dev-workflow-kit

A Claude Code marketplace with one plugin, dev-workflow, that installs a spec-driven workflow for building software with agents. It adds three mechanisms: two independent cross-model review gates, a self-hardening findings ledger, and repo-enforced quality.

What it does

• Two independent review gates. A different model than the author reviews the design before it becomes code (Gate A) and the diff before it lands (Gate B).
• A self-hardening ledger. Every finding is fingerprinted, so recurrence of a class is detectable — and a recurrence escalates the response one rung harder: prose note → lint rule → type constraint → test.
• Repo-enforced quality. One quality command runs in CI on every change, so nothing red can merge.

Why each of these, and how to adapt them: docs/coding-workflow.md.

dev-workflow:intake	skill — a raw idea or voice transcript (German or English) becomes a reviewable story. Captures WHAT and WHY; refuses to invent the parts that aren't there.
dev-workflow:harden-finding	skill — one review finding becomes a lint rule, type constraint, test, or documented convention, at the right rung, recorded in the ledger.
/dev-workflow:process-pr-review	command — validates PR bot comments against the code and your invariants, replies to each, fixes regressions, tracks pre-existing issues.
dev-workflow:finding-triage	agent — read-only, fresh context, judges whether one PR-bot claim is actually true of the code. Used by the PR processor; never counts as a review gate.
/dev-workflow:workflow-init	command — scaffolds the per-project files, then interviews you to write AGENTS.md.
codex-gate hook	non-blocking reminders that count Gate A and Gate B passes, and verify a Gate-B review against a fingerprint of the effective index plus the included worktree content, as of the hook's invocation — a deliberate superset of any one commit's payload, so the gate errs toward firing. Always exits 0.

Setup

1. Install superpowers, then this plugin:

claude plugin marketplace add obra/superpowers-marketplace
claude plugin install superpowers@superpowers-marketplace

claude plugin marketplace add dsnger/dev-workflow-kit
claude plugin install dev-workflow@dev-workflow-kit

To update later:

claude plugin marketplace update dev-workflow-kit
claude plugin update dev-workflow@dev-workflow-kit   # qualified form is a workaround: the bare
                                                     # name is documented but errors "Plugin
                                                     # 'dev-workflow' not found" (CLI 2.1.x)

Updates arrive only when the plugin version is bumped, and a running session keeps the old version until you restart it or run /reload-plugins.

2. Prerequisites:

• superpowers — not vendored. The workflow's middle is its skills; without it, intake hands off to nothing and Gate A never fires.

• Codex — the reviewer behind both gates. Needs the Codex CLI, authenticated with an OpenAI account — a real external dependency, not just the .mcp.json entry /workflow-init writes for you. It also needs a Codex MCP server that exposes exec and review — the gates key on those two tool names, and the pass counters additionally skip routed calls whose result the hook reads as failed, backgrounded, or yielding no usable text; a result it can read but not interpret still counts, and normally says so once. Use the mcp-codex-dev server /workflow-init pins, which has both. The official codex mcp-server is a different server exposing a single codex tool, which can't be attributed to Gate A (reviews text) or Gate B (reviews a diff): with it connected, no pass ever counts and Gate B reports "not run" forever (the hook says so, once).

  Both gates have Codex write its findings to a file under .context/codex-reviews/ and reply with a one-line summary, because a long finding list returned inline can come back cut off — and a cut between findings looks exactly like a short list. Claude Code limits MCP tool output to 25,000 tokens by default; MAX_MCP_OUTPUT_TOKENS raises that, which is worth trying as a secondary mitigation but is not the fix. It moves the ceiling rather than removing it, and it applies only to tools that don't declare their own text limit via anthropic/maxResultSizeChars — whether mcp-codex-dev declares one is not established here. The file protocol is what actually keeps findings out of the response.

• gh — optional; only /dev-workflow:process-pr-review uses it.

2b. Set CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS — strongly recommended, and the primary defence against a gate call being auto-backgrounded. Claude Code moves a long MCP call to the background at a threshold (120 s by default) and fires PostToolUse at that moment, carrying the harness's own notice instead of any Codex result; the eventual real completion fires no second PostToolUse, so the hook never sees the review's outcome.

Requires Claude Code 2.1.212 or newer. Set it in the environment Claude Code is launched from — it is read at process start, so exporting it inside a tool shell leaves the running session unchanged and you must restart Claude Code. Use 0 to disable auto-backgrounding, or a positive value that exceeds your longest expected gate call; a positive value shorter than the call still backgrounds it.

export CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS=0   # or e.g. 900000, exceeding your longest gate call

Without it, both outcomes are possible, and only one is safe. While the harness notice keeps the wording the hook recognizes, the backgrounded pass is discarded — correct, but re-running it is not simply a retry: the original call may still be running and can still write into the findings slot afterwards, leaving a correctly terminated file from the wrong run that no downstream check can detect. Stop that task by the id in the tool result — or await it if the result carries none — and delete the findings slot first. The hook's own backgrounding message carries that procedure; follow it there rather than from memory. If that harness prose ever changes, the hook can no longer recognize the notice and the call is counted instead, with a disclosure that says the count was made without inspection. That second outcome is why this setting is the defence rather than the hook: the hook fails safe against today's wording, not against every future one.

(CLAUDE_CODE_AUTO_BACKGROUND_TIMEOUT_MS appears in the 2.1.220 string table but was never exercised here, so it is deliberately not documented — naming the wrong one of two similar variables is this project's own docs-drift class.)

3. Run /dev-workflow:workflow-init in each project. It verifies the rest and tells you what's missing — git repo, superpowers, Codex (not configured / not loaded / ok), gh, AGENTS.md, stack — before writing a single file. Then follow docs/getting-started.md for your first story.

Daily use

idea → intake → brainstorm → spec → Gate A → plan → Gate A → implement → quality battery → Gate B → PR → process-pr-review → merge, running every finding worth keeping through harden-finding.

New to the workflow? docs/getting-started.md walks one feature through every step — what you do, what happens, what you see.

The hook only speaks up in initialized projects — the ones where /workflow-init has run (it writes .context/codex-gate.on, and its CLAUDE.md §5 counts too). The plugin is installed once per machine; every other repo you open hears nothing from it.

Per-workspace knobs, all files under .context/:

| codex-gate.floor | a positive integer; moves the 3-passes-per-gate floor. | | codex-gate.off | silences the reminders; classification and state tracking keep running, so re-enabling lands on counters carrying the same semantics as gate-on — which is not the same as evidence that a review happened. | | codex-gate.tools | execTool=<name> and/or reviewTool=<name> — counts a Codex server whose tools aren't named exec/review, and only worth it if that server really does separate text-review from diff-review; aiming both gates at one general-purpose tool moves the counters while neither gate means what it says. Each mapped name must itself lie in mcp__codex__*: the hook's hooks.json matcher is ^(Bash\|Skill\|mcp__codex__.*)$, so an out-of-namespace name is either never delivered (the mapping looks applied and does nothing) or, for the reserved names Bash/Skill, hijacks a lifecycle event; the hook refuses both — register the server as codex to place its tools there. Unparseable, out-of-namespace and reserved (Bash/Skill) lines are ignored, and the gate keeps its default exec/review name. A typo inside the namespace — mcp__codex__exce — is still honoured: the hook does not check that a mapped tool exists, so the gate now counts that name and nothing else. Whether it ever counts depends on whether a tool by that name is actually invoked; for a typo, normally never. |

Without Codex, /workflow-init degrades honestly instead of scaffolding gates that can't run: it silences the hook and marks CLAUDE.md §5 INACTIVE with the re-enable path. There is deliberately no same-model fallback reviewer — explicitly gateless beats implicitly self-reviewed (why).

What to expect

Five things stay yours on purpose — a plausible default nobody verified is worse than an honest gap (reasoning):

• Quality-battery tools — the plugin names the roles (typecheck, lint, dead code, duplication, tests), never the tools. You wire them into one command.
• Baselines — generated from your repo, in their own commit.
• Custom lint rules — two ship as examples only (examples/eslint-rules/); they encode one stack's invariants and won't transfer.
• Branch protection — a repo setting, not a file; worth doing once the battery runs.
• AGENTS.md — your invariants. Both gates check against it, so a generic one makes "check against our invariants" read as satisfied when nothing was.

Contributing

CI (.github/workflows/ci.yml) runs four checks on every PR and push to main: shellcheck --shell=sh over all three executables and their test files, the hook's test suite, scripts/check-invariants.sh (invariants 5 and 6, plus two prompt-conformance checks) plus both checkers' regression suites, and claude plugin validate . --strict.

A fifth check runs on pull requests only: scripts/check-version-bump.sh (invariant 12), which needs a base branch to diff against. Its suite runs unconditionally with the others; the checker itself does not. That is sufficient here because main accepts changes only through a PR: a branch ruleset (protect-main., active since 2026-07-19) requires a pull request and a green quality check, and the version-bump step runs inside that quality job — so there is no push path into main that skips it. The single command that runs the whole battery locally is in AGENTS.md under "Commands".

Main is protected: a PR with a green quality check is the only way in, admins included — the ruleset lists no bypass actors.

Everything else here is a prompt, and prompts have no typechecker — they are reviewed against docs/prompt-standards.md, this repo's own standard and the same checklist it scaffolds into every project. A prompt-quality defect here is a defect in the shipped product.

Repo layout and the two non-obvious design decisions: docs/architecture.md.