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:

#!/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
    ↓
ace-cli
    ↓
ACE Server: Reflector analyzes code
    ↓
ace-cli: returns results
    ↓
Command: calls ace-cli 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 ace-cli bootstrap to initialize your playbook from the codebase.

Basic usage:

# CLI reads org/project from environment variables or config automatically
ace-cli bootstrap --json

With options:

# Hybrid mode (recommended) - docs → git → files
ace-cli bootstrap --json --mode hybrid --thoroughness deep

# Git history only
ace-cli bootstrap --json --mode git-history --commit-limit 1000 --days-back 180

# Local files only
ace-cli bootstrap --json --mode local-files --max-files 5000

# Docs only
ace-cli bootstrap --json --mode docs-only

Parameters:

--mode <mode> - Analysis mode (default: "hybrid")
- hybrid: RECOMMENDED - Intelligently scan docs → git history → local files
- both: Analyze current files + git history (no docs)
- local-files: Current codebase files only
- git-history: Git commit history only
- docs-only: Documentation files only (*.md, *.txt)
--thoroughness <level> - Analysis depth (default: "medium")
- light: max_files=1000, commit_limit=100, days_back=30
- medium: max_files=5000, commit_limit=500, days_back=90
- deep: max_files=unlimited, commit_limit=1000, days_back=180
--repo-path <path> - Path to repository (default: current directory)
--max-files <number> - Maximum files to analyze (overrides thoroughness)
--commit-limit <number> - Max commits to analyze (overrides thoroughness)
--days-back <number> - Days of history to analyze (overrides thoroughness)
--merge - Merge with existing playbook (default: true)

Examples:

# 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:

Check existing documentation - Scans for CLAUDE.md, README.md, ARCHITECTURE.md, docs/*.md
Analyze git history - Extracts patterns from commits (if git repository exists)
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:

{
  "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)

{ "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

{ "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

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

Playbook Retrieval Skill: Before tasks (auto-invokes when trigger keywords detected)
Playbook Learning Skill: After tasks (auto-invokes after substantial work)
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:

Verify patterns loaded:
- Run /ace:status to see playbook statistics
- Should show bullets distributed across 4 sections
Review learned patterns:
- Run /ace:patterns to view what was discovered
- Check strategies, snippets, troubleshooting, and API patterns
Start coding:
- ACE will now retrieve these patterns before tasks
- Automatic learning will add new patterns as you work
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)

/ace-bootstrap