@accelerationguy/accel 1.0.0

package/modules/drive/src/workflows/quality-gate.md

@@ -0,0 +1,263 @@
+<purpose>
+Run SonarQube quality scan, check gates, and update CONCERNS.md with findings.
+
+Provides objective code quality metrics to inform planning decisions.
+</purpose>
+
+<when_to_use>
+- Before planning new phases (baseline quality)
+- After completing significant work
+- When CONCERNS.md needs updating
+- Manual quality check anytime
+</when_to_use>
+
+<philosophy>
+**Quality as input, not gate:**
+Quality metrics inform decisions but don't block work. A failing gate means "address this" not "stop everything."
+
+**Automated CONCERNS.md:**
+Manual concern tracking is tedious. Let tools find issues, humans prioritize them.
+
+**Optional integration:**
+SonarQube is not required. Workflow gracefully handles disabled state.
+</philosophy>
+
+<references>
+@src/references/sonarqube-integration.md
+@src/templates/config.md
+@src/templates/codebase/concerns.md
+</references>
+
+<process>
+
+<step name="check_config" priority="first">
+1. Check if .drive/config.md exists:
+   ```bash
+   ls .drive/config.md 2>/dev/null
+   ```
+
+2. If exists, read and check sonarqube.enabled
+
+3. **If SonarQube disabled or config missing:**
+   ```
+   SonarQube integration not enabled.
+
+   To enable:
+   1. Add to .drive/config.md:
+      sonarqube:
+        enabled: true
+        project_key: [your-project]
+
+   2. Create sonar-project.properties in project root
+
+   3. Run this workflow again
+   ```
+   Exit workflow.
+
+4. **If enabled:** Extract project_key, continue to verify_prerequisites.
+</step>
+
+<step name="verify_prerequisites">
+1. Check sonar-project.properties exists:
+   ```bash
+   ls sonar-project.properties 2>/dev/null
+   ```
+
+2. **If missing:**
+   ```
+   Missing sonar-project.properties
+
+   Create with:
+   sonar.projectKey=[project_key from config]
+   sonar.projectName=[project name]
+   sonar.sources=src
+
+   Or use MCP to create project:
+   mcp__sonarqube__sonar_create_project
+   ```
+   Exit workflow.
+
+3. **If exists:** Continue to run_scan.
+</step>
+
+<step name="run_scan">
+Run SonarQube scan using MCP:
+
+```
+mcp__sonarqube__sonar_scan
+  project_path: [current directory absolute path]
+```
+
+**Handle results:**
+- Success: Continue to check_gates
+- Failure: Report error, suggest troubleshooting
+
+Display while scanning:
+```
+Running SonarQube scan...
+Project: [project_key]
+```
+</step>
+
+<step name="check_gates">
+Get quality gate status:
+
+```
+mcp__sonarqube__sonar_get_metrics
+  project: [project_key]
+```
+
+**Parse response for:**
+- Quality gate status (OK/ERROR)
+- Bug count
+- Vulnerability count
+- Code smell count
+- Coverage percentage
+- Duplication percentage
+
+Store metrics for report.
+
+Continue to get_issues.
+</step>
+
+<step name="get_issues">
+Fetch unresolved issues by severity:
+
+```
+mcp__sonarqube__sonar_get_issues
+  project: [project_key]
+  severity: "CRITICAL"
+```
+
+```
+mcp__sonarqube__sonar_get_issues
+  project: [project_key]
+  severity: "MAJOR"
+```
+
+**For each issue, extract:**
+- File path
+- Line number (if available)
+- Message
+- Severity
+- Type (BUG, VULNERABILITY, CODE_SMELL)
+
+Group issues by severity for report.
+
+Continue to update_concerns.
+</step>
+
+<step name="update_concerns">
+Update .drive/codebase/CONCERNS.md with scan results.
+
+**If CONCERNS.md doesn't exist:**
+Create from template first.
+
+**Add or update SonarQube section:**
+
+```markdown
+## SonarQube Analysis
+
+**Last Scan:** [YYYY-MM-DD HH:MM]
+**Quality Gate:** [PASSED/FAILED]
+
+### Metrics
+
+| Metric | Value |
+|--------|-------|
+| Bugs | [N] |
+| Vulnerabilities | [N] |
+| Code Smells | [N] |
+| Coverage | [N]% |
+| Duplications | [N]% |
+
+### Critical Issues
+
+[List CRITICAL issues with file paths]
+
+**[Issue type]:** [message]
+- File: `[path]`
+
+### Major Issues
+
+[List MAJOR issues, limit to top 10]
+
+**[Issue type]:** [message]
+- File: `[path]`
+
+---
+*Auto-generated by /drive:quality-gate*
+*Run scan again to update*
+```
+
+**If section already exists:**
+Replace with new data (don't append).
+
+Continue to report_results.
+</step>
+
+<step name="report_results">
+Display summary:
+
+```
+════════════════════════════════════════
+QUALITY GATE: [PASSED/FAILED]
+════════════════════════════════════════
+
+Project: [project_key]
+Scanned: [timestamp]
+
+Metrics:
+  Bugs:            [N]
+  Vulnerabilities: [N]
+  Code Smells:     [N]
+  Coverage:        [N]%
+  Duplications:    [N]%
+
+Issues:
+  CRITICAL: [N]
+  MAJOR:    [N]
+  MINOR:    [N]
+
+Updated: .drive/codebase/CONCERNS.md
+
+────────────────────────────────────────
+[If FAILED:]
+▶ NEXT: Address critical issues before continuing
+
+[If PASSED:]
+▶ Quality gate passed. Continue with planning.
+────────────────────────────────────────
+```
+
+End workflow.
+</step>
+
+</process>
+
+<output>
+- Updated .drive/codebase/CONCERNS.md with SonarQube section
+- Quality gate status displayed
+- Actionable next steps based on results
+</output>
+
+<error_handling>
+**SonarQube server unreachable:**
+- Report connection error
+- Suggest checking server status
+- Provide manual scan instructions
+
+**Scan timeout:**
+- Report timeout
+- Suggest running scan directly
+- Note: large projects may need increased timeout
+
+**MCP tools unavailable:**
+- Report MCP error
+- Suggest checking MCP server configuration
+- Provide manual alternative
+
+**No issues found:**
+- Report clean scan
+- Note in CONCERNS.md: "No significant concerns detected"
+</error_handling>

package/modules/drive/src/workflows/register-manifest.md

@@ -0,0 +1,107 @@
+<purpose>
+Generate .drive/drive.json for an existing Drive project that predates v1.1. Reads current STATE.md to populate fields accurately, falls back to sensible defaults if STATE.md is unreadable.
+</purpose>
+
+<when_to_use>
+- Project has .drive/ directory but no drive.json
+- User needs Momentum satellite auto-detection to work for this project
+- Migrating a pre-v1.1 project to v1.1+ infrastructure
+</when_to_use>
+
+<process>
+
+<step name="validate_preconditions" priority="first">
+1. Check .drive/ exists:
+   ```bash
+   ls .drive/ 2>/dev/null
+   ```
+   If missing: "No .drive/ directory found. Run /drive:init first."
+   Stop.
+
+2. Check drive.json doesn't already exist:
+   ```bash
+   ls .drive/drive.json 2>/dev/null
+   ```
+   If exists: "drive.json already exists. Nothing to do. Momentum will detect this project on next session start."
+   Stop.
+</step>
+
+<step name="read_state">
+Read .drive/STATE.md to extract current project state:
+```bash
+cat .drive/STATE.md 2>/dev/null
+```
+
+Extract from STATE.md (best-effort — use defaults if not found):
+- **project name**: infer from current directory name (`basename $(pwd)`)
+- **milestone name**: look for `Milestone:` line under `## Current Position`
+- **milestone version**: look for version in parentheses on `Milestone:` line (e.g., `(v1.0.0)`)
+- **milestone status**: if `MILESTONE COMPLETE` in the line → "complete"; if `In Progress` or active plans → "in_progress"; otherwise → "not_started"
+- **phase number**: look for `Phase: N of M` line
+- **phase name**: text after the number on the Phase line (e.g., `Phase: 3 of 7 (Auth Layer)` → "Auth Layer")
+- **phase status**: if COMPLETE → "complete"; if Planning → "planning"; if active → "in_progress"; otherwise → "not_started"
+- **loop position**: check Loop Position section — if all three ✓ or IDLE → "IDLE"; if PLAN ✓ but APPLY ○ → "PLAN"; if APPLY ✓ but UNIFY ○ → "APPLY"; if UNIFY in progress → "UNIFY"
+
+**Defaults if STATE.md missing or unparseable:**
+- name: directory name
+- version: "0.1.0"
+- milestone: name "None", version "0.1.0", status "not_started"
+- phase: number 0, name "None", status "not_started"
+- loop: plan null, position "IDLE"
+</step>
+
+<step name="create_paul_json">
+Generate `.drive/drive.json` using extracted values:
+
+```json
+{
+  "name": "[project_name]",
+  "version": "[milestone_version]",
+  "milestone": {
+    "name": "[milestone_name]",
+    "version": "[milestone_version]",
+    "status": "[milestone_status]"
+  },
+  "phase": {
+    "number": [phase_number],
+    "name": "[phase_name]",
+    "status": "[phase_status]"
+  },
+  "loop": {
+    "plan": null,
+    "position": "[loop_position]"
+  },
+  "timestamps": {
+    "created_at": "[current ISO 8601 timestamp]",
+    "updated_at": "[current ISO 8601 timestamp]"
+  },
+  "satellite": {
+    "groom": true
+  }
+}
+```
+
+Write to `.drive/drive.json`.
+</step>
+
+<step name="confirm">
+Report:
+```
+drive.json created for [project_name]
+
+.drive/drive.json registered with:
+  name:      [project_name]
+  version:   [version]
+  milestone: [milestone_name] ([milestone_status])
+  phase:     [phase_number] — [phase_name] ([phase_status])
+  loop:      [loop_position]
+
+Momentum will auto-detect and register this project on next session start.
+```
+</step>
+
+</process>
+
+<output>
+`.drive/drive.json` created with current project state populated from STATE.md.
+</output>

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

@@ -0,0 +1,241 @@
+<purpose>
+Research a topic using subagents and save findings for main session review.
+
+**Philosophy:** Subagents are appropriate for research because research is self-contained, has clear scope, can parallelize, and doesn't require iterative feedback.
+
+**Key principle:** Main session always reviews findings. Never auto-integrate research.
+</purpose>
+
+<when_to_use>
+- User needs information on a topic before planning
+- Technical unknowns need investigation
+- Documentation or patterns need gathering
+- Multiple topics can be researched in parallel
+</when_to_use>
+
+<loop_context>
+N/A - This is a pre-planning workflow, not a loop phase.
+Research informs planning but doesn't gate it.
+</loop_context>
+
+<required_reading>
+@~/.claude/drive-framework/references/subagent-criteria.md
+</required_reading>
+
+<references>
+@src/templates/RESEARCH.md (output format)
+</references>
+
+<process>
+
+<step name="validate_topic" priority="first">
+1. Parse topic from $ARGUMENTS
+
+**If argument missing:**
+```
+Error: Topic required.
+
+Usage: /drive:research <topic> [--codebase | --web]
+Examples:
+  /drive:research "nextjs app router patterns"
+  /drive:research "auth patterns in this codebase" --codebase
+  /drive:research "prisma vs drizzle comparison" --web
+```
+Exit workflow.
+
+2. Check topic complexity against subagent-criteria.md:
+   - Is this substantial (15+ min research)? → Proceed with subagent
+   - Is this trivial (< 5 min lookup)? → Handle in main session
+
+**If trivial:**
+```
+This looks like a quick lookup. Handling in main session...
+
+[provide answer directly]
+```
+Exit workflow.
+</step>
+
+<step name="classify_research">
+Determine research type:
+
+**Codebase research (use Explore agent):**
+- Questions about existing code patterns
+- Finding implementations in the codebase
+- Understanding architecture or conventions
+- "How does X work in this project?"
+
+**Web research (use general-purpose agent):**
+- Documentation lookups
+- Library comparisons
+- Best practices research
+- "What's the recommended approach for X?"
+
+**Auto-detection logic:**
+- Contains "codebase", "this project", "our code" → Codebase
+- Contains "documentation", "library", "vs", "comparison" → Web
+- References specific file paths → Codebase
+- Default → Web (broader scope)
+
+**Override with flags:**
+- `--codebase` forces Explore agent
+- `--web` forces general-purpose agent
+
+Display:
+```
+Research type: {Codebase | Web}
+Agent: {Explore | general-purpose}
+
+Spawning research agent...
+```
+</step>
+
+<step name="spawn_agent">
+**Subagent criteria validation (from subagent-criteria.md):**
+
+| Criterion | Check |
+|-----------|-------|
+| Task Independence | Research is self-contained ✓ |
+| Clear Scope | Topic defines inputs/outputs ✓ |
+| Parallel Value | Can run with other research ✓ |
+| Complexity Sweet Spot | 15-30 min expected ✓ |
+| Token Efficiency | Single spawn, consolidated return ✓ |
+| State Compatibility | No blocking checkpoints ✓ |
+
+**Spawn the appropriate agent:**
+
+For **Codebase** research:
+```
+Use Task tool:
+- subagent_type: Explore
+- description: "Research: {topic}"
+- prompt: |
+    Research the following topic in this codebase:
+
+    Topic: {topic}
+
+    Please find:
+    1. Relevant files and patterns
+    2. How this is currently implemented (if applicable)
+    3. Conventions being followed
+    4. Any related code or dependencies
+
+    Return findings in a structured format with file paths and code examples.
+```
+
+For **Web** research:
+```
+Use Task tool:
+- subagent_type: general-purpose
+- description: "Research: {topic}"
+- prompt: |
+    Research the following topic:
+
+    Topic: {topic}
+
+    Please find:
+    1. Official documentation
+    2. Best practices and patterns
+    3. Pros/cons if comparing options
+    4. Example implementations
+    5. Common pitfalls to avoid
+
+    Use WebSearch and WebFetch as needed.
+    Return findings in a structured format with sources.
+```
+
+**For multiple topics (parallel):**
+- Spawn multiple agents in single message
+- Each agent researches one topic
+- Consolidate findings when all complete
+</step>
+
+<step name="save_findings">
+Create `.drive/research/{topic-slug}.md`:
+
+1. Create research directory if needed:
+   ```bash
+   mkdir -p .drive/research
+   ```
+
+2. Generate topic slug (lowercase, hyphens):
+   - "nextjs app router patterns" → "nextjs-app-router-patterns"
+   - "auth patterns in this codebase" → "auth-patterns-codebase"
+
+3. Write findings using RESEARCH.md template format
+
+4. Display:
+```
+════════════════════════════════════════
+RESEARCH COMPLETE
+════════════════════════════════════════
+
+Topic: {topic}
+Agent: {agent_type}
+Output: .drive/research/{topic-slug}.md
+
+Summary:
+{key findings in 3-5 bullets}
+
+────────────────────────────────────────
+Review the findings above. This research informs but does not
+automatically integrate into plans or code.
+
+What's next?
+[1] View full findings | [2] Research another topic | [3] Done
+────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<output>
+- .drive/research/{topic-slug}.md created with findings
+- Summary presented for review
+- Main session can use findings for planning
+</output>
+
+<success_criteria>
+- [ ] Topic validated (not trivial)
+- [ ] Research type classified correctly
+- [ ] Subagent criteria validated
+- [ ] Appropriate agent spawned
+- [ ] Findings saved to research directory
+- [ ] Summary presented for review
+</success_criteria>
+
+<anti_patterns>
+**Spawning for trivial lookups:**
+DON'T: Spawn subagent for "what's the syntax for X"
+DO: Answer directly if < 5 min lookup
+
+**Auto-integrating findings:**
+DON'T: Automatically apply research to code or plans
+DO: Present findings for human review
+
+**Using wrong agent type:**
+DON'T: Use Explore for web documentation research
+DO: Match agent type to research type
+
+**Serial research chains:**
+DON'T: Spawn agent A, wait, spawn agent B, wait
+DO: Spawn independent agents in parallel
+
+**Over-researching:**
+DON'T: Research every possible topic
+DO: Focus on genuine unknowns that inform decisions
+</anti_patterns>
+
+<error_handling>
+**Subagent timeout:**
+- Report partial findings if available
+- Offer to retry or continue without
+
+**No relevant findings:**
+- Report that topic may be too specific
+- Suggest broader or alternative search terms
+
+**Agent error:**
+- Report error
+- Offer to retry with different approach or agent type
+</error_handling>