@accelerationguy/accel 1.0.0

package/modules/drive/README.md

@@ -0,0 +1,555 @@
+<div align="center">
+
+# Drive
+
+**Plan-Apply-Unify Loop** — Structured AI-assisted development for Claude Code.
+
+[![npm version](https://img.shields.io/npm/v/drive-framework?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/drive-framework)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/accelerationguy/drive?style=for-the-badge&logo=github&color=181717)](https://github.com/accelerationguy/drive)
+
+<br>
+
+```bash
+npx drive-framework
+```
+
+**Works on Mac, Windows, and Linux.**
+
+<br>
+
+![Drive Install](assets/terminal.svg)
+
+<br>
+
+*"Quality over speed-for-speed's-sake. In-session context over subagent sprawl."*
+
+<br>
+
+[Why Drive](#why-drive) · [Getting Started](#getting-started) · [The Loop](#the-loop) · [Commands](#commands) · [How It Works](#how-it-works)
+
+</div>
+
+---
+
+## Why Drive
+
+I build with Claude Code every day. It's incredibly powerful — when you give it the right context.
+
+The problem? **Context rot.** As your session fills up, quality degrades. Subagents spawn with fresh context but return ~70% quality work that needs cleanup. Plans get created but never closed. State drifts. You end up debugging AI output instead of shipping features.
+
+Drive fixes this with three principles:
+
+1. **Loop integrity** — Every plan closes with UNIFY. No orphan plans. UNIFY reconciles what was planned vs what happened, updates state, logs decisions. This is the heartbeat.
+
+2. **In-session context** — Subagents are expensive and produce lower quality for implementation work. Drive keeps development in-session with properly managed context. Subagents are reserved for discovery and research — their job IS to gather context.
+
+3. **Acceptance-driven development** — Acceptance criteria are first-class citizens, not afterthoughts. Define done before starting. Every task references its AC. BDD format: `Given [precondition] / When [action] / Then [outcome]`.
+
+The complexity is in the system, not your workflow. Behind the scenes: structured state management, XML task formatting, loop enforcement. What you see: a few commands that keep you on track.
+
+---
+
+## Who This Is For
+
+**Builders who use AI to ship** — software, campaigns, workflows, automations, anything that benefits from structured execution.
+
+Drive isn't just for code. It manages marketing campaigns, funnel builds, email sequences, and automation workflows with the same rigor it brings to software development.
+
+You describe what you want, Claude Code builds it, and Drive ensures:
+- **Init gathers real requirements** — type-adapted walkthrough produces a populated project brief, not empty placeholders
+- Plans have clear acceptance criteria
+- **Every task is qualified against the spec** — not just executed and assumed correct
+- Execution stays bounded with explicit scope control
+- Every unit of work gets closed properly
+- State persists across sessions
+- Decisions are logged for future reference
+
+No sprint ceremonies. No story points. No enterprise theater. Just a system that keeps AI-assisted development reliable.
+
+---
+
+## Getting Started
+
+```bash
+npx drive-framework
+```
+
+The installer prompts you to choose:
+1. **Location** — Global (all projects) or local (current project only)
+
+Verify with `/drive:help` inside Claude Code.
+
+### Quick Workflow
+
+```bash
+# 1. Initialize Drive in your project
+#    Walks through type-adapted requirements (app, campaign, workflow)
+#    Produces a populated PROJECT.md — not empty placeholders
+/drive:init
+
+# 2. Create a plan for your work
+#    Auto-detects scope: quick-fix, standard, or complex
+#    Validates coherence against project context before approval
+/drive:plan
+
+# 3. Execute the approved plan
+#    Each task goes through Execute/Qualify loop
+#    Escalation statuses: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED
+/drive:apply
+
+# 4. Close the loop (required!)
+/drive:unify
+
+# 5. Check progress anytime
+/drive:progress
+```
+
+### Staying Updated
+
+```bash
+npx drive-framework@latest
+```
+
+<details>
+<summary><strong>Non-interactive Install</strong></summary>
+
+```bash
+npx drive-framework --global   # Install to ~/.claude/
+npx drive-framework --local    # Install to ./.claude/
+```
+
+</details>
+
+---
+
+## The Loop
+
+Every unit of work follows this cycle:
+
+```
+┌─────────────────────────────────────┐
+│  PLAN ──▶ APPLY ──▶ UNIFY          │
+│                                     │
+│  Define    Execute    Reconcile     │
+│  work      tasks      & close       │
+└─────────────────────────────────────┘
+```
+
+### PLAN
+
+Create an executable plan with scope-adaptive ceremony:
+
+- **Quick-fix** (1 file, 1 change) — Compressed: objective + 1 task + 1 AC. Full loop, minimal ceremony.
+- **Standard** (2-5 tasks) — Full plan with boundaries, multiple ACs, verification checklist.
+- **Complex** (6+ tasks) — Full plan + actively recommends splitting.
+
+All plans include:
+- **Objective** — What you're building and why
+- **Acceptance Criteria** — Given/When/Then definitions of done
+- **Tasks** — Specific actions with files, verification, done criteria
+- **Boundaries** — What NOT to change (standard/complex only)
+- **Coherence validation** — Auto-checked against project context before approval
+
+### APPLY
+
+Execute the approved plan with built-in quality enforcement:
+- Tasks follow an **Execute/Qualify loop** — after execution, each task is independently verified against the spec and linked acceptance criteria before moving on
+- **Escalation statuses** give nuance beyond pass/fail: DONE, DONE_WITH_CONCERNS, NEEDS_CONTEXT, BLOCKED
+- Checkpoints pause for human input when needed — with **diagnostic failure routing** that classifies issues as intent, spec, or code before attempting fixes
+- Anti-rationalization enforcement prevents false completion claims
+
+### UNIFY
+
+Close the loop (required!):
+- Create SUMMARY.md documenting what was built
+- Compare plan vs actual
+- Record decisions and deferred issues
+- Update STATE.md
+
+**Never skip UNIFY.** Every plan needs closure. This is what separates structured development from chaos.
+
+---
+
+## Commands
+
+Drive provides 26 commands organized by purpose. Run `/drive:help` for the complete reference.
+
+### Core Loop
+
+| Command | What it does |
+|---------|--------------|
+| `/drive:init` | Initialize Drive with type-adapted requirements walkthrough |
+| `/drive:plan [phase]` | Create an executable plan (auto-routes quick-fix/standard/complex) |
+| `/drive:apply [path]` | Execute an approved plan |
+| `/drive:unify [path]` | Reconcile and close the loop |
+| `/drive:help` | Show command reference |
+| `/drive:status` | Show loop position *(deprecated — use progress)* |
+
+### Session
+
+| Command | What it does |
+|---------|--------------|
+| `/drive:pause [reason]` | Create handoff for session break |
+| `/drive:resume [path]` | Restore context and continue |
+| `/drive:progress [context]` | Smart status + ONE next action |
+| `/drive:handoff [context]` | Generate comprehensive handoff |
+
+### Roadmap
+
+| Command | What it does |
+|---------|--------------|
+| `/drive:add-phase <desc>` | Append phase to roadmap |
+| `/drive:remove-phase <N>` | Remove future phase |
+
+### Milestone
+
+| Command | What it does |
+|---------|--------------|
+| `/drive:milestone <name>` | Create new milestone |
+| `/drive:complete-milestone` | Archive and tag milestone |
+| `/drive:discuss-milestone` | Articulate vision before starting |
+
+### Pre-Planning
+
+| Command | What it does |
+|---------|--------------|
+| `/drive:discuss <phase>` | Capture decisions before planning |
+| `/drive:assumptions <phase>` | See Claude's intended approach |
+| `/drive:discover <topic>` | Explore options before planning |
+| `/drive:consider-issues` | Triage deferred issues |
+
+### Research
+
+| Command | What it does |
+|---------|--------------|
+| `/drive:research <topic>` | Deploy research agents |
+| `/drive:research-phase <N>` | Research unknowns for a phase |
+
+### Specialized
+
+| Command | What it does |
+|---------|--------------|
+| `/drive:flows` | Configure skill requirements |
+| `/drive:config` | View/modify Drive settings |
+| `/drive:map-codebase` | Generate codebase overview |
+
+### Quality
+
+| Command | What it does |
+|---------|--------------|
+| `/drive:verify` | Guide manual acceptance testing |
+| `/drive:plan-fix` | Plan fixes for UAT issues |
+
+---
+
+## How It Works
+
+### Project Structure
+
+```
+.drive/
+├── PROJECT.md           # Project context and requirements
+├── ROADMAP.md           # Phase breakdown and milestones
+├── STATE.md             # Loop position and session state
+├── config.md            # Optional integrations
+├── SPECIAL-FLOWS.md     # Optional skill requirements
+└── phases/
+    ├── 01-foundation/
+    │   ├── 01-01-PLAN.md
+    │   └── 01-01-SUMMARY.md
+    └── 02-features/
+        ├── 02-01-PLAN.md
+        └── 02-01-SUMMARY.md
+```
+
+### State Management
+
+**STATE.md** tracks:
+- Current phase and plan
+- Loop position (PLAN/APPLY/UNIFY markers)
+- Session continuity (where you stopped, what's next)
+- Accumulated decisions
+- Blockers and deferred issues
+
+When you resume work, `/drive:resume` reads STATE.md and suggests exactly ONE next action. No decision fatigue.
+
+### PLAN.md Structure
+
+```markdown
+---
+phase: 01-foundation
+plan: 01
+type: execute
+autonomous: true
+---
+
+<objective>
+Goal, Purpose, Output
+</objective>
+
+<context>
+@-references to relevant files
+</context>
+
+<acceptance_criteria>
+## AC-1: Feature Works
+Given [precondition]
+When [action]
+Then [outcome]
+</acceptance_criteria>
+
+<tasks>
+<task type="auto">
+  <name>Create login endpoint</name>
+  <files>src/api/auth/login.ts</files>
+  <action>Implementation details...</action>
+  <verify>curl command returns 200</verify>
+  <done>AC-1 satisfied</done>
+</task>
+</tasks>
+
+<boundaries>
+## DO NOT CHANGE
+- database/migrations/*
+- src/lib/auth.ts
+</boundaries>
+```
+
+Every task has: files, action, verify, done. If you can't specify all four, the task is too vague.
+
+### Vector Integration
+
+Drive has a companion: **[Vector](https://github.com/accelerationguy/vector-core)** (Context Augmentation & Reinforcement Layer).
+
+Vector is a dynamic rule injection system. Instead of bloating your context with static prompts, Vector loads rules just-in-time based on what you're doing:
+
+| Trigger | Rules Loaded |
+|---------|--------------|
+| Working in `.drive/` directory | Drive domain activates |
+| Writing code | DEVELOPMENT rules load |
+| Managing projects | PROJECTS rules load |
+
+**Drive-specific rules Vector enforces:**
+- Loop enforcement (PLAN → APPLY → UNIFY — no shortcuts)
+- Boundary protection (DO NOT CHANGE sections are real)
+- State consistency checks at phase transitions
+- Verification requirements for every task
+- Skill blocking (required skills must load before APPLY)
+
+The Drive domain contains 14 rules that govern structured AI development. They load when you're in a Drive project, disappear when you're not. Your context stays lean.
+
+**Without Vector:** You'd need massive static prompts in every session.
+**With Vector:** Rules activate when relevant, disappear when not.
+
+---
+
+## Quality Enforcement
+
+Drive doesn't just plan and execute — it verifies. These systems work together to catch problems early, before they compound.
+
+### Execute/Qualify Loop
+
+Every task in the APPLY phase goes through an E/Q loop:
+
+```
+Execute → Report Status → Qualify Against Spec → (fix gaps) → Next Task
+```
+
+The **Qualify** step independently re-reads what was actually produced and compares it against the task spec and acceptance criteria. This catches drift, missing requirements, and false completions that would otherwise pass unnoticed until UNIFY — when it's too late.
+
+### Escalation Statuses
+
+Tasks report one of four statuses instead of binary pass/fail:
+
+| Status | Meaning |
+|---|---|
+| **DONE** | Completed, no concerns |
+| **DONE_WITH_CONCERNS** | Completed, but flagged doubts for review |
+| **NEEDS_CONTEXT** | Can't complete — missing information |
+| **BLOCKED** | Can't complete — structural impediment |
+
+This surfaces uncertainty honestly instead of silently swallowing it.
+
+### Diagnostic Failure Routing
+
+When a checkpoint fails or UAT finds issues, Drive classifies the root cause before attempting any fix:
+
+- **Intent issue** — Need to build something different → re-plan the phase
+- **Spec issue** — Plan was missing/wrong → fix the spec before patching code
+- **Code issue** — Plan was right, code doesn't match → standard fix-in-place
+
+This prevents the common failure mode of patching code when the plan itself was wrong.
+
+### Coherence Check
+
+Before presenting any plan for approval, Drive automatically validates it against:
+- PROJECT.md constraints
+- Accumulated decisions in STATE.md
+- Files modified in recent plans
+- ROADMAP.md phase scope
+
+Issues get flagged before approval. Clean plans pass silently with zero friction.
+
+---
+
+## Philosophy
+
+### Acceptance-Driven Development (A.D.D.)
+
+Acceptance criteria aren't afterthoughts — they're the foundation:
+
+1. **AC defined before tasks** — Know what "done" means
+2. **Tasks reference AC** — Every task links to AC-1, AC-2, etc.
+3. **Verification required** — Every task needs a verify step
+4. **BDD format** — Given/When/Then for testability
+
+### In-Session Context
+
+Why Drive minimizes subagents for development work:
+
+| Issue | Impact |
+|-------|--------|
+| Launch cost | 2,000-3,000 tokens to spawn |
+| Context gathering | Starts fresh, researches from scratch |
+| Resynthesis | Results must be integrated back |
+| Quality gap | ~70% compared to in-session work |
+| Rework | Subagent output often needs cleanup |
+
+**When Drive does use subagents:**
+- **Discovery/exploration** — Codebase mapping, parallel exploration
+- **Research** — Web searches, documentation gathering
+
+For implementation, Drive keeps everything in-session with proper context management.
+
+### Loop Integrity
+
+The loop isn't optional:
+
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+  ✓        ✓        ✓     [Loop complete]
+```
+
+- **No orphan plans** — Every PLAN gets a SUMMARY
+- **State reconciliation** — UNIFY catches drift
+- **Decision logging** — Choices are recorded for future sessions
+
+---
+
+## Configuration
+
+### Optional Integrations
+
+Drive supports modular integrations configured in `.drive/config.md`:
+
+| Integration | Purpose |
+|-------------|---------|
+| SonarQube | Code quality metrics and issues |
+| *Future* | Linting, CI/CD, test runners |
+
+### SPECIAL-FLOWS
+
+For projects with specialized requirements, `.drive/SPECIAL-FLOWS.md` defines skills that must be loaded before execution:
+
+```markdown
+## Required Skills
+
+| Skill | Work Type | Priority |
+|-------|-----------|----------|
+| /frontend-design | UI components | required |
+| /revops-expert | Landing pages | required |
+```
+
+APPLY blocks until required skills are confirmed loaded.
+
+---
+
+## Troubleshooting
+
+**Commands not found after install?**
+- Restart Claude Code to reload slash commands
+- Verify files exist in `~/.claude/commands/drive/` (global) or `./.claude/commands/drive/` (local)
+
+**Commands not working as expected?**
+- Run `/drive:help` to verify installation
+- Re-run `npx drive-framework` to reinstall
+
+**Loop position seems wrong?**
+- Check `.drive/STATE.md` for current state
+- Run `/drive:progress` for guided next action
+
+**Resuming after a break?**
+- Run `/drive:resume` — it reads state and handoffs automatically
+
+---
+
+## Comparison
+
+### vs. Ad-hoc AI Coding
+
+| Ad-hoc | Drive |
+|--------|------|
+| No structure | Explicit planning gates |
+| State drifts | STATE.md tracks everything |
+| No closure | Mandatory UNIFY |
+| Decisions lost | Decisions logged |
+
+### vs. GSD
+
+Drive takes a different approach from GSD:
+
+| Aspect | GSD | Drive |
+|--------|-----|------|
+| Execution | Parallel subagents | In-session context |
+| Loop | Optional closure | Mandatory UNIFY |
+| Criteria | Embedded in tasks | First-class AC section |
+| Rules | Static prompts | Vector dynamic loading |
+
+Same comprehensive coverage, different philosophy. Drive prioritizes quality over speed-for-speed's-sake. See [Drive-VS-GSD.md](Drive-VS-GSD.md) for full comparison.
+
+### vs. Traditional Planning
+
+| Traditional | Drive |
+|-------------|------|
+| Documentation-first | Execution-first |
+| Human-readable specs | AI-executable prompts |
+| Separate from code | Colocated in .drive/ |
+
+---
+
+## Ecosystem
+
+Drive is part of a broader Claude Code extension ecosystem:
+
+| System | What It Does | Link |
+|--------|-------------|------|
+| **Radar** | Multi-agent codebase auditing — diagnosis + controlled evolution | [GitHub](https://github.com/accelerationguy/radar) |
+| **Momentum** | Builder's Automated State Engine — workspace lifecycle, health tracking, drift prevention | [GitHub](https://github.com/accelerationguy/base) |
+| **Vector** | Context Augmentation & Reinforcement Layer — dynamic rules loaded JIT by intent | [GitHub](https://github.com/accelerationguy/vector) |
+| **Drive** | Project orchestration — Plan, Apply, Unify Loop | You are here |
+| **Ignition** | Typed project incubator — guided ideation through graduation into buildable projects | [GitHub](https://github.com/accelerationguy/ignition) |
+| **Forge** | Skill builder — standardized syntax specs + guided workflows for Claude Code skills | [GitHub](https://github.com/accelerationguy/forge) |
+| **CC Strategic AI** | Skool community — courses, community, live support | [Skool](https://accelerationguy.com) |
+
+---
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+---
+
+## Author
+
+**Acceleration Guy** — [Chris AI Systems](https://github.com/accelerationguy)
+
+Building tools for AI-assisted development.
+
+---
+
+<div align="center">
+
+**Claude Code is powerful. Drive makes it reliable.**
+
+</div>

package/modules/drive/assets/terminal.svg

@@ -0,0 +1,67 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 540">
+  <defs>
+    <style>
+      .terminal-bg { fill: #1a1b26; }
+      .terminal-border { fill: #24283b; }
+      .title-bar { fill: #1f2335; }
+      .btn-red { fill: #f7768e; }
+      .btn-yellow { fill: #e0af68; }
+      .btn-green { fill: #9ece6a; }
+      .text { font-family: 'SF Mono', 'Fira Code', 'JetBrains Mono', Consolas, monospace; }
+      .prompt { fill: #7aa2f7; }
+      .command { fill: #c0caf5; }
+      .cyan { fill: #7dcfff; }
+      .green { fill: #9ece6a; }
+      .dim { fill: #565f89; }
+      .white { fill: #c0caf5; }
+    </style>
+  </defs>
+
+  <!-- Window -->
+  <rect class="terminal-border" width="960" height="540" rx="12"/>
+  <rect class="terminal-bg" x="1" y="1" width="958" height="538" rx="11"/>
+
+  <!-- Title bar -->
+  <rect class="title-bar" x="1" y="1" width="958" height="36" rx="11"/>
+  <rect class="terminal-bg" x="1" y="26" width="958" height="12"/>
+
+  <!-- Window buttons -->
+  <circle class="btn-red" cx="24" cy="19" r="7"/>
+  <circle class="btn-yellow" cx="48" cy="19" r="7"/>
+  <circle class="btn-green" cx="72" cy="19" r="7"/>
+
+  <!-- Title -->
+  <text x="480" y="24" text-anchor="middle" class="text dim" font-size="13">Terminal</text>
+
+  <!-- Content -->
+  <g transform="translate(32, 72)">
+    <!-- Prompt line -->
+    <text class="text prompt" font-size="15" y="0">~</text>
+    <text class="text dim" font-size="15" x="16" y="0">$</text>
+    <text class="text command" font-size="15" x="36" y="0">npx /cli</text>
+
+    <!-- Banner -->
+    <text class="text cyan" font-size="14" y="48" xml:space="preserve">  ██████╗  █████╗ ██╗   ██╗██╗</text>
+    <text class="text cyan" font-size="14" y="68" xml:space="preserve">  ██╔══██╗██╔══██╗██║   ██║██║</text>
+    <text class="text cyan" font-size="14" y="88" xml:space="preserve">  ██████╔╝███████║██║   ██║██║</text>
+    <text class="text cyan" font-size="14" y="108" xml:space="preserve">  ██╔═══╝ ██╔══██║██║   ██║██║</text>
+    <text class="text cyan" font-size="14" y="128" xml:space="preserve">  ██║     ██║  ██║╚██████╔╝███████╗</text>
+    <text class="text cyan" font-size="14" y="148" xml:space="preserve">  ╚═╝     ╚═╝  ╚═╝ ╚═════╝ ╚══════╝</text>
+
+    <!-- Title and subtitle -->
+    <text class="text white" font-size="15" y="188">  Drive <tspan class="dim">v0.1.0</tspan></text>
+    <text class="text white" font-size="15" y="212">  Plan-Apply-Unify Loop for Claude Code</text>
+
+    <!-- Install output -->
+    <text class="text" font-size="15" y="260"><tspan class="green">  ✓</tspan><tspan class="white"> Installed commands/drive</tspan></text>
+    <text class="text" font-size="15" y="284"><tspan class="green">  ✓</tspan><tspan class="white"> Installed Accelerate Drive</tspan></text>
+
+    <!-- Done message -->
+    <text class="text" font-size="15" y="332"><tspan class="green">  Done!</tspan><tspan class="white"> Run </tspan><tspan class="cyan">/drive:help</tspan><tspan class="white"> to get started.</tspan></text>
+
+    <!-- New prompt -->
+    <text class="text prompt" font-size="15" y="380">~</text>
+    <text class="text dim" font-size="15" x="16" y="380">$</text>
+    <text class="text white" font-size="15" x="36" y="380">▌</text>
+  </g>
+</svg>