Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Amby Run?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/ambystechcom-amby-run)
---
name: amby-run
description: "Run a feature's tasks as a team — workers build, QA and architect review, state kept in files, resumable."
---
<!-- GENERATED by AmbyKit from src/prompts/run.md — do not edit by hand; run `ambykit sync`. -->
Run the feature in `the user's request that followed this skill invocation` (number or name; `--new` only when the person asked for a new run). You are the
**lead**: you start workers, hand out task IDs, run the reviews and keep the run state. You have no role of
your own. Run `ambykit activity <feature> --agent=codex --phase=run` first; ignore any error.
Subagents on this host: `no`. If `yes`, workers are the `amby-worker` subagent and reviewers the
`amby-qa` and `amby-architect` subagents (roles `@.amby/roles/qa.md`, `@.amby/roles/architect.md`). If `no`,
say so once, then do each worker, QA and architect step yourself, in sequence, one task at a time, with the
same commands and state files below: claim, edit, check off, report; QA before architect, each acting as its
role file, and say which role you are acting as.
Every step works from files with these verbs alone, and nothing here needs a server: `ambykit fleet`,
`ambykit activity`, `ambykit directive`.
## 1. Resume or start
Run `ambykit fleet status <feature>`; it prints the run, the next phase, lanes, free slots and warnings.
- **Done** → say so and change nothing. **Stopped** naming `spec.md`, `plan.md` or `tasks.md` (missing, or the
spec still `draft`) → stop, name that artifact and the command that makes it.
- **No unfinished run** → `ambykit fleet start <feature>` (this invocation is the request; `--new` starts another
run on request only). **One** → resume it. **Several** → list them and ask which; never pick.
- **Warning: state missing or corrupt** → `ambykit fleet status <feature> --run=<id> --rebuild`, then go on.
Checked tasks in `tasks.md` stay checked, so nothing completed is repeated.
- Load by reference only: the current phase of `@specs/<feature>/tasks.md`, the plan sections and `US-#`/`FR-###`
its tasks cite, and `@specs/<feature>/tests.md` when it exists. Never whole artifacts.
## 2. Work the phase (stage `working`)
- Take the phase's open, unblocked tasks from `status`. Tasks are independent when their file ownership is
disjoint. If two tasks you want to run together own overlapping files, see **Overlap**.
- **Caps:** `status` shows free slots (default 3 workers, 2 per assistant type). Never start a worker without one.
- Per worker: `ambykit fleet update <feature> --worker-start=<lane> --assistant=<id> --tasks=T001,T002`
(`<lane>` is `lane-<phase>-<k>`, `<id>` the assistant the worker runs on, the same id as your `--agent`; it is refused
when no slot is free). Give the worker only: the feature, run,
lane, its task IDs, their file ownership and the artifacts by `@path`. It returns one line per task.
- Workers report on a fixed rule, which you must also keep. Report at the start of a task, at the end of a task, and whenever you are blocked or waiting. Never report on a timer and never report progress.
- When a worker finishes: `ambykit fleet update <feature> --worker-done=<lane>`.
- **Blocked:** the worker marks the task `⚠ BLOCKED: <reason>` and you continue with other unblocked tasks.
Blocked work is yours to resolve or give to the person; workers never ask each other.
- **Stalled:** `status` flags a lane with no report and no `tasks.md` change for the stall limit. Restart it with
`ambykit fleet update <feature> --restart=<lane>` and re-delegate its unchecked IDs. After the restart limit the
command pauses the lane and asks for a person: only they may approve moving it to another assistant or marking
its task BLOCKED.
- **Notes and claims:** workers claim files before editing (`ambykit fleet claim`), post one-line notes
(`ambykit fleet note`) and their claims are released when a task is checked off. A refused claim names the
owner; sort it out through the board and `status` warnings, not by editing the file.
## 3. QA (stage `qa`)
When every task of the phase is checked: `ambykit fleet update <feature> --stage=qa`. Ask QA (`@.amby/roles/qa.md`, read-only) to:
1. run the phase's `**Verify:**` line, and check the acceptance criteria of its stories; if `tests.md` exists, its
cases for these tasks are the expected tests. No Verify line → check the criteria only and say the phase has none.
2. return a verdict. You write it to `.amby/fleet/<run>/verdicts/<lane>.qa.<round>.json`
(`<round>` = failed rounds so far + 1): `{"verdict":"pass"|"fail","findings":[{"id","severity","finding","fix"}]}`.
3. record the result on the Verify line, per spec 020: `✓ passed`, `✗ failed: <why>`, or, when the check cannot be
run here, tell the person, ask them to confirm and record `? unverified`.
A failing Verify never passes the checkpoint. Do not tick the checkpoint or start the next phase until it passes.
## 4. Architect review (stage `architect`)
After QA passes: `ambykit fleet update <feature> --stage=architect`. Ask the architect (`@.amby/roles/architect.md`, read-only) for correctness,
simplification and fit with `plan.md`; findings by stable ID, same verdict file with `.architect.`.
- **Fail** (QA or architect): `ambykit fleet update <feature> --round=<failed rounds so far>`. It prints `retry` or
`escalate`. **retry** → return only the finding IDs and their `fix` to the **same worker** (same lane) and go back
to `working`. **escalate** (the round limit) → stop: summarize the open findings and ask the person to decide.
Record their answer with `ambykit fleet update <feature> --decision="<text>"` and continue from it.
- **Pass:** `ambykit fleet update <feature> --phase=<next>`; after the last phase,
`ambykit fleet update <feature> --done`, then suggest `/amby.converge`.
## Pause, resume, stop
When the person asks: `ambykit fleet update <feature> --pause` (or `--resume`, `--stop`; add `=<lane>` for one lane).
This writes a directive per lane; start no new worker while paused. The directive protocol is: The reply carries a directive: continue, pause or stop. On pause or stop, finish the task you are on, then obey it at your next report: do not start another task.
The run state records `paused`; the next `/amby.run` resumes from it.
## Overlap
If workers' files overlap, choose before any work starts and record it:
- **Serialize:** one worker after the other. `ambykit fleet update <feature> --overlap=serialized --lanes=a,b --order=a,b`
- **Squad:** one writer per shared file, a fixed merge order; others send change requests through the writer or you.
`ambykit fleet update <feature> --overlap=squad --lanes=a,b --shared=<path>,... --writer=<path>:<lane>,... --order=a,b`
## Rules
- All review roles, including `security`, stay read-only; never give them write access. Only workers write code.
- Keep every status line to one line; no logs, no restated artifacts.