eslamnegm010/ai-dev-workflow

separate agent writes the code, a hard quality gate checks the whole repo, and a third agent, which never saw the
plan, reviews the pushed PR. Screens are checked pixel by pixel against the design with golden tests. Every step
is written down in the repo, so any new session can pick up exactly where the last one stopped.
sh
curl -fsSL https://raw.githubusercontent.com/eslamnegm010/ai-dev-workflow/main/install.sh | bash
Then open Claude Code in any repository and say "set up the AI dev workflow here".
Contents: Why · The loop · Roles · Quality gate ·
Golden tests · Reviews · Status files ·
Examples · Install · Use it · Optional modules
## Why
AI agents write a lot of code quickly. Without a process they also guess at missing specs, approve their own work,
"fix" failing tests by weakening them, drift from the design, and forget everything when the context is compacted.
| Problem | What the workflow does about it |
| The agent invents behaviour, copy or pixels | Translate, don't invent. Every gap is logged as a discrepancy with options and a recommendation. The owner decides product questions; small technical gaps are decided and marked "delegated" |
| The same agent writes and approves the code | Three separate roles: the planner, the implementer (a new instance for every task) and the reviewer (one per PR, reading only the pushed diff) |
| "All tests pass" when they don't | The main session re-runs the gate itself. The gate covers the whole repo before every push, PR and merge |
| Tests edited until they go green | Never edit a test just to make it pass. Key tests are mutation-checked: break the code, watch the test fail, restore |
| The UI drifts from the design | Golden tests against captured design references, in every theme and language, with diff images and similarity scores |
| A new session doesn't know where things stand | Living status files: a progress log, a RESUME HERE line and every standing rule, in the repo |
| Endless fix rounds | Take over after the second failed round. Another round means the hand-off failed |
## The loop
Every substantive task runs these six steps. Small or mechanical tasks (docs, copy, config, renames) skip the agents:
the main session makes the change, runs the gate and self-reviews against the Definition of Done. The process
scales with the task.
Around the loop, the skill ships the whole method: stages with exit gates (alignment → foundation → design system
→ feature loop → hardening → release), a precedence table for sources of truth, Definition of Ready and Done, PR
sizing (≤ ~800 lines, stacked slices), a pre-push checklist, and change management for a new design export, rule
changes, copy and architecture.
## Roles you choose once
The skill asks once per repo, then writes the answer in two places: a dated Roles table in CLAUDE.md, and the
model: line of each agent file. Every later session follows it. A change of mind adds a new dated row, so the
history stays visible.
implementer: a fresh instance for every task. It builds exactly the plan, writes the tests, mutation-checks
the ★ tests, passes the gate and commits locally. It never pushes.
reviewer: one instance per PR, reused for that PR's rounds and replaced for the next PR, so it carries no