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:

   ${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:

   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:

# ACE Orchestration Plugin - Automatic Learning Cycle

If this header already exists:

1. Detect existing version by searching for version pattern in project CLAUDE.md:

   • Optimized: Check line 93 specifically: ## 🔄 Complete Automatic Learning Cycle (v3.2.36)
   • Extract version using pattern: v([0-9]+\.[0-9]+\.[0-9]+)
   • Fallback: Search entire file if not found on line 93

2. Read plugin version from the plugin CLAUDE.md file:

   • Optimized: Check line 93 of plugin template (same location)
   • Fallback: Search entire plugin file if structure differs

3. Compare versions:

   If versions match (up-to-date):

   • Tell the user ACE is already initialized with current version
   • Show them where it's located in CLAUDE.md
   • Exit successfully (no changes needed)

   If project version is older than plugin version:

   • Tell the user ACE content is outdated
   • Show current version vs. plugin version
   • Ask if they want to update: "Your project has ACE v{old}, but plugin is v{new}. Would you like to update? (y/n)"
   • If user says yes → proceed to Step 3a (Update existing ACE content)
   • If user says no → exit successfully

Step 3a: Update Existing ACE Content (Only if outdated)

If user confirmed they want to update outdated ACE content:

1. Find ACE section boundaries in project CLAUDE.md:

   • Check for HTML markers first: <!-- ACE_SECTION_START --> and <!-- ACE_SECTION_END -->
   • If markers present: Use them for exact boundaries (fast, accurate)
   • If markers absent: Use header-based detection:
     • Start: Line with # ACE Orchestration Plugin - Automatic Learning Cycle
     • End: Next # header at the same level (pattern: ^# [^#]) OR end of file

2. Extract non-ACE content:

   • Content BEFORE the ACE section (if any)
   • Content AFTER the ACE section (if any)

3. Replace ACE section:

   • Remove old ACE section completely
   • Insert new plugin CLAUDE.md content at same location
   • Preserve all other content (before and after)

4. Write updated file:

   • Reconstruct: [content before] + [new ACE content] + [content after]
   • Save to project CLAUDE.md

5. Confirm update:

   • Tell user ACE updated from vX.X.X → vY.Y.Y
   • Show what's new in the update
   • Proceed to Step 5 (Confirm Success)

Step 4: Copy ACE Instructions Inline

If ACE content is NOT present:

If CLAUDE.md exists:

• Append to the END of the file (preserve all existing content)
• Add two blank lines first for spacing
• Copy the FULL content of the plugin CLAUDE.md file inline
• DO NOT use @ reference syntax
• The content should start with: # ACE Orchestration Plugin - Automatic Learning Cycle

If CLAUDE.md doesn't exist:

• Create it with the full ACE plugin CLAUDE.md content
• Copy all ~344 lines of content from the plugin file (includes MANDATORY section + trajectory format fix)

Step 5: Confirm Success

After adding:

• Read the updated CLAUDE.md to verify
• Show the user a confirmation message
• Confirm ACE instructions are now available inline
• Explain what this enables (automatic learning cycle)

What Gets Added

The full ACE plugin CLAUDE.md content (~344 lines) is copied inline, which contains:

• 🚨 MANDATORY: ACE Skill Usage Rules (v3.2.8+) - Explicit, non-negotiable skill invocation instructions
• 🔄 Complete automatic learning cycle explanation
• 🤖 How skills work (retrieval before tasks, learning after tasks)
• 🎯 When to trigger ACE features (implement, debug, refactor, etc.)
• 📊 Architecture overview (Generator → Reflector → Curator → Playbook)
• 🔧 Slash commands reference for manual control
• 📁 Playbook structure (4 sections: strategies, snippets, troubleshooting, APIs)

Why This is Needed

Problem: Skills are model-invoked and load instructions ONLY when triggered. This means:

• ❌ Claude doesn't know about the ACE cycle until a skill activates
• ❌ No standing context about when to use ACE features
• ❌ Missing architecture overview

Solution: Copying ACE instructions inline into project CLAUDE.md provides:

• ✅ Always-on context about the ACE system
• ✅ Clear trigger words for skills (implement, debug, refactor)
• ✅ Complete understanding of the automatic learning cycle
• ✅ Complementary to skills (general context + specific tools)
• ✅ Full content always available (no reference dependency)

When to Use

✅ Required For:

• Full ACE cycle - Retrieval + Learning working together
• Optimal skill triggering - Claude knows when to invoke skills
• Architecture awareness - Claude understands the system

⚠️ One-Time Setup (With Version Updates):

• Run once per project for initial setup
• Safe to run multiple times (checks for existing content)
• Auto-detects version - offers to update if outdated
• Run again after plugin updates to get new features
• No manual editing needed

After Running

Once initialized, every Claude session will have:

1. ✅ Your project-specific instructions (existing CLAUDE.md content)
2. ✅ ACE plugin instructions (copied inline, ~344 lines with MANDATORY section + trajectory format fix)
3. ✅ Skills available for automatic invocation
4. ✅ Explicit skill invocation rules (YOU MUST use skills for qualifying tasks)

Test it:

• Try a coding task: "Implement JWT authentication"
• Watch for ACE Playbook Retrieval skill to auto-invoke
• Complete the task and watch ACE Learning skill capture feedback

Complementary Commands

• /ace:ace-configure - Set up ACE server connection (REQUIRED FIRST!)
• /ace:ace-status - Check playbook statistics
• /ace:ace-bootstrap - Bootstrap playbook from git history (optional)
• /ace:ace-patterns - View learned patterns

Example Workflow

# 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