autonomous-coding-toolkit 1.0.0

package/skills/using-superpowers/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: using-superpowers
+description: Use when starting any conversation - establishes how to find and use skills, requiring Skill tool invocation before ANY response including clarifying questions
+version: 1.0.0
+---
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## How to Access Skills
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you—follow it directly. Never use the Read tool on skill files.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check.
+
+## Red Flags
+
+These thoughts mean STOP—you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (brainstorming, debugging) - these determine HOW to approach the task
+2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution
+
+## Skill Types
+
+**Rigid** (TDD, debugging): Follow exactly. Don't adapt away discipline.
+**Flexible** (patterns): Adapt principles to context.
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+version: 1.0.0
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/skills/verify/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: verify
+description: Self-verification checklist — run before declaring work complete, committing, or creating PRs
+disable-model-invocation: true
+version: 1.0.0
+---
+
+## Dependencies
+- Bash tool (git, test runners, linters)
+
+Run a verification pass on the work just completed. Do NOT skip steps.
+
+## Step 1: Check what changed
+
+1. `git diff --stat` — list modified files
+2. `git diff --cached --stat` — list staged files
+3. If no git repo, list files you created or modified this session
+
+## Step 2: Run automated checks (if available)
+
+Try each in order, skip if not applicable:
+
+1. **Tests:** Look for test runner config. Run tests. Report pass/fail count.
+2. **Linter:** Look for linter config. Run linter. Report issue count.
+3. **Type check:** Look for `tsconfig.json` or `mypy.ini`. Run type checker.
+4. **Build:** If there's a build step, run it.
+
+## Step 2.5: Integration Wiring + Lesson Scanner
+
+**Run this step if the session built multiple components across batches.**
+
+1. **Integration wiring check:** Confirm every shared module built this session is imported/called by its consumer.
+2. **Lesson scanner:** Dispatch `lesson-scanner` agent against modified files.
+3. **Contract tests:** For parallel feature lists, verify a contract test exists.
+
+## Step 3: Pipeline testing (if service has API, UI, or multi-layer data flow)
+
+### 3a: Horizontal sweep — every endpoint/interface works
+
+Hit every API endpoint, CLI command, and static file with a known input. Confirms the **surface exists and responds.**
+
+### 3b: Vertical trace — one input flows through the entire stack
+
+Submit one real input and trace it through every layer. Confirms **data flows end-to-end and state accumulates correctly.**
+
+### Why both axes are required
+
+Horizontal catches: missing routes, broken static files, schema errors, 500s.
+Vertical catches: path prefix mismatches, missing state updates, aggregate bugs.
+
+**If time-constrained:** Run the vertical trace — it catches more integration bugs per minute.
+
+## Step 4: Manual verification checklist
+
+For each file changed, verify:
+
+- [ ] Does the change do what was asked?
+- [ ] No secrets committed
+- [ ] No debug artifacts left
+- [ ] File permissions correct
+- [ ] If config changed: service reloaded/restarted?
+
+## Step 5: Report
+
+Present as:
+
+```
+VERIFICATION — <date>
+Files changed: N
+Tests: X passed, Y failed (or N/A)
+Lint: X issues (or N/A)
+Types: clean (or N/A)
+Pipeline (horizontal): X/Y endpoints pass (or N/A)
+Pipeline (vertical): data traced input→output / [list gaps] (or N/A)
+Manual checks: all clear / [list issues]
+```
+
+## Anti-patterns
+
+- NEVER say "looks good" without running actual commands
+- NEVER skip the git diff
+- NEVER declare work complete if any test fails

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: writing-plans
+description: Use when you have a spec or requirements for a multi-step task, before touching code
+version: 1.0.0
+---
+
+# Writing Plans
+
+## Overview
+
+Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.
+
+Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.
+
+**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."
+
+**Context:** This should be run in a dedicated worktree (created by brainstorming skill).
+
+**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`
+
+## Bite-Sized Task Granularity
+
+**Each step is one action (2-5 minutes):**
+- "Write the failing test" - step
+- "Run it to make sure it fails" - step
+- "Implement the minimal code to make the test pass" - step
+- "Run the tests and make sure they pass" - step
+- "Commit" - step
+
+## Plan Document Header
+
+**Every plan MUST start with this header:**
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+## Task Structure
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py:123-145`
+- Test: `tests/exact/path/to/test.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: FAIL with "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `pytest tests/path/test.py::test_name -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## Remember
+- Exact file paths always
+- Complete code in plan (not "add validation")
+- Exact commands with expected output
+- Reference relevant skills with @ syntax
+- DRY, YAGNI, TDD, frequent commits
+
+## Execution Handoff
+
+After saving the plan, offer execution choice:
+
+**"Plan complete and saved to `docs/plans/<filename>.md`. Three execution options:**
+
+**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task with two-stage review, fast iteration, you watch progress
+
+**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with human review checkpoints
+
+**3. Headless (walk away)** - Run `scripts/run-plan.sh` in the background. Fresh `claude -p` per batch, quality gates between batches, resume on interruption. Best for 5+ batch plans.
+
+**Which approach?"**
+
+**If Subagent-Driven chosen:**
+- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
+- Stay in this session
+- Fresh subagent per task + code review
+
+**If Parallel Session chosen:**
+- Guide them to open new session in worktree
+- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans
+
+**If Headless chosen:**
+- Generate the run command with appropriate flags:
+  ```bash
+  scripts/run-plan.sh docs/plans/<plan-file>.md --quality-gate "scripts/quality-gate.sh --project-root ."
+  ```
+- If the plan has critical batches, suggest `--mode competitive --competitive-batches N,M`
+- For long plans (10+ batches), suggest `--on-failure retry --max-retries 3`
+- Remind them: `--resume` picks up where it left off after interruption

package/skills/writing-skills/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: writing-skills
+description: Use when creating new skills, editing existing skills, or verifying skills work before deployment
+version: 1.0.0
+---
+
+# Writing Skills
+
+## Overview
+
+**Writing skills IS Test-Driven Development applied to process documentation.**
+
+You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).
+
+**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.
+
+## What is a Skill?
+
+A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches.
+
+**Skills are:** Reusable techniques, patterns, tools, reference guides
+**Skills are NOT:** Narratives about how you solved a problem once
+
+## SKILL.md Structure
+
+**Frontmatter (YAML):**
+- Only two fields supported: `name` and `description`
+- Max 1024 characters total
+- `name`: Use letters, numbers, and hyphens only
+- `description`: Third-person, describes ONLY when to use (NOT what it does)
+
+```markdown
+---
+name: Skill-Name-With-Hyphens
+description: Use when [specific triggering conditions and symptoms]
+---
+
+# Skill Name
+
+## Overview
+What is this? Core principle in 1-2 sentences.
+
+## When to Use
+Bullet list with SYMPTOMS and use cases
+
+## Core Pattern
+Before/after code comparison
+
+## Quick Reference
+Table or bullets for scanning
+
+## Common Mistakes
+What goes wrong + fixes
+```
+
+## The Iron Law (Same as TDD)
+
+```
+NO SKILL WITHOUT A FAILING TEST FIRST
+```
+
+Write skill before testing? Delete it. Start over.
+
+## RED-GREEN-REFACTOR for Skills
+
+### RED: Write Failing Test (Baseline)
+Run pressure scenario with subagent WITHOUT the skill. Document exact behavior.
+
+### GREEN: Write Minimal Skill
+Write skill that addresses those specific rationalizations. Run same scenarios WITH skill.
+
+### REFACTOR: Close Loopholes
+Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
+
+## Skill Creation Checklist
+
+**RED Phase:**
+- [ ] Create pressure scenarios
+- [ ] Run scenarios WITHOUT skill - document baseline
+- [ ] Identify patterns in rationalizations/failures
+
+**GREEN Phase:**
+- [ ] Name uses only letters, numbers, hyphens
+- [ ] YAML frontmatter with only name and description
+- [ ] Description starts with "Use when..."
+- [ ] Address specific baseline failures
+- [ ] Run scenarios WITH skill - verify compliance
+
+**REFACTOR Phase:**
+- [ ] Identify NEW rationalizations from testing
+- [ ] Add explicit counters
+- [ ] Build rationalization table
+- [ ] Re-test until bulletproof