Every skill, the files that carry the work, and one idea followed all the way to shipped.
A set of skills that take a change from a rough idea to shipped, tested and documented code, one skill per stage. The important state lives in files in your repository, not in a chat, so the work survives across sessions and is shared with your whole team.
The nine skills
There are nine. You run only the ones a change needs, in whatever order fits.
Skill reference
One entry per skill: what it does, when to run it, what it writes, and what it will not touch. Every entry is self-contained, so you can jump straight to the one you need.
Turn an idea into a plan of what to build
The entry point for a product or a new slice of one. It turns what you describe into a high-level plan of what to build and in what order, written to docs/scope/, and it keeps that plan current as features land.
Write the context files every other skill reads
It reads your real code and writes AGENTS.md: the plain-text description of your stack, your commands and your conventions. Every other skill reads it, which is why nothing else has to guess how your project works.
Make the decision, and write it as a spec
A design conversation that ends in a file. A stack, a data model, a provider, a page design: any decision the build depends on gets made here and written to docs/specs/ as the contract the build follows.
Build the feature from its spec
The only skill that writes application code. It builds a feature, user interface or backend, from its spec, runs migrations for real, and moves the scope and the spec status forward as work lands.
Prove it runs, then read it with fresh eyes
Two modes with one job: confirm a change before it merges. Verify drives the real running app against the spec. Review reads the code on a different model than the one that wrote it.
Lock the proof into a test suite
Writes a real test suite for the code you just changed, so what was proven once stays proven. It works out your framework the first time and remembers the choice.
Write the human-facing text from the real diff
Reads the actual commits and the actual diff and writes the prose a finished change needs: a pull request body, a changelog entry, a release note, a postmortem.
Bring the knowledge back in line with the code
The closing step. It looks at what the repo now shows and reconciles the durable files to it, so the next session starts from an accurate picture instead of a stale one.
Find the real cause, then keep it fixed
Not part of the sequence. Reach for it anytime something is failing, throwing, or behaving wrong. It does one thing only, find and fix the real cause, and adds no features along the way.
The files that carry the work
Everything the workflow knows is written into files in your repo. This is the whole idea. A chat can end, a session can be cleared, a teammate can pull the branch, and the knowledge is still there because it was never trapped in a conversation. There are four kinds of file, and each one has a clear life.
The context files, named AGENTS.md
These describe how your project actually works (its stack, its commands, its conventions) in plain text any coding agent can read. On a project that uses Claude Code there is also a tiny CLAUDE.md that does nothing but point at AGENTS.md, so there is only ever one real source and no copy to drift.
The key idea is that these files nest. One at the root for rules that apply everywhere; more inside folders for rules that apply only to that area. When a skill works on the payments code, it reads the nearest one, so it sees both the project-wide rules and the local ones.
audit creates these files. Every other skill reads them. sync keeps them current as the code changes. No skill guesses your conventions when a context file already states them.
The scope, in docs/scope/
The high-level plan of what to build and in what order. scope creates it. develop advances it as features get built, marking a feature in progress and ticking milestones, but never marking a feature fully done on its own, because built is not the same as verified. A bare run of scope, and sync at merge time, reconcile it back against what the code now shows.
The specs, in docs/specs/
A spec is the written record of one real decision, and it is the contract the build follows. This is the file type people ask about most, so here is its full life.
Two rules keep this clean. Only architect writes the content of a spec. Only develop moves the status. That single ownership is why the files do not turn into mush over time.
The design system, in design.md
This holds the art direction for your interface: the character, and the rules for how pages are put together. The real values, the exact colors and sizes, live in your project's CSS, and design.md only points at them, so a value is never written in two places. develop creates it the first time you build an interface, or extracts it from your existing screens.
Who owns which file
The files stay trustworthy because ownership is fixed. Here is who creates each file, who reads it, and who is allowed to change it.
The one thread that ties the stages together
Under all the stages runs a single thread that keeps the work honest: the acceptance criteria. When architect writes a spec, it turns each requirement into a short, numbered statement of what done means, for example, that a signed-in person sees only their own tasks.
So a single requirement can be followed in a straight line, from the decision, to the code that satisfies it, to the proof that it works, to the test that keeps it working. Nothing important is left unmeasured, and nothing is marked done that was not actually proven.
Workflow depth
At the end of scope you pick a workflow depth for the project, and you can override it per feature anytime. The depth is a suggested checking tail after develop, never a track you are locked onto. You run or skip any step and mark a feature done when you decide it is. The one thing the workflow asks, at every depth, is that a load-bearing decision gets written down.
If building would mean inventing an undecided design, provider or data model, develop stops and points you to architect. You can override and build anyway, but the override is not free: the assumption is recorded as an Assumed spec and flagged on the feature until architect confirms it. The flag does not block you from marking done: it is a standing reminder that a decision still needs confirming, so it never gets silently lost in chat.
A worked example, from idea to shipped
To make the flow concrete, follow one idea all the way through. The idea is a small app where people sign in and keep their own to-do list. It is a brand new project, so it touches almost every stage. At each stage the workflow asks a small number of questions, and each answer changes what happens next.
Scope the idea
It turns the idea into a high-level plan and writes it to docs/scope/. Because there is no code yet, it treats this as a brand new project and plans the first slices, starting with the foundation and the first real feature.
The one real question here is how you want to deliver the work. Your pick shapes the order everything is built in later, and is recorded as the project default: any single feature can override it.
Decide the stack
Because this is a new project with no stack yet, architect works in stack mode: a wide comparison of options with a clear recommendation. Before it asks anything, it reads whatever context files exist, so it never asks what it can already see.
If a decision could be helped by an outside connector or a ready-made skill, it asks first whether you want it to look, and only searches if you say yes. Anything it finds and relies on gets written into the spec. When the conversation is done it writes the decision as a spec in docs/specs/, status Proposed.
Set up and read the real project
You set up the empty project with the stack’s own setup tool, so there is a real project to read. Then audit reads it and writes the context files: a root AGENTS.md with a tiny CLAUDE.md pointer beside it, recording the stack, the commands, and the conventions it can see.
The order matters. The stack is chosen and the project exists before audit runs, so audit reads a real project instead of guessing about an empty folder.
Design the sign-in feature
Now architect works in feature mode: a focused design of one thing rather than a whole stack comparison, using the same three kinds of questions.
Before writing, it checks whether a spec for this already exists. If a very close one is found, it asks whether to treat this as a brand new decision, an update, or a replacement. It also decides the shape: a single file for a simple decision, a small folder when the decision is large. It writes the spec as Proposed and links it to the matching row in the scope.
Build it
This is where the most branching happens, and it happens in a set order. First the check: to build this, would it have to invent something you have not decided? For sign-in the spec exists, so it goes ahead and builds. If a decision were missing it would stop and offer to decide it first in architect (recommended), build directly if you judge there is nothing to decide, or skip for now and leave a mark that a decision is still needed.
Then it sorts the task into user interface work, backend work, or both. Sign-in is both.
The backend part runs in fixed phases, each with a senior rule baked in: build the data layer and actually run the migration and confirm the tables exist; build core logic with repeated requests made safe so a double tap cannot create two accounts; build endpoints that check not just that a caller is logged in but that they are allowed to touch this particular thing; wire outside services with secrets read from the environment; delete replaced code so two versions never sit side by side; finish with a safety pass. If the spec turns out to be wrong partway through, it stops and sends you back to architect rather than quietly building something else.
The interface part starts with one question (where does the design come from) and every screen must leave as a complete, professional product: brand, real wording, layout, and the empty, loading and error states. Before reporting done it looks at its own work, rendering the screen if it can, and fixes visual defects.
When the build lands, develop moves the spec from Proposed to In Progress, ticks the parts of the plan that truly landed, and updates the scope. It does not mark the feature done: that waits for verification and tests. Finally it writes concrete manual check steps derived from the acceptance criteria, and asks whether to save them to a verify.md beside the spec.
Prove it runs
It drives the real running app and proves the feature actually works against its spec: every promised behavior and every promised screen, not just that a test file passed. For the to-do app that means it can really sign up, sign in, and see its own list.
Write the tests
It writes a real test suite for the code you just changed, working out your test framework and asking and remembering it the first time. It covers the normal path, the edge cases, the error states and the accessibility of any interface. When verification has passed and the tests are in, the feature can finally be marked done, and its spec moves from In Progress to Accepted.
Get a second opinion
It runs a senior code review on a different model than the one that wrote the code, because a model reviewing its own work tends to agree with itself. It writes its findings to docs/reviews/, sorted from the most serious down to small preferences, and it also says what the change did well. It reads the code; it does not change it.
Write it up
It reads the real commits and the real difference in the code and writes the human-facing text (a pull request body, a changelog entry, a release note, whatever the moment needs) and puts each in the right place. It writes no code and no specs.
Bring the knowledge back in line
It looks at what the code now shows and reconciles the durable files back to it: updates the context files if the build introduced a new convention, reconciles the scope, and flags any spec the change made out of date. It makes small, surgical edits (adding lines and fixing the lines it owns) and never rewrites your prose.
At this point the loop is closed. The feature is shipped, proven, tested, reviewed, written up, and the files that carry the project's knowledge are current again. You clear the session and start the next feature fresh, and because everything lives in files, the fresh session knows exactly where things stand.
When something breaks: the debug loop
You run debug. It does one thing only (find and fix the real cause) and it adds no features and tidies no unrelated code along the way. You reach for it anytime something is failing, throwing, or behaving wrong, and you need no scope and no spec to run it.
On an existing codebase, and in a monorepo
The worked example was a brand new project. Two common situations differ slightly.
On an existing codebase, run audit first. It reads your real code and writes the context files, so every later skill understands your stack and conventions before it touches anything. Then scope enrolls what already exists and plans the new slice on top. From there the loop is the same.
In a monorepo (one repository holding several projects) everything scopes to the one workspace you are working in. Each workspace gets its own scope, its own specs, and its own nested context files, and every skill stays inside the target workspace and uses that workspace's own commands. A change to one app does not reach into another.
Safe to resume, and safe on a team
Because the state lives in files, you can stop at any handoff, clear the session, and pick up later with nothing lost. When develop resumes a half-built feature, it reads which tasks are already done and starts at the first unfinished one, so it never rebuilds what already shipped.
On a team, before it changes anything, develop checks a few things and warns you rather than charging ahead. These are warnings, not walls, but they surface before any code is written.
What the workflow will not do
The limits matter as much as the features.
Frequently Asked Questions
No. You run only the ones a change needs. A tiny change can be just /develop and then /check verify. A bug is just /debug.
If a real decision is missing, /develop stops and offers to send you to /architect to make it, or to build directly if you judge there is nothing to decide, or to skip for now and leave a note that a decision is still needed.
A long chat costs more and drifts. Because the work is saved in files, a fresh session reads the current state from disk and continues cleanly, so clearing loses nothing.
If docs/ is a live documentation site, the workflow writes its files to a .workflow/ folder instead, so they do not ship with your site.
Yes. The style you pick in scope is the project default, and any single feature can override it when that feature is better built a different way.
No prompt is. The check is layered: architect names the source of every value a feature must produce, develop checks that coverage again before building, and at Beta and above architect recommends an independent cross-model critic over the spec. It is defense in depth that catches the vast majority; behavioral correctness is caught by the /check verify and /test layers.
Getting started
Install with npx skills. Pick the line for your agent, then commit the installed skills folder so your whole team shares the same workflow.
For a brand new product start at stage 1 above. For an existing codebase run audit first, then plan the next slice with scope and follow the same loop. For a bug, go straight to debug. For a tiny change, run just develop and then check verify.