A workflow for AI engineers

/dev one entry point, two phases, six agents

Type-aware. Resumable. Specialists do the work — the orchestrator drives.

› /dev create a todolist app
press → to start · ? for help
02 · the shape

Two phases, ten numbered steps.

Phase 1 is interactive: a human approves the plan. Phase 2 is autonomous: agents implement, test, review, ship, reflect.

Phase 1 · Requirements
  1. 1 Interview + spec
  2. 2 Plan
  3. 3 Gate human approval
Interactive
Phase 2 · Implementation
  1. 4 Implement
  2. 5 Test
  3. 6 Review
  4. 7 Security trigger
  5. 8 Docs
  6. 9 Ship
  7. 10 Retro
Autonomous
03 · type-aware

The same flow, branched by intent.

Pick a type — see which phases run. No e2e test runs for a chore; no fix lands without a regression test.

04 · six agents

Specialists. The orchestrator only drives.

Hover an agent to see what it owns. Several have multiple modes, so the count stays small.

05 · artifacts

One folder per run. Templates, never freeform.

Everything lives in .workflow/<id>/. Resume cursor in state.json. Carry-overs in FOLLOWUPS.md.

.workflow/
├── INDEX.md
├── FOLLOWUPS.md
├── _templates/
└── 0001-feat-todolist-app/
    ├── state.json
    ├── spec.md
    ├── plan.md
    ├── test-plan.md
    ├── review.md
    ├── security.md
    ├── tests.md
    └── retro.md
06 · the gate

The non-negotiable checkpoint.

Before any code is written, the user sees the spec, the plan, and the per-task phase plan. Approve, revise, skip/run a discretionary phase, or swap.

Run plan · 0001-feat-todolist-app awaiting approval
Outcome TODOs scattered in notes → single-user todolist (CRUD · localStorage) · one place that persists
Type feat · Ship as: single PR
Stack Vite + React + TypeScript
Test plan AC1 → unit · AC2 → e2e · empty-list edge case probed
Will run 1 · 2 · 2½ · 3 · 4 · 5 · 6 · 8 · 9 · 10
Skipping 7 — no sensitive paths
07 · live flow

Watch a feat run move through the steps.

Press play. Each tile lights up as the active phase advances; cycle counters show review and test loops.

review0/2
test0/3
1interview
2plan
3gate
4implement
5test
6review
7security
8docs
9ship
10retro
› idle · press play to start
06 · security · trigger-based

Phase 7 fires only when the diff earns it.

Click a path on the left. If it matches the sensitive list, the security review fires automatically.

click a path
The orchestrator checks each changed file against the sensitive-paths list before phase 7. No match → recorded as skipped. Match → lead spawned in security mode.
  • auth / session / token
  • password / crypto primitives
  • SQL / query building
  • raw HTML render
  • file / path handling
  • exec / shell calls
  • deserialise untrusted input
  • env / secrets
  • new outbound network
09 · resumable

Context dies? /dev --resume <id> picks up.

Every step writes to state.json. Phase, step, cycle counters, last agent — all the cursor the orchestrator needs.

{
  "id": "0001-feat-todolist-app",
  "type": "feat",
  "phase": "phase-2-implementation",
  "step": "review",
  "next_step": "test",
  "cycles": { "review": 1, "test": 0 },
  "last_agent": "lead",
  "last_updated": "2026-05-14T12:48:03Z"
}

Each tick simulates the orchestrator finishing a step and writing state. The JSON updates live — that's exactly what --resume reads back.

10 · stop conditions

Loops have budgets. The orchestrator doesn't grind.

Review at 2, test at 3, then escalate. Anti-bias rule keeps reviews honest — checklists, not vibes.

review cycles max 2

After cycle 2, orchestrator escalates: continue / hand off / abort.

test cycles max 3

Same shape. No silent grinding past the limit.

security · high blocking

High severity loops count against the review budget.

interview mandatory

If pm skips it, orchestrator re-spawns. Spec built from a one-liner is broken.

11 · in practice

Three runs, three shapes.

Same orchestrator, same artifacts. The matrix flexes around the intent.

/dev create todolist app
feat
  1. interview → spec (Type=feat)
  2. plan: Vite + React + TS, 10 steps
  3. gate → approve
  4. scaffold → implement → tests pass
  5. review clean → docs → commit + PR
  6. retro → 1 skill candidate created
skips: 7 (no sensitive paths)
/dev fix login redirect loop
fix
  1. spec includes reproduction
  2. plan step 1 = failing regression test
  3. gate → approve
  4. test fails → fix → test passes
  5. security review fires (auth diff)
  6. commit only (no PR) → retro
fires: 7 · skips: 8 (docs)
/dev spike bullmq vs sidekiq
spike
  1. spec: timebox 1 day
  2. exploration plan, no production code
  3. gate → approve
  4. engineer explores both
  5. recommendations.md drafted
  6. retro → maybe a follow-up feat
skips: 5, 7, 8 · 9 optional
In one sentence

/dev runs a strict, resumable, type-aware loop so AI engineers can stay in the loop only at the moments that matter.

2
phases
10
steps
6
agents
1
gate
› /dev <your intent here>
← back · Home restart · WORKFLOW.md is the source of truth