Skip to content
Skills Library
Programming · Planning

dev-flow

/dev-flow

Start here before writing any code — sizes the task (XS/S/M/L/XL, bug, urgent `!`), sets up branch and session rules. Use when: "I'm starting on X", "quick fix for Y", "continuing from yesterday", "hotfix needed", "let's implement X", "skip to coding", "我要開始做 X", "快速修一下", "接續昨天的進度", resuming a feature branch, or any task that touches code. Not for: debugging (→ debug), authoring a plan doc (→ references/plan-template.md), pre-code design exploration (→ brainstorm), or code review (→ quality-pipeline).

Repository
autopilot ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Start here before writing any code — sizes the task (XS/S/M/L/XL, bug, urgent `!`), sets up branch and session rules. Use when: "I'm starting on X", "quick fix for Y", "continuing from yesterday", "hotfix needed", "let's implement X", "skip to coding", "我要開始做 X", "快速修一下", "接續昨天的進度", resuming a feature branch, or any task that touches code. Not for: debugging (→ debug), authoring a plan doc (→ references/plan-template.md), pre-code design exploration (→ brainstorm), or code review (→ quality-pipeline).

Triggers from the description

m starting on Xquick fix for Ycontinuing from yesterdayhotfix neededletskip to coding我要開始做 X快速修一下
Original author description

Start here before writing any code — sizes the task (XS/S/M/L/XL, bug, urgent `!`), sets up branch and session rules. Use when: "I'm starting on X", "quick fix for Y", "continuing from yesterday", "hotfix needed", "let's implement X", "skip to coding", "我要開始做 X", "快速修一下", "接續昨天的進度", resuming a feature branch, or any task that touches code. Not for: debugging (→ debug), authoring a plan doc (→ references/plan-template.md), pre-code design exploration (→ brainstorm), or code review (→ quality-pipeline).

How it works

  1. Project Config (auto-injected)
  2. Model Routing (for subagent dispatch)
  3. Dispatch Chains (for orchestrator routing)
  4. Session Start
  5. Stage protocol
  6. Nodes
  7. Session Rules (persist throughout)
  8. Skill Routing (project-specific)
  9. Completeness Principle
  10. Anti-patterns
Original SKILL.md headings · 521 lines, 5,276 words
SKILL.md preview
---
name: dev-flow
description: >
  Start here before writing any code — sizes the task (XS/S/M/L/XL, bug, urgent `!`), sets up branch and session rules.
  Use when: "I'm starting on X", "quick fix for Y", "continuing from yesterday", "hotfix needed",
  "let's implement X", "skip to coding", "我要開始做 X", "快速修一下", "接續昨天的進度",
  resuming a feature branch, or any task that touches code. Not for: debugging
  (→ debug), authoring a plan doc (→ references/plan-template.md), pre-code design
  exploration (→ brainstorm), or code review (→ quality-pipeline).
---

# Development Flow

## Project Config (auto-injected)
!`cat .claude/dev-flow-config.md 2>/dev/null || true`

## Model Routing (for subagent dispatch)
!`cat .claude/model-routing-config.md 2>/dev/null || true`

If no project config above, use defaults from [references/model-routing.md](references/model-routing.md).

## Dispatch Chains (for orchestrator routing)
!`cat .claude/dispatch-config.md 2>/dev/null || true`

If no project config above, autopilot's own fallback skills are primary for methodology; `native` Task dispatch for parallel; `autopilot:reviewer` for code review. See [project-config-template/dispatch-config.md](../../project-config-template/dispatch-config.md) for the schema.

---

## Session Start

Run before any code change. Steps 1 and 4 run at every size (bug, urgent included); step 1 precedes any research or
question, so every session has a marker. `references/stage-graph.json` alone defines which nodes run; this skill
says what to do inside each. Script contract and exits: [references/stage-graph.md](references/stage-graph.md).

```
1. Size the task (table below), then record it — the flags are separate, never `--size M!`:
   node scripts/session-mode.js set --size <XS|S|M|L|XL> [--urgent] [--bug]
2. Read your node sequence (never copy it from prose):
   node scripts/stage-graph.js nodes --size <size> [--bug] [--urgent]
3. Run the start gates (table below). M, L, XL also owe the Entry gates (§ intent) before the first `implement`.
4. Enter the first node: node scripts/stage-advance.js --to <entry from step 2>
```

**No human available** (headless `-p`, a just-results level `/l3`–`/l6`, CEO mode): never stop to ask. Wherever this
skill says ask, confirm, pick or "unsure ⇒ ask", take the recommended option (within DOA when one is set), record it
as a decision taken on the owner's behalf, and continue: `node scripts/decision-ledger.js append --kind decision
--json '{"decision_id":"<node>-<n>","class":"tactical","rationale":"<question → choice, why>","reversibility":"two-way"}'`
(the default ledger the status band counts as ◆; the owner vetoes with `decision-ledger.js veto --id`; ceo-agent
`references/depth0-control-loop.md` §6). Board-class stops stay stops: scope expansion, a DOA boundary, and the
User Override Protocol's cannot-be-overridden list.

### Sizing

| Size | Predicate — decide structure first (XL, then L); otherwise the smallest of XS, S, M that holds |
|------|-----------|
| **XL** | Several deliverables that are independent of each other and each shippable alone |
| **L** | One deliverable in multiple phases that build on each other, OR an open design question, a public API change, incompatible data, a feature flag, or the user asks for planning |
| **M** | One deliverable touching several modules or adding a module, design already clear; fits `stage-graph.js limits --size M` |
| **S** | One module, one commit, no interface change beyond an additive flag; fits `stage-graph.js limits --size S` |
| **XS** | One spot (a value, a message, one condition) plus the test that pins it; fits `stage-graph.js limits --size XS` |

| Modifier | Predicate | Flag |
|----------|-----------|------|
| bug | The task is to make existing wrong behavior right. Size it by the fix's footprint: a cause that spans several modules, or is not yet located among several, is at least M; module count alone never makes a bug L | `--bug` (entry node `diagnose`) |
| urgent | Production is broken, or the user says it must ship now / today / within hours | `--urgent` (written `S!` / `S急` in prose and backlog) |

- Pick the smaller size only when two sizes genuinely fit their predicates: the E1 bump (`stage-advance.js` exit 4)
  moves the size up when the diff outgrows it. L and XL are decided by structure, not by diff size.
- Urgency never lowers the size: the urgent "smallest change" is about the diff, not the size flag.
- Risk (money/points, auth/security, production protocol) does not change the size. It raises review strength:
  `scripts/resolve-review-loop.sh` reads it from `classify-diff-risk.sh` (`review_risk`).
- Size moves only up (`set --size` refuses a downward move). A resumed session never re-sizes.

### Start gates

| Gate | Sizes | How | Enforcer |
|------|-------|-----|----------|
| Confirm task | all | Restate what will be done in one sentence (bug: the symptom and, when known, the root cause) | documented-only |
| Branch check | all | `git branch --show-current`; bug ⇒ `git checkout -b fix/<description>`; production broken ⇒ `git checkout -b hotfix/<description> main` | documented-only |
| Skill routing | all | Project skills for the target code area (CLAUDE.md, `.claude/skill-routing.md`) are invoked before code is written; L/XL via the skill-routing TaskCreate at `intent` | TaskCreate + blockedBy (L/XL); documented-only (XS–M) |
| TaskCreate tools | all | TaskCreate missing from the tool list (Claude 5-era models are gated off by default since CC 2.1.233) ⇒ warn the user once to set `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` via `.claude/settings.json` `env` and continue — advisory, never a blocker (`references/multi-agent-portability.md`, task-persistence row) | documented-only |

Branch freshness:

| Behind | Ahead | Status | Action |
|--------|-------|--------|--------|
| 0 | any | Up to date with main | Proceed |
| 1-5 | any | Slightly behind | Proceed with note |
| >5 | 0 | Behind, no local work | Warn user, recommend merge |
| >5 | >0 | DIVERGED | Flag to user before proceeding |

### Context Continuation (Resuming Prior Work)

Resuming a feature branch with an active project → the 5-step procedure in
[references/context-continuation.md](references/context-continuation.md). The size is the original session's;
the walk resumes at the recorded node, never re-sized.

---

## Stage protocol

| Situation | Do |
|-----------|----|
| Calling `stage-advance` / `next` | One node per Bash call, output visible: no `>/dev/null`, no `\| head`/`tail`, no loop over nodes, no `&&`/`;` work chained after it. Read the exit code and JSON before the node's work. Write a node only when you start its work |
| The walk | Done only when `--to finish` exits 0. Every node `nodes` printed runs: a small diff, passing tests or a commit already made never skips one (only the User Override Protocol does) |
| Entering any node | `node scripts/stage-advance.js --to <node>` before its work. Rails write `plan-review`, `code-review` and (at /l5–/l6) `implement` themselves; every other node is yours. A skill you hand off to may write the same node again — a repeat write is a harmless same-node update, so write it anyway |
| Entering `implement` when `nodes` prints a non-null `unit_kind` | Add `--unit <unit_kind>:<i>/<N>:<label>` (`phase:` or `deliverable:`). Same `<i>` = repair of that unit; `<i>+1` = next unit; leaving the loop needs `<i> = <N>` |
| Choosing the next node | `node scripts/stage-graph.js next --from <stage> --size <size> [--bug] [--urgent] [--research]`. `implement` in that list is the repair / next-unit edge; otherwise take the forward node |
| Leaving the last `verify` of an urgent session | Not `next` (the risk is sampled only on this move): `stage-advance.js --to code-review`. Exit 0 ⇒ high risk, normal order. Exit 3 with `qc-gate` in `legal_next` ⇒ urgent-low: go to `qc-gate`; finish-flow runs the code-review after `finish` |
| Exit 3 | Illegal move: read `legal_next`, go to one of those. Never retry the refused `--to`, never force |
| Exit 4 | E1 bump: `session-mode.js set --size <bump_to>`, then advance to the forward node of `stage-graph.js next --from <current stage> --size <bump_to>`. Never retry the original `--to` |
| Exit 2 / 5 | No marker / no size: run Session Start step 1, then retry the same call |

`/l3`–`/l6` decide who implements and who authors verification; they never change which nodes run.

---

## Nodes

### intent

`node scripts/stage-advance.js --to intent`, then work the Entry gates; leave `intent` only when gates 1–7 pass.

**Entry gates** (M, L, XL): all must pass before the first `implement`; a blocked gate ⇒ surface to the
decision-maker. M runs 1–5 at `plan`; L/XL bugs run 1–7 at `diagnose`.

1. Session start SHA: `mkdir -p .claude && git rev-parse HEAD > .claude/session-start-sha`
2. Branch freshness: `git log HEAD..main --oneline | wc -l` (behind), `git log main..HEAD --oneline | wc -l`
   (ahead) → freshness table (Session Start); no `main` ⇒ skip
3. Knowledge: `.claude/knowledge/` for prior learnings; unprocessed session digests
4. In-progress projects: `docs/projects/INDEX.md` (or the configured path) — an active project for this work ⇒
   Context Continuation instead of a new walk
5. Draft plan overlap: `ls docs/plans/*.md` (or the configured path): same feature / module / user story ⇒
   normal mode asks the user whether to adopt the draft; CEO mode decides within DOA
6. (L, XL) Goal in the project README (below), both parent tasks created, Scope Completeness Audit done
7. (L, XL) Ladder probe run — always, even when nothing looks unknown; its `eligible_max` picks `research` or `proposal`
8. (L, XL) Plan file on disk before `plan-review` (§ plan)

Record the goal in the project README; CEO mode skips the confirmation (the OKR was confirmed at CEO startup).

```markdown
## Project Goal

> **Final goal**: [one sentence]
> **Success criteria**: [quantifiable conditions]
> **Scope boundary**: [explicit include/exclude]
```

Each success criterion carries (a) a measurable threshold — number, percentage, boolean state, or named command
output — AND (b) how it will be verified. A criterion without both = incomplete, do not proceed. Pick acceptance
patterns (ids + evidence incl. negative controls) from [acceptance-patterns.md](../../references/acceptance-patterns.md).

**Task tracking (MANDATORY at intent)**: create both parent tasks. Missing either = failed intent gate; if one is
found missing later, STOP, create it retroactively (skill routing: pause the current unit, invoke the missing
skills, resume).

```
TaskCreate: "Skill routing — invoke required skills for all affected code areas"
  description: MANDATORY before any implement node. Input: the module/surface list
  produced by the Scope Completeness Audit. For each affected area, consult project
  CLAUDE.md and/or .claude/skill-routing.md for required skills. Invoke each required
  skill via the Skill tool (reading the file is NOT invoking). Mark this task completed
  ONLY after:
    (a) every required skill has been invoked via Skill tool, AND
    (b) one-line summary of "what this skill told me for this task" is captured in
        session context (either a note or a TaskCreate subtask).
  If a module has no skill routing entry, mark N/A with a one-line justification.
  Unit implementation tasks MUST be created with blockedBy=[this task] so
  they cannot start until skill routing is confirmed done.

TaskCreate: "finish: Invoke autopilot:finish-flow"
  description: MANDATORY completion. At the finish node invoke autopilot:finish-flow,
  which expands into its size-keyed sub-tasks. Do not mark this completed until the
  skill has run and every sub-task reaches completed.
```

Rationale for both: [references/historical-rationale.md](references/historical-rationale.md).

#### Scope Completeness Audit (MANDATORY before phase TaskCreate)

```
TaskCreate: "Scope completeness audit — enumerate all affected surfaces"
  description: Before unit TaskCreate. Walk the dimensions checklist below.
  For each "yes" row, either add a unit task for it OR document in README
  scope boundary why it's explicitly out-of-scope. Do NOT mark this task
  completed without dimension-by-dimension coverage recorded in README.
```

| Dimension | Trigger |
|-----------|---------|
| Source code + tests | Almost always |
| User-facing docs (README, guides, help text) | Any user-visible behavior change |
| API / interface reference | Any public interface change |
| Config file templates / examples | Any new or changed config format |
| CHANGELOG entry | Any release-worthy change to a versioned artifact |
| Version bump (semver) | Any externally-visible change to a versioned artifact |
| Version sync verification (grep) | Any version bump — `grep` the old version string across **all tracked files** (no extension pre-filter); N hits ⇒ the edit list touches all N. Never enumerate the file list from memory |
| Migration guide / notes | Any breaking change or schema change |
| Dependent repos / external consumers | Any interface change with downstream consumers |
| Credit / attribution | Any feature absorbing external OSS, prior art, or third-party design — README's `Inspired By` / credits section lists the source(s) |
| Dogfood target | Any tooling/infra change (does it apply to itself?) |

- **User-stated requirements ledger**: list EVERY requirement the user stated (verbatim quote each) → map each to a
  unit/task. finish-flow's goal review checks every row. An accepted requirement that maps to nothing = audit FAILS.
- Every "Source code + tests" module found here is cross-referenced against `.claude/skill-routing.md` (or the
  project equivalent) — it is the skill-routing task's input.
- CEO mode: the CEO runs the audit and records coverage in the README; it does not ask the user to enumerate.

**Ladder probe** (Entry gate 7, at the end of `intent`; L/XL bugs at the end of `diagnose`): `node scripts/probe-unknown.js
classify --ledger <ledger> --work-unit <task-id> [--terms <terms>]`. Ledger: `<project>/ledger/decisions.jsonl`
(omitted ⇒ `~/.autopilot/ladder/<repo-hash>.jsonl`). Terms are the things the design depends on that you would have to
look up or verify before relying on them: unfamiliar libraries, internal modules you have not read, external services,
protocols or formats you are not certain about. A zero-hit term is novelty, so omit dependencies you can use confidently
from your own knowledge (standard library, mainstream platform APIs — they live outside the repo and miss by
construction) and never name what the task will create (a new command, flag, file or feature name). Nothing qualifies
⇒ run `classify` without `--terms`; expect `U0` → `proposal` unless another signal fires.

`eligible_max` picks the node; `recommend` only picks the rail inside `research`:

| `eligible_max` | Next |
|----------------|------|
| `U0` | No unknown: read the local hits it lists; propose from your own knowledge → `proposal` |
| `U1`–`U4` | An unknown exists, whatever `recommend` says → `research` (`--research` on `stage-graph.js next`); `recommend: none` there means the rung is skipped, not that nothing is unknown |

Sizes without a `research` node (XS–M bugs) work an unknown cause inside `diagnose` (`autopilot:debug` step 4).

### diagnose

`node scripts/stage-advance.js --to diagnose`, then invoke `autopilot:debug` unless the root cause is already known; either way, state the
root cause in one sentence before leaving the node. L/XL bugs also run Entry gates 1–7 (§ intent) here.

### research (when `classify` reports `eligible_max` above `U0`)

`node scripts/stage-advance.js --to research`, then act on `recommend` from the latest `classify`; re-run `classify` after each receipt until it says `U0` / `none`,
then advance to `proposal`. Budgets per work unit: U1 2 · U2 1 · U3 1 · U4 1 — a spent rung is never repeated.

| `recommend` | Rail, then receipt |
|-------------|--------------------|
| `U1` | `bash scripts/dispatch-consult.sh --question-file <q> --artifact <a> --ladder-receipt <ledger> --ladder-terms <terms> --ladder-unknown-type <unknown_type> --ladder-signals <ids> --ladder-work-unit <unit>` (writes its own receipt) |
| `U2` | `autopilot:survey` (`issue-search` mode for a `why` unknown), then `node scripts/probe-unknown.js receipt --ledger <ledger> --rung U2 --unknown-type <unknown_type> --terms <terms> --signals <ids> --work-unit <unit>` |
| `U3` | The `rail` classify names: `dispatch-discuss` (qualified discuss seat), else `autopilot:think-tank` (`whether`) / `autopilot:debugger` PUA (`why`); receipt `--rung U3 --rail <rail> --families <a,b>` (non-heterogeneous rail: add `--heterogeneous false`, no `--reason`) |
| `U4` | A spike in a throwaway worktree; receipt `--rung U4 --question <q> --criterion <c> --result pass\|fail\|inconclusive` |
| `none` (rung skipped, e.g. `not-heterogeneous`, or budget spent) | Research with local means (repo, docs, knowledge); record what stays assumed, then advance to `proposal`, which lists it |

An unknown still open once its rungs are spent or skipped is the research result, not a stop: it goes into
`proposal` as an assumption. U5 (owner) is never recommended: it is reached only by a board-class stop
(Session Start) or the stall fuse, carrying the ladder receipts — never by an unknown research could not close.

### proposal

`node scripts/stage-advance.js --to proposal`, then publish a web page (Artifact tool) with the assumptions (from research, or your own knowledge at U0) and 2–3
illustrated options, each with its trade-off and a recommendation; the user picks. Record the pick and the
assumptions in the plan. No Artifact tool ⇒ write the page as a local `.html` file and list the options in the
reply. No human available ⇒ take the recommended option and record it (Session Start), then continue to `plan`.

### plan

`node scripts/stage-advance.js --to plan`, then:

| Size | Plan |
|------|------|
| M | Entry gates 1–5 (§ intent) first. In-session: unit list (one task each), the verify command, acceptance |
| L, XL | User-provided plan ⇒ use it. Needs design ⇒ EnterPlanMode → design → ExitPlanMode → user approval. Write it to `docs/plans/YYYY-MM-DD-<feature-name>.md` per [references/plan-template.md](../../references/plan-template.md) and confirm it is on disk (`ls`) before `--to plan-review` — no code before it. Project setup is mandatory even with a user-provided plan: project directory, branch, project index (bootstrap commands per project config) |

**Consult before design (L, XL; the ladder's U1 at this call site)**: `node scripts/probe-unknown.js classify
--ledger <ledger> --work-unit <phase> --terms <dependency terms, as at intent>`; call `bash scripts/dispatch-consult.sh --question-file
<design-question> --artifact <plan-draft> --ladder-receipt <ledger> --ladder-terms <terms> --ladder-unknown-type
<unknown_type> --ladder-signals <ids> --ladder-work-unit <phase>` **only on `recommend: U1`**. Any other
`recommend` follows the research table; a skipped U1 (`not-heterogeneous`, `consult_dispatch: off`) never invokes
`dispatch-consult.sh`. From here on the work unit is the phase id. Rail details:
[references/hetero-loops.md#consult-before-design](references/hetero-loops.md#consult-before-design).

L/XL unit tasks are created with `blockedBy=[Skill routing]` (Mission routing: one per admitted graph node).

### plan-review (the rail writes the stage)

Invoke `autopilot:hetero-review` with the plan file (plan loop). Gate: a frozen rubric plus `node
scripts/check-phase-review-receipt.js --plan-artifact <file> --dispositions <file>` exiting 0, or a valid opt-out
receipt when the `plan_review` knob resolves to off. Enforcer: `scripts/check-phase-review-receipt.js`
([references/hetero-loops.md#plan-review-gate--frozen-rubrics](references/hetero-loops.md#plan-review-gate--frozen-rubrics)).

### implement

`node scripts/stage-advance.js --to implement [--unit <unit_kind>:<i>/<N>:<label>]` (at /l5–/l6 the engine
writes it). Before the first implement, answer the verification contract (驗證合約, below). Before each unit
(M, L, XL):

1. Does this change move us closer to the **final goal**?
2. Is this unit essential — would skipping it prevent the final goal?
3. Does my understanding match the user's stated goal?

Any "no" or "unsure" = blocked; surface to the decision-maker. CEO mode answers them itself and escalates to the
Board only when the answer is "no" AND the response is a strategic pivot (goal change, scope expansion).

| Drift signal | Response |
|--------------|----------|
| "This unit has low ROI, skip it" | STOP — does it affect the final goal? |
| "We can do this later" | STOP — any hidden dependencies? |
| "Project is basically done" | STOP — has the final goal been achieved? |
| "User probably just wants..." | STOP — ask and confirm directly |

Continuous execution: proceed between units without asking "continue?". Stop only for: staging gate, build/test
failure, a design decision, context near limit.

### verify

`node scripts/stage-advance.js --to verify` (exit 4 = E1 bump). Each unit is verified by a qualified verifier: a seat `node scripts/engine-scorecard.js current --role verifier`
reports qualified (at /l6 the verification-author dispatch; in a campaign the engine's per-deliverable review). It
reads artifacts only (`references/blind-dispatch.md` § Verifier isolation). No qualified seat ⇒ the
`on_engine_unavailable` policy from `scripts/resolve-review-loop.sh`, never a silent skip.

**驗證合約(必答)** —「這個任務做完,跑什麼命令能客觀證明?」

| 答案 | 機械判定 | 路由 |
|------|---------|------|
| 命令,且通過**紅綠驗證** | 見下方紅綠語意 | 紅綠通過 ⇒ **驗證錨定恆成立**(ratchet + 一輪 advisory review)。review 降為**非 gating** 需三條件**同時**:紅綠通過 **且** implementer scorecard-qualified(`engine-scorecard.js` status=qualified,由 `engine-qualify.sh` 的 known-bad 零漏放 bar 產生)**且** risk=low |
| 命令,但未過紅綠(vacuous)或紅無法成立 | 自動降級 | 同「無驗證」列 |
| 「沒有客觀驗證」(合法誠實答案) | 記入 run summary | **審查 gating 常駐**,不分模型強弱(模型強只降輪數 ≤2,不降為零);優先派工具可執行的原生 reviewer,而非 diff-text 軌 |

紅綠語意:
- base = dispatcher 釘死的 immutable base SHA(engine `--base`;dev-flow inline = marker `base_ref`);dirty tree 不是 base。
- base-run = base 的產品碼 + diff 中的驗證 artifact 套上去跑,避免純新增 TDD artifact 被誤降級。
- 紅的資格 = assertion/行為失敗;基礎設施錯誤(檔案不存在、import error、collect 0)不算紅。
- 紅必須可重現(flaky base-fail 重跑一次確認;不可重現 → 降級)。

Engine wiring: the answer flows to `engine implement-review --verify-cmd`; non-gating only per the conjunction,
else keep `--no-verify-first`. Campaign identity requires `engine implement-review --campaign-contract
<campaign.json>`, which owns the durable ledger/resume. verify-cmd is dispatcher-authored, isolated-worktree,
read-only expectation.

**Unit advance gate** (M, L, XL) — TaskCreate these five as discrete sub-tasks of the unit task, named verbatim:

- [ ] Goal check: all three verification questions answered "yes"
- [ ] Tests pass: zero failures
- [ ] Completeness scan: `bash scripts/completeness-scan.sh` — no placeholder markers or stub implementations
- [ ] Verifier verdict: the qualified verifier passed this unit (artifacts, not the implementer's report)
- [ ] Project docs: progress row updated to reflect unit completion

Then commit the unit. CEO mode verifies the gate itself; no user confirmation for passing gates.

**Backlog safety** (before deferring anything): affects the final goal ⇒ do NOT defer; goal unreachable without
it ⇒ do NOT defer; unsure ⇒ ask the user. A passing deferral = one backlog row per
[`references/backlog-entry.md`](../../references/backlog-entry.md), evidence at the pointer, unit marked "Deferred".

**Scope expansion** (L, XL — after every unit): new subsystem not in the README, larger public API, estimate
doubled, or requirements beyond the OKR ⇒ STOP. Board decision (user; CEO escalates): update the README scope
boundary first, proceed only after explicit approval, record it in the project decision log.

**Leaving the last unit of an urgent session**: `--to code-review`, never `next` (Stage protocol row).

### code-review (the rail writes the stage)

After all units, invoke `autopilot:hetero-review` (code loop) on the full diff, `--phase full --phase-base
<base_ref>`. Strength = the distinct model families `bash scripts/resolve-review-loop.sh --field
required_review_families` resolves from risk and roster — low risk defaults to one family with a fresh-context
reviewer; a shortfall goes through `on_engine_unavailable`, never silently lowered. Gate: `node
scripts/check-phase-review-receipt.js --ledger <ledger> --phase full --branch <b> --phase-base "$(cat
<ledger>/phase-full.base)"` exits 0 (SHIP-AS-IS chain or explicit opt-out). `FIX-THEN-SHIP` ⇒ back to `implement`
(not on the urgent-low path, where each finding opens a new `S` task instead).

### qc-gate

`node scripts/stage-advance.js --to qc-gate` (exit 4 = E1 bump), then:

| Size | Gate |
|------|------|
| XS, S | Project-config gate (default: lint + test); risk flags (money, auth/security, production protocol) ⇒ `autopilot:quality-pipeline` instead. Before committing, check no feature was added beyond the original goal — if one was, stop and ask |
| M, L, XL | `autopilot:quality-pipeline` (per-size flags from project config), at most 3 fix-review rounds; requires a valid code-review receipt (urgent-low excepted) and, for L/XL, the plan-review receipt |

A failure loops back to `implement`. XS/S commit after the gate (bug: message states root cause + what was wrong +
how it is fixed).

### finish

`node scripts/stage-advance.js --to finish`, then invoke `autopilot:finish-flow`; it owns the size-keyed closing checklist (merge, archive,
session end, the urgent-low code-review). Never inline it, never mark the parent task done while its sub-tasks are
pending. CEO mode: every finish sub-task is within DOA — execute all, then report.

---

## Session Rules (persist throughout)

These apply to all subsequent work in this session, whichever skills are invoked.

| Activity | Read first (if it exists) | Contains |
|----------|---------------------------|----------|
| Debugging | `.claude/debug-config.md` | Debug tools, Docker commands, known gotchas |
| Writing or running tests | `.claude/test-strategy-config.md` | Framework, commands, coverage thresholds |
| Parallel task dispatch | `.claude/team-config.md` | Role templates, tech stack, team size |
| Performance profiling | `.claude/profiling-config.md` | Profiling tools, baseline commands |
| Comparison audit | `.claude/audit-config.md` | By-design divergences, audit scope |
| Methodology / reviewer / parallel routing | `.claude/dispatch-config.md` | Preference chains (also injected above) |

### Background Wait Rule

A turn must NEVER end waiting only on a background-task notification: Claude Code delivers subagent completion
notifications best-effort and drops them in practice (2026-09-02: 29 of 63 never arrived).

| Expected wait | Do this |
|---------------|---------|
| ≤ 15 min | Foreground `Bash` with an explicit `timeout`, or the `Monitor` tool. Not `run_in_background`. |
| > 15 min | `run_in_background` ONLY with both: the leaf's output path written down in the same turn, AND a second background dead-man timer (`sleep <deadline>; echo WAKE`). |

An orchestrator handing off a long unit starts its dead-man timer before ending the turn. Foremen under
`/l4`–`/l6` keep their stricter no-polling clause: the dead-man timer is itself a background task — never
foreground `sleep`, never `Monitor`.

### Urgent

- Smallest possible diff, fastest path to stable; the size stays what Sizing says. A DB migration ⇒ STOP:
  `session-mode.js set --size L`.
- Production broken ⇒ the `hotfix/` branch from `main`; finish-flow merges back to `main` and makes the
  post-incident `autopilot:learn` mandatory. Rollback: invoke finish-flow once the rollback is verified stable.

### Staging Gate

Trigger: a unit awaits user review, or the session ends with undeployed committed changes. Deploy per project
config (default: build + restart).

### Session End Rule

Work finished ⇒ the `finish` node. Session ends mid-work ⇒ `autopilot:handoff`; record knowledge if something was
surprising or took more than one retry (`autopilot:learn`). Long or degraded session ⇒
[Context Health Check](references/hetero-loops.md#context-health-check-reference). After code changes, the
doc-sync mapping in [references/post-feature-doc-sync.md](references/post-feature-doc-sync.md) applies (skip for bug
fixes, value tweaks, log messages).

---

## Skill Routing (project-specific)
!`cat .claude/skill-routing.md 2>/dev/null || true`

## Completeness Principle

Complete (all edge cases, full test coverage, proper error handling) beats shortcut (happy path only) — always
choose complete, for tests, error handling, edge cases, docs and features alike.

## Anti-patterns

| Wrong | Correct |
|-------|---------|
| `--size M!` or `!M` | `--size M --urgent`; `!` is written after the letter in prose only |
| Copying a node sequence into a plan or prompt | Cite `stage-graph.js nodes`; the JSON is the only definition |
| Retrying the refused `--to` after exit 3 or 4 | Exit 3: a `legal_next` node. Exit 4: bump, then `next` from the current stage |
| `for n in …; do stage-advance --to $n`, `--to <node> >/dev/null && <work>` | One call per node, its output read before the work (Stage protocol) |
| Skipping `verify`, `code-review` or `finish` because the change is small or already committed | The size chose the nodes; the walk ends at `finish` |
| Searching or researching before `session-mode.js set` | Session Start step 1 comes first |
| Stopping because research found no answer | Record the open unknown as an assumption and advance to `proposal` |
| Leaving `intent` without the ladder probe "because nothing is unknown" | Run `classify` anyway (Entry gate 7); its `U0` is the answer |
| Reading `recommend: none` as "no unknown" and skipping `research` | `eligible_max` above `U0` ⇒ `research`; `none` only says the rung is skipped |
| A delegated commit task that says only "commit changes" | It names the gate that runs before the commit |
| Sizing a bug L because it crosses 3 modules, or S while its cause is unlocated across several | Size the fix's footprint: a cause across several modules is at least M; L only for design / multi-phase work |
| `--terms` naming what the task will create, or a dependency you can use from your own knowledge | Terms are only what you would look up first; both miss the repo by construction and fake novelty |
| Raising the size for a risky change | Risk raises review strength, not size |
| Ask "continue?" after a unit | Proceed directly to the next unit |
| Re-sizing on context continuation | Use the marker's size; only the E1 bump moves it |
| Skipping the skill-routing or finish parent TaskCreate "because I remember" | The task IS the forcing function — memory is what keeps failing |
| Reading a skill file instead of invoking it | Read ≠ invoke: the Skill tool loads it and records the decision |
| Unit tasks without `blockedBy=[Skill routing]` | The dependency is the mechanical enforcement |
| Enumerating units before the Scope Completeness Audit | The audit decides which units exist |
| Inlining finish-flow steps or batching its sub-tasks | Invoke finish-flow; each sub-task is its own TaskCreate |
| Scope expansion without Board approval | Doubled estimate or new subsystem = Board decision, never CEO-tactical |
| Defer work that affects the final goal | Never defer goal-critical items |
| Force knowledge extraction when nothing happened | Skip — do not force it |
| Auto-execute context reduction without confirmation | List the operations with numbered choices |

## User Override Protocol

User may request skipping process steps. When overridden:
1. State which check is skipped and the associated risk
2. Log `[OVERRIDE: skipped {step}]` in commit message
3. Comply -- user has final authority

**Cannot be overridden** (explain why and suggest alternatives):
- Migration integrity check (data corruption risk)
- SQL injection / security validation
- Completeness scan on new handlers/routes (invisible data loss)
- Code review Critical-severity findings (security/correctness)

## Capability-adaptive compatibility

This skill remains the canonical guided compatibility path. When a verified profile session is
active, the host retains the full task graph, checklist, completed history, and future slices, then
sends the worker only the current six-field active slice plus its matching envelope and role grant.
A late profile/grant change requires a fresh-session handoff and never edits the project default.
The `profile-session.js` lane is a no-effect isolation probe, not an effectful handoff gate;
rehashable artifacts, same-process observations, and caller-authored traces cannot qualify one.

## Mission Routing Override

When project governance configures `mission_convergence`, this section overrides every unit-enumeration rule above.

Before any TaskCreate, branch, worktree, runner, or model effect:

```bash
node <autopilot-source>/scripts/mission-routing-admission.js \
  --repo-root "$(git rev-parse --show-toplevel)" --level <l3|l4|l5|l6>
```

- `READY` is the only enforce-mode admission. Create one implementation TaskCreate per admitted
  graph node, plus the parent forcing-function tasks.
- `SHADOW` is observation only. Record `admitted`/`would_block` honestly and continue through the
  unit workflow without claiming an enforced receipt or grant.
- `LEGACY` means project Mission policy is off.
- Source `Phase`/`P0..PN` headings, modules, reviewer seats, tests, retries, repairs, and fallbacks
  remain coverage or gates inside a caller-authored bounded deliverable. They never become tasks
  one-for-one.
- In `READY`, every unit above means an admitted graph node, and instructions to extract units from
  source headings are disabled. Admitted implementation tasks remain blocked by the skill-routing task.
- Topology fallback reuses the same admission and owning gate-attempt budget; it does not create a
  second graph or reset authority.
- The project README keeps historical completed phases in a non-executable ledger and reports only
  current admitted deliverables as executable work.
- **Resume projection**: on resume, Mission nodes are remaining deliverables only — see
  [references/context-continuation.md](references/context-continuation.md#resume-projection-mission).

## Available Scripts

| Script | Purpose |
|---|---|
| `scripts/session-mode.js` | `set --size <XS\|S\|M\|L\|XL> [--urgent] [--bug]` creates or merges the session marker (size moves only up); `status` prints it. Session Start step 1. |
| `scripts/stage-graph.js` | Queries the canonical graph: `nodes`, `next --from`, `limits`, `validate`. Read the sequence and the next node here, never from prose. |
| `scripts/stage-advance.js` | Records entry into a node; refuses illegal moves (exit 3, `legal_next`) and requests the E1 size bump (exit 4, `bump_to`). Called on entering every prose-written node. |
| `scripts/check-stage-vocab.js` | Finds old stage ids, old size names and removed marker fields in shipped text; `--repo <consumer>` lists stale lines in a consumer's `.claude/*.md` and backlog with their replacement. |
| `scripts/mission-routing-admission.js` | Resolve project Mission policy and admit the authoritative bounded graph/source coverage before L/XL TaskCreate or execution topology effects. |
| `scripts/mission-execution-graph-check.js` | Validate graph limits, exact source/rubric coverage, critical path, batches, gate attempts, aggregate reservations, and ICC campaign projection bounds. In a repo with a codex mirror, pass `--mirror-roots <(scripts/sync-codex-plugin-skills.sh --mirror-roots-json)` so an `output_paths` entry under a mirrored dir must name its mirror too. |
| `scripts/plan-rubric-scaffold.js` | Generate structured rubric markdown skeletons from an input plan document for frozen review rubrics. |
| `scripts/hetero-review-loop.js` | Drive multi-seat review collection, disposition aggregation, verdict synthesis, and opt-out receipts for review loops. |
| `scripts/check-phase-review-receipt.js` | Validate review receipts against git history and review artifacts or validate plan artifact blocker dispositions. |
| `scripts/probe-unknown.js` | Unknown-escalation ladder probe: `classify` turns refuted hypotheses / loop non-convergence / stall / zero-hit terms / low consensus into one rung recommendation on the U0–U5 ladder (classify never emits U5 — the owner rung is reached only by the caller's own stop); `receipt` appends the ladder row after a rail returns. Call sites: `intent` / `diagnose` and the `plan` consult (this skill), debug step 4, think-tank Step 5, foreman round end. |
Files in this package (7)
  • SKILL.md 37 KB
  • references/context-continuation.md 2 KB
  • references/hetero-loops.md 8 KB
  • references/historical-rationale.md 3 KB
  • references/model-routing.md 9 KB
  • references/post-feature-doc-sync.md 1 KB
  • references/stage-graph.md 5 KB

Versions

RepositoryScoreLicence
This page · cookys/autopilot90MIT
cookys/autopilot100MIT
lukedj78/dev-flow100MIT
vakovalskii/ontoship100MIT
cookys/autopilot95MIT
cookys/autopilot95MIT
cookys/autopilot95MIT
cookys/autopilot95MIT
cookys/autopilot95MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 2db93d428db7 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90start-work
    Use when someone wants to work on something in claude-session-restore ("let's do #12", "pick up the restore bug", "make it work on macOS", "fix Y"), before any code or docs change. Finds or creates the issue, reads the code and the APIs it touches, decides whether it needs a…
  • 95tl-hotfix
    Emergency hotfix to main: stash/cherry-pick changes, create hotfix branch from main, validate, open PR with auto-merge, restore source branch. Use when: critical production bug, urgent fix to main, hotfix, or the user says "/nacl:tl-hotfix".
  • 95nacl-tl-hotfix
    Emergency hotfix to main: stash/cherry-pick changes, create hotfix branch from main, validate, open PR with auto-merge, restore source branch. Use when: critical production bug, urgent fix to main, hotfix, or the user says "/nacl-tl-hotfix".
  • 90dev-protocol
    Use when starting substantive development work — a code change, refactor, bug fix, infra change, or multi-step debugging task in any repo. Load BEFORE writing code: it is the fleet development protocol (orient/ground, clarify vs proceed, design-align on larger tasks, the…
  • 84run
    Run a task through AI flow with the user at every step. Analyze the code and ask the user, plan and have the plan approved, build test-first, review with a fresh agent, test, fix what fails, commit what the user approves and write a summary, all on a new branch. Use when the…
  • 90hotfix
    Fast-track fix pipeline for production incidents. Skips worktree isolation and planning ceremony. Still requires code-reviewer and merge-reviewer as a safety gate. Use only when the root cause is already known and the fix is well-understood. Trigger this when someone says:…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.