Initial commit
This commit is contained in:
Zhongwei Li
426
commands/ace-bootstrap.md
Normal file
426
commands/ace-bootstrap.md
Normal file
@@ -0,0 +1,426 @@
|
||||
---
|
||||
description: Bootstrap ACE playbook from docs, git history, and/or current code
|
||||
argument-hint: [--mode hybrid|both|local-files|git-history|docs-only] [--thoroughness light|medium|deep] [--commits N] [--days N]
|
||||
---
|
||||
|
||||
# ACE Bootstrap
|
||||
|
||||
Bootstrap ACE playbook by analyzing your current codebase files and/or git commit history.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When user runs `/ace-bootstrap`, execute the bootstrap script:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Get plugin root directory
|
||||
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
|
||||
|
||||
# Execute bootstrap script with all arguments
|
||||
exec "${PLUGIN_ROOT}/scripts/ace-bootstrap.sh" "$@"
|
||||
```
|
||||
|
||||
**Data Flow**:
|
||||
```
|
||||
/ace-bootstrap command
|
||||
↓
|
||||
ce-ace CLI
|
||||
↓
|
||||
ACE Server: Reflector analyzes code
|
||||
↓
|
||||
ce-ace CLI: returns results
|
||||
↓
|
||||
Command: calls ce-ace status for final counts
|
||||
↓
|
||||
Command: generates dynamic report for user
|
||||
```
|
||||
|
||||
**To invoke**: Simply use the bootstrap-orchestrator skill with the user's parameters.
|
||||
|
||||
## Usage
|
||||
|
||||
Use `ce-ace bootstrap` to initialize your playbook from the codebase.
|
||||
|
||||
**Basic usage**:
|
||||
```bash
|
||||
# CLI reads org/project from environment variables or config automatically
|
||||
ce-ace bootstrap --json
|
||||
```
|
||||
|
||||
**With options**:
|
||||
```bash
|
||||
# Hybrid mode (recommended) - docs → git → files
|
||||
ce-ace bootstrap --json --mode hybrid --thoroughness deep
|
||||
|
||||
# Git history only
|
||||
ce-ace bootstrap --json --mode git-history --commit-limit 1000 --days-back 180
|
||||
|
||||
# Local files only
|
||||
ce-ace bootstrap --json --mode local-files --max-files 5000
|
||||
|
||||
# Docs only
|
||||
ce-ace bootstrap --json --mode docs-only
|
||||
```
|
||||
|
||||
**Parameters**:
|
||||
- `--mode <mode>` - Analysis mode (default: "hybrid")
|
||||
- `hybrid`: RECOMMENDED - Intelligently scan docs → git history → local files
|
||||
- `both`: Analyze current files + git history (no docs)
|
||||
- `local-files`: Current codebase files only
|
||||
- `git-history`: Git commit history only
|
||||
- `docs-only`: Documentation files only (*.md, *.txt)
|
||||
|
||||
- `--thoroughness <level>` - Analysis depth (default: "medium")
|
||||
- `light`: max_files=1000, commit_limit=100, days_back=30
|
||||
- `medium`: max_files=5000, commit_limit=500, days_back=90
|
||||
- `deep`: max_files=unlimited, commit_limit=1000, days_back=180
|
||||
|
||||
- `--repo-path <path>` - Path to repository (default: current directory)
|
||||
- `--max-files <number>` - Maximum files to analyze (overrides thoroughness)
|
||||
- `--commit-limit <number>` - Max commits to analyze (overrides thoroughness)
|
||||
- `--days-back <number>` - Days of history to analyze (overrides thoroughness)
|
||||
- `--merge` - Merge with existing playbook (default: true)
|
||||
|
||||
**Examples**:
|
||||
```bash
|
||||
# RECOMMENDED: Most comprehensive analysis
|
||||
/ace:bootstrap --mode hybrid --thoroughness deep
|
||||
|
||||
# Good balance of speed and coverage
|
||||
/ace:bootstrap --mode hybrid --thoroughness medium
|
||||
|
||||
# Quick local files scan
|
||||
/ace:bootstrap --mode local-files --thoroughness light
|
||||
|
||||
# Deep git history analysis
|
||||
/ace:bootstrap --mode git-history --thoroughness deep
|
||||
```
|
||||
|
||||
## What Gets Analyzed
|
||||
|
||||
### Mode: hybrid (RECOMMENDED - Intelligent Multi-Source Analysis)
|
||||
|
||||
The **hybrid mode** uses intelligent fallback logic to extract maximum knowledge from available sources:
|
||||
|
||||
**Priority Order:**
|
||||
1. **Check existing documentation** - Scans for CLAUDE.md, README.md, ARCHITECTURE.md, docs/*.md
|
||||
2. **Analyze git history** - Extracts patterns from commits (if git repository exists)
|
||||
3. **Parse local files** - Analyzes current source code files
|
||||
|
||||
**Intelligent Fallback Logic:**
|
||||
```
|
||||
IF (docs found with substantial content):
|
||||
→ Extract architectural patterns, best practices, troubleshooting guides from docs
|
||||
→ STILL analyze git history for bug fix patterns and refactoring insights
|
||||
→ STILL scan local files for current API usage and dependencies
|
||||
|
||||
ELSE IF (git history available):
|
||||
→ Analyze commit history for strategies, troubleshooting, API patterns
|
||||
→ Scan local files for current state and dependencies
|
||||
|
||||
ELSE (no docs, no git):
|
||||
→ Deep analysis of local files only
|
||||
→ Extract patterns from code structure, imports, error handling
|
||||
```
|
||||
|
||||
**Why Hybrid is Superior:**
|
||||
- ✅ **Documentation-first**: Captures explicit team knowledge and architectural decisions
|
||||
- ✅ **History-aware**: Learns from past mistakes and successful refactorings
|
||||
- ✅ **Current-state**: Reflects what's actually being used right now
|
||||
- ✅ **Comprehensive**: Combines all three sources for maximum coverage
|
||||
- ✅ **Adaptive**: Automatically falls back based on what's available
|
||||
|
||||
**What Gets Extracted:**
|
||||
|
||||
From **Documentation** (`*.md`, `*.txt`):
|
||||
- Architectural patterns and principles (→ strategies section)
|
||||
- Coding standards and best practices (→ strategies section)
|
||||
- Known issues and troubleshooting guides (→ troubleshooting section)
|
||||
- API integration examples (→ apis section)
|
||||
- Code snippets from docs (→ snippets section)
|
||||
|
||||
From **Git History** (commits):
|
||||
- Refactoring patterns (commits with "refactor", "improve", "optimize")
|
||||
- Bug fix patterns (commits with "fix", "bug", "error", "crash")
|
||||
- API integration lessons (commits touching API/service/client files)
|
||||
- File co-occurrence patterns (frequently changed together)
|
||||
- Error resolution patterns (specific error keywords in messages)
|
||||
|
||||
From **Local Files** (source code):
|
||||
- Current library usage and dependencies (import statements)
|
||||
- Error handling patterns (try-catch, exception handling)
|
||||
- Code structure and organization
|
||||
- Active API integrations
|
||||
|
||||
**Example Output from Hybrid Mode:**
|
||||
```json
|
||||
{
|
||||
"mode": "HYBRID",
|
||||
"sources_analyzed": {
|
||||
"docs": {
|
||||
"files_found": 12,
|
||||
"patterns_extracted": 45
|
||||
},
|
||||
"git_history": {
|
||||
"commits_analyzed": 500,
|
||||
"patterns_extracted": 187
|
||||
},
|
||||
"local_files": {
|
||||
"files_scanned": 3421,
|
||||
"patterns_extracted": 245
|
||||
}
|
||||
},
|
||||
"total_patterns": 477,
|
||||
"by_section": {
|
||||
"strategies": 120,
|
||||
"snippets": 89,
|
||||
"troubleshooting": 178,
|
||||
"apis": 90
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Mode: local-files (Current Codebase)
|
||||
|
||||
Analyzes **current project files** (includes uncommitted/unstaged changes):
|
||||
|
||||
**1. Imports & Dependencies → APIs Section**
|
||||
- TypeScript/JavaScript: `import X from 'Y'`, `require('Y')`
|
||||
- Python: `import X`, `from X import Y`
|
||||
- Discovers what libraries you're ACTUALLY using NOW
|
||||
- Example: "Project uses: express, jsonwebtoken, bcrypt"
|
||||
|
||||
**2. Error Handling Patterns → Troubleshooting Section**
|
||||
- Try-catch patterns with console.error logging
|
||||
- Try-catch with error re-throwing
|
||||
- Exception handling with named exceptions (Python)
|
||||
- Example: "Pattern: try-catch with console.error logging"
|
||||
|
||||
**3. Architecture Discovery → Strategies Section** (Future)
|
||||
- Class/function structure
|
||||
- Module organization
|
||||
- Design patterns in use
|
||||
|
||||
**Why This Matters:**
|
||||
- ✅ **Uncommitted code** - Captures work-in-progress and prototypes
|
||||
- ✅ **Current reality** - What's actually being used, not historical experiments
|
||||
- ✅ **Fast** - Client-side analysis, no git operations needed
|
||||
|
||||
### Mode: git-history (Historical Patterns)
|
||||
|
||||
Analyzes **git commit history** (server-side):
|
||||
|
||||
**1. Strategies** (from refactorings)
|
||||
- Commits with "refactor", "improve", "optimize", "clean"
|
||||
- Extracts successful architectural decisions
|
||||
- Example: "Pattern from refactoring: Split monolithic service into microservices"
|
||||
|
||||
**2. Troubleshooting** (from bug fixes)
|
||||
- Commits with "fix", "bug", "error", "crash", "issue"
|
||||
- Captures common pitfalls and solutions
|
||||
- Example: "Common issue: Null pointer errors in user service"
|
||||
|
||||
**3. APIs** (from feature additions)
|
||||
- Commits touching API/service/client/interface files
|
||||
- Documents API usage patterns
|
||||
- Example: "API pattern: Implement JWT auth for user endpoints"
|
||||
|
||||
**4. File Co-occurrence**
|
||||
- Files that frequently change together
|
||||
- Highlights coupling and dependencies
|
||||
- Example: "Files that often change together: auth.ts + user.service.ts"
|
||||
|
||||
**5. Error Patterns**
|
||||
- Specific error keywords in commit messages
|
||||
- Warns about common failure modes
|
||||
- Example: "Watch out for timeout errors when calling external APIs"
|
||||
|
||||
**Why This Matters:**
|
||||
- ✅ **Problem-solving patterns** - How bugs were fixed
|
||||
- ✅ **Evolution** - What changed and why
|
||||
- ✅ **Team knowledge** - Lessons from multiple contributors
|
||||
|
||||
### Mode: both (Current + History)
|
||||
|
||||
Combines **current codebase** + **git history** (without docs scanning):
|
||||
- Current state (what's used NOW)
|
||||
- Historical lessons (how problems were solved)
|
||||
- Good when documentation is missing or sparse
|
||||
|
||||
**Note:** Consider using **hybrid mode** instead - it includes docs scanning AND both sources with intelligent fallback!
|
||||
|
||||
## Merge vs Replace
|
||||
|
||||
### Merge Mode (Default)
|
||||
```json
|
||||
{ "merge_with_existing": true }
|
||||
```
|
||||
- Combines new bullets with existing playbook
|
||||
- Uses curator's grow-and-refine algorithm
|
||||
- Deduplicates similar bullets (0.85 similarity threshold)
|
||||
- Preserves helpful/harmful counters on existing bullets
|
||||
|
||||
**Use when:** You want to enrich existing playbook with historical patterns
|
||||
|
||||
### Replace Mode
|
||||
```json
|
||||
{ "merge_with_existing": false }
|
||||
```
|
||||
- Clears existing playbook
|
||||
- Replaces with fresh analysis from git history
|
||||
- Resets all helpful/harmful counters
|
||||
|
||||
**Use when:** Starting fresh or clearing bad patterns
|
||||
|
||||
## Example Output
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": "MERGE",
|
||||
"bullets_added": 42,
|
||||
"bullets_existing": 18,
|
||||
"bullets_final": 55,
|
||||
"by_section": {
|
||||
"strategies": 12,
|
||||
"snippets": 8,
|
||||
"troubleshooting": 25,
|
||||
"apis": 10
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## When to Use
|
||||
|
||||
### ✅ Recommended Scenarios
|
||||
|
||||
**Use `hybrid` mode with `thoroughness: deep`:**
|
||||
- ✅ **New project onboarding**: Extract all available knowledge (docs + history + code)
|
||||
- ✅ **Team knowledge capture**: Comprehensive analysis of architectural decisions
|
||||
- ✅ **Post-migration**: Understand new codebase from all angles
|
||||
- ✅ **Large codebases**: Maximum pattern extraction (5000+ files, 500+ commits, 90+ days)
|
||||
|
||||
**Use `hybrid` mode with `thoroughness: medium`:**
|
||||
- ✅ **Periodic refresh**: Re-analyze every few months for new patterns
|
||||
- ✅ **Medium projects**: Balanced analysis (up to 5000 files, 500 commits, 90 days)
|
||||
- ✅ **Quick comprehensive scan**: Good coverage without long processing time
|
||||
|
||||
**Use `local-files` mode:**
|
||||
- ✅ **No git history**: Project just started or not in git repo
|
||||
- ✅ **Current state only**: Only care about what's being used right now
|
||||
- ✅ **Fast iteration**: Quick dependency and pattern scan
|
||||
|
||||
**Use `git-history` mode:**
|
||||
- ✅ **Legacy understanding**: Learn from how bugs were fixed and refactorings done
|
||||
- ✅ **Team patterns**: Extract lessons from multiple contributors over time
|
||||
- ✅ **Architectural evolution**: Understand how system design changed
|
||||
|
||||
**Use `docs-only` mode:**
|
||||
- ✅ **Documentation exists**: Well-documented project with CLAUDE.md, ARCHITECTURE.md, etc.
|
||||
- ✅ **Quick bootstrap**: Fast startup without code analysis
|
||||
- ✅ **Explicit knowledge**: Team has written good documentation already
|
||||
|
||||
### ❌ When NOT to Use
|
||||
|
||||
- **Empty repository**: Need at least ~20 commits for meaningful git-history analysis
|
||||
- **No sources available**: No docs, no git, and trivial codebase (< 10 files)
|
||||
- **Pre-initialized playbook**: If playbook already has 100+ quality patterns, online learning is better
|
||||
- **Frequent re-bootstraps**: Don't run daily - use online learning (ace_learn) instead
|
||||
|
||||
## Integration with ACE Agent Skills (v3.2.36)
|
||||
|
||||
**NEW in v3.2.36**: ACE skills now trigger on 35+ action keywords with intent-based fallback!
|
||||
|
||||
After bootstrapping your initial playbook, ACE's Agent Skills will automatically use these patterns during your work. The skills trigger on:
|
||||
|
||||
**8 Trigger Categories (35+ keywords):**
|
||||
- **Implementation**: implement, build, create, add, develop, write
|
||||
- **Modification**: update, modify, change, edit, enhance, extend, revise
|
||||
- **Debugging**: debug, fix, troubleshoot, resolve, diagnose
|
||||
- **Refactoring**: refactor, optimize, improve, restructure
|
||||
- **Integration**: integrate, connect, setup, configure, install
|
||||
- **Architecture**: architect, design, plan
|
||||
- **Testing**: test, verify, validate
|
||||
- **Operations**: deploy, migrate, upgrade
|
||||
|
||||
**Intent-based fallback**: Even without exact keywords, skills trigger when requests clearly intend to write/modify code, solve technical problems, make architectural decisions, or perform substantial technical work.
|
||||
|
||||
**How it works:**
|
||||
1. **Playbook Retrieval Skill**: Before tasks (auto-invokes when trigger keywords detected)
|
||||
2. **Playbook Learning Skill**: After tasks (auto-invokes after substantial work)
|
||||
3. **Bootstrap command**: Provides initial patterns for skills to retrieve
|
||||
|
||||
**Result**: Bootstrap gives you a strong foundation, then skills automatically retrieve and expand patterns as you work!
|
||||
|
||||
## After Bootstrap
|
||||
|
||||
Once bootstrapped, ACE continues learning through **online learning**:
|
||||
- Execute tasks → ACE learns from outcomes (ace_learn)
|
||||
- Successful tasks → adds helpful bullets
|
||||
- Failed tasks → adds troubleshooting bullets
|
||||
- Counters update → helpful/harmful tracking
|
||||
|
||||
**Bootstrap (ace_bootstrap)** + **Online learning (ace_learn)** = Complete ACE system
|
||||
|
||||
## Next Steps
|
||||
|
||||
**After bootstrap completes:**
|
||||
|
||||
1. **Verify patterns loaded:**
|
||||
- Run `/ace:status` to see playbook statistics
|
||||
- Should show bullets distributed across 4 sections
|
||||
|
||||
2. **Review learned patterns:**
|
||||
- Run `/ace:patterns` to view what was discovered
|
||||
- Check strategies, snippets, troubleshooting, and API patterns
|
||||
|
||||
3. **Start coding:**
|
||||
- ACE will now retrieve these patterns before tasks
|
||||
- Automatic learning will add new patterns as you work
|
||||
|
||||
4. **Optional - Export backup:**
|
||||
- Run `/ace:export-patterns` to save initial playbook state
|
||||
- Useful for team sharing or restoration
|
||||
|
||||
## Complementary Commands
|
||||
|
||||
- `/ace:patterns` - View the initialized playbook
|
||||
- `/ace:status` - Check statistics after initialization
|
||||
- `/ace:export-patterns` - Backup before re-initialization
|
||||
|
||||
## Git History Requirements
|
||||
|
||||
**Minimum:**
|
||||
- Git repository with commit history
|
||||
- At least 10-20 commits
|
||||
|
||||
**Optimal:**
|
||||
- 50+ commits over multiple weeks/months
|
||||
- Descriptive commit messages
|
||||
- Mix of features, refactorings, and bug fixes
|
||||
- Multiple contributors (diverse patterns)
|
||||
|
||||
## Privacy & Security
|
||||
|
||||
**What gets analyzed:**
|
||||
- Commit messages
|
||||
- File paths
|
||||
- Commit statistics (additions/deletions)
|
||||
|
||||
**NOT analyzed:**
|
||||
- Actual file contents (unless you implement custom analysis)
|
||||
- Credentials or secrets
|
||||
- Private comments
|
||||
|
||||
**Storage:**
|
||||
- Playbook stored on ACE server (configured in plugin.json)
|
||||
- Project-specific (isolated by project ID)
|
||||
- Multi-tenant safe (your org's patterns are private)
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace-patterns` - View playbook
|
||||
- `/ace-export-patterns` - Export for backup
|
||||
- `/ace-import-patterns` - Import from backup
|
||||
- `/ace-clear` - Clear playbook
|
||||
359
commands/ace-claude-init.md
Normal file
359
commands/ace-claude-init.md
Normal file
@@ -0,0 +1,359 @@
|
||||
---
|
||||
description: Add ACE plugin instructions to project CLAUDE.md (one-time setup)
|
||||
---
|
||||
|
||||
# ACE Claude Init
|
||||
|
||||
Initialize ACE plugin instructions in your project's CLAUDE.md file.
|
||||
|
||||
## What This Does
|
||||
|
||||
Copies the full ACE plugin instructions inline into your project's CLAUDE.md. This ensures Claude always has access to ACE architecture instructions for the automatic learning cycle.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace-claude-init`, follow these steps:
|
||||
|
||||
### Step 0: Try Script-Based Initialization (Fast Path)
|
||||
|
||||
**NEW in v3.2.36+:** Try the shell script first for token-free, instant execution.
|
||||
|
||||
1. **Execute the script:**
|
||||
```bash
|
||||
${CLAUDE_PLUGIN_ROOT}/scripts/ace-claude-init.sh
|
||||
```
|
||||
|
||||
2. **Check exit code:**
|
||||
- **Exit 0:** Success! Script handled initialization/update
|
||||
- Show success message from script output
|
||||
- Skip to "Confirm Success" section
|
||||
- **Stop here - do NOT proceed to Step 1**
|
||||
|
||||
- **Exit 2:** Fallback needed (file has no HTML markers or complex structure)
|
||||
- Continue to Step 1 (LLM-based approach)
|
||||
- This is expected for first-time runs on projects without markers
|
||||
|
||||
- **Exit 1:** Error occurred
|
||||
- Continue to Step 1 (LLM-based approach as fallback)
|
||||
|
||||
3. **When script succeeds (exit 0):**
|
||||
- Token usage: **0 tokens** (pure shell script)
|
||||
- Execution time: **< 1 second**
|
||||
- No further action needed
|
||||
|
||||
4. **When script exits with code 2:**
|
||||
- This means: File exists but has no HTML markers
|
||||
- Fall through to Step 1 for LLM-based handling
|
||||
- Token usage: Normal LLM path (~17,000 tokens)
|
||||
|
||||
**Script Capabilities:**
|
||||
- ✅ Creates new CLAUDE.md files (instant)
|
||||
- ✅ Appends to existing CLAUDE.md without ACE content
|
||||
- ✅ Updates marker-based ACE sections (v3.2.36+)
|
||||
- ❌ Cannot handle: Files without HTML markers (uses LLM fallback)
|
||||
|
||||
### Step 0a: Interactive Update Menu (NEW in v4.1.14)
|
||||
|
||||
**When:** Script exits with code 2 AND output contains JSON with `"status":"update_available"`.
|
||||
|
||||
**What to do:**
|
||||
|
||||
1. **Parse version info from script output:**
|
||||
- Look for JSON output: `{"status":"update_available","current_version":"X.X.X","plugin_version":"Y.Y.Y"}`
|
||||
- Extract: `current_version` and `plugin_version`
|
||||
|
||||
2. **Show interactive menu using AskUserQuestion:**
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: `Your project has ACE v${current_version}, but plugin is v${plugin_version}. Would you like to update?`,
|
||||
header: "ACE Update",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Yes, update now",
|
||||
description: `Update to v${plugin_version} (recommended)`
|
||||
},
|
||||
{
|
||||
label: "Show what changed",
|
||||
description: "View changelog before deciding"
|
||||
},
|
||||
{
|
||||
label: "No, keep current version",
|
||||
description: `Stay on v${current_version}`
|
||||
}
|
||||
]
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
3. **Handle user selection:**
|
||||
|
||||
**User selected "Yes, update now":**
|
||||
- Run: `${CLAUDE_PLUGIN_ROOT}/scripts/ace-claude-init.sh --update`
|
||||
- Display update result
|
||||
- Exit successfully
|
||||
|
||||
**User selected "Show what changed":**
|
||||
- Run: `${CLAUDE_PLUGIN_ROOT}/scripts/ace-claude-init.sh --show-changes`
|
||||
- Display changelog output
|
||||
- **Re-show the interactive menu** (same 3 options)
|
||||
- User can now choose "Yes" or "No" with full context
|
||||
|
||||
**User selected "No, keep current version":**
|
||||
- Tell user: "Keeping ACE v${current_version}. Run `/ace-claude-init` again if you change your mind."
|
||||
- Exit successfully
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Token-free changelog preview (~50 tokens vs ~17k)
|
||||
- ✅ User-friendly interactive workflow
|
||||
- ✅ Informed decision-making
|
||||
- ✅ No manual flag typing
|
||||
|
||||
**Example Flow:**
|
||||
```
|
||||
User runs: /ace:ace-claude-init
|
||||
↓
|
||||
Script detects: v4.1.12 → v4.1.14
|
||||
Script outputs: {"status":"update_available","current_version":"4.1.12","plugin_version":"4.1.14"}
|
||||
Script exits: code 2
|
||||
↓
|
||||
Claude shows menu:
|
||||
[1] Yes, update now
|
||||
[2] Show what changed ← User selects this
|
||||
[3] No, keep current
|
||||
↓
|
||||
Claude runs: --show-changes
|
||||
Claude displays:
|
||||
## [4.1.14] - 2025-01-06
|
||||
### Fixed
|
||||
- Missing interactive menu features...
|
||||
↓
|
||||
Claude re-shows menu:
|
||||
[1] Yes, update now ← User selects this
|
||||
[2] Show what changed
|
||||
[3] No, keep current
|
||||
↓
|
||||
Claude runs: --update
|
||||
Claude shows: ✅ Updated to v4.1.14
|
||||
```
|
||||
|
||||
### Step 1: Read Plugin CLAUDE.md (LLM Fallback Path)
|
||||
|
||||
Read the full ACE plugin CLAUDE.md file:
|
||||
```
|
||||
~/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace/CLAUDE.md
|
||||
```
|
||||
|
||||
This file contains ~344 lines of ACE architecture documentation (includes v3.2.8 MANDATORY section + trajectory format fix).
|
||||
|
||||
### Step 2: Check for Project CLAUDE.md
|
||||
|
||||
Check if CLAUDE.md exists in the project root:
|
||||
- If it exists, read it first to check for existing ACE content
|
||||
- If it doesn't exist, you'll create it
|
||||
|
||||
### Step 3: Check if ACE Already Added & Version Detection
|
||||
|
||||
Look for the ACE content marker in the project's CLAUDE.md:
|
||||
```markdown
|
||||
# ACE Orchestration Plugin - Automatic Learning Cycle
|
||||
```
|
||||
|
||||
**If this header already exists:**
|
||||
|
||||
1. **Detect existing version** by searching for version pattern in project CLAUDE.md:
|
||||
- **Optimized:** Check line 93 specifically: `## 🔄 Complete Automatic Learning Cycle (v3.2.36)`
|
||||
- Extract version using pattern: `v([0-9]+\.[0-9]+\.[0-9]+)`
|
||||
- Fallback: Search entire file if not found on line 93
|
||||
|
||||
2. **Read plugin version** from the plugin CLAUDE.md file:
|
||||
- **Optimized:** Check line 93 of plugin template (same location)
|
||||
- Fallback: Search entire plugin file if structure differs
|
||||
|
||||
3. **Compare versions:**
|
||||
|
||||
**If versions match (up-to-date):**
|
||||
- Tell the user ACE is already initialized with current version
|
||||
- Show them where it's located in CLAUDE.md
|
||||
- Exit successfully (no changes needed)
|
||||
|
||||
**If project version is older than plugin version:**
|
||||
- Tell the user ACE content is outdated
|
||||
- Show current version vs. plugin version
|
||||
- Ask if they want to update: "Your project has ACE v{old}, but plugin is v{new}. Would you like to update? (y/n)"
|
||||
- If user says yes → proceed to Step 3a (Update existing ACE content)
|
||||
- If user says no → exit successfully
|
||||
|
||||
### Step 3a: Update Existing ACE Content (Only if outdated)
|
||||
|
||||
If user confirmed they want to update outdated ACE content:
|
||||
|
||||
1. **Find ACE section boundaries** in project CLAUDE.md:
|
||||
- **Check for HTML markers first:** `<!-- ACE_SECTION_START -->` and `<!-- ACE_SECTION_END -->`
|
||||
- If markers present: Use them for exact boundaries (fast, accurate)
|
||||
- If markers absent: Use header-based detection:
|
||||
- Start: Line with `# ACE Orchestration Plugin - Automatic Learning Cycle`
|
||||
- End: Next `#` header at the same level (pattern: `^# [^#]`) OR end of file
|
||||
|
||||
2. **Extract non-ACE content:**
|
||||
- Content BEFORE the ACE section (if any)
|
||||
- Content AFTER the ACE section (if any)
|
||||
|
||||
3. **Replace ACE section:**
|
||||
- Remove old ACE section completely
|
||||
- Insert new plugin CLAUDE.md content at same location
|
||||
- Preserve all other content (before and after)
|
||||
|
||||
4. **Write updated file:**
|
||||
- Reconstruct: `[content before] + [new ACE content] + [content after]`
|
||||
- Save to project CLAUDE.md
|
||||
|
||||
5. **Confirm update:**
|
||||
- Tell user ACE updated from vX.X.X → vY.Y.Y
|
||||
- Show what's new in the update
|
||||
- Proceed to Step 5 (Confirm Success)
|
||||
|
||||
### Step 4: Copy ACE Instructions Inline
|
||||
|
||||
If ACE content is NOT present:
|
||||
|
||||
**If CLAUDE.md exists:**
|
||||
- Append to the END of the file (preserve all existing content)
|
||||
- Add two blank lines first for spacing
|
||||
- Copy the FULL content of the plugin CLAUDE.md file inline
|
||||
- DO NOT use `@` reference syntax
|
||||
- The content should start with: `# ACE Orchestration Plugin - Automatic Learning Cycle`
|
||||
|
||||
**If CLAUDE.md doesn't exist:**
|
||||
- Create it with the full ACE plugin CLAUDE.md content
|
||||
- Copy all ~344 lines of content from the plugin file (includes MANDATORY section + trajectory format fix)
|
||||
|
||||
### Step 5: Confirm Success
|
||||
|
||||
After adding:
|
||||
- Read the updated CLAUDE.md to verify
|
||||
- Show the user a confirmation message
|
||||
- Confirm ACE instructions are now available inline
|
||||
- Explain what this enables (automatic learning cycle)
|
||||
|
||||
## What Gets Added
|
||||
|
||||
The full ACE plugin CLAUDE.md content (~344 lines) is copied inline, which contains:
|
||||
|
||||
- 🚨 **MANDATORY: ACE Skill Usage Rules** (v3.2.8+) - Explicit, non-negotiable skill invocation instructions
|
||||
- 🔄 **Complete automatic learning cycle** explanation
|
||||
- 🤖 **How skills work** (retrieval before tasks, learning after tasks)
|
||||
- 🎯 **When to trigger** ACE features (implement, debug, refactor, etc.)
|
||||
- 📊 **Architecture overview** (Generator → Reflector → Curator → Playbook)
|
||||
- 🔧 **Slash commands reference** for manual control
|
||||
- 📁 **Playbook structure** (4 sections: strategies, snippets, troubleshooting, APIs)
|
||||
|
||||
## Why This is Needed
|
||||
|
||||
**Problem:** Skills are model-invoked and load instructions ONLY when triggered. This means:
|
||||
- ❌ Claude doesn't know about the ACE cycle until a skill activates
|
||||
- ❌ No standing context about when to use ACE features
|
||||
- ❌ Missing architecture overview
|
||||
|
||||
**Solution:** Copying ACE instructions inline into project CLAUDE.md provides:
|
||||
- ✅ Always-on context about the ACE system
|
||||
- ✅ Clear trigger words for skills (implement, debug, refactor)
|
||||
- ✅ Complete understanding of the automatic learning cycle
|
||||
- ✅ Complementary to skills (general context + specific tools)
|
||||
- ✅ Full content always available (no reference dependency)
|
||||
|
||||
## When to Use
|
||||
|
||||
### ✅ Required For:
|
||||
- **Full ACE cycle** - Retrieval + Learning working together
|
||||
- **Optimal skill triggering** - Claude knows when to invoke skills
|
||||
- **Architecture awareness** - Claude understands the system
|
||||
|
||||
### ⚠️ One-Time Setup (With Version Updates):
|
||||
- Run once per project for initial setup
|
||||
- Safe to run multiple times (checks for existing content)
|
||||
- **Auto-detects version** - offers to update if outdated
|
||||
- Run again after plugin updates to get new features
|
||||
- No manual editing needed
|
||||
|
||||
## After Running
|
||||
|
||||
Once initialized, every Claude session will have:
|
||||
1. ✅ Your project-specific instructions (existing CLAUDE.md content)
|
||||
2. ✅ ACE plugin instructions (copied inline, ~344 lines with MANDATORY section + trajectory format fix)
|
||||
3. ✅ Skills available for automatic invocation
|
||||
4. ✅ Explicit skill invocation rules (YOU MUST use skills for qualifying tasks)
|
||||
|
||||
**Test it:**
|
||||
- Try a coding task: "Implement JWT authentication"
|
||||
- Watch for ACE Playbook Retrieval skill to auto-invoke
|
||||
- Complete the task and watch ACE Learning skill capture feedback
|
||||
|
||||
## Complementary Commands
|
||||
|
||||
- `/ace:ace-configure` - Set up ACE server connection (REQUIRED FIRST!)
|
||||
- `/ace:ace-status` - Check playbook statistics
|
||||
- `/ace:ace-bootstrap` - Bootstrap playbook from git history (optional)
|
||||
- `/ace:ace-patterns` - View learned patterns
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```bash
|
||||
# 1. Install ACE plugin
|
||||
# 2. Restart Claude Code
|
||||
|
||||
# 3. Configure ACE server connection (REQUIRED!)
|
||||
/ace:ace-configure
|
||||
|
||||
# 4. Initialize ACE in project (one-time)
|
||||
/ace:ace-claude-init
|
||||
|
||||
# 5. Optionally bootstrap from git history
|
||||
/ace:ace-bootstrap --commits 100 --days 30
|
||||
|
||||
# 6. Verify setup
|
||||
/ace:ace-status
|
||||
|
||||
# 7. Start coding - ACE learns automatically!
|
||||
# "Implement user authentication"
|
||||
# → ACE Playbook Retrieval skill auto-invokes
|
||||
# → Claude implements with learned patterns
|
||||
# → ACE Learning skill captures new insights
|
||||
```
|
||||
|
||||
## Safety Features
|
||||
|
||||
### Non-Destructive:
|
||||
- ✅ Never overwrites existing content
|
||||
- ✅ Always appends to end of file
|
||||
- ✅ Checks for duplicates before adding
|
||||
- ✅ Preserves all user customizations
|
||||
|
||||
### Idempotent & Version-Aware:
|
||||
- ✅ Safe to run multiple times
|
||||
- ✅ Detects existing ACE content
|
||||
- ✅ Compares versions automatically
|
||||
- ✅ Offers to update when outdated
|
||||
- ✅ No duplicate entries
|
||||
|
||||
### Transparent:
|
||||
- ✅ Shows what was added
|
||||
- ✅ Explains why it's needed
|
||||
- ✅ User can inspect/remove manually if desired
|
||||
|
||||
## Manual Removal (if needed)
|
||||
|
||||
If the user wants to remove ACE instructions:
|
||||
|
||||
1. Open CLAUDE.md in the project root
|
||||
2. Find the section starting with: `# ACE Orchestration Plugin - Automatic Learning Cycle`
|
||||
3. Delete all ACE content (~344 lines)
|
||||
|
||||
ACE skills will still work, but won't have the always-on architectural context.
|
||||
|
||||
## See Also
|
||||
|
||||
- Project CLAUDE.md documentation: https://docs.claude.com/en/docs/claude-code/memory
|
||||
- ACE plugin README: `~/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace/README.md`
|
||||
- Skills guide: https://docs.claude.com/en/docs/claude-code/skills
|
||||
87
commands/ace-clear.md
Normal file
87
commands/ace-clear.md
Normal file
@@ -0,0 +1,87 @@
|
||||
---
|
||||
description: Clear ACE playbook (reset all learned bullets)
|
||||
argument-hint: [--confirm]
|
||||
---
|
||||
|
||||
# ACE Clear
|
||||
|
||||
Reset the ACE playbook by clearing all learned bullets.
|
||||
|
||||
⚠️ **WARNING**: This will delete ALL learned bullets across all 4 sections!
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
if [ -z "$ORG_ID" ] || [ -z "$PROJECT_ID" ]; then
|
||||
echo "❌ Run /ace-configure first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "⚠️ WARNING: This will delete ALL learned patterns!"
|
||||
read -p "Are you sure? Type 'yes' to confirm: " CONFIRMATION
|
||||
|
||||
if [ "$CONFIRMATION" != "yes" ]; then
|
||||
echo "❌ Aborted"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
ce-ace --org "$ORG_ID" --project "$PROJECT_ID" clear --confirm
|
||||
```
|
||||
|
||||
## What Gets Deleted
|
||||
|
||||
**All playbook sections**:
|
||||
- `strategies_and_hard_rules` - All strategies cleared
|
||||
- `useful_code_snippets` - All code snippets cleared
|
||||
- `troubleshooting_and_pitfalls` - All troubleshooting cleared
|
||||
- `apis_to_use` - All API patterns cleared
|
||||
|
||||
**All metadata**:
|
||||
- Helpful/harmful counters reset to 0
|
||||
- Confidence scores lost
|
||||
- Evidence trails removed
|
||||
- Timestamps cleared
|
||||
|
||||
## Storage Impact
|
||||
|
||||
Clears from:
|
||||
- **Remote server**: ACE Storage Server (ChromaDB)
|
||||
- **Project-specific**: Only YOUR project's playbook
|
||||
- **Multi-tenant safe**: Other projects/orgs unaffected
|
||||
|
||||
## When to Use
|
||||
|
||||
- **Fresh start**: Reset learning for new project phase
|
||||
- **Bad patterns**: Clear after accumulating misleading bullets
|
||||
- **Testing**: Clean state for testing ACE learning
|
||||
|
||||
## After Clearing
|
||||
|
||||
ACE will start learning from scratch:
|
||||
- Execute tasks → ACE learns from outcomes
|
||||
- Successful tasks → adds helpful bullets
|
||||
- Failed tasks → adds troubleshooting bullets
|
||||
|
||||
## Backup First!
|
||||
|
||||
**Before clearing, export your playbook**:
|
||||
```
|
||||
/ace:ace-export-patterns
|
||||
```
|
||||
|
||||
This saves a JSON backup you can re-import later.
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:ace-export-patterns` - Backup before clearing
|
||||
- `/ace:ace-import-patterns` - Restore from backup
|
||||
- `/ace:ace-status` - Verify playbook is cleared
|
||||
593
commands/ace-configure.md
Normal file
593
commands/ace-configure.md
Normal file
@@ -0,0 +1,593 @@
|
||||
---
|
||||
description: Configure ACE server connection settings interactively
|
||||
argument-hint: [--global] [--project]
|
||||
---
|
||||
|
||||
# Configure ACE Connection
|
||||
|
||||
Interactive configuration wizard using ce-ace CLI v1.0.2+ features with Claude Code native UI.
|
||||
|
||||
## What This Does
|
||||
|
||||
**Two-step configuration:**
|
||||
1. **Global Config**: Uses `ce-ace config validate` + `ce-ace config` with flags
|
||||
2. **Project Config**: Creates `.claude/settings.json` with orgId and projectId
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace:configure`, follow these steps:
|
||||
|
||||
### Step 1: Check ce-ace CLI Version and Dependencies
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Check for jq (required for JSON parsing)
|
||||
if ! command -v jq >/dev/null 2>&1; then
|
||||
echo "❌ jq not found (required for JSON parsing)"
|
||||
echo ""
|
||||
echo "Installation instructions:"
|
||||
echo " macOS: brew install jq"
|
||||
echo " Linux: apt-get install jq or yum install jq"
|
||||
echo " Windows: Download from https://stedolan.github.io/jq/download/"
|
||||
echo ""
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for ce-ace CLI
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace CLI not found"
|
||||
echo ""
|
||||
echo "Installation required:"
|
||||
echo " npm install -g @ace-sdk/cli"
|
||||
echo ""
|
||||
exit 1
|
||||
fi
|
||||
|
||||
VERSION=$(ce-ace --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
|
||||
echo "✅ ce-ace CLI found (version: $VERSION)"
|
||||
|
||||
# Check version >= 1.0.2
|
||||
REQUIRED_VERSION="1.0.2"
|
||||
if [ "$(printf '%s\n' "$REQUIRED_VERSION" "$VERSION" | sort -V | head -n1)" != "$REQUIRED_VERSION" ]; then
|
||||
echo "⚠️ ce-ace v$VERSION found, but v1.0.2+ required for non-interactive config"
|
||||
echo ""
|
||||
echo "Please upgrade:"
|
||||
echo " npm install -g @ace-sdk/cli@latest"
|
||||
echo ""
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo ""
|
||||
```
|
||||
|
||||
### Step 2: Detect Scope
|
||||
|
||||
```bash
|
||||
# Parse arguments
|
||||
SCOPE="both"
|
||||
if [ "${1:-}" == "--global" ]; then
|
||||
SCOPE="global"
|
||||
elif [ "${1:-}" == "--project" ]; then
|
||||
SCOPE="project"
|
||||
else
|
||||
# Auto-detect: If in a git repo, do both; otherwise just global
|
||||
if git rev-parse --show-toplevel 2>/dev/null; then
|
||||
SCOPE="both"
|
||||
else
|
||||
SCOPE="global"
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "📋 Configuration scope: $SCOPE"
|
||||
echo ""
|
||||
```
|
||||
|
||||
### Step 3: Global Configuration (if needed)
|
||||
|
||||
**If SCOPE is "global" or "both", use AskUserQuestion to gather inputs, then configure:**
|
||||
|
||||
1. **Ask for Server URL**:
|
||||
Use AskUserQuestion tool:
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "ACE Server URL?",
|
||||
header: "Server URL",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Production (ace-api.code-engine.app)",
|
||||
description: "Official ACE production server (recommended)"
|
||||
},
|
||||
{
|
||||
label: "Localhost (localhost:9000)",
|
||||
description: "Local development server"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Map user selection to URL:
|
||||
- "Production" → `https://ace-api.code-engine.app`
|
||||
- "Localhost" → `http://localhost:9000`
|
||||
- "Other" → Prompt for custom URL
|
||||
|
||||
2. **Ask for API Token**:
|
||||
Use AskUserQuestion tool:
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Enter your ACE API token (starts with 'ace_')?",
|
||||
header: "API Token",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "I have a token",
|
||||
description: "Enter token in the next step"
|
||||
},
|
||||
{
|
||||
label: "I need to get a token",
|
||||
description: "Visit https://ace.code-engine.app/settings/tokens"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If user selects "I have a token", they'll provide it in the "Other" field.
|
||||
If "I need to get a token", show them the URL and exit.
|
||||
|
||||
3. **Validate Token and Get Org/Project Info**:
|
||||
```bash
|
||||
echo "🔍 Validating token with ACE server..."
|
||||
echo " Server: $SERVER_URL"
|
||||
echo ""
|
||||
|
||||
# Use subshell to avoid polluting parent environment
|
||||
# Workaround: ce-ace config validate doesn't accept --server-url flag properly
|
||||
# Use environment variables instead
|
||||
VALIDATION_OUTPUT=$(
|
||||
ACE_SERVER_URL="$SERVER_URL" \
|
||||
ACE_API_TOKEN="$API_TOKEN" \
|
||||
ce-ace config validate --json 2>&1
|
||||
)
|
||||
VALIDATION_EXIT_CODE=$?
|
||||
|
||||
if [ $VALIDATION_EXIT_CODE -ne 0 ]; then
|
||||
echo "❌ Token validation failed"
|
||||
echo ""
|
||||
echo "Error details:"
|
||||
echo "$VALIDATION_OUTPUT"
|
||||
echo ""
|
||||
echo "Common issues:"
|
||||
echo " - Invalid or expired token"
|
||||
echo " - Network connectivity problems"
|
||||
echo " - Server URL incorrect"
|
||||
echo ""
|
||||
echo "Please verify your token at: https://ace.code-engine.app/settings"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Verify we got valid JSON back
|
||||
if ! echo "$VALIDATION_OUTPUT" | jq empty 2>/dev/null; then
|
||||
echo "❌ Invalid response from ACE server (not valid JSON)"
|
||||
echo ""
|
||||
echo "Response:"
|
||||
echo "$VALIDATION_OUTPUT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Parse validation response
|
||||
ORG_ID=$(echo "$VALIDATION_OUTPUT" | jq -r '.org_id // empty')
|
||||
ORG_NAME=$(echo "$VALIDATION_OUTPUT" | jq -r '.org_name // empty')
|
||||
PROJECTS_JSON=$(echo "$VALIDATION_OUTPUT" | jq -c '.projects // []')
|
||||
|
||||
# Verify required fields
|
||||
if [ -z "$ORG_ID" ] || [ -z "$ORG_NAME" ]; then
|
||||
echo "❌ Validation response missing required fields (org_id, org_name)"
|
||||
echo ""
|
||||
echo "Response:"
|
||||
echo "$VALIDATION_OUTPUT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check if user has any projects
|
||||
PROJECT_COUNT=$(echo "$PROJECTS_JSON" | jq 'length')
|
||||
if [ "$PROJECT_COUNT" -eq 0 ]; then
|
||||
echo "⚠️ No projects found for organization: $ORG_NAME"
|
||||
echo ""
|
||||
echo "Please create a project first at: https://ace.code-engine.app/projects"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Validated! Organization: $ORG_NAME ($ORG_ID)"
|
||||
echo " Projects available: $PROJECT_COUNT"
|
||||
echo ""
|
||||
```
|
||||
|
||||
4. **Ask User to Select Project** (use AskUserQuestion):
|
||||
```javascript
|
||||
// Parse projects from PROJECTS_JSON
|
||||
// Build options dynamically from project list
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Which project should be configured?",
|
||||
header: "Project",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
// For each project in PROJECTS_JSON:
|
||||
{
|
||||
label: "project.project_name",
|
||||
description: "project.project_id"
|
||||
}
|
||||
// ... more projects
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Extract project_id from user selection.
|
||||
|
||||
5. **Configure with ce-ace CLI**:
|
||||
```bash
|
||||
echo "💾 Saving global configuration..."
|
||||
|
||||
# Determine config location (respect XDG_CONFIG_HOME)
|
||||
GLOBAL_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/ace/config.json"
|
||||
GLOBAL_CONFIG_DIR=$(dirname "$GLOBAL_CONFIG")
|
||||
|
||||
# Ensure config directory exists
|
||||
if [ ! -d "$GLOBAL_CONFIG_DIR" ]; then
|
||||
echo "📁 Creating config directory: $GLOBAL_CONFIG_DIR"
|
||||
mkdir -p "$GLOBAL_CONFIG_DIR"
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Failed to create config directory: $GLOBAL_CONFIG_DIR"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# Save configuration
|
||||
ce-ace config \
|
||||
--server-url "$SERVER_URL" \
|
||||
--api-token "$API_TOKEN" \
|
||||
--project-id "$PROJECT_ID" \
|
||||
--json
|
||||
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "❌ Failed to save global configuration (ce-ace config command failed)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Verify config file was created
|
||||
if [ ! -f "$GLOBAL_CONFIG" ]; then
|
||||
echo "❌ Global config was not created at expected location"
|
||||
echo " Expected: $GLOBAL_CONFIG"
|
||||
echo " Please check ce-ace CLI logs for details"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Verify config is valid JSON
|
||||
if ! jq empty "$GLOBAL_CONFIG" 2>/dev/null; then
|
||||
echo "❌ Global config is not valid JSON"
|
||||
echo " Location: $GLOBAL_CONFIG"
|
||||
echo " Please check file contents"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Verify required fields are present
|
||||
if ! jq -e '.serverUrl and .apiToken' "$GLOBAL_CONFIG" >/dev/null 2>&1; then
|
||||
echo "❌ Global config is missing required fields (serverUrl, apiToken)"
|
||||
echo " Location: $GLOBAL_CONFIG"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "✅ Global configuration saved and verified:"
|
||||
echo " Location: $GLOBAL_CONFIG"
|
||||
echo " Server: $SERVER_URL"
|
||||
echo " Project: $PROJECT_ID"
|
||||
echo ""
|
||||
```
|
||||
|
||||
### Step 4: Project Configuration (if needed)
|
||||
|
||||
**If SCOPE is "project" or "both":**
|
||||
|
||||
1. **Get Project Root**:
|
||||
```bash
|
||||
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
PROJECT_CONFIG="$PROJECT_ROOT/.claude/settings.json"
|
||||
|
||||
echo "📂 Project root: $PROJECT_ROOT"
|
||||
echo ""
|
||||
```
|
||||
|
||||
2. **Check Existing Config**:
|
||||
```bash
|
||||
if [ -f "$PROJECT_CONFIG" ]; then
|
||||
EXISTING_ORG=$(jq -r '.env.ACE_ORG_ID // empty' "$PROJECT_CONFIG" 2>/dev/null || echo "")
|
||||
EXISTING_PROJECT=$(jq -r '.env.ACE_PROJECT_ID // empty' "$PROJECT_CONFIG" 2>/dev/null || echo "")
|
||||
|
||||
if [ -n "$EXISTING_ORG" ] && [ -n "$EXISTING_PROJECT" ]; then
|
||||
echo "ℹ️ Found existing project configuration:"
|
||||
echo " Organization ID: $EXISTING_ORG"
|
||||
echo " Project ID: $EXISTING_PROJECT"
|
||||
echo ""
|
||||
# Ask user what they want to do - STOP HERE AND PROMPT
|
||||
EXISTING_CONFIG="true"
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
3. **Prompt for Action** (if existing config found):
|
||||
|
||||
If existing configuration was detected, use AskUserQuestion:
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Found existing ACE configuration. What would you like to do?",
|
||||
header: "Config Action",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Keep existing configuration",
|
||||
description: "No changes - use current org and project settings"
|
||||
},
|
||||
{
|
||||
label: "Update project only",
|
||||
description: "Keep organization, select a different project"
|
||||
},
|
||||
{
|
||||
label: "Reconfigure everything",
|
||||
description: "Fresh setup - change both organization and project"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Based on user's choice:
|
||||
- **"Keep existing configuration"** → Exit early:
|
||||
```bash
|
||||
echo "✅ Keeping existing configuration"
|
||||
echo " Organization: $EXISTING_ORG"
|
||||
echo " Project: $EXISTING_PROJECT"
|
||||
exit 0
|
||||
```
|
||||
- **"Update project only"** → Skip to Step 5 (project selection), reuse $EXISTING_ORG
|
||||
- **"Reconfigure everything"** → Continue with Step 4 (full flow)
|
||||
|
||||
4. **Read Global Config**:
|
||||
```bash
|
||||
GLOBAL_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/ace/config.json"
|
||||
|
||||
if [ ! -f "$GLOBAL_CONFIG" ]; then
|
||||
echo "⚠️ No global config found at $GLOBAL_CONFIG"
|
||||
echo " Run /ace:configure --global first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check if multi-org mode
|
||||
HAS_ORGS=$(jq 'has("orgs")' "$GLOBAL_CONFIG" 2>/dev/null || echo "false")
|
||||
```
|
||||
|
||||
4. **Multi-Org Mode** (if HAS_ORGS is true):
|
||||
|
||||
Use AskUserQuestion to select organization:
|
||||
```javascript
|
||||
// Parse orgs from global config
|
||||
// For each org in config.orgs:
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Which organization should this project use?",
|
||||
header: "Organization",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "org.orgName",
|
||||
description: "org_id"
|
||||
}
|
||||
// ... more orgs
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Then ask for project from that org's project list.
|
||||
|
||||
5. **Single-Org Mode** (if HAS_ORGS is false):
|
||||
|
||||
Just ask for project ID directly using AskUserQuestion.
|
||||
|
||||
6. **Write .claude/settings.json**:
|
||||
```bash
|
||||
mkdir -p "$PROJECT_ROOT/.claude"
|
||||
|
||||
if [ -n "$ORG_ID" ]; then
|
||||
# Multi-org: include ACE_ORG_ID in env
|
||||
cat > "$PROJECT_CONFIG" <<EOF
|
||||
{
|
||||
"env": {
|
||||
"ACE_ORG_ID": "$ORG_ID",
|
||||
"ACE_PROJECT_ID": "$PROJECT_ID"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
echo "✅ Project configuration saved:"
|
||||
echo " Organization ID: $ORG_ID"
|
||||
echo " Project ID: $PROJECT_ID"
|
||||
else
|
||||
# Single-org: just ACE_PROJECT_ID in env
|
||||
cat > "$PROJECT_CONFIG" <<EOF
|
||||
{
|
||||
"env": {
|
||||
"ACE_PROJECT_ID": "$PROJECT_ID"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
echo "✅ Project configuration saved:"
|
||||
echo " Project ID: $PROJECT_ID"
|
||||
fi
|
||||
|
||||
echo " Location: $PROJECT_CONFIG"
|
||||
echo ""
|
||||
```
|
||||
|
||||
### Step 5: Show Summary
|
||||
|
||||
```bash
|
||||
echo ""
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo "✅ ACE Configuration Complete!"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
|
||||
if [ "$SCOPE" = "global" ] || [ "$SCOPE" = "both" ]; then
|
||||
GLOBAL_CONFIG="${XDG_CONFIG_HOME:-$HOME/.config}/ace/config.json"
|
||||
echo "Global Config: $GLOBAL_CONFIG ✓"
|
||||
fi
|
||||
|
||||
if [ "$SCOPE" = "project" ] || [ "$SCOPE" = "both" ]; then
|
||||
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
echo "Project Config: $PROJECT_ROOT/.claude/settings.json ✓"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo "1. Run: /ace:status to verify connection"
|
||||
echo "2. Optional: /ace:bootstrap to populate playbook from codebase"
|
||||
echo "3. Start coding - hooks will auto-search patterns!"
|
||||
echo ""
|
||||
```
|
||||
|
||||
## Implementation Notes for Claude
|
||||
|
||||
**Key Points:**
|
||||
1. **Always use AskUserQuestion** for user input (not bash read or prompts)
|
||||
2. **Parse JSON responses** from `ce-ace config validate --json`
|
||||
3. **Build dynamic options** from validation response (orgs/projects)
|
||||
4. **Map user selections** to actual values (e.g., "Production" → URL)
|
||||
5. **Handle both single-org and multi-org modes** based on global config
|
||||
|
||||
**Error Handling:**
|
||||
- Check jq availability (required for JSON parsing)
|
||||
- Check ce-ace version >= 1.0.2
|
||||
- Validate token before saving (with detailed error messages)
|
||||
- Verify global config file was created and is valid JSON
|
||||
- Verify global config has required fields (serverUrl, apiToken)
|
||||
- Check user has at least one project in organization
|
||||
- Handle missing global config for project-only mode
|
||||
- Use subshell for environment variables (avoid pollution)
|
||||
|
||||
**User Experience:**
|
||||
- Show progress messages at each step
|
||||
- Display org/project names (not just IDs) in selections
|
||||
- Provide helpful error messages with next steps
|
||||
- Summarize what was configured
|
||||
|
||||
## What Gets Configured
|
||||
|
||||
### Global Config (~/.config/ace/config.json)
|
||||
|
||||
**Single-Org Mode:**
|
||||
```json
|
||||
{
|
||||
"serverUrl": "https://ace-api.code-engine.app",
|
||||
"apiToken": "ace_xxxxx",
|
||||
"projectId": "prj_xxxxx",
|
||||
"cacheTtlMinutes": 120
|
||||
}
|
||||
```
|
||||
|
||||
**Multi-Org Mode:**
|
||||
```json
|
||||
{
|
||||
"serverUrl": "https://ace-api.code-engine.app",
|
||||
"orgs": {
|
||||
"org_xxxxx": {
|
||||
"orgName": "My Organization",
|
||||
"apiToken": "ace_xxxxx",
|
||||
"projects": ["prj_123", "prj_456"]
|
||||
}
|
||||
},
|
||||
"cacheTtlMinutes": 120
|
||||
}
|
||||
```
|
||||
|
||||
### Project Config (.claude/settings.json)
|
||||
|
||||
**Multi-Org:**
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ACE_ORG_ID": "org_xxxxx",
|
||||
"ACE_PROJECT_ID": "prj_xxxxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Single-Org:**
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ACE_PROJECT_ID": "prj_xxxxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### First-Time Setup (Both Global + Project)
|
||||
|
||||
```
|
||||
/ace:configure
|
||||
```
|
||||
|
||||
**Flow:**
|
||||
1. Asks for server URL (production/localhost/custom)
|
||||
2. Asks for API token
|
||||
3. Validates token, fetches org/projects
|
||||
4. Asks which project to configure
|
||||
5. Saves global config (~/.config/ace/config.json)
|
||||
6. Saves project config (.claude/settings.json)
|
||||
|
||||
### Update Global Config Only
|
||||
|
||||
```
|
||||
/ace:configure --global
|
||||
```
|
||||
|
||||
**Flow:**
|
||||
1. Reconfigures global settings
|
||||
2. Validates token
|
||||
3. Updates ~/.config/ace/config.json
|
||||
|
||||
### Update Project Config Only
|
||||
|
||||
```
|
||||
/ace:configure --project
|
||||
```
|
||||
|
||||
**Flow:**
|
||||
1. Reads existing global config
|
||||
2. Asks which org/project for THIS project
|
||||
3. Updates .claude/settings.json
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:status` - Verify configuration
|
||||
- `/ace:bootstrap` - Initialize playbook
|
||||
- `ce-ace config --help` - CLI config help
|
||||
- `ce-ace config show` - View current config
|
||||
272
commands/ace-delta.md
Normal file
272
commands/ace-delta.md
Normal file
@@ -0,0 +1,272 @@
|
||||
---
|
||||
description: Manual pattern management - add, update, or remove patterns in the ACE playbook
|
||||
---
|
||||
|
||||
# ACE Delta Operations
|
||||
|
||||
Manually manipulate patterns in the ACE playbook using delta operations. This is an **advanced feature** for manual curation, distinct from automatic learning via `ace_learn`.
|
||||
|
||||
## What This Does
|
||||
|
||||
Allows **direct manipulation** of patterns in the ACE playbook:
|
||||
- **ADD**: Manually add new patterns without going through the learning pipeline
|
||||
- **UPDATE**: Modify helpful/harmful scores or pattern content
|
||||
- **REMOVE**: Delete patterns from the playbook
|
||||
|
||||
**Difference from `/ace-learn`**:
|
||||
- `/ace-learn` → Automatic learning through Reflector/Curator pipeline (preferred)
|
||||
- `/ace-delta` → Manual pattern manipulation (advanced/admin feature)
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace-delta [operation]`, use ce-ace CLI with JSON input:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Read context
|
||||
ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
# Try env wrapper format
|
||||
if [ -z "$ORG_ID" ] || [ -z "$PROJECT_ID" ]; then
|
||||
ORG_ID=$(jq -r '.env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
fi
|
||||
|
||||
if [ -z "$PROJECT_ID" ]; then
|
||||
echo "❌ Run /ace:configure first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Operation: add | update | remove
|
||||
OPERATION="$1"
|
||||
shift
|
||||
|
||||
# Create JSON payload based on operation
|
||||
# See examples below for JSON structure
|
||||
```
|
||||
|
||||
### 1. Add New Pattern
|
||||
|
||||
```bash
|
||||
# Example: Add new pattern
|
||||
JSON_PAYLOAD=$(cat <<'EOF'
|
||||
{
|
||||
"bullets": [
|
||||
{
|
||||
"id": "manual-001",
|
||||
"content": "Use HTTP-only cookies for JWT refresh tokens to prevent XSS attacks",
|
||||
"section": "strategies_and_hard_rules",
|
||||
"helpful": 0,
|
||||
"harmful": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
EOF
|
||||
)
|
||||
|
||||
echo "$JSON_PAYLOAD" | if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --json --org "$ORG_ID" --project "$PROJECT_ID" delta add --stdin
|
||||
else
|
||||
ce-ace --json --project "$PROJECT_ID" delta add --stdin
|
||||
fi
|
||||
```
|
||||
|
||||
**Sections**:
|
||||
- `strategies_and_hard_rules` - Architectural patterns, coding principles
|
||||
- `useful_code_snippets` - Reusable code patterns
|
||||
- `troubleshooting_and_pitfalls` - Known issues, gotchas, solutions
|
||||
- `apis_to_use` - Recommended libraries, frameworks
|
||||
|
||||
### 2. Update Pattern Scores
|
||||
|
||||
```bash
|
||||
# Example: Update pattern helpful score
|
||||
JSON_PAYLOAD='{"bullets": [{"id": "ctx-1749038476-4cb2", "helpful": 5}]}'
|
||||
|
||||
echo "$JSON_PAYLOAD" | if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --json --org "$ORG_ID" --project "$PROJECT_ID" delta update --stdin
|
||||
else
|
||||
ce-ace --json --project "$PROJECT_ID" delta update --stdin
|
||||
fi
|
||||
```
|
||||
|
||||
**What can be updated**:
|
||||
- `helpful`: Increment helpful score (pattern was useful)
|
||||
- `harmful`: Increment harmful score (pattern was incorrect/outdated)
|
||||
- `content`: Update pattern text (rare - usually just add new pattern)
|
||||
|
||||
### 3. Remove Pattern
|
||||
|
||||
```bash
|
||||
# Example: Remove pattern
|
||||
JSON_PAYLOAD='{"bullets": [{"id": "ctx-1749038476-4cb2"}]}'
|
||||
|
||||
echo "$JSON_PAYLOAD" | if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --json --org "$ORG_ID" --project "$PROJECT_ID" delta remove --stdin
|
||||
else
|
||||
ce-ace --json --project "$PROJECT_ID" delta remove --stdin
|
||||
fi
|
||||
```
|
||||
|
||||
**When to remove**:
|
||||
- Pattern is outdated or incorrect
|
||||
- Duplicate of another pattern
|
||||
- No longer relevant to project
|
||||
|
||||
### 4. Batch Operations
|
||||
|
||||
```bash
|
||||
# Example: Update multiple patterns
|
||||
JSON_PAYLOAD=$(cat <<'EOF'
|
||||
{
|
||||
"bullets": [
|
||||
{"id": "ctx-001", "helpful": 1},
|
||||
{"id": "ctx-002", "helpful": 1},
|
||||
{"id": "ctx-003", "helpful": 1}
|
||||
]
|
||||
}
|
||||
EOF
|
||||
)
|
||||
|
||||
echo "$JSON_PAYLOAD" | if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --json --org "$ORG_ID" --project "$PROJECT_ID" delta update --stdin
|
||||
else
|
||||
ce-ace --json --project "$PROJECT_ID" delta update --stdin
|
||||
fi
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Quick Pattern Addition
|
||||
|
||||
**Scenario**: You discover a gotcha during debugging and want to immediately add it to the playbook without writing a full learning report.
|
||||
|
||||
```bash
|
||||
/ace-delta add "PostgreSQL array_agg preserves nulls - use array_remove(array_agg(x), null) to filter" troubleshooting_and_pitfalls
|
||||
```
|
||||
|
||||
### 2. Manual Curation
|
||||
|
||||
**Scenario**: You reviewed patterns and found some that need score adjustments or removal.
|
||||
|
||||
```bash
|
||||
# Mark outdated pattern as harmful
|
||||
/ace-delta update ctx-old-001 harmful=3
|
||||
|
||||
# Remove duplicate pattern
|
||||
/ace-delta remove ctx-duplicate-002
|
||||
```
|
||||
|
||||
### 3. Importing External Knowledge
|
||||
|
||||
**Scenario**: You have patterns from another project/team and want to import them.
|
||||
|
||||
```bash
|
||||
/ace-delta add "React useEffect cleanup prevents memory leaks - always return cleanup function" useful_code_snippets
|
||||
```
|
||||
|
||||
### 4. Correcting Incorrect Patterns
|
||||
|
||||
**Scenario**: Automatic learning captured a pattern incorrectly.
|
||||
|
||||
```bash
|
||||
# Remove incorrect pattern
|
||||
/ace-delta remove ctx-wrong-001
|
||||
|
||||
# Add corrected version
|
||||
/ace-delta add "Correct pattern description..." strategies_and_hard_rules
|
||||
```
|
||||
|
||||
## Delta vs Learn
|
||||
|
||||
| Feature | `/ace-delta` | `/ace-learn` (via skill) |
|
||||
|---------|--------------|--------------------------|
|
||||
| **Invocation** | Manual command | Automatic skill trigger |
|
||||
| **Processing** | Direct to playbook | Reflector → Curator → Merge |
|
||||
| **Use Case** | Quick fixes, curation | Post-task learning |
|
||||
| **Quality Control** | User responsibility | Server-side analysis |
|
||||
| **Trajectory** | Not captured | Full execution trace |
|
||||
| **Preferred** | ❌ Rare/admin use | ✅ Primary method |
|
||||
|
||||
**Recommendation**: Use automatic learning (`ace_learn` via skill) for 99% of cases. Use delta operations only for manual curation or quick fixes.
|
||||
|
||||
## Safety Notes
|
||||
|
||||
⚠️ **Delta operations bypass automatic quality control**:
|
||||
- No Reflector analysis
|
||||
- No Curator validation
|
||||
- No deduplication check
|
||||
- Direct playbook manipulation
|
||||
|
||||
**Best Practices**:
|
||||
1. **Prefer automatic learning** - Use `ace_learn` skill whenever possible
|
||||
2. **Be specific** - Write clear, actionable pattern descriptions
|
||||
3. **Use proper sections** - Place patterns in correct playbook section
|
||||
4. **Verify after changes** - Run `/ace-patterns` to confirm updates
|
||||
5. **Start with helpful=0** - Let usage naturally increase scores
|
||||
6. **Don't duplicate** - Check `/ace-search` before adding manually
|
||||
|
||||
## Output Format
|
||||
|
||||
### Successful ADD:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"operation": "add",
|
||||
"bullets_affected": 1,
|
||||
"message": "Successfully applied add operation to 1 bullet(s)"
|
||||
}
|
||||
```
|
||||
|
||||
### Successful UPDATE:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"operation": "update",
|
||||
"bullets_affected": 2,
|
||||
"message": "Successfully applied update operation to 2 bullet(s)"
|
||||
}
|
||||
```
|
||||
|
||||
### Successful REMOVE:
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"operation": "remove",
|
||||
"bullets_affected": 1,
|
||||
"message": "Successfully applied remove operation to 1 bullet(s)"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Pattern ID Not Found:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Pattern ctx-nonexistent-001 not found"
|
||||
}
|
||||
```
|
||||
|
||||
### Invalid Section:
|
||||
```json
|
||||
{
|
||||
"success": false,
|
||||
"error": "Invalid section: invalid_section"
|
||||
}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- **ACE Learning Skill** - Automatic pattern learning (preferred method)
|
||||
- `/ace-patterns` - View playbook to find pattern IDs
|
||||
- `/ace-search` - Search patterns before adding duplicates
|
||||
- `/ace-status` - Check playbook statistics after changes
|
||||
634
commands/ace-doctor.md
Normal file
634
commands/ace-doctor.md
Normal file
@@ -0,0 +1,634 @@
|
||||
---
|
||||
description: Comprehensive ACE installation and health diagnostic
|
||||
---
|
||||
|
||||
# ACE Doctor - Installation & Health Diagnostic
|
||||
|
||||
Comprehensive diagnostic tool that checks your entire ACE setup and identifies issues.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace:ace-doctor`, perform a complete health check of the ACE system.
|
||||
|
||||
### Diagnostic Flow
|
||||
|
||||
Run all checks in parallel for speed, then present organized results.
|
||||
|
||||
---
|
||||
|
||||
## 🏥 Diagnostic Checks
|
||||
|
||||
### Check 1: Plugin Installation
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Verify plugin directory structure
|
||||
ls -la ~/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace/
|
||||
```
|
||||
|
||||
**Expected Structure**:
|
||||
```
|
||||
ace/
|
||||
├── commands/ # Slash commands (/ace-search, /ace-patterns, etc.)
|
||||
├── hooks/
|
||||
│ └── hooks.json # Hook definitions
|
||||
├── scripts/ # Hook wrapper scripts
|
||||
│ ├── ace_install_cli.sh
|
||||
│ ├── ace_before_task_wrapper.sh
|
||||
│ ├── ace_task_complete_wrapper.sh
|
||||
│ └── ace_after_task_wrapper.sh
|
||||
├── plugin.json
|
||||
└── CLAUDE.md
|
||||
```
|
||||
|
||||
**Report**:
|
||||
- ✅ Plugin installed correctly
|
||||
- ⚠️ Plugin directory missing components
|
||||
- ❌ Plugin not installed
|
||||
|
||||
**If Failed**:
|
||||
```
|
||||
❌ Plugin Installation: NOT FOUND
|
||||
|
||||
Recommended Actions:
|
||||
1. Install plugin via Claude Code marketplace
|
||||
2. OR install via symlink:
|
||||
ln -s /path/to/ace ~/.claude/plugins/ace
|
||||
3. Restart Claude Code after installation
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Check 2: Global Configuration
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Check global config exists (XDG standard path)
|
||||
XDG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
|
||||
CONFIG_PATH="$XDG_HOME/ace/config.json"
|
||||
test -f "$CONFIG_PATH" && echo "EXISTS" || echo "MISSING"
|
||||
|
||||
# If exists, validate JSON and check required fields
|
||||
jq -e '.serverUrl, .apiToken, .cacheTtlMinutes, .autoUpdateEnabled' "$CONFIG_PATH"
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```json
|
||||
{
|
||||
"serverUrl": "https://ace-api.code-engine.app",
|
||||
"apiToken": "ace_xxxxx",
|
||||
"cacheTtlMinutes": 120,
|
||||
"autoUpdateEnabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Report**:
|
||||
- ✅ Global config valid
|
||||
- ⚠️ Global config exists but incomplete
|
||||
- ❌ Global config missing
|
||||
|
||||
**If Failed**:
|
||||
```
|
||||
❌ Global Configuration: MISSING
|
||||
|
||||
Recommended Actions:
|
||||
1. Run: /ace:ace-configure --global
|
||||
2. Provide:
|
||||
- Server URL (https://ace-api.code-engine.app)
|
||||
- API Token (starts with ace_)
|
||||
```
|
||||
|
||||
**If Incomplete**:
|
||||
```
|
||||
⚠️ Global Configuration: INCOMPLETE
|
||||
|
||||
Missing fields: apiToken, cacheTtlMinutes
|
||||
|
||||
Recommended Actions:
|
||||
1. Run: /ace:ace-configure --global
|
||||
2. This will preserve existing values and fill missing fields
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Check 3: Project Configuration
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Get project root
|
||||
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
|
||||
# Check project settings
|
||||
test -f "$PROJECT_ROOT/.claude/settings.json" && echo "EXISTS" || echo "MISSING"
|
||||
|
||||
# If exists, validate ACE_PROJECT_ID env var
|
||||
jq -e '.projectId' "$PROJECT_ROOT/.claude/settings.json"
|
||||
```
|
||||
|
||||
**Expected**:
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"ACE_PROJECT_ID": "prj_xxxxx"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Report**:
|
||||
- ✅ Project config valid with ACE_PROJECT_ID set
|
||||
- ⚠️ Project config exists but ACE_PROJECT_ID missing
|
||||
- ❌ Project config missing
|
||||
|
||||
**Note**: ce-ace CLI is used for all ACE operations.
|
||||
|
||||
**If Failed**:
|
||||
```
|
||||
❌ Project Configuration: MISSING
|
||||
|
||||
Recommended Actions:
|
||||
1. Run: /ace:ace-configure --project
|
||||
2. Provide your project ID (starts with prj_)
|
||||
```
|
||||
|
||||
**If Using @latest**:
|
||||
```
|
||||
⚠️ Project Configuration: USING @latest
|
||||
|
||||
Current: "@ce-dot-net/ace-client@latest"
|
||||
Recommended: "@ce-dot-net/ace-client@3.7.2"
|
||||
|
||||
Issue: @latest causes npx caching - updates won't install automatically
|
||||
|
||||
Recommended Actions:
|
||||
1. Run: /ace:ace-configure --project
|
||||
2. This will update to pinned version 3.7.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Check 4: CLI Availability
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Check if ce-ace is installed and working
|
||||
command -v ce-ace >/dev/null 2>&1 && echo "INSTALLED" || echo "NOT FOUND"
|
||||
|
||||
# If installed, check version
|
||||
ce-ace --version
|
||||
```
|
||||
|
||||
**Report**:
|
||||
- ✅ ce-ace CLI installed and accessible
|
||||
- ⚠️ ce-ace CLI installed but old version
|
||||
- ❌ ce-ace CLI not found
|
||||
|
||||
**If Failed**:
|
||||
```
|
||||
❌ CLI: NOT FOUND
|
||||
|
||||
Possible Causes:
|
||||
1. ce-ace CLI not installed globally
|
||||
2. npm global bin path not in PATH
|
||||
|
||||
Recommended Actions:
|
||||
1. Install: npm install -g @ace-sdk/cli
|
||||
2. Check version: ce-ace --version
|
||||
3. Verify PATH includes npm global bin: npm bin -g
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Check 5: ACE Server Connectivity
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Read serverUrl and apiToken from global config
|
||||
XDG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
|
||||
SERVER_URL=$(jq -r '.serverUrl' "$XDG_HOME/ace/config.json")
|
||||
API_TOKEN=$(jq -r '.apiToken' "$XDG_HOME/ace/config.json")
|
||||
PROJECT_ID=$(jq -r '.projectId' .claude/settings.json)
|
||||
|
||||
# Test connection to ACE server
|
||||
curl -s -X GET \
|
||||
-H "Authorization: Bearer $API_TOKEN" \
|
||||
"$SERVER_URL/api/projects/$PROJECT_ID/playbook" \
|
||||
-w "\nHTTP: %{http_code}\n" \
|
||||
-o /tmp/ace-doctor-response.json
|
||||
```
|
||||
|
||||
**Report**:
|
||||
- ✅ ACE server reachable and authenticated (HTTP 200)
|
||||
- ⚠️ Server reachable but authentication failed (HTTP 401)
|
||||
- ⚠️ Project not found (HTTP 404)
|
||||
- ❌ Server unreachable (connection timeout/refused)
|
||||
|
||||
**If Failed**:
|
||||
```
|
||||
❌ ACE Server: UNREACHABLE
|
||||
|
||||
Server URL: https://ace-api.code-engine.app
|
||||
HTTP Status: Connection refused
|
||||
|
||||
Possible Causes:
|
||||
1. Network connectivity issues
|
||||
2. Firewall blocking HTTPS
|
||||
3. Incorrect server URL
|
||||
|
||||
Recommended Actions:
|
||||
1. Test connection: curl https://ace-api.code-engine.app/api/health
|
||||
2. Check firewall settings
|
||||
3. Try different network (WiFi vs. Ethernet)
|
||||
4. Verify serverUrl in ~/.config/ace/config.json
|
||||
```
|
||||
|
||||
**If 401 Unauthorized**:
|
||||
```
|
||||
⚠️ ACE Server: AUTHENTICATION FAILED
|
||||
|
||||
Server URL: https://ace-api.code-engine.app
|
||||
HTTP Status: 401 Unauthorized
|
||||
|
||||
Recommended Actions:
|
||||
1. Verify API token is correct
|
||||
2. Check token hasn't expired
|
||||
3. Run: /ace:ace-configure --global
|
||||
4. Get new token from ACE server admin
|
||||
```
|
||||
|
||||
**If 404 Not Found**:
|
||||
```
|
||||
⚠️ ACE Server: PROJECT NOT FOUND
|
||||
|
||||
Project ID: prj_xxxxx
|
||||
HTTP Status: 404 Not Found
|
||||
|
||||
Recommended Actions:
|
||||
1. Verify project ID exists in ACE server
|
||||
2. Check you have access to this project
|
||||
3. Run: /ace:ace-configure --project
|
||||
4. Create new project in ACE dashboard
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Check 6: Hooks Registered
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Check if hook scripts exist
|
||||
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
PLUGIN_ROOT="$HOME/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace"
|
||||
|
||||
# Check hook wrappers in scripts/
|
||||
test -f "$PLUGIN_ROOT/scripts/ace_before_task_wrapper.sh" && echo "before_task: EXISTS"
|
||||
test -f "$PLUGIN_ROOT/scripts/ace_task_complete_wrapper.sh" && echo "task_complete: EXISTS"
|
||||
test -f "$PLUGIN_ROOT/scripts/ace_after_task_wrapper.sh" && echo "after_task: EXISTS"
|
||||
test -f "$PLUGIN_ROOT/scripts/ace_install_cli.sh" && echo "install_cli: EXISTS"
|
||||
|
||||
# Check hooks.json
|
||||
test -f "$PLUGIN_ROOT/hooks/hooks.json" && echo "hooks.json: EXISTS"
|
||||
```
|
||||
|
||||
**Expected Hooks** (5 total):
|
||||
1. `SessionStart` → `ace_install_cli.sh`
|
||||
2. `UserPromptSubmit` → `ace_before_task_wrapper.sh`
|
||||
3. `PostToolUse` → `ace_task_complete_wrapper.sh`
|
||||
4. `PreCompact` → `ace_after_task_wrapper.sh`
|
||||
5. `Stop` → `ace_after_task_wrapper.sh`
|
||||
|
||||
**Report**:
|
||||
- ✅ All hooks registered (5/5)
|
||||
- ⚠️ Some hooks missing (e.g., 3/5)
|
||||
- ❌ No hooks registered (0/5)
|
||||
|
||||
**If Failed**:
|
||||
```
|
||||
❌ Hooks: NOT REGISTERED
|
||||
|
||||
Expected Hook Scripts:
|
||||
- ace_before_task_wrapper.sh (retrieves patterns before tasks)
|
||||
- ace_task_complete_wrapper.sh (captures learning after tasks)
|
||||
- ace_after_task_wrapper.sh (backup learning at session end)
|
||||
- ace_install_cli.sh (ensures ce-ace CLI is available)
|
||||
|
||||
Recommended Actions:
|
||||
1. Verify plugin installation (Check 1)
|
||||
2. Check scripts/ directory exists in plugin
|
||||
3. Verify hooks.json exists in hooks/ directory
|
||||
4. Run: /ace:ace-test to verify hook execution
|
||||
5. Check Claude Code logs for hook errors
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Check 7: CLAUDE.md Status
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Check if CLAUDE.md exists in project root
|
||||
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
|
||||
test -f "$PROJECT_ROOT/CLAUDE.md" && echo "EXISTS" || echo "MISSING"
|
||||
|
||||
# If exists, check for ACE section
|
||||
grep -q "ACE_SECTION_START" "$PROJECT_ROOT/CLAUDE.md" && echo "HAS_ACE" || echo "NO_ACE"
|
||||
|
||||
# Extract version
|
||||
grep -oP 'ACE_SECTION_START v\K[\d.]+' "$PROJECT_ROOT/CLAUDE.md"
|
||||
```
|
||||
|
||||
**Report**:
|
||||
- ✅ CLAUDE.md exists with ACE instructions (v5.x.x)
|
||||
- ⚠️ CLAUDE.md exists but no ACE section
|
||||
- ⚠️ CLAUDE.md exists but outdated version (< v5.0.0)
|
||||
- ❌ CLAUDE.md missing
|
||||
|
||||
**If Missing**:
|
||||
```
|
||||
❌ CLAUDE.md: NOT FOUND
|
||||
|
||||
Recommended Actions:
|
||||
1. Run: /ace:ace-claude-init
|
||||
2. This will create CLAUDE.md with ACE instructions
|
||||
3. Documents hook-based architecture and automatic learning
|
||||
4. Commit CLAUDE.md to your repository
|
||||
```
|
||||
|
||||
**If Outdated**:
|
||||
```
|
||||
⚠️ CLAUDE.md: OUTDATED VERSION
|
||||
|
||||
Current: v4.x.x (or earlier)
|
||||
Latest: v5.1.2
|
||||
|
||||
Breaking Change: v5.x uses hooks instead of skills/subagents
|
||||
|
||||
Recommended Actions:
|
||||
1. Run: /ace:ace-claude-init
|
||||
2. This will update to hook-based architecture
|
||||
3. Review CHANGELOG.md for migration details
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Check 8: CLI Configuration
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Check ce-ace CLI config
|
||||
XDG_HOME="${XDG_CONFIG_HOME:-$HOME/.config}"
|
||||
test -f "$XDG_HOME/ace/config.json" && echo "CONFIG: EXISTS"
|
||||
|
||||
# Check if multi-org format (ce-ace v1.x)
|
||||
jq -e '.organizations' "$XDG_HOME/ace/config.json" >/dev/null 2>&1 && echo "FORMAT: MULTI-ORG"
|
||||
|
||||
# Check required fields
|
||||
jq -e '.organizations[0].apiKey' "$XDG_HOME/ace/config.json" >/dev/null 2>&1 && echo "API_KEY: SET"
|
||||
```
|
||||
|
||||
**Expected** (ce-ace v1.x multi-org format):
|
||||
```json
|
||||
{
|
||||
"organizations": [
|
||||
{
|
||||
"name": "ce-dot-net",
|
||||
"apiKey": "ace_xxxxx"
|
||||
}
|
||||
],
|
||||
"activeOrg": "ce-dot-net"
|
||||
}
|
||||
```
|
||||
|
||||
**Report**:
|
||||
- ✅ CLI config valid (multi-org format)
|
||||
- ⚠️ CLI config exists but old format (single-org)
|
||||
- ❌ CLI config missing
|
||||
|
||||
**If Old Format**:
|
||||
```
|
||||
⚠️ CLI Configuration: OLD FORMAT
|
||||
|
||||
Current: Single-org format (ce-ace v0.x)
|
||||
Expected: Multi-org format (ce-ace v1.x+)
|
||||
|
||||
Recommended Actions:
|
||||
1. Update ce-ace CLI: npm install -g @ace-sdk/cli@latest
|
||||
2. Run: ce-ace configure
|
||||
3. Or run: /ace:ace-configure
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Check 9: Version Status
|
||||
|
||||
**What to Check**:
|
||||
```bash
|
||||
# Get plugin version
|
||||
PLUGIN_JSON="$HOME/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace/plugin.json"
|
||||
if [ -f "$PLUGIN_JSON" ]; then
|
||||
jq -r '.version' "$PLUGIN_JSON"
|
||||
else
|
||||
echo "unknown"
|
||||
fi
|
||||
|
||||
# Get ce-ace CLI version
|
||||
if command -v ce-ace >/dev/null 2>&1; then
|
||||
ce-ace --version 2>/dev/null || echo "unknown"
|
||||
else
|
||||
echo "not installed"
|
||||
fi
|
||||
|
||||
# Check for Python hooks (shared-hooks/)
|
||||
if [ -d "shared-hooks" ]; then
|
||||
echo "Python hooks: present"
|
||||
else
|
||||
echo "Python hooks: missing (required for v5.x)"
|
||||
fi
|
||||
```
|
||||
|
||||
**Expected Versions** (as of 2024-11):
|
||||
- Plugin: v5.1.2+
|
||||
- ce-ace CLI: v1.0.9+
|
||||
- CLAUDE.md: v5.0.3+
|
||||
|
||||
**Report**:
|
||||
- ✅ All components up to date
|
||||
- ⚠️ Plugin outdated (< v5.1.2)
|
||||
- ⚠️ CLI outdated (< v1.0.9)
|
||||
- ❌ Critical version mismatch
|
||||
|
||||
**If Updates Available**:
|
||||
```
|
||||
⚠️ Updates Recommended
|
||||
|
||||
Plugin: v5.1.1 → v5.1.2 (latest)
|
||||
ce-ace CLI: v1.0.8 → v1.0.9 (latest)
|
||||
|
||||
Changes in v5.1.2:
|
||||
- Context passing bug fix (subprocess environment variables)
|
||||
- Improved error handling in Python hooks
|
||||
|
||||
Recommended Actions:
|
||||
1. Update ce-ace CLI: npm install -g @ace-sdk/cli@latest
|
||||
2. Update plugin from marketplace (if available)
|
||||
3. Run: /ace:ace-claude-init to update CLAUDE.md
|
||||
4. Restart Claude Code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Final Report Format
|
||||
|
||||
After running all checks, present results in this format:
|
||||
|
||||
```
|
||||
🩺 ACE Doctor - Health Diagnostic Report
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
[1] Plugin Installation................... ✅ PASS
|
||||
[2] Global Configuration................. ✅ PASS
|
||||
[3] Project Configuration................ ✅ PASS
|
||||
[4] CLI Availability..................... ✅ PASS (v1.0.9)
|
||||
[5] ACE Server Connectivity.............. ✅ PASS (HTTP 200)
|
||||
[6] Hooks Registered..................... ✅ PASS (5/5)
|
||||
[7] CLAUDE.md Status..................... ✅ PASS (v5.1.2)
|
||||
[8] CLI Configuration.................... ✅ PASS (multi-org)
|
||||
[9] Version Status....................... ✅ PASS
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Overall Health: 🟢 HEALTHY
|
||||
|
||||
✅ All systems operational!
|
||||
|
||||
ACE is properly configured and ready to use.
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
System Information:
|
||||
|
||||
Plugin Version: v5.1.2
|
||||
CLI Version: v1.0.9
|
||||
Architecture: Hook-based (v5.x)
|
||||
Project ID: prj_d3a244129d62c198
|
||||
Organization: org_34fYIlitYk4nyFuTvtsAzA6uUJF
|
||||
|
||||
Registered Hooks:
|
||||
• SessionStart → ace_install_cli.sh
|
||||
• UserPromptSubmit → ace_before_task_wrapper.sh
|
||||
• PostToolUse → ace_task_complete_wrapper.sh
|
||||
• PreCompact → ace_after_task_wrapper.sh
|
||||
• Stop → ace_after_task_wrapper.sh
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
For detailed troubleshooting, see:
|
||||
- README.md (section: 🐛 Troubleshooting)
|
||||
- /ace:ace-test (hook execution test)
|
||||
|
||||
Report issues: https://github.com/ce-dot-net/ce-claude-marketplace/issues
|
||||
```
|
||||
|
||||
### Example with Warnings
|
||||
|
||||
```
|
||||
🩺 ACE Doctor - Health Diagnostic Report
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
[1] Plugin Installation................... ✅ PASS
|
||||
[2] Global Configuration................. ✅ PASS
|
||||
[3] Project Configuration................ ⚠️ WARN
|
||||
[4] CLI Availability..................... ✅ PASS (v1.0.9)
|
||||
[5] ACE Server Connectivity.............. ✅ PASS (HTTP 200)
|
||||
[6] Hooks Registered..................... ⚠️ WARN (3/5)
|
||||
[7] CLAUDE.md Status..................... ⚠️ WARN (v4.2.0)
|
||||
[8] CLI Configuration.................... ✅ PASS
|
||||
[9] Version Status....................... ⚠️ WARN
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
Overall Health: 🟡 NEEDS ATTENTION (4 warnings)
|
||||
|
||||
⚠️ Warnings Found:
|
||||
|
||||
[3] Project Configuration
|
||||
Issue: projectId missing in .claude/settings.json
|
||||
Impact: Hooks cannot determine which project to use
|
||||
Fix: Run /ace:ace-configure
|
||||
|
||||
[6] Hooks Registered
|
||||
Issue: Some hook scripts missing (3/5 found)
|
||||
Missing: ace_task_complete_wrapper.sh, ace_after_task_wrapper.sh
|
||||
Impact: Learning capture won't work after tasks
|
||||
Fix: Reinstall plugin or check scripts/ directory
|
||||
|
||||
[7] CLAUDE.md Status
|
||||
Issue: Outdated version (v4.2.0, latest: v5.1.2)
|
||||
Impact: Using old skills-based architecture instead of hooks
|
||||
Fix: Run /ace:ace-claude-init
|
||||
|
||||
[9] Version Status
|
||||
Issue: Updates available
|
||||
Plugin: v5.1.1 → v5.1.2
|
||||
CLI: v1.0.8 → v1.0.9
|
||||
Fix: See recommended actions below
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
🎯 Quick Fix All Issues:
|
||||
|
||||
Run these commands in order:
|
||||
1. /ace:ace-configure
|
||||
2. /ace:ace-claude-init
|
||||
3. npm install -g @ace-sdk/cli@latest
|
||||
4. Restart Claude Code
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
System Information:
|
||||
|
||||
Plugin Version: v5.1.1
|
||||
CLI Version: v1.0.8
|
||||
Architecture: Hook-based (v5.x)
|
||||
Project ID: (not configured)
|
||||
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
For detailed troubleshooting, see:
|
||||
- README.md (section: 🐛 Troubleshooting)
|
||||
- /ace:ace-test (hook execution test)
|
||||
|
||||
Report issues: https://github.com/ce-dot-net/ce-claude-marketplace/issues
|
||||
```
|
||||
|
||||
## Color Coding Legend
|
||||
|
||||
Use these status indicators:
|
||||
- ✅ **PASS** - Everything working correctly
|
||||
- ⚠️ **WARN** - Non-critical issue, system still functional
|
||||
- ❌ **FAIL** - Critical issue, system may not work properly
|
||||
|
||||
## Performance
|
||||
|
||||
Run all checks in **parallel** for speed (< 5 seconds total).
|
||||
|
||||
Use Promise.all() or concurrent bash commands where possible.
|
||||
|
||||
## Error Handling
|
||||
|
||||
If any check throws an error:
|
||||
1. Catch the error gracefully
|
||||
2. Report as ❌ FAIL with error message
|
||||
3. Continue with remaining checks
|
||||
4. Include error details in final report
|
||||
|
||||
## Exit Codes
|
||||
|
||||
This is a diagnostic command - NEVER exit with error code.
|
||||
Always complete all checks and present full report.
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:ace-test` - Plugin-specific tests
|
||||
- `/ace:ace-status` - Playbook statistics
|
||||
- `/ace:ace-configure` - Configuration wizard
|
||||
- README.md - Full troubleshooting guide
|
||||
258
commands/ace-enable-auto-update.md
Normal file
258
commands/ace-enable-auto-update.md
Normal file
@@ -0,0 +1,258 @@
|
||||
---
|
||||
description: Enable or disable automatic ACE CLAUDE.md updates on session start
|
||||
---
|
||||
|
||||
# ACE Enable Auto-Update
|
||||
|
||||
Control automatic updates of ACE plugin instructions in your project's CLAUDE.md.
|
||||
|
||||
## What This Does
|
||||
|
||||
Toggles automatic updating of ACE instructions when the plugin version changes. When enabled, ACE will silently update your project's CLAUDE.md on session start if a new plugin version is detected.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace-enable-auto-update`, follow these steps:
|
||||
|
||||
### Check Current Status
|
||||
|
||||
1. Check if auto-update is currently enabled:
|
||||
```bash
|
||||
if [ -f ~/.ace/auto-update-enabled ]; then
|
||||
echo "Status: ENABLED"
|
||||
else
|
||||
echo "Status: DISABLED"
|
||||
fi
|
||||
```
|
||||
|
||||
2. Show current status to user with explanation
|
||||
|
||||
### Ask User for Action
|
||||
|
||||
Present options:
|
||||
```
|
||||
Auto-Update Status: [ENABLED/DISABLED]
|
||||
|
||||
What would you like to do?
|
||||
1. Enable auto-update - ACE instructions update automatically on session start
|
||||
2. Disable auto-update - Manual updates only (run /ace:ace-claude-init)
|
||||
3. Show more info - Learn about auto-update feature
|
||||
4. Cancel - No changes
|
||||
```
|
||||
|
||||
### Perform Action
|
||||
|
||||
**If user chooses "Enable":**
|
||||
```bash
|
||||
mkdir -p ~/.ace
|
||||
touch ~/.ace/auto-update-enabled
|
||||
echo "✅ Auto-update ENABLED"
|
||||
echo ""
|
||||
echo "ACE will now automatically update your project's CLAUDE.md when:"
|
||||
echo "- A new ACE plugin version is installed"
|
||||
echo "- You start a Claude Code session"
|
||||
echo "- Your project's ACE instructions are outdated"
|
||||
echo ""
|
||||
echo "Updates are:"
|
||||
echo "- ✅ Silent (no interruption)"
|
||||
echo "- ✅ Safe (backups created)"
|
||||
echo "- ✅ Smart (only when needed)"
|
||||
echo ""
|
||||
echo "To disable: Run /ace:ace-enable-auto-update again"
|
||||
```
|
||||
|
||||
**If user chooses "Disable":**
|
||||
```bash
|
||||
rm -f ~/.ace/auto-update-enabled
|
||||
echo "✅ Auto-update DISABLED"
|
||||
echo ""
|
||||
echo "ACE will now require manual updates:"
|
||||
echo "- Run /ace:ace-claude-init to update"
|
||||
echo "- You'll be notified when updates are available"
|
||||
echo ""
|
||||
echo "To re-enable: Run /ace:ace-enable-auto-update"
|
||||
```
|
||||
|
||||
**If user chooses "Show more info":**
|
||||
```
|
||||
## Auto-Update Feature Details
|
||||
|
||||
**How It Works:**
|
||||
1. SessionStart hook checks for ACE version mismatch
|
||||
2. If update available AND auto-update enabled:
|
||||
- Script runs in background (< 1 second)
|
||||
- Updates only ACE section (preserves your content)
|
||||
- Creates backup before update
|
||||
- Logs update to ~/.ace/update-history.log
|
||||
|
||||
**What Gets Updated:**
|
||||
- ACE plugin instructions (between HTML markers)
|
||||
- Version markers
|
||||
- New features and improvements
|
||||
|
||||
**What's Preserved:**
|
||||
- All your custom CLAUDE.md content (before and after ACE section)
|
||||
- File structure and formatting
|
||||
- Git history (you can revert if needed)
|
||||
|
||||
**Safety Features:**
|
||||
- Automatic backups: ~/.claude-md-backup/
|
||||
- Only updates marked sections (HTML markers required)
|
||||
- Falls back to manual if complex merge needed
|
||||
- Never overwrites without validation
|
||||
|
||||
**Token Savings:**
|
||||
- Script-based updates: 0 tokens
|
||||
- LLM-based updates: ~17,000 tokens (fallback)
|
||||
- Manual checks eliminated: ~1,000 tokens per session
|
||||
|
||||
**When Updates Happen:**
|
||||
- Only on plugin version changes (not every session)
|
||||
- Only when your project's ACE version is outdated
|
||||
- Requires markers in CLAUDE.md (v3.2.36+)
|
||||
|
||||
**Control:**
|
||||
- Enable/disable anytime
|
||||
- Per-user setting (not per-project)
|
||||
- Applies to all projects with auto-update enabled
|
||||
|
||||
**Recommendation:**
|
||||
- Enable if: You trust automatic updates and want seamless experience
|
||||
- Disable if: You prefer manual control over documentation changes
|
||||
```
|
||||
|
||||
**If user chooses "Cancel":**
|
||||
```
|
||||
No changes made. Auto-update status unchanged.
|
||||
```
|
||||
|
||||
## Usage Examples
|
||||
|
||||
### Enable Auto-Update
|
||||
|
||||
```
|
||||
User: /ace-enable-auto-update
|
||||
|
||||
Claude: Auto-Update Status: DISABLED
|
||||
|
||||
What would you like to do?
|
||||
1. Enable auto-update
|
||||
2. Disable auto-update
|
||||
3. Show more info
|
||||
4. Cancel
|
||||
|
||||
User: 1
|
||||
|
||||
Claude: ✅ Auto-update ENABLED
|
||||
...
|
||||
```
|
||||
|
||||
### Check Status
|
||||
|
||||
```
|
||||
User: /ace-enable-auto-update
|
||||
|
||||
Claude: Auto-Update Status: ENABLED
|
||||
|
||||
What would you like to do?
|
||||
[options...]
|
||||
|
||||
User: 4
|
||||
|
||||
Claude: No changes made.
|
||||
```
|
||||
|
||||
## How Auto-Update Works
|
||||
|
||||
**SessionStart Flow:**
|
||||
```
|
||||
Session Start
|
||||
↓
|
||||
check-ace-version.sh runs
|
||||
↓
|
||||
Detects version mismatch?
|
||||
↓
|
||||
Check ~/.ace/auto-update-enabled exists?
|
||||
↓
|
||||
YES → Run ace-claude-init.sh --auto-update
|
||||
NO → Create notification only
|
||||
↓
|
||||
Update completed silently
|
||||
(or notification shown)
|
||||
```
|
||||
|
||||
**Update Process:**
|
||||
1. Backup created: `CLAUDE.md.backup-YYYYMMDD-HHMMSS`
|
||||
2. ACE section extracted using HTML markers
|
||||
3. New template content inserted
|
||||
4. File validated (must have ACE content)
|
||||
5. Original file replaced
|
||||
6. Log entry created
|
||||
|
||||
## Configuration Files
|
||||
|
||||
**Auto-update flag:**
|
||||
- Location: `~/.ace/auto-update-enabled`
|
||||
- Type: Empty file (presence = enabled)
|
||||
- Scope: User-wide (applies to all projects)
|
||||
|
||||
**Update history:**
|
||||
- Location: `~/.ace/update-history.log`
|
||||
- Format: JSON lines (one per update)
|
||||
- Example:
|
||||
```json
|
||||
{"timestamp":"2025-10-30T12:00:00Z","project":"/path/to/project","from":"3.2.28","to":"3.2.36","status":"success"}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Auto-update not working
|
||||
|
||||
1. Check if enabled:
|
||||
```bash
|
||||
ls -la ~/.ace/auto-update-enabled
|
||||
```
|
||||
|
||||
2. Check for update notifications:
|
||||
```bash
|
||||
cat ~/.ace/update-notification.txt
|
||||
```
|
||||
|
||||
3. Check update history:
|
||||
```bash
|
||||
tail ~/.ace/update-history.log
|
||||
```
|
||||
|
||||
### Manual update after auto-update failure
|
||||
|
||||
If auto-update fails (complex file structure), you'll see a notification. Run:
|
||||
```
|
||||
/ace:ace-claude-init
|
||||
```
|
||||
|
||||
This will use LLM-based update (more robust, handles complex cases).
|
||||
|
||||
### Restore from backup
|
||||
|
||||
If an update went wrong:
|
||||
```bash
|
||||
# List backups
|
||||
ls -lt CLAUDE.md.backup-*
|
||||
|
||||
# Restore specific backup
|
||||
cp CLAUDE.md.backup-20251030-120000 CLAUDE.md
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:ace-claude-init` - Manual update command
|
||||
- `/ace:ace-status` - Check ACE connection and status
|
||||
- `/ace:ace-configure` - Configure ACE server
|
||||
|
||||
## Security Note
|
||||
|
||||
Auto-update modifies your project's CLAUDE.md file automatically. While safe (backups are created), you should:
|
||||
- ✅ Review changes periodically
|
||||
- ✅ Commit backups to git (optional)
|
||||
- ✅ Disable if working on critical documentation
|
||||
- ✅ Trust the ACE plugin source (official marketplace)
|
||||
106
commands/ace-export-patterns.md
Normal file
106
commands/ace-export-patterns.md
Normal file
@@ -0,0 +1,106 @@
|
||||
---
|
||||
description: Export ACE playbook to JSON for backup or sharing
|
||||
---
|
||||
|
||||
# ACE Export Playbook
|
||||
|
||||
Export your ACE playbook to JSON for backup or cross-project sharing.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace:export-patterns`, use ce-ace CLI to export the playbook:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Read context
|
||||
ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
# Try env wrapper format
|
||||
if [ -z "$ORG_ID" ] || [ -z "$PROJECT_ID" ]; then
|
||||
ORG_ID=$(jq -r '.env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
fi
|
||||
|
||||
if [ -z "$PROJECT_ID" ]; then
|
||||
echo "❌ Run /ace:configure first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Export playbook
|
||||
OUTPUT_FILE="${1:-ace-playbook-export.json}"
|
||||
|
||||
echo "📦 Exporting ACE playbook..."
|
||||
|
||||
if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --json --org "$ORG_ID" --project "$PROJECT_ID" export > "$OUTPUT_FILE"
|
||||
else
|
||||
ce-ace --json --project "$PROJECT_ID" export > "$OUTPUT_FILE"
|
||||
fi
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
PATTERN_COUNT=$(jq '.playbook | to_entries | map(.value | length) | add' "$OUTPUT_FILE" 2>/dev/null || echo "unknown")
|
||||
FILE_SIZE=$(du -h "$OUTPUT_FILE" | cut -f1)
|
||||
|
||||
echo "✅ Playbook exported successfully!"
|
||||
echo " File: $OUTPUT_FILE"
|
||||
echo " Size: $FILE_SIZE"
|
||||
echo " Patterns: $PATTERN_COUNT"
|
||||
else
|
||||
echo "❌ Export failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## What Gets Exported
|
||||
|
||||
The exported JSON contains:
|
||||
|
||||
```json
|
||||
{
|
||||
"playbook": {
|
||||
"strategies_and_hard_rules": [
|
||||
{
|
||||
"id": "ctx-xxx",
|
||||
"content": "Pattern content...",
|
||||
"helpful": 5,
|
||||
"harmful": 0,
|
||||
"confidence": 1.0,
|
||||
"evidence": [...],
|
||||
"observations": 10
|
||||
}
|
||||
],
|
||||
"useful_code_snippets": [...],
|
||||
"troubleshooting_and_pitfalls": [...],
|
||||
"apis_to_use": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Backup**:
|
||||
```
|
||||
/ace:export-patterns ace-backup-2025-01-20.json
|
||||
```
|
||||
|
||||
**Cross-project sharing**:
|
||||
1. Export from project A: `/ace:export-patterns project-a-patterns.json`
|
||||
2. Import to project B: `/ace:import-patterns project-a-patterns.json`
|
||||
|
||||
**Version control** (optional):
|
||||
- Export periodically to track playbook evolution
|
||||
- Commit to git for team sharing (careful with sensitive patterns!)
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:import-patterns` - Import playbook from JSON
|
||||
- `/ace:status` - View current playbook stats
|
||||
- `/ace:clear` - Clear playbook before importing
|
||||
74
commands/ace-import-patterns.md
Normal file
74
commands/ace-import-patterns.md
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
description: Import ACE playbook from JSON file
|
||||
argument-hint: <file>
|
||||
---
|
||||
|
||||
# ACE Import Playbook
|
||||
|
||||
Import an ACE playbook from a JSON file to restore backup or share patterns across projects.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace:import-patterns <file>`, use ce-ace CLI to import the playbook:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Read context
|
||||
ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
# Try env wrapper format
|
||||
if [ -z "$ORG_ID" ] || [ -z "$PROJECT_ID" ]; then
|
||||
ORG_ID=$(jq -r '.env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
fi
|
||||
|
||||
if [ -z "$PROJECT_ID" ]; then
|
||||
echo "❌ Run /ace:configure first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Get filename from argument
|
||||
IMPORT_FILE="${1:-ace-playbook-export.json}"
|
||||
|
||||
if [ ! -f "$IMPORT_FILE" ]; then
|
||||
echo "❌ File not found: $IMPORT_FILE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validate JSON
|
||||
if ! jq empty "$IMPORT_FILE" 2>/dev/null; then
|
||||
echo "❌ Invalid JSON in $IMPORT_FILE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📥 Importing ACE playbook from $IMPORT_FILE..."
|
||||
|
||||
# Import playbook
|
||||
if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --json --org "$ORG_ID" --project "$PROJECT_ID" import --file "$IMPORT_FILE"
|
||||
else
|
||||
ce-ace --json --project "$PROJECT_ID" import --file "$IMPORT_FILE"
|
||||
fi
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ Playbook imported successfully!"
|
||||
echo " Run /ace:status to verify"
|
||||
else
|
||||
echo "❌ Import failed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:export-patterns` - Export current playbook
|
||||
- `/ace:clear` - Clear playbook before importing
|
||||
- `/ace:status` - Verify import results
|
||||
275
commands/ace-install-cli.md
Normal file
275
commands/ace-install-cli.md
Normal file
@@ -0,0 +1,275 @@
|
||||
---
|
||||
description: Install and verify ce-ace CLI tool (smart, non-noisy installation wizard)
|
||||
argument-hint:
|
||||
---
|
||||
|
||||
# ACE CLI Installation Wizard
|
||||
|
||||
This command provides a smart, interactive installation wizard for the `ce-ace` CLI tool.
|
||||
|
||||
## Behavior
|
||||
|
||||
- **Silent if already installed correctly** (no noise!)
|
||||
- **Interactive wizard** only when action needed
|
||||
- **Multi-package-manager support** (npm, pnpm, yarn)
|
||||
- **Verification** of installation + server connectivity
|
||||
- **Troubleshooting** guidance on failures
|
||||
|
||||
## Instructions for Execution
|
||||
|
||||
When the user invokes this command, follow these steps in order:
|
||||
|
||||
### Phase 1: Detection (Always Run, But Silent If OK)
|
||||
|
||||
Use the Bash tool to check current installation status. **IMPORTANT**: Break this into simple, single-purpose commands to avoid eval parse errors.
|
||||
|
||||
**Step 1.1**: Check if ce-ace command exists:
|
||||
```bash
|
||||
command -v ce-ace && echo "FOUND" || echo "NOT_INSTALLED"
|
||||
```
|
||||
|
||||
**Step 1.2**: If FOUND, get version:
|
||||
```bash
|
||||
ce-ace --version 2>/dev/null | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1
|
||||
```
|
||||
|
||||
**Handle results**:
|
||||
|
||||
- **If Step 1.1 output contains `FOUND`** and Step 1.2 returns a version:
|
||||
- Check if version >= 1.0.0
|
||||
- If yes: Show `✅ ce-ace v{VERSION} installed and working` and EXIT (silent success!)
|
||||
- If no: Show `⚠️ ce-ace v{VERSION} installed (outdated)` and ask `Would you like to upgrade? (Y/n)`
|
||||
- If yes → proceed to Phase 2 (Installation)
|
||||
- If no → EXIT
|
||||
|
||||
- **If Step 1.1 output contains `NOT_INSTALLED`**:
|
||||
- Show: `❌ ce-ace CLI not found`
|
||||
- Proceed to Phase 2 (Installation)
|
||||
|
||||
### Phase 2: Package Manager Detection
|
||||
|
||||
Use the Bash tool to detect available package managers. **IMPORTANT**: Use simple, separate commands to avoid parse errors.
|
||||
|
||||
**Step 2.1**: Check for npm:
|
||||
```bash
|
||||
command -v npm >/dev/null 2>&1 && npm --version 2>/dev/null || echo "NOT_FOUND"
|
||||
```
|
||||
|
||||
**Step 2.2**: Check for pnpm:
|
||||
```bash
|
||||
command -v pnpm >/dev/null 2>&1 && pnpm --version 2>/dev/null || echo "NOT_FOUND"
|
||||
```
|
||||
|
||||
**Step 2.3**: Check for yarn:
|
||||
```bash
|
||||
command -v yarn >/dev/null 2>&1 && yarn --version 2>/dev/null || echo "NOT_FOUND"
|
||||
```
|
||||
|
||||
**Build list of available managers** from the results above. For each manager that didn't return "NOT_FOUND", add it to a list with its version number.
|
||||
|
||||
**Handle results**:
|
||||
|
||||
- **If ALL managers returned `NOT_FOUND`**:
|
||||
- Show error message:
|
||||
```
|
||||
❌ No package managers found (npm, pnpm, or yarn required)
|
||||
|
||||
Please install Node.js and npm first:
|
||||
- macOS: brew install node
|
||||
- Linux: https://nodejs.org/en/download/package-manager
|
||||
- Windows: https://nodejs.org/en/download
|
||||
```
|
||||
- EXIT with error
|
||||
|
||||
- **If at least ONE manager was found**:
|
||||
- Display numbered list with versions (e.g., "1. npm (v11.1.0)")
|
||||
- Proceed to Phase 3 with the list of available managers
|
||||
|
||||
### Phase 3: User Selection
|
||||
|
||||
Present package manager options to the user and ask them to choose:
|
||||
|
||||
**If only one manager available** (e.g., just `npm`):
|
||||
- Auto-select that manager
|
||||
- Show: `📦 Using npm for installation`
|
||||
|
||||
**If multiple managers available**:
|
||||
- Show the numbered list from Phase 2
|
||||
- Ask: `Which package manager would you like to use? [1-{N}]:`
|
||||
- Wait for user input (number selection)
|
||||
- Validate input is a valid number
|
||||
|
||||
**Store selected manager** in a variable for Phase 4.
|
||||
|
||||
### Phase 4: Installation Command Construction
|
||||
|
||||
Based on the selected package manager, construct the installation command:
|
||||
|
||||
**npm**:
|
||||
```bash
|
||||
npm install -g @ace-sdk/cli
|
||||
```
|
||||
|
||||
**pnpm**:
|
||||
```bash
|
||||
pnpm add -g @ace-sdk/cli
|
||||
```
|
||||
|
||||
**yarn**:
|
||||
```bash
|
||||
yarn global add @ace-sdk/cli
|
||||
```
|
||||
|
||||
**Show the command to the user**:
|
||||
```
|
||||
📥 Installation command:
|
||||
{COMMAND}
|
||||
|
||||
Proceed with installation? (Y/n):
|
||||
```
|
||||
|
||||
**Wait for user confirmation**:
|
||||
- If `n` or `N` → EXIT (user cancelled)
|
||||
- If `Y`, `y`, or Enter → proceed to Phase 5
|
||||
|
||||
### Phase 5: Execute Installation
|
||||
|
||||
Use the Bash tool to run the installation command:
|
||||
|
||||
```bash
|
||||
# Run installation command (use the selected manager)
|
||||
{INSTALL_COMMAND}
|
||||
```
|
||||
|
||||
**Handle results**:
|
||||
|
||||
- **If exit code = 0** (success):
|
||||
- Show: `✅ Installation completed successfully!`
|
||||
- Proceed to Phase 6 (Verification)
|
||||
|
||||
- **If exit code != 0** (failure):
|
||||
- Show error message with common troubleshooting:
|
||||
```
|
||||
❌ Installation failed!
|
||||
|
||||
Common issues:
|
||||
|
||||
1. Permission errors:
|
||||
- Try: sudo {INSTALL_COMMAND}
|
||||
- Or use: npx @ace-sdk/cli (run without install)
|
||||
|
||||
2. Network errors:
|
||||
- Check internet connection
|
||||
- Try: npm config set registry https://registry.npmjs.org/
|
||||
|
||||
3. PATH issues:
|
||||
- After install, close and reopen terminal
|
||||
- Or add npm bin to PATH: export PATH="$(npm bin -g):$PATH"
|
||||
|
||||
Full error output:
|
||||
{ERROR_OUTPUT}
|
||||
```
|
||||
- EXIT with error
|
||||
|
||||
### Phase 6: Verify Installation
|
||||
|
||||
Use the Bash tool to verify the installation worked. **IMPORTANT**: Use simple, separate commands.
|
||||
|
||||
**Step 6.1**: Check if command exists:
|
||||
```bash
|
||||
command -v ce-ace
|
||||
```
|
||||
|
||||
**Step 6.2**: Get version (if Step 6.1 succeeded):
|
||||
```bash
|
||||
ce-ace --version
|
||||
```
|
||||
|
||||
**Step 6.3**: Get OS info:
|
||||
```bash
|
||||
uname -s
|
||||
```
|
||||
|
||||
**Process results**:
|
||||
- If Step 6.1 returns a path: ✅ ce-ace found
|
||||
- If Step 6.1 fails: ❌ Not found (PATH issue, may need to restart terminal)
|
||||
- Extract version number from Step 6.2 output
|
||||
- Check OS from Step 6.3: Linux/Darwin = supported, Windows = suggest WSL
|
||||
|
||||
**Show verification results** to the user with a summary:
|
||||
```
|
||||
🔍 Installation Verification:
|
||||
{OUTPUT_FROM_VERIFICATION}
|
||||
|
||||
🎉 All set! The ce-ace CLI tool is installed and ready to use.
|
||||
|
||||
Next steps:
|
||||
1. Run /ace:ace-configure to set up your organization and project
|
||||
2. Run /ace:ace-status to check your playbook
|
||||
3. Start using ACE for automatic pattern learning!
|
||||
```
|
||||
|
||||
### Phase 7: Optional Server Connectivity Test
|
||||
|
||||
**Ask user** if they want to test server connectivity:
|
||||
```
|
||||
Would you like to test connection to the ACE server? (Y/n):
|
||||
```
|
||||
|
||||
**If yes**, use simple Bash commands:
|
||||
|
||||
**Step 7.1**: Check if global config exists:
|
||||
```bash
|
||||
test -f ~/.config/ace/config.json && echo "CONFIG_EXISTS" || echo "NO_CONFIG"
|
||||
```
|
||||
|
||||
**Step 7.2**: If config exists, get server URL:
|
||||
```bash
|
||||
jq -r '.serverUrl // "https://ace-api.code-engine.app"' ~/.config/ace/config.json
|
||||
```
|
||||
|
||||
**Step 7.3**: Test connectivity (using URL from Step 7.2):
|
||||
```bash
|
||||
curl -s --connect-timeout 5 {SERVER_URL}/health
|
||||
```
|
||||
|
||||
**Process results**:
|
||||
- If NO_CONFIG: Show "ℹ️ No ACE configuration found - Run /ace-configure"
|
||||
- If Step 7.3 succeeds: ✅ Server connectivity OK
|
||||
- If Step 7.3 fails: ⚠️ Could not reach server (normal if not configured)
|
||||
|
||||
**Show connectivity results** and exit with success.
|
||||
|
||||
---
|
||||
|
||||
## Error Handling Guidelines
|
||||
|
||||
**Always provide actionable guidance** when errors occur:
|
||||
|
||||
1. **Permission errors**: Suggest `sudo` or `npx` alternative
|
||||
2. **Network errors**: Check internet, suggest registry config
|
||||
3. **PATH errors**: Explain how to add npm bin to PATH
|
||||
4. **Version conflicts**: Suggest uninstall old version first
|
||||
5. **OS compatibility**: Warn about Windows, recommend WSL
|
||||
|
||||
**Use clear status indicators**:
|
||||
- ✅ Success (green)
|
||||
- ⚠️ Warning (yellow)
|
||||
- ❌ Error (red)
|
||||
- ℹ️ Info (blue)
|
||||
- 🔍 Checking/verifying
|
||||
- 📦 Package manager
|
||||
- 📥 Installing
|
||||
- 🎉 Complete
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
|
||||
1. **Be non-noisy**: If already installed correctly, just show "✅ installed" and exit
|
||||
2. **Be interactive**: Ask for user confirmation before installing
|
||||
3. **Be helpful**: Provide clear troubleshooting for common issues
|
||||
4. **Be thorough**: Verify installation after completion
|
||||
5. **Be informative**: Show next steps after successful install
|
||||
|
||||
Execute these phases in order, handling each result appropriately.
|
||||
242
commands/ace-learn.md
Normal file
242
commands/ace-learn.md
Normal file
@@ -0,0 +1,242 @@
|
||||
---
|
||||
description: Capture learning from completed work interactively
|
||||
---
|
||||
|
||||
# ACE Learn
|
||||
|
||||
Manually capture patterns and lessons learned from your recent work using Claude Code's native UI.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace:learn`, follow these steps:
|
||||
|
||||
### Step 1: Gather Information with AskUserQuestion
|
||||
|
||||
Use the AskUserQuestion tool to collect learning details:
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "What task did you just complete?",
|
||||
header: "Task",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Implemented new feature",
|
||||
description: "Built new functionality or component"
|
||||
},
|
||||
{
|
||||
label: "Fixed bug or issue",
|
||||
description: "Debugged and resolved a problem"
|
||||
},
|
||||
{
|
||||
label: "Refactored code",
|
||||
description: "Improved code structure or performance"
|
||||
},
|
||||
{
|
||||
label: "Integrated API/library",
|
||||
description: "Connected external service or tool"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Then ask for task description in "Other" field or follow-up question.
|
||||
|
||||
### Step 2: Ask for Success Status
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "Was the task successful?",
|
||||
header: "Outcome",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Success",
|
||||
description: "Task completed successfully"
|
||||
},
|
||||
{
|
||||
label: "Partial success",
|
||||
description: "Completed but with issues or compromises"
|
||||
},
|
||||
{
|
||||
label: "Failed",
|
||||
description: "Task failed or was abandoned"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Ask for Lessons Learned
|
||||
|
||||
```javascript
|
||||
{
|
||||
questions: [
|
||||
{
|
||||
question: "What did you learn? (key insights, gotchas, solutions)",
|
||||
header: "Lessons",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
{
|
||||
label: "Enter lessons in 'Other' field",
|
||||
description: "Describe insights, gotchas, best practices discovered"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
User will provide detailed lessons in the "Other" text input.
|
||||
|
||||
### Step 4: Call ce-ace CLI with Flags
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Read context from .claude/settings.json
|
||||
ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
# Also try env wrapper format
|
||||
if [ -z "$ORG_ID" ] || [ -z "$PROJECT_ID" ]; then
|
||||
ORG_ID=$(jq -r '.env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
fi
|
||||
|
||||
if [ -z "$PROJECT_ID" ]; then
|
||||
echo "❌ Run /ace:configure first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📚 [ACE Learning] Capturing patterns from your work..."
|
||||
echo ""
|
||||
|
||||
# Build ce-ace command based on success status
|
||||
if [ "$SUCCESS_STATUS" = "Success" ]; then
|
||||
SUCCESS_FLAG="--success"
|
||||
elif [ "$SUCCESS_STATUS" = "Failed" ]; then
|
||||
SUCCESS_FLAG="--failure"
|
||||
else
|
||||
# Partial success - treat as success with note in output
|
||||
SUCCESS_FLAG="--success"
|
||||
LESSONS_LEARNED="Partial success: $LESSONS_LEARNED"
|
||||
fi
|
||||
|
||||
# Call ce-ace learn with flags
|
||||
if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --json --org "$ORG_ID" --project "$PROJECT_ID" \
|
||||
learn \
|
||||
--task "$TASK_DESCRIPTION" \
|
||||
$SUCCESS_FLAG \
|
||||
--output "$LESSONS_LEARNED"
|
||||
else
|
||||
# Single-org mode (no --org flag)
|
||||
ce-ace --json --project "$PROJECT_ID" \
|
||||
learn \
|
||||
--task "$TASK_DESCRIPTION" \
|
||||
$SUCCESS_FLAG \
|
||||
--output "$LESSONS_LEARNED"
|
||||
fi
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ Patterns captured successfully!"
|
||||
echo " Run /ace:status to see updated playbook"
|
||||
else
|
||||
echo "❌ Failed to capture patterns"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Implementation Notes for Claude
|
||||
|
||||
**Key Points:**
|
||||
1. **Always use AskUserQuestion** for user input (Claude Code native UI)
|
||||
2. **Map user selections** to appropriate values:
|
||||
- "Success" → `--success` flag
|
||||
- "Failed" → `--failure` flag
|
||||
- "Partial success" → `--success` with note in output
|
||||
3. **Extract task description** from user's "Other" input or category selection
|
||||
4. **Extract lessons learned** from "Other" text input
|
||||
5. **Handle both org formats**: Direct (`orgId`) and env wrapper (`env.ACE_ORG_ID`)
|
||||
|
||||
**Error Handling:**
|
||||
- Check ce-ace is installed
|
||||
- Verify project context exists
|
||||
- Provide clear error messages
|
||||
- Show success confirmation with next steps
|
||||
|
||||
## When to Use
|
||||
|
||||
✅ **Use /ace:learn after**:
|
||||
- Implementing new features
|
||||
- Debugging and fixing issues
|
||||
- Discovering edge cases or gotchas
|
||||
- Integrating APIs or libraries
|
||||
- Making architectural decisions
|
||||
- Learning something non-obvious
|
||||
|
||||
❌ **Skip for**:
|
||||
- Trivial changes
|
||||
- Simple Q&A
|
||||
- Reading/exploring code only
|
||||
- No new insights gained
|
||||
|
||||
## Example Workflow
|
||||
|
||||
```
|
||||
User: /ace:learn
|
||||
|
||||
Claude: [Shows AskUserQuestion UI]
|
||||
Question 1: What task did you just complete?
|
||||
User selects: "Fixed bug or issue"
|
||||
User types in Other: "Debugged intermittent test failures in async database operations"
|
||||
|
||||
Claude: [Shows AskUserQuestion UI]
|
||||
Question 2: Was the task successful?
|
||||
User selects: "Success"
|
||||
|
||||
Claude: [Shows AskUserQuestion UI]
|
||||
Question 3: What did you learn?
|
||||
User types in Other: "Root cause was missing await on database.close() causing connection pool exhaustion. Intermittent failures in async code often indicate missing await statements. Always check async cleanup functions."
|
||||
|
||||
Claude runs:
|
||||
ce-ace --json --org "org_xxx" --project "prj_xxx" learn \
|
||||
--task "Debugged intermittent test failures in async database operations" \
|
||||
--success \
|
||||
--output "Root cause was missing await on database.close() causing connection pool exhaustion. Intermittent failures in async code often indicate missing await statements. Always check async cleanup functions."
|
||||
|
||||
✅ Patterns captured successfully!
|
||||
Run /ace:status to see updated playbook
|
||||
```
|
||||
|
||||
## What Gets Captured
|
||||
|
||||
The learning event sent to ACE includes:
|
||||
- **Task description**: Brief summary of the work
|
||||
- **Success/failure status**: Outcome of the task
|
||||
- **Lessons learned**: Key insights, gotchas, solutions, best practices
|
||||
- **Timestamp**: When the learning was captured
|
||||
- **Project context**: Organization and project IDs
|
||||
|
||||
The ACE server's Reflector analyzes this and the Curator updates the playbook with new patterns.
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:status` - View playbook statistics
|
||||
- `/ace:patterns` - Browse learned patterns
|
||||
- `/ace:search <query>` - Find relevant patterns
|
||||
- `/ace:bootstrap` - Initialize from codebase
|
||||
114
commands/ace-patterns.md
Normal file
114
commands/ace-patterns.md
Normal file
@@ -0,0 +1,114 @@
|
||||
---
|
||||
description: View ACE playbook organized by section (strategies, snippets, troubleshooting, APIs)
|
||||
argument-hint: [section] [min-helpful]
|
||||
---
|
||||
|
||||
# ACE Playbook
|
||||
|
||||
Display the ACE playbook (4 structured sections).
|
||||
|
||||
## Usage:
|
||||
- `/ace:ace-patterns` - Show entire playbook
|
||||
- `/ace:ace-patterns strategies` - Show strategies_and_hard_rules section only
|
||||
- `/ace:ace-patterns troubleshooting 5` - Show troubleshooting bullets with ≥5 helpful count
|
||||
|
||||
## Playbook Sections
|
||||
|
||||
The ACE framework defines 4 sections:
|
||||
- `strategies_and_hard_rules` - Core strategies and rules
|
||||
- `useful_code_snippets` - Reusable code patterns
|
||||
- `troubleshooting_and_pitfalls` - Common issues and solutions
|
||||
- `apis_to_use` - API usage patterns
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Check ce-ace CLI available
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace CLI not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Get context and export as env vars (support both formats)
|
||||
export ACE_ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
export ACE_PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
if [ -z "$ACE_ORG_ID" ] || [ -z "$ACE_PROJECT_ID" ]; then
|
||||
echo "❌ Run /ace-configure first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Parse arguments
|
||||
SECTION="${1:-}" # Optional section filter
|
||||
MIN_HELPFUL="${2:-0}" # Optional min helpful score
|
||||
|
||||
# Call ce-ace patterns - CLI reads org/project from env vars automatically
|
||||
ce-ace patterns \
|
||||
${SECTION:+--section "$SECTION"} \
|
||||
--min-helpful "$MIN_HELPFUL"
|
||||
```
|
||||
|
||||
Arguments:
|
||||
- section: Optional section filter (strategies, snippets, troubleshooting, apis)
|
||||
- min_helpful: Optional minimum helpful count (default: 0)
|
||||
|
||||
Examples:
|
||||
- All sections: /ace-patterns
|
||||
- Single section: /ace-patterns strategies
|
||||
- High-value patterns: /ace-patterns troubleshooting 5
|
||||
```
|
||||
|
||||
The tool returns a nested JSON structure (v3.8.0+):
|
||||
|
||||
```json
|
||||
{
|
||||
"playbook": {
|
||||
"strategies_and_hard_rules": [...],
|
||||
"useful_code_snippets": [...],
|
||||
"troubleshooting_and_pitfalls": [...],
|
||||
"apis_to_use": [...]
|
||||
},
|
||||
"metadata": {
|
||||
"tokens_in_response": 30000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Access sections via**: `response.playbook.strategies_and_hard_rules`, `response.playbook.useful_code_snippets`, etc.
|
||||
|
||||
Each bullet shows:
|
||||
- **ID**: ctx-{timestamp}-{random}
|
||||
- **Helpful/Harmful**: ✅ 5 | ❌ 0
|
||||
- **Confidence**: 100%
|
||||
- **Content**: The learned insight
|
||||
- **Evidence**: File paths, errors, line numbers
|
||||
- **Metadata** (v3.8.0+): Token count when include_metadata=true
|
||||
|
||||
## How Bullets Are Created
|
||||
|
||||
ACE learns from **execution feedback**:
|
||||
|
||||
**Successful task** → adds to `strategies_and_hard_rules` or `useful_code_snippets`
|
||||
**Failed task** → adds to `troubleshooting_and_pitfalls`
|
||||
**API usage** → adds to `apis_to_use`
|
||||
|
||||
Bullets accumulate helpful/harmful counts over time as they prove useful or misleading.
|
||||
|
||||
## Next Steps
|
||||
|
||||
**After viewing patterns:**
|
||||
|
||||
- **See full statistics:** Run `/ace:ace-status` for counts and top helpful/harmful
|
||||
- **Filter patterns:** Use section parameter (e.g., `/ace:ace-patterns strategies`)
|
||||
- **Filter by quality:** Use min-helpful parameter (e.g., `/ace:ace-patterns troubleshooting 5`)
|
||||
- **Export patterns:** Run `/ace:ace-export-patterns` for backup or sharing
|
||||
- **Bootstrap more patterns:** Run `/ace:ace-bootstrap` to analyze git/docs/code
|
||||
- **Clear bad patterns:** Run `/ace:ace-clear --confirm` to reset playbook
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:ace-status` - View playbook statistics
|
||||
- `/ace:ace-bootstrap` - Add patterns from git/docs/code
|
||||
- `/ace:ace-export-patterns` - Backup playbook to JSON
|
||||
- `/ace:ace-clear` - Clear playbook (reset)
|
||||
147
commands/ace-search.md
Normal file
147
commands/ace-search.md
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
description: Semantic search for ACE patterns using natural language query
|
||||
---
|
||||
|
||||
# ACE Semantic Search
|
||||
|
||||
Search for relevant patterns using natural language query instead of retrieving all patterns.
|
||||
|
||||
## What This Does
|
||||
|
||||
Uses semantic search to find only the most relevant patterns matching your query, reducing context usage by 50-80%.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace-search <query>`, use the Bash tool to call ce-ace CLI:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Check ce-ace is available
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace CLI not found in PATH"
|
||||
echo ""
|
||||
echo "Installation:"
|
||||
echo " npm install -g @ace-sdk/cli"
|
||||
echo ""
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Get context from .claude/settings.json and export as env vars
|
||||
export ACE_ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
export ACE_PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
if [ -z "$ACE_ORG_ID" ] || [ -z "$ACE_PROJECT_ID" ]; then
|
||||
echo "❌ No .claude/settings.json found or missing orgId/projectId"
|
||||
echo "Run /ace-configure to set up ACE"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Call ce-ace search - CLI reads org/project from env vars automatically
|
||||
# Threshold comes from server config (ce-ace tune show) - don't override!
|
||||
ce-ace search "$*"
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
- **query** (required): Natural language description passed as command argument
|
||||
- Examples: "authentication patterns", "async debugging tips", "database connection pooling best practices"
|
||||
- **--threshold**: Similarity threshold (optional, overrides server config)
|
||||
- Default: Uses server config from `ce-ace tune show`
|
||||
- Range: 0.0 - 1.0 (higher = stricter matching)
|
||||
- Only specify if you want to override project's default
|
||||
- **--json**: Return JSON format for programmatic use
|
||||
|
||||
**Note**: To limit number of results, use `jq` for filtering:
|
||||
```bash
|
||||
ce-ace search "query" --json | jq '.patterns[:5]' # First 5 results
|
||||
```
|
||||
The `--limit` flag is not supported by ce-ace CLI. Use `--top-k` via server config (`/ace-tune`) instead.
|
||||
|
||||
### Example Usage
|
||||
|
||||
```bash
|
||||
/ace-search JWT authentication best practices
|
||||
→ Calls: ce-ace search "JWT authentication best practices"
|
||||
→ Uses: Server config threshold (e.g., 0.45)
|
||||
|
||||
/ace-search async test failures debugging
|
||||
→ Calls: ce-ace search "async test failures debugging"
|
||||
|
||||
# Override threshold if needed:
|
||||
/ace-search "JWT auth" --threshold 0.7
|
||||
→ Calls: ce-ace search "JWT auth" --threshold 0.7
|
||||
```
|
||||
|
||||
### When to Use This
|
||||
|
||||
✅ **Use `/ace-search` when**:
|
||||
- You have a specific implementation question
|
||||
- You're debugging a specific type of problem
|
||||
- You know what domain/topic you need help with
|
||||
- You want to minimize context usage
|
||||
|
||||
❌ **Don't use when**:
|
||||
- You need comprehensive architectural overview
|
||||
- You're working on multi-domain tasks
|
||||
- You want to see all patterns in a section
|
||||
|
||||
For those cases, use `/ace-patterns` instead.
|
||||
|
||||
## Output Format
|
||||
|
||||
The tool returns JSON with matching patterns and metadata (v3.8.0+):
|
||||
|
||||
```json
|
||||
{
|
||||
"patterns": [
|
||||
{
|
||||
"content": "Pattern description with context",
|
||||
"helpful": 8,
|
||||
"harmful": 0,
|
||||
"confidence": 0.92,
|
||||
"section": "strategies_and_hard_rules",
|
||||
"similarity": 0.87
|
||||
}
|
||||
],
|
||||
"query": "your search query",
|
||||
"count": 10,
|
||||
"metadata": {
|
||||
"tokens_in_response": 2400,
|
||||
"tokens_saved_vs_full_playbook": 27600,
|
||||
"efficiency_gain": "92%",
|
||||
"full_playbook_size": 30000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Patterns are sorted by semantic similarity to your query.
|
||||
|
||||
**Metadata field** (v3.8.0+): Provides token efficiency metrics. Omitted if `include_metadata=false`.
|
||||
|
||||
## Performance Impact
|
||||
|
||||
**Before** (full playbook):
|
||||
- Retrieves: ALL patterns in section
|
||||
- Token usage: ~10,000-15,000 tokens (measured via metadata)
|
||||
- Time: 100-300ms
|
||||
|
||||
**After** (semantic search with metadata):
|
||||
- Retrieves: Top 10 relevant patterns only
|
||||
- Token usage: ~2,400 tokens (confirmed via metadata)
|
||||
- Time: 150-400ms
|
||||
- **50-92% token reduction** (exact savings shown in metadata.efficiency_gain)
|
||||
|
||||
**After** (semantic search without metadata):
|
||||
- Token usage: ~2,000-2,200 tokens
|
||||
- Time: 140-390ms (~10ms faster)
|
||||
- **85-92% token reduction**
|
||||
|
||||
**Metadata overhead**: Adds ~5-10ms response time + ~200-400 tokens for efficiency metrics
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace-top` - Get highest-rated patterns by helpful score
|
||||
- `/ace-patterns` - View full playbook (comprehensive)
|
||||
- `/ace-status` - Check playbook statistics
|
||||
155
commands/ace-status.md
Normal file
155
commands/ace-status.md
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
description: Show ACE playbook statistics and learning status
|
||||
argument-hint:
|
||||
---
|
||||
|
||||
# ACE Status
|
||||
|
||||
Display comprehensive statistics about your ACE playbook.
|
||||
|
||||
Call ce-ace CLI to get current statistics:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Check ce-ace CLI is installed
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for jq (required for JSON formatting)
|
||||
if ! command -v jq >/dev/null 2>&1; then
|
||||
echo "❌ jq not found - Install: brew install jq (macOS) or apt-get install jq (Linux)"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Optional: Export environment variables if available from .claude/settings.json
|
||||
# ce-ace will use these if provided, otherwise fallback to global config
|
||||
export ACE_ORG_ID="${ACE_ORG_ID:-}"
|
||||
export ACE_PROJECT_ID="${ACE_PROJECT_ID:-}"
|
||||
|
||||
# Run ce-ace status and capture output
|
||||
STATUS_OUTPUT=$(ce-ace status --json 2>&1)
|
||||
EXIT_CODE=$?
|
||||
|
||||
# Check if command succeeded
|
||||
if [ $EXIT_CODE -ne 0 ]; then
|
||||
echo "❌ Failed to get ACE status"
|
||||
echo ""
|
||||
echo "Error details:"
|
||||
echo "$STATUS_OUTPUT"
|
||||
echo ""
|
||||
echo "Common fixes:"
|
||||
echo " 1. Run: /ace-configure to setup configuration"
|
||||
echo " 2. Verify global config exists: cat ~/.config/ace/config.json"
|
||||
echo " 3. Check API token is valid at: https://ace.code-engine.app/settings"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Verify we got valid JSON
|
||||
if ! echo "$STATUS_OUTPUT" | jq empty 2>/dev/null; then
|
||||
echo "❌ Invalid response from ce-ace (not valid JSON)"
|
||||
echo ""
|
||||
echo "Response:"
|
||||
echo "$STATUS_OUTPUT"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Format output for readability
|
||||
echo "$STATUS_OUTPUT" | jq -r '
|
||||
"📊 ACE Playbook Status",
|
||||
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━",
|
||||
"Organization: \(.org_id // "Not configured")",
|
||||
"Project: \(.project_id // "Not configured")",
|
||||
"",
|
||||
"📚 Total Patterns: \(.total_bullets // 0)",
|
||||
"",
|
||||
"By Section:",
|
||||
" • Strategies & Rules: \(.by_section.strategies_and_hard_rules // 0)",
|
||||
" • Code Snippets: \(.by_section.useful_code_snippets // 0)",
|
||||
" • Troubleshooting: \(.by_section.troubleshooting_and_pitfalls // 0)",
|
||||
" • APIs to Use: \(.by_section.apis_to_use // 0)",
|
||||
"",
|
||||
"📈 Average Confidence: \((.avg_confidence // 0) * 100 | floor)%"
|
||||
'
|
||||
```
|
||||
|
||||
## What You'll See
|
||||
|
||||
**Playbook Summary**:
|
||||
- Total bullets across all sections
|
||||
- Bullets by section (strategies, snippets, troubleshooting, APIs)
|
||||
- Average confidence score
|
||||
|
||||
**Top Helpful Bullets**:
|
||||
- 5 most helpful bullets (highest ✅ counts)
|
||||
- Shows which patterns are most valuable
|
||||
|
||||
**Top Harmful Bullets**:
|
||||
- 5 most harmful bullets (highest ❌ counts)
|
||||
- Shows which patterns are misleading
|
||||
|
||||
## Example Output
|
||||
|
||||
```json
|
||||
{
|
||||
"total_bullets": 42,
|
||||
"by_section": {
|
||||
"strategies_and_hard_rules": 10,
|
||||
"useful_code_snippets": 15,
|
||||
"troubleshooting_and_pitfalls": 12,
|
||||
"apis_to_use": 5
|
||||
},
|
||||
"avg_confidence": 0.78,
|
||||
"top_helpful": [
|
||||
{
|
||||
"id": "ctx-1737387600-a1b2c",
|
||||
"section": "strategies_and_hard_rules",
|
||||
"content": "Always verify npm package names...",
|
||||
"helpful": 12,
|
||||
"harmful": 0,
|
||||
"confidence": 1.0
|
||||
},
|
||||
...
|
||||
],
|
||||
"top_harmful": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## How to Interpret
|
||||
|
||||
**High helpful count** → Pattern proven useful across multiple tasks
|
||||
**High harmful count** → Pattern caused errors, needs revision
|
||||
**High confidence** → helpful/(helpful+harmful) ratio is strong
|
||||
**Low confidence** → Pattern unreliable, may be pruned at 0.30 threshold
|
||||
|
||||
## Storage
|
||||
|
||||
ACE v3.0 stores playbooks in:
|
||||
- **Remote**: ACE Storage Server (FastAPI + ChromaDB)
|
||||
- **Project-specific**: Isolated by project ID
|
||||
- **Multi-tenant**: Your org's patterns are private
|
||||
|
||||
## Next Steps
|
||||
|
||||
**After checking status:**
|
||||
|
||||
- **If playbook is empty (0 bullets):**
|
||||
- Run `/ace:bootstrap` to populate initial patterns from git/docs/code
|
||||
- Or start coding - ACE will learn automatically!
|
||||
|
||||
- **If not configured yet:**
|
||||
- Run `/ace:configure` to set up ACE server connection
|
||||
|
||||
- **If ACE not initialized in project:**
|
||||
- Run `/ace:claude-init` to add ACE instructions to CLAUDE.md
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:configure` - Configure ACE server connection
|
||||
- `/ace:claude-init` - Initialize ACE in project
|
||||
- `/ace:bootstrap` - Bootstrap playbook from git/docs/code
|
||||
- `/ace:patterns` - View learned patterns
|
||||
- `/ace:clear` - Clear playbook and start fresh
|
||||
417
commands/ace-test.md
Normal file
417
commands/ace-test.md
Normal file
@@ -0,0 +1,417 @@
|
||||
---
|
||||
description: Verify ACE plugin is properly configured and operational
|
||||
argument-hint:
|
||||
---
|
||||
|
||||
# ACE Test
|
||||
|
||||
Verify that the ACE plugin is properly configured and operational with ce-ace CLI.
|
||||
|
||||
## What This Command Does
|
||||
|
||||
1. **Checks if ce-ace CLI is installed**
|
||||
- Verifies `ce-ace` command is available
|
||||
- Shows installed version
|
||||
|
||||
2. **Tests ACE server connectivity**
|
||||
- Runs `ce-ace doctor` diagnostics
|
||||
- Shows connection status
|
||||
|
||||
3. **Verifies hooks configuration**
|
||||
- Checks if hook wrapper scripts exist
|
||||
- Confirms hooks.json is properly configured
|
||||
|
||||
4. **Provides diagnostic information**
|
||||
- Helpful for troubleshooting
|
||||
- Confirms plugin setup is correct
|
||||
|
||||
## How to Use
|
||||
|
||||
Simply run:
|
||||
```
|
||||
/ace-test
|
||||
```
|
||||
|
||||
## Verification Steps
|
||||
|
||||
### Step 1: Check CLI Installation
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
echo "🔍 ACE Plugin Test"
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo ""
|
||||
|
||||
# Test 1: CLI Installation
|
||||
echo "[1/4] Checking ce-ace CLI installation..."
|
||||
if command -v ce-ace >/dev/null 2>&1; then
|
||||
VERSION=$(ce-ace --version 2>&1 | head -1)
|
||||
echo "✅ ce-ace CLI found: $VERSION"
|
||||
else
|
||||
echo "❌ ce-ace CLI not found"
|
||||
echo " Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
echo ""
|
||||
```
|
||||
|
||||
### Step 2: Test ACE Server Connectivity
|
||||
|
||||
```bash
|
||||
# Test 2: Server Connectivity
|
||||
echo "[2/4] Testing ACE server connectivity..."
|
||||
|
||||
export ACE_ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
export ACE_PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
# Try env wrapper format if not found
|
||||
if [ -z "$ACE_ORG_ID" ] || [ -z "$ACE_PROJECT_ID" ]; then
|
||||
export ACE_ORG_ID=$(jq -r '.env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
export ACE_PROJECT_ID=$(jq -r '.env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
fi
|
||||
|
||||
if [ -z "$ACE_PROJECT_ID" ]; then
|
||||
echo "❌ No project configured"
|
||||
echo " Run: /ace:ace-configure"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Run doctor command - CLI reads org/project from env vars automatically
|
||||
DOCTOR_RESULT=$(ce-ace doctor --json 2>&1)
|
||||
|
||||
# Parse results
|
||||
PASSED=$(echo "$DOCTOR_RESULT" | jq -r '.summary.passed // 0')
|
||||
FAILED=$(echo "$DOCTOR_RESULT" | jq -r '.summary.failed // 0')
|
||||
|
||||
if [ "$FAILED" -eq 0 ]; then
|
||||
echo "✅ Server connectivity: $PASSED/$((PASSED + FAILED)) checks passed"
|
||||
else
|
||||
echo "⚠️ Server connectivity: $FAILED checks failed"
|
||||
echo "$DOCTOR_RESULT" | jq -r '.results[] | select(.status != "pass") | " - \(.check): \(.message)"'
|
||||
fi
|
||||
echo ""
|
||||
```
|
||||
|
||||
### Step 3: Verify Hooks Configuration
|
||||
|
||||
```bash
|
||||
# Test 3: Hooks Configuration
|
||||
echo "[3/4] Checking hooks configuration..."
|
||||
|
||||
PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace"
|
||||
|
||||
# Check hook wrappers
|
||||
HOOKS_FOUND=0
|
||||
if [ -f "$PLUGIN_DIR/scripts/ace_before_task_wrapper.sh" ]; then
|
||||
HOOKS_FOUND=$((HOOKS_FOUND + 1))
|
||||
fi
|
||||
if [ -f "$PLUGIN_DIR/scripts/ace_after_task_wrapper.sh" ]; then
|
||||
HOOKS_FOUND=$((HOOKS_FOUND + 1))
|
||||
fi
|
||||
|
||||
if [ "$HOOKS_FOUND" -eq 2 ]; then
|
||||
echo "✅ Hook wrappers: 2/2 found"
|
||||
else
|
||||
echo "⚠️ Hook wrappers: $HOOKS_FOUND/2 found"
|
||||
fi
|
||||
|
||||
# Check hooks.json
|
||||
if [ -f "$PLUGIN_DIR/hooks/hooks.json" ]; then
|
||||
HOOK_COUNT=$(jq -r '.hooks | length' "$PLUGIN_DIR/hooks/hooks.json")
|
||||
echo "✅ hooks.json: $HOOK_COUNT hooks registered"
|
||||
else
|
||||
echo "❌ hooks.json not found"
|
||||
fi
|
||||
echo ""
|
||||
```
|
||||
|
||||
### Step 4: Test Basic ACE Operations
|
||||
|
||||
```bash
|
||||
# Test 4: Basic Operations
|
||||
echo "[4/4] Testing basic ACE operations..."
|
||||
|
||||
# Test status command - CLI reads org/project from env vars automatically
|
||||
STATUS_RESULT=$(ce-ace status --json 2>&1)
|
||||
|
||||
TOTAL_BULLETS=$(echo "$STATUS_RESULT" | jq -r '.total_bullets // 0')
|
||||
echo "✅ Status command: Playbook has $TOTAL_BULLETS patterns"
|
||||
|
||||
echo ""
|
||||
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
|
||||
echo "✅ All tests passed!"
|
||||
echo ""
|
||||
echo "Next steps:"
|
||||
echo " - Bootstrap playbook: /ace:ace-bootstrap"
|
||||
echo " - Search patterns: /ace:ace-search <query>"
|
||||
echo " - Capture learning: /ace:ace-learn"
|
||||
```
|
||||
|
||||
**Error Handling**:
|
||||
|
||||
1. **CLI Not Found**
|
||||
```
|
||||
❌ ce-ace CLI not found
|
||||
→ Install: npm install -g @ace-sdk/cli
|
||||
```
|
||||
|
||||
2. **Server Connection Failed**
|
||||
```
|
||||
⚠️ Server connectivity: checks failed
|
||||
→ Run: /ace:ace-doctor for detailed diagnostics
|
||||
→ Or: /ace:ace-configure to reconfigure
|
||||
```
|
||||
|
||||
2. **Timeout**
|
||||
```
|
||||
Error: Request timeout
|
||||
→ Network issues or server overloaded
|
||||
→ Action: Retry with exponential backoff
|
||||
→ Fallback: Check ~/.config/ace/config.json for correct serverUrl
|
||||
```
|
||||
|
||||
3. **Authentication Failed**
|
||||
```
|
||||
Error: 401 Unauthorized
|
||||
→ Invalid or missing API token
|
||||
→ Action: Run /ace:ace-configure to set up credentials
|
||||
→ Fallback: Check ~/.config/ace/config.json for valid apiToken
|
||||
```
|
||||
|
||||
4. **Invalid Project**
|
||||
```
|
||||
Error: 404 Project not found
|
||||
→ Project ID doesn't exist
|
||||
→ Action: Verify projectId in .claude/settings.json
|
||||
→ Fallback: Create new project or use existing one
|
||||
```
|
||||
|
||||
5. **Server Error**
|
||||
```
|
||||
Error: 500 Internal Server Error
|
||||
→ ACE server malfunction
|
||||
→ Action: Check server logs
|
||||
→ Fallback: Restart ACE server
|
||||
```
|
||||
|
||||
6. **Malformed Response**
|
||||
```
|
||||
Error: Invalid JSON response
|
||||
→ Server returned unexpected format
|
||||
→ Action: Log raw response for debugging
|
||||
→ Fallback: Check server version compatibility
|
||||
```
|
||||
|
||||
7. **Missing Configuration**
|
||||
```
|
||||
Error: Config file not found
|
||||
→ ~/.config/ace/config.json or .claude/settings.json missing
|
||||
→ Action: Run /ace:ace-configure to create config files
|
||||
→ Fallback: Provide default configuration template
|
||||
```
|
||||
|
||||
## Available ACE Commands
|
||||
|
||||
All ACE operations use ce-ace CLI:
|
||||
|
||||
**Core Commands**:
|
||||
- `ce-ace status` - Get playbook statistics
|
||||
- `ce-ace patterns` - View playbook patterns
|
||||
- `ce-ace search --stdin` - Search for patterns
|
||||
- `ce-ace learn` - Capture learning (via /ace:ace-learn)
|
||||
- `ce-ace bootstrap` - Initialize from codebase
|
||||
- `ce-ace clear` - Clear playbook
|
||||
- `ce-ace export` - Export playbook to JSON
|
||||
- `ce-ace import` - Import playbook from JSON
|
||||
- `ce-ace top` - Get top-rated patterns
|
||||
- `ce-ace doctor` - Run diagnostics
|
||||
- `ce-ace config` - Manage configuration
|
||||
|
||||
**Error Handling**:
|
||||
|
||||
1. **CLI Not Found**
|
||||
```
|
||||
Error: ce-ace command not found
|
||||
→ ce-ace CLI not installed
|
||||
→ Action: npm install -g @ace-sdk/cli
|
||||
→ Fallback: Check npm global bin is in PATH
|
||||
```
|
||||
|
||||
2. **Tool Execution Failed**
|
||||
```
|
||||
Error: Tool execution error
|
||||
→ Tool exists but fails on invocation
|
||||
→ Action: Check tool parameters and server logs
|
||||
→ Fallback: Try with minimal parameters or default values
|
||||
```
|
||||
|
||||
3. **Partial Setup**
|
||||
```
|
||||
Warning: Some ACE components missing
|
||||
→ Incomplete plugin installation
|
||||
→ Action: Check hook wrappers and scripts exist
|
||||
→ Fallback: Reinstall plugin from marketplace
|
||||
```
|
||||
|
||||
### Step 4: Show Configuration Summary
|
||||
|
||||
Display the current ACE configuration:
|
||||
- Server URL (from `~/.config/ace/config.json` or environment)
|
||||
- Project ID (from `.claude/settings.json`)
|
||||
- API token status (present/missing, don't show actual token)
|
||||
- Plugin version
|
||||
- Learning mode (automatic/manual)
|
||||
|
||||
**Error Handling**:
|
||||
|
||||
1. **Configuration File Read Error**
|
||||
```
|
||||
Error: Cannot read ~/.config/ace/config.json or .claude/settings.json
|
||||
→ Permission denied or file corrupted
|
||||
→ Action: Check file permissions (global config should be 600)
|
||||
→ Fallback: Recreate config with /ace:ace-configure
|
||||
```
|
||||
|
||||
2. **Invalid JSON in Config**
|
||||
```
|
||||
Error: Malformed configuration file
|
||||
→ JSON parse error
|
||||
→ Action: Show line/column of error
|
||||
→ Fallback: Backup corrupted file, create new config
|
||||
```
|
||||
|
||||
3. **Missing Required Fields**
|
||||
```
|
||||
Warning: Configuration incomplete
|
||||
→ serverUrl, apiToken, or projectId missing
|
||||
→ Action: List missing fields
|
||||
→ Fallback: Run /ace:ace-configure to complete setup
|
||||
```
|
||||
|
||||
4. **Invalid URL Format**
|
||||
```
|
||||
Error: Invalid serverUrl format
|
||||
→ URL doesn't match expected pattern
|
||||
→ Action: Suggest correct format (e.g., https://ace-api.code-engine.app)
|
||||
→ Fallback: Provide default URL options
|
||||
```
|
||||
|
||||
## Example Success Output
|
||||
|
||||
```
|
||||
✅ ACE Agent Skill Status
|
||||
|
||||
Agent Skill: ace:ace-learning
|
||||
Status: ✅ LOADED
|
||||
Description: Learn from execution feedback and update ACE playbook
|
||||
|
||||
ACE Server Connection:
|
||||
Status: ✅ CONNECTED
|
||||
Server: https://ace-api.code-engine.app
|
||||
Project ID: prj_xxxxx
|
||||
|
||||
Playbook Statistics:
|
||||
Total Bullets: 42
|
||||
- Strategies & Rules: 10
|
||||
- Code Snippets: 15
|
||||
- Troubleshooting: 12
|
||||
- API Patterns: 5
|
||||
Average Confidence: 78%
|
||||
|
||||
Available ACE Tools:
|
||||
✅ ace_learn - Core learning function
|
||||
✅ ace_status - Get playbook stats
|
||||
✅ ace_get_playbook - View playbook
|
||||
✅ ace_clear - Clear playbook
|
||||
✅ ace_init - Initialize from git
|
||||
✅ ace_save_config - Save configuration
|
||||
|
||||
Configuration:
|
||||
Learning Mode: Automatic (hook-based)
|
||||
Plugin Version: 5.0.0
|
||||
Config Files:
|
||||
- Global: ~/.config/ace/config.json (serverUrl, apiToken, cacheTtl)
|
||||
- Project: .claude/settings.json (projectId, orgId)
|
||||
|
||||
🎯 Everything looks good! ACE automatic learning is ready.
|
||||
```
|
||||
|
||||
## Example Failure Output
|
||||
|
||||
```
|
||||
❌ ACE Agent Skill Status
|
||||
|
||||
Agent Skill: ace:ace-learning
|
||||
Status: ❌ NOT FOUND
|
||||
|
||||
The ACE Agent Skill is not loaded. Possible causes:
|
||||
1. Plugin not installed in ~/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace/
|
||||
2. Skill file missing or misconfigured
|
||||
3. Claude Code plugin system not initialized
|
||||
|
||||
Troubleshooting Steps:
|
||||
1. Check plugin installation: ls ~/.claude/plugins/marketplaces/ce-dot-net-marketplace/plugins/ace/
|
||||
2. Verify skill configuration in plugin.json
|
||||
3. Restart Claude Code CLI
|
||||
4. Check Claude Code logs for plugin loading errors
|
||||
```
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: ACE Server Connection Failed
|
||||
**Symptom**: ce-ace commands return connection error or authentication failed
|
||||
**Solution**:
|
||||
1. Run `/ace:ace-configure` to set up connection
|
||||
2. Verify server URL in `~/.config/ace/config.json` is correct
|
||||
3. Check API token is valid (not expired)
|
||||
4. Verify server is running and accessible
|
||||
5. Check network connectivity
|
||||
|
||||
### Issue: No Bullets in Playbook
|
||||
**Symptom**: ace_status shows 0 total bullets
|
||||
**Solution**: This is normal for new installations. Bullets accumulate as you work:
|
||||
- Complete substantial tasks (coding, debugging, API integration)
|
||||
- Agent Skill will automatically trigger
|
||||
- Patterns will be learned and stored
|
||||
|
||||
### Issue: Agent Skill Present but Not Triggering
|
||||
**Symptom**: Skill exists but never invokes automatically
|
||||
**Solution**:
|
||||
1. Ensure you're doing substantial work (not simple Q&A)
|
||||
2. Check skill description matches task type
|
||||
3. Verify automatic invocation is enabled
|
||||
4. Manual test: Use `Skill(ace:ace-learning)` after completing work
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace:ace-status` - View playbook statistics
|
||||
- `/ace:ace-patterns` - View learned patterns
|
||||
- `/ace:ace-configure` - Configure ACE server connection
|
||||
- `/ace:ace-bootstrap` - Initialize playbook from codebase
|
||||
|
||||
## Technical Details
|
||||
|
||||
**Agent Skill Trigger Conditions**:
|
||||
The skill automatically triggers after:
|
||||
- Problem-solving & debugging
|
||||
- Code implementation & refactoring
|
||||
- API & tool integration
|
||||
- Learning from failures
|
||||
- Substantial multi-step tasks
|
||||
|
||||
**Not triggered for**:
|
||||
- Simple Q&A responses
|
||||
- Basic file reads
|
||||
- Trivial informational queries
|
||||
|
||||
**Learning Pipeline**:
|
||||
```
|
||||
Work Completed → Agent Skill Triggers → ace_learn Called →
|
||||
Reflector Analyzes → Curator Creates Updates → Playbook Updated
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Note**: This is a diagnostic command. It doesn't modify your playbook or configuration.
|
||||
179
commands/ace-top.md
Normal file
179
commands/ace-top.md
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
description: Get highest-rated ACE patterns by helpful score
|
||||
---
|
||||
|
||||
# ACE Top Patterns
|
||||
|
||||
Retrieve proven patterns with the highest helpful scores - battle-tested patterns that have proven successful.
|
||||
|
||||
## What This Does
|
||||
|
||||
Returns patterns sorted by helpful score (upvotes from successful usage), giving you quality-first retrieval instead of quantity.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace-top [section] [limit]`, use ce-ace CLI:
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
if ! command -v ce-ace >/dev/null 2>&1; then
|
||||
echo "❌ ce-ace not found - Install: npm install -g @ace-sdk/cli"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Read context
|
||||
ORG_ID=$(jq -r '.orgId // .env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.projectId // .env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
|
||||
# Try env wrapper format
|
||||
if [ -z "$ORG_ID" ] || [ -z "$PROJECT_ID" ]; then
|
||||
ORG_ID=$(jq -r '.env.ACE_ORG_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
PROJECT_ID=$(jq -r '.env.ACE_PROJECT_ID // empty' .claude/settings.json 2>/dev/null || echo "")
|
||||
fi
|
||||
|
||||
if [ -z "$PROJECT_ID" ]; then
|
||||
echo "❌ Run /ace:configure first"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Parse arguments
|
||||
SECTION="${1:-}"
|
||||
LIMIT="${2:-10}"
|
||||
MIN_HELPFUL="${3:-0}"
|
||||
|
||||
# Build command
|
||||
CMD_ARGS=""
|
||||
if [ -n "$SECTION" ]; then
|
||||
CMD_ARGS="$CMD_ARGS --section $SECTION"
|
||||
fi
|
||||
CMD_ARGS="$CMD_ARGS --limit $LIMIT --min-helpful $MIN_HELPFUL"
|
||||
|
||||
echo "🏆 Fetching top-rated patterns..."
|
||||
|
||||
# Execute command
|
||||
if [ -n "$ORG_ID" ]; then
|
||||
ce-ace --org "$ORG_ID" --project "$PROJECT_ID" top $CMD_ARGS
|
||||
else
|
||||
ce-ace --project "$PROJECT_ID" top $CMD_ARGS
|
||||
fi
|
||||
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✅ Retrieved top patterns"
|
||||
else
|
||||
echo "❌ Failed to retrieve patterns"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Parameters
|
||||
|
||||
- **section** (optional): Filter to specific playbook section
|
||||
- Values: `strategies_and_hard_rules`, `useful_code_snippets`, `troubleshooting_and_pitfalls`, `apis_to_use`
|
||||
- Default: All sections
|
||||
- **limit** (optional): Maximum patterns to return
|
||||
- Default: 10
|
||||
- **min_helpful** (optional): Minimum helpful score threshold
|
||||
- Default: 0
|
||||
- Use `5` for only highly-rated patterns
|
||||
|
||||
### Example Usage
|
||||
|
||||
```bash
|
||||
/ace-top
|
||||
→ Returns top 10 patterns across all sections
|
||||
|
||||
/ace-top strategies_and_hard_rules
|
||||
→ Returns top 10 architectural patterns/principles
|
||||
|
||||
/ace-top troubleshooting_and_pitfalls 5
|
||||
→ Returns top 5 troubleshooting patterns
|
||||
|
||||
/ace-top apis_to_use 20 3
|
||||
→ Returns top 20 API recommendations with helpful >= 3
|
||||
```
|
||||
|
||||
### When to Use This
|
||||
|
||||
✅ **Use `/ace-top` when**:
|
||||
- You want proven, high-quality patterns
|
||||
- You're asking for "best practices"
|
||||
- You need patterns that have been validated through use
|
||||
- You want quick access to most valuable knowledge
|
||||
|
||||
❌ **Don't use when**:
|
||||
- You have a specific query (use `/ace-search` instead)
|
||||
- You need comprehensive coverage (use `/ace-patterns` instead)
|
||||
- You're looking for something specific (semantic search is better)
|
||||
|
||||
## Output Format
|
||||
|
||||
The tool returns JSON with top-rated patterns:
|
||||
|
||||
```json
|
||||
{
|
||||
"patterns": [
|
||||
{
|
||||
"content": "Always use refresh token rotation to prevent theft attacks",
|
||||
"helpful": 12,
|
||||
"harmful": 0,
|
||||
"confidence": 0.95,
|
||||
"section": "strategies_and_hard_rules",
|
||||
"observations": 15,
|
||||
"evidence": [
|
||||
"Prevented auth bypass in 3 projects",
|
||||
"Industry standard per OWASP recommendations"
|
||||
]
|
||||
}
|
||||
],
|
||||
"section": "strategies_and_hard_rules",
|
||||
"count": 10,
|
||||
"min_helpful": 5
|
||||
}
|
||||
```
|
||||
|
||||
Patterns are sorted by helpful score (descending).
|
||||
|
||||
## Helpful Score Interpretation
|
||||
|
||||
- **0-2**: New pattern, not yet validated
|
||||
- **3-5**: Moderately proven, used successfully a few times
|
||||
- **6-10**: Well-proven, reliable pattern
|
||||
- **11+**: Highly validated, cornerstone pattern
|
||||
|
||||
Patterns with `harmful > 0` indicate they've had negative feedback and should be used cautiously.
|
||||
|
||||
## Performance Impact
|
||||
|
||||
Similar to semantic search - retrieves only top patterns instead of full playbook:
|
||||
|
||||
- Token usage: ~2,000-4,000 tokens (vs ~15,000 for full)
|
||||
- **60-75% token reduction**
|
||||
- Fast retrieval with quality guarantee
|
||||
|
||||
## Use Cases
|
||||
|
||||
**Architecture questions**:
|
||||
```
|
||||
/ace-top strategies_and_hard_rules 10
|
||||
→ "What are the best architectural patterns we've learned?"
|
||||
```
|
||||
|
||||
**Debugging help**:
|
||||
```
|
||||
/ace-top troubleshooting_and_pitfalls 5
|
||||
→ "What are the most common issues we've encountered?"
|
||||
```
|
||||
|
||||
**Library selection**:
|
||||
```
|
||||
/ace-top apis_to_use 10 5
|
||||
→ "What libraries have we had success with?"
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace-search` - Semantic search for specific queries
|
||||
- `/ace-patterns` - View full playbook
|
||||
- `/ace-status` - Check playbook statistics
|
||||
406
commands/ace-tune.md
Normal file
406
commands/ace-tune.md
Normal file
@@ -0,0 +1,406 @@
|
||||
---
|
||||
description: View and update ACE project configuration dynamically at runtime
|
||||
---
|
||||
|
||||
# ACE Configuration Management (Project-Level)
|
||||
|
||||
Manage ACE configuration for **THIS PROJECT ONLY**. Adjust thresholds, enable token budget, and configure runtime behavior dynamically.
|
||||
|
||||
## 🚨 Important: Project-Level Scope
|
||||
|
||||
**All `/ace-tune` commands affect THIS PROJECT ONLY.**
|
||||
|
||||
- Changes apply to the current project
|
||||
- Other projects in your organization are NOT affected
|
||||
- Organization-wide settings are managed via web dashboard
|
||||
|
||||
**Hierarchical Configuration:**
|
||||
- **Server defaults** (global baseline)
|
||||
- **Organization-level** (per org) ← Set via web dashboard
|
||||
- **Project-level** (per project) ← `/ace-tune` scope
|
||||
|
||||
**Priority**: `Project > Org > Server` (project overrides org overrides server)
|
||||
|
||||
**For organization-wide configuration**, use the web dashboard instead.
|
||||
|
||||
## What This Does
|
||||
|
||||
Allows you to **fetch and update ACE project configuration** in real-time:
|
||||
- View current effective configuration (with source hierarchy)
|
||||
- Enable/disable token budget enforcement for this project
|
||||
- Adjust semantic search sensitivity
|
||||
- Configure deduplication thresholds
|
||||
- Control automatic learning features
|
||||
- Reset project config to org/server defaults
|
||||
|
||||
**All changes persist on the server** for this specific project.
|
||||
|
||||
## Instructions for Claude
|
||||
|
||||
When the user runs `/ace-tune [action] [params]`, execute the tune script:
|
||||
|
||||
### 1. View Current Configuration
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
# Get plugin root directory
|
||||
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"
|
||||
|
||||
# Execute tune script - shows current config
|
||||
exec "${PLUGIN_ROOT}/scripts/ace-tune.sh" show
|
||||
```
|
||||
|
||||
**Display format:**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ ACE Configuration (Project: {project_name}) │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ dedup_similarity_threshold: 0.85 (from org) │
|
||||
│ constitution_threshold: 0.7 (from server) │
|
||||
│ pruning_threshold: 0.3 (from server) │
|
||||
│ token_budget_enforcement: false (from server) │
|
||||
│ max_playbook_tokens: null (from server) │
|
||||
│ max_batch_size: 50 (from server) │
|
||||
│ auto_learning_enabled: true (from server) │
|
||||
│ reflector_enabled: true (from server) │
|
||||
│ curator_enabled: true (from server) │
|
||||
│ dedup_enabled: true (from server) │
|
||||
│ │
|
||||
│ 💡 Config source: project < org < server │
|
||||
│ To change org defaults, use web dashboard. │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Returns current effective settings including:**
|
||||
- `constitution_threshold` - Semantic search threshold (default: 0.7)
|
||||
- `dedup_similarity_threshold` - Duplicate detection threshold (default: 0.85)
|
||||
- `pruning_threshold` - Low-quality pattern removal (default: 0.3)
|
||||
- `token_budget_enforcement` - Auto-pruning enabled/disabled (default: false)
|
||||
- `max_playbook_tokens` - Token limit before pruning (default: null)
|
||||
- `max_batch_size` - Max patterns per batch request (default: 50)
|
||||
|
||||
### 2. Interactive Mode (Recommended)
|
||||
|
||||
When user runs `/ace-tune` without arguments, use AskUserQuestion tool for interactive configuration:
|
||||
|
||||
```python
|
||||
# Step 1: Show current config first
|
||||
ce-ace tune show
|
||||
|
||||
# Step 2: Ask what they want to change
|
||||
AskUserQuestion({
|
||||
"questions": [{
|
||||
"question": "What would you like to configure?",
|
||||
"header": "ACE Setting",
|
||||
"multiSelect": false,
|
||||
"options": [
|
||||
{
|
||||
"label": "Search Threshold",
|
||||
"description": "Adjust similarity threshold for pattern retrieval (0.0-1.0)"
|
||||
},
|
||||
{
|
||||
"label": "Search Top K",
|
||||
"description": "Maximum patterns returned per search (1-100)"
|
||||
},
|
||||
{
|
||||
"label": "Token Budget",
|
||||
"description": "Enable automatic playbook pruning at token limit"
|
||||
},
|
||||
{
|
||||
"label": "View Only",
|
||||
"description": "Just show current configuration"
|
||||
}
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
# Step 3: Based on selection, ask for value
|
||||
# Example: If "Search Threshold" selected
|
||||
AskUserQuestion({
|
||||
"questions": [{
|
||||
"question": "What threshold value? (0.0-1.0)",
|
||||
"header": "Threshold",
|
||||
"multiSelect": false,
|
||||
"options": [
|
||||
{"label": "0.35", "description": "Broad matches (more results)"},
|
||||
{"label": "0.45", "description": "Balanced (recommended)"},
|
||||
{"label": "0.60", "description": "Strict matches (fewer results)"},
|
||||
{"label": "0.75", "description": "Very strict (only close matches)"}
|
||||
]
|
||||
}]
|
||||
})
|
||||
|
||||
# Step 4: Apply with CLI
|
||||
ce-ace tune --constitution-threshold 0.45
|
||||
```
|
||||
|
||||
### 3. Non-Interactive Mode (Direct)
|
||||
|
||||
```bash
|
||||
# Single setting
|
||||
ce-ace tune --constitution-threshold 0.6
|
||||
|
||||
# Multiple settings
|
||||
ce-ace tune \
|
||||
--constitution-threshold 0.5 \
|
||||
--search-top-k 15 \
|
||||
--dedup-enabled true
|
||||
```
|
||||
|
||||
**What this does**:
|
||||
- Enables automatic playbook pruning FOR THIS PROJECT
|
||||
- When playbook exceeds 50,000 tokens:
|
||||
- Server removes low-quality patterns (helpful-harmful < pruning_threshold)
|
||||
- Keeps high-quality patterns
|
||||
- Maintains playbook size within budget
|
||||
|
||||
### 3. Direct CLI Examples
|
||||
|
||||
**Adjust Search Threshold**:
|
||||
```bash
|
||||
# Lower threshold for broader matches
|
||||
ce-ace tune --constitution-threshold 0.35
|
||||
|
||||
# Higher threshold for stricter matches
|
||||
ce-ace tune --constitution-threshold 0.8
|
||||
```
|
||||
|
||||
**Effect on `/ace-search`**:
|
||||
- **Lower (0.3-0.5)**: Broader matches, more results
|
||||
- **Medium (0.6-0.7)**: Balanced precision/recall
|
||||
- **Higher (0.8-0.9)**: Stricter matches, fewer but more precise results
|
||||
|
||||
**Adjust Multiple Settings**:
|
||||
```bash
|
||||
# Configure search behavior
|
||||
ce-ace tune \
|
||||
--constitution-threshold 0.5 \
|
||||
--search-top-k 15
|
||||
|
||||
# Configure deduplication
|
||||
ce-ace tune --dedup-similarity-threshold 0.9
|
||||
|
||||
# Configure pruning
|
||||
ce-ace tune --pruning-threshold 0.4
|
||||
|
||||
# Enable token budget
|
||||
ce-ace tune --token-budget-enforcement true --max-playbook-tokens 50000
|
||||
```
|
||||
|
||||
**Reset to Defaults**:
|
||||
```bash
|
||||
# Reset project to org/server defaults
|
||||
ce-ace tune --reset
|
||||
|
||||
# Verify reset
|
||||
ce-ace tune show
|
||||
```
|
||||
|
||||
## Configuration Options Reference
|
||||
|
||||
| Parameter | Type | Default | Range | Description |
|
||||
|-----------|------|---------|-------|-------------|
|
||||
| `constitution_threshold` | float | 0.7 | 0.0-1.0 | Semantic search similarity threshold |
|
||||
| `dedup_similarity_threshold` | float | 0.85 | 0.0-1.0 | Duplicate detection threshold |
|
||||
| `pruning_threshold` | float | 0.3 | 0.0-1.0 | Min quality score to keep pattern |
|
||||
| `token_budget_enforcement` | bool | false | - | Enable automatic pruning |
|
||||
| `max_playbook_tokens` | int\|null | null | >0 | Token limit for auto-pruning |
|
||||
| `max_batch_size` | int | 50 | 1-100 | Max patterns per batch request |
|
||||
| `auto_learning_enabled` | bool | true | - | Enable automatic learning |
|
||||
| `reflector_enabled` | bool | true | - | Enable Reflector (Sonnet 4) |
|
||||
| `curator_enabled` | bool | true | - | Enable Curator (Haiku 4.5) |
|
||||
| `dedup_enabled` | bool | true | - | Enable deduplication |
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### Optimize for Precision (Strict Search)
|
||||
|
||||
```bash
|
||||
/ace-tune search-threshold 0.85
|
||||
```
|
||||
**Use when**: You want only highly relevant results for this project, willing to miss some edge cases.
|
||||
|
||||
### Optimize for Recall (Broad Search)
|
||||
|
||||
```bash
|
||||
/ace-tune search-threshold 0.4
|
||||
```
|
||||
**Use when**: You want comprehensive results for this project, okay with some less-relevant matches.
|
||||
|
||||
### Enable Automatic Playbook Management
|
||||
|
||||
```bash
|
||||
/ace-tune token-budget 50000
|
||||
```
|
||||
**Use when**: This project's playbook is growing large (10k+ patterns) and you want automatic quality-based pruning.
|
||||
|
||||
### Aggressive Deduplication
|
||||
|
||||
```bash
|
||||
/ace-tune dedup-threshold 0.75
|
||||
```
|
||||
**Use when**: This project is getting too many similar patterns and you want more aggressive merging.
|
||||
|
||||
### Conservative Pruning
|
||||
|
||||
```bash
|
||||
/ace-tune pruning-threshold 0.2
|
||||
```
|
||||
**Use when**: Token budget is enabled for this project but you want to keep more patterns (only remove clearly harmful ones).
|
||||
|
||||
### Reset to Organization Defaults
|
||||
|
||||
```bash
|
||||
/ace-tune reset
|
||||
```
|
||||
**Use when**: You want to remove project-specific customizations and inherit org/server defaults.
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Interactive Mode (Recommended for Exploration)
|
||||
|
||||
```
|
||||
User: "/ace-tune"
|
||||
Claude: [Shows current config via ce-ace tune show]
|
||||
Claude: [Uses AskUserQuestion with options: Search Threshold, Search Top K, Token Budget, View Only]
|
||||
User: Selects "Search Threshold"
|
||||
Claude: [Uses AskUserQuestion with threshold options: 0.35, 0.45, 0.60, 0.75]
|
||||
User: Selects "0.45"
|
||||
Claude: [Runs ce-ace tune --constitution-threshold 0.45]
|
||||
Claude: "✅ Search threshold updated to 0.45 for this project"
|
||||
```
|
||||
|
||||
### Non-Interactive Mode (Fast Direct Changes)
|
||||
|
||||
```bash
|
||||
# 1. Check current settings
|
||||
ce-ace tune show
|
||||
|
||||
# 2. Adjust search for broader matches
|
||||
ce-ace tune --constitution-threshold 0.35
|
||||
|
||||
# 3. Increase max results
|
||||
ce-ace tune --search-top-k 15
|
||||
|
||||
# 4. Enable token budget
|
||||
ce-ace tune --token-budget-enforcement true --max-playbook-tokens 50000
|
||||
|
||||
# 5. Verify changes
|
||||
ce-ace tune show
|
||||
|
||||
# 6. Later, reset to org/server defaults
|
||||
ce-ace tune --reset
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### ce-ace tune show
|
||||
|
||||
```
|
||||
🎛️ ACE Configuration
|
||||
|
||||
ℹ Project: prj_d3a244129d62c198
|
||||
ℹ Organization: org_34fYIlitYk4nyFuTvtsAzA6uUJF
|
||||
|
||||
ℹ Search/Retrieval:
|
||||
ℹ Constitution Threshold: 0.45 (similarity)
|
||||
ℹ Search Top K: 10 (max results)
|
||||
|
||||
ℹ Deduplication:
|
||||
ℹ Enabled: true
|
||||
ℹ Similarity Threshold: 0.85
|
||||
|
||||
ℹ Token Budget:
|
||||
ℹ Enforcement: false
|
||||
ℹ Max Playbook Tokens: (not set)
|
||||
ℹ Pruning Threshold: 0.3
|
||||
|
||||
ℹ Batch Processing:
|
||||
ℹ Max Batch Size: 50
|
||||
|
||||
ℹ Learning Pipeline:
|
||||
ℹ Auto Learning: true
|
||||
ℹ Reflector (Sonnet 4): true
|
||||
ℹ Curator (Haiku 4.5): true
|
||||
```
|
||||
|
||||
### ce-ace tune --constitution-threshold 0.5
|
||||
|
||||
```
|
||||
✅ Configuration updated successfully
|
||||
|
||||
🎛️ ACE Configuration
|
||||
|
||||
ℹ Project: prj_d3a244129d62c198
|
||||
ℹ Organization: org_34fYIlitYk4nyFuTvtsAzA6uUJF
|
||||
|
||||
ℹ Search/Retrieval:
|
||||
ℹ Constitution Threshold: 0.5 (similarity) ← Updated
|
||||
ℹ Search Top K: 10 (max results)
|
||||
...
|
||||
```
|
||||
|
||||
### ce-ace tune --reset
|
||||
|
||||
```
|
||||
✅ Configuration reset successfully
|
||||
|
||||
All project-level overrides removed.
|
||||
Project now inherits organization and server defaults.
|
||||
|
||||
Run 'ce-ace tune show' to see current effective config.
|
||||
```
|
||||
|
||||
## Important Notes
|
||||
|
||||
### Project-Scoped Configuration
|
||||
|
||||
- All `/ace-tune` changes affect **THIS PROJECT ONLY**
|
||||
- Changes persist on the server and sync across sessions
|
||||
- Other projects maintain their own independent configurations
|
||||
- Organization-level defaults can be set via web dashboard
|
||||
|
||||
### Environment Context
|
||||
|
||||
The `ce-ace` CLI automatically reads context from:
|
||||
1. `ACE_ORG_ID` environment variable (passed by slash command)
|
||||
2. `ACE_PROJECT_ID` environment variable (passed by slash command)
|
||||
3. `~/.config/ace/config.json` for API token
|
||||
|
||||
You don't need to manually specify these - the slash command handles it.
|
||||
|
||||
### Multi-Tenant Safety
|
||||
|
||||
- Each project maintains independent configuration
|
||||
- Configuration hierarchy: Project > Organization > Server
|
||||
- Project overrides take precedence over org defaults
|
||||
- Organization-wide settings require web dashboard access
|
||||
|
||||
## Performance Notes
|
||||
|
||||
- Configuration changes are **immediate** (no restart required)
|
||||
- Changes **persist across sessions** (stored on server)
|
||||
- Configuration is fetched fresh on each command (no stale cache issues)
|
||||
- Hierarchical config resolved server-side (project → org → server)
|
||||
- Average response time: 200-500ms for show, 300-600ms for updates
|
||||
|
||||
## See Also
|
||||
|
||||
- `/ace-search` - Semantic search (uses `constitution_threshold`)
|
||||
- `/ace-status` - View playbook statistics
|
||||
- `/ace-patterns` - View full playbook
|
||||
- `/ace-top` - Get highest-rated patterns
|
||||
- `/ace-configure` - Initial project setup
|
||||
|
||||
## Web Dashboard
|
||||
|
||||
For organization-wide configuration management:
|
||||
**https://ace-dashboard.code-engine.app/org/{org_id}/settings**
|
||||
|
||||
Use the web dashboard to:
|
||||
- Set organization-wide defaults
|
||||
- Manage multiple projects
|
||||
- View organization-level analytics
|
||||
- Configure team permissions
|
||||
Reference in New Issue
Block a user