claude-foundation — a /dev workflow for Claude Code

Why it exists

Structure where AI coding usually has none.

Most agent coding is ad-hoc: a prompt, a diff, hope. This turns it into a pipeline with gates, checklists, and a paper trail — without slowing the easy stuff down.

01

Single entry point

One command, one flow. No scattered /plan, /review, /test — the orchestrator runs them in order so nothing gets skipped.

02

Type-aware

A chore skips e2e tests. A fix writes its regression test first. A spike is timeboxed and returns a recommendation, not code.

03

Artifacts on disk

Every run leaves a folder — spec, plan, review, tests, retro, and a state.json cursor. Audit it, hand it off, or resume after a crash.

04

Reproduce before fix

A fix can't ship without a regression test that fails on the pre-fix code and passes now. Enforced at plan, implement, and test time.

The /dev flow

Two phases. Ten steps. One gate between them.

Phase 1 is interactive — you shape the spec and approve the plan. Phase 2 is autonomous — agents implement, test, review, and ship, only stopping on blocking issues.

gate — you approve / revise / skip / run / swap conditional — security (sensitive diff) review & test loops back to implement --resume re-enters at the saved step

Phase 1 — Design

Interactive

1
Interview + specOrchestrator interviews you (≤4 questions), then pm writes spec.md.
2
Planlead maps the spec to executable steps with path#anchor refs, risks, and verification.
3
GateYou see spec + plan + the type-aware step list, and approve before any code lands.

Phase 2 — Build & ship

Autonomous

4
Implementengineer executes the plan and ticks each acceptance criterion or files a blocker.
5
Testqa writes & runs unit + integration + e2e, mapping every criterion to a test — before review, so reviewers judge a green suite.
6
Reviewlead checks the diff row-by-row against the plan and spec — no "looks good."
7
Security reviewTrigger-based — fires only when the diff touches auth, SQL, crypto, secrets, exec…
8
Docs touch-upengineer updates inline comments where the why is non-obvious.
9
ShipStages, commits with a spec-aware message, and opens a PR via gh if opted in.
10
Retroretro writes retro.md, carries over follow-ups, surfaces memory & skill candidates.

The gate is non-negotiable. Reply approverevise <notes>skip <n>run <n>swap <n>. The lead proposes a per-task phase plan; any deviation from the type matrix — and skip/run on a discretionary phase (test · review · docs) — needs your explicit per-line OK. Once you approve, Phase 2 only stops on blocking review issues, failing tests, or genuine ambiguity.

Type-aware phase matrix

The same ten phases adapt to what you're doing.

Pick a run type and watch the pipeline reshape — what runs, what's skipped, what runs light.

The roster

Roles are split so no one grades their own homework.

The planner isn't the implementer; the reviewer checks against the plan and spec it can't quietly edit. The orchestrator (the main agent) runs the interview, the gate, and fanout.

@pmPhase 1

Writes spec.md from the interview Q&A and any research findings — outcome (before → after → benefit), users, scope, non-goals, acceptance criteria, and the Type slot.

writesspec.md

readsinterview · FOLLOWUPS · fanout

@lead2 · 6 · 7

Three modes: plan, review, security. Writes the plan, then reviews the diff row-by-row against that plan and the spec's acceptance criteria.

writesplan.md · tasks.md · review.md · security.md

readsspec.md · the diff

@engineer4 · 8 · 9

Three modes: implement, docs, ship. Works through tasks.md with progress tracking, ticks each criterion, then commits and opens the PR.

writescode · commit · PR

readstasks.md · spec.md

@qaPhase 2½ + 7

First designs the test strategy into test-plan.md before any code (which level proves each criterion, edge cases to probe, fixtures) — signed off at the gate. Then executes it: unit + integration + contract + e2e, every acceptance criterion mapped to a test, with advisory diff-coverage floors on the changed code (unit ≥80% · integration ≥70% · e2e ≥50% of critical journeys). UI diffs get a visual + accessibility (axe-core) pass in the same browser session. For a fix, it verifies the regression test fails on pre-fix code.

writestest-plan.md · tests.md · tests

readsspec.md · plan.md · the diff

@retroPhase 10

Closes the run — writes retro.md, appends to FOLLOWUPS.md, marks consumed items, and surfaces memory + skill candidates for you to confirm.

writesretro.md · FOLLOWUPS

readsall artifacts · the diff

@uxuiteam mode

Design-time UX for UI-bearing work. Writes uxui-plan.md — Scenes (every screen/state), Scenarios (user flows), UX direction & components, and an AC↔scene mapping that catches orphan screens and unmapped criteria. Drives ui-ux-pro-max; design only, no UI code.

writesuxui-plan.md

readsspec.md · design system

@orchestratormain agent

Not a sub-agent — the main agent is the orchestrator. It runs the interview, the gate, fanout dispatch, and drives all ten phases via .claude/orchestrator.md.

ownsgate · interview · state.json

+ parallel fanout workers

/dev is delegation-first: whenever a phase splits into independent sub-investigations, it fans out by default — focused team-* workers run in parallel and a sub-agent synthesises their findings into one artifact. The splittable workers spawn their own helpers directly (direct nesting), and a multi-repo run fans review, security, and test out per repo.

team-codebase-explorer team-best-practice-researcher team-code-reviewer team-silent-failure-hunter team-type-design-analyzer team-pr-test-analyzer

Review fans out tiered: core 3 at M, full 4 at L — simplification and comment-accuracy run as lenses inside team-code-reviewer since v2.8.

+ run one role on its own — team mode

Don't want the whole pipeline in one shot? Hand each role its own command. Each one writes into the same .workflow/<id>/ run and shares the gate, so the work still composes. The three Phase-1 plan slices — /dev-plan, /test-plan, /uxui-plan — can even run in parallel: each writes its own state.<slice>.json shard instead of the shared cursor, and the gate folds them back together single-writer. Then /dev --resume <id> (or /implement) carries it the rest of the way.

/spec → @pm /dev-plan → @lead /test-plan → @qa /uxui-plan → @uxui /implement → @engineer · Phase 2

Always-on fundamentals

Pre-flight rules that load before code lands.

Each rule is a three-line always-on pointer — trigger, one-sentence why, skill path. The full skill body loads on demand before the relevant work happens, and the cross-skill run order lives in one file — the right checklist at the right moment, without paying for it in every context window.

coding-disciplineStated assumptions, minimal code, surgical diffs, verifiable done. ddd-strategicBounded contexts, ubiquitous language, aggregate sizing. programming-fundamentalsData shape, illegal states, pure core, error handling. database-fundamentalsSchema, constraints, indexes, plans, safe migrations. hexagonal-backendPorts & adapters, dependency direction, layering. api-design-fundamentalsResource modeling, HTTP semantics, errors-as-contract, versioning. architecture-fundamentalsBoundaries, ownership, sync/async, resilience, contracts. queue-fundamentalsDelivery semantics, idempotency, DLQ, outbox pattern. debug-fundamentalsReproduce, read evidence, bisect, fix the real layer. git-workflowAtomic commits, why-carrying messages, safe recovery.

product skills · loaded on demand

brainstorming plan-writing fanout-team-agents frontend-design ui-ux-pro-max tailwind-design-system skill-creator

Single source of truth

One router. One writer. No cycle.

Every run reads skills, fires phases, and calls rules down the same spine — so each fact lives in exactly one place. Here's the control plane and the five properties that keep it from looping or drifting.

the router is canonical — triggers & run order live here only one writer for state.json — slices fold at the gate mirrors point back, never redefine

✓ One source of truth

.claude/rules/fundamentals.md owns every trigger and the cross-skill run order. CLAUDE.md, README.md and WORKFLOW.md only mirror it and name it canonical — they never restate a trigger as fact.

✓ No cycle in the chain

Construction skills run in one fixed line — ddd-strategic → … → observability. A skill never re-invokes one earlier in the chain, so the dependency graph is a line, not a loop.

✓ One writer for state

Only the orchestrator writes state.json. Team-mode /dev-plan · /test-plan · /uxui-plan each write a state.<slice>.json shard; the gate folds them in once. Sub-agents never touch the cursor.

✓ The only loops are bounded

The sole back-edges are test → implement ≤ 3× and review → implement ≤ 2×, both capped. Every other edge flows forward; --resume re-enters at the saved step, it doesn't loop.

✓ Loaded lazily

A trigger pulls exactly one skill body on demand — and on the hot path, at most one targeted references/<file>. Nothing reads the whole library per turn.

Everything on disk

A run is a folder you can read, replay, or resume.

Agents copy from templates into a per-run folder — nothing freeform. If the session dies, /dev --resume <id> picks up from the state.json cursor.

.workflow/
├── 0003-fix-login-redirect/
│   ├── spec.md        # the contract
│   ├── plan.md        # design & strategy
│   ├── tasks.md       # executable T### list
│   ├── test-plan.md   # test strategy
│   ├── review.md      # row-by-row
│   ├── security.md    # if triggered
│   ├── tests.md       # AC → test map
│   ├── retro.md       # what we learned
│   └── state.json     # resume cursor
├── INDEX.md           # run registry
└── FOLLOWUPS.md       # carry-over

spec.md · pm

Outcome (before → after → benefit), users, scope, non-goals, acceptance criteria, Type.

plan.md · lead

Design & strategy: approach, path#anchor refs, diagram, risks, verification.

tasks.md · lead

Dependency-ordered T### task list — each tagged with its acceptance criteria + a runnable verify line.

test-plan.md · qa

Test strategy before code: level per criterion, edge cases, fixtures. Signed off at the gate.

review.md · lead

One check per file, one row per acceptance criterion.

security.md · lead

Inline checklist; high findings are blocking.

tests.md · qa

Each criterion mapped to a specific test; run results + coverage.

recommendations.md · spike

What we learned + the recommended next step.

retro.md · retro

Outcomes, follow-ups, memory & skill candidates.

state.json · all

The phase cursor that makes --resume work.

Team awareness

See who's online — and who's about to conflict with you.

A tiny presence board for everyone on the flow. One background command per machine; one page that shows who's working where — and warns when two people edit the same lines, before the merge.

⚠

acme/checkout · src/payment/charge.ts

alice ⎇ feat/stripe-retry L42–58 ⨯ bob ⎇ fix/idempotency L50–63

alice · alice-mbp

working in

acme/checkout-service ⎇ feat/stripe-retry 7 files

~/work/checkout-service

/dev 0042-feat-stripe-retry · implement

Presence

Who's online right now, by git name + host. In-memory, 30-second window.

Working in

The repos each person has uncommitted changes in — folder path + an optional label, so nested sub-repos stay distinct.

/dev activity

Which run is in flight and what phase, read straight from state.json.

Conflict warning

Overlapping line ranges across branches in the same file — flagged to both people before anyone pushes.

View the live demo claude-foundation dashboard-up --key … No key needed for the demo · binds no port · opt out with --no-conflicts

See it move

An interactive walkthrough of the whole flow.

Twelve slides — the phases, the type matrix, the agents, the gate, an animated live run, and resume. Built with the workflow itself.

claude-foundation / dev-workflow-slides open full-screen

Load the interactive deck · ← → to navigate

Get started

One command drops it into any repo.

Install with Homebrew (or the bundled install.sh). Foundation-owned files refresh on every run so upstream updates land; your state files are never overwritten.

bash

# 1 · install the CLI via Homebrew (macOS / Linux)
brew tap maximumsoft-co-ltd/claude-foundation https://github.com/Maximumsoft-Co-LTD/claude-foundation
brew trust maximumsoft-co-ltd/claude-foundation
brew install claude-foundation

# 2 · scaffold the foundation into your project
cd /path/to/your/project && claude-foundation

# …or skip Homebrew — clone and run install.sh directly
git clone https://github.com/Maximumsoft-Co-LTD/claude-foundation.git
cd claude-foundation && ./install.sh /path/to/your/project

# 3 · inside your project, in Claude Code
/dev create a todo app with localStorage
/dev --resume 0003-fix-login-redirect

--dry-run print the plan --force overwrite settings --yes skip confirm --source <path>

Installbrew install claude-foundation via Homebrew (after tapping & trusting the tap), or clone and point ./install.sh at your target repo. --dry-run previews exactly what lands.
Enable GitHub PagesThis very site lives in website/ — publish it to GitHub Pages with a GitHub Actions deploy.
Run /dev <intent>Describe the change in plain language. The orchestrator picks the run ID and drives the flow.
Approve at the gateReview the spec and plan, reply approve, and let Phase 2 take it to a shipped PR.

Changelog

Everything that's shipped, straight from the source.

Fetched live from CHANGELOG.md on GitHub — no copy to drift — in Keep a Changelog format, grouped by change type. Filter below or read the full file on GitHub.

Loading the latest changes…

Ship changes with a
small team of agents.

Structure where AI coding usually has none.

Single entry point

Type-aware

Artifacts on disk

Reproduce before fix

Two phases. Ten steps. One gate between them.

Phase 1 — Design

Phase 2 — Build & ship

The same ten phases adapt to what you're doing.

Roles are split so no one grades their own homework.

+ parallel fanout workers

+ run one role on its own — team mode

Pre-flight rules that load before code lands.

One router. One writer. No cycle.

✓ One source of truth

✓ No cycle in the chain

✓ One writer for state

✓ The only loops are bounded

✓ Loaded lazily

A run is a folder you can read, replay, or resume.

See who's online — and who's about to conflict with you.

Presence

Working in

/dev activity

Conflict warning

An interactive walkthrough of the whole flow.

One command drops it into any repo.

Everything that's shipped, straight from the source.

Stop vibe-coding. Run the pipeline.

Ship changes with asmall team of agents.

Structure where AI coding usually has none.

Single entry point

Type-aware

Artifacts on disk

Reproduce before fix

Two phases. Ten steps. One gate between them.

Phase 1 — Design

Phase 2 — Build & ship

The same ten phases adapt to what you're doing.

Roles are split so no one grades their own homework.

+ parallel fanout workers

+ run one role on its own — team mode

Pre-flight rules that load before code lands.

One router. One writer. No cycle.

✓ One source of truth

✓ No cycle in the chain

✓ One writer for state

✓ The only loops are bounded

✓ Loaded lazily

A run is a folder you can read, replay, or resume.

See who's online — and who's about to conflict with you.

Presence

Working in

/dev activity

Conflict warning

An interactive walkthrough of the whole flow.

One command drops it into any repo.

Everything that's shipped, straight from the source.

Stop vibe-coding. Run the pipeline.

Ship changes with a
small team of agents.