Development Workflow

A disciplined, test-first development workflow for AI coding agents. Works with Claude Code and Codex.

You describe the problem. The agent explores the code, asks you a few sharp questions, and writes a plan. Once you approve the plan, it builds the change one small unit at a time - test first, reviewed after every commit - and stops to ask you when something will not converge.

It is a set of plain Markdown skills. There is no runtime, no server, and no lock-in.

• Why use it
• How it works
• Install
• Use it
• What is inside
• Status
• Acknowledgements

Why use it

Coding agents are fast, but they tend to guess the requirement, skip the test, review their own work, and say "done" without proof. This workflow puts hard stops in those places:

• Problem first. Nobody reads code or writes a plan before you describe the problem.
• You approve the plan. No production code before you approve PLAN.md.
• Never on main. Work happens on a branch.
• Test first. Every behaviour change starts with a test.
• Fresh eyes. A separate reviewer checks each commit: does it solve the problem, and does it follow your project's style?
• Evidence, not claims. No "done" without test and lint output from the current code.
• Bounded loops. Two fix rounds at most, then it stops and asks you. It does not grind.
• Resumable. State lives in files, so an interrupted session picks up where it stopped.

How it works

flowchart TD
    req([Your request]) --> route{Route the work}

    route -- "new behaviour" --> problem[/"You describe the problem"/]
    route -- "bug" --> problemBug[/"You describe the problem"/]
    route -- "interrupted" --> resume["Resume from PROGRESS.md"]

    problem --> brainstorm["<b>brainstorming</b><br/>explorers read the code<br/>then up to 3 rounds of questions"]
    problemBug --> debug["<b>systematic-debugging</b><br/>reproduce, prove the root cause"]
    brainstorm --> plan["<b>writing-plans</b><br/>one PLAN.md, split into units"]
    debug --> plan
    plan --> approve{"You approve<br/>the plan?"}
    approve -- "change it" --> plan
    approve -- "yes" --> branch["Create a branch<br/>and PROGRESS.md"]

    subgraph loop ["Per-unit loop - one unit at a time"]
        impl["<b>implementer</b><br/>test first, then specs and lint once"]
        commit["Coordinator commits"]
        review{"<b>reviewer</b><br/>solves the problem?<br/>follows the style?"}
        impl --> commit --> review
        review -- "blocking finding" --> impl
    end

    branch --> impl
    resume -.-> loop
    review -- "approved, more units" --> impl
    review -- "2 fix rounds used" --> ask[/"You decide how to proceed"/]
    review -- "approved, last unit" --> finish["<b>finishing-development</b><br/>verify once, then 2 reviewers<br/>in parallel on the whole change"]
    finish --> integrate[/"You choose: merge, open a PR,<br/>keep the branch, or discard"/]

    classDef human fill:#fff4d6,stroke:#c99a2e,color:#000
    class problem,problemBug,approve,ask,integrate human

Loading

Yellow steps wait for you. Everything else runs on its own.

Three roles do the work. The main session is the coordinator: it talks to you, keeps the files, commits, and dispatches fresh workers.

Role	What it does
explorer	Answers one question about the code or a dependency. Read-only. Several run at once.
implementer	Builds one unit test-first, runs specs and lint once, then stops. Does not commit.
reviewer	Checks one commit for the problem and for style. Cannot edit code.

The workflow keeps its state in .agent-work/<date>-<feature>/ inside your project: the approved PLAN.md, a live PROGRESS.md, and the review notes. Keep that folder out of Git. The workflow prefers a local exclusion in .git/info/exclude over editing your .gitignore.

For the full picture - phases, files, loops, and gates - read the workflow guide.

Install

You need Git and a Unix shell (macOS, Linux, or WSL). The install scripts symlink files, so git pull updates your install.

Clone the repository once. Pick any folder; this guide uses ~/development-workflow:

git clone https://github.com/ali-sheiba/development-workflow.git ~/development-workflow

Claude Code

1. Install the skills and the three subagents for every project:

   ~/development-workflow/scripts/install-claude-code.sh

2. Start a new Claude Code session. Check that /agents lists explorer, implementer, and reviewer.

3. Optional, per project: add the hooks. One reminds the agent to use the workflow on every prompt. The other blocks edits while you are on main, master, or develop. They need jq and git.

   cd /path/to/your/project
   ~/development-workflow/adapters/claude-code/install-hooks.sh

   The script prints a settings.json snippet. Merge it into the project's .claude/settings.json.

Hooks are per project on purpose. A global hook would fire in every repository on your machine. Details: Claude Code adapter.

Codex

1. Install the skills and the three custom agents for every project:

   ~/development-workflow/scripts/install-codex.sh

   Skills go to ~/.agents/skills/. Agents go to ~/.codex/agents/.

2. Start a new Codex session. Ask it to list its custom agents. It should name explorer, implementer, and reviewer.

3. Optional, per project: add this to the project's AGENTS.md, so Codex uses the workflow for every change:

   ## Development workflow
   
   Before you change this repository - a feature, a fix, a refactor, or a single
   file edit - use the `development-workflow` skill and follow it. Questions,
   explanations, and reads need no skill.

Codex does not enforce per-role tool limits, and there is no branch-guard hook. Details: Codex adapter.

Other agents

The skills are plain Markdown with a standard SKILL.md front matter. Point any agent that supports skills at skills/. If the agent cannot dispatch subagents, the main session plays each role in turn. The gates stay the same.

Update and uninstall

cd ~/development-workflow && git pull
./scripts/install-claude-code.sh   # or ./scripts/install-codex.sh

Re-running the install picks up new skills and removes links to deleted ones.

To remove everything the install scripts linked:

~/development-workflow/scripts/uninstall.sh

Use it

Start the workflow and describe what you want:

Agent	Start with
Claude Code	/development-workflow add rate limiting to the login endpoint
Codex	$development-workflow add rate limiting to the login endpoint

With the routing hook (Claude Code) or the AGENTS.md line (Codex), you can just ask for the change. The agent routes it through the workflow itself.

What to expect:

1. The agent restates the problem and asks you to confirm.
2. Explorers read the code. You get 3-5 numbered questions, each with a recommended answer. You can reply "all yes, except 3".
3. You get a PLAN.md. Approve it, or ask for changes.
4. The agent builds each unit, commits it, and has it reviewed. You are not interrupted unless something is blocked.
5. The whole change is verified and reviewed again. You choose how to integrate.

To resume after an interruption, start the workflow again. It finds the PROGRESS.md and continues from the recorded next step.

What is inside

Skill	Purpose
development-workflow	The entry point. Routes the work, runs the per-unit loop, holds the evidence gate, resumes.
brainstorming	Problem first, then explore, then short rounds of questions.
exploring	Answer one question about the code as a short findings brief.
writing-plans	Write the one PLAN.md you approve.
test-driven-development	Test first for every behaviour change.
systematic-debugging	Reproduce, prove the root cause, fix through a failing test.
requesting-review	Review a commit for the problem and for style.
finishing-development	Verify the whole change, review it, offer integration choices.
writing-skills	Create and test new skills for this collection.

The repository has three layers, kept apart on purpose:

.
|-- skills/     WHAT to do  - canonical, agent-agnostic. Wins any disagreement.
|-- agents/     WHO does it - three roles in plain capability terms.
|-- adapters/   HOW a given agent runs it - tool limits, agent files, hooks.
|-- scripts/    install, update, and uninstall
`-- docs/       the plain-language workflow guide

An adapter only wires. It points at the canonical files and never restates a procedure, because copied procedure drifts. No file pins a model: every worker uses your session's model.

Status

Alpha. The workflow is in daily use, but its structure and skill behaviour can still change in breaking ways. Pin a commit or a tag if you depend on it.

Tested on Claude Code 2.1.308 and Codex CLI 0.163.0, on macOS.

Contributing

Issues and pull requests are welcome. Read CONTRIBUTING.md first - a change to a skill must update the workflow guide in the same pull request.

Acknowledgements

This workflow is an independent adaptation, not an official distribution of the projects that inspired it. With gratitude to:

• Superpowers by Jesse Vincent and contributors (MIT) - the composable software-development methodology behind these skills: requirements brainstorming, detailed planning, strict TDD, systematic debugging, isolated subagent execution, independent review gates, evidence-based verification, and deliberate branch completion.
• mattpocock/skills by Matt Pocock (MIT) - the grilling interview technique adapted into brainstorming: walking the decision tree in dependency order and pairing every question with a recommended answer.

Both sources are MIT licensed, and their full license texts live in their repositories. This project reworks their ideas substantially rather than redistributing them verbatim.

License

MIT - Copyright (c) 2026 Ali Al-Sheiba.