dev-loop

English | 한국어

A Claude Code plugin that merges two things into one self-contained tool:

• loop-orchestrator — a methodology-grounded verification loop (TDD / PDCA / Reflexion) for driving one task, or many parallel tasks, to "done".
• dev-llm-wiki — a case-routed, semantic-layer knowledge base of software best-practices, edge cases, and development-process methodology (test-first ordering, review discipline, completion-evidence gates, agent-orchestration decision policy, agent-facing tool/instruction design), plus a planning methodology that grounds every design decision in it.

And it scales past one session: the orchestrate skill is a multi-session orchestrator over the same loop — it decomposes a goal into a dependency graph, schedules parallel workers with a ready-set scheduler, and supervises them Orca-natively when the Orca CLI is installed (raw tmux otherwise). See Orca integration, and watch a run live from the coordinator's own session with the session-progress mod.

The one change from upstream loop-orchestrator: the plan step is no longer an optional, pluggable role. It is fixed to the bundled wiki-plan methodology — every non-trivial task plans by routing each design decision to a page in the bundled wiki/ before any code is written. Since v1.17.0 that planning itself runs as three gated phases — Analyze → Design → Decompose — each judged mechanically before the next may start (see below). The rest of the loop is unchanged.

On top of that, dev-loop adds a knowledge-capture loop: your sessions emit verified insights, and knowledge-flush researches, de-dups, routes, and opens a reviewed PR that grows the wiki over time.

---

Install (global)

Installed via the Claude Code plugin marketplace, so the skills and hooks apply globally across every project you work in:

/plugin marketplace add choiyounggi/dev-loop
/plugin install dev-loop@dev-loop

Nothing is repo-scoped: the wiki-grounded loop, the ★ Insight capture instruction, and the harvest hook are active in any repository you open.

---

The implementation loop

Run it two ways:

• One task or one feature → the loop-implement skill — the single implementer. Step 2 runs wiki-plan once to produce an ordered task list where each task names the exact wiki pages that ground it; the loop then executes those tasks in the plan's order, and per task runs: 0 define done → 1 analyze + load the task's named wiki pages → 3 tests (Red) → 4 implement (apply the pages' directives, no improvisation) → 5 run → 6 self-review → 6.5 independent test-quality audit → 7 judge (report the WIKI references applied) → 7b reflect + retry (bounded). There is no separate executor — the wiki-executor discipline (load only named pages, decisions win, BLOCKED-on-gap) is folded into this loop.
• A whole goal, split across parallel worker sessions → the orchestrate skill: intake → decompose (approval gate) → dispatch loop: plan (wiki-plan on the task-analyst + task-planner agents) → implement + review (each session runs loop-implement) → integration test → pre-merge gate → merge. There is no wave barrier: a dependency graph plus slot accounting starts each task the moment its own dependencies are approved and a slot is free, so a finished worker is refilled instead of waiting out its batch's slowest member. A worker that finds its task far larger than the brief assumed can propose splitting it mid-run. Substrate: Orca when detected — offered at the task-split gate — drives spawn and supervision; otherwise raw tmux. On Orca each phase is a tracked Task + Dispatch, and the coordinator blocks on pushed worker_done / escalation / question mail instead of polling status files on a timer — so a worker's blocking question reaches you in seconds. On tmux the original status-file poll is unchanged. Either way, worker sessions escalate a guardrails ask instead of blocking, and a dead worker is detected fast rather than stalling the run.

Step 2 is fixed to wiki-plan — three gated phases

wiki-plan runs Phase A (Analyze) → gate-A → Phase B (Design) → gate-B → Phase C (Decompose). Every exit condition is machine-checkable — plan-gate.sh emit writes a gates ledger and gate-check.sh --run judges it — so "the plan is ready" is never a self-report:

• Phase A — Analyze (plans/<feature>/analysis.md): requirements as an Example-Mapping table (an unresolved OPEN: question blocks entry to Phase B — Definition of Ready); ground truth with evidence attached (a re-runnable baseline test command, affected files each with the search that proved them, pinned-file constraints); time-boxed spikes for load-bearing unknowns; and an external best-practice search via the research role.
• Phase B — Design (plans/<feature>/design.md): the wiki routing sweep — read INDEX.md, then each touched domain's index.md, and for every design decision find the page that owns it. Each decision row carries its choice, its wiki basis as a real path (gate-B greps that the page exists), the rejected alternative, and the test that would catch it being wrong. A decision no page covers is marked [no-wiki] and becomes an ingest candidate. The design is then reviewed by the plan-reviewer subagent — read-only, fresh context, so the session that wrote the plan never grades its own design.
• Phase C — Decompose: ordered, small-model-sized tasks, each naming the exact wiki pages that ground it and the requirement (covers: R<n>) its verification proves — coverage is checked in both directions. Decisions are written as concrete values/code (never "as appropriate"), so the implementing pass executes instead of guessing.

Small tasks take a lite mode (machine-judged: small size, no [no-wiki], no pins touched) that keeps the baseline pin and grounding grep but skips the reviewer — recorded as an open ABANDON on the ledger, never a silent skip. This is not a configurable role and cannot be turned off.

The wiki lives at the plugin root (wiki/, INDEX.md, AGENTS.md, templates/); the wiki skills resolve their paths against ${CLAUDE_PLUGIN_ROOT}.

A project can add its own layer at <repo>/wiki-local/ (same templates/page.md schema, one wiki-local/index.md map, ids local-<domain>-<category>-<slug>). wiki-plan cites local pages as first-class Wiki basis groundings, the routing protocol reads the local index only when it exists, and a local page wins over a bundled page on the same trigger.

Configuring your tools (optional)

Like loop-orchestrator, dev-loop runs fully generic with no config, but you can map its capability roles to your real tools so the loop uses them:

Role	Map to
verify	your project's test / build / lint / typecheck / QA command (the loop's run step)
knowledge	your domain/team wiki or knowledge MCP (external facts)
explore	code/symbol search (LSP, ripgrep, a source-search CLI)
tacit	past incidents / danger-zone lore
design	Figma / visual-spec MCP (UI work)
intake	issue tracker (orchestrate's work-list)
research	external best-practice/pitfall search (wiki-plan Phase A/B). Fixed fallback when unset: brave-search MCP if present → built-in WebSearch → open ABANDON

(plan is not a role — the plan step is fixed to wiki-plan. And the bundled best-practice wiki/ needs no config; knowledge is a separate external wiki — the project's own wiki-local/ layer needs no config either.)

Set it up with /dev-loop:configure, which writes ~/.claude/dev-loop/tools.json (global) or <repo>/.dev-loop/tools.json (per-repo, team-shared). Precedence is git-config style: defaults < ~/.claude/dev-loop/tools.json < <repo>/.dev-loop/tools.json. A SessionStart hook nudges you (at most weekly, then never) if you haven't configured anything — silence it with DEV_LOOP_CONFIG_NUDGE=0. Legacy loop-orchestrator config paths are still read as a fallback. See references/tool-profile.md and examples/tools.example.json.

---

Orca integration — supervision, not just spawning

orchestrate treats Orca as a first-class substrate, not a terminal spawner. When the orca CLI is on your PATH the coordinator offers it at the task-split gate, and from then on the whole run flows through Orca orchestration:

• Provenance — one Run per orchestration; every task phase (plan / implement / rework / merge-prep) is a tracked Task + Dispatch, so "who is doing what, and did it settle" is queryable state, not a guess.
• Event-driven waits — the coordinator blocks on pushed worker_done / escalation / question mail (orca-wait.sh) instead of polling status files on a timer. A worker's blocking ask reaches the coordinator in seconds and is answered with orchestration reply; a dead Orca runtime is a distinct exit, never a silent timeout.
• Env-carrying worker start — orca-worker-start.sh composes the worktree, an agent terminal that carries the guardrails escalation contract (GROUNDWORK_ESCALATION_DIR / GROUNDWORK_TASK_ID) and the worker's own guardrails config (GROUNDWORK_GUARDRAILS_CONFIG), and the Dispatch binding; on re-entry it probes for a live agent first, so one worktree never ends up with two agents.
• Liveness is two questions — orca-worktree-alive.sh (is the terminal there?) and orca-worker-stalled.sh (is the pane actually moving?) — because a wedged worker passes the first check for hours.

Without Orca, the same run gets the same protections over raw tmux, file-based: a worker writes a blocking question with ask-coordinator.sh and the watch surfaces it (exit 6); a silent pane surfaces as a stall (exit 7) with a classify-then-act playbook (chooser / usage-limit / finished-but-silent); an on-screen chooser is answered with allowlisted key events (send-prompt.sh keys); and every launch pre-seeds the status record, so a worker that dies during planning is caught instead of waited out. The guardrails escalation contract is identical on both substrates.

Worker guardrails loosening is opt-in. By default a worker's destructive rules (rm_rf, git_discard, system_tmp_write) stay ask, same as your own session — only the .orchestration status/plan path is pre-allowed, so that protocol still works without a prompt. Set DEV_LOOP_WORKER_RELAX=1 (e.g. "env": {"DEV_LOOP_WORKER_RELAX": "1"} in ~/.claude/settings.json) to get today's looser default (those three rules set to off) back, trading friction for speed on routine in-worktree cleanup. Guardrails is a seatbelt against mistakes, not a sandbox: any session running as your user, including a worker, can edit its own guardrails config files, so opting in means trusting workers with that.

One setup note for auto-mode coordinators (tmux): the launcher starts each worker as claude --permission-mode bypassPermissions, which an auto-mode permission classifier flags as privilege escalation — it cannot see the guardrails deny-net that makes it safe. If your coordinator session runs in auto mode, the three worker-management scripts (launch-session.sh, send-prompt.sh, watch-status.sh) need pre-approval. The coordinator handles this at onboarding: it probes read-only (install-permission-rules.sh --check), and if the rules are missing it asks you once — on your explicit yes it runs the bundled installer (idempotent, backed-up, atomic; never silent), otherwise it shows you the snippet to paste yourself. safe-cleanup.sh is deliberately excluded so destructive verbs keep their normal review, and a blocked coordinator stops and re-asks rather than working around the classifier.

Watch a run live — the session-progress mod

orchestrate already records everything a run does in plain files: .orchestration/graph.json, one .orchestration/status/<task>.json per worker, and each worker's .dev-loop/gates/<task>.md ledger. The session-progress mod (in the groundwork marketplace) reads those files and draws the run into a pane of the coordinator's own Claude Code session, so you check on the workers without opening a terminal per worker or running collect-status.sh.

• Per worker: its phase as the run records it (pending → plan_ready → impl_done → done, plus rework and failed), gates n/m from its ledger, try N after a second rework, and how long ago it last reported; expand a worker for its session, last error and gate list. When the worker's own status copy in its worktree is newer, that copy wins (the same newer-updatedAt rule collect-status.sh uses).
• Overall: the run's percent and worker count; while the pane is closed and the run is active, the summary and its workers sit above the prompt instead.
• Where it shows: only in the coordinator's checkout; worker sessions inside .worktrees/ show nothing. It reads; it never writes to the run. Workers call status-update.sh on both Orca and raw tmux, so it works on either. On Orca a worker first appears once the coordinator's collect-status.sh has picked up its record.
• Kept compatible: groundwork's CI regenerates the mod's fixture with this repo's own graph-add.sh, status-update.sh and gate-check.sh at the pinned dev-loop release, so a change to the file format shows up there (it pins the format, not which phases a run writes).

/plugin marketplace add choiyounggi/groundwork
/plugin install session-progress@groundwork

A mod is a Claude Code plugin of in-process function hooks that can draw its own pane; it needs a build with mod support (verified on 2.1.296). The same pane also shows the current request's plan, the task history and a context gauge.

---

The knowledge-capture loop

The wiki is meant to grow from what you actually learn. Three moving parts:

1. Capture (global, automatic). A SessionStart hook injects a standing instruction: whenever, in any repo, you discover a verified best-practice or a real edge case worth persisting, emit a compact ★ Insight block (trigger / directive / why / evidence / domain / tags).

2. Harvest (automatic, offline). A Stop hook scrapes those blocks from the session transcript into a local queue (~/.dev-loop/queue/). It dedupes against both the session's queue file and the already-flushed store (.processed.jsonl), caps a session at 10 rows as a runaway backstop, and cleans up emptied queue files. It never edits the wiki and never opens a PR — harvesting is cheap and non-blocking.

3. Flush → verified PR (automatic, or on-demand). The queue is drained by the knowledge-flush pipeline. For each candidate it must, before any PR:

   • research & verify the best-practice against real sources (official docs, primary references) and assign a confidence (verified / field-tested / unverified — never a fabricated citation),
   • check existing layers for duplicates to merge into and pages to link (naming the page ids it actually read),
   • check open knowledge/* PRs so sibling flushes don't pile up duplicate PRs — the manual path can git diff an in-flight PR's branch, so it folds a genuine overlap into that branch, drops a pure duplicate, or ingests as new. The automatic headless path has no git at all (see below) and so cannot diff those PRs' content; it only lists them, and drops any candidate whose domain/trigger plausibly overlaps as a pending duplicate — it never folds into another branch,
   • decide the target layer/category (or justify a new category),
   • then run wiki-ingest and write an INGEST_REPORT.md.

   It opens one PR per flush and never auto-merges. Each contributor's PR is committed and opened under their own git/gh identity (never a hardcoded account, never an assistant); the repo owner reviews the open dev-loop:knowledge PRs and merges or rejects each one.

   Two ways it runs:

   • Automatic, opt-in (OFF by default) — set DEV_LOOP_AUTOFLUSH=1 and the hooks/auto-flush.sh Stop hook fires the pipeline in a detached, headless claude run when the queue crosses a threshold and the rate-limit window has elapsed, so PRs appear without you doing anything. That run keeps your normal permission checks — it passes an explicit --allowedTools/ --disallowedTools pair scoped to exactly what the flush pipeline calls, never --permission-mode bypassPermissions.

     The nested session gets no git tool at all, and no gh pr create. Scoping git by subcommand (Bash(git -C <repo>:*)) still let a prompt-injected session run arbitrary code through an allowed-looking git prefix — git -C <repo> -c alias.x='!sh -c evil' x, fetch --upload-pack=<cmd> / push --receive-pack=<cmd>, log --output=<any path>, rebase --exec, submodule foreach, bisect run all execute a program, and a subcommand denylist/allowlist never closes (the same lesson as the regex shell lexer). So the boundary moved: hooks/auto-flush.sh itself — never inside any Claude session's permission system — does the checkout, branch, commit, push, and gh pr create, each with fixed arguments. The nested session only edits files (research, dedup, wiki-ingest's edits, and a small autoflush-result.json naming the PR title and report path), and even its Edit/Write access is explicitly denied inside the checkout's own .git/ (so it can't plant a hook there), with an independent checksum comparison of .git/hooks/* + .git/config before/after the session as a second, trusted-side check that doesn't rely on the deny rule holding. Each allowed/denied entry and why it's there:

     Entry	Why
     Bash(export DEV_LOOP_FLUSH_RUN_ID=*)	Kept for parity with the manual skill path; this headless run doesn't need to call it (the hook holds the flush lock for the whole run).
     Bash(sh <plugin root>/scripts/flush-lock.sh:*)	Kept for parity, unused this run — not a bare sh:*, which would run any script or sh -c '<anything>'.
     Bash(node <plugin root>/hooks/queue-claim.js:*)	Claims/releases queue rows, pinned to its exact path — not a bare node:*, which would run node -e '<anything>'.
     Bash(gh api user:*)	Kept for parity — not gh api:*, which would allow any GitHub API call.
     Bash(gh pr list --repo choiyounggi/dev-loop:*)	Lists open knowledge/* PRs for the (read-only, drop-on-overlap) dedup check, scoped to this repo.
     Read	Reads the wiki, templates, and queue files; left unscoped since nothing here is sensitive to read.
     Edit(//<~/.dev-loop>/**)	Covers both the Edit and Write tools (Claude Code only checks Edit path rules), scoped to the checkout plus the queue dir it also retires rows in — not a bare Edit/Write, which would write anywhere.
     Skill	Runs the wiki-ingest sub-skill.
     WebSearch	Verifies each candidate against real sources before ingesting it.
     mcp__plugin_dev-loop_dev-loop-wiki__wiki_search	Semantic dedup against the existing wiki before creating a new page.
     disallowed: Edit(//<~/.dev-loop>/repo/.git/**)	Carves the checkout's own .git/ back out of the Edit allow rule above — a deny rule wins over a matching allow rule — so the session can't plant a .git/hooks/* script or rewrite .git/config.

     Claude Code's Bash permission matcher is a static, literal-text prefix match: it can't auto-approve a command containing an unresolved shell variable (so ${CLAUDE_PLUGIN_ROOT} must be the already-resolved literal path), an if/else conditional, or a || fallback. skills/knowledge-flush/SKILL.md keeps its portable, human-readable form for the manual, approved-by-you path. Left at the default (unset, or anything other than 1), the hook never spawns a session or opens a PR; instead it emits one rate-limited notice telling you how many insights are queued and to run the manual flush below. Guarded either way: once per DEV_LOOP_AUTOFLUSH_INTERVAL (default 3600s), only at DEV_LOOP_AUTOFLUSH_MIN (default 3) pending items, an owner-token single-flight lock shared with the manual flush below (DEV_LOOP_FLUSH_LOCK_TTL, default 900s, before a crashed holder's lock is reclaimable) plus a per-run queue claim (DEV_LOOP_CLAIM_TTL, default 3600s) so the two entry points never ingest the same candidate, and recursion-safe. Needs claude + gh on PATH and gh authenticated; if either is missing it silently no-ops and you fall back to manual.

   • Manual — invoke /dev-loop:knowledge-flush any time to drain the queue now.

This ordering is enforced by a hook

hooks/pre-flush-pr-gate.sh (PreToolUse) blocks gh pr create on a knowledge branch unless the INGEST_REPORT.md exists and has all four sections (## Verified best-practice, ## Existing-layer check, ## Open-PR check, ## Routing decision) filled with real content. The Existing-layer check must carry a Pages read: <id>, … line, and each id is resolved against the checkout's wiki/ — a report citing pages that don't exist fails closed. The gate is narrowly scoped to knowledge-flush PRs, so it never interferes with ordinary gh pr create in any repo.

Wiki search index (optional, fail-open)

The bundled wiki is also indexed locally (scripts/wiki-index.py → ~/.dev-loop/wiki-index/, refreshed in the background by hooks/wiki-index.sh) and served through the two-tool dev-loop-wiki MCP (.mcp.json → scripts/wiki-mcp-launch.sh → scripts/wiki-mcp.py: wiki_search, wiki_page). Curated routing stays the first path; the index is a fail-open second path in four places — wiki-plan's Phase B routing sweep runs one semantic candidate check per task and per [no-wiki] decision, adopting a hit only after its own trigger text matches; wiki-query retries a routing 0-hit once semantically; wiki-ingest shows the top-5 hits before merge-vs-create; and wiki-lint check 19 lists near-duplicate trigger pairs (neardup). Without uv or a built index every skill behaves as before; DEV_LOOP_WIKI_INDEX=0 turns the feature off.

---

Skills

Skill	Role
loop-implement	The single implementer — consumes the wiki-plan and executes its tasks in order (loading each task's named wiki pages) through the verification loop. Plan step = wiki-plan.
orchestrate	The multi-session orchestrator — split one goal into parallel worker sessions, each running loop-implement — over Orca when detected (Task/Dispatch tracking, event-driven worker_done/ask/escalation waits, native liveness), else tmux with a hardened watch (worker question channel, stall surfacing, allowlisted chooser keys). Scheduling is a dependency graph plus slot accounting, not wave barriers: ready-set.sh says what may start now, the slot count is proposed at Gate 1 and bounded by LO_MAX_SESSIONS, and a failed dependency surfaces as a reported deadlock rather than a silent wait. Per-role model selection: a cheap worker model, a strong planner/auditor. Workers escalate guardrails asks instead of blocking, may propose splitting an over-large task mid-run, and dead workers are detected. Both human gates (task split + substrate, pre-merge) are put to you as AskUserQuestion choosers, enforced by orchestrate-ask-gate.sh.
wiki-plan	The fixed plan methodology — three gated phases (Analyze → Design → Decompose): evidence-backed analysis, wiki-routed decisions independently reviewed by the plan-reviewer subagent, then ordered, page-navigated tasks. Gates are judged mechanically (plan-gate.sh + gate-check.sh); orchestrate refuses to dispatch a plan without gate evidence.
wiki-ingest	Add verified knowledge to the right semantic layer (used by knowledge-flush).
wiki-query	Answer a question from the wiki with citations.
wiki-lint	Health-check the wiki.
knowledge-flush	Research + verify + route queued insights → one reviewed wiki PR.
configure	Set up the capability-role tool profile (map your wiki, test command, etc.).
graph-setup	Onboard a workspace of git repos onto the graphify code graph (consented install, workspace roots, batch build, both hook sets).

Structure

dev-loop/
├── .claude-plugin/{plugin,marketplace}.json
├── AGENTS.md INDEX.md templates/     # wiki schema + routing entry + page/brief/session-prompt templates
├── wiki/                             # 10-domain semantic-layer knowledge base (260 pages: best practices, edge cases, process methodology)
├── skills/                           # the 9 skills above (user-invocable; appear in the / menu by skill name)
├── agents/test-quality-auditor.md    # bundled independent test auditor (loop step 6.5)
├── agents/task-reviewer.md           # bundled fresh-context per-task reviewer (orchestrate Phase 4)
├── agents/task-analyst.md            # bundled fresh-context per-task analyst, wiki-plan Phase A (orchestrate Phase 3 step 2a)
├── agents/task-planner.md            # bundled fresh-context per-task planner, wiki-plan Phase B+C (orchestrate Phase 3 step 2a)
├── agents/*-r1.md                    # generated R1/R0 copies, one effort step lower, never below high (scripts/gen-agent-tier-variants.sh)
├── hooks/
│   ├── hooks.json
│   ├── preflight.sh                  # SessionStart: git/tmux/jq advisory
│   ├── insight-instruction.sh        # SessionStart: inject ★ Insight capture instruction (global)
│   ├── config-nudge.sh               # SessionStart: nudge to /dev-loop:configure if unconfigured (weekly)
│   ├── graph-nudge.sh                # SessionStart: nudge to /dev-loop:graph-setup if the workspace graph needs onboarding (weekly)
│   ├── wiki-index.sh                 # SessionStart: refresh the local wiki vector index in the background (DEV_LOOP_WIKI_INDEX=0 disables)
│   ├── loop-gate.sh                  # Stop: verification-loop integrity gate
│   ├── harvest-insights.sh + harvest.js  # Stop: harvest insights → queue
│   ├── auto-flush.sh                 # Stop: opt-in (DEV_LOOP_AUTOFLUSH=1) knowledge-flush → PR; default off = notice only
│   ├── pre-flush-pr-gate.sh          # PreToolUse: enforce the flush pre-PR pipeline
│   └── orchestrate-ask-gate.sh       # PreToolUse: no worker launch until Gate 1 was asked with AskUserQuestion
├── scripts/resolve-tools.sh          # capability-role profile resolver (no `plan` role)
├── scripts/wiki-contradiction.sh     # evidence-gated log.md contradiction entry for a wiki page falsified at implement time (loop-implement rule 4)
├── scripts/wiki-usage.sh + wiki-lint-usage.js  # WIKI: line telemetry -> <repo>/.dev-loop/wiki-usage.jsonl; wiki-lint check 18 zero-citation review queue (report-only)
├── scripts/wiki-index.py + wiki-mcp.py + wiki-mcp-launch.sh  # local vector index over wiki/ + the two-tool dev-loop-wiki MCP (fail-open)
├── .mcp.json                         # registers dev-loop-wiki (stdio) through the launcher
├── tests/                            # bats suites — hooks (harvest, flush gate, loop gate) + orchestration scripts; CI runs them on ubuntu + macos
├── references/tool-profile.md
└── docs/                             # inherited design notes (loop-orchestrator lineage)

---

Attribution

Knowledge PRs (manual or auto-opened) are committed under each contributor's own git/gh identity — never a hardcoded account and never an assistant, with no Co-Authored-By trailer. Every contributor opens a PR from their own account; the repo owner reviews and merges/rejects.

Lineage & license

Forked from loop-orchestrator and dev-llm-wiki (both by choiyounggi). See docs/ for the inherited loop design (note: those docs predate the fixed-plan-step change described above). MIT — see LICENSE.