From d03c46038c7e99126d1cdfa361afe98efdb6070c Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:08:19 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 + README.md | 3 + commands/ace-bootstrap.md | 426 +++++++++++++++++++ commands/ace-claude-init.md | 359 ++++++++++++++++ commands/ace-clear.md | 87 ++++ commands/ace-configure.md | 593 +++++++++++++++++++++++++++ commands/ace-delta.md | 272 +++++++++++++ commands/ace-doctor.md | 634 +++++++++++++++++++++++++++++ commands/ace-enable-auto-update.md | 258 ++++++++++++ commands/ace-export-patterns.md | 106 +++++ commands/ace-import-patterns.md | 74 ++++ commands/ace-install-cli.md | 275 +++++++++++++ commands/ace-learn.md | 242 +++++++++++ commands/ace-patterns.md | 114 ++++++ commands/ace-search.md | 147 +++++++ commands/ace-status.md | 155 +++++++ commands/ace-test.md | 417 +++++++++++++++++++ commands/ace-top.md | 179 ++++++++ commands/ace-tune.md | 406 ++++++++++++++++++ hooks/hooks.json | 76 ++++ plugin.lock.json | 113 +++++ 21 files changed, 4951 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 commands/ace-bootstrap.md create mode 100644 commands/ace-claude-init.md create mode 100644 commands/ace-clear.md create mode 100644 commands/ace-configure.md create mode 100644 commands/ace-delta.md create mode 100644 commands/ace-doctor.md create mode 100644 commands/ace-enable-auto-update.md create mode 100644 commands/ace-export-patterns.md create mode 100644 commands/ace-import-patterns.md create mode 100644 commands/ace-install-cli.md create mode 100644 commands/ace-learn.md create mode 100644 commands/ace-patterns.md create mode 100644 commands/ace-search.md create mode 100644 commands/ace-status.md create mode 100644 commands/ace-test.md create mode 100644 commands/ace-top.md create mode 100644 commands/ace-tune.md create mode 100644 hooks/hooks.json create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..c0c1328 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "ace", + "description": "Code Engine ACE - Intelligent pattern learning with hooks-based architecture. v5.2.4: Fix empty learning stats header display. Requires ce-ace >= v3.0.0.", + "version": "5.2.4", + "author": { + "name": "ACE Team", + "email": "ace@ce-dot-net.com" + }, + "commands": [ + "./commands" + ], + "hooks": [ + "./hooks" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..15611e9 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# ace + +Code Engine ACE - Intelligent pattern learning with hooks-based architecture. v5.2.4: Fix empty learning stats header display. Requires ce-ace >= v3.0.0. diff --git a/commands/ace-bootstrap.md b/commands/ace-bootstrap.md new file mode 100644 index 0000000..6dbc642 --- /dev/null +++ b/commands/ace-bootstrap.md @@ -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 ` - 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 ` - 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 to repository (default: current directory) +- `--max-files ` - Maximum files to analyze (overrides thoroughness) +- `--commit-limit ` - Max commits to analyze (overrides thoroughness) +- `--days-back ` - 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 diff --git a/commands/ace-claude-init.md b/commands/ace-claude-init.md new file mode 100644 index 0000000..c36ff97 --- /dev/null +++ b/commands/ace-claude-init.md @@ -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:** `` and `` + - 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 diff --git a/commands/ace-clear.md b/commands/ace-clear.md new file mode 100644 index 0000000..e77db05 --- /dev/null +++ b/commands/ace-clear.md @@ -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 diff --git a/commands/ace-configure.md b/commands/ace-configure.md new file mode 100644 index 0000000..b49e2e3 --- /dev/null +++ b/commands/ace-configure.md @@ -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" < "$PROJECT_CONFIG" </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 diff --git a/commands/ace-delta.md b/commands/ace-delta.md new file mode 100644 index 0000000..7e4d33a --- /dev/null +++ b/commands/ace-delta.md @@ -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 diff --git a/commands/ace-doctor.md b/commands/ace-doctor.md new file mode 100644 index 0000000..a3bebb5 --- /dev/null +++ b/commands/ace-doctor.md @@ -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 diff --git a/commands/ace-enable-auto-update.md b/commands/ace-enable-auto-update.md new file mode 100644 index 0000000..5392842 --- /dev/null +++ b/commands/ace-enable-auto-update.md @@ -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) diff --git a/commands/ace-export-patterns.md b/commands/ace-export-patterns.md new file mode 100644 index 0000000..fb77c52 --- /dev/null +++ b/commands/ace-export-patterns.md @@ -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 diff --git a/commands/ace-import-patterns.md b/commands/ace-import-patterns.md new file mode 100644 index 0000000..280a785 --- /dev/null +++ b/commands/ace-import-patterns.md @@ -0,0 +1,74 @@ +--- +description: Import ACE playbook from JSON file +argument-hint: +--- + +# 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 `, 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 diff --git a/commands/ace-install-cli.md b/commands/ace-install-cli.md new file mode 100644 index 0000000..f9013db --- /dev/null +++ b/commands/ace-install-cli.md @@ -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. diff --git a/commands/ace-learn.md b/commands/ace-learn.md new file mode 100644 index 0000000..546eb15 --- /dev/null +++ b/commands/ace-learn.md @@ -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 ` - Find relevant patterns +- `/ace:bootstrap` - Initialize from codebase diff --git a/commands/ace-patterns.md b/commands/ace-patterns.md new file mode 100644 index 0000000..9dcd56d --- /dev/null +++ b/commands/ace-patterns.md @@ -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) diff --git a/commands/ace-search.md b/commands/ace-search.md new file mode 100644 index 0000000..119b631 --- /dev/null +++ b/commands/ace-search.md @@ -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 `, 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 diff --git a/commands/ace-status.md b/commands/ace-status.md new file mode 100644 index 0000000..c018923 --- /dev/null +++ b/commands/ace-status.md @@ -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 diff --git a/commands/ace-test.md b/commands/ace-test.md new file mode 100644 index 0000000..e498c26 --- /dev/null +++ b/commands/ace-test.md @@ -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 " +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. diff --git a/commands/ace-top.md b/commands/ace-top.md new file mode 100644 index 0000000..7dcf30c --- /dev/null +++ b/commands/ace-top.md @@ -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 diff --git a/commands/ace-tune.md b/commands/ace-tune.md new file mode 100644 index 0000000..00e98a5 --- /dev/null +++ b/commands/ace-tune.md @@ -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 diff --git a/hooks/hooks.json b/hooks/hooks.json new file mode 100644 index 0000000..caf66fa --- /dev/null +++ b/hooks/hooks.json @@ -0,0 +1,76 @@ +{ + "hooks": { + "SessionStart": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/ace_install_cli.sh", + "timeout": 30000 + } + ] + } + ], + "UserPromptSubmit": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/ace_before_task_wrapper.sh", + "timeout": 15000 + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/ace_posttooluse_wrapper.sh --log", + "timeout": 130000 + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/ace_permission_request_wrapper.sh", + "timeout": 5000 + } + ] + } + ], + "Stop": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/ace_stop_wrapper.sh --log --chat", + "timeout": 130000 + } + ] + } + ], + "SubagentStop": [ + { + "matcher": "", + "hooks": [ + { + "type": "command", + "command": "${CLAUDE_PLUGIN_ROOT}/scripts/ace_subagent_stop_wrapper.sh --log --chat --notify", + "timeout": 130000 + } + ] + } + ] + } +} diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..b6da6ec --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,113 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:ce-dot-net/ce-claude-marketplace:plugins/ace", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "ac70602a50f474172f1f08b03a1862e3be6d44af", + "treeHash": "ba5e05d83ee570131bceb4522e993326eb6da2b57aa51cdfceba5c47816511d8", + "generatedAt": "2025-11-28T10:14:57.524133Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "ace", + "description": "Code Engine ACE - Intelligent pattern learning with hooks-based architecture. v5.2.4: Fix empty learning stats header display. Requires ce-ace >= v3.0.0.", + "version": "5.2.4" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "75c75637e58d0215468ea60fa14dab2786b539dbd0ea3a2c8328670c7a2714cb" + }, + { + "path": "hooks/hooks.json", + "sha256": "551611819d25fb0b10ee40585d6a042d777325e07c3847a659ab59c0672a679a" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "6e503ffda0a34fef51733ee65b3332df704574564ab56524df146de9041a4a63" + }, + { + "path": "commands/ace-top.md", + "sha256": "769dc165126f2d24de178ebec66f7751fe4557228fe2c4fec970c4a51e63427f" + }, + { + "path": "commands/ace-clear.md", + "sha256": "a0e905272d1f3bae5387fd1d3f00d9f5e55632c131bbfc863d3b3a198490343f" + }, + { + "path": "commands/ace-install-cli.md", + "sha256": "eac27f22b0cae197227fef1eb96352017e85d8549cdf8196519cd4c44854986f" + }, + { + "path": "commands/ace-claude-init.md", + "sha256": "ba56a77c4f27fd0e0b6a2fae70fba497d205f3075e62c1a8890ae6f4f97526b0" + }, + { + "path": "commands/ace-tune.md", + "sha256": "ac5e0c41ab3df7c69d9f8128a2d21a8f352136ee546b6551974c45e267f39ccc" + }, + { + "path": "commands/ace-export-patterns.md", + "sha256": "f42718573dfc578f760926099c20f81ebfc29e5cfa34c542fadd933a7da20d03" + }, + { + "path": "commands/ace-import-patterns.md", + "sha256": "7d4373c681c5ee95e13a33fa3d456c983adf4d6860b3451390c59b88fbd9680a" + }, + { + "path": "commands/ace-learn.md", + "sha256": "8f2fef38997909f925039a14a67014106a20330d74d746d838ef571de48209ec" + }, + { + "path": "commands/ace-delta.md", + "sha256": "9d2e821ebefa71e7120ed162ba1a819e0565130adece264d32b5b37302243915" + }, + { + "path": "commands/ace-doctor.md", + "sha256": "05f3cbae08acebf44dad9293ffd2291473bfbd767e77924f62f814c8dfd8a194" + }, + { + "path": "commands/ace-test.md", + "sha256": "02fc5363bae5a8d2502e450ad13de16e38042c588c9c021e80caec709968bcf4" + }, + { + "path": "commands/ace-status.md", + "sha256": "c3d81827976d5aeb2f1cd3ce010e4e2db12f2fe32ead60950e597b82e422fbcc" + }, + { + "path": "commands/ace-bootstrap.md", + "sha256": "ddd3137d8ff94aef2935d32c19bf2a2bec6bb20732ce7ee2aaf134ef26de160c" + }, + { + "path": "commands/ace-patterns.md", + "sha256": "9038984d78ff69c8a535af49e720afecb53a12e468600a9344f6d44aabaf3d29" + }, + { + "path": "commands/ace-enable-auto-update.md", + "sha256": "024c9595e5b1e4f4a773dd884ff0793fb3d97014e2ee5e0a5cecd3ce7a264167" + }, + { + "path": "commands/ace-search.md", + "sha256": "1ae2f5b70ce1447ae5b25a12637e1a0c4919498b55e3106051139c02f15de429" + }, + { + "path": "commands/ace-configure.md", + "sha256": "d74b4b4dd42aedcc9241c5dcb855b07c8a5ba615d4e9e33468da0e6a9bf7825f" + } + ], + "dirSha256": "ba5e05d83ee570131bceb4522e993326eb6da2b57aa51cdfceba5c47816511d8" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file