ace-experience 0.1.0

package/commands/ace.dash.md

@@ -0,0 +1,308 @@
+---
+name: ace.dash
+description: Execute a quick task with ACE guarantees (atomic commits, state tracking) but skip optional agents
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Execute small, ad-hoc tasks with ACE guarantees (atomic commits, pulse.md tracking) while skipping optional agents (research, plan-reviewer, auditor).
+
+Dash mode is the same system with a shorter path:
+- Spawns ace-architect (quick mode) + ace-runner(s)
+- Skips ace-stage-scout, ace-plan-reviewer, ace-auditor
+- Dash tasks live in `.ace/quick/` separate from planned stages
+- Updates pulse.md "Quick Tasks Completed" table (NOT track.md)
+
+Use when: You know exactly what to do and the task is small enough to not need research or verification.
+</objective>
+
+<execution_context>
+Orchestration is inline - no separate workflow file. Dash mode is deliberately simpler than full ACE.
+</execution_context>
+
+<context>
+@.ace/pulse.md
+</context>
+
+<process>
+**Step 0: Resolve Horsepower Profile**
+
+Read horsepower profile for agent spawning:
+
+```bash
+HORSEPOWER=$(cat .ace/config.json 2>/dev/null | grep -o '"horsepower"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | max | balanced | eco |
+|-------|-----|----------|-----|
+| ace-architect | opus | opus | sonnet |
+| ace-runner | opus | sonnet | sonnet |
+
+Store resolved models for use in Task calls below.
+
+---
+
+**Step 1: Pre-flight validation**
+
+Check that an active ACE project exists:
+
+```bash
+if [ ! -f .ace/track.md ]; then
+  echo "Dash mode requires an active project with track.md."
+  echo "Run /ace.start first."
+  exit 1
+fi
+```
+
+If validation fails, stop immediately with the error message.
+
+Dash tasks can run mid-stage - validation only checks track.md exists, not stage status.
+
+---
+
+**Step 2: Get task description**
+
+Prompt user interactively for the task description:
+
+```
+AskUserQuestion(
+  header: "Dash Task",
+  question: "What do you want to do?",
+  followUp: null
+)
+```
+
+Store response as `$DESCRIPTION`.
+
+If empty, re-prompt: "Please provide a task description."
+
+Generate slug from description:
+```bash
+slug=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//' | cut -c1-40)
+```
+
+---
+
+**Step 3: Calculate next dash task number**
+
+Ensure `.ace/quick/` directory exists and find the next sequential number:
+
+```bash
+# Ensure .ace/quick/ exists
+mkdir -p .ace/quick
+
+# Find highest existing number and increment
+last=$(ls -1d .ace/quick/[0-9][0-9][0-9]-* 2>/dev/null | sort -r | head -1 | xargs -I{} basename {} | grep -oE '^[0-9]+')
+
+if [ -z "$last" ]; then
+  next_num="001"
+else
+  next_num=$(printf "%03d" $((10#$last + 1)))
+fi
+```
+
+---
+
+**Step 4: Create dash task directory**
+
+Create the directory for this dash task:
+
+```bash
+DASH_DIR=".ace/quick/${next_num}-${slug}"
+mkdir -p "$DASH_DIR"
+```
+
+Report to user:
+```
+Creating dash task ${next_num}: ${DESCRIPTION}
+Directory: ${DASH_DIR}
+```
+
+Store `$DASH_DIR` for use in orchestration.
+
+---
+
+**Step 5: Spawn architect (quick mode)**
+
+Spawn ace-architect with quick mode context:
+
+```
+Task(
+  prompt="
+<planning_context>
+
+**Mode:** quick
+**Directory:** ${DASH_DIR}
+**Description:** ${DESCRIPTION}
+
+**Project State:**
+@.ace/pulse.md
+
+</planning_context>
+
+<constraints>
+- Create a SINGLE run with 1-3 focused tasks
+- Dash tasks should be atomic and self-contained
+- No research stage, no reviewer stage
+- Target ~30% context usage (simple, focused)
+</constraints>
+
+<output>
+Write run to: ${DASH_DIR}/${next_num}-run.md
+Return: ## PLANNING COMPLETE with run path
+</output>
+",
+  subagent_type="ace-architect",
+  model="{architect_model}",
+  description="Dash run: ${DESCRIPTION}"
+)
+```
+
+After architect returns:
+1. Verify run exists at `${DASH_DIR}/${next_num}-run.md`
+2. Extract run count (typically 1 for dash tasks)
+3. Report: "Run created: ${DASH_DIR}/${next_num}-run.md"
+
+If run not found, error: "Architect failed to create ${next_num}-run.md"
+
+---
+
+**Step 6: Spawn runner**
+
+Spawn ace-runner with run reference:
+
+```
+Task(
+  prompt="
+Execute dash task ${next_num}.
+
+Run: @${DASH_DIR}/${next_num}-run.md
+Project state: @.ace/pulse.md
+
+<constraints>
+- Execute all tasks in the run
+- Commit each task atomically
+- Create recap at: ${DASH_DIR}/${next_num}-recap.md
+- Do NOT update track.md (dash tasks are separate from planned stages)
+</constraints>
+",
+  subagent_type="ace-runner",
+  model="{runner_model}",
+  description="Execute: ${DESCRIPTION}"
+)
+```
+
+After runner returns:
+1. Verify recap exists at `${DASH_DIR}/${next_num}-recap.md`
+2. Extract commit hash from runner output
+3. Report completion status
+
+If recap not found, error: "Runner failed to create ${next_num}-recap.md"
+
+Note: For dash tasks producing multiple runs (rare), spawn runners in parallel batches per run-stage patterns.
+
+---
+
+**Step 7: Update pulse.md**
+
+Update pulse.md with dash task completion record.
+
+**7a. Check if "Quick Tasks Completed" section exists:**
+
+Read pulse.md and check for `### Quick Tasks Completed` section.
+
+**7b. If section doesn't exist, create it:**
+
+Insert after `### Blockers/Concerns` section:
+
+```markdown
+### Quick Tasks Completed
+
+| # | Description | Date | Commit | Directory |
+|---|-------------|------|--------|-----------|
+```
+
+**7c. Append new row to table:**
+
+```markdown
+| ${next_num} | ${DESCRIPTION} | $(date +%Y-%m-%d) | ${commit_hash} | [${next_num}-${slug}](./quick/${next_num}-${slug}/) |
+```
+
+**7d. Update "Last activity" line:**
+
+Find and update the line:
+```
+Last activity: $(date +%Y-%m-%d) - Completed dash task ${next_num}: ${DESCRIPTION}
+```
+
+Use Edit tool to make these changes atomically
+
+---
+
+**Step 8: Final commit and completion**
+
+Stage and commit dash task artifacts:
+
+```bash
+# Stage dash task artifacts
+git add ${DASH_DIR}/${next_num}-run.md
+git add ${DASH_DIR}/${next_num}-recap.md
+git add .ace/pulse.md
+
+# Commit with dash task format
+git commit -m "$(cat <<'EOF'
+docs(dash-${next_num}): ${DESCRIPTION}
+
+Dash task completed.
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+EOF
+)"
+```
+
+Get final commit hash:
+```bash
+commit_hash=$(git rev-parse --short HEAD)
+```
+
+Display completion output:
+```
+---
+
+ACE > DASH TASK COMPLETE
+
+Dash Task ${next_num}: ${DESCRIPTION}
+
+Recap: ${DASH_DIR}/${next_num}-recap.md
+Commit: ${commit_hash}
+
+---
+
+Ready for next task: /ace.dash
+```
+
+</process>
+
+<success_criteria>
+- [ ] track.md validation passes
+- [ ] User provides task description
+- [ ] Slug generated (lowercase, hyphens, max 40 chars)
+- [ ] Next number calculated (001, 002, 003...)
+- [ ] Directory created at `.ace/quick/NNN-slug/`
+- [ ] `${next_num}-run.md` created by architect
+- [ ] `${next_num}-recap.md` created by runner
+- [ ] pulse.md updated with dash task row
+- [ ] Artifacts committed
+</success_criteria>

package/commands/ace.debug.md

@@ -0,0 +1,169 @@
+---
+name: ace.debug
+description: Systematic debugging with persistent state across context resets
+argument-hint: [issue description]
+allowed-tools:
+  - Read
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Debug issues using scientific method with subagent isolation.
+
+**Orchestrator role:** Gather symptoms, spawn ace-detective agent, handle gates, spawn continuations.
+
+**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction.
+</objective>
+
+<context>
+User's issue: $ARGUMENTS
+
+Check for active sessions:
+```bash
+ls .ace/debug/*.md 2>/dev/null | grep -v resolved | head -5
+```
+</context>
+
+<process>
+
+## 0. Resolve Horsepower Profile
+
+Read horsepower profile for agent spawning:
+
+```bash
+HORSEPOWER=$(cat .ace/config.json 2>/dev/null | grep -o '"horsepower"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | max | balanced | eco |
+|-------|---------|----------|--------|
+| ace-detective | opus | sonnet | sonnet |
+
+Store resolved model for use in Task calls below.
+
+## 1. Check Active Sessions
+
+If active sessions exist AND no $ARGUMENTS:
+- List sessions with status, hypothesis, next action
+- User picks number to resume OR describes new issue
+
+If $ARGUMENTS provided OR user describes new issue:
+- Continue to symptom gathering
+
+## 2. Gather Symptoms (if new issue)
+
+Use AskUserQuestion for each:
+
+1. **Expected behavior** - What should happen?
+2. **Actual behavior** - What happens instead?
+3. **Error messages** - Any errors? (paste or describe)
+4. **Timeline** - When did this start? Ever worked?
+5. **Reproduction** - How do you trigger it?
+
+After all gathered, confirm ready to investigate.
+
+## 3. Spawn ace-detective Agent
+
+Fill prompt and spawn:
+
+```markdown
+<objective>
+Investigate issue: {slug}
+
+**Summary:** {trigger}
+</objective>
+
+<symptoms>
+expected: {expected}
+actual: {actual}
+errors: {errors}
+reproduction: {reproduction}
+timeline: {timeline}
+</symptoms>
+
+<mode>
+symptoms_prefilled: true
+goal: find_and_fix
+</mode>
+
+<debug_file>
+Create: .ace/debug/{slug}.md
+</debug_file>
+```
+
+```
+Task(
+  prompt=filled_prompt,
+  subagent_type="ace-detective",
+  model="{detective_model}",
+  description="Debug {slug}"
+)
+```
+
+## 4. Handle Agent Return
+
+**If `## CULPRIT FOUND`:**
+- Display root cause and evidence summary
+- Offer options:
+  - "Fix now" - spawn fix subagent
+  - "Plan fix" - suggest ace.plan-stage --gaps
+  - "Manual fix" - done
+
+**If `## GATE REACHED`:**
+- Present gate details to user
+- Get user response
+- Spawn continuation agent (see step 5)
+
+**If `## INVESTIGATION INCONCLUSIVE`:**
+- Show what was checked and eliminated
+- Offer options:
+  - "Continue investigating" - spawn new agent with additional context
+  - "Manual investigation" - done
+  - "Add more context" - gather more symptoms, spawn again
+
+## 5. Spawn Continuation Agent (After Gate)
+
+When user responds to gate, spawn fresh agent:
+
+```markdown
+<objective>
+Continue debugging {slug}. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.ace/debug/{slug}.md
+</prior_state>
+
+<checkpoint_response>
+**Type:** {checkpoint_type}
+**Response:** {user_response}
+</checkpoint_response>
+
+<mode>
+goal: find_and_fix
+</mode>
+```
+
+```
+Task(
+  prompt=continuation_prompt,
+  subagent_type="ace-detective",
+  model="{detective_model}",
+  description="Continue debug {slug}"
+)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Active sessions checked
+- [ ] Symptoms gathered (if new)
+- [ ] ace-detective spawned with context
+- [ ] Gates handled correctly
+- [ ] Root cause confirmed before fixing
+</success_criteria>

package/commands/ace.discuss-stage.md

@@ -0,0 +1,86 @@
+---
+name: ace.discuss-stage
+description: Gather stage context through adaptive questioning before architecting
+argument-hint: "<stage>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Extract implementation decisions that downstream agents need — scout and architect will use intel.md to know what to investigate and what choices are locked.
+
+**How it works:**
+1. Analyze the stage to identify gray areas (UI, UX, behavior, etc.)
+2. Present gray areas — user selects which to discuss
+3. Deep-dive each selected area until satisfied
+4. Create intel.md with decisions that guide research and architecting
+
+**Output:** `{stage}-intel.md` — decisions clear enough that downstream agents can act without asking the user again
+</objective>
+
+<execution_context>
+@~/.claude/ace/workflows/scope-stage.md
+@~/.claude/ace/templates/intel.md
+</execution_context>
+
+<context>
+Stage number: $ARGUMENTS (required)
+
+**Load project state:**
+@.ace/pulse.md
+
+**Load track:**
+@.ace/track.md
+</context>
+
+<process>
+1. Validate stage number (error if missing or not in track)
+2. Check if intel.md exists (offer update/view/skip if yes)
+3. **Analyze stage** — Identify domain and generate stage-specific gray areas
+4. **Present gray areas** — Multi-select: which to discuss? (NO skip option)
+5. **Deep-dive each area** — 4 questions per area, then offer more/next
+6. **Write intel.md** — Sections match areas discussed
+7. Offer next steps (research or architect)
+
+**CRITICAL: Scope guardrail**
+- Stage boundary from track.md is FIXED
+- Discussion clarifies HOW to implement, not WHETHER to add more
+- If user suggests new capabilities: "That's its own stage. I'll note it for later."
+- Capture deferred ideas — don't lose them, don't act on them
+
+**Domain-aware gray areas:**
+Gray areas depend on what's being built. Analyze the stage goal:
+- Something users SEE → layout, density, interactions, states
+- Something users CALL → responses, errors, auth, versioning
+- Something users RUN → output format, flags, modes, error handling
+- Something users READ → structure, tone, depth, flow
+- Something being ORGANIZED → criteria, grouping, naming, exceptions
+
+Generate 3-4 **stage-specific** gray areas, not generic categories.
+
+**Probing depth:**
+- Ask 4 questions per area before checking
+- "More questions about [area], or move to next?"
+- If more → ask 4 more, check again
+- After all areas → "Ready to create intel?"
+
+**Do NOT ask about (Claude handles these):**
+- Technical implementation
+- Architecture choices
+- Performance concerns
+- Scope expansion
+</process>
+
+<success_criteria>
+- Gray areas identified through intelligent analysis
+- User chose which areas to discuss
+- Each selected area explored until satisfied
+- Scope creep redirected to deferred ideas
+- intel.md captures decisions, not vague vision
+- User knows next steps
+</success_criteria>