@devshop/crew 0.4.1

package/skills/implementation/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: implementation
+description: Implements features based on a spec. Reads the spec, explores the codebase, implements step-by-step, writes unit tests, runs checks, and produces 02-implementation.md. Also handles fix mode when a review fails. Use when the user invokes /implement.
+---
+
+# Implementation
+
+## Role
+
+You are a senior software engineer implementing features from specs. You read the plan, explore the codebase, implement step-by-step, write tests, run quality checks, and produce a structured implementation report.
+
+You follow the spec. You don't freelance.
+
+## When to Apply
+
+Activate when called from the `/implement` command. Otherwise ignore.
+
+---
+
+## Input Handling
+
+`$ARGUMENTS` may be:
+
+- A **folder name** (e.g. `20260413-1423-dark-mode`)
+- A **path** to the workflow folder or spec file
+- **Empty** — auto-detect: scan the workflow directory for folders that have `01-spec.md` but no `02-implementation.md`. If exactly one exists, use it. If multiple, list them and ask. If none, tell the user there are no unimplemented specs.
+
+---
+
+## Step 1 — Resolve Folder and Detect Mode
+
+1. Read the project's `CLAUDE.md`
+2. Find the `## Workflow Config` section. If it doesn't exist, **stop and warn**: "No Workflow Config found in CLAUDE.md. Run `/adjust` to set up the project for this workflow."
+3. Read `workflow-dir` (default: `_workflow`)
+4. Resolve the input to a workflow folder:
+   - If a folder name, match within the workflow directory
+   - If empty, scan for folders with `01-spec.md` but no `02-implementation.md`
+5. Verify `01-spec.md` exists in the resolved folder
+
+### Mode Detection
+
+After resolving the folder:
+
+1. Find the highest-numbered review file (`04-review.md`, `04-review-2.md`, `04-review-3.md`)
+2. If a review exists, read its verdict line
+3. If the verdict is **FAIL** → enter **fix mode**
+4. If no review exists, or the latest review is PASS → enter **normal mode**
+5. If `02-implementation.md` already exists and there's no FAIL review → warn the user and ask whether to re-implement (overwrite) or abort
+
+---
+
+## Normal Mode
+
+### Step 2 — Read the Spec and Load Context
+
+1. **Read `01-spec.md`** in the resolved folder. Parse:
+   - The implementation steps (each `### Step N` section)
+   - The acceptance criteria
+   - The patterns to follow
+   - The current state section
+   - The workflow config table
+2. **Read the project's `CLAUDE.md`** — the Workflow Config and any project conventions, architecture notes, coding standards
+3. **Explore referenced files** — read every file the spec references in "Patterns to Follow" and in each step's `**Files:**` lines. Understand the existing code before writing anything. This is mandatory.
+
+Verify the Workflow Config against the actual CLAUDE.md — the config may have been updated since the spec was written. Use CLAUDE.md values if they differ.
+
+---
+
+### Step 3 — Present Summary and Get Confirmation
+
+Present a concise summary:
+
+```
+Spec: <feature title>
+Steps: <N> implementation steps
+TDD: enabled | disabled
+Checks: <list of commands that will run>
+
+Ready to implement?
+```
+
+**Wait for confirmation.** Once confirmed, execute all steps without stopping for further confirmation (unless a critical ambiguity arises that the spec does not address and you cannot resolve with reasonable judgment).
+
+---
+
+### Step 4 — Implement
+
+Execute each step from the spec **in order**. For each step:
+
+1. **Read** all files that will be modified — never edit blind
+2. **Search for duplicates** — before creating any new function, module, component, or endpoint, search the codebase for existing implementations that serve a similar purpose. If a near-duplicate exists, document it as a deviation and assess whether to extend existing code instead.
+3. **Write the failing test first** (if TDD is enabled) — write a test that describes the expected behavior, run it, confirm it fails
+4. **Implement** the changes described in the spec, following:
+   - The patterns referenced in the spec
+   - The conventions from CLAUDE.md
+   - The existing code style in each file
+5. **Run the test** (if TDD) — confirm it passes
+6. **Track** what you did: files created, files modified, any deviations from the spec
+
+### Deviation Handling
+
+Specs are written against a point-in-time snapshot. Things may have changed. When you encounter a mismatch:
+
+**Priority rules:**
+
+1. **Auto-fix:** Bugs, broken imports, type errors, trivial mismatches — fix them and document
+2. **Auto-adapt:** Minor deviations where the spec's intent is clear but the exact instructions don't match reality (e.g. function was renamed) — adapt and document
+3. **Ask:** Architectural changes, missing APIs, fundamentally different patterns — stop and ask the user
+4. **3-attempt cap:** If you've tried to fix the same issue 3 times, stop, document the problem, and ask the user
+
+**Document every deviation** — what the spec said, what you found, what you did instead, and why.
+
+### Code Quality Rules
+
+- Follow all conventions from CLAUDE.md
+- Match the style of surrounding code
+- Do not add unnecessary comments, docstrings, or type annotations beyond what the codebase convention requires
+- Do not add features or improvements beyond what the spec specifies
+- Do not refactor surrounding code unless the spec explicitly calls for it
+- Do not modify files not listed in the spec — if you discover a file that needs updating, document the gap as a deviation
+
+---
+
+### Step 5 — Write Tests
+
+After implementing all steps, write **unit tests** for the new code (if TDD is enabled, most tests are already written — this step catches anything remaining):
+
+1. **Identify what to test** — new functions, components, utilities, type guards, mappers, or any logic introduced
+2. **Follow existing test patterns** — find the closest existing test file and match its style, imports, conventions
+3. **Place tests correctly** — follow the project's test file organization
+4. **Test behavior, not implementation** — focus on inputs/outputs, edge cases, and integration points
+
+Do not write tests for trivial code (pure config objects, re-exports, type-only files).
+
+---
+
+### Step 6 — Run Checks
+
+Run quality checks using the commands from Workflow Config:
+
+1. Run `lint-cmd`
+2. Run `test-cmd`
+3. Run `build-cmd`
+
+Run all checks even if earlier ones fail. For each failure:
+
+1. **Fix the issue** if it's caused by your implementation
+2. **Re-run** the failing check to confirm the fix
+3. **Document** any fixes in the implementation artifact
+4. If a failure is pre-existing (not caused by your changes), fix it anyway — all checks must be green before completing
+
+---
+
+### Step 7 — Write the Implementation Artifact
+
+Create `02-implementation.md` in the workflow folder:
+
+```markdown
+# Implementation: <feature title>
+
+> Spec: [01-spec.md](01-spec.md)
+> Date: YYYY-MM-DD
+> Mode: normal
+> Status: DONE | DONE_WITH_CONCERNS | BLOCKED
+
+## Summary
+
+<2–3 sentence summary of what was implemented.>
+
+## Steps Completed
+
+### Step 1 — <title from spec>
+
+**Files modified:**
+
+- `path/to/file.ext` — <what changed>
+
+**Files created:**
+
+- `path/to/new-file.ext` — <what it contains>
+
+<Brief description of what was done.>
+
+<Repeat for each step>
+
+## Tests Added
+
+- `path/to/test-file.test.ts` — <what it tests>
+
+## Deviations from Spec
+
+<If no deviations: "None — implementation followed the spec as written.">
+
+<If deviations exist, for each:>
+
+### <area of deviation>
+
+- **Spec said:** <what the spec specified>
+- **Found:** <what was actually encountered>
+- **Did instead:** <what you did and why>
+
+## Check Results
+
+| Check | Command | Result |
+|-------|---------|--------|
+| Lint | `<lint-cmd>` | Pass / Fail (details) |
+| Tests | `<test-cmd>` | Pass (N passed) / Fail (details) |
+| Build | `<build-cmd>` | Pass / Fail (details) |
+
+## Acceptance Criteria
+
+<Copy from the spec, with status:>
+
+- [x] <criterion that was met>
+- [ ] <criterion NOT met — explain why>
+
+## Discovered Issues
+
+<Anything found during implementation that is out of scope but worth noting.>
+```
+
+### Status Codes
+
+- **DONE** — all steps completed, all checks pass, all acceptance criteria met
+- **DONE_WITH_CONCERNS** — completed but with deviations, unmet criteria, or pre-existing failures worth noting
+- **BLOCKED** — could not complete due to a fundamental issue
+
+---
+
+### Step 8 — Report to User
+
+Present:
+
+1. Status (DONE / DONE_WITH_CONCERNS / BLOCKED)
+2. What was implemented (high level)
+3. How many tests were added
+4. Check results (pass/fail)
+5. Any deviations or unmet acceptance criteria
+6. The path to `02-implementation.md`
+
+Do **not** create any git commits. Leave that to the user or the ship skill.
+
+---
+
+## Fix Mode
+
+When the skill detects a FAIL review on startup, it enters fix mode. Fix mode is **scoped** — it only addresses what the review flagged, it doesn't re-implement the whole feature.
+
+### Step 2F — Read the Review Chain
+
+1. Read the latest review file (`04-review.md`, or the highest-numbered `04-review-N.md`)
+2. Read `02-implementation.md` to understand what was already done
+3. Read `01-spec.md` for original context
+4. Parse the review's "Summary for Fix Mode" section — extract each flagged issue with its severity
+
+### Step 3F — Present Fix Plan
+
+Summarize what the review flagged and what you'll fix. Ask for confirmation.
+
+### Step 4F — Fix Each Issue
+
+In the order the review lists them:
+
+1. Read the relevant files
+2. Make targeted fixes — do not touch code unrelated to the review's issues
+3. If a fix requires changing the approach (not just the code), document it
+
+### Step 5F — Re-run Checks
+
+Run `lint-cmd`, `test-cmd`, `build-cmd`. Fix any failures caused by your fixes.
+
+### Step 6F — Update the Implementation Artifact
+
+**Append** a "Fix Round N" section to `02-implementation.md`. Do NOT edit, replace, or rewrite any existing sections — the original implementation report and any prior fix rounds are the paper trail. Add a new section at the bottom:
+
+```markdown
+## Fix Round N
+
+> Review: [04-review-N.md](04-review-N.md)
+> Date: YYYY-MM-DD
+
+### Issues Addressed
+
+1. **<issue title from review>** — <what you did to fix it>
+2. ...
+
+### Updated Check Results
+
+| Check | Command | Result |
+|-------|---------|--------|
+| ... | ... | ... |
+```
+
+Update the top-level Status if appropriate.
+
+### Step 7F — Report
+
+Summarize fixes, updated check results, remaining concerns.
+
+### Iteration Cap
+
+After 3 fix rounds (meaning `04-review-3.md` exists and is still FAIL):
+
+1. Document the remaining issues
+2. Tell the user: "This feature has failed review 3 times. The remaining issues may need human judgment or a spec revision."
+3. Do not attempt a 4th fix automatically
+
+---
+
+## Constraints
+
+**DO:**
+- Read all referenced files before writing any code
+- Search for existing implementations before creating new functions/modules
+- Follow the spec's implementation steps in order
+- Write tests before production code (when TDD is enabled)
+- Run all quality checks after implementation
+- Document every deviation from the spec
+- Limit fix mode to only the issues the review flagged
+- In fix mode, always append a Fix Round section to `02-implementation.md` immediately after fixing — never overwrite or replace existing content. The doc is append-only.
+
+**DON'T:**
+- Modify files not listed in the spec — document the gap instead
+- Add features, refactoring, or improvements not in the spec
+- Skip codebase exploration before implementing
+- Claim completion without running checks and showing results
+- Leave pre-existing failures unfixed — always fix them so CI stays green
+- Re-implement the whole feature in fix mode — scope fixes to review issues only
+- Exceed 3 fix iterations — escalate to the user
+
+---
+
+## Red Flags
+
+If you catch yourself thinking any of these, stop:
+
+- "The spec says X but Y would be better" — STOP. Follow the spec. Document your concern as a Discovered Issue.
+- "I'll add this small improvement while I'm here" — STOP. Scope creep. The spec defines the scope.
+- "Tests can come later" — STOP. If TDD is enabled, test first. No exceptions.
+- "This file isn't in the spec but it needs updating" — STOP. Document the gap as a deviation. Don't silently expand scope.
+- "I'll skip the duplicate check, this is clearly new code" — STOP. You don't know that until you've searched.
+- "The checks are failing but it's not my fault" — STOP. Fix it anyway. All checks must be green, whether or not the failure is caused by your changes. Document it as a pre-existing fix.
+- "I've been going back and forth on this fix, let me try one more thing" — COUNT. If this is attempt 3, stop and escalate.
+- "I'll update the implementation doc to reflect the fixes" — STOP. You APPEND a new Fix Round section. Never edit or replace existing sections — they are the paper trail.

package/skills/indie/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: indie
+description: Autonomous end-to-end orchestrator. Takes a feature from description through spec, implementation, QA, review (with fix loops), shipping, and CI monitoring — in its own git worktree for parallel execution. Defaults to fully autonomous; user can set breakpoints to pause after any phase. Use when the user invokes /indie.
+---
+
+# Indie
+
+## Role
+
+You are a workflow orchestrator. You drive the full development chain — spec, implementation, QA, review, shipping, and CI monitoring — by invoking each skill in sequence and reading their output artifacts to decide the next step. You are a conductor, not a player: you never duplicate skill logic, you delegate to the skills and read their results.
+
+Each feature runs in its own git worktree, enabling multiple `/indie` invocations to run in parallel across separate terminals.
+
+By default you run fully autonomously. The user provides input once, you deliver a PR with green CI. If the user sets a breakpoint, you pause after that phase and wait for re-invocation to continue.
+
+## When to Apply
+
+Activate when called from the `/indie` command. Otherwise ignore.
+
+---
+
+## Input Handling
+
+`$ARGUMENTS` may be:
+
+- A **GitHub issue URL** (e.g. `https://github.com/org/repo/issues/42`) — passed to the spec-writer as input
+- **Free text** — a feature description, passed to the spec-writer as input
+- A **workflow folder reference** (folder name or path) — resume an existing workflow from wherever it left off
+- **Empty** — auto-detect: scan the workflow directory for incomplete workflows (folders missing later artifacts). If exactly one exists, resume it. If multiple, list and ask. If none, tell the user to provide a feature description.
+
+### Breakpoints
+
+The input may include a breakpoint instruction. Parse and strip it before passing the remainder as the feature description.
+
+**Syntax:** `--stop-after <phase>`, `stop after <phase>`, `pause after <phase>`, or `break after <phase>` anywhere in the input.
+
+**Recognized phases:** `spec`, `implement`, `qa`, `review`, `ship`
+
+**Examples:**
+- `/indie https://github.com/org/repo/issues/42 --stop-after spec`
+- `/indie add user avatars, stop after review`
+- `/indie dark-mode --stop-after implement`
+- `/indie https://github.com/org/repo/issues/42` — no breakpoint, fully autonomous
+
+**At a breakpoint:**
+1. Complete the phase normally
+2. Verify the output artifact exists
+3. Report: "Paused after `<phase>`. Artifact: `<path>`. Worktree: `<worktree-path>`. Review it, then re-invoke `/indie <folder>` to continue."
+4. Stop. Do not proceed.
+
+**Resuming:** The user re-invokes `/indie <folder>` from the worktree directory. Resume detection picks up from the artifact state. The user may set a new breakpoint or omit one to run to completion.
+
+**Artifact compatibility:** Breakpoints produce the exact same artifacts as a fully autonomous run. The user can mix modes — pause after spec, then let the rest run autonomously.
+
+---
+
+## Step 1 — Parse Input and Determine State
+
+1. Read the project's `CLAUDE.md`
+2. Find the `## Workflow Config` section and parse the key-value table. If it doesn't exist, stop: "No Workflow Config found. Run `/adjust` to set up the project."
+3. Parse and strip any breakpoint instruction from the input
+4. Determine the input type:
+   - Workflow folder reference → resolve it, jump to resume detection
+   - Issue URL or free text → new feature, proceed to Step 1W (worktree setup)
+   - Empty → scan `workflow-dir` for incomplete workflows (resume detection)
+
+---
+
+## Step 1W — Worktree Setup (new features only)
+
+1. **Derive the folder name:** Short, scannable kebab-case name (2–5 words) derived from the input. No timestamp prefix in the directory name. Example: `dark-mode`, `auth-refactor`, `db-seed-script`
+2. **Derive the branch name:** `<branch-prefix>YYYYMMDD-HHMM-<folder-name>` using the current timestamp. Example: `feature/20260413-1423-dark-mode`. The timestamp lives in the branch name, not the directory.
+3. **Determine the worktree path:** `../../wt/<folder-name>` — inside the `wt/` subdirectory at the project root. Example: if you're running from `~/projects/rival.sale/main`, the worktree goes to `~/projects/rival.sale/wt/dark-mode`.
+4. **Create the worktree:** `mkdir -p ../../wt && git worktree add <worktree-path> -b <branch-name> <base-branch>` (run from the current worktree — git resolves the bare repo automatically)
+5. **Copy local environment files:** Copy `.env` (and `.env.local` if it exists) from the current worktree into the new worktree. These are gitignored and won't exist in the fresh checkout.
+6. **Switch context:** all subsequent steps run inside the worktree directory
+
+Present a one-line plan:
+- **No breakpoint:** "Starting autonomous workflow for: `<feature summary>` in worktree `<path>`. Will run: spec → implement → qa → review → ship → monitor CI. I'll report back when done or if I hit a blocker."
+- **With breakpoint:** "Starting workflow for: `<feature summary>` in worktree `<path>`. Will run through `<phase>` and pause for your review."
+- **Resuming:** "Resuming workflow `<folder>` from `<next phase>`."
+
+---
+
+## Resume Detection
+
+Read the workflow folder and determine the current state from existing artifacts:
+
+| State | Artifacts Present | Next Action |
+|-------|-------------------|-------------|
+| Nothing | No workflow folder | Run spec-writer (Step 2) |
+| Spec done | `01-spec.md` only | Run implementation (Step 3) |
+| Implementation done | `+ 02-implementation.md` | Run QA (Step 4) |
+| QA done | `+ 03-qa*.md` (latest) | Run review (Step 5) |
+| Review FAIL | `+ 04-review*.md` with FAIL verdict | Run implementation fix mode (Step 5F) |
+| Review PASS | `+ 04-review*.md` with PASS verdict | Run ship (Step 6) |
+| PR created | PR exists on remote branch | Monitor CI (Step 7) |
+| CI passing | All checks green | Write summary (Step 8) |
+| CI failing | Checks red | CI fix loop (Step 7F) |
+
+**To detect "PR created":** Check if the current branch exists on the remote (`git ls-remote --heads origin <branch-name>`). If it does, find the PR with `gh pr list --head <branch-name>`.
+
+This makes the skill idempotent — re-invoking `/indie` on a partially completed workflow resumes from the correct point without re-running completed phases.
+
+---
+
+## Step 2 — Spec Phase
+
+Follow the spec-writer skill's full process:
+
+1. Parse the input (issue URL → fetch with `gh issue view`; free text → use directly)
+2. Read CLAUDE.md and project conventions
+3. Explore the codebase — find affected areas, structural templates, current state
+4. Determine spec depth (lightweight / standard / deep)
+5. Create the workflow folder: `<workflow-dir>/<folder-name>/` using the timestamp-based name from Step 1W
+6. Write `01-spec.md`
+
+**Overrides for autonomous mode:**
+- Skip the ambiguity check's user questions — make reasonable decisions and document assumptions in the spec
+- Skip "present and refine" — write the spec and move on
+- If requirements are genuinely too vague to plan (no identifiable feature, contradictory requirements), escalate: "Cannot write a spec — the requirements are too ambiguous. Please clarify: [specific questions]."
+
+**Gate:** Verify `01-spec.md` exists and contains an Acceptance Criteria section with at least one criterion. If breakpoint is `spec`, pause here.
+
+---
+
+## Step 3 — Implementation Phase
+
+Follow the implementation skill's full process:
+
+1. Read `01-spec.md` — the spec is the contract
+2. Read the codebase — understand files that need to change
+3. Implement each step from the spec in order
+4. Write tests (TDD if `tdd: true` in config)
+5. Run quality checks (`lint-cmd`, `test-cmd`, `build-cmd`)
+6. Write `02-implementation.md`
+
+**Overrides for autonomous mode:**
+- Skip "present summary and get confirmation" — begin implementing immediately after reading the spec
+
+**Gate:** Verify `02-implementation.md` exists and has check results. If breakpoint is `implement`, pause here.
+
+---
+
+## Step 4 — QA Phase
+
+Follow the qa-engineer skill's full process:
+
+1. Read `01-spec.md` independently (don't trust the implementation report)
+2. Find existing e2e test patterns in the project
+3. Design tests from acceptance criteria
+4. Write e2e tests following project conventions
+5. Run tests with `e2e-cmd`
+6. Verify test substance (no stubs)
+7. Write `03-qa.md` (or `03-qa-N.md` for re-runs)
+
+**Overrides:** None — the QA skill already runs without confirmation.
+
+**Gate:** Verify `03-qa.md` (or latest `03-qa-N.md`) exists. If breakpoint is `qa`, pause here. Otherwise read its status:
+- **PASS** → proceed to review
+- **FAIL** → log it, proceed to review (the review will catch the implementation issue)
+- **PARTIAL** → proceed to review (some criteria may be untestable via e2e)
+
+---
+
+## Step 5 — Review Phase
+
+Follow the review skill's full process:
+
+1. Load all artifacts (spec, implementation, QA, any prior reviews)
+2. Read the actual code — do not trust the implementation report
+3. Evaluate spec compliance, code quality, QA results
+4. Run independent verification (`lint-cmd`, `test-cmd`, `build-cmd`, `e2e-cmd`)
+5. Compile issues with severity (CRITICAL / MAJOR / MINOR)
+6. Render binary verdict (PASS or FAIL)
+7. Write `04-review.md` (or `04-review-N.md` for re-reviews)
+
+**Overrides:** None. The review skill's adversarial stance is non-negotiable. Never soften review criteria to avoid fix loops.
+
+**Gate:** Read the review verdict. If breakpoint is `review`, pause here (regardless of PASS or FAIL — let the user see the result). Otherwise:
+- **PASS** → proceed to Step 6 (ship)
+- **FAIL** → enter the fix loop (Step 5F)
+
+---
+
+## Step 5F — Fix Loop
+
+When review returns FAIL:
+
+1. **Check iteration count** — count `04-review*.md` files in the workflow folder. If 10 exist, escalate: "Feature has failed review 10 times. Escalating for human judgment. Review history: [list all review files with their verdicts and key issues]."
+2. **Run implementation in fix mode** — it detects the FAIL review on startup, reads the flagged issues, addresses only those issues, appends a "Fix Round N" section to `02-implementation.md`
+3. **Re-run QA** — produces `03-qa-N.md`, verifying the fixes and any new tests
+4. **Re-run review** — produces `04-review-N.md` with a fresh verdict
+5. **Read verdict:**
+   - **PASS** → proceed to Step 6
+   - **FAIL** → loop back to 5F.1
+
+---
+
+## Step 6 — Ship Phase
+
+Follow the ship skill's full process:
+
+1. Verify the latest review has a PASS verdict
+2. Run pre-flight checks (`lint-cmd`, `test-cmd`, `build-cmd`; check `git status`)
+3. Read workflow artifacts to assemble the PR body
+4. The branch already exists (created with the worktree in Step 1W) — use the current branch
+5. Stage implementation files and the workflow folder
+6. Commit with a descriptive message referencing the spec
+7. Push: `git push -u origin <branch-name>`
+8. Create PR: `gh pr create --title "<title>" --body "<generated body>" --base <base-branch>`
+
+**Overrides for autonomous mode:**
+- Skip the confirmation gate — execute the full pipeline (stage → commit → push → PR) without stopping. The review PASS verdict is the authorization.
+
+**Gate:** Verify the PR was created. Extract the PR URL and number. If breakpoint is `ship`, pause here.
+
+---
+
+## Step 7 — CI Monitoring Phase
+
+1. **Wait for CI to start** — wait 60 seconds, then poll `gh pr checks <PR-number> --repo <owner>/<repo>` every 30 seconds until at least one check has started (status is not all "pending").
+2. **Wait for CI to complete** — continue polling until all checks have a conclusion (`success`, `failure`, `skipped`, or `cancelled`). Max wait: 15 minutes total from first poll. If CI hasn't completed after 15 minutes, report the current status and halt: "CI is still running after 15 minutes. Current status: [check names and statuses]. PR: [URL]."
+3. **Evaluate results:**
+   - All checks pass (or skipped) → proceed to Step 8 (done)
+   - Any check fails → enter CI fix loop (Step 7F)
+
+---
+
+## Step 7F — CI Fix Loop
+
+When CI checks fail:
+
+1. **Check iteration count** — if 10 CI fix attempts have already been made, escalate: "CI has failed 10 times after fixes. Escalating to user. PR: [URL]. Latest failure: [summary]."
+2. **Identify the failed run** — use `gh pr checks` output to find the failed check's details URL, extract the run ID
+3. **Read failure logs** — `gh run view <run-id> --log-failed --repo <owner>/<repo>` to get the failed job output
+4. **Diagnose:**
+   - **Test failure** — read the test output, identify root cause (flaky test vs environment issue vs actual bug)
+   - **Build/type-check failure** — read the error, identify the file and issue
+   - **Lint failure** — read the violation
+5. **Fix** — make the minimal code change to resolve the failure. Only fix what CI flagged. Do not refactor, add features, or "improve" surrounding code.
+6. **Stage, commit, push:**
+   - Stage only the changed files
+   - Commit: `fix(ci): <one-line description of what was fixed>`
+   - Push to the same branch
+7. **Re-monitor** — return to Step 7 to watch the new CI run
+
+---
+
+## Step 8 — Final Report
+
+Write `05-indie-summary.md` in the workflow folder:
+
+```markdown
+# Indie Run: <feature title>
+
+> Date: YYYY-MM-DD
+> Status: DONE | DONE_WITH_CI_FIXES | ESCALATED
+> PR: <PR URL>
+> Worktree: <worktree path>
+
+## Phases Completed
+
+| Phase | Artifact | Status | Iterations |
+|-------|----------|--------|------------|
+| Spec | 01-spec.md | Done | 1 |
+| Implementation | 02-implementation.md | Done | 1 (+ N fix rounds) |
+| QA | 03-qa.md — 03-qa-N.md | PASS | N |
+| Review | 04-review.md — 04-review-N.md | PASS | N |
+| Ship | PR #<number> | Created | 1 |
+| CI | <check names> | Pass | N attempts |
+
+## Review Loop Summary
+
+<If reviews > 1: what issues were found and how they were fixed>
+<If no loop: "First review passed.">
+
+## CI Fix Summary
+
+<If CI fixes were needed: what failed and what was fixed>
+<If no fixes: "CI passed on first run.">
+
+## Final State
+
+- Worktree: <worktree path>
+- Branch: <branch name>
+- PR: <PR URL>
+- Checks: <all green / current status>
+- Total commits: <count> (implementation + CI fixes)
+```
+
+After writing the summary:
+1. Stage `05-indie-summary.md`: `git add <workflow-dir>/<folder-name>/05-indie-summary.md`
+2. Commit: `docs: add indie run summary for <feature-name>`
+3. Push to the same branch
+
+Present the final report to the user: PR URL, check status, iteration counts, and worktree path. Remind: "After merge, clean up with: `git worktree remove <path> && rm -rf <path>`"
+
+---
+
+## Constraints
+
+**DO:**
+- Create a dedicated worktree for each new feature — this enables parallel runs
+- Use short, scannable folder names in `wt/` (timestamp goes in the branch name, not the directory) — never sequential numbers
+- Check artifact state before each phase — never re-run completed phases
+- Respect the 10-iteration cap on both the review loop and the CI fix loop
+- Escalate with full context when hitting a cap or an unrecoverable error
+- Keep CI fixes minimal and scoped — fix only what CI flagged
+- Preserve the full audit trail — all review files, QA re-runs, and fix rounds are kept
+- Produce the same artifacts whether running autonomously or with breakpoints
+
+**DON'T:**
+- Ask the user anything during execution — the only interaction points are the initial input, breakpoints (if set), and the final report (or escalation)
+- Modify the review or QA skills' behavior — their independence is the quality gate
+- Skip phases — every phase runs, even if the code "looks fine"
+- Continue after 10 review FAILs or 10 CI fix failures — escalate, don't loop forever
+- Re-run completed phases on resume — read existing artifacts and pick up where you left off
+- Make large code changes during CI fixes — if the fix is architectural, escalate
+- Rewrite the spec after it's written — review issues are addressed in implementation fix mode, not by revising the spec
+- Delete the worktree automatically — leave cleanup to the user after merge
+
+---
+
+## Red Flags
+
+If you catch yourself thinking any of these, stop:
+
+- "The implementation looks solid, I'll skip QA" — STOP. Every phase runs. The workflow's value is the adversarial chain.
+- "The review is being too strict, I'll soften the criteria" — STOP. The review's adversarial stance is non-negotiable. If it keeps failing, the code has real issues.
+- "CI is flaky, I'll just re-run without fixing anything" — STOP. Read the logs. Diagnose before acting.
+- "I'll ask the user what to do about this ambiguity" — STOP. Unless there's a breakpoint, you're autonomous. Decide and document.
+- "This CI fix requires changing the feature implementation" — STOP. CI fixes are minimal. Escalate if the fix is architectural.
+- "I've been running for a while, I should wrap up" — STOP. Follow the process. Escalate at the cap, don't shortcut.
+- "I'll re-run the spec since the review found issues" — STOP. The spec is locked. Review issues go through implementation fix mode.
+- "I should confirm this with the user before pushing" — STOP. The review PASS is the authorization. Unless there's a `ship` breakpoint, push and create the PR.
+- "I'll work in the main checkout instead of creating a worktree" — STOP. Always create a worktree for new features. It enables parallel runs and keeps the main checkout clean.