dev-loop

A plan + state + /step loop-engineering harness for Claude Code. Drive any project through a verified, resumable, one-step-at-a-time plan. State lives in files — so you can /clear between steps and pick up exactly where you left off.

This repository is a Claude Code marketplace (dev-loop-marketplace) hosting the dev-loop plugin (this README). The general-purpose agent/command/skill toolkit formerly bundled here as cc-toolkit now lives in its own repository/marketplace: YuheiNakasaka/cc-toolkit.

What it gives you

Two files become the source of truth — not the chat history:

• .claude/dev-plans/<date>-<slug>.md — the spec (what to do): an ordered list of steps, each with a goal, success criteria, verification method, and dependencies. /plan-init writes a new file every run and never overwrites an earlier plan, so past plans (and the decisions behind them) are preserved as files + in git history; the active plan is whatever dev-state.json's planDoc points to.
• .claude/dev-state.json — the ledger (what happened + config): per-step status, gate results, learnings, and all settings (working branch, base branch, worktree path, quality-gate commands, project name, plan path). Git-ignored and local (per-developer) — it changes on every step and would otherwise cause merge conflicts on multi-person projects; teammates track progress via the committed plan files + the Step N: <title> commit history.

Because every setting lives in dev-state.json, the commands are completely project-agnostic. The same /step works in any repository.

Commands

Command	What it does
/plan-init [goal · spec · path to a review doc]	Creates an isolated git worktree at .worktrees/<slug>/ (branch dev-loop/<slug>) by default — say "current tree" to skip — then scaffolds a new .claude/dev-plans/<date>-<slug>.md (never overwriting an earlier plan) + a local .claude/dev-state.json inside the worktree. Auto-detects quality gates (typecheck / test / lint / build), confirms them with you, records a baseline, sets up the review gate, and — when the goal is ambiguous — offers an optional one-question-at-a-time grilling to sharpen the success criteria.
/step [id]	Runs one step: check dependencies (incl. a worktree guard that refuses to run in the wrong tree) → implement → run the gates → review gate → update state → one commit per step. With no argument it runs the next pending step (and resumes an in-progress one).
/step-review [id]	Read-only: runs only the review gate against the current working tree and reports the verdict. Never edits, commits, or advances currentStep. Useful after manual fixes or as a pre-commit dry run.
/plan-status	Read-only progress view: step table (with review verdicts), completion %, gate-regression check, blocked steps' human tasks, accumulated learnings. Suggests /plan-finish once every step is done (or deferred).
/plan-finish	Finishes the plan: re-runs all gates fresh → syncs with the base branch (origin/<base>) → asks merge / push + PR / keep / discard → provenance-gated worktree cleanup (removes a worktree only if dev-loop created it under .worktrees/).

If a project already defines a command with the same name locally (e.g. .claude/commands/step.md), the local one wins. In that case invoke the plugin version explicitly as /dev-loop:step.

Worktree isolation (parallel sessions)

Running several LLM sessions against the same checkout causes edit conflicts, linter noise, and clean-tree collisions. /plan-init therefore creates a git worktree per plan by default:

• Layout — .worktrees/<slug>/ inside the repo, with branch dev-loop/<slug> checked out. The plan file and dev-state.json are created inside the worktree.
• State isolation is structural — dev-state.json is an untracked, per-working-tree file, so every worktree automatically gets its own ledger. No extra schema machinery needed.
• Mutual exclusion is structural too — git refuses to check out the same branch in two worktrees, so another session can never grab your plan (ownership is checked with git worktree list --porcelain before creating, because git worktree add -b's failure message doesn't distinguish a checked-out branch from a stale one).
• Safety gates — before anything is created, .worktrees/ is confirmed ignored — registered in .git/info/exclude (shared by all worktrees, no commit needed) unless a committed .gitignore entry already covers it (as in this repo); submodules and already-linked worktrees are detected and never nested.
• Session handoff — after /plan-init, open a new Claude Code session in .worktrees/<slug> (or move there with your harness's worktree tool) and run /step there. /step's worktree guard stops accidental runs from the main tree.
• Teardown — /plan-finish closes the loop (see the commands table) and removes the worktree only if dev-loop created it (provenance gate); user-made worktrees are never touched.

Vertical-slice (tracer-bullet) step decomposition — each step cuts a thin, complete path through the layers — further reduces same-file contention between steps and between parallel plans.

Review gate

At the end of every /step (after the quality gates pass, before commit), dev-loop runs a self-contained, iterative code review — no external plugin required:

• Fail-closed preconditions — before any reviewer is launched, new files are surfaced with git add -N (untracked files never appear in git diff), the base commit must resolve, and the diff must be non-empty — so an empty or broken diff can never be mistaken for a clean review.
• Parallel perspective review — one dev-reviewer sub-agent per perspective (correctness, architecture, security, testing, performance, … — a built-in catalog comparable in breadth to a full PR review) reviews the step's diff in parallel and returns labeled findings ([must]/[ask]/[suggestion]/[nits]), each self-adjudicated with a scope (in-step / out-of-scope / dependency), a requiresHuman flag, an autoFixable flag, and an evidence quote.
• Merge & adjudicate — the /step main agent itself dedupes the findings, spot-checks blocking ones against the real code to reject false positives, and decides the verdict — zero extra agent spawns.
• Iterate — fixable [must] findings are auto-fixed, the gates re-run, and the diff is re-reviewed for several rounds until it converges. An oscillation guard and a maxRounds cap prevent non-terminating loops.
• Decide the next action — on a clean result the step is committed (message tail e.g. [review: clean, 1r]) and currentStep advances; findings that need a human (infra/config/credentials/judgment calls) leave the step blocked with a human task list instead of being auto-edited; valid out-of-scope findings become new steps (verdict followups).

Everything is configured in dev-state.json's review block (enabled, maxRounds, blockOn, autoFix, perspectives). Set enabled: false (or omit the block) to keep the classic behavior.

Install

From GitHub:

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

From a local clone (for development):

/plugin marketplace add /path/to/dev-loop
/plugin install dev-loop@dev-loop-marketplace

To enable the plugin across all your projects automatically, add it to ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "dev-loop-marketplace": { "source": { "source": "github", "repo": "YuheiNakasaka/dev-loop" } }
  },
  "enabledPlugins": { "dev-loop@dev-loop-marketplace": true }
}

cc-toolkit has moved

The general-purpose agent/command/skill toolkit unrelated to the plan/step harness above — formerly plugins/cc-toolkit here — now lives in its own repository: YuheiNakasaka/cc-toolkit.

/plugin marketplace add YuheiNakasaka/cc-toolkit
/plugin install cc-toolkit@cc-toolkit

Quick start

/plan-init "Refactor the auth flow: fix the token-refresh bug and add tests"
#   → detects gates → confirms → creates .worktrees/<slug>/ (branch dev-loop/<slug>)
#   → writes the plan + a local (git-ignored) dev-state.json inside the worktree

# open a new Claude Code session in .worktrees/<slug>, then:
/step          # run step 1, then commit
/clear         # safe to clear — the state is on disk
/step          # run step 2 (auto-resumes from state)
...
/plan-status   # check progress any time
/plan-finish   # all steps done: fresh gates → base sync → merge / PR / keep / discard → cleanup

Why externalize state? (loop engineering)

On long-horizon tasks the context window fills up; summarization or /clear loses the thread. By keeping the plan (spec) and state (ledger) in files, each /step reconstructs what to do next and what already happened from disk. The result:

• Resumable — survives /clear, compaction, and fresh sessions.
• Verified — every step must pass the project's quality gates, so regressions surface immediately.
• Traceable — one commit per step (the plan file + code; the local state ledger is git-ignored) makes git bisect trivial, and learnings accumulate project-specific knowledge.

This follows the same lineage as GitHub Spec Kit (spec → plan → tasks) and Anthropic's writing on effective harnesses for long-running agents — external memory plus a verification loop.

State schema & design principles

The full execution protocol, the dev-state.json JSON schema, the plan-file (dev-plan.md) structure, the implement-vs-gate decision framework, and the review gate protocol all live in the bundled skill — the single source of truth:

• plugins/dev-loop/skills/dev-loop/SKILL.md
• Templates: plugins/dev-loop/skills/dev-loop/assets/

Repository layout

dev-loop/
├── .claude-plugin/marketplace.json     # marketplace manifest
├── README.md
├── LICENSE
└── plugins/dev-loop/                   # plugin: plan + state + /step harness
    ├── .claude-plugin/plugin.json
    ├── README.md
    ├── commands/                       # /plan-init, /step, /step-review, /plan-status, /plan-finish
    ├── agents/                         # dev-reviewer (built-in review engine)
    └── skills/dev-loop/                # SKILL.md (protocol + schema) + assets/ (templates + review-perspectives)

The command prose is written in Japanese — that is the workflow the author uses day to day. The commands work regardless of your Claude Code UI language; translation PRs are welcome.

Contributing

Issues and pull requests are welcome. Good first contributions: English translations of the command prose, more gate-detection recipes (Cargo, Go, Python, Gradle…), and example plans.

License

MIT © Yuhei Nakasaka