ace-experience 0.1.0

package/ace/references/git-integration.md

@@ -0,0 +1,254 @@
+<overview>
+Git integration for ACE framework.
+</overview>
+
+<core_principle>
+
+**Commit outcomes, not process.**
+
+The git log should read like a changelog of what shipped, not a diary of planning activity.
+</core_principle>
+
+<commit_points>
+
+| Event                   | Commit? | Why                                              |
+| ----------------------- | ------- | ------------------------------------------------ |
+| BRIEF + TRACK created   | YES     | Project initialization                           |
+| run.md created          | NO      | Intermediate - commit with run completion        |
+| RESEARCH.md created     | NO      | Intermediate                                     |
+| research.md created        | NO      | Intermediate                                     |
+| **Task completed**      | YES     | Atomic unit of work (1 commit per task)         |
+| **Run completed**       | YES     | Metadata commit (RECAP + PULSE + TRACK)         |
+| Handoff created         | YES     | WIP state preserved                              |
+
+</commit_points>
+
+<git_check>
+
+```bash
+[ -d .git ] && echo "GIT_EXISTS" || echo "NO_GIT"
+```
+
+If NO_GIT: Run `git init` silently. ACE projects always get their own repo.
+</git_check>
+
+<commit_formats>
+
+<format name="initialization">
+## Project Initialization (brief + track together)
+
+```
+docs: initialize [project-name] ([N] stages)
+
+[One-liner from brief.md]
+
+Stages:
+1. [stage-name]: [goal]
+2. [stage-name]: [goal]
+3. [stage-name]: [goal]
+```
+
+What to commit:
+
+```bash
+git add .ace/
+git commit
+```
+
+</format>
+
+<format name="task-completion">
+## Task Completion (During Run Execution)
+
+Each task gets its own commit immediately after completion.
+
+```
+{type}({stage}.{run}): {task-name}
+
+- [Key change 1]
+- [Key change 2]
+- [Key change 3]
+```
+
+**Commit types:**
+- `feat` - New feature/functionality
+- `fix` - Bug fix
+- `test` - Test-only (TDD RED stage)
+- `refactor` - Code cleanup (TDD REFACTOR stage)
+- `perf` - Performance improvement
+- `chore` - Dependencies, config, tooling
+
+**Examples:**
+
+```bash
+# Standard task
+git add src/api/auth.ts src/types/user.ts
+git commit -m "feat(08.02): create user registration endpoint
+
+- POST /auth/register validates email and password
+- Checks for duplicate users
+- Returns JWT token on success
+"
+
+# TDD task - RED stage
+git add src/__tests__/jwt.test.ts
+git commit -m "test(07.02): add failing test for JWT generation
+
+- Tests token contains user ID claim
+- Tests token expires in 1 hour
+- Tests signature verification
+"
+
+# TDD task - GREEN stage
+git add src/utils/jwt.ts
+git commit -m "feat(07.02): implement JWT generation
+
+- Uses jose library for signing
+- Includes user ID and expiry claims
+- Signs with HS256 algorithm
+"
+```
+
+</format>
+
+<format name="run-completion">
+## Run Completion (After All Tasks Done)
+
+After all tasks committed, one final metadata commit captures run completion.
+
+```
+docs({stage}.{run}): complete [run-name] run
+
+Tasks completed: [N]/[N]
+- [Task 1 name]
+- [Task 2 name]
+- [Task 3 name]
+
+RECAP: .ace/stages/XX-name/{stage}.{run}-recap.md
+```
+
+What to commit:
+
+```bash
+git add .ace/stages/XX-name/{stage}.{run}-run.md
+git add .ace/stages/XX-name/{stage}.{run}-recap.md
+git add .ace/pulse.md
+git add .ace/track.md
+git commit
+```
+
+**Note:** Code files NOT included - already committed per-task.
+
+</format>
+
+<format name="handoff">
+## Handoff (WIP)
+
+```
+wip: [stage-name] paused at task [X]/[Y]
+
+Current: [task name]
+[If blocked:] Blocked: [reason]
+```
+
+What to commit:
+
+```bash
+git add .ace/
+git commit
+```
+
+</format>
+</commit_formats>
+
+<example_log>
+
+**Old approach (per-run commits):**
+```
+a7f2d1 feat(checkout): Stripe payments with webhook verification
+3e9c4b feat(products): catalog with search, filters, and pagination
+8a1b2c feat(auth): JWT with refresh rotation using jose
+5c3d7e feat(foundation): Next.js 15 + Prisma + Tailwind scaffold
+2f4a8d docs: initialize ecommerce-app (5 stages)
+```
+
+**New approach (per-task commits):**
+```
+# Stage 04 - Checkout
+1a2b3c docs(04.01): complete checkout flow run
+4d5e6f feat(04.01): add webhook signature verification
+7g8h9i feat(04.01): implement payment session creation
+0j1k2l feat(04.01): create checkout page component
+
+# Stage 03 - Products
+3m4n5o docs(03.02): complete product listing run
+6p7q8r feat(03.02): add pagination controls
+9s0t1u feat(03.02): implement search and filters
+2v3w4x feat(03.01): create product catalog schema
+
+# Stage 02 - Auth
+5y6z7a docs(02.02): complete token refresh run
+8b9c0d feat(02.02): implement refresh token rotation
+1e2f3g test(02.02): add failing test for token refresh
+4h5i6j docs(02.01): complete JWT setup run
+7k8l9m feat(02.01): add JWT generation and validation
+0n1o2p chore(02.01): install jose library
+
+# Stage 01 - Foundation
+3q4r5s docs(01.01): complete scaffold run
+6t7u8v feat(01.01): configure Tailwind and globals
+9w0x1y feat(01.01): set up Prisma with database
+2z3a4b feat(01.01): create Next.js 15 project
+
+# Initialization
+5c6d7e docs: initialize ecommerce-app (5 stages)
+```
+
+Each run produces 2-4 commits (tasks + metadata). Clear, granular, bisectable.
+
+</example_log>
+
+<anti_patterns>
+
+**Still don't commit (intermediate artifacts):**
+- run.md creation (commit with run completion)
+- RESEARCH.md (intermediate)
+- research.md (intermediate)
+- Minor planning tweaks
+- "Fixed typo in track"
+
+**Do commit (outcomes):**
+- Each task completion (feat/fix/test/refactor)
+- Run completion metadata (docs)
+- Project initialization (docs)
+
+**Key principle:** Commit working code and shipped outcomes, not planning process.
+
+</anti_patterns>
+
+<commit_strategy_rationale>
+
+## Why Per-Task Commits?
+
+**Context engineering for AI:**
+- Git history becomes primary context source for future Claude sessions
+- `git log --grep="{stage}.{run}"` shows all work for a run
+- `git diff <hash>^..<hash>` shows exact changes per task
+- Less reliance on parsing recap.md = more context for actual work
+
+**Failure recovery:**
+- Task 1 committed ✅, Task 2 failed ❌
+- Claude in next session: sees task 1 complete, can retry task 2
+- Can `git reset --hard` to last successful task
+
+**Debugging:**
+- `git bisect` finds exact failing task, not just failing run
+- `git blame` traces line to specific task context
+- Each commit is independently revertable
+
+**Observability:**
+- Solo developer + Claude workflow benefits from granular attribution
+- Atomic commits are git best practice
+- "Commit noise" irrelevant when consumer is Claude, not humans
+
+</commit_strategy_rationale>

package/ace/references/horsepower-profiles.md

@@ -0,0 +1,73 @@
+# Horsepower Profiles
+
+Horsepower profiles control which Claude model each ACE agent uses. This allows balancing quality vs token spend.
+
+## Profile Definitions
+
+| Agent | `max` | `balanced` | `eco` |
+|-------|-------|------------|-------|
+| ace-architect | opus | opus | sonnet |
+| ace-navigator | opus | sonnet | sonnet |
+| ace-runner | opus | sonnet | sonnet |
+| ace-stage-scout | opus | sonnet | haiku |
+| ace-project-scout | opus | sonnet | haiku |
+| ace-synthesizer | sonnet | sonnet | haiku |
+| ace-detective | opus | sonnet | sonnet |
+| ace-codebase-mapper | sonnet | haiku | haiku |
+| ace-auditor | sonnet | sonnet | haiku |
+| ace-plan-reviewer | sonnet | sonnet | haiku |
+| ace-integration-checker | sonnet | sonnet | haiku |
+
+## Profile Philosophy
+
+**max** - Maximum reasoning power
+- Opus for all decision-making agents
+- Sonnet for read-only verification
+- Use when: quota available, critical architecture work
+
+**balanced** (default) - Smart allocation
+- Opus only for planning (where architecture decisions happen)
+- Sonnet for execution and research (follows explicit instructions)
+- Sonnet for verification (needs reasoning, not just pattern matching)
+- Use when: normal development, good balance of quality and cost
+
+**eco** - Minimal Opus usage
+- Sonnet for anything that writes code
+- Haiku for research and verification
+- Use when: conserving quota, high-volume work, less critical stages
+
+## Resolution Logic
+
+Orchestrators resolve model before spawning:
+
+```
+1. Read .ace/config.json
+2. Get horsepower (default: "balanced")
+3. Look up agent in table above
+4. Pass model parameter to Task call
+```
+
+## Switching Profiles
+
+Runtime: `/ace.set-profile <profile>`
+
+Per-project default: Set in `.ace/config.json`:
+```json
+{
+  "horsepower": "balanced"
+}
+```
+
+## Design Rationale
+
+**Why Opus for ace-architect?**
+Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
+
+**Why Sonnet for ace-runner?**
+Runners follow explicit run.md instructions. The run already contains the reasoning; execution is implementation.
+
+**Why Sonnet (not Haiku) for auditors in balanced?**
+Verification requires goal-backward reasoning - checking if code *delivers* what the stage promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+
+**Why Haiku for ace-codebase-mapper?**
+Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.

package/ace/references/planning-config.md

@@ -0,0 +1,189 @@
+<planning_config>
+
+Configuration options for `.ace/` directory behavior.
+
+<config_schema>
+```json
+"planning": {
+  "commit_docs": true,
+  "search_gitignored": false
+},
+"git": {
+  "branching_strategy": "none",
+  "stage_branch_template": "ace/stage-{stage}-{slug}",
+  "milestone_branch_template": "ace/{milestone}-{slug}"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `commit_docs` | `true` | Whether to commit planning artifacts to git |
+| `search_gitignored` | `false` | Add `--no-ignore` to broad rg searches |
+| `git.branching_strategy` | `"none"` | Git branching approach: `"none"`, `"stage"`, or `"milestone"` |
+| `git.stage_branch_template` | `"ace/stage-{stage}-{slug}"` | Branch template for stage strategy |
+| `git.milestone_branch_template` | `"ace/{milestone}-{slug}"` | Branch template for milestone strategy |
+</config_schema>
+
+<commit_docs_behavior>
+
+**When `commit_docs: true` (default):**
+- Planning files committed normally
+- recap.md, pulse.md, track.md tracked in git
+- Full history of planning decisions preserved
+
+**When `commit_docs: false`:**
+- Skip all `git add`/`git commit` for `.ace/` files
+- User must add `.ace/` to `.gitignore`
+- Useful for: OSS contributions, client projects, keeping planning private
+
+**Checking the config:**
+
+```bash
+# Check config.json first
+COMMIT_DOCS=$(cat .ace/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+
+# Auto-detect gitignored (overrides config)
+git check-ignore -q .ace 2>/dev/null && COMMIT_DOCS=false
+```
+
+**Auto-detection:** If `.ace/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.ace/` in `.gitignore`.
+
+**Conditional git operations:**
+
+```bash
+if [ "$COMMIT_DOCS" = "true" ]; then
+  git add .ace/pulse.md
+  git commit -m "docs: update state"
+fi
+```
+
+</commit_docs_behavior>
+
+<search_behavior>
+
+**When `search_gitignored: false` (default):**
+- Standard rg behavior (respects .gitignore)
+- Direct path searches work: `rg "pattern" .ace/` finds files
+- Broad searches skip gitignored: `rg "pattern"` skips `.ace/`
+
+**When `search_gitignored: true`:**
+- Add `--no-ignore` to broad rg searches that should include `.ace/`
+- Only needed when searching entire repo and expecting `.ace/` matches
+
+**Note:** Most ACE operations use direct file reads or explicit paths, which work regardless of gitignore status.
+
+</search_behavior>
+
+<setup_uncommitted_mode>
+
+To use uncommitted mode:
+
+1. **Set config:**
+   ```json
+   "planning": {
+     "commit_docs": false,
+     "search_gitignored": true
+   }
+   ```
+
+2. **Add to .gitignore:**
+   ```
+   .ace/
+   ```
+
+3. **Existing tracked files:** If `.ace/` was previously tracked:
+   ```bash
+   git rm -r --cached .ace/
+   git commit -m "chore: stop tracking planning docs"
+   ```
+
+</setup_uncommitted_mode>
+
+<branching_strategy_behavior>
+
+**Branching Strategies:**
+
+| Strategy | When branch created | Branch scope | Merge point |
+|----------|---------------------|--------------|-------------|
+| `none` | Never | N/A | N/A |
+| `stage` | At `ace.run-stage` start | Single stage | User merges after stage |
+| `milestone` | At first `ace.run-stage` of milestone | Entire milestone | At `ace.complete-milestone` |
+
+**When `git.branching_strategy: "none"` (default):**
+- All work commits to current branch
+- Standard ACE behavior
+
+**When `git.branching_strategy: "stage"`:**
+- `ace.run-stage` creates/switches to a branch before execution
+- Branch name from `stage_branch_template` (e.g., `ace/stage-03-authentication`)
+- All run commits go to that branch
+- User merges branches manually after stage completion
+- `ace.complete-milestone` offers to merge all stage branches
+
+**When `git.branching_strategy: "milestone"`:**
+- First `ace.run-stage` of milestone creates the milestone branch
+- Branch name from `milestone_branch_template` (e.g., `ace/v1.0-mvp`)
+- All stages in milestone commit to same branch
+- `ace.complete-milestone` offers to merge milestone branch to main
+
+**Template variables:**
+
+| Variable | Available in | Description |
+|----------|--------------|-------------|
+| `{stage}` | stage_branch_template | Zero-padded stage number (e.g., "03") |
+| `{slug}` | Both | Lowercase, hyphenated name |
+| `{milestone}` | milestone_branch_template | Milestone version (e.g., "v1.0") |
+
+**Checking the config:**
+
+```bash
+# Get branching strategy (default: none)
+BRANCHING_STRATEGY=$(cat .ace/config.json 2>/dev/null | grep -o '"branching_strategy"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "none")
+
+# Get stage branch template
+STAGE_BRANCH_TEMPLATE=$(cat .ace/config.json 2>/dev/null | grep -o '"stage_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "ace/stage-{stage}-{slug}")
+
+# Get milestone branch template
+MILESTONE_BRANCH_TEMPLATE=$(cat .ace/config.json 2>/dev/null | grep -o '"milestone_branch_template"[[:space:]]*:[[:space:]]*"[^"]*"' | sed 's/.*:.*"\([^"]*\)"/\1/' || echo "ace/{milestone}-{slug}")
+```
+
+**Branch creation:**
+
+```bash
+# For stage strategy
+if [ "$BRANCHING_STRATEGY" = "stage" ]; then
+  STAGE_SLUG=$(echo "$STAGE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$STAGE_BRANCH_TEMPLATE" | sed "s/{stage}/$PADDED_STAGE/g" | sed "s/{slug}/$STAGE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+
+# For milestone strategy
+if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
+  MILESTONE_SLUG=$(echo "$MILESTONE_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+  BRANCH_NAME=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed "s/{milestone}/$MILESTONE_VERSION/g" | sed "s/{slug}/$MILESTONE_SLUG/g")
+  git checkout -b "$BRANCH_NAME" 2>/dev/null || git checkout "$BRANCH_NAME"
+fi
+```
+
+**Merge options at ace.complete-milestone:**
+
+| Option | Git command | Result |
+|--------|-------------|--------|
+| Squash merge (recommended) | `git merge --squash` | Single clean commit per branch |
+| Merge with history | `git merge --no-ff` | Preserves all individual commits |
+| Delete without merging | `git branch -D` | Discard branch work |
+| Keep branches | (none) | Manual handling later |
+
+Squash merge is recommended — keeps main branch history clean while preserving the full development history in the branch (until deleted).
+
+**Use cases:**
+
+| Strategy | Best for |
+|----------|----------|
+| `none` | Solo development, simple projects |
+| `stage` | Code review per stage, granular rollback, team collaboration |
+| `milestone` | Release branches, staging environments, PR per version |
+
+</branching_strategy_behavior>
+
+</planning_config>

package/ace/references/questioning.md

@@ -0,0 +1,141 @@
+<questioning_guide>
+
+Project initialization is dream extraction, not requirements gathering. You're helping the user discover and articulate what they want to build. This isn't a contract negotiation — it's collaborative thinking.
+
+<philosophy>
+
+**You are a thinking partner, not an interviewer.**
+
+The user often has a fuzzy idea. Your job is to help them sharpen it. Ask questions that make them think "oh, I hadn't considered that" or "yes, that's exactly what I mean."
+
+Don't interrogate. Collaborate. Don't follow a script. Follow the thread.
+
+</philosophy>
+
+<the_goal>
+
+By the end of questioning, you need enough clarity to write a brief.md that downstream stages can act on:
+
+- **Research** needs: what domain to research, what the user already knows, what unknowns exist
+- **Requirements** needs: clear enough vision to scope v1 features
+- **Track** needs: clear enough vision to decompose into stages, what "done" looks like
+- **ace.plan-stage** needs: specific requirements to break into tasks, context for implementation choices
+- **ace.run-stage** needs: success criteria to verify against, the "why" behind requirements
+
+A vague brief.md forces every downstream stage to guess. The cost compounds.
+
+</the_goal>
+
+<how_to_question>
+
+**Start open.** Let them dump their mental model. Don't interrupt with structure.
+
+**Follow energy.** Whatever they emphasized, dig into that. What excited them? What problem sparked this?
+
+**Challenge vagueness.** Never accept fuzzy answers. "Good" means what? "Users" means who? "Simple" means how?
+
+**Make the abstract concrete.** "Walk me through using this." "What does that actually look like?"
+
+**Clarify ambiguity.** "When you say Z, do you mean A or B?" "You mentioned X — tell me more."
+
+**Know when to stop.** When you understand what they want, why they want it, who it's for, and what done looks like — offer to proceed.
+
+</how_to_question>
+
+<question_types>
+
+Use these as inspiration, not a checklist. Pick what's relevant to the thread.
+
+**Motivation — why this exists:**
+- "What prompted this?"
+- "What are you doing today that this replaces?"
+- "What would you do if this existed?"
+
+**Concreteness — what it actually is:**
+- "Walk me through using this"
+- "You said X — what does that actually look like?"
+- "Give me an example"
+
+**Clarification — what they mean:**
+- "When you say Z, do you mean A or B?"
+- "You mentioned X — tell me more about that"
+
+**Success — how you'll know it's working:**
+- "How will you know this is working?"
+- "What does done look like?"
+
+</question_types>
+
+<using_askuserquestion>
+
+Use AskUserQuestion to help users think by presenting concrete options to react to.
+
+**Good options:**
+- Interpretations of what they might mean
+- Specific examples to confirm or deny
+- Concrete choices that reveal priorities
+
+**Bad options:**
+- Generic categories ("Technical", "Business", "Other")
+- Leading options that presume an answer
+- Too many options (2-4 is ideal)
+
+**Example — vague answer:**
+User says "it should be fast"
+
+- header: "Fast"
+- question: "Fast how?"
+- options: ["Sub-second response", "Handles large datasets", "Quick to build", "Let me explain"]
+
+**Example — following a thread:**
+User mentions "frustrated with current tools"
+
+- header: "Frustration"
+- question: "What specifically frustrates you?"
+- options: ["Too many clicks", "Missing features", "Unreliable", "Let me explain"]
+
+</using_askuserquestion>
+
+<context_checklist>
+
+Use this as a **background checklist**, not a conversation structure. Check these mentally as you go. If gaps remain, weave questions naturally.
+
+- [ ] What they're building (concrete enough to explain to a stranger)
+- [ ] Why it needs to exist (the problem or desire driving it)
+- [ ] Who it's for (even if just themselves)
+- [ ] What "done" looks like (observable outcomes)
+
+Four things. If they volunteer more, capture it.
+
+</context_checklist>
+
+<decision_gate>
+
+When you could write a clear brief.md, offer to proceed:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create brief.md?"
+- options:
+  - "Create brief.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add or identify gaps and probe naturally.
+
+Loop until "Create brief.md" selected.
+
+</decision_gate>
+
+<anti_patterns>
+
+- **Checklist walking** — Going through domains regardless of what they said
+- **Canned questions** — "What's your core value?" "What's out of scope?" regardless of context
+- **Corporate speak** — "What are your success criteria?" "Who are your stakeholders?"
+- **Interrogation** — Firing questions without building on answers
+- **Rushing** — Minimizing questions to get to "the work"
+- **Shallow acceptance** — Taking vague answers without probing
+- **Premature constraints** — Asking about tech stack before understanding the idea
+- **User skills** — NEVER ask about user's technical experience. Claude builds.
+
+</anti_patterns>
+
+</questioning_guide>