@accelerationguy/accel 1.0.0

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

@@ -0,0 +1,219 @@
+<overview>
+TDD is about design quality, not coverage metrics. The red-green-refactor cycle forces you to think about behavior before implementation, producing cleaner interfaces and more testable code.
+
+**Principle:** If you can describe the behavior as `expect(fn(input)).toBe(output)` before writing `fn`, TDD improves the result.
+
+**Key insight:** TDD work is fundamentally heavier than standard tasks—it requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. TDD features get dedicated plans to ensure full context is available throughout the cycle.
+</overview>
+
+<when_to_use_tdd>
+
+## When TDD Improves Quality
+
+**TDD candidates (create a TDD plan with `type: tdd`):**
+- Business logic with defined inputs/outputs
+- API endpoints with request/response contracts
+- Data transformations, parsing, formatting
+- Validation rules and constraints
+- Algorithms with testable behavior
+- State machines and workflows
+- Utility functions with clear specifications
+
+**Skip TDD (use standard plan with `type: execute`):**
+- UI layout, styling, visual components
+- Configuration changes
+- Glue code connecting existing components
+- One-off scripts and migrations
+- Simple CRUD with no business logic
+- Exploratory prototyping
+
+**Heuristic:** Can you write `expect(fn(input)).toBe(output)` before writing `fn`?
+→ Yes: Create a TDD plan
+→ No: Use standard plan, add tests after if needed
+
+</when_to_use_tdd>
+
+<tdd_plan_structure>
+
+## TDD Plan Structure
+
+Each TDD plan implements **one feature** through the full RED-GREEN-REFACTOR cycle.
+
+```yaml
+---
+phase: XX-name
+plan: NN
+type: tdd
+---
+```
+
+```markdown
+## Objective
+
+[What feature and why]
+Purpose: [Design benefit of TDD for this feature]
+Output: [Working, tested feature]
+
+## Context
+
+@.drive/PROJECT.md
+@.drive/ROADMAP.md
+@relevant/source/files.ts
+
+## Acceptance Criteria
+
+- AC-1: Failing test written and committed
+- AC-2: Implementation passes all tests
+- AC-3: Refactor complete (if needed)
+
+## Feature
+
+<feature>
+  <name>[Feature name]</name>
+  <files>[source file, test file]</files>
+  <behavior>
+    [Expected behavior in testable terms]
+    Cases: input → expected output
+  </behavior>
+  <implementation>[How to implement once tests pass]</implementation>
+</feature>
+
+## Verification
+
+[Test command that proves feature works]
+
+## Boundaries
+
+DO NOT CHANGE: [files outside TDD scope]
+```
+
+**One feature per TDD plan.** If features are trivial enough to batch, they're trivial enough to skip TDD.
+
+</tdd_plan_structure>
+
+<execution_flow>
+
+## Red-Green-Refactor Cycle
+
+**RED - Write failing test:**
+1. Create test file following project conventions
+2. Write test describing expected behavior
+3. Run test - it MUST fail
+4. If test passes: feature exists or test is wrong. Investigate.
+5. Commit: `test({phase}-{plan}): add failing test for [feature]`
+
+**GREEN - Implement to pass:**
+1. Write minimal code to make test pass
+2. No cleverness, no optimization - just make it work
+3. Run test - it MUST pass
+4. Commit: `feat({phase}-{plan}): implement [feature]`
+
+**REFACTOR (if needed):**
+1. Clean up implementation if obvious improvements exist
+2. Run tests - MUST still pass
+3. Only commit if changes made: `refactor({phase}-{plan}): clean up [feature]`
+
+**Result:** Each TDD plan produces 2-3 atomic commits.
+
+</execution_flow>
+
+<test_quality>
+
+## Good Tests vs Bad Tests
+
+**Test behavior, not implementation:**
+- Good: "returns formatted date string"
+- Bad: "calls formatDate helper with correct params"
+- Tests should survive refactors
+
+**One concept per test:**
+- Good: Separate tests for valid input, empty input, malformed input
+- Bad: Single test checking all edge cases with multiple assertions
+
+**Descriptive names:**
+- Good: "should reject empty email", "returns null for invalid ID"
+- Bad: "test1", "handles error", "works correctly"
+
+**No implementation details:**
+- Good: Test public API, observable behavior
+- Bad: Mock internals, test private methods, assert on internal state
+
+</test_quality>
+
+<commit_pattern>
+
+## Drive Commit Pattern for TDD Plans
+
+TDD plans produce 2-3 atomic commits (one per phase):
+
+```
+test(08-02): add failing test for email validation
+
+- Tests valid email formats accepted
+- Tests invalid formats rejected
+- Tests empty input handling
+
+feat(08-02): implement email validation
+
+- Regex pattern matches RFC 5322
+- Returns boolean for validity
+- Handles edge cases (empty, null)
+
+refactor(08-02): extract regex to constant (optional)
+
+- Moved pattern to EMAIL_REGEX constant
+- No behavior changes
+- Tests still pass
+```
+
+**Format:** `{type}({phase}-{plan}): {description}`
+
+Types for TDD:
+- `test` - RED phase (failing test)
+- `feat` - GREEN phase (implementation)
+- `refactor` - REFACTOR phase (cleanup)
+
+</commit_pattern>
+
+<context_budget>
+
+## Context Budget
+
+TDD plans target **~40% context usage** (lower than standard plans' ~50%).
+
+Why lower:
+- RED phase: write test, run test, potentially debug why it didn't fail
+- GREEN phase: implement, run test, potentially iterate on failures
+- REFACTOR phase: modify code, run tests, verify no regressions
+
+Each phase involves reading files, running commands, analyzing output. The back-and-forth is inherently heavier than linear task execution.
+
+Single feature focus ensures full quality throughout the cycle.
+
+</context_budget>
+
+<error_handling>
+
+## Error Handling
+
+**Test doesn't fail in RED phase:**
+- Feature may already exist - investigate
+- Test may be wrong (not testing what you think)
+- Fix before proceeding
+
+**Test doesn't pass in GREEN phase:**
+- Debug implementation
+- Don't skip to refactor
+- Keep iterating until green
+
+**Tests fail in REFACTOR phase:**
+- Undo refactor
+- Commit was premature
+- Refactor in smaller steps
+
+**Unrelated tests break:**
+- Stop and investigate
+- May indicate coupling issue
+- Fix before proceeding
+
+</error_handling>

package/modules/drive/src/references/work-units.md

@@ -0,0 +1,161 @@
+<work_units>
+
+<purpose>
+Guide plan sizing to maintain consistent quality. Plans must complete within ~50% context to avoid quality degradation. This reference helps estimate scope and know when to split.
+
+**For Vector users:** Vector context brackets handle this operationally. This reference documents the underlying principles.
+</purpose>
+
+<quality_insight>
+Claude degrades when it perceives context pressure and enters "completion mode."
+
+| Context Usage | Quality | Claude's State |
+|---------------|---------|----------------|
+| 0-30% | PEAK | Thorough, comprehensive |
+| 30-50% | GOOD | Confident, solid work |
+| 50-70% | DEGRADING | Efficiency mode begins |
+| 70%+ | POOR | Rushed, minimal |
+
+**The 40-50% inflection point:** Claude sees context mounting and thinks "I'd better conserve now." Result: quality crash.
+
+**The rule:** Stop BEFORE quality degrades, not at context limit.
+</quality_insight>
+
+<context_target>
+**Plans should complete within ~50% of context usage.**
+
+Why 50% not 80%?
+- No context anxiety possible
+- Quality maintained start to finish
+- Room for unexpected complexity
+- If you target 80%, you've already spent 40% in degradation mode
+</context_target>
+
+<task_limits>
+**Each plan: 2-3 tasks maximum. Stay under 50% context.**
+
+| Task Complexity | Tasks/Plan | Context/Task | Total |
+|-----------------|------------|--------------|-------|
+| Simple (config, single file) | 3 | ~10-15% | ~30-45% |
+| Medium (feature, few files) | 2 | ~20-30% | ~40-50% |
+| Complex (architecture, many files) | 1-2 | ~30-40% | ~30-50% |
+
+**When in doubt: Default to 2 tasks.** Better to have an extra plan than degraded quality.
+</task_limits>
+
+<split_signals>
+
+**Always split when:**
+- More than 3 tasks (even if tasks seem small)
+- Multiple subsystems (DB + API + UI = separate plans)
+- Any task with >5 file modifications
+- Discovery + implementation (DISCOVERY.md in one plan, implementation in another)
+
+**Consider splitting when:**
+- Estimated >5 files modified total
+- Complex domains (auth, payments, data modeling)
+- Uncertainty about approach
+- Natural semantic boundaries
+
+</split_signals>
+
+<splitting_strategies>
+
+**Vertical slices (default):** Group by feature, not by layer.
+
+```
+PREFER: Plan 01 = User (model + API + UI)
+        Plan 02 = Product (model + API + UI)
+
+AVOID:  Plan 01 = All models
+        Plan 02 = All APIs (depends on 01)
+```
+
+Vertical slices maximize parallelism and reduce dependencies.
+
+**By dependency:** Only when genuine dependencies exist.
+```
+Plan 01: Auth foundation (middleware, JWT)
+Plan 02: Protected features (uses auth from 01)
+```
+
+**By complexity:** When one slice is much heavier.
+```
+Plan 01: Dashboard layout shell
+Plan 02: Data fetching and state
+Plan 03: Visualization components
+```
+</splitting_strategies>
+
+<estimating_context>
+
+| Files Modified | Context Impact |
+|----------------|----------------|
+| 0-3 files | ~10-15% (small) |
+| 4-6 files | ~20-30% (medium) |
+| 7+ files | ~40%+ (large - split) |
+
+| Complexity | Context/Task |
+|------------|--------------|
+| Simple CRUD | ~15% |
+| Business logic | ~25% |
+| Complex algorithms | ~40% |
+| Domain modeling | ~35% |
+
+**Quick estimates:**
+- 2 simple tasks: ~30%
+- 2 medium tasks: ~50%
+- 2 complex tasks: ~80% (split!)
+- 3 simple tasks: ~45%
+- 3 medium tasks: ~75% (risky)
+</estimating_context>
+
+<paul_integration>
+**How this fits Drive's loop:**
+
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+```
+
+- **PLAN phase:** Use work-units to size correctly
+- **APPLY phase:** Execute within context budget
+- **UNIFY phase:** Record actual duration for future estimates
+
+**With Vector (recommended):**
+Vector context brackets automate these checks:
+- FRESH (>60%): Full implementation OK
+- MODERATE (40-60%): Consider splitting
+- DEPLETED (<40%): Handoff or fresh agent
+
+Drive provides the framework. Vector provides operational automation.
+</paul_integration>
+
+<anti_patterns>
+
+**Bad - Comprehensive plan:**
+```
+Plan: "Complete Authentication System"
+Tasks: 8
+Result: Task 1-3 good, Task 4-5 degrading, Task 6-8 rushed
+```
+
+**Good - Atomic plans:**
+```
+Plan 1: "Auth Database Models" (2 tasks)
+Plan 2: "Auth API Core" (2 tasks)
+Plan 3: "Auth UI Components" (2 tasks)
+Each: 30-40% context, peak quality
+```
+</anti_patterns>
+
+<summary>
+**Core rules:**
+- 2-3 tasks per plan
+- 50% context target
+- Split when in doubt
+- Vertical slices over horizontal layers
+
+**The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
+</summary>
+
+</work_units>

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

@@ -0,0 +1,108 @@
+---
+paths:
+  - "src/commands/**/*.md"
+---
+
+# Command Rules
+
+Rules for editing files in `src/commands/`.
+
+## File Structure
+
+```yaml
+---
+name: drive:command-name
+description: One-line description
+argument-hint: "<required>" or "[optional]"
+allowed-tools: [Read, Write, Bash, Glob, Grep, Edit, AskUserQuestion]
+---
+```
+
+## Section Order
+
+1. `<objective>` — What/why/when (always present)
+2. `<execution_context>` — @-references to workflows, templates, references
+3. `<context>` — Dynamic content: `$ARGUMENTS`, bash output, @file refs
+4. `<process>` or `<step>` elements — Implementation steps (thin, delegates to workflow)
+5. `<success_criteria>` — Measurable completion checklist
+
+## Core Principle
+
+**Commands are thin wrappers.** Delegate detailed logic to workflows.
+
+Commands answer "what to do", workflows answer "how to do it".
+
+A command should fit on one screen. If it grows beyond that, logic belongs in a workflow.
+
+## @-Reference Patterns
+
+```markdown
+<execution_context>
+@src/workflows/plan-phase.md
+@src/templates/PLAN.md
+@src/references/checkpoints.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+@.drive/PROJECT.md
+@.drive/STATE.md
+@.drive/ROADMAP.md
+</context>
+```
+
+- `execution_context`: Static resources (workflows, templates, references from Drive framework)
+- `context`: Dynamic project state (from `.drive/` directory) and user arguments
+
+## Success Criteria Format
+
+```xml
+<success_criteria>
+- [ ] Specific, measurable criterion
+- [ ] Another verifiable outcome
+</success_criteria>
+```
+
+Use checkbox format. Each criterion must be objectively verifiable.
+
+## Example Command Structure
+
+```markdown
+---
+name: drive:plan
+description: Enter PLAN phase for current or new plan
+argument-hint: "[phase-plan]"
+allowed-tools: [Read, Write, Glob, AskUserQuestion]
+---
+
+<objective>
+Create or continue a PLAN for the specified phase.
+
+**When to use:** Starting new work or resuming incomplete plan.
+</objective>
+
+<execution_context>
+@src/workflows/plan-phase.md
+@src/templates/PLAN.md
+@src/references/plan-format.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+@.drive/PROJECT.md
+@.drive/STATE.md
+@.drive/ROADMAP.md
+</context>
+
+<process>
+Follow workflow: @src/workflows/plan-phase.md
+</process>
+
+<success_criteria>
+- [ ] PLAN.md created in correct phase directory
+- [ ] All acceptance criteria defined
+- [ ] STATE.md updated with loop position
+</success_criteria>
+```

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

@@ -0,0 +1,107 @@
+---
+paths:
+  - "src/references/**/*.md"
+---
+
+# Reference File Rules
+
+Rules for editing files in `src/references/`.
+
+## No Frontmatter
+
+References don't use YAML frontmatter. They are conceptual documentation, not executable artifacts.
+
+## File Structure
+
+References follow a teaching-oriented structure:
+
+1. **Outer container** — Semantic XML tag matching the concept (optional but common)
+2. **Purpose section** — What this reference explains
+3. **Concepts section** — Core ideas with explanations
+4. **Examples section** — Concrete illustrations (good vs bad when applicable)
+5. **Anti-patterns section** — What to avoid and WHY
+
+## Outer Container Pattern
+
+References often use an outer XML container related to their topic:
+
+```markdown
+<!-- checkpoints.md -->
+<checkpoints>
+## Purpose
+...
+
+## Checkpoint Types
+...
+</checkpoints>
+
+<!-- subagent-criteria.md -->
+<subagent_criteria>
+## Purpose
+...
+
+## When to Use Subagents
+...
+</subagent_criteria>
+```
+
+Not a strict requirement — use when it adds semantic clarity.
+
+## Teaching Patterns
+
+References explain concepts for workflows and commands to load when relevant.
+
+**Teach by contrast:**
+```markdown
+## Vague vs Specific
+
+<!-- BAD -->
+<task>
+  <action>Set up authentication</action>
+</task>
+
+<!-- GOOD -->
+<task>
+  <action>
+    Create POST /api/auth/login endpoint:
+    - Accept { email, password }
+    - Validate with bcrypt compare
+    - Return JWT token (15min expiry)
+  </action>
+</task>
+```
+
+**Explain WHY:**
+```markdown
+## Why Boundaries Matter
+
+Without explicit boundaries, AI assistants may:
+- Refactor code outside the plan scope
+- "Improve" working code that wasn't part of the task
+- Break existing functionality while fixing something else
+
+Boundaries prevent scope creep by making off-limits areas explicit.
+```
+
+## Loading Pattern
+
+References are lazy-loaded by workflows when conceptual context is needed:
+
+```xml
+<!-- In a workflow -->
+<required_reading>
+@src/references/checkpoints.md (when plan has checkpoints)
+@src/references/subagent-criteria.md (when parallel execution considered)
+</required_reading>
+```
+
+References should be self-contained — a workflow can load just one reference without needing others.
+
+## Key Principle
+
+References explain concepts and patterns. They are loaded by workflows/commands when relevant context is needed.
+
+References are NOT:
+- Step-by-step instructions (that's workflows)
+- Document structure definitions (that's templates)
+- Behavioral rules (that's Vector domains)

package/modules/drive/src/rules/style.md

@@ -0,0 +1,123 @@
+---
+paths:
+  - "src/**/*.md"
+---
+
+# Drive Style Rules
+
+Universal conventions for all Drive framework files.
+
+## Language & Tone
+
+**Imperative voice.** "Execute tasks", "Create file" — not "Execution is performed"
+
+**No filler.** Absent: "Let me", "Just", "Simply", "Basically", "I'd be happy to"
+
+**No sycophancy.** Absent: "Great!", "Awesome!", "Excellent!", "I'd love to help"
+
+**Brevity with substance.** Good: "JWT auth with refresh rotation using jose library" Bad: "Phase complete"
+
+## Temporal Language Ban
+
+Never write: "We changed X to Y", "Previously", "No longer", "Instead of"
+
+Always: Describe current state only.
+
+Exception: SUMMARY.md deviations section, git commits (their purpose IS tracking change)
+
+## Naming Conventions
+
+| Type | Convention | Example |
+|------|------------|---------|
+| Files | kebab-case | `plan-phase.md` |
+| Commands | `drive:kebab-case` | `drive:plan` |
+| Step names | snake_case | `name="load_project_state"` |
+| Bash variables | CAPS_UNDERSCORES | `PHASE_ARG` |
+| Type attributes | colon separator | `type="checkpoint:human-verify"` |
+| Phase directories | `NN-kebab-name` | `02-rules-layer` |
+| Plan files | `NN-NN-PLAN.md` | `02-01-PLAN.md` |
+
+## XML Conventions
+
+XML tags are semantic containers. Use Markdown headers for hierarchy within.
+
+```xml
+<!-- DO -->
+<objective>
+## Goal
+Build authentication system
+
+## Purpose
+Enable secure user access
+</objective>
+
+<!-- DON'T -->
+<section name="objective">
+  <subsection name="goal">
+    <content>Build authentication</content>
+  </subsection>
+</section>
+```
+
+**Semantic tags to use:**
+- `<objective>`, `<context>`, `<tasks>`, `<boundaries>`, `<verification>`
+- `<acceptance_criteria>`, `<success_criteria>`
+- `<task>`, `<action>`, `<verify>`, `<done>`
+- `<purpose>`, `<when_to_use>`, `<process>`, `<step>`
+
+**Generic tags to avoid:**
+- `<section>`, `<item>`, `<content>`, `<block>`
+
+## @-References
+
+@-references are lazy loading signals — instructions to read at execution time, not pre-loaded content.
+
+```markdown
+# Static (always load)
+@src/workflows/plan-phase.md
+@src/templates/PLAN.md
+
+# Project-relative (dynamic)
+@.drive/PROJECT.md
+@.drive/STATE.md
+
+# Conditional
+@.drive/DISCOVERY.md (if exists)
+```
+
+## Loop Terminology
+
+Drive uses explicit loop phase names:
+
+| Phase | Purpose | Artifacts |
+|-------|---------|-----------|
+| PLAN | Define work, acceptance criteria | PLAN.md |
+| APPLY | Execute approved plan | Code changes, APPLY-LOG |
+| UNIFY | Reconcile plan vs actual | SUMMARY.md, STATE.md updates |
+
+Always reference the current loop position when relevant.
+
+## Acceptance Criteria Format
+
+Use Given/When/Then (BDD) in `<acceptance_criteria>` sections:
+
+```gherkin
+Given [precondition / initial state]
+When [action / trigger]
+Then [expected outcome]
+```
+
+Each criterion must be independently testable.
+
+## Commit Format
+
+```
+{type}({phase}-{plan}): {description}
+```
+
+Types: `feat`, `fix`, `test`, `refactor`, `docs`, `chore`
+
+Rules:
+- One commit per task when practical
+- Stage files individually (never `git add .`)
+- Include `Co-Authored-By: Claude` line