@accelerationguy/accel 1.0.0

package/modules/drive/src/references/sonarqube-integration.md

@@ -0,0 +1,244 @@
+# SonarQube Integration
+
+Reference for integrating SonarQube code quality scanning with Drive.
+
+---
+
+## Overview
+
+**What SonarQube provides:**
+- Static code analysis (bugs, vulnerabilities, code smells)
+- Quality gates (pass/fail thresholds)
+- Technical debt estimation
+- Code coverage tracking
+- Duplicate code detection
+
+**Why integrate with Drive:**
+- Auto-populate CONCERNS.md with real issues
+- Objective quality metrics for planning
+- Track improvement over time
+- Catch issues before they become problems
+
+---
+
+## Prerequisites
+
+### 1. SonarQube Server
+
+You need a running SonarQube instance:
+
+**Option A: Local Docker (recommended for development)**
+```bash
+docker run -d --name sonarqube -p 9000:9000 sonarqube:community
+```
+
+**Option B: SonarCloud (cloud hosted)**
+- Create account at sonarcloud.io
+- Use cloud URL in configuration
+
+### 2. Project Configuration
+
+Create `sonar-project.properties` in project root:
+
+```properties
+sonar.projectKey=my-project
+sonar.projectName=My Project
+sonar.sources=src
+sonar.exclusions=**/node_modules/**,**/dist/**
+```
+
+### 3. SonarQube MCP Server
+
+Ensure sonarqube MCP is configured in Claude Code:
+
+```json
+{
+  "mcpServers": {
+    "sonarqube": {
+      "command": "node",
+      "args": ["/path/to/sonarqube-mcp/index.js"]
+    }
+  }
+}
+```
+
+---
+
+## Setup Steps
+
+### Step 1: Enable in Drive Config
+
+Edit `.drive/config.md`:
+
+```yaml
+sonarqube:
+  enabled: true
+  project_key: my-project  # Must match sonar-project.properties
+```
+
+### Step 2: Create Project in SonarQube
+
+Use the MCP tool or SonarQube UI:
+
+```
+mcp__sonarqube__sonar_create_project
+  project_key: "my-project"
+  name: "My Project"
+  project_path: "/path/to/project"
+```
+
+This also creates `sonar-project.properties` if missing.
+
+### Step 3: Run Initial Scan
+
+```
+mcp__sonarqube__sonar_scan
+  project_path: "/path/to/project"
+```
+
+Or use Drive workflow:
+```
+/drive:quality-gate
+```
+
+### Step 4: Verify Integration
+
+Check that scan completed:
+```
+mcp__sonarqube__sonar_get_metrics
+  project: "my-project"
+```
+
+---
+
+## Usage Patterns
+
+### Manual Scan via Workflow
+
+Run quality checks anytime:
+```
+/drive:quality-gate
+```
+
+This will:
+1. Verify SonarQube is enabled
+2. Run scan
+3. Check quality gate status
+4. Fetch issues
+5. Update CONCERNS.md
+
+### Before Planning
+
+Run quality gate before planning new phases:
+- Identifies existing issues to address
+- Provides objective baseline
+- Informs scope decisions
+
+### After Major Changes
+
+Run after completing significant work:
+- Verify no new issues introduced
+- Check quality gate still passes
+- Update CONCERNS.md with current state
+
+### Reading Results
+
+**Get metrics:**
+```
+mcp__sonarqube__sonar_get_metrics
+  project: "my-project"
+```
+
+Returns: bugs, vulnerabilities, code smells, coverage, duplications
+
+**Get issues:**
+```
+mcp__sonarqube__sonar_get_issues
+  project: "my-project"
+  severity: "CRITICAL"  # Optional filter
+```
+
+Returns: file, line, message, severity for each issue
+
+---
+
+## Integration with Drive
+
+### CONCERNS.md Auto-Population
+
+The quality-gate workflow updates `.drive/codebase/CONCERNS.md`:
+
+```markdown
+## SonarQube Analysis
+
+**Last Scan:** 2026-01-28
+**Quality Gate:** PASSED
+
+### Issues by Severity
+
+| Severity | Count | Examples |
+|----------|-------|----------|
+| CRITICAL | 0 | - |
+| MAJOR | 3 | SQL injection in `src/db.ts`, ... |
+| MINOR | 12 | ... |
+
+### Metrics
+
+- Bugs: 2
+- Vulnerabilities: 1
+- Code Smells: 15
+- Coverage: 72%
+- Duplications: 3.2%
+```
+
+### Quality Gates as Planning Input
+
+When planning, reference CONCERNS.md:
+- Address CRITICAL issues before new features
+- Factor MAJOR issues into phase scope
+- Track code smell reduction over time
+
+### Tracking Improvement
+
+Compare scans over time:
+- Note issue count changes in SUMMARY.md
+- Celebrate quality improvements
+- Identify recurring problem areas
+
+---
+
+## Troubleshooting
+
+### "SonarQube not enabled"
+
+Check `.drive/config.md` has:
+```yaml
+sonarqube:
+  enabled: true
+```
+
+### "Project not found"
+
+Ensure project_key matches between:
+- `.drive/config.md`
+- `sonar-project.properties`
+- SonarQube server
+
+### "Scan failed"
+
+Common causes:
+- SonarQube server not running
+- sonar-project.properties missing
+- Invalid source path in properties
+
+Check with:
+```bash
+curl http://localhost:9000/api/system/status
+```
+
+### "MCP tools not available"
+
+Verify sonarqube MCP server is:
+- Configured in Claude Code settings
+- Running without errors
+- Has correct authentication token

package/modules/drive/src/references/specialized-workflow-integration.md

@@ -0,0 +1,186 @@
+<specialized_workflow_integration>
+
+## Purpose
+
+SPECIAL-FLOWS enables explicit tracking of specialized skills, commands, and workflows within Drive governance. Instead of ad-hoc skill invocation, projects declare which skills apply, when they're required, and UNIFY verifies they were actually used.
+
+**Core principle:** If a skill is important enough to use, it's important enough to track.
+
+## Why This Matters
+
+### The Problem
+Users build specialized skills for their work (e.g., `/revops-expert` for persuasion copy, `/frontend-design` for UI components). Without explicit integration:
+- Skills are invoked ad-hoc, inconsistently
+- No verification that required skills were used
+- No gap analysis for continuous improvement
+- Knowledge about "which skills for which work" lives only in human memory
+
+### The Solution
+Layered reinforcement through the Drive loop:
+
+```
+SPECIAL-FLOWS.md   →  "This project uses X, Y, Z skills"
+       ↓
+ROADMAP.md         →  "Phase 2 requires X skill"
+       ↓
+PLAN.md            →  "Task 2.1 invokes /frontend-design"
+       ↓
+UNIFY              →  "Was skill invoked? Gap noted if not"
+```
+
+## Skill Flow
+
+### 1. Declaration (SPECIAL-FLOWS.md)
+At project setup, declare which skills apply:
+
+```markdown
+| Work Type | Skill/Command | Priority | When Required |
+|-----------|---------------|----------|---------------|
+| Persuasion copy | /revops-expert | required | Before headlines, CTAs |
+| UI components | /frontend-design | optional | Before writing HTML |
+```
+
+### 2. Phase Annotation (ROADMAP.md)
+Optionally annotate phases with required skills:
+
+```markdown
+### Phase 4: Landing Page
+**Required Skills:** /revops-expert (copy), /frontend-design (UI)
+```
+
+### 3. Task Invocation (PLAN.md)
+Plans can reference skills in pre-implementation or task notes:
+
+```markdown
+## Pre-Implementation
+- [ ] Load /revops-expert (Hormozi frameworks)
+
+## Tasks
+1. Write headline copy
+   - **Skill:** /revops-expert (value equation)
+```
+
+### 4. Verification (UNIFY)
+During UNIFY, audit skill invocation:
+
+| Expected | Invoked | Gap? | Notes |
+|----------|---------|------|-------|
+| /revops-expert | ✓ | - | Loaded Hormozi stack |
+| /frontend-design | ○ | Yes | Used inline CSS instead |
+
+Gaps are documented in STATE.md Deviations, not blocked.
+
+## Priority Levels
+
+### Required
+- **Definition:** Skill should be invoked for this type of work
+- **Verification:** Gap documented in STATE.md if not used
+- **Use case:** Core skills that significantly impact quality
+
+### Optional
+- **Definition:** Skill is available but not mandatory
+- **Verification:** Informational only, no gap logged
+- **Use case:** Nice-to-have skills, situational enhancements
+
+## Verification Behavior
+
+### Manual During UNIFY (Not Hook-Based)
+Skill usage is verified manually during UNIFY phase:
+1. Read SPECIAL-FLOWS.md for declared skills
+2. Review conversation/session for invocations
+3. Mark each required skill as invoked or gap
+4. Document gaps in STATE.md Deviations
+
+**Why not automatic?** Hook-based tracking is complex, may miss invocations, and adds fragility. Manual verification during UNIFY keeps it simple and reliable.
+
+### Warn, Don't Block
+Gaps generate warnings, not blocking errors:
+- Gaps are documented for learning
+- User can note "intentional deviation"
+- UNIFY still completes
+- Continuous improvement, not rigid enforcement
+
+## Examples
+
+### Example 1: Client Website Project
+
+```markdown
+# Specialized Flows
+
+## Project-Level Dependencies
+
+| Work Type | Skill/Command | Priority | When Required |
+|-----------|---------------|----------|---------------|
+| Persuasion copy | /revops-expert | required | Headlines, CTAs, offers |
+| UI components | /frontend-design | required | All HTML generation |
+| Pricing sections | /revops-expert:hormozi | optional | Offer stacking phases |
+
+## Phase Overrides
+
+| Phase | Additional Skills | Notes |
+|-------|-------------------|-------|
+| 3 (Pricing) | /revops-expert:hormozi | Value stacking for offers |
+
+## Templates & Assets
+
+| Asset Type | Location | When Used |
+|------------|----------|-----------|
+| Hero template | templates/hero-section.html | Homepage hero |
+| Testimonial | templates/testimonial-card.html | Social proof sections |
+```
+
+### Example 2: Technical Project
+
+```markdown
+# Specialized Flows
+
+## Project-Level Dependencies
+
+| Work Type | Skill/Command | Priority | When Required |
+|-----------|---------------|----------|---------------|
+| API documentation | /docs-generator | optional | After API changes |
+| Database changes | /migration-helper | required | Schema modifications |
+```
+
+## Evolution and Improvement
+
+### Pattern Recognition
+Over time, SPECIAL-FLOWS reveals patterns:
+- Which skills are consistently used
+- Which are often skipped (maybe not required?)
+- New skills that should be added
+
+### Updating Patterns
+When intentional deviation becomes the norm:
+1. Note deviation in UNIFY
+2. Consider updating SPECIAL-FLOWS.md
+3. Log decision if significant change
+
+## Integration Points
+
+### With Init
+During `/drive:init`, optionally configure specialized flows:
+- "Do you have specialized skills for this project?"
+- If yes, route to configuration workflow
+- If no, skip (can add later via `/drive:flows`)
+
+### With UNIFY
+During UNIFY, audit skill usage:
+- Check SPECIAL-FLOWS.md for declared skills
+- Verify invocations in session
+- Document gaps in STATE.md Deviations
+
+### With PROJECT.md
+Quick reference in PROJECT.md:
+
+```markdown
+## Specialized Flows
+
+See: .drive/SPECIAL-FLOWS.md
+
+Quick Reference:
+- /revops-expert → Persuasion copy, offers, CTAs
+- /frontend-design → UI components, HTML generation
+```
+
+</specialized_workflow_integration>

package/modules/drive/src/references/subagent-criteria.md

@@ -0,0 +1,179 @@
+<subagent_criteria>
+
+## Purpose
+
+Define strategic criteria for when subagents are appropriate. Subagents are a tool, not a default. Use them deliberately when criteria are met, not reflexively to "save context."
+
+**Key principle:** Strategic criteria, not default behavior.
+
+## When Subagents Are Appropriate
+
+Subagents are APPROPRIATE when **ALL** of the following are true:
+
+### 1. Task Independence
+Work is self-contained and doesn't require iterative human feedback during execution.
+
+```
+GOOD for subagent:
+- "Create User model with these exact fields"
+- "Write unit tests for existing calculateTotal function"
+
+BAD for subagent:
+- "Design the UI for dashboard" (needs feedback)
+- "Figure out why tests are failing" (may need clarification)
+```
+
+### 2. Clear Scope
+Inputs and outputs are well-defined with low ambiguity.
+
+```
+GOOD for subagent:
+- Input: PLAN.md with specific tasks
+- Output: Code files, test results
+
+BAD for subagent:
+- "Make the API better" (ambiguous)
+- "Optimize performance" (unclear targets)
+```
+
+### 3. Parallel Value
+Multiple independent tasks can run simultaneously, providing actual time savings.
+
+```
+GOOD for subagent:
+- Plan 01-01 (User model) and Plan 01-02 (Product model) - independent
+- Three test suites for different modules
+
+BAD for subagent:
+- Single sequential task (no parallelization benefit)
+- Tasks with shared state or outputs
+```
+
+### 4. Complexity Sweet Spot
+Not too complex (risk of drift), not too granular (overhead not worth it).
+
+```
+GOOD complexity:
+- 2-3 well-defined tasks
+- 15-60 minutes of work
+- Clear verification criteria
+
+TOO complex:
+- Multi-phase architectural work
+- Requires judgment calls on ambiguous requirements
+
+TOO simple:
+- "Add one import statement"
+- "Fix typo in comment"
+```
+
+### 5. Token Efficiency
+Subagent cost < in-session cost for equivalent work.
+
+Consider:
+- Subagent startup overhead (~2-3k tokens)
+- Full context re-establishment
+- Result serialization back to main session
+
+### 6. State Compatibility
+Current workflow state supports async completion.
+
+```
+GOOD state:
+- APPLY phase with autonomous plan
+- No pending decisions or blockers
+
+BAD state:
+- Mid-checkpoint, waiting for human input
+- Iterative refinement cycle with user
+```
+
+## When Subagents Are NOT Appropriate
+
+**Do NOT use subagents when:**
+
+- **Task requires iterative refinement** - Human feedback needed during execution
+- **Output quality depends on nuanced context** - Only available in main session
+- **Task is too simple** - Overhead exceeds value (< 5 min work)
+- **Task is too complex** - Risk of drift, hard to verify (> 60 min work)
+- **Tight coupling to other work** - Dependencies on in-progress tasks
+- **Uncertain requirements** - Need to clarify before execution
+
+## Decision Framework
+
+```
+┌─────────────────────────────────────────┐
+│ Is task self-contained and well-defined?│
+└─────────────────┬───────────────────────┘
+                  │
+         ┌────────▼────────┐
+         │     NO          │──► Work in main session
+         └─────────────────┘
+                  │
+                 YES
+                  │
+         ┌────────▼────────┐
+         │ Multiple tasks  │
+         │ that can run    │──► NO ──► Work in main session
+         │ in parallel?    │          (no parallelization benefit)
+         └─────────────────┘
+                  │
+                 YES
+                  │
+         ┌────────▼────────┐
+         │ Complexity in   │
+         │ sweet spot?     │──► NO ──► Split or simplify first
+         │ (15-60 min)     │
+         └─────────────────┘
+                  │
+                 YES
+                  │
+         ┌────────▼────────┐
+         │ SUBAGENT        │
+         │ APPROPRIATE     │
+         └─────────────────┘
+```
+
+## Subagent Usage Pattern
+
+When using subagents:
+
+1. **Document decision** - Why subagent was chosen
+2. **Define clear handoff** - PLAN.md with full context
+3. **Specify verification** - How to validate subagent output
+4. **Plan integration** - How results merge back to main session
+
+## Anti-Patterns
+
+**Subagent by default:**
+```
+# BAD
+"Let me spawn a subagent to handle this small task"
+(Task is 5 minutes, overhead exceeds value)
+```
+
+**Subagent for uncertain work:**
+```
+# BAD
+"I'll have a subagent figure out the best approach"
+(Requires judgment that needs human input)
+```
+
+**Subagent chain:**
+```
+# BAD
+Subagent A → Subagent B → Subagent C
+(Serial subagents have no parallel benefit, just overhead)
+```
+
+## Prefer In-Session When Uncertain
+
+When criteria are borderline, prefer working in the main session:
+- Lower overhead
+- Better context continuity
+- Easier course correction
+- Direct human interaction available
+
+**Subagents are for parallelization of well-defined work, not context offloading.**
+
+</subagent_criteria>