@accelerationguy/accel 1.0.0

package/modules/drive/src/commands/research.md

@@ -0,0 +1,47 @@
+---
+name: drive:research
+description: Research a topic using subagents for discovery
+argument-hint: "<topic> [--codebase | --web]"
+allowed-tools: [Read, Task, Bash, Write]
+---
+
+<objective>
+Research a specific topic using subagents and save findings for review.
+
+**When to use:** When you need to gather information on a topic before planning or implementing.
+
+**Subagent use case:** Research is the APPROPRIATE use of subagents per subagent-criteria.md:
+- Task Independence: Research is self-contained
+- Clear Scope: Topic defines clear inputs/outputs
+- Parallel Value: Multiple topics can run simultaneously
+- Complexity Sweet Spot: 15-30 min per research task
+</objective>
+
+<execution_context>
+@~/.claude/drive-framework/workflows/research.md
+@~/.claude/drive-framework/references/subagent-criteria.md
+</execution_context>
+
+<context>
+Topic: $ARGUMENTS (required)
+
+Optional flags:
+- `--codebase`: Focus on codebase exploration (uses Explore agent)
+- `--web`: Focus on web/documentation (uses general-purpose agent)
+- No flag: Auto-detect based on topic
+
+@.drive/PROJECT.md
+@.drive/STATE.md
+</context>
+
+<process>
+Follow workflow: @~/.claude/drive-framework/workflows/research.md
+</process>
+
+<success_criteria>
+- [ ] Topic validated (not trivial)
+- [ ] Appropriate agent type selected
+- [ ] Subagent spawned for research
+- [ ] Findings saved to .drive/research/{topic}.md
+- [ ] Summary presented for review
+</success_criteria>

package/modules/drive/src/commands/resume.md

@@ -0,0 +1,49 @@
+---
+name: drive:resume
+description: Restore context from handoff and continue work
+argument-hint: "[optional: handoff path, e.g., '.drive/HANDOFF-phase10-audit.md']"
+allowed-tools: [Read, Glob, Bash]
+---
+
+<objective>
+Restore Drive context after a session break, determine current position, and suggest exactly ONE next action.
+
+**When to use:** Starting a new session on an existing Drive project.
+
+**Handoff lifecycle:** Detects handoffs, presents content, archives after work proceeds.
+</objective>
+
+<execution_context>
+@~/.claude/drive-framework/workflows/resume-project.md
+</execution_context>
+
+<context>
+$ARGUMENTS (optional handoff path)
+
+@.drive/STATE.md
+</context>
+
+<process>
+**Follow workflow: @~/.claude/drive-framework/workflows/resume-project.md**
+
+The workflow implements:
+1. Verify .drive/ exists
+2. Detect handoff files (use $ARGUMENTS if provided, else find most recent)
+3. Load STATE.md
+4. Present handoff content if detected
+5. Reconcile handoff vs STATE.md
+6. Determine exactly ONE next action based on loop position
+7. Display resume status with single routing
+8. After work proceeds: archive/delete consumed handoff
+
+**Key behavior:** Suggest exactly ONE next action, not multiple options.
+
+**Handoff pattern:** `.drive/HANDOFF-{context}.md` (e.g., `HANDOFF-phase10-audit.md`)
+</process>
+
+<success_criteria>
+- [ ] Context restored from STATE.md and/or handoff
+- [ ] Loop position correctly identified
+- [ ] Exactly ONE next action suggested (not multiple options)
+- [ ] User can proceed or redirect with context
+</success_criteria>

package/modules/drive/src/commands/status.md

@@ -0,0 +1,78 @@
+---
+name: drive:status
+description: "[DEPRECATED] Use /drive:progress instead"
+argument-hint:
+allowed-tools: [Read]
+---
+
+> **⚠️ DEPRECATED:** This command is deprecated. Use `/drive:progress` instead.
+>
+> `/drive:progress` provides the same information plus:
+> - Visual milestone progress
+> - Smarter routing with single next-action suggestion
+> - Optional context argument for tailored suggestions
+
+<objective>
+Display current loop position (PLAN/APPLY/UNIFY) and phase progress.
+
+**When to use:** Use `/drive:progress` instead for better routing.
+</objective>
+
+<execution_context>
+</execution_context>
+
+<context>
+@.drive/STATE.md
+@.drive/ROADMAP.md
+</context>
+
+<process>
+
+<step name="read_state">
+Read STATE.md and extract:
+- Current milestone
+- Current phase (X of Y)
+- Current plan status
+- Loop position (PLAN/APPLY/UNIFY)
+- Last activity
+</step>
+
+<step name="display_status">
+Display formatted status:
+
+```
+Drive Status
+════════════════════════════════════════
+
+Milestone: [name]
+Phase: [X of Y] ([phase name])
+Plan: [status]
+
+Loop Position:
+┌─────────────────────────────────────┐
+│  PLAN ──▶ APPLY ──▶ UNIFY          │
+│   [✓/○]    [✓/○]    [✓/○]          │
+└─────────────────────────────────────┘
+
+Last: [timestamp] — [activity]
+Next: [recommended action]
+
+════════════════════════════════════════
+```
+</step>
+
+<step name="suggest_next">
+Based on loop position, suggest next action:
+- If PLAN needed: "Run /drive:plan to create plan"
+- If PLAN ready: "Approve plan, then run /drive:apply"
+- If APPLY complete: "Run /drive:unify to close loop"
+- If UNIFY complete: "Loop closed. Ready for next phase."
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Loop position displayed clearly
+- [ ] Phase progress shown
+- [ ] Next action suggested
+</success_criteria>

package/modules/drive/src/commands/unify.md

@@ -0,0 +1,87 @@
+---
+name: drive:unify
+description: Reconcile plan vs actual and close the loop
+argument-hint: "[plan-path]"
+allowed-tools: [Read, Write, AskUserQuestion]
+---
+
+<objective>
+Reconcile plan versus actual results, create SUMMARY.md, and close the loop.
+
+**When to use:** After APPLY phase complete. This is MANDATORY - never skip UNIFY.
+
+Creates SUMMARY.md documenting what was built, decisions made, and any deferred issues.
+</objective>
+
+<execution_context>
+@~/.claude/drive-framework/workflows/unify-phase.md
+@~/.claude/drive-framework/templates/SUMMARY.md
+</execution_context>
+
+<context>
+Plan path: $ARGUMENTS
+
+@.drive/STATE.md
+@{plan-path} (the PLAN.md being unified)
+</context>
+
+<process>
+
+<step name="validate_preconditions">
+1. Confirm PLAN.md exists at $ARGUMENTS path
+2. Confirm APPLY phase was executed (tasks completed)
+3. If SUMMARY.md already exists: "Loop already closed. SUMMARY: {path}"
+</step>
+
+<step name="reconcile">
+Follow workflow: @~/.claude/drive-framework/workflows/unify-phase.md
+
+Compare plan to actual:
+- Which tasks completed as planned?
+- Any deviations from plan?
+- Decisions made during execution?
+- Issues discovered but deferred?
+</step>
+
+<step name="create_summary">
+Create SUMMARY.md in same directory as PLAN.md:
+- Document what was built
+- Record acceptance criteria results
+- Note any deferred issues
+- Capture decisions made
+- List files created/modified
+</step>
+
+<step name="update_state">
+Update STATE.md:
+- Loop position: PLAN ✓ → APPLY ✓ → UNIFY ✓
+- Phase progress if plan completes phase
+- Performance metrics (duration)
+- Session continuity (next action)
+</step>
+
+<step name="report">
+Display:
+```
+Loop Closed
+════════════════════════════════════════
+
+Plan: {plan-path}
+Summary: {summary-path}
+
+PLAN ──▶ APPLY ──▶ UNIFY
+  ✓        ✓        ✓
+
+Next: [phase complete message or next plan]
+
+════════════════════════════════════════
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] SUMMARY.md created
+- [ ] STATE.md updated with loop closure
+- [ ] User knows next action
+</success_criteria>

package/modules/drive/src/commands/verify.md

@@ -0,0 +1,60 @@
+---
+name: drive:verify
+description: Guide manual user acceptance testing of recently built features
+argument-hint: "[optional: phase or plan number, e.g., '4' or '04-02']"
+allowed-tools: [Read, Bash, Glob, Grep, Edit, Write, AskUserQuestion]
+---
+
+<objective>
+Guide the user through manual acceptance testing of recently built features.
+
+**When to use:** After completing a plan, validate that what Claude built actually works from the user's perspective.
+
+**Who tests:** The USER performs all testing. Claude generates the test checklist, guides the process, and captures issues.
+</objective>
+
+<execution_context>
+@~/.claude/drive-framework/workflows/verify-work.md
+@~/.claude/drive-framework/templates/UAT-ISSUES.md
+</execution_context>
+
+<context>
+Scope: $ARGUMENTS (optional)
+- If provided: Test specific phase or plan (e.g., "4" or "04-02")
+- If not provided: Test most recently completed plan
+
+@.drive/STATE.md
+@.drive/ROADMAP.md
+</context>
+
+<process>
+**Follow workflow: @~/.claude/drive-framework/workflows/verify-work.md**
+
+The workflow implements:
+1. Identify test scope (specified or most recent SUMMARY)
+2. Extract testable deliverables from SUMMARY.md
+3. Generate test checklist based on acceptance criteria
+4. Guide user through each test via AskUserQuestion
+5. Collect and categorize any issues found
+6. Log issues to phase-scoped UAT file
+7. Present summary with verdict
+8. Offer next steps based on results
+</process>
+
+<success_criteria>
+- [ ] Test scope identified from SUMMARY.md
+- [ ] Checklist generated based on deliverables
+- [ ] User guided through each test
+- [ ] All test results captured (pass/fail/partial/skip)
+- [ ] Any issues logged to `.drive/phases/XX-name/{plan}-UAT.md`
+- [ ] Summary presented with verdict
+- [ ] User knows next steps based on results
+</success_criteria>
+
+<anti_patterns>
+- Don't run automated tests (that's for CI/test suites)
+- Don't make assumptions about test results — USER reports outcomes
+- Don't skip the guidance — walk through each test
+- Don't dismiss minor issues — log everything user reports
+- Don't fix issues during testing — capture for later
+</anti_patterns>

package/modules/drive/src/references/checkpoints.md

@@ -0,0 +1,234 @@
+<checkpoints>
+
+## Purpose
+
+Checkpoints formalize interaction points where human verification or decisions are needed during plan execution. Plans execute autonomously except at checkpoints.
+
+**Core principle:** Claude automates everything with CLI/API. Checkpoints are for verification and decisions, not manual work.
+
+**Golden rule:** If Claude CAN automate it, Claude MUST automate it.
+
+## Checkpoint Types
+
+### checkpoint:human-verify (90% of checkpoints)
+
+**When:** Claude completed automated work, human confirms it works correctly.
+
+**Use for:** Visual UI checks, interactive flows, functional verification, audio/video quality, animation smoothness, accessibility testing.
+
+**Structure:**
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>[What Claude automated]</what-built>
+  <how-to-verify>
+    1. [First verification step]
+    2. [Second verification step]
+    3. [Expected behavior to confirm]
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+
+**Example:**
+```xml
+<task type="checkpoint:human-verify" gate="blocking">
+  <what-built>Responsive dashboard with sidebar navigation</what-built>
+  <how-to-verify>
+    1. Run: npm run dev
+    2. Visit: http://localhost:3000/dashboard
+    3. Desktop (>1024px): Sidebar visible on left
+    4. Mobile (375px): Sidebar collapses to hamburger menu
+    5. Check: No layout shift, smooth transitions
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+```
+
+### checkpoint:decision (9% of checkpoints)
+
+**When:** Human must make choice that affects implementation direction.
+
+**Use for:** Technology selection, architecture decisions, design choices, feature prioritization.
+
+**Structure:**
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>[What's being decided]</decision>
+  <context>[Why this matters]</context>
+  <options>
+    <option id="option-a">
+      <name>[Name]</name>
+      <pros>[Benefits]</pros>
+      <cons>[Tradeoffs]</cons>
+    </option>
+    <option id="option-b">
+      <name>[Name]</name>
+      <pros>[Benefits]</pros>
+      <cons>[Tradeoffs]</cons>
+    </option>
+  </options>
+  <resume-signal>Select: option-a or option-b</resume-signal>
+</task>
+```
+
+**Example:**
+```xml
+<task type="checkpoint:decision" gate="blocking">
+  <decision>Select state management approach</decision>
+  <context>Dashboard needs client-side state. Two viable approaches:</context>
+  <options>
+    <option id="zustand">
+      <name>Zustand</name>
+      <pros>Lightweight, simple API, no boilerplate</pros>
+      <cons>Less structure for large apps</cons>
+    </option>
+    <option id="context">
+      <name>React Context + useReducer</name>
+      <pros>No dependencies, built-in</pros>
+      <cons>More boilerplate, potential re-render issues</cons>
+    </option>
+  </options>
+  <resume-signal>Select: zustand or context</resume-signal>
+</task>
+```
+
+### checkpoint:human-action (1% - rare)
+
+**When:** Action has NO CLI/API and requires human-only interaction.
+
+**Use ONLY for:**
+- Email verification links
+- SMS 2FA codes
+- Manual account approvals
+- 3D Secure payment flows
+- OAuth app approvals
+
+**Do NOT use for:**
+- Deployments (use CLI)
+- Creating resources (use CLI/API)
+- Builds/tests (use Bash)
+- File operations (use Write/Edit)
+
+**Structure:**
+```xml
+<task type="checkpoint:human-action" gate="blocking">
+  <action>[Unavoidable manual step]</action>
+  <instructions>
+    [What Claude already automated]
+    [The ONE thing requiring human action]
+  </instructions>
+  <verification>[What Claude checks afterward]</verification>
+  <resume-signal>Type "done" when complete</resume-signal>
+</task>
+```
+
+## Execution Protocol
+
+When executing a plan encounters `type="checkpoint:*"`:
+
+1. **Stop immediately** — do not proceed to next task
+2. **Display checkpoint clearly** with visual separator
+3. **Wait for user response** — instead of proceeding on assumptions, because unverified checkpoints accumulate into larger failures that are harder to diagnose
+4. **Verify if possible** — check files, run tests after human action
+5. **Resume execution** — continue only after confirmation
+
+## Diagnostic Failure Routing
+
+When a checkpoint:human-verify receives failure reports OR when `/drive:verify` finds issues, classify the root cause BEFORE attempting fixes — instead of patching immediately, because wrong-layer fixes produce fragile patches that break again.
+
+**Classification:**
+
+| Type | Signal | Routing |
+|---|---|---|
+| **Intent** | "I need something different than what was planned" | Archive plan, re-plan the phase with updated intent |
+| **Spec** | "The plan missed something or got it wrong" | Update ACs/tasks at the spec level before generating code fixes |
+| **Code** | "The plan was right, implementation doesn't match" | Standard fix-in-place — patch code, re-verify |
+
+**Where this applies:**
+- **During APPLY:** checkpoint:human-verify failures (see apply-phase.md)
+- **After APPLY:** /drive:verify UAT failures (see verify-work.md)
+
+**Why classification matters:**
+- Intent wrong + code patch = fix that contradicts what the user actually wants
+- Spec wrong + code patch = fix that contradicts the plan, making UNIFY reconciliation unreliable
+- Code wrong + code patch = correct response — this is the only case where patching is the right move
+
+**Anti-pattern:** Jumping straight to code patches without classifying. Claude's default under pressure is to patch code because it's the fastest visible action — but speed at the wrong layer creates more work than pausing to classify.
+
+## Authentication Gates
+
+When Claude tries CLI/API and gets auth error, this is NOT a failure - it's a gate requiring human input to unblock automation.
+
+**Pattern:** Claude tries automation → auth error → creates dynamic checkpoint → human authenticates → Claude retries → continues
+
+**Key distinction:**
+- Pre-planned checkpoint: "I need you to deploy" (WRONG - Claude should automate)
+- Auth gate: "I tried to deploy but need credentials" (CORRECT - unblocks automation)
+
+## Guidelines
+
+**DO:**
+- Automate everything with CLI/API before checkpoint
+- Be specific: "Visit https://myapp.vercel.app" not "check deployment"
+- Number verification steps
+- State expected outcomes
+- Make verification executable
+
+**DON'T:**
+- Ask human to do work Claude can automate
+- Assume knowledge: "Configure the usual settings"
+- Mix multiple verifications in one checkpoint
+- Use checkpoints too frequently (verification fatigue)
+
+**Placement:**
+- After automation completes (not before)
+- After UI buildout
+- Before dependent work (decisions)
+- At integration points
+
+## Anti-Patterns
+
+**BAD: Asking human to automate**
+```xml
+<task type="checkpoint:human-action">
+  <action>Deploy to Vercel</action>
+  <instructions>Visit vercel.com/new, import repo, click Deploy</instructions>
+</task>
+```
+Why bad: Vercel has CLI. Use `vercel --yes`.
+
+**BAD: Too many checkpoints**
+```xml
+<task type="auto">Create schema</task>
+<task type="checkpoint:human-verify">Check schema</task>
+<task type="auto">Create API</task>
+<task type="checkpoint:human-verify">Check API</task>
+```
+Why bad: Verification fatigue. Combine into one checkpoint at end.
+
+**GOOD: Claude automates, human verifies once**
+```xml
+<task type="auto">Create schema</task>
+<task type="auto">Create API</task>
+<task type="auto">Create UI</task>
+
+<task type="checkpoint:human-verify">
+  <what-built>Complete auth flow</what-built>
+  <how-to-verify>Test full flow: register, login, access protected page</how-to-verify>
+</task>
+```
+
+## Summary
+
+| Type | % Used | Purpose |
+|------|--------|---------|
+| checkpoint:human-verify | 90% | Claude automated, human confirms visual/functional |
+| checkpoint:decision | 9% | Human makes architectural/technology choice |
+| checkpoint:human-action | 1% | Truly unavoidable manual step (no API/CLI) |
+
+**When NOT to use checkpoints:**
+- Things Claude can verify programmatically (tests, builds)
+- File operations (Claude can read/write)
+- Anything with CLI/API available
+
+</checkpoints>