ace-experience 0.1.0

package/commands/ace.audit.md

@@ -0,0 +1,219 @@
+---
+name: ace.audit
+description: Validate built features through conversational UAT
+argument-hint: "[stage number, e.g., '4']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Edit
+  - Write
+  - Task
+---
+
+<objective>
+Validate built features through conversational testing with persistent state.
+
+Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. When issues are found, automatically diagnose, plan fixes, and prepare for execution.
+
+Output: {stage}-uat.md tracking all test results. If issues found: diagnosed gaps, verified fix runs ready for /ace.run-stage
+</objective>
+
+<execution_context>
+@~/.claude/ace/workflows/audit-work.md
+@~/.claude/ace/templates/uat.md
+</execution_context>
+
+<context>
+Stage: $ARGUMENTS (optional)
+- If provided: Test specific stage (e.g., "4")
+- If not provided: Check for active sessions or prompt for stage
+
+@.ace/pulse.md
+@.ace/track.md
+</context>
+
+<process>
+1. Check for active UAT sessions (resume or start new)
+2. Find recap.md files for the stage
+3. Extract testable deliverables (user-observable outcomes)
+4. Create {stage}-uat.md with test list
+5. Present tests one at a time:
+   - Show expected behavior
+   - Wait for plain text response
+   - "yes/y/next" = pass, anything else = issue (severity inferred)
+6. Update uat.md after each response
+7. On completion: commit, present summary
+8. If issues found:
+   - Spawn parallel debug agents to diagnose root causes
+   - Spawn ace-architect in --gaps mode to create fix runs
+   - Spawn ace-plan-reviewer to verify fix runs
+   - Iterate architect <-> reviewer until runs pass (max 3)
+   - Present ready status with `/clear` then `/ace.run-stage`
+</process>
+
+<anti_patterns>
+- Don't use AskUserQuestion for test responses — plain text conversation
+- Don't ask severity — infer from description
+- Don't present full checklist upfront — one test at a time
+- Don't run automated tests — this is manual user validation
+- Don't fix issues during testing — log as gaps, diagnose after all tests complete
+</anti_patterns>
+
+<offer_next>
+Output this markdown directly (not as a code block). Route based on UAT results:
+
+| Status | Route |
+|--------|-------|
+| All tests pass + more stages | Route A (next stage) |
+| All tests pass + last stage | Route B (milestone complete) |
+| Issues found + fix runs ready | Route C (execute fixes) |
+| Issues found + planning blocked | Route D (manual intervention) |
+
+---
+
+**Route A: All tests pass, more stages remain**
+
+=====================================================
+ ACE > STAGE {Z} VERIFIED
+=====================================================
+
+**Stage {Z}: {Name}**
+
+{N}/{N} tests passed
+UAT complete
+
+---------------------------------------------------------------
+
+## > Next Up
+
+**Stage {Z+1}: {Name}** — {Goal from track.md}
+
+/ace.discuss-stage {Z+1} — gather context and clarify approach
+
+<sub>/clear first -> fresh context window</sub>
+
+---------------------------------------------------------------
+
+**Also available:**
+- /ace.plan-stage {Z+1} — skip discussion, plan directly
+- /ace.run-stage {Z+1} — skip to execution (if already planned)
+
+---------------------------------------------------------------
+
+---
+
+**Route B: All tests pass, milestone complete**
+
+=====================================================
+ ACE > STAGE {Z} VERIFIED
+=====================================================
+
+**Stage {Z}: {Name}**
+
+{N}/{N} tests passed
+Final stage verified
+
+---------------------------------------------------------------
+
+## > Next Up
+
+**Audit milestone** — verify requirements, cross-stage integration, E2E flows
+
+/ace.audit-milestone
+
+<sub>/clear first -> fresh context window</sub>
+
+---------------------------------------------------------------
+
+**Also available:**
+- /ace.complete-milestone — skip audit, archive directly
+
+---------------------------------------------------------------
+
+---
+
+**Route C: Issues found, fix runs ready**
+
+=====================================================
+ ACE > STAGE {Z} ISSUES FOUND
+=====================================================
+
+**Stage {Z}: {Name}**
+
+{N}/{M} tests passed
+{X} issues diagnosed
+Fix runs verified
+
+### Issues Found
+
+{List issues with severity from uat.md}
+
+---------------------------------------------------------------
+
+## > Next Up
+
+**Execute fix runs** — run diagnosed fixes
+
+/ace.run-stage {Z} --gaps-only
+
+<sub>/clear first -> fresh context window</sub>
+
+---------------------------------------------------------------
+
+**Also available:**
+- cat .ace/stages/{stage_dir}/*-run.md — review fix runs
+- /ace.plan-stage {Z} --gaps — regenerate fix runs
+
+---------------------------------------------------------------
+
+---
+
+**Route D: Issues found, planning blocked**
+
+=====================================================
+ ACE > STAGE {Z} BLOCKED
+=====================================================
+
+**Stage {Z}: {Name}**
+
+{N}/{M} tests passed
+Fix planning blocked after {X} iterations
+
+### Unresolved Issues
+
+{List blocking issues from architect/reviewer output}
+
+---------------------------------------------------------------
+
+## > Next Up
+
+**Manual intervention required**
+
+Review the issues above and either:
+1. Provide guidance for fix planning
+2. Manually address blockers
+3. Accept current state and continue
+
+---------------------------------------------------------------
+
+**Options:**
+- /ace.plan-stage {Z} --gaps — retry fix planning with guidance
+- /ace.discuss-stage {Z} — gather more context before replanning
+
+---------------------------------------------------------------
+</offer_next>
+
+<success_criteria>
+- [ ] uat.md created with tests from recap.md
+- [ ] Tests presented one at a time with expected behavior
+- [ ] Plain text responses (no structured forms)
+- [ ] Severity inferred, never asked
+- [ ] Batched writes: on issue, every 5 passes, or completion
+- [ ] Committed on completion
+- [ ] If issues: parallel debug agents diagnose root causes
+- [ ] If issues: ace-architect creates fix runs from diagnosed gaps
+- [ ] If issues: ace-plan-reviewer verifies fix runs (max 3 iterations)
+- [ ] Ready for `/ace.run-stage` when complete
+</success_criteria>

package/commands/ace.check-todos.md

@@ -0,0 +1,229 @@
+---
+name: ace.check-todos
+description: List pending todos and select one to work on
+argument-hint: [area filter]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+
+Enables reviewing captured ideas and deciding what to work on next.
+</objective>
+
+<context>
+$ARGUMENTS
+@.ace/pulse.md
+@.ace/track.md
+</context>
+
+<process>
+
+<step name="check_exist">
+```bash
+TODO_COUNT=$(ls .ace/todos/pending/*.md 2>/dev/null | wc -l | tr -d ' ')
+echo "Pending todos: $TODO_COUNT"
+```
+
+If count is 0:
+```
+No pending todos.
+
+Todos are captured during work sessions with /ace.add-todo.
+
+---
+
+Would you like to:
+
+1. Continue with current stage (/ace.status)
+2. Add a todo now (/ace.add-todo)
+```
+
+Exit.
+</step>
+
+<step name="parse_filter">
+Check for area filter in arguments:
+- `/ace.check-todos` → show all
+- `/ace.check-todos api` → filter to area:api only
+</step>
+
+<step name="list_todos">
+```bash
+for file in .ace/todos/pending/*.md; do
+  created=$(grep "^created:" "$file" | cut -d' ' -f2)
+  title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs)
+  area=$(grep "^area:" "$file" | cut -d' ' -f2)
+  echo "$created|$title|$area|$file"
+done | sort
+```
+
+Apply area filter if specified. Display as numbered list:
+
+```
+Pending Todos:
+
+1. Add auth token refresh (api, 2d ago)
+2. Fix modal z-index issue (ui, 1d ago)
+3. Refactor database connection pool (database, 5h ago)
+
+---
+
+Reply with a number to view details, or:
+- `/ace.check-todos [area]` to filter by area
+- `q` to exit
+```
+
+Format age as relative time.
+</step>
+
+<step name="handle_selection">
+Wait for user to reply with a number.
+
+If valid: load selected todo, proceed.
+If invalid: "Invalid selection. Reply with a number (1-[N]) or `q` to exit."
+</step>
+
+<step name="load_context">
+Read the todo file completely. Display:
+
+```
+## [title]
+
+**Area:** [area]
+**Created:** [date] ([relative time] ago)
+**Files:** [list or "None"]
+
+### Problem
+[problem section content]
+
+### Solution
+[solution section content]
+```
+
+If `files` field has entries, read and briefly summarize each.
+</step>
+
+<step name="check_track">
+```bash
+ls .ace/track.md 2>/dev/null && echo "Track exists"
+```
+
+If track exists:
+1. Check if todo's area matches an upcoming stage
+2. Check if todo's files overlap with a stage's scope
+3. Note any match for action options
+</step>
+
+<step name="offer_actions">
+**If todo maps to a track stage:**
+
+Use AskUserQuestion:
+- header: "Action"
+- question: "This todo relates to Stage [N]: [name]. What would you like to do?"
+- options:
+  - "Work on it now" — move to done, start working
+  - "Add to stage run" — include when planning Stage [N]
+  - "Brainstorm approach" — think through before deciding
+  - "Put it back" — return to list
+
+**If no track match:**
+
+Use AskUserQuestion:
+- header: "Action"
+- question: "What would you like to do with this todo?"
+- options:
+  - "Work on it now" — move to done, start working
+  - "Create a stage" — /ace.add-stage with this scope
+  - "Brainstorm approach" — think through before deciding
+  - "Put it back" — return to list
+</step>
+
+<step name="execute_action">
+**Work on it now:**
+```bash
+mv ".ace/todos/pending/[filename]" ".ace/todos/done/"
+```
+Update pulse.md todo count. Present problem/solution context. Begin work or ask how to proceed.
+
+**Add to stage run:**
+Note todo reference in stage planning notes. Keep in pending. Return to list or exit.
+
+**Create a stage:**
+Display: `/ace.add-stage [description from todo]`
+Keep in pending. User runs command in fresh context.
+
+**Brainstorm approach:**
+Keep in pending. Start discussion about problem and approaches.
+
+**Put it back:**
+Return to list_todos step.
+</step>
+
+<step name="update_state">
+After any action that changes todo count:
+
+```bash
+ls .ace/todos/pending/*.md 2>/dev/null | wc -l
+```
+
+Update pulse.md "### Pending Todos" section if exists.
+</step>
+
+<step name="git_commit">
+If todo was moved to done/, commit the change:
+
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .ace/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .ace 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations, log "Todo moved (not committed - commit_docs: false)"
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
+```bash
+git add .ace/todos/done/[filename]
+git rm --cached .ace/todos/pending/[filename] 2>/dev/null || true
+[ -f .ace/pulse.md ] && git add .ace/pulse.md
+git commit -m "$(cat <<'EOF'
+docs: start work on todo - [title]
+
+Moved to done/, beginning implementation.
+EOF
+)"
+```
+
+Confirm: "Committed: docs: start work on todo - [title]"
+</step>
+
+</process>
+
+<output>
+- Moved todo to `.ace/todos/done/` (if "Work on it now")
+- Updated `.ace/pulse.md` (if todo count changed)
+</output>
+
+<anti_patterns>
+- Don't delete todos — move to done/ when work begins
+- Don't start work without moving to done/ first
+- Don't create runs from this command — route to /ace.plan-stage or /ace.add-stage
+</anti_patterns>
+
+<success_criteria>
+- [ ] All pending todos listed with title, area, age
+- [ ] Area filter applied if specified
+- [ ] Selected todo's full context loaded
+- [ ] Track context checked for stage match
+- [ ] Appropriate actions offered
+- [ ] Selected action executed
+- [ ] pulse.md updated if todo count changed
+- [ ] Changes committed to git (if todo moved to done/)
+</success_criteria>

package/commands/ace.complete-milestone.md

@@ -0,0 +1,134 @@
+---
+type: prompt
+name: ace.complete-milestone
+description: Archive completed milestone and prepare for next version
+argument-hint: <version>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Mark milestone {{version}} complete, archive to milestones/, and update track.md and specs.md.
+
+Purpose: Create historical record of shipped version, archive milestone artifacts (track + specs), and prepare for next milestone.
+Output: Milestone archived (track + specs), brief.md evolved, git tagged.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @~/.claude/ace/workflows/ship-milestone.md (main workflow)
+- @~/.claude/ace/templates/milestone-archive.md (archive template)
+  </execution_context>
+
+<context>
+$ARGUMENTS
+
+**Project files:**
+- `.ace/track.md`
+- `.ace/specs.md`
+- `.ace/pulse.md`
+- `.ace/brief.md`
+</context>
+
+<process>
+
+**Follow ship-milestone.md workflow:**
+
+0. **Check for audit:**
+
+   - Look for `.ace/v{{version}}-MILESTONE-AUDIT.md`
+   - If missing or stale: recommend `/ace.audit-milestone` first
+   - If audit status is `gaps_found`: recommend `/ace.plan-milestone-gaps` first
+   - If audit status is `passed`: proceed to step 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-MILESTONE-AUDIT.md:}
+   ⚠ No milestone audit found. Run `/ace.audit-milestone` first to verify
+   specs coverage, cross-stage integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. Run `/ace.plan-milestone-gaps` to create
+   stages that close the gaps, or proceed anyway to accept as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **Verify readiness:**
+
+   - Check all stages in milestone have completed runs (recap.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count stages, runs, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+   - Present summary, confirm
+
+3. **Extract accomplishments:**
+
+   - Read all stage recap.md files in milestone range
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone:**
+
+   - Create `.ace/milestones/v{{version}}-track.md`
+   - Extract full stage details from track.md
+   - Fill milestone-archive.md template
+   - Update track.md to one-line summary with link
+
+5. **Archive specs:**
+
+   - Create `.ace/milestones/v{{version}}-specs.md`
+   - Mark all v1 specs as complete (checkboxes checked)
+   - Note spec outcomes (validated, adjusted, dropped)
+   - Delete `.ace/specs.md` (fresh one created for next milestone)
+
+6. **Update brief.md:**
+
+   - Add "Current State" section with shipped version
+   - Add "Next Milestone Goals" section
+   - Archive previous content in `<details>` (if v1.1+)
+
+7. **Commit and tag:**
+
+   - Stage: milestones.md, brief.md, track.md, pulse.md, archive files
+   - Commit: `chore: archive v{{version}} milestone`
+   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/ace.new-milestone` — start next milestone (questioning → research → specs → track)
+
+</process>
+
+<success_criteria>
+
+- Milestone archived to `.ace/milestones/v{{version}}-track.md`
+- Specs archived to `.ace/milestones/v{{version}}-specs.md`
+- `.ace/specs.md` deleted (fresh for next milestone)
+- track.md collapsed to one-line entry
+- brief.md updated with current state
+- Git tag v{{version}} created
+- Commit successful
+- User knows next steps (including need for fresh specs)
+  </success_criteria>
+
+<critical_rules>
+
+- **Load workflow first:** Read ship-milestone.md before executing
+- **Verify completion:** All stages must have recap.md files
+- **User confirmation:** Wait for approval at verification gates
+- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **One-line summary:** Collapsed milestone in track.md should be single line with link
+- **Context efficiency:** Archive keeps track.md and specs.md constant size per milestone
+- **Fresh specs:** Next milestone starts with `/ace.new-milestone` which includes specs definition
+  </critical_rules>

package/commands/ace.continue.md

@@ -0,0 +1,46 @@
+---
+name: ace.continue
+description: Resume work from previous session with full context restoration
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - AskUserQuestion
+  - SlashCommand
+---
+
+<objective>
+Restore complete project context and resume work seamlessly from previous session.
+
+Routes to the continue-project workflow which handles:
+
+- pulse.md loading (or reconstruction if missing)
+- Gate detection (.continue-here files)
+- Incomplete work detection (run.md without recap.md)
+- Status presentation
+- Context-aware next action routing
+</objective>
+
+<execution_context>
+@~/.claude/ace/workflows/continue-project.md
+</execution_context>
+
+<process>
+**Follow the continue-project workflow** from `@~/.claude/ace/workflows/continue-project.md`.
+
+The workflow handles all resumption logic including:
+
+1. Project existence verification
+2. pulse.md loading or reconstruction
+3. Gate and incomplete work detection
+4. Visual status presentation
+5. Context-aware option offering (checks intel.md before suggesting plan vs discuss)
+6. Routing to appropriate next command
+7. Session continuity updates
+</process>
+
+<success_criteria>
+- [ ] Project context restored from pulse.md (or reconstructed if missing)
+- [ ] Gates and incomplete work detected (checked .continue-here files and run.md without recap.md)
+- [ ] Visual status and context-aware next actions presented to user
+</success_criteria>