@accelerationguy/accel 1.0.0

package/modules/drive/src/references/plan-format.md

@@ -0,0 +1,263 @@
+<plan_format>
+
+## Purpose
+
+PLAN.md IS the executable prompt. It contains everything needed to execute a phase: objective, context, acceptance criteria, tasks, boundaries, verification, and output specification.
+
+**Core principle:** A plan is Claude-executable when Claude can read the PLAN.md and immediately start implementing without asking clarifying questions.
+
+If Claude has to guess, interpret, or make assumptions - the task is too vague.
+
+## Frontmatter
+
+Every PLAN.md starts with YAML frontmatter:
+
+```yaml
+---
+phase: XX-name
+plan: NN
+type: execute
+wave: N
+depends_on: []
+files_modified: []
+autonomous: true
+---
+```
+
+| Field | Required | Purpose |
+|-------|----------|---------|
+| `phase` | Yes | Phase identifier (e.g., `02-rules-layer`) |
+| `plan` | Yes | Plan number within phase (e.g., `01`, `02`) |
+| `type` | Yes | `execute` for standard, `tdd` for test-driven, `research` for exploration |
+| `wave` | Yes | Execution wave number (pre-computed at plan time) |
+| `depends_on` | Yes | Array of plan IDs this plan requires |
+| `files_modified` | Yes | Files this plan touches (for conflict detection) |
+| `autonomous` | Yes | `true` if no checkpoints, `false` if has checkpoints |
+
+## Plan Structure
+
+```markdown
+---
+[frontmatter]
+---
+
+<objective>
+## Goal
+[What this plan accomplishes - specific, measurable]
+
+## Purpose
+[Why this matters for the project]
+
+## Output
+[What artifacts will be created/modified]
+</objective>
+
+<context>
+@.drive/PROJECT.md
+@.drive/ROADMAP.md
+@.drive/STATE.md
+@relevant/source/files.ts
+</context>
+
+<acceptance_criteria>
+## AC-1: [Criterion Name]
+Given [precondition]
+When [action]
+Then [expected outcome]
+</acceptance_criteria>
+
+<tasks>
+[Task definitions]
+</tasks>
+
+<boundaries>
+## DO NOT CHANGE
+[Protected files/patterns]
+
+## SCOPE LIMITS
+[What's explicitly out of scope]
+</boundaries>
+
+<verification>
+[Overall phase checks]
+</verification>
+
+<success_criteria>
+[Measurable completion criteria]
+</success_criteria>
+
+<output>
+[SUMMARY.md specification]
+</output>
+```
+
+## Task Anatomy
+
+Every `auto` task has four required fields:
+
+### files
+**What it is:** Exact file paths created or modified.
+
+```xml
+<!-- GOOD -->
+<files>src/app/api/auth/login/route.ts, prisma/schema.prisma</files>
+
+<!-- BAD -->
+<files>the auth files, relevant components</files>
+```
+
+### action
+**What it is:** Specific implementation instructions, including what to avoid and WHY.
+
+```xml
+<!-- GOOD -->
+<action>
+  Create POST endpoint accepting {email, password}.
+  Query User by email, compare password with bcrypt.
+  On match, create JWT with jose library (15-min expiry).
+  Return 200. On mismatch, return 401.
+  Avoid: jsonwebtoken (CommonJS issues with Edge runtime)
+</action>
+
+<!-- BAD -->
+<action>Add authentication</action>
+```
+
+### verify
+**What it is:** How to prove the task is complete.
+
+```xml
+<!-- GOOD -->
+<verify>curl -X POST localhost:3000/api/auth/login returns 200 with Set-Cookie header</verify>
+
+<!-- BAD -->
+<verify>It works</verify>
+```
+
+### done
+**What it is:** Acceptance criteria - links to AC-N for traceability.
+
+```xml
+<!-- GOOD -->
+<done>AC-1 satisfied: Valid credentials return 200 + JWT cookie</done>
+
+<!-- BAD -->
+<done>Authentication is complete</done>
+```
+
+**If you can't specify Files + Action + Verify + Done, the task is too vague.**
+
+## Acceptance Criteria Format
+
+Use Given/When/Then (BDD) format:
+
+```gherkin
+Given [precondition / initial state]
+When [action / trigger]
+Then [expected outcome]
+```
+
+**Guidelines:**
+- Each criterion should be independently testable
+- Include error states and edge cases
+- Avoid implementation details (describe behavior, not code)
+- Link tasks to criteria via `<done>AC-N satisfied</done>`
+
+## Boundaries Section
+
+Drive plans include explicit boundaries:
+
+```markdown
+<boundaries>
+## DO NOT CHANGE
+- database/migrations/* (schema locked for this phase)
+- src/lib/auth.ts (auth system stable)
+
+## SCOPE LIMITS
+- This plan creates API only - no UI
+- Do not add new dependencies
+</boundaries>
+```
+
+Boundaries prevent scope creep by making off-limits areas explicit.
+
+## Specificity Levels
+
+### Too Vague
+```xml
+<task type="auto">
+  <name>Add authentication</name>
+  <files>???</files>
+  <action>Implement auth</action>
+  <verify>???</verify>
+  <done>Users can authenticate</done>
+</task>
+```
+Claude: "How? What type? What library? Where?"
+
+### Just Right
+```xml
+<task type="auto">
+  <name>Create login endpoint with JWT</name>
+  <files>src/app/api/auth/login/route.ts</files>
+  <action>
+    POST endpoint accepting {email, password}.
+    Query User by email, compare password with bcrypt.
+    On match, create JWT with jose (15-min expiry).
+    Return 200. On mismatch, return 401.
+  </action>
+  <verify>curl -X POST returns 200 with Set-Cookie header</verify>
+  <done>AC-1 satisfied: Valid credentials → 200 + cookie</done>
+</task>
+```
+Claude can implement immediately.
+
+### Too Detailed
+Writing the actual code in the plan. Trust Claude to implement from clear instructions.
+
+## Sizing Guidance
+
+**Good plan size:** 2-3 tasks, ~50% context usage, single concern.
+
+**When to split into multiple plans:**
+- Different subsystems (auth vs API vs UI)
+- More than 3 tasks
+- Risk of context overflow
+- TDD candidates (separate plans)
+
+**Prefer vertical slices:**
+```
+PREFER: Plan 01 = User (model + API + UI)
+        Plan 02 = Product (model + API + UI)
+
+AVOID:  Plan 01 = All models
+        Plan 02 = All APIs
+```
+
+## Anti-Patterns
+
+**Vague actions:**
+- "Set up the infrastructure"
+- "Handle edge cases"
+- "Make it production-ready"
+
+**Unverifiable completion:**
+- "It works correctly"
+- "User experience is good"
+- "Code is clean"
+
+**Missing context:**
+- "Use the standard approach"
+- "Follow best practices"
+- "Like the other endpoints"
+
+**Reflexive dependencies:**
+```yaml
+# BAD - chaining just because sequential
+depends_on: ["01-01"]  # Plan 02 doesn't actually need 01's output
+
+# GOOD - genuine dependency
+depends_on: ["01-01"]  # Plan 02 imports User type from 01-01
+```
+
+</plan_format>

package/modules/drive/src/references/quality-principles.md

@@ -0,0 +1,152 @@
+<principles>
+Core principles for the Drive development workflow.
+
+<solo_developer_claude>
+
+You are planning for ONE person (the user) and ONE implementer (Claude).
+- No teams, stakeholders, ceremonies, coordination overhead
+- User is the visionary/product owner
+- Claude is the builder
+- Estimate effort in context usage, not human dev time
+</solo_developer_claude>
+
+<plans_are_prompts>
+
+PLAN.md is not a document that gets transformed into a prompt.
+PLAN.md IS the prompt. It contains:
+- Objective (what and why)
+- Context (@file references)
+- Acceptance Criteria (measurable outcomes)
+- Tasks (with verification criteria)
+- Boundaries (explicit scope control)
+
+When planning, you are writing the prompt that will execute it.
+</plans_are_prompts>
+
+<loop_first>
+
+Every PLAN must complete the full loop:
+
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+```
+
+- **PLAN:** Design, get approval, set boundaries
+- **APPLY:** Execute tasks, commit per-task
+- **UNIFY:** Reconcile plan vs actual, update STATE.md
+
+Never leave a loop incomplete. UNIFY closes the loop and updates state.
+This creates audit trail and enables proper session handoff.
+</loop_first>
+
+<acceptance_driven>
+
+Acceptance criteria are first-class, not afterthoughts.
+
+Every PLAN.md has an `## Acceptance Criteria` section with:
+- AC-1, AC-2, AC-3... numbered criteria
+- Each AC is testable/verifiable
+- SUMMARY.md maps results to AC numbers
+
+Format: `AC-N: [Measurable, observable outcome]`
+
+This enables:
+- Clear completion signals
+- Objective verification
+- Deviation tracking against defined scope
+</acceptance_driven>
+
+<evidence_before_claims>
+
+No completion claim without fresh verification evidence.
+
+**The evidence chain:** Execute → Verify (run command) → Read output → Compare to spec → THEN claim.
+
+Breaking any link in the chain produces false completion:
+- Skip verify → "it should work" (hope, not evidence)
+- Run verify but don't read output → "I ran it" (ritual, not verification)
+- Read output but don't compare to spec → "tests pass" (partial check — tests may be incomplete)
+- Compare to spec but from memory → "I checked it" (stale check — re-read the actual files)
+
+**Anti-rationalization reference:**
+
+| If you're thinking... | STOP. Instead... | Because... |
+|---|---|---|
+| "Should work now" | Run the verify command and read its output | Confidence is not evidence |
+| "I already checked this" | Check it again, fresh | Memory of checking is not verification |
+| "It's close enough" | Compare against the AC word by word | "Close" fails acceptance criteria |
+| "The test passes" | Also compare against the spec | Tests can be incomplete |
+| "This is a minor deviation" | Log it explicitly | Minor deviations compound into drift |
+| "I'm confident it works" | Run it and prove it | Confidence without evidence is the #1 cause of false completions |
+
+This table is the canonical reference. It is embedded inline in the APPLY phase qualify step for operational enforcement.
+
+</evidence_before_claims>
+
+<scope_control>
+
+Plans must complete within reasonable context usage.
+
+**Quality degradation curve:**
+- 0-30% context: Peak quality
+- 30-50% context: Good quality
+- 50-70% context: Degrading quality
+- 70%+ context: Poor quality
+
+**Solution:** Target 2-3 tasks per plan — instead of larger plans, because quality degrades past 50% context usage and splitting preserves peak output per token.
+- Each plan independently executable
+- Target ~50% context per plan (40% for TDD plans)
+</scope_control>
+
+<claude_automates>
+
+If Claude CAN do it via CLI/API/tool, Claude MUST do it.
+
+Checkpoints are for:
+- **Verification** - Human confirms Claude's work (visual, UX)
+- **Decision** - Human makes implementation choice
+
+Not for:
+- Deploying (use CLI)
+- Creating resources (use CLI/API)
+- Running builds/tests (use Bash)
+- Writing files (use Write tool)
+</claude_automates>
+
+<deviation_rules>
+
+Plans are guides, not straitjackets. During APPLY:
+
+1. **Auto-fix bugs** - Fix immediately, log in SUMMARY
+2. **Auto-add critical** - Security/correctness gaps, add immediately
+3. **Auto-fix blockers** - Can't proceed, fix immediately
+4. **Ask about architectural** - Major changes, stop and ask
+5. **Log enhancements** - Nice-to-haves, log to deferred issues
+
+All deviations logged during UNIFY for audit trail.
+</deviation_rules>
+
+<ship_fast>
+
+No enterprise process. No approval gates beyond PLAN approval.
+
+Plan → Execute → Ship → Learn → Repeat
+
+Milestones mark shipped versions (v0.1 → v0.2 → v1.0).
+Decimal phases (8.5) for urgent interruptions.
+</ship_fast>
+
+<anti_enterprise>
+
+NEVER include:
+- Team structures, RACI matrices
+- Stakeholder management
+- Sprint ceremonies
+- Human dev time estimates (hours, days, weeks)
+- Change management processes
+- Documentation for documentation's sake
+
+If it sounds like corporate PM theater, delete it — instead of keeping it "just in case", because unnecessary ceremony consumes tokens without producing value.
+</anti_enterprise>
+
+</principles>

package/modules/drive/src/references/research-quality-control.md

@@ -0,0 +1,247 @@
+<research_quality_control>
+
+<purpose>
+Quality assurance patterns for research subagents. When Drive deploys subagents for research or discovery, this reference ensures findings are accurate, well-sourced, and actionable.
+
+**Core principle:** Research quality is measured by accuracy and source verification, not speed or volume.
+
+**When used:** Referenced by research workflows when spawning subagents for documentation lookups, web searches, or codebase exploration.
+</purpose>
+
+<quality_patterns>
+
+<pattern name="explicit_enumeration">
+**DO:** Enumerate all known possibilities before investigating.
+
+**Why:** Prevents gaps in coverage and ensures systematic research.
+
+**Example:**
+```xml
+<verification_checklist>
+Before investigating "configuration options":
+□ User/global scope configuration
+□ Project scope configuration
+□ Local scope overrides
+□ Environment variables
+□ CLI flags
+□ Check for additional unlisted options
+</verification_checklist>
+```
+</pattern>
+
+<pattern name="source_verification">
+**DO:** Verify every claim with authoritative sources.
+
+**Why:** Prevents outdated or incorrect information from entering the project.
+
+**Requirements for each claim:**
+- Official documentation URL
+- Publication/update date verified
+- Version relevance confirmed
+- Cross-referenced with at least one other source for critical claims
+</pattern>
+
+<pattern name="confidence_levels">
+**DO:** Assign confidence levels to findings.
+
+**Why:** Distinguishes verified facts from educated guesses.
+
+| Level | Meaning | Evidence Required |
+|-------|---------|-------------------|
+| HIGH | Verified fact | Official docs + tested |
+| MEDIUM | Likely accurate | Official docs OR multiple sources |
+| LOW | Uncertain | Single source OR inference |
+| UNKNOWN | Cannot determine | No reliable source found |
+</pattern>
+
+<pattern name="scope_awareness">
+**DO:** Check all configuration scopes explicitly.
+
+**Why:** Prevents false negatives from incomplete investigation.
+
+For any "where is X configured?" research:
+- [ ] System/global scope
+- [ ] User scope
+- [ ] Project scope
+- [ ] Workspace scope
+- [ ] Environment scope
+- [ ] Runtime flags
+</pattern>
+
+<pattern name="currency_verification">
+**DO:** Check publication dates and version numbers.
+
+**Why:** Outdated documentation causes incorrect conclusions.
+
+Before trusting any source:
+- [ ] Publication date within last 12 months (prefer current)
+- [ ] Version number matches current version
+- [ ] Changelog checked for recent updates
+- [ ] Not marked deprecated or archived
+</pattern>
+
+</quality_patterns>
+
+<anti_patterns>
+
+<anti_pattern name="assumed_completeness">
+**DON'T:** Assume search results are complete.
+
+**Problem:** First Google result may be outdated or incomplete.
+
+**Instead:** Try multiple search queries, check official docs first, verify publication dates.
+</anti_pattern>
+
+<anti_pattern name="negative_claims_without_evidence">
+**DON'T:** Make "X is not possible" statements without explicit verification.
+
+**Problem:** Absence of evidence is not evidence of absence.
+
+**Instead:** For any "not possible" claim:
+- [ ] Official documentation explicitly states it?
+- [ ] Recent updates checked?
+- [ ] All possible mechanisms verified?
+- [ ] Distinguishing "I didn't find it" from "it doesn't exist"?
+</anti_pattern>
+
+<anti_pattern name="vague_sources">
+**DON'T:** Say "according to documentation" without specific URL.
+
+**Problem:** Claims cannot be verified or updated.
+
+**Instead:** Always provide exact URL: "According to https://docs.example.com/config#scopes..."
+</anti_pattern>
+
+<anti_pattern name="tool_conflation">
+**DON'T:** Assume capabilities are the same across tools/environments.
+
+**Problem:** "Claude Desktop supports X" ≠ "Claude Code supports X"
+
+**Instead:** Document which environment supports which features explicitly.
+</anti_pattern>
+
+<anti_pattern name="single_source_reliance">
+**DON'T:** Rely on a single source for critical claims.
+
+**Problem:** Stack Overflow answer from 2021 may not reflect current best practices.
+
+**Instead:** Cross-reference official docs, release notes, and at least one other authoritative source.
+</anti_pattern>
+
+<anti_pattern name="search_vagueness">
+**DON'T:** Give vague research instructions like "search for documentation."
+
+**Problem:** Finds outdated community blogs instead of official docs.
+
+**Instead:** Specify exact sources:
+```xml
+<sources>
+Official sources (use WebFetch):
+- https://exact-url-to-official-docs
+- https://exact-url-to-api-reference
+
+Search queries (use WebSearch):
+- "specific search query 2026"
+- "another specific query site:official-domain.com"
+</sources>
+```
+</anti_pattern>
+
+</anti_patterns>
+
+<verification_checklists>
+
+<checklist name="pre_submission">
+Before submitting research findings:
+
+- [ ] All enumerated items investigated (not just some)
+- [ ] Negative claims verified with official docs
+- [ ] Multiple sources cross-referenced for critical claims
+- [ ] URLs provided for all official documentation
+- [ ] Publication dates checked (prefer recent/current)
+- [ ] Tool/environment-specific variations documented
+- [ ] Confidence levels assigned honestly
+- [ ] Assumptions distinguished from verified facts
+- [ ] "What might I have missed?" review completed
+</checklist>
+
+<checklist name="critical_claims">
+For any "X is not possible" or "Y is the only way" statement:
+
+- [ ] Is this verified by official documentation stating it explicitly?
+- [ ] Have I checked for recent updates that might change this?
+- [ ] Have I verified all possible approaches/mechanisms?
+- [ ] Am I confusing "I didn't find it" with "it doesn't exist"?
+</checklist>
+
+<checklist name="source_quality">
+For each source consulted:
+
+- [ ] Publication/update date verified (prefer recent/current)
+- [ ] Source authority confirmed (official docs, not blogs)
+- [ ] Version relevance checked (matches current version)
+- [ ] Multiple search queries tried (not just one)
+</checklist>
+
+</verification_checklists>
+
+<red_flags>
+
+<red_flag name="perfect_success">
+**Warning:** Every investigation succeeds perfectly.
+**Problem:** Real research encounters dead ends, ambiguity, and unknowns.
+**Action:** Expect honest reporting of limitations, contradictions, and gaps.
+</red_flag>
+
+<red_flag name="uniform_confidence">
+**Warning:** All findings presented as equally certain.
+**Problem:** Can't distinguish verified facts from educated guesses.
+**Action:** Require confidence levels (High/Medium/Low) for key findings.
+</red_flag>
+
+<red_flag name="missing_urls">
+**Warning:** "According to documentation..." without specific URL.
+**Problem:** Can't verify claims or check for updates.
+**Action:** Require actual URLs for all official documentation claims.
+</red_flag>
+
+<red_flag name="unsupported_absolutes">
+**Warning:** "X cannot do Y" or "Z is the only way" without citation.
+**Problem:** Strong claims require strong evidence.
+**Action:** Flag for verification against official sources.
+</red_flag>
+
+<red_flag name="incomplete_coverage">
+**Warning:** Verification checklist lists 4 items, output covers 2.
+**Problem:** Systematic gaps in coverage.
+**Action:** Ensure all enumerated items addressed or marked "not found."
+</red_flag>
+
+</red_flags>
+
+<quick_reference>
+
+## Research Quality Checklist
+
+**Before starting:**
+- [ ] Enumerate all items to investigate
+- [ ] Identify official documentation sources
+- [ ] Set clear success criteria
+
+**During research:**
+- [ ] Use official sources first
+- [ ] Check publication dates
+- [ ] Cross-reference critical claims
+- [ ] Document URLs for every claim
+
+**Before submitting:**
+- [ ] All items addressed (or marked not found)
+- [ ] Confidence levels assigned
+- [ ] Assumptions clearly labeled
+- [ ] "What did I miss?" self-review
+
+**Living document:** Update after research gaps are discovered.
+
+</quick_reference>
+
+</research_quality_control>