agentleFS
bakhod1rbakhod1r/awesome-agents/.claude/skills/orchestration/SKILL.md

orchestration

Skill0 starsChanged 3 months agoMITView on GitHub

Run a task end to end through the full delivery pipeline — product discovery, architecture, build, verification, release. Use when the user gives a goal rather than a specific technical instruction, or invokes /flow.

  • Commits and pushes

48 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use orca-cli, orca-per-workspace-env and 10 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • HK-hubSkill

    orca-cli

    Use the public `orca` CLI to operate Orca-managed worktrees, folder contexts, terminals, repos, automations, artifacts, worktree comments, and the browser embedded inside the Orca app. Use when the user says "$orca-cli", "use orca cli", "Orca worktree", "child worktree", "cardStatus", "spawn codex/claude in a worktree", "read/wait/send Orca terminal", "terminal send", "full handoff", "handover", "give this to another agent", "another worktree", "Orca browser", "orca artifacts", "share HTML/Markdown", "public artifact link", or "control the browser inside Orca". Prefer this over raw `git worktree`, ad hoc PTYs, Playwright, or Computer Use when the task touches Orca-managed state. Use Computer Use for browser windows, webviews, or desktop UI outside Orca's embedded browser.

    Also in 5 projects that use this

  • Iron-HamSkill

    orca-per-workspace-env

    Set up, review, debug, or validate Orca per-workspace environment recipes — on-demand, disposable runtimes (cloud sandboxes, VMs, or local) created fresh for each workspace. Covers first-time setup (provider prerequisites, the reusable base snapshot, the coding-agent auth snapshot, credentials, and state), not just the per-workspace lifecycle scripts. Use to stand up per-workspace environments, fix an `environmentRecipes` entry in `orca.yaml`, scaffold provider lifecycle scripts, or resolve an `orca vm recipe doctor` failure.

    Also in 3 projects that use this

  • HK-hubSkill

    computer-use

    Use Orca's computer-use CLI to inspect and operate local desktop app windows through accessibility trees, screenshots, and safe UI actions. Use for desktop app interaction: list apps/windows, get app state, read visible UI, click controls, type, press keys, scroll, drag, set values, or perform accessibility actions. Also use for browser windows, webviews, Orca app UI, or other desktop UI. Triggers include "computer use", "orca computer", "read Spotify", "read Slack", "control/click/read in a desktop app", and "get app state".

    Also in 6 projects that use this

  • kongyo2Skill

    prompt-engineering

    Comprehensive prompt engineering framework for designing, optimizing, and iterating LLM prompts. This skill should be used when users request prompt creation, optimization, or improvement for any LLM task, or when users need help translating vague requirements into effective prompts through collaborative dialogue and iterative refinement.

    Also in 3 projects that use this

  • AnthropicSkill

    wrap-up

    Close out (or revisit) a Claude Managed Agent build — refresh the overview page, recap every primitive the founder now owns, show the run log and live status, suggest 1–2 tailored next upgrades, and sweep hygiene (sessions archived, key only in .env, no literal dates in deployment kickoffs). Use when the founder says "/wrap-up", "wrap up", "close it out", "where do things stand with my agent", or at the end of a /launch-your-agent build.

    Also in 3 projects that use this

  • SentrySkill

    deslop

    Strip AI-generated noise from the diff before pushing — extra comments a human wouldn't write, defensive try/catch in trusted code paths, casts to any, inline imports in Python, and other style inconsistencies with the surrounding file. Use this immediately before commit so the diff stays clean.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

15 rules. 0 are common, 11 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 43 edited versions we read keep these.

  • 11

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every hand-off passes through you, which is what makes the chain inspectable.

    line 12
  2. Distinctive:

    Ask the user rather than invent a metric.

    line 119
  3. Very specific:

    Run architects in parallel only when their concerns do not overlap.

    line 163
  4. Distinctive:

    A written rollback is not a rollback: Run it. Deploy the change to an environment that matters, roll it back, and confirm the system is …

    line 240
  5. Distinctive:

    Run the full suite yourself: Not the changed tests — the whole suite, plus lint and build.

    line 246
  6. Distinctive:

    Then stop and hand over: Do not commit, tag, or push unless the user explicitly asks.

    line 264
  7. Distinctive:

    All three are this stage. Reporting only the first is the usual failure.

    line 298
  8. Distinctive:

    If it is met, say so and withdraw it.

    line 306
  9. Very specific:

    A rollback or a failed smoke earns a post-mortem: Use the postmortem skill: timeline, what was believed at each point, why the gates let it …

    line 309
  10. Distinctive:

    Every stage begins with its lead writing a short plan and ends against it.

    line 336
  11. Very specific:

    Every stage has a lead who owns its result end to end — product-lead, architecture-lead, design-lead, the owning engineering lead, …

    line 373
  12. Very specific:

    ② back to ①: When the architects find the feature as scoped is too expensive, too risky, or blocked, product-manager re-opens it rather …

    line 409
  13. Distinctive:

    ③ back to ②: When design shows the contract cannot carry the flow — the screen needs one call and the contract gives four, or it needs a …

    line 415
  14. Distinctive:

    If it cannot move, ③ redesigns inside the real limit and says what the user loses.

    line 418
  15. Distinctive:

    Two bounces means the loop is wrong: If ② and ③ hand the same problem back and forth twice, the constraint is not technical — the scope is …

    line 431

“Common” is measured: kept by at least 6 in 10 of the 43 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Orchestration

One task. Seven stages. Each stage produces an artefact the next stage consumes. No artefact, no advance — that is the whole mechanism.

You are the orchestrator. Agents cannot call each other; they have no Agent tool. Every hand-off passes through you, which is what makes the chain inspectable.

The pipeline

                              USER GOAL
                                  │
  ┌───────────────────────────────▼───────────────────────────────┐
  │ ① DISCOVER   Product Strategy — product-manager, business-analyst
  │              → problem, segment, success metric, non-goals, kill criterion
  │              → written spec: scope, out-of-scope, acceptance criteria
  │              ⛔ no measurable metric → stop, ask the user
  │              ⛔ spec not approved by the user → nothing downstream starts
  └───────────────────────────────┬───────────────────────────────┘
        ▲                         │  problem + metric, verbatim
        │                         ▼
        │  ┌────────────────────────────────────────────────────────┐
        │  │ ② ARCHITECT  Architecture — backend-, frontend-, security-,
        │  │              database-architect, by domain
        │  │              → options, trade-offs, failure modes, ADR,
        │  │                + the CONTRACT design works in, with its cost
        │  │              ⛔ irreversible decision without an ADR → do not build
        │  └────────────────────────┬───────────────────────────────┘
        │        ▲                  │  ADR + contract, verbatim
        │        │                  ▼
        │        │  ┌─────────────────────────────────────────────────┐
        │        │  │ ③ SHAPE     Design — ui-designer, ux-researcher,
        │        │  │             interaction-designer, content-designer,
        │        │  │             then design-qa-engineer tests the design itself
        │        │  │             → 2-3 mock files, one recommended, every reachable
        │        │  │               case drawn, flow + state spec, interface copy
        │        │  │             ⛔ visible change with no mock → nothing to build
        │        │  │             ⛔ design QA finds an undrawn case → not ready
        │        │  └────────────────────────┬────────────────────────┘
        │        │                           │  chosen mock + state spec
        │        │                           ▼
        │        │  ┌─────────────────────────────────────────────────┐
        │        │  │ ④ BUILD     owning engineering team
        │        │  │             → implementation, tests incl. failure paths,
        │        │  │               migrations, instrumentation
        │        │  │             ⛔ no failure-path test → not done
        │        │  └────────────────────────┬────────────────────────┘
        │        │                  ▲        │  diff + mock + ADR
        │        │                  │        ▼
        │        │                  │  ┌──────────────────────────────┐
        │        │                  │  │ ⑤ VERIFY   Quality — code-reviewer
        │        │                  │  │            + the specialist for the change
        │        │                  │  │            → ranked findings: claim,
        │        │                  │  │              file:line, impact, fix
        │        │                  │  │            ⛔ open HIGH → back to ④
        │        │                  │  └─────────────┬────────────────┘
        │        │                  │  HIGH finding  │
        │        │                  └────────────────┤
        │        │                                   ▼
        │        │                  ┌──────────────────────────────────┐
        │        │                  │ ⑥ RELEASE  production-readiness-engineer,
        │        │                  │            release-manager, SRE
        │        │                  │            → full suite output, version + SemVer
        │        │                  │              rule, CHANGELOG, release notes,
        │        │                  │              rollout, rollback, owner, runbook
        │        │                  │            ⛔ red test / no owner / no rollback
        │        │                  │              / untested rollback → no ship
        │        │                  └─────────────┬────────────────────┘
        │        │                                ▼
        │        │                        RELEASE PACKAGE
        │        │                     handed over, then deployed
        │        │                                │
        │        │                  ┌─────────────▼────────────────────┐
        │        │                  │ ⑦ OBSERVE  qa + user-acceptance-tester
        │        │                  │            + site-reliability-engineer
        │        │                  │            + product-manager on the metric
        │        │                  │            → post-deploy smoke on the real
        │        │                  │              environment, a profile panel of real
        │        │                  │              users by age and sector running the
        │        │                  │              task, error and latency watch, then
        │        │                  │              ①'s metric measured
        │        │                  │            ⛔ smoke fails or abort threshold hit
        │        │                  │              → roll back now, diagnose after
        │        │                  └─────────────┬────────────────────┘
        │        │                                ▼
        │        │                     metric moved? kill criterion hit?
        │        │                                │
        └────────┴────────────────────────────────┘  answer goes back to ①
        │        │
        │        └── ③→② the contract cannot carry the flow the user needs:
        │               widen it and state the cost, or say why it cannot move
        │
        └─────────── ②→① the feature as scoped cannot be built at acceptable
                        cost or risk — product re-scopes, architects do not trim
                     ③→① research or the mocks show ①'s problem or metric is wrong
                     ②⇄③ twice → escalate to ①: the scope is wrong, not the technique

Stage contracts

Each stage declares what it needs and what it must return. A stage that cannot produce its artefact fails loudly — it never guesses forward.

① Discover — Product Strategy Team

Agentsproduct-manager; add business-analyst when business rules or process are involved
NeedsThe user's goal, any constraints, existing analytics if available
ReturnsProblem statement, affected segment, success metric, non-goals, kill criterion
GateA success metric that is measurable. "Users are happier" fails. "Checkout completion rate, currently 61%, target 70%" passes.

Ask the user rather than invent a metric. This is the one stage where stopping is correct.

The stage ends with an approved spec, not a conversation. product-lead writes it and puts it in front of the user; business-analyst supplies the rules where the domain is involved. Everything downstream quotes this document, so an ambiguity left in it is an ambiguity built into the product.

SectionWhat it must say
ProblemWho is blocked, at which step, and what it costs today — with a number
ScopeThe specific capability being built, in the user's language
Out of scopeWhat a reader might reasonably assume is included and is not
Acceptance criteriaObservable conditions, each one testable: given, when, then
Success metricCurrent value, target value, and the window it is measured over
Kill criterionThe condition under which the feature is withdrawn
Performance budgetThe number the result must hold: page or endpoint latency, payload size, cost per request. Agreed here, so ⑤ has nothing to argue about
AssumptionsWhat is taken as true without proof, and what breaks if it is wrong
Open questionsEach with an owner and a date, or the stage is not finished

Approval is explicit and it is the user's. Not "no objection", not silence — a stated yes to that document. Until it exists, ② has nothing to design against and every later disagreement about "what we agreed" is unresolvable. An approved spec that changes later is fine and normal; it is re-approved, with what changed named.

② Architect — Architecture Team

AgentsRoute by domain: backend-architect, frontend-architect, data-architect, security-architect, ai-architect, mobile-architect…
NeedsStage ① output verbatim, plus the current system state you read yourself
ReturnsOptions considered, trade-offs, failure modes, recommendation, ADR path, and the contract design works inside: what the system can return, in one call or several, how fast, and what it costs to change
ReturnsOptions considered, trade-offs, failure modes, recommendation, ADR path
GateIrreversible decision without an ADR does not proceed. Reversible ones may skip. A change touching authentication, money, personal data, file upload, or third-party input does not proceed without a threat model. A new table, event, or exported dataset does not proceed without a data contract.

Threat model where it earns its place. security-architect runs the threat-model skill on anything handling authentication, money, personal data, uploads, or third-party input. STRIDE per trust boundary, each threat with its mitigation and where that mitigation lives. A feature that touches none of those skips it and says so.

Data contract for anything another system will read. data-architect — or the owning database-architect — names the owner, the schema, the grain, the classification, the retention period, and the deprecation path before the first row exists. Retrofitting a contract onto a table that already has consumers is the expensive version of this work.

Run architects in parallel only when their concerns do not overlap. Where two disagree, do not average — state both positions and escalate to enterprise-architect.

Architecture leads, but it does not get the last word on the screen. Return the contract as a starting position with its cost, not as a wall: "one call with these fields, adding a field is cheap, realtime is expensive". Stage ③ designs inside it and pushes back when the user's flow genuinely needs more. A contract that was never questioned is usually one that was drawn against a guess.

③ Shape — Design Team

Agentsui-designer for any visible surface; add ux-researcher when the user's behaviour is disputed, interaction-designer for multi-step flows, content-designer for the strings, design-ops-engineer to say what the system already covers; design-qa-engineer closes the stage
NeedsStage ① and ② output verbatim — the contract and its limits — plus the design system and the existing screens in the same flow
ReturnsTwo to three mock files with paths, the recommended variant marked, flow and state spec, interface copy, and the list of new tokens or components required
GateA user-facing change with no mock does not proceed. A described layout is not a mock. design-qa-engineer must find no undrawn reachable case.

Skip this stage only when nothing visible changes, and say so.

Design inside the contract. Stage ② has already said what the system can return, how fast, and at what cost. Mocks are drawn against that, not against a blank page — which is what stops a beautiful screen that needs data nobody can produce.

When the contract does not fit the screen, go back — do not bend the screen. A mock that has to add four requests, poll, or hide a field to satisfy the contract is reporting a design flaw in ②. Send it back with the specific need: this list needs one call with these fields. Quietly working around the contract in ④ is the failure this ordering exists to prevent.

Where a mock needs a component the design system lacks, say so here. It is an input to ④, not something an engineer invents mid-build.

Interface copy is approved with the design, not after it. content-designer delivers the strings as part of this stage and they are reviewed here. Placeholder text that reaches ④ ships; every team has a screen with a "TODO: better wording" in production to prove it.

The test plan is written before the code, from the mock. quality-lead names, per case in the mock: what proves it works, at which layer, and what the failure input is. Written after the build, a test plan documents what the code happens to do rather than what the feature is supposed to do.

The design gets tested before anything is built. design-qa-engineer walks the mock set the way a user would and looks for the case nobody drew: the branch, the role, the limit, the empty and worst-case content, the state with no way out. Contrast, target size, focus order, and keyboard operability are checked here, on the mock, where fixing them costs an edit rather than a rebuild. A design is not ready because it looks finished; it is ready when every reachable case is drawn or explicitly ruled out of scope.

④ Build — owning engineering team

Agentsbackend-developer, frontend-engineer, mobile-engineer, data-engineer, platform-engineer… plus database-engineer for schema work
NeedsThe ADR and contract from ②, the chosen mock and its state spec from ③, acceptance criteria from ①
ReturnsImplementation, tests including failure paths, migrations, instrumentation
GateTests must cover the failure path, not only the happy path

⑤ Verify — Quality Engineering Team

Agentscode-reviewer always; add the specialist matching the change: api-quality-engineer, accessibility-qa-engineer, performance-test-engineer, security-test-engineer, data-quality-test-engineer
NeedsThe diff, the chosen mock, the ADR, the test results
ReturnsRanked findings — claim, evidence at file:line, impact, fix
GateUnresolved high-severity finding sends the work back to ④, not forward. A shipped screen that does not match the approved mock is a finding, not a detail.

⑥ Release — Release & Reliability Team

The pipeline does not end at "the code works". It ends at a release package the user can tag and push without doing further work.

Agentsproduction-readiness-engineer, release-manager; site-reliability-engineer when SLOs are touched
NeedsEverything above
GateRed test, missing owner, missing runbook, or a rollback nobody executed → no ship

A written rollback is not a rollback. Run it. Deploy the change to an environment that matters, roll it back, and confirm the system is serving correctly afterwards — including the data: a migration that cannot be reversed without loss must say so in the release package and carry the recovery procedure instead. Paste what you ran and what came back. The middle of an incident is where untested rollback procedures are discovered to be wrong.

Run the full suite yourself. Not the changed tests — the whole suite, plus lint and build. Paste the actual result. "Tests pass" without output is an assertion, not evidence. A test that was already failing before this change is reported as pre-existing, with proof.

The release package — every item, or say which is missing and why:

ItemContent
Test evidenceFull suite command and its real output. Failures quoted exactly.
VersionThe next version and which SemVer rule applies: breaking → major, additive → minor, fix → patch. Say which and why.
CHANGELOG entryAdded / Changed / Fixed / Security, written for a user, not a commit log
Release notesWhat changed, who is affected, what they must do
Migration stepsOrdered, reversible, with the command for each — or "none"
Rollout planCanary percentage, health metric watched, abort threshold
RollbackExact steps, and how to confirm it worked
OwnerA named person. No owner, no launch.
RunbookFor every new alert this change introduces

Then stop and hand over. Do not commit, tag, or push unless the user explicitly asks. Present the exact commands and let them run it:

git add -A
git commit -m "<type>: <summary>"
git tag -a vX.Y.Z -m "vX.Y.Z"
git push origin main --follow-tags

⑦ Observe — post-release verification

Passing tests in CI is evidence the code does what the author expected. It is not evidence the feature works for users. This stage closes that gap, and it is the one most often skipped.

Agentsqa for the smoke pass; user-acceptance-tester for the profile panel; site-reliability-engineer for error, latency, and saturation; product-manager to read ①'s metric; add web-ux-quality-engineer when a user-facing flow changed
NeedsThe deployed version, ①'s success metric and kill criterion, the rollout plan's abort threshold, the runbook
ReturnsSmoke result on the real environment, the health window observed with numbers, the metric measured against ①'s target, and the decision: continue, hold, or roll back
GateSmoke failure or a breached abort threshold rolls back immediately. Diagnose from the rolled-back state, never from the burning one.

Real people, not the team. user-acceptance-tester runs the released flow as a panel of concrete profiles spanning the age range and the sectors the product claims to serve, on their devices and their connections, with no instructions. The team cannot produce this evidence itself: everyone who built it knows where the button is. A finding is ranked by how many profiles failed, not by how surprising it was — one profile stuck is a case, every profile stuck is a design defect that ③ and ⑤ both missed.

Three checks, on three clocks. The smoke pass runs within minutes of the deploy and answers "is it alive": the critical path works end to end against real infrastructure, with real auth, real data, and the config that environment actually has — the class of failure no test double can catch. The panel runs in the days after, and answers "can a stranger do it". The metric read comes days or weeks later, on the window ① named, and answers "did it work". All three are this stage. Reporting only the first is the usual failure.

Watch what the change can break, not everything. Name the signals before the deploy: error rate on the touched endpoints, p99 on the changed path, the funnel step ① measured, and the resource the change consumes more of. A dashboard nobody named in advance is a dashboard nobody reads at 3am.

The kill criterion is real. ① named the condition under which this feature is withdrawn. If it is met, say so and withdraw it. A kill criterion that is quietly renegotiated once the work is done was never a criterion — it was a formality, and every later one is too.

A rollback or a failed smoke earns a post-mortem. Use the postmortem skill: timeline, what was believed at each point, why the gates let it through, and a regression test that would have caught it. Blameless, and written before the next release, not "when things calm down" — that moment does not arrive. The action items land in the pipeline as gate changes, not as a list nobody rereads.

Then close the loop. The measured result returns to ① as input: the metric moved and the next increment is scoped, it did not move and the problem statement was wrong, or the feature is withdrawn. This is what makes the pipeline a cycle rather than a queue.

Definition of done, per stage

A stage is done when its lead can show four things. Anything less is "in progress", however it feels.

ArtefactThe document, mock, code, or report the stage declares — existing as a file, at a path, not as a description in the chat
Gate verdictPASSED, FAILED, or SKIPPED, with the evidence behind it
Hand-offEverything the next stage needs, passed verbatim
Open itemsEach with an owner and a date, or the stage is not done

"Done" is never asserted by the person who did the work alone; the stage lead confirms it against the artefact.

Each team plans before it works

Every stage begins with its lead writing a short plan and ends against it. Not a document — four lines, before the specialists start:

StepsWhat will be done, in order
OwnerWhich agent does each step
EvidenceWhat will prove each step is done
RiskWhat could make this stage fail, and the earliest signal of it

A stage that ends differently from its plan says so and why. Planning that never survives contact is planning aimed at the wrong things — and the pattern is the useful finding.

Production ready, not demo ready

The pipeline's output is a feature that survives real use, not one that works when the person who built it drives it. Before ⑥, the owning lead confirms each of these or names it as knowingly missing, with the reason:

Failure pathsEvery external call has a timeout, a retry policy where retry is safe, and a defined behaviour when it fails
IdempotencyAnything that can be submitted twice — by a user double-tap, a retry, or a queue redelivery — is safe to submit twice
ValidationInput is validated at the boundary, allowlist first, and the error tells the user what to fix
AuthorisationChecked at the resource, not only the route, with a negative test proving denial
DataMigration is reversible or its recovery procedure is written; retention and deletion reach every copy
LimitsPagination, payload caps, and rate limits exist on anything a client can call in a loop
ObservabilityThe signals named in ④ are emitting, and an alert has a runbook
DegradationThe feature fails to a usable state, not a blank screen or a spinner that never resolves
SecretsNothing in code, logs, fixtures, or error messages
CostThe per-request cost is known and inside the budget ① set

A "yes" here means someone checked, with a file reference. A checklist filled in from memory is the artefact of a demo, not a product.

Who is accountable for a stage

Every stage has a lead who owns its result end to end — product-lead, architecture-lead, design-lead, the owning engineering lead, quality-lead, release-lead. The specialists produce the work; the lead is answerable for whether the stage's artefact is real, whether the gate was honestly assessed, and whether the hand-off carried everything the next stage needs.

OwnsThe stage artefact, the gate verdict, and the state of the hand-off
DecidesDisagreements inside the team, and what is sent back rather than shipped with a caveat
EscalatesTo it-director when two team leads cannot agree, always with a proposed decision
NeverReports a gate as passed on work whose evidence they have not seen

A backward step is reported by the lead who received the work, naming the stage it went back to and why. delivery-manager tracks the hand-offs between teams — the boundary is where work waits longest, and it is nobody's specialist job to notice.

Cross-team conflict that survives two attempts goes to it-director, who picks one position rather than averaging them, and states what would reverse the decision.

Going backwards

The arrows point both ways. A stage that cannot produce its artefact sends the work back to the stage that made it impossible — with the reason, never silently.

  ①  ←──────────  ②        architecture says the feature as scoped cannot be built
  DISCOVER        ARCHITECT   at acceptable cost, risk, or time

  ②  ←──────────  ③        design says the contract cannot carry the flow the user needs
  ARCHITECT       SHAPE

  ①  ←────────────────────  ②→③ deadlock: the contract that fits the design is too
  DISCOVER                    expensive, and the design that fits the contract fails ①'s metric

② back to ①. When the architects find the feature as scoped is too expensive, too risky, or blocked, product-manager re-opens it rather than the architects trimming it themselves. Product decides what is cut: a smaller segment, a later phase, a different mechanism, or the feature is dropped. Return to ② with the re-scoped problem and the metric restated — the metric may have to move too, and that is a product decision, not an engineering one.

③ back to ②. When design shows the contract cannot carry the flow — the screen needs one call and the contract gives four, or it needs a push and the contract polls — the architects revisit. They either widen the contract and say what it costs, or state why it cannot move. If it cannot move, ③ redesigns inside the real limit and says what the user loses.

③ back to ①. Design reaches the user before anyone else does, so it is the stage most likely to find that ① aimed at the wrong thing: research shows the drop-off has a different cause, or no mock can move the stated metric because the metric measures the wrong step. That is a product problem, not an architecture one — go straight to ①, do not route it through ②.

The bar is evidence, not preference. A named observation, a failed task in a usability session, or a metric the flow demonstrably cannot reach. "This would feel better as a wizard" is a stage ③ decision and stays inside ③; re-opening ① on taste burns the pipeline's credibility and everyone starts skipping gates.

Two bounces means the loop is wrong. If ② and ③ hand the same problem back and forth twice, the constraint is not technical — the scope is wrong. Escalate to ①. Product decides between paying for the expensive contract, accepting the weaker flow, or cutting the feature.

Every backward step is reported, with the stage, the reason, and what changed on the way forward. A hidden bounce turns into a rediscovered problem three stages later.

Skipping stages

The pipeline is a default, not a ritual. Skip deliberately and say so:

TaskStages
Typo, comment, formattingnone — do it inline
Bug fix, cause understood④ ⑤ ⑦ (smoke only)
Backend-only change, nothing visible② ④ ⑤ ⑥ ⑦
Feature inside an existing design③ ④ ⑤ ⑥ ⑦
New feature① ② ③ ④ ⑤ ⑥ ⑦
New system or vendor choice① ② ③ then stop for user approval before ④
Incidentnot this pipeline — use /incident

State which stages you skipped and why. A silent skip is the failure mode.

Worked example

"Users abandon checkout. Fix it."

① DISCOVER — product-manager
   Reads analytics. Returns:
     Problem: 39% abandon at the payment step, up from 22% in March.
     Segment: mobile users on slow networks — 81% of abandonment.
     Metric: checkout completion 61% → 70%.
     Non-goals: no redesign of the cart, no new payment providers.
     Kill criterion: no movement after two weeks at full rollout.

   ⛔ Gate passed: metric is measurable.

     ↓ this output is the literal input to ②, not a paraphrase

② ARCHITECT — backend-architect + frontend-architect (parallel, distinct concerns)
   backend-architect:  payment confirmation blocks on a synchronous 3rd-party call,
                       p99 11s, no timeout. Recommends async confirmation + idempotency keys.
                       Contract: POST returns immediately with a pending id; status arrives
                       on a poll or a push. Adding fields is cheap; sub-second confirm is not.
   frontend-architect: no optimistic state; the user sees a dead button for 11s.
                       Recommends immediate pending state + resumable session.
   → ADR docs/adr/0012-async-payment-confirmation.md

   ⛔ Gate passed: irreversible (changes the payment contract), ADR written.

③ SHAPE — ui-designer + interaction-designer
   ui-designer:         three mocks of the pending state the contract forces — inline
                        pending, full-page confirmation, resumable drawer. Recommends the
                        drawer: it survives a backgrounded mobile browser.
                        → design/mocks/checkout-pending-{a,b,c}.html
   interaction-designer: state spec — submit, pending, confirmed, timed out, resumed.
                        Input is preserved on every failure path.
                        Pushes back on one point: the poll interval leaves a 4s dead
                        window; asks ② for a push channel on this one event. Granted.

   ⛔ Gate passed: mocks exist, one is chosen, contract gap raised in ③ not patched in ④.

④ BUILD — backend-developer + frontend-engineer
   Idempotency table, async confirmation worker, pending UI state,
   tests: duplicate submit, timeout, network loss mid-confirm.

   ⛔ Gate passed: failure paths tested.

⑤ VERIFY — code-reviewer + api-quality-engineer + web-ux-quality-engineer
   HIGH  api.py:240 — retry has no jitter; a provider blip causes a thundering herd.
   MED   checkout.tsx:88 — pending state has no screen reader announcement.

   ⛔ Gate FAILED on HIGH → back to ④. Fixed, re-verified, then forward.

⑤ RELEASE — production-readiness-engineer, release-manager
   Test run:  pytest -q  →  418 passed, 2 skipped, 0 failed (94s)
              npm test   →  212 passed
              ruff check →  clean
   Version:   1.4.0 → 1.5.0  (minor: async confirmation is additive,
              the old sync path stays until 2.0)
   CHANGELOG: ### Added — async payment confirmation with idempotency keys
              ### Fixed — checkout no longer blocks for up to 11s on provider latency
   Migration: 1 forward-only, adds payment_idempotency. Online, ~0.4s on 12M rows.
   Rollout:   canary 5% → 25% → 100%.
              Abort if completion rate < 61% or worker lag > 60s.
   Rollback:  feature flag payment_async_confirm=false. Table stays; it is unused when off.
   Owner:     @payments-team · Runbook: docs/runbooks/confirmation-worker-lag.md

   ⛔ Gate passed. Release package handed to the user; nothing pushed.

Note stage ④ sending work backwards. That is the pipeline functioning, not failing.

Reporting

Report each stage as it completes — do not save everything for the end. Per stage:

### ① Discover — product-manager
<the artefact>
Gate: PASSED — metric is checkout completion 61% → 70%

At the end, one summary table: stage, agents, artefact, gate result.

Anti-patterns

Anti-patternWhat goes wrong
Running all seven stages on a typoEnormous cost, zero added correctness
Paraphrasing stage output into the next stageDetail loss compounds; stage ④ builds the wrong thing
Advancing past a failed gate "to save time"The gate existed because that failure is expensive later
Running every architect in parallelThey overlap, contradict, and you arbitrate with no basis
Building a screen with no mockThe design gets invented inside component code, then argued about in review
Skipping ① because the user sounded certain"Fix checkout" has no metric; without one, you cannot tell if you succeeded
Hiding a backwards stepStage ⑤ pushing back to ④ is the system working — show it
"All tests pass" with no outputUnverifiable. Paste the real result.
Stopping at "the code works"The user still has to figure out version, changelog, and rollback
Stopping at "it shipped"Green CI is not a working feature; nobody checked the real environment
Reporting the smoke pass as the outcome"Alive" is not "it worked". ①'s metric is the outcome.
Renegotiating the kill criterion after the buildIt was never a criterion, and the next one will not be either
Committing or tagging unaskedRelease is the user's decision, always

Done when

  • Every stage that ran named its agents and produced its declared artefact.
  • Every gate result is stated explicitly — PASSED, FAILED, or SKIPPED with a reason.
  • Each stage received the previous stage's output verbatim, not summarised.
  • Skipped stages are listed with the reason.
  • Backwards steps are reported, not hidden.
  • The full test suite was run and its real output shown — not summarised as "passing".
  • The release package is complete, or each missing item is named with a reason.
  • The version bump cites the SemVer rule that justifies it.
  • Post-deploy smoke ran against the real environment and its result is shown.
  • The signals to watch were named before the deploy, and the observed window is reported with numbers.
  • ①'s metric was measured on the window ① named, or the date it will be is stated.
  • The kill criterion was checked against reality, not renegotiated.
  • The spec was approved by the user before anything downstream started.
  • Each stage wrote its plan before starting and reported against it.
  • Threat model and data contract exist where the change required them, or their absence is justified.
  • Interface copy was approved with the design, not left as placeholder.
  • The test plan was written from the mock, before the code.
  • The rollback was executed, not just written, and the result pasted.
  • The production-ready checklist is answered with file references, not from memory.
  • A rollback or failed smoke produced a post-mortem with a regression test.
  • Nothing was committed, tagged, or pushed without the user asking.
  • The final summary table lets the user audit the whole chain.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.