@accelerationguy/accel 1.0.0

package/modules/drive/src/workflows/map-codebase.md

@@ -0,0 +1,459 @@
+<purpose>
+Orchestrate parallel Explore agents to analyze codebase and produce structured documents in .drive/codebase/
+
+Each agent has fresh context and focuses on specific aspects. Output is concise and actionable for planning.
+</purpose>
+
+<philosophy>
+**Why parallel agents:**
+- Fresh context per domain (no token contamination)
+- Thorough analysis without context exhaustion
+- Each agent optimized for its domain (tech vs organization vs quality vs issues)
+- Faster execution (agents run simultaneously)
+
+**Document quality over length:**
+Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity. A 200-line TESTING.md with real patterns is more valuable than a 74-line summary.
+
+**Always include file paths:**
+Documents are reference material for Claude when planning/executing. Vague descriptions like "UserService handles users" are not actionable. Always include actual file paths formatted with backticks: `src/services/user.ts`. This allows Claude to navigate directly to relevant code without re-searching. Do NOT include line numbers (they go stale), just file paths.
+</philosophy>
+
+<references>
+@src/templates/codebase/stack.md
+@src/templates/codebase/architecture.md
+@src/templates/codebase/structure.md
+@src/templates/codebase/conventions.md
+@src/templates/codebase/testing.md
+@src/templates/codebase/integrations.md
+@src/templates/codebase/concerns.md
+</references>
+
+<process>
+
+<step name="check_existing" priority="first">
+Check if .drive/codebase/ already exists:
+
+```bash
+ls -la .drive/codebase/ 2>/dev/null
+```
+
+**If exists:**
+
+```
+.drive/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Update - Keep existing, only update specific documents
+3. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .drive/codebase/, continue to create_structure
+If "Update": Ask which documents to update, continue to spawn_agents (filtered)
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .drive/codebase/ directory:
+
+```bash
+mkdir -p .drive/codebase
+```
+
+**Expected output files:**
+- STACK.md (from stack.md template)
+- ARCHITECTURE.md (from architecture.md template)
+- STRUCTURE.md (from structure.md template)
+- CONVENTIONS.md (from conventions.md template)
+- TESTING.md (from testing.md template)
+- INTEGRATIONS.md (from integrations.md template)
+- CONCERNS.md (from concerns.md template)
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+Spawn 4 parallel Explore agents to analyze codebase.
+
+Use Task tool with `subagent_type="Explore"` and `run_in_background=true` for parallel execution.
+
+**Agent 1: Stack + Integrations (Technology Focus)**
+
+Task tool parameters:
+```
+subagent_type: "Explore"
+run_in_background: true
+description: "Analyze technology stack and integrations"
+```
+
+Prompt:
+```
+Analyze this codebase for technology stack and external integrations.
+
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/config/database.ts`. This makes the output actionable for planning.
+
+Focus areas:
+1. Languages (check file extensions, package manifests)
+2. Runtime environment (Node.js, Python, etc. - check .nvmrc, .python-version, engines field)
+3. Package manager and lockfiles
+4. Frameworks (web, testing, build tools)
+5. Key dependencies (critical packages for functionality)
+6. External services (APIs, databases, auth providers)
+7. Third-party integrations (payment, analytics, etc.)
+8. Configuration approach (.env, config files)
+
+Search for:
+- package.json / requirements.txt / Cargo.toml / go.mod
+- .env files, .env.example
+- Config files (vite.config, webpack.config, tsconfig.json)
+- API client code, database connection code
+- Import statements for major libraries
+
+Output findings for populating these sections:
+- STACK.md: Languages, Runtime, Frameworks, Dependencies, Configuration
+- INTEGRATIONS.md: External APIs, Services, Third-party tools
+
+For each finding, include the file path where you found it. Example:
+- "TypeScript 5.3 - `package.json`"
+- "Supabase client - `src/lib/supabase.ts`"
+- "Stripe integration - `src/services/stripe.ts`, `src/webhooks/stripe.ts`"
+
+If something is not found, note "Not detected" for that category.
+```
+
+**Agent 2: Architecture + Structure (Organization Focus)**
+
+Task tool parameters:
+```
+subagent_type: "Explore"
+run_in_background: true
+description: "Analyze architecture patterns and directory structure"
+```
+
+Prompt:
+```
+Analyze this codebase architecture and directory structure.
+
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `src/index.ts`. This makes the output actionable for planning.
+
+Focus areas:
+1. Overall architectural pattern (monolith, microservices, layered, etc.)
+2. Conceptual layers (API, service, data, utility)
+3. Data flow and request lifecycle
+4. Key abstractions and patterns (services, controllers, repositories)
+5. Entry points (main files, server files, CLI entry)
+6. Directory organization and purposes
+7. Module boundaries
+8. Naming conventions for directories and files
+
+Search for:
+- Entry points: index.ts, main.ts, server.ts, app.ts, cli.ts
+- Directory structure patterns (src/, lib/, components/, services/)
+- Import patterns (what imports what)
+- Recurring code patterns (base classes, interfaces, common abstractions)
+
+Output findings for populating these sections:
+- ARCHITECTURE.md: Pattern, Layers, Data Flow, Abstractions, Entry Points
+- STRUCTURE.md: Directory layout, Organization, Key locations
+
+For each finding, include the file path. Examples:
+- "CLI entry point: `bin/install.js`"
+- "Service layer: `src/services/*.ts` (UserService, ProjectService)"
+- "API routes: `src/routes/api/*.ts`"
+
+If something is not clear, provide best-guess interpretation based on code structure.
+```
+
+**Agent 3: Conventions + Testing (Quality Focus)**
+
+Task tool parameters:
+```
+subagent_type: "Explore"
+run_in_background: true
+description: "Analyze coding conventions and test patterns"
+```
+
+Prompt:
+```
+Analyze this codebase for coding conventions and testing practices.
+
+IMPORTANT: Always include actual file paths in your findings. Use backtick formatting like `vitest.config.ts`. This makes the output actionable for planning.
+
+Focus areas:
+1. Code style (indentation, quotes, semicolons, formatting)
+2. File naming conventions (kebab-case, PascalCase, etc.)
+3. Function/variable naming patterns
+4. Comment and documentation style
+5. Test framework and structure
+6. Test organization (unit, integration, e2e)
+7. Test coverage approach
+8. Linting and formatting tools
+
+Search for:
+- Config files: .eslintrc, .prettierrc, tsconfig.json
+- Test files: *.test.*, *.spec.*, __tests__/
+- Test setup: vitest.config, jest.config
+- Code patterns across multiple files
+- README or CONTRIBUTING docs
+
+Output findings for populating these sections:
+- CONVENTIONS.md: Code Style, Naming, Patterns, Documentation
+- TESTING.md: Framework, Structure, Coverage, Tools
+
+For each finding, include file paths. Examples:
+- "Prettier config: `.prettierrc`"
+- "Test pattern: `src/**/*.test.ts` (co-located with source)"
+- "Example of naming convention: `src/services/user-service.ts`"
+
+Look at actual code files to infer conventions if config files are missing.
+```
+
+**Agent 4: Concerns (Issues Focus)**
+
+Task tool parameters:
+```
+subagent_type: "Explore"
+run_in_background: true
+description: "Identify technical debt and areas of concern"
+```
+
+Prompt:
+```
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+CRITICAL: Always include actual file paths in your findings. Use backtick formatting like `src/auth/login.ts`. Concerns without file paths are not actionable. For each issue found, specify exactly where it is.
+
+Focus areas:
+1. TODO and FIXME comments
+2. Complex or hard-to-understand code
+3. Missing error handling (try/catch, error checks)
+4. Security patterns (hardcoded secrets, unsafe operations)
+5. Outdated dependencies (check versions against current)
+6. Missing tests for critical code
+7. Duplicate code patterns
+8. Performance concerns (N+1 queries, inefficient loops)
+9. Documentation gaps (complex code without comments)
+
+Search for:
+- TODO, FIXME, HACK, XXX comments
+- Large functions or files (>200 lines)
+- Repeated code patterns
+- Missing .env.example when .env is used
+- Dependencies with known vulnerabilities (check versions)
+- Error-prone patterns (no validation, no error handling)
+
+Output findings for populating:
+- CONCERNS.md: Technical Debt, Issues, Security, Performance, Documentation
+
+For EVERY concern, include file paths. Examples:
+- "Direct DB queries in components: `src/pages/Dashboard.tsx`, `src/pages/Profile.tsx`"
+- "Missing error handling: `src/api/webhook.ts` (Stripe webhook has no try/catch)"
+- "TODO: 'fix race condition' in `src/services/subscription.ts`"
+
+Be constructive - focus on actionable concerns, not nitpicks.
+If codebase is clean, note that rather than inventing problems.
+```
+
+Continue to collect_results.
+</step>
+
+<step name="collect_results">
+Wait for all 4 agents to complete.
+
+Use TaskOutput tool to collect results from each agent. Since agents were run with `run_in_background=true`, retrieve their output.
+
+**Collection pattern:**
+
+For each agent, use TaskOutput tool to get the full exploration findings.
+
+**Aggregate findings by document:**
+
+From Agent 1 output, extract:
+- STACK.md sections: Languages, Runtime, Frameworks, Dependencies, Configuration, Platform
+- INTEGRATIONS.md sections: External APIs, Services, Authentication, Webhooks
+
+From Agent 2 output, extract:
+- ARCHITECTURE.md sections: Pattern Overview, Layers, Data Flow, Key Abstractions, Entry Points
+- STRUCTURE.md sections: Directory Layout, Key Locations, Organization
+
+From Agent 3 output, extract:
+- CONVENTIONS.md sections: Code Style, Naming Conventions, Common Patterns, Documentation Style
+- TESTING.md sections: Framework, Structure, Coverage, Tools
+
+From Agent 4 output, extract:
+- CONCERNS.md sections: Technical Debt, Known Issues, Security, Performance, Missing
+
+**Handling missing findings:**
+
+If an agent didn't find information for a section, use placeholder:
+- "Not detected" (for infrastructure/tools that may not exist)
+- "Not applicable" (for patterns that don't apply to this codebase)
+- "No significant concerns" (for CONCERNS.md if codebase is clean)
+
+Continue to write_documents.
+</step>
+
+<step name="write_documents">
+Write all 7 codebase documents using templates and agent findings.
+
+**Template filling process:**
+
+For each document:
+
+1. **Reference template file** from `src/templates/codebase/{name}.md`
+2. **Extract the "File Template" section** - this is the markdown code block containing the actual document structure
+3. **Fill template placeholders** with agent findings:
+   - Replace `[YYYY-MM-DD]` with current date
+   - Replace `[Placeholder text]` with specific findings from agents
+   - If agent found nothing for a section, use appropriate placeholder:
+     - "Not detected" for optional infrastructure
+     - "Not applicable" for patterns that don't fit this codebase
+     - "No significant concerns" for clean codebase areas
+4. **Write to .drive/codebase/{NAME}.md** (uppercase filename)
+
+**Example filling pattern:**
+
+Template placeholder:
+```
+**Primary:**
+- [Language] [Version] - [Where used: e.g., "all application code"]
+```
+
+Agent finding:
+```
+Found: TypeScript 5.3 used in all .ts files throughout src/
+```
+
+Filled result:
+```
+**Primary:**
+- TypeScript 5.3 - All application code
+```
+
+**Document writing order:**
+
+1. **STACK.md** (from stack.md template + Agent 1 findings)
+2. **INTEGRATIONS.md** (from integrations.md template + Agent 1 findings)
+3. **ARCHITECTURE.md** (from architecture.md template + Agent 2 findings)
+4. **STRUCTURE.md** (from structure.md template + Agent 2 findings)
+5. **CONVENTIONS.md** (from conventions.md template + Agent 3 findings)
+6. **TESTING.md** (from testing.md template + Agent 3 findings)
+7. **CONCERNS.md** (from concerns.md template + Agent 4 findings)
+
+After all documents written, continue to verify_output.
+</step>
+
+<step name="verify_output">
+Verify all documents created successfully:
+
+```bash
+ls -la .drive/codebase/
+wc -l .drive/codebase/*.md
+```
+
+**Verification checklist:**
+- All 7 documents exist
+- No empty documents
+- Templates populated with findings
+
+If any checks fail, report issues to user.
+
+Continue to commit_codebase_map.
+</step>
+
+<step name="commit_codebase_map">
+Commit the codebase map:
+
+```bash
+git add .drive/codebase/*.md
+git commit -m "$(cat <<'EOF'
+docs: map existing codebase
+
+- STACK.md - Technologies and dependencies
+- ARCHITECTURE.md - System design and patterns
+- STRUCTURE.md - Directory layout
+- CONVENTIONS.md - Code style and patterns
+- TESTING.md - Test structure
+- INTEGRATIONS.md - External services
+- CONCERNS.md - Technical debt and issues
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+EOF
+)"
+```
+
+Continue to update_state.
+</step>
+
+<step name="update_state">
+If .drive/STATE.md exists, note that codebase has been mapped.
+
+Add to Accumulated Context section:
+```
+### Codebase Mapped
+Date: [current date]
+Documents: .drive/codebase/ (7 files)
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps.
+
+**Output format:**
+
+```
+Codebase mapping complete.
+
+Created .drive/codebase/:
+- STACK.md ([N] lines) - Technologies and dependencies
+- ARCHITECTURE.md ([N] lines) - System design and patterns
+- STRUCTURE.md ([N] lines) - Directory layout and organization
+- CONVENTIONS.md ([N] lines) - Code style and patterns
+- TESTING.md ([N] lines) - Test structure and practices
+- INTEGRATIONS.md ([N] lines) - External services and APIs
+- CONCERNS.md ([N] lines) - Technical debt and issues
+
+
+---
+
+## ▶ Next Up
+
+**Initialize Drive project** — use codebase context for planning
+
+`/drive:init`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Re-run mapping: `/drive:map-codebase`
+- Review specific file: `cat .drive/codebase/STACK.md`
+- Edit any document before proceeding
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .drive/codebase/ directory created
+- 4 parallel Explore agents spawned with run_in_background=true
+- Agent prompts are specific and actionable
+- TaskOutput used to collect all agent results
+- All 7 codebase documents written using template filling
+- Documents follow template structure with actual findings
+- Clear completion summary with line counts
+- User offered clear next steps
+</success_criteria>

package/modules/drive/src/workflows/pause-work.md

@@ -0,0 +1,259 @@
+<purpose>
+Create HANDOFF.md file and update STATE.md when pausing work mid-session. Enables seamless resumption in fresh session with full context restoration.
+</purpose>
+
+<when_to_use>
+- Before ending a session (planned or context limit approaching)
+- Switching to different project
+- Context window at DEEP or CRITICAL bracket
+- User explicitly pauses work
+</when_to_use>
+
+<loop_context>
+Any position in PLAN/APPLY/UNIFY loop. Captures state regardless of where loop is.
+</loop_context>
+
+<required_reading>
+@.drive/STATE.md
+@.drive/PROJECT.md
+</required_reading>
+
+<references>
+@~/.claude/drive-framework/references/context-management.md
+@~/.claude/drive-framework/templates/HANDOFF.md
+</references>
+
+<process>
+
+<step name="detect_position" priority="first">
+1. Read `.drive/STATE.md` to get:
+   - Current phase and plan
+   - Loop position (PLAN/APPLY/UNIFY markers)
+   - Last activity
+2. Identify current working directory:
+   ```bash
+   ls -t .drive/phases/*/PLAN*.md 2>/dev/null | head -1
+   ```
+</step>
+
+<step name="gather_session_context">
+**Collect complete state for handoff:**
+
+Ask user (or infer from conversation):
+1. **Work completed this session** - What got done?
+2. **Work in progress** - What's partially done?
+3. **Decisions made** - Key choices and rationale
+4. **Blockers/issues** - Anything stuck?
+5. **Mental context** - The approach, what you were thinking
+
+If user doesn't provide, summarize from:
+- Recent file modifications (`git status`)
+- Conversation history
+- STATE.md changes
+</step>
+
+<step name="create_handoff">
+**Create HANDOFF file:**
+
+```bash
+# Generate filename
+TIMESTAMP=$(date +%Y-%m-%d)
+HANDOFF_FILE=".drive/HANDOFF-${TIMESTAMP}.md"
+```
+
+**Write content (NOT from template, populate directly):**
+
+```markdown
+# Drive Handoff
+
+**Date:** [current timestamp]
+**Status:** [paused/blocked/context-limit]
+
+---
+
+## READ THIS FIRST
+
+You have no prior context. This document tells you everything.
+
+**Project:** [from PROJECT.md]
+**Core value:** [from PROJECT.md]
+
+---
+
+## Current State
+
+**Version:** [from STATE.md]
+**Phase:** [N] of [total] — [phase name]
+**Plan:** [plan-id] — [status]
+
+**Loop Position:**
+```
+PLAN ──▶ APPLY ──▶ UNIFY
+  [✓/○]    [✓/○]    [✓/○]
+```
+
+---
+
+## What Was Done
+
+- [Accomplishment 1]
+- [Accomplishment 2]
+- [Accomplishment 3]
+
+---
+
+## What's In Progress
+
+- [In-progress item with status]
+
+---
+
+## What's Next
+
+**Immediate:** [specific next action]
+
+**After that:** [following action]
+
+---
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `.drive/STATE.md` | Live project state |
+| `.drive/ROADMAP.md` | Phase overview |
+| [current plan path] | [plan purpose] |
+
+---
+
+## Resume Instructions
+
+1. Read `.drive/STATE.md` for latest position
+2. Check loop position
+3. Run `/drive:resume` or `/drive:progress`
+
+---
+
+*Handoff created: [timestamp]*
+```
+
+Be specific enough for a fresh Claude to understand immediately.
+</step>
+
+<step name="update_state">
+**Update `.drive/STATE.md` Session Continuity section:**
+
+```markdown
+## Session Continuity
+
+Last session: [timestamp]
+Stopped at: [what was happening]
+Next action: [clear directive]
+Resume file: .drive/HANDOFF-[date].md
+Resume context:
+- [bullet 1 - key context]
+- [bullet 2 - key context]
+- [bullet 3 - key context]
+```
+</step>
+
+<step name="optional_commit">
+**If git repo, offer WIP commit with explicit two-question flow:**
+
+**Question 1 — Commit WIP?**
+```
+────────────────────────────────────────
+Would you like to commit your work-in-progress?
+
+This saves a checkpoint you can return to.
+────────────────────────────────────────
+[yes] / [no]
+```
+
+**If no:** Skip to confirm step.
+
+**If yes — Question 2 — Branch choice:**
+```
+────────────────────────────────────────
+Where should this WIP commit go?
+
+[1] main — Commit directly to main branch
+[2] feature branch — Create feature/{phase-name} branch first
+
+Note: Feature branch is useful if work isn't ready for main.
+────────────────────────────────────────
+```
+
+**If main (option 1):**
+```bash
+git add .drive/ src/
+git commit -m "wip({phase}): paused at {plan}
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+**If feature branch (option 2):**
+```bash
+# Create and switch to feature branch
+git checkout -b feature/{phase-name}
+
+# Commit to feature branch
+git add .drive/ src/
+git commit -m "wip({phase}): paused at {plan}
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+
+# Record branch strategy in STATE.md for transition-phase
+```
+
+**Update STATE.md Session Continuity with branch info:**
+```markdown
+Git strategy: {main|feature/{phase-name}}
+```
+
+This enables transition-phase.md to know the branch strategy when reconciling.
+</step>
+
+<step name="confirm">
+**Display confirmation:**
+
+```
+════════════════════════════════════════
+Drive SESSION PAUSED
+════════════════════════════════════════
+
+Handoff created: .drive/HANDOFF-[date].md
+
+Current State:
+  Phase: [N] of [M]
+  Plan: [status]
+  Loop: [PLAN/APPLY/UNIFY position]
+
+To resume later:
+  /drive:resume
+
+════════════════════════════════════════
+```
+</step>
+
+</process>
+
+<output>
+- HANDOFF-{date}.md created in .drive/
+- STATE.md updated with session continuity
+- Optional WIP commit with branch choice (main or feature/{phase})
+- Git strategy recorded in STATE.md for transition-phase
+- User knows how to resume
+</output>
+
+<error_handling>
+**No .drive/ directory:**
+- "No Drive project found. Nothing to pause."
+
+**STATE.md missing or corrupted:**
+- Create minimal handoff from available context
+- Note the gap in handoff file
+
+**Git not available:**
+- Skip commit step, still create handoff
+</error_handling>