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.

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.