| name | insight-devloop |
| description | 4-step build loop for human+AI teams. Consumes plan.md (with Challenge section) from /insight-plan, then executes: Frame (triage) → Build (TDD + parallel worktrees) → Ship (merge + normalize + verify). Use after /plan produces artifacts, or for any scoped task ready to build. Trigger on: 'build this', 'execute the plan', 'run devloop', 'start building', or when plan.md exists and user wants to proceed. |
| model | opus |
| disable-model-invocation | true |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash(npx jest*), Bash(npx tsc*), Bash(git *), Agent, Skill(frontend-design), AskUserQuestion |
| argument-hint | [path-to-plan.md] |
DevLoop — The Crew
A 4-step build loop: Frame → Build → Ship → Done. Each step has crew, each produces artifacts for the next.
The Crew
| Role | Persona | Model | Output |
|---|
| Decomposition | The Quartermaster | Opus | frame.md |
| TDD | The Sentinel | Opus | Failing test suite |
| Builder | The Shipwright | Sonnet | Passing implementation in worktree |
| Adversarial + Consistency | The Storm | Opus | storm-report.md, storm-tdd.md |
| Edge Cases | The Cartographer | Sonnet | edge-cases.md |
| Chaos | The Monkey | Opus | monkey-frame.md, monkey-build.md |
| Retro | The Lookout | Sonnet | Crew round + learnings (separate skill) |
Lean Crew (Small triage)
| Agent | Lean (Small) | Full (Medium+) |
|---|
| Monkey Frame | Yes | Yes |
| Sentinel | Yes | Yes |
| Storm TDD | Yes | Yes |
| Shipwright | Yes | Yes |
| Storm Verify | Yes | Yes |
| Cartographer | No | Yes |
| Build Monkey | No | Yes |
Gate: Triage: Small. Lean crew. Approve / Full crew / Adjust / Abort
After plan correction (§ Quartermaster correction mode), re-evaluate triage. If Small→Medium, escalate to Full. Convergence gate states what was skipped, nudges retro.
Step 0: Load Project Values
Read VALUES.md and TDD-MATRIX.md at repo root if they exist. Read .insightsLoop/config.md for engine tunables (defaults: monkey_findings_per_step: 3 per vertical, confidence_threshold: 80).
When constructing Monkey briefs: substitute [N] in templates with monkey_findings_per_step from config. Tell the Monkey: "Produce {N} findings per vertical, each using a different technique."
Read each crew SKILL.md right before briefing that crew member — not all upfront:
.claude/skills/insight-quartermaster/SKILL.md — before Step 1.claude/skills/insight-sentinel/SKILL.md — before Step 2a.claude/skills/insight-storm/SKILL.md — before Step 2a (TDD Review).claude/skills/insight-shipwright/SKILL.md — before Step 2b.claude/skills/insight-storm/SKILL.md — re-read before Step 3b.claude/skills/insight-edge-case-hunter/SKILL.md — before Step 3b
Briefing
Paste SKILL.md verbatim into the Agent prompt — the entire file, not selected sections. Then add one line: "Read .insightsLoop/current/brief-<crew>.md for your mission context." The SKILL.md is the agent's identity; the brief is the run-specific context.
Fill template from brief-templates/. Write brief to .insightsLoop/current/brief-<crew>.md. For parallel Shipwrights, number them: brief-shipwright-1.md, brief-shipwright-2.md. Present crew output as-is — do not rewrite or narrate. All brief-*.md files are on the archive discard list.
No VALUES_MD slot in templates — agents read VALUES.md themselves.
Artifact Persistence
Write artifacts to disk immediately after each agent returns. Agent output alone is not persistent — if you don't write the file, the archive loses the artifact. This applies to: monkey-frame.md, storm-tdd.md, storm-report.md, edge-cases.md, monkey-build.md.
Step 0.5: Resume Check
If .insightsLoop/current/ has artifacts, ask: Resume (skip steps whose output exists) / Start fresh (archive, begin new) / Abort.
Gates always re-run on resume (Sentinel gate, user approvals). Natural idempotency handles the rest.
Artifact Directory
.insightsLoop/
├── current/ ← active run (create if doesn't exist)
│ ├── plan.md, frame.md, monkey-frame.md, storm-tdd.md
│ ├── monkey-build.md, storm-report.md, edge-cases.md
│ └── brief-*.md (ephemeral)
└── run-NNNN-feature-name/ ← archived run
Keep: summary.md, plan.md, monkey-frame.md, monkey-build.md, storm-tdd.md, storm-report.md, storm-plan.md, findings-consolidated.md, fix-specs.md, scaffolding-checklist.md, mockup.html (all if exists).
Discard: frame.md, edge-cases.md, brief-*.md.
Prerequisites
plan.md with ## Challenge required. Search: $ARGUMENTS → .insightsLoop/current/plan.md → repo root plan.md. No plan = no build. No Challenge section = incomplete plan. Both are hard gates. Normalize plan.md into .insightsLoop/current/ before proceeding.
Definitions
- "Task" = unit of work for one Shipwright in one worktree.
- "Done" = step's output artifact is produced and next step can consume it.
Monkey Scope Rules (Frame)
What IS a Frame finding: impossible requirements, hard dependencies on unreliable things, missing shared contracts between parallel worktrees, silent assumptions between components, design decisions that lock you into expensive paths.
What is NOT a Frame finding: naming conventions, missing input validation, standard security hygiene, "this component should be inlined," anything that imagines what code will look like. Storm catches these on real code.
Verticals
| Vertical | Lens | Best Techniques |
|---|
| Architecture | Coupling, abstractions, dependency direction, YAGNI violations, unnecessary layers | Existence Question, Assumption Flip, Delete Probe |
| Data | Queries, N+1, missing indexes, partial state, transactions, migration safety | Scale Shift, Time Travel, Hostile Input |
| Security | Auth gaps, injection, validation, secrets, privilege escalation | Hostile Input, Assumption Flip, Requirement Inversion |
| Integration | Cross-module seams, naming mismatches, assumption conflicts, API drift | Cross-Seam Probe, Assumption Flip, Scale Shift |
| Operational | 3am failures, monitoring, recovery, deploy safety, config drift | Time Travel, Scale Shift, Requirement Inversion |
Vertical selection: The orchestrator selects relevant verticals based on the plan:
- Pure UI story → skip Data, Security (unless auth-related)
- API-only story → skip Operational (unless deployment changes)
- Always run Architecture and Integration
- When in doubt, include all 5
Step 1: Frame
The orchestrator does NOT decompose the plan itself. The Quartermaster does. The orchestrator invokes, presents, gates.
1a: Quartermaster(template:quartermaster) → frame.md
1b: Monkey(template:monkey-frame, scope:plan-level) → monkey-frame.md
Impact tags: orchestrator sorts by breaks-build → values-gap → nice-to-have
1c: Gate — Approve / Adjust / Abort
Survived:no → highlight, re-scope
Adjust → Quartermaster(template:quartermaster-correction, selected findings from monkey-frame.md)
Re-evaluate triage after correction. No Monkey re-run.
1a: The orchestrator does NOT modify frame.md. It is the Quartermaster's artifact. If changes needed, re-invoke the Quartermaster.
1b — Dedup: If .insightsLoop/current/monkey-plan.md exists (from Navigator), include its findings in "Previous Monkey findings" so the Frame Monkey doesn't repeat them.
1c — Gate wording: "Frame and Monkey review complete. [N tasks, M worktrees, parallelization shape]. [Monkey summary]. Approve / Adjust / Abort." If adjust: re-invoke the Quartermaster with feedback. Do NOT manually edit frame.md.
SELECTED_FINDINGS: Orchestrator reads full detail from monkey-frame.md for user-selected finding numbers. Not from summary return.
Sentinel Gate
Three checks before Step 2a, every run (including resume):
Manifest exists? Lock file exists? Test framework installed? Any fail (non-greenfield): stop. Greenfield: Task 0 must have run.
Step 2: Build
2a: Sentinel(template:sentinel) → test files
Storm TDD(template:storm-tdd) → storm-tdd.md
critical/high → Gate → re-invoke Sentinel
2b: Shipwright(template:shipwright, worktree, isolation:"worktree") × N
independent ∥, dependent →
Task 0 (greenfield): Shipwright(template:shipwright-scaffold) in main dir before Sentinel gate
2a: The Sentinel must be a separate agent from the builder. If Storm TDD finds critical/high gaps: dispatch to the Sentinel to write missing contracts — the orchestrator does NOT write tests itself.
2b: Each Shipwright runs in an isolated worktree (isolation: "worktree"). Independent tasks in parallel, dependent tasks sequential per frame.md parallelization plan.
Step 3: Ship
3a: Merge worktrees → main (never auto-resolve)
3b: Storm(template:storm-verify) ∥ Cartographer(template:cartographer)
→ Build Monkey(template:monkey-build)
Gate: "Storm:[N] Cart:[N] Monkey:[N]. Fix / Discuss / Stop"
Lean gate: "Storm:[N]. Fix / Discuss / Stop" (Cart + Monkey skipped)
Normalize at consolidation: impact tags → severity
breaks-build → critical/high, values-gap → medium, nice-to-have → low
3c: Consolidate → sort(severity) → triage(matrix) → Gate
full: Storm(spec, inline brief) → Sentinel(test, inline brief) → Shipwright(patch, inline brief)
direct: Shipwright(rename)
backlog: log, skip
max 2/finding → backlog
Note: fix pipeline briefs are inline — short, context-specific, no template needed
3d: tests + typecheck → all pass → shippable
3a: Merge Procedure
Pre-merge check: Only merge worktrees where the Shipwright completed successfully (all tests pass). Skip stopped worktrees. Present: "Merging: [list]. Skipped (stopped): [list]." If all stopped, loop back to user.
For each worktree:
- Check which files were modified
- No overlap with other worktrees → fast-forward merge
- Files overlap → present conflict to user, never auto-resolve
3b: Verify + Converge
Cartographer skip condition: If the story is visual-only (layout, CSS, copy changes) with no new code paths, skip the Cartographer. Write empty edge-cases.md (header only) noting "Skipped: visual-only change."
Build Monkey: Do not skip. Do not proceed to convergence without running.
This is a hard gate. Do not proceed to 3c without completing convergence.
Present all findings: Storm: [N] introduced ([severity breakdown]), [N] consistency. Cartographer: [N] (or "skipped"). Monkey: [N] across [M] verticals, [X] survived, [Y] didn't. Gate: "Proceed to fix pipeline / Discuss / Stop"
FINDINGS_BEFORE_SHIP in storm-verify template = monkey-frame.md + storm-tdd.md only. Files from the same step (monkey-build.md, edge-cases.md) don't exist yet.
3c: Consolidate + Fix Pipeline
Consolidated Findings → .insightsLoop/current/findings-consolidated.md:
| # | Source | Phase | Location | Issue | Severity | Status |
Location: file.ts:33 = actionable (fix pipeline eligible). [concept] description = conceptual (straight to Backlog). Sort: severity desc, sub-sort by file + line. No auto-dedup — note "Possible dup of #N", user confirms.
Triage gate: "Consolidated findings: [N] total, [M] actionable. Triage: [N] full pipeline, [N] Shipwright-direct. Fix / Skip to backlog / Discuss"
Findings Dispatch (Monkey + Storm TDD)
| Source | Step | Finding Type | Dispatched To |
|---|
| Monkey | Frame | Scope/triage challenge | Orchestrator (frame.md is not code) |
| Monkey | Frame | Conceptual finding | Backlog |
| Storm | TDD | Missing test contract | Sentinel (re-invoke) |
| Storm | TDD | Over-testing / wrong abstraction | User decides |
| Monkey | Build | Finding with file:line | Enters consolidated findings → fix matrix |
| Monkey | Build | Conceptual finding | Backlog |
Fix Dispatch Matrix
The orchestrator NEVER writes code. Not one line. Not a rename.
| Finding Type | Route | Who Specs | Who Tests | Who Fixes |
|---|
| Storm critical/high (file:line) | Full pipeline | Storm (Fix Spec) | Sentinel (regression test) | Shipwright (patch) |
| Storm consistency — assumption mismatch | Full pipeline | Storm (Fix Spec) | Sentinel (regression test) | Shipwright (patch) |
| Storm consistency — naming only | Shipwright-direct | N/A | N/A | Shipwright (rename) |
| Cartographer — data corruption/crash | Full pipeline | Storm (Fix Spec) | Sentinel (regression test) | Shipwright (patch) |
Monkey Survived: no, high confidence, file:line | Full pipeline | Storm (Fix Spec) | Sentinel (regression test) | Shipwright (patch) |
Monkey Survived: no, low confidence or [concept] | Backlog | — | — | — |
| Dup of #N | Skip | — | — | — |
Full Pipeline (3 agents, sequential)
- Storm Fix Spec →
.insightsLoop/current/fix-specs.md — one spec per finding: regression test contract, fix location, fix intent, boundary (what NOT to touch). Does NOT write code or tests.
- Sentinel regression tests — one test per fix spec. Each must fail before fix is applied.
- Shipwright patches — minimum patches. Runs full suite. All tests pass — old and new.
Shipwright-direct: Receives Storm consistency table with canonical forms, applies renames. Existing tests must still pass.
Fix gate: "Fix pipeline patched [N] findings ([M] full, [K] rename). Approve?" Max 2 fix attempts per finding. If tests fail after fixes: stop, present to user.
Update consolidated report Status column: Fixed, Unresolved, Backlog, Dup of #N.
Step 4: Done
Write .insightsLoop/current/summary.md:
# Run Summary
**Feature:** [from plan.md title]
**Date:** [ISO date]
**Triage:** [small/medium/architectural]
## What Was Built
[Brief description]
## Files
- Created: [list]
- Modified: [list]
## Tests
- Before: [count]
- After: [count]
## Findings
- Storm Verify: [X critical, Y high, Z medium, W low]
- Storm TDD: [X test gaps found]
- Cartographer: [X findings]
- Monkey (Frame): [X findings across Y verticals, Z survived]
- Monkey (Build): [X findings across Y verticals, Z survived]
## Decisions
[Any decisions made during the build]
Archive the run:
- Determine next run number (look at existing
run-* dirs)
- Keep: summary.md, plan.md, monkey-frame.md, monkey-build.md, storm-tdd.md, storm-report.md, storm-plan.md, findings-consolidated.md, fix-specs.md, scaffolding-checklist.md, mockup.html (all if exists)
- Delete: frame.md, edge-cases.md, brief-*.md
- Rename
.insightsLoop/current/ → .insightsLoop/run-NNNN-feature-name/
Run naming: NNNN zero-padded sequential, feature-name from plan.md # Plan: [Feature Name] heading, lowercased and hyphenated.
Present summary. Suggest: run /insight-retro to capture learnings.
Errors
Sentinel won't compile → stop, loop to plan
Shipwright fails ×3 → stop worktree, show user
Merge conflict → never auto-resolve, user picks
Pass in wt, fail merged → integration bug, check Monkey Frame
Typecheck fails → check Storm Consistency
Fix causes regression → show both, user decides (fix regression / revert + backlog / different approach)
Model Assignment
| Role | Model | Why |
|---|
| TDD agent | Opus | Correlated failure protection needs strong contracts |
| Builder agents | Sonnet | Pattern-following, speed matters |
| Adversarial + Consistency | Opus | Must find real issues, not surface noise |
| Edge case hunter | Sonnet | Mechanical enumeration, method not judgment |
| Monkey | Opus | Chaos requires intelligence |
User Gates
Every decision point uses AskUserQuestion. Never present a decision as plain text.
| When | Gate | Options |
|---|
| Step 1c | Approve triage and parallelization | Approve / Adjust / Abort |
| Step 1c | Monkey Survived: no | Re-scope / Ignore / Abort |
| Step 2a | Storm TDD critical/high | Add contracts / Ignore / Rethink |
| Step 3a | Merge conflict | Show both, user picks |
| Step 3b | Converge (all agents done) | Fix pipeline / Discuss / Stop |
| Step 3d | After fixes + verify clean | Ship / Fix more / Abort |
Rules
- Every user gate uses
AskUserQuestion. No exceptions.
- Never run TDD and build in the same agent. Correlated failure is silent and deadly.
- The orchestrator NEVER writes code. Dispatch to crew via fix matrix.
- The Monkey is a real agent — brief, context, structured markdown back.
- Always use worktree isolation for parallel agents.
- Empty edge case report is valid.
- Human approves at Frame. Don't build without go-ahead.
- Plan is a hard gate. No plan.md = no build.
- Archive runs, don't delete.
current/ → run-NNNN-feature-name/.
- Stop condition: fix critical/high Storm, data-corruption/crash Cartographer,
Survived: no high-confidence Monkey. Rest → backlog.
