dev-skills

A plugin for Claude Code and Codex: skills and two agents for building a change — discussion, a plan file, implementation by subagents, a review and an e2e check, and your approval before merge. The session you start coordinates the work and does not edit code.

The pipeline

Every change goes through the same eight stages. For a small task each stage is shorter; none is skipped, and every plan ends in a human gate.

1. Entry. A grill when it is unclear what is being built, a discussion when it is lighter. Workers bring facts from the code; you make the decisions. A bug adds its reproduction and its cause.
2. Prototype. Offered after the entry; you pick the shape or decline: an HTML file, inside the app with real data, or code. A worker draws it.
3. Plan. Always a file, one screen: Result, Approach, Out of scope, Phases, Checks, Done, and the prototype's link. Each phase names its territory and what it waits for; together they form the graph. Status runs draft → approved → building → at the human gate → at code review → passed → merged, via a merge-request link when finish opens one; your "go" takes it from draft to approved.
4. Build. One branch and one working tree per plan: this one, or a worktree when another plan is building here. Every phase whose dependencies are met starts at once, as an implementer that writes only inside its territory and runs the project's checks on it.
5. The E2E gate. At the level the plan names, small, normal or wide: the full checks, then at once a fresh review against the project's rules and e2e over what you would not see by trying the app. Defects and failures make one list for one new implementer, then a targeted re-check; two fixes at most.
6. The human gate. The product, one page written into the plan: the product questions the orchestrator answered without you, and the e2e (the use cases, each with its last result and the commit it ran on; the ones marked "you check" are yours). You try the running app. What you say about the product goes into a notes file beside the plan, and nothing starts on it until you say so; then a round builds every open note like a phase: an implementer, its checks, a review, and e2e where the diff reaches past what the notes name.
7. Land and the code review. You type land. The working commits become the ones a reviewer reads, one or a few by meaning, on the same tree; a backup branch keeps the old ones. Then the code review page: the commits with a walkthrough, and the rulings the implementers made alone. Notes about the code go to a round, and it lands again.
8. Finish. You type it. It asks: a merge request, or local with --no-ff or --ff-only.

The drawing: docs/pipeline.html.

What you type

You type	It does
grill, or just talk	reach a shared understanding; then a prototype is offered, then the plan
bug	a worker reproduces it and brings the cause; the red test becomes phase 1
prototype	a throwaway answer to a design question, drawn by a worker
epic	several plans in order, only when you say so
plan	the one-screen plan and its graph
build <plan>	the branch, the implementers, the E2E gate, the human gate
land	the commits a reviewer reads, then the code review
finish	merge it: a merge request, or local with --no-ff or --ff-only

A small task is built by the session that discussed it; anything bigger by a new session started from the plan file. land and finish are the only skills the model cannot start.

Who does what

• You decide, approve, and type land and finish. A prototype, an epic, where to build, how to finish and a retro are your call.
• The orchestrator is the model you started with, from the first pipeline skill you enter. It talks, writes the plan, runs the graph, relays messages and sorts findings. During a build it answers product questions itself, except an irreversible one, and shows each answer at the human gate. It never edits code.
• Implementers are the implementer agent: Sonnet, a clean context each, handed the whole plan, its phase, and what earlier phases reported. When the plan and the code disagree, it rules, carries on, and records the ruling with its cost if wrong.
• Workers are Sonnet subagents for side jobs: facts from the code, a prototype, the full checks, e2e.
• The reviewer is the reviewer agent: Opus for the first review of a plan's branch and for a range you name, Sonnet for the re-check and every later round.

In Codex the same roles are Codex subagents on the session's model, at reasoning effort high where Claude Code uses Sonnet and xhigh for the first review. The skills name Claude Code's tools; references/CODEX.md says what each one is in Codex.

The plugin ships no hooks and no scripts. The pipeline lives in the skills' text; the level-1 checks are the project's own tests, linters and typechecks.

The project's side

The plugin reads the project's AGENTS.md or CLAUDE.md and its style skills as the bar for review, and one block in that file for the commands a plan's Checks names:

## Environment

**Tests.** `npm test`
**Lint.** `npm run lint`
**Dev server.** `npm run dev`, serves on `http://localhost:5173`
**Runtime.** a browser
**Access.** a test account without a one-time code, its password in `.env.local`

The full format is in environment-contract.md. AGENTS.md serves both hosts: Codex reads it, and Claude Code reads it where the project has no CLAUDE.md, or one that imports it with @AGENTS.md.

Install

In Claude Code:

/plugin marketplace add bmox0/dev-skills
/plugin install dev-skills@dev-skills

Then restart the session. Installing also brings the agents implementer and reviewer.

In Codex:

codex plugin marketplace add bmox0/dev-skills
codex plugin add dev-skills@dev-skills

Then start a new session, and name a skill with $: $dev-skills:grill, $dev-skills:build <plan>, $dev-skills:land, $dev-skills:finish. Codex's own /plan is not this plugin's. To update, codex plugin marketplace upgrade dev-skills, then codex plugin add dev-skills@dev-skills again. In the default workspace-write sandbox .git is read-only, so the first git add and git commit of a build ask for approval; approve each kind once.

The repository is a marketplace holding exactly one plugin, itself: .claude-plugin/ for Claude Code, .agents/plugins/marketplace.json and .codex-plugin/plugin.json for Codex. Both hosts install the same skills.

Every skill

Skill	For
browser-test	the web e2e tool: the use cases as one Playwright scenario in a visible tab you can watch, single commands to dig in; a web app or an Electron build over CDP
bug	reproduce a bug and pin down its cause before the plan
build	run a plan: the graph, the E2E gate, the human gate
commit-work	stage by path, split into logical commits, write the message
domain-modeling	the glossary in CONTEXT.md, and an ADR for a decision that needs one
epic	shared decisions and the ordered list of plans
finish	merge a passed plan, typed by the user
grill	talk an idea into a shared understanding
handoff	pack this session for a fresh context
land	rewrite a plan's branch into reviewable commits, typed by the user
plan	write the one-screen plan
prototype	answer a design question with throwaway code
retro	propose environment changes after a plan, each with what it removes
review	the code half of the E2E gate, or a review of any range
tdd	red before green, read by the implementer
verify	the e2e half of the E2E gate: drive the Done use cases
writing-skills	design or audit a skill

references/VOCABULARY.md defines the words they share.

Principles

• A stage stays only if it saves more time than it takes.
• The skills do not restrict the models or make them work one step after another without a reason.
• Where the work could go two ways, the user chooses, not the agent. During a build the orchestrator chooses and the human gate shows each choice; an irreversible one waits for the user.

Checking this repository

scripts/check asks whether the tree is sound: every link resolves, every dev-skills: name exists, no retired name comes back, every markdown file is within its budget in scripts/word-budgets.txt, and the manifests and every frontmatter parse (claude plugin validate). It also installs the plugin into a throwaway Codex home and reads back the skills Codex shows its model: all of them but land and finish (scripts/check-codex.py).

scripts/test runs the behavioural tests on the maintainer scripts and the plugin's shape — TC-13 pins the shape itself (no hooks, no skill scripts, Sonnet implementers, an Opus reviewer, one version in every manifest), TC-14 pins the plan's statuses across plan, build, land, finish, epic and the implementer; one file is scripts/test <path>.

scripts/usage measures sessions from Claude Code's transcripts: wall and active hours, human messages, tokens, subagents, per project or per session (--json, --project, --since).

Working on this repository with the installed plugin also active runs the pipeline twice; turn it off first: claude --settings '{"enabledPlugins":{"dev-skills@dev-skills":false}}', or in Codex codex -c 'plugins.dev-skills@dev-skills.enabled=false'.

Licence

MIT — see LICENSE.