Huruikagi/pc-build-planner / .agents/skills/sb-plan
sb-plan
VerifiedPlan active Spec work through Requirements, Design, Contract Review, and Tasks, run one explicitly requested planning phase for one named Spec, or prepare explicitly scoped project shared Contracts. Ordinary Spec planning uses one named Spec or explicit all-Spec scope.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.6 KB |
| agents/openai.yaml | config | 195 B |
| references/complete-route.md | markdown | 19.6 KB |
| references/design.md | markdown | 30.2 KB |
| references/replan.md | markdown | 6.5 KB |
| references/requirements.md | markdown | 19.9 KB |
| references/shared-contract.md | markdown | 3.6 KB |
| references/tasks.md | markdown | 17.9 KB |
references/tasks.md
View on GitHub# Tasks phase
Selected `_Retired_` Requirement IDs are retirement work, not promises to
reimplement. Use the existing `requirement_ids` fields to cover their explained
continuation or cessation. Define evidence for preserved obligations, removed
behavior and affected consumers as applicable. Prose-only consolidation needs
preservation and reference checks, not invented product code changes.
## Apply project language style
Before authoring any artifact or user-facing prose, read this once unless this
receiver already read it for the current `sb-plan` run:
```sh
specbind rule read language-style --for consume
```
Apply returned policy only to natural-language prose. `NO_CHANGE RULE_ABSENT`
means no additional project preference; any `ERROR` line stops the workflow.
This is the complete Tasks procedure selected by `sb-plan`. Read it only
for a Tasks phase, whether the parent is running the complete planning workflow
or the maintainer explicitly requested this phase alone.
Turn the approved design into `tasks.yaml`: the ordered plan an implementer
executes and the CLI derives progress from.
You author one file and approve one gate. You never record progress against it —
that belongs to implementation.
## 1. Check the order before anything else
```sh
specbind spec status <spec>
specbind milestone review status
```
**The contract review must be accepted before a new or revised plan can receive
Tasks approval.** Proceed with authorship only on `Status: fresh`.
From the `tasks` state onward `spec status` also reports `Contract review:`, so
use it as corroborating Spec-local context. `milestone review status` remains
the authoritative focused check and is always required before first authoring.
On `absent` or `stale`, author nothing and route the user to
`sb-contract-review`. A retained `tasks.yaml` is not a review input and does not
need deletion. Leave its plan and execution records unchanged until the review
is fresh, then return here for the owned repair.
This check covers both first authoring and revision after an upstream rewind. A
plan that already exists after a Tasks-only invalidation keeps the accepted
review. A plan retained after a Requirements or Design rewind waits unchanged
while the milestone review is renewed, then re-enters this procedure as repair
input.
### Then check the prerequisite gate
`spec status` must report the design gate approved and fresh, and the Spec a
current participant of the active milestone.
If it does not, stop and say so. Route the user to `sb-plan` in explicit
Design-phase mode. Never
approve or invalidate an upstream gate, and never edit the requirements, design,
or contract to make a plan work.
## 2. Read
```sh
specbind artifact read <spec> design/main --for consume
specbind artifact read <spec> requirements --for consume
specbind artifact read <spec> contract --for consume
```
Use `specbind artifact list <spec>` first when the Spec's design is split across
several documents, and read all of them.
The design is your primary input — the plan decomposes it. The requirements give
you the active IDs the plan must deliver. The contract gives you the entry
references a task may name.
### Read the schema, do not recall it
```sh
specbind schema read tasks/v1
```
Tasks has no template. The schema **is** the structure, and it is strict:
unknown fields and empty arrays fail. Writing from a
remembered shape means debugging validation errors against a document you could
have read first.
### Steering is not read here
This is the one authoring phase that does not read steering. Requirements and
design each read it whole and wrote what they took from it into their own
documents, so the constraints are already carried by the artifacts you are
decomposing. Reading it again invites the plan to introduce an obligation no
approved artifact contains, and nothing downstream checks the plan against
steering.
If you find you cannot write the plan without consulting steering, that is a
finding about the **design**: it does not yet determine the work. Report it and
return to design rather than patching around it.
Read the project's task-planning preferences through its rule surface:
```text
specbind rule read tasks-generation --for consume
```
This shared rule, not steering, states task sizing, decomposition order,
test-work convention, and known conflict areas. `NO_CHANGE RULE_ABSENT` means no
customization; the protocol still applies. Any `ERROR` line stops planning.
## 3. Write the plan
```sh
specbind protocol read task-planning
```
The protocol owns the judgment: coverage is delivery rather than mapping, every
task is work that will be done, and order carries the dependencies.
Write `tasks.yaml` at the Spec's directory. A few things the schema enforces and
the protocol assumes:
- Task IDs are **positional** — `1`, `2`, `1.1`, `1.2` — and match array
position. There are no gaps and no third level.
- A group holds at least two tasks and carries no requirement, boundary, or
completion fields of its own.
- `requirement_ids` is required on every executable task and non-empty.
- Omit `details`, `completion_criteria`, `boundaries`, `contracts`, and
`depends_on` rather than writing them empty.
- `depends_on` names only tasks in this same file. A cross-spec dependency is a
roadmap or contract edge, never a Task ID.
For a new plan, do not write `execution`. That state belongs to implementation,
and a new plan that arrives claiming completed work records a judgment nobody
made. When revising a retained plan, follow the explicit mapping rules below;
they preserve only execution judgments that already existed and still apply.
### The YAML itself has traps
**Quote any string containing `: `.** In YAML, `Reject the addition: leave the
cart unchanged` is a *mapping*, not a sentence — and the failure surfaces as a
schema error about a field you never wrote, several lines from the real cause.
Task titles and `details` entries are where this bites. A `#` after a space
starts a comment, so quote those too.
The YAML SpecBind reads is deliberately restricted. **No anchors, aliases, merge
keys, custom tags, or multiple documents** — all are rejected outright. Write the
value out rather than reaching for a YAML feature to share it.
When `tasks list` reports something you cannot place, suspect the quoting before
suspecting the schema. Do not install a YAML or JSON-Schema tool to investigate:
the CLI is the validator, its diagnostics carry the line, and reaching outside
the project for a second opinion changes the machine rather than the plan.
## 4. Verify what you wrote
After **every** write:
```sh
specbind tasks list <spec>
specbind check traceability <spec>
```
The first proves the document parses, satisfies the strict schema, and produces
a coherent derived model. The second proves every active requirement ID is
mapped to an executable task.
Both are read-only. Run them before you present anything, so a structural fault
is something you fixed rather than something the approval refused.
Then perform the execution-readiness audit the schema cannot perform. For every
task, identify the checks that apply when that task finishes and require one of
these to be true:
- the verification command or test interface already exists,
- this same task creates or updates it together with the behavior, or
- an earlier task establishes it before this task becomes actionable.
A later test task does not make an earlier behavior task verifiable. In
particular, when the project names a canonical test command that is currently
absent, do not approve a plan that implements behavior first and creates that
command later. Combine the behavior and its tests, or place genuine test
scaffolding first, then rerun both CLI checks.
For each completion check, also establish what it proves, the input or state it
needs, how that will be supplied, and whether it is available when the task
finishes. Inspect relevant existing checks or fixtures rather than assuming a
named command can produce the required state. No separate inventory is needed.
Compare these checks with the approved Design's verification obligations before
presenting the plan as ready. Do not silently omit a stronger Design condition
or replace required real-connection proof with boundary tests. Report that
mismatch even when the draft passes the CLI checks; correcting it belongs to
Design before this plan can be approved.
Only when another Spec supplies a prerequisite, read its relevant Contract and
Design and compare availability with `specbind milestone scope`. Read that
Spec's Tasks only if they exist and their detail is needed. This targeted read
does not authorize editing that Spec or require an audit of every Spec's Tasks.
The Roadmap read checks execution order; it does not reopen product Steering.
Distinguish boundary input that proves this task's responsibility from a later
integration check of the real connection. Prefer an existing input path or a
small test helper when sufficient; do not require a new public API, injection
layer, or permanent abstraction solely to make Specs independently finishable.
Correct the completion condition, verification placement, or work order within
the approved scope, then rerun both CLI checks. Do not defer proof of this task's
own responsibility or silently assign work to another Spec. If the correction
requires changing Design, Contract, Roadmap, or another Spec's plan, report the
concrete prerequisite and ordering mismatch, route to its owner, and stop this
plan's approval. Existing approval and invalidation rules still apply.
## 5. Revising a retained plan or a plan that has recorded progress
If the Spec is in `implementation`, tasks may already be completed or blocked,
and this is where a plan revision can destroy information silently.
Identity is positional. Inserting, removing, or reordering renumbers every task
after that point, and `execution.tasks` is keyed by those same identifiers. Get
this wrong and the document still validates: `tasks list` shows a plausible mix
of completed and pending, while a completed record now sits on work nobody did.
So:
- Rewrite the `execution.tasks` keys in the **same edit** that renumbers the
plan. Never leave the two disagreeing.
- **State the before-and-after mapping** for every renumbered task that has a
persisted entry, and get confirmation before writing unless explicit Drive
replan authority covers it. In that recovery, report the mapping and proceed.
Preserve a completed record only when its obligation and evidence still
apply; changed work must return to implementation for fresh proof.
- Prefer a revision that leaves completed tasks where they are — appending, or
splitting a task that has not started — over one that renumbers finished work,
when both express the same intent.
Preservation through renewed Contract Review ends at this explicit mapping. Give
every retained Task with execution state exactly one disposition:
- keep its identity and state only when its active obligation and evidence still
apply;
- revise it and reset it to pending when changed active work remains; or
- remove it from the active plan and remove its keyed execution entry when it
serves no active Requirement.
A historical-only Task that references no active Requirement cannot remain in
the replacement plan; complete traceability will reject it. Its removal is not
silent when the before/after mapping names the old identity, state, and reason
and the user confirms that exact mapping. The retained plan remains visible in
Git history and the renewed-review checkpoint; do not invent an archive. Never
relabel an old completed entry as evidence for a new Requirement. An instruction
to preserve the plan and progress through review means do not delete it before
this mapping, not that every item must survive the approved replacement.
This confirmed retained-plan reconciliation is the sole exception to the
project instruction against hand-editing execution state. It is one Tasks-owned
replacement of the plan and its existing keyed records, followed immediately by
the checks in section 4 and the approval in section 7. It permits only keeping,
resetting, remapping, or removing entries that already existed. Never create a
new completed or blocked judgment, invent evidence, or change a blocker reason
through this exception; implementation owns those judgments through the CLI.
Restructuring an approved plan is legitimate. Doing it in a way that mislabels
completed work is not.
## 6. Review and revise
Present the plan: the decomposition and its order, and which active requirements
each task delivers.
Revise on feedback rather than approving something you know to be weak. Stop and
ask the user when the same objection survives one revision — a repeated objection
is a disagreement about intent, and rewriting again produces another variation of
the same misunderstanding.
If an objection reveals that the **design** does not determine the work, return
it there. A plan that compensates for an underspecified design moves the decision
into a document nothing verifies against the requirements.
## 7. Approve
Approve only when the protocol's judgment is satisfied **and** you hold authority
for this gate. Authority is one of two things, never their absence:
- **Explicit** — the user approved this plan after seeing it.
- **Delegated** — a run context the user intentionally started authorized this
gate by name. Every check still runs.
**The workflow name comes from that context. Never invent one.** If you were
told the content is pre-approved but given no workflow name, you do not have a
delegation — present your result and stop.
Never run a mutating command to find out what it accepts. Approval has no dry
run.
```sh
specbind spec tasks approve <spec> --approval-mode explicit
```
A delegated run names the workflow that carries the authority:
```sh
specbind spec tasks approve <spec> --approval-mode delegated --delegation-workflow <workflow>
```
There are no IDs or fingerprints to pass. The CLI derives its input from the
normalized plan projection.
No prompt appearing, a non-interactive invocation, and a scripted run grant no
authority. Without either form, present your result and stop.
Never approve to resolve a failing check. A refused approval is information about
the plan; report the diagnostic rather than working around it.
## 8. Checkpoint
Only after the approval succeeds is this work eligible to commit. A draft you
have not yet approved is never committed, however often the project wants
checkpoints. If you stopped short of approving, you also stop short of this.
```sh
specbind adapter read git --for consume
```
`NO_CHANGE ADAPTER_ABSENT` or `NO_CHANGE ADAPTER_SCAFFOLD` means there is no
adapter-directed commit. Stop there — that is an answer, not a missing file to
work around.
When the adapter has guidance, follow it. The request to perform this mutating
phase authorizes the adapter's narrow local checkpoint as its ordinary final
step. It does not authorize anything broader:
- An explicit user or root instruction that forbids commits wins, and tool
permissions still apply.
- Delegated approval authorizes the gate, while the orchestrated phase request
authorizes only this local checkpoint. Neither authorizes pushing.
- Commit guidance is not push guidance. Push only where the adapter says to, and
never force-push, rewrite history, or bypass a protected branch.
- Stage only the paths this run produced. Unrelated work already in the worktree
is left exactly as it is.
- Stop before the Git operation if the guidance is ambiguous, unsafe, or
conflicts with something else you were told.
A failed checkpoint does not undo or weaken the approval. The gate stays
approved; report the work as uncommitted and continue.
## When the gate is already approved
Exception: explicit Drive replan authority from [the recovery procedure](replan.md)
covers this Tasks rewind and reapproval, including progress remapping. Report
the cost and mapping, then continue without another confirmation.
If `spec status` shows the tasks gate approved, do not edit. Editing underneath
an approved gate leaves evidence describing a plan that no longer exists, and the
CLI then refuses later work citing freshness rather than the edit that caused it.
State the cost accurately and run it only after the user confirms. This is the
**cheapest** of the three rewinds, and overstating it pushes people away from the
right operation:
- it clears the tasks and completion evidence, and
- it **keeps** the accepted contract review, and the requirements and design
gates.
Add what the revision itself will cost when implementation has started — which
recorded progress is affected, per the mapping rule above.
```sh
specbind spec tasks invalidate <spec>
```
Outside that explicit Drive recovery, confirmation cannot be inferred, and
ordinary delegated authority does not cover this. Ordinary delegation
authorizes accepting gates, not discarding accepted work.
## Boundaries
- Author `tasks.yaml` only. Requirements, design, and the contract belong to
earlier phases; ordinary execution state and implementation notes belong to
implementation. The confirmed retained-plan reconciliation in section 5 is
the only exception, and it may transform only entries that already existed.
- Write no machine state. Never edit `spec.yaml`.
- Never run `tasks complete`, `tasks block`, or `tasks reopen`. Those record an
implementer's judgment.
- Do not accept the contract review, and do not delete a retained plan to
unblock one. When review is absent or stale, route to `sb-contract-review` and
leave the plan and execution records unchanged.
- Report in the project's language: the decomposition, the order and why, which
requirements each task delivers, whether the work was
committed, and what runs next.
For a shared resource contribution, trace the Task to its own feature
Requirements. Put concrete shared paths and the intended contribution in its
boundaries; reference the shared resource in contracts where useful. Do not
invent a Requirement or a separate shared Task plan merely to name the file.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |