autonomous-coding-toolkit 1.0.0

package/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,82 @@
+# Code Review Agent
+
+You are reviewing code changes for production readiness.
+
+**Your task:**
+1. Review {WHAT_WAS_IMPLEMENTED}
+2. Compare against {PLAN_OR_REQUIREMENTS}
+3. Check code quality, architecture, testing
+4. Categorize issues by severity
+5. Assess production readiness
+
+## What Was Implemented
+
+{DESCRIPTION}
+
+## Requirements/Plan
+
+{PLAN_REFERENCE}
+
+## Git Range to Review
+
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## Review Checklist
+
+**Code Quality:**
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+- Tests actually test logic (not mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+
+**Requirements:**
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+
+## Output Format
+
+### Strengths
+[What's well done? Be specific.]
+
+### Issues
+
+#### Critical (Must Fix)
+[Bugs, security issues, data loss risks]
+
+#### Important (Should Fix)
+[Architecture problems, missing features, test gaps]
+
+#### Minor (Nice to Have)
+[Code style, optimization, documentation]
+
+**For each issue:**
+- File:line reference
+- What's wrong
+- Why it matters
+- How to fix (if not obvious)
+
+### Assessment
+
+**Ready to merge?** [Yes/No/With fixes]
+
+**Reasoning:** [Technical assessment in 1-2 sentences]

package/skills/research/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: research
+description: "Structured investigation between brainstorming and PRD. Produces durable research artifacts that inform implementation decisions."
+version: 1.0.0
+---
+
+# Research — Structured Investigation Protocol
+
+## Overview
+
+Research fills the gap between design intent (brainstorming) and technical specification (PRD). It investigates existing code, external libraries, potential blockers, and implementation options before committing to an approach.
+
+**When to invoke:** After brainstorming produces an approved design, before PRD generation.
+
+## Inputs
+
+- Approved design doc from brainstorming (e.g., `docs/plans/YYYY-MM-DD-<topic>-design.md`)
+- Feature description or scope from the user
+
+## Steps
+
+### Step 1: Extract Research Questions
+
+Read the design doc and identify:
+- Technical unknowns ("does library X support feature Y?")
+- Existing code dependencies ("what module handles auth today?")
+- Integration points ("what interface does the consumer expect?")
+- Performance constraints ("can we process N items in M seconds?")
+
+List 3-8 concrete research questions.
+
+### Step 2: Search Existing Code
+
+For each question about the current codebase:
+- Use Grep/Glob to find relevant files and patterns
+- Read key files to understand current implementations
+- Document: file paths, function signatures, data structures
+
+### Step 3: Search Documentation
+
+For each question about libraries or frameworks:
+- Check project docs (README, ARCHITECTURE.md, CLAUDE.md)
+- Search for existing patterns in the codebase
+- Check docs/lessons/ for relevant lessons
+
+### Step 4: External Research
+
+For each question requiring external knowledge:
+- Search for library documentation, API references
+- Look for known issues, migration guides, compatibility notes
+- Document version constraints and breaking changes
+
+### Step 5: Identify Blockers
+
+Categorize findings as:
+- **Blocking:** Cannot proceed without resolving (missing dependency, incompatible API, no viable approach)
+- **Warning:** Proceed with caution (deprecated API, performance concern, partial support)
+- **Dependency:** Requires work in another module/project first
+
+### Step 6: Synthesize Findings
+
+Write a human-readable summary with:
+- Answer to each research question
+- Recommended approach (with confidence level: high/medium/low)
+- Blocking issues and proposed resolutions
+- Warnings that the PRD should account for
+
+### Step 7: Produce Artifacts
+
+Create two files:
+
+**`tasks/research-<slug>.md`** — Human-readable research report:
+```markdown
+# Research: <Feature Name>
+
+## Questions Investigated
+1. <question> — <answer summary>
+...
+
+## Recommended Approach
+<1-2 paragraphs with confidence level>
+
+## Blocking Issues
+- [ ] <issue> — <proposed resolution>
+
+## Warnings
+- <warning that PRD should account for>
+
+## Dependencies
+- <module/project that needs work first>
+
+## Evidence
+- <file:line references, documentation links>
+```
+
+**`tasks/research-<slug>.json`** — Machine-readable for pipeline consumption:
+```json
+{
+  "feature": "<name>",
+  "timestamp": "<ISO 8601>",
+  "questions": ["<q1>", "<q2>"],
+  "blocking_issues": [
+    {"issue": "<description>", "resolved": false, "resolution": "<proposed>"}
+  ],
+  "warnings": ["<w1>", "<w2>"],
+  "dependencies": ["<dep1>"],
+  "confidence_ratings": {
+    "approach": "high|medium|low",
+    "effort_estimate": "high|medium|low"
+  },
+  "recommended_approach": "<summary>"
+}
+```
+
+### Step 8: Gate Check
+
+If any `blocking_issues` have `resolved: false`:
+- Present them to the user
+- Wait for resolution or override
+- Do NOT proceed to PRD with unresolved blockers
+
+### Step 9: Update Progress
+
+Append research summary to `progress.txt`.
+
+### Step 10: Handoff
+
+Pass `tasks/research-<slug>.json` to PRD generation. The PRD should:
+- Account for all warnings
+- Include tasks that resolve blocking issues
+- Reference research findings in acceptance criteria
+
+## Exit Criteria
+
+- `tasks/research-<slug>.md` exists with all sections
+- `tasks/research-<slug>.json` is valid JSON with all required fields
+- All blocking issues are resolved OR user has explicitly overridden
+- `progress.txt` updated with research summary
+
+## Rules
+
+- **Always make a file.** Research that exists only in conversation is lost on context reset.
+- **Cite evidence.** Every finding should reference a specific file:line, documentation URL, or command output.
+- **Confidence levels are mandatory.** Express high/medium/low confidence on every recommendation.
+- **Don't over-research.** 30-60 minutes maximum. If a question can't be answered in that time, flag it as a blocking issue for the user.

package/skills/roadmap/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: roadmap
+description: "Decompose a multi-feature epic into a dependency-ordered, phased roadmap with effort estimates."
+version: 1.0.0
+---
+
+# Roadmap — Multi-Feature Decomposition
+
+## Overview
+
+When the input to `/autocode` is a multi-feature epic (3+ distinct features or the keyword "roadmap"), this skill decomposes it into an ordered sequence of features, each ready for brainstorming as a standalone unit.
+
+<HARD-GATE>
+Do NOT brainstorm individual features until the roadmap is approved. Feature ordering determines dependency flow — changing order mid-execution causes rework.
+</HARD-GATE>
+
+## When to Use
+
+- Input contains 3+ distinct features
+- Input uses "roadmap", "epic", or "multi-feature" keywords
+- Input references a large body of work spanning multiple PRs
+
+Skip this stage when:
+- Input is a single feature (even a complex one — brainstorming handles that)
+- Input is a bug fix or small enhancement
+
+## Process
+
+### Step 1: Extract Features
+
+Read the input and identify distinct features. Each feature must be:
+- **Independent enough** to be brainstormed, PRD'd, and implemented as a standalone unit
+- **Ordered by dependency** — if Feature B needs Feature A's output, A comes first
+- **Sized for 1-3 sessions** — if a feature takes more, it's an epic, not a feature; decompose further
+
+### Step 2: Identify Dependencies
+
+For each pair of features, determine:
+- **Hard dependency** — B cannot start until A is merged (shared interfaces, schema changes)
+- **Soft dependency** — B benefits from A being done first (shared patterns, learning)
+- **Independent** — no relationship
+
+### Step 3: Order and Phase
+
+Group features into phases based on dependencies:
+
+| Phase | Features | Why this order |
+|-------|----------|---------------|
+| 1 | Foundation features | No dependencies, enable later work |
+| 2 | Dependent features | Require Phase 1 outputs |
+| 3 | Polish features | Require Phase 1+2, add refinement |
+
+### Step 4: Estimate Effort
+
+For each feature, estimate:
+- **Complexity** — simple (1 batch) / moderate (2-3 batches) / complex (4+ batches)
+- **Risk** — low / medium / high (based on unknowns, integration surface, external deps)
+
+### Step 5: Produce Artifact
+
+Write `tasks/roadmap.md` with this structure:
+
+```markdown
+# Roadmap: <Epic Title>
+
+Generated: YYYY-MM-DD
+
+## Features (dependency order)
+
+### Phase 1: <Phase Name>
+| # | Feature | Complexity | Risk | Dependencies |
+|---|---------|-----------|------|-------------|
+| 1 | Feature A | moderate | low | none |
+| 2 | Feature B | simple | low | none |
+
+### Phase 2: <Phase Name>
+| # | Feature | Complexity | Risk | Dependencies |
+|---|---------|-----------|------|-------------|
+| 3 | Feature C | complex | medium | #1 |
+
+## Dependency Graph
+1 → 3
+2 (independent)
+
+## Total Estimate
+- Features: N
+- Phases: M
+- Estimated sessions: X-Y
+```
+
+### Step 6: Get Approval
+
+Present the roadmap to the user. Ask:
+- **"Does this feature ordering make sense?"**
+- **"Should any features be cut, combined, or reordered?"**
+
+Minimum 1 round of refinement before proceeding.
+
+**Exit criteria:** `tasks/roadmap.md` exists, user approves feature ordering.
+
+## After Approval
+
+The autocode pipeline loops through features in roadmap order:
+1. Pick next feature from roadmap
+2. Run Stage 1 (Brainstorm) through Stage 6 (Finish) for that feature
+3. Mark feature complete in roadmap
+4. Repeat until all features done
+
+Each feature gets its own branch, PRD, plan, and verification cycle.
+
+## Integration
+
+**Called by:** `autocode` skill (Stage 0.5, conditional)
+**Produces:** `tasks/roadmap.md`
+**Consumed by:** `autocode` pipeline (iterates features in order)

package/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: subagent-driven-development
+description: Use when executing implementation plans with independent tasks in the current session
+version: 1.0.0
+---
+
+# Subagent-Driven Development
+
+Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
+
+**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
+
+## When to Use
+
+**vs. Executing Plans (parallel session):**
+- Same session (no context switch)
+- Fresh subagent per task (no context pollution)
+- Two-stage review after each task: spec compliance first, then code quality
+- Faster iteration (no human-in-loop between tasks)
+
+## The Process
+
+```dot
+digraph process {
+    rankdir=TB;
+
+    subgraph cluster_per_task {
+        label="Per Task";
+        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
+        "Implementer subagent asks questions?" [shape=diamond];
+        "Answer questions, provide context" [shape=box];
+        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
+        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
+        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
+        "Implementer subagent fixes spec gaps" [shape=box];
+        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
+        "Code quality reviewer subagent approves?" [shape=diamond];
+        "Implementer subagent fixes quality issues" [shape=box];
+        "Mark task complete in TodoWrite" [shape=box];
+    }
+
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
+    "More tasks remain?" [shape=diamond];
+    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
+    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
+
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
+    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
+    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
+    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
+    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
+    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
+    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
+    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
+    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
+    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
+    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
+    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
+    "Mark task complete in TodoWrite" -> "More tasks remain?";
+    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
+    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
+    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
+}
+```
+
+## Prompt Templates
+
+- `./implementer-prompt.md` - Dispatch implementer subagent
+- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
+- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
+
+## Red Flags
+
+**Never:**
+- Start implementation on main/master branch without explicit user consent
+- Skip reviews (spec compliance OR code quality)
+- Dispatch multiple implementation subagents in parallel (conflicts)
+- Make subagent read plan file (provide full text instead)
+- **Start code quality review before spec compliance is ✅** (wrong order)
+
+**If subagent asks questions:**
+- Answer clearly and completely
+- Don't rush them into implementation
+
+**If reviewer finds issues:**
+- Implementer (same subagent) fixes them
+- Reviewer reviews again
+- Repeat until approved
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:using-git-worktrees** - REQUIRED: Set up isolated workspace before starting
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:requesting-code-review** - Code review template for reviewer subagents
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -0,0 +1,18 @@
+# Code Quality Reviewer Prompt Template
+
+**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
+
+**Only dispatch after spec compliance review passes.**
+
+```
+Task tool (superpowers:code-reviewer):
+  Use template at requesting-code-review/code-reviewer.md
+
+  WHAT_WAS_IMPLEMENTED: [from implementer's report]
+  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
+  BASE_SHA: [commit before task]
+  HEAD_SHA: [current commit]
+  DESCRIPTION: [task summary]
+```
+
+**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment

package/skills/subagent-driven-development/implementer-prompt.md

@@ -0,0 +1,73 @@
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent.
+
+```
+Task tool (general-purpose):
+  description: "Implement Task N: [task name]"
+  prompt: |
+    You are implementing Task N: [task name]
+
+    ## Task Description
+
+    [FULL TEXT of task from plan - paste it here, don't make subagent read file]
+
+    ## Context
+
+    [Scene-setting: where this fits, dependencies, architectural context]
+
+    ## Before You Begin
+
+    If you have questions about:
+    - The requirements or acceptance criteria
+    - The approach or implementation strategy
+    - Dependencies or assumptions
+    - Anything unclear in the task description
+
+    **Ask them now.** Raise any concerns before starting work.
+
+    ## Your Job
+
+    Once you're clear on requirements:
+    1. Implement exactly what the task specifies
+    2. Write tests (following TDD if task says to)
+    3. Verify implementation works
+    4. Commit your work
+    5. Self-review (see below)
+    6. Report back
+
+    Work from: [directory]
+
+    **While you work:** If you encounter something unexpected or unclear, **ask questions**.
+
+    ## Before Reporting Back: Self-Review
+
+    Review your work with fresh eyes. Ask yourself:
+
+    **Completeness:**
+    - Did I fully implement everything in the spec?
+    - Did I miss any requirements?
+
+    **Quality:**
+    - Is this my best work?
+    - Are names clear and accurate?
+
+    **Discipline:**
+    - Did I avoid overbuilding (YAGNI)?
+    - Did I follow existing patterns?
+
+    **Testing:**
+    - Do tests actually verify behavior?
+    - Did I follow TDD if required?
+
+    If you find issues during self-review, fix them now before reporting.
+
+    ## Report Format
+
+    When done, report:
+    - What you implemented
+    - What you tested and test results
+    - Files changed
+    - Self-review findings (if any)
+    - Any issues or concerns
+```

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -0,0 +1,57 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching a spec compliance reviewer subagent.
+
+**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
+
+```
+Task tool (general-purpose):
+  description: "Review spec compliance for Task N"
+  prompt: |
+    You are reviewing whether an implementation matches its specification.
+
+    ## What Was Requested
+
+    [FULL TEXT of task requirements]
+
+    ## What Implementer Claims They Built
+
+    [From implementer's report]
+
+    ## CRITICAL: Do Not Trust the Report
+
+    The implementer finished suspiciously quickly. Their report may be incomplete,
+    inaccurate, or optimistic. You MUST verify everything independently.
+
+    **DO NOT:**
+    - Take their word for what they implemented
+    - Trust their claims about completeness
+    - Accept their interpretation of requirements
+
+    **DO:**
+    - Read the actual code they wrote
+    - Compare actual implementation to requirements line by line
+    - Check for missing pieces they claimed to implement
+    - Look for extra features they didn't mention
+
+    ## Your Job
+
+    Read the implementation code and verify:
+
+    **Missing requirements:**
+    - Did they implement everything that was requested?
+    - Are there requirements they skipped or missed?
+
+    **Extra/unneeded work:**
+    - Did they build things that weren't requested?
+    - Did they over-engineer or add unnecessary features?
+
+    **Misunderstandings:**
+    - Did they interpret requirements differently than intended?
+
+    **Verify by reading code, not by trusting report.**
+
+    Report:
+    - ✅ Spec compliant (if everything matches after code inspection)
+    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+```