Huruikagi/pc-build-planner / .claude/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.7 KB |
| 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/requirements.md
View on GitHub# Requirements phase
## 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 Requirements procedure selected by `sb-plan`. Read it
only for a Requirements phase, whether the parent is running the complete
planning workflow or the maintainer explicitly requested this phase alone.
Produce the document every later phase is verified against: this Spec's
**complete current behavioral contract**, not the delta this milestone requested.
You author one artifact and approve one gate. Everything else — the contract,
the design, the task plan — belongs to other phases.
## 1. Read
Always:
```sh
specbind spec status <spec>
specbind steering list
```
Read the Spec's brief, and read **every** steering document the listing named:
```sh
specbind artifact read <spec> brief --for consume
specbind steering read <selector> --for consume
```
If the Brief declares Source Items, read the shared contract once and then read
every exact project-relative item it names:
```sh
specbind protocol read source-material
```
Do not reopen the whole collection or infer neighboring files; Discovery already
recorded this Spec's relevant subset. A missing, unreadable, unsupported, or
project-external item makes the request context partial, so stop before
authoring. Source material is context rather than approved scope, and a locator
alone never becomes a Requirement.
Read all the steering, not a promising-looking subset. The listing gives you a
selector, a type, and a path, and nothing in that says whether a document
constrains this Spec's behavior. A project constraint missed here is absent from
the contract every later phase checks against, so it is missed everywhere.
Treat that listing as the complete, closed set for this read. Do not enumerate
the storage directory or invent another selector from a nearby filename. In
particular, the active Roadmap is milestone state stored beside Steering; it is
not a Steering document and must not be passed to `steering read`.
If `steering list` or `steering read` prints an `ERROR` line, stop. Authoring a
contract against a knowingly partial view of the project's constraints produces
something nobody can trust. `Found 0 steering document(s).` is a complete answer
and you continue.
### Then branch on what exists
A Spec created by this milestone holds only its brief: `milestone create` writes
machine state, and discovery does not author requirements. `spec status`
reporting a missing requirements artifact is the expected starting state here,
not a fault.
- **New Spec** — start from the template and author the Spec's first complete
contract from the brief:
```sh
specbind template resolve spec <spec> requirements
specbind template read spec requirements
```
Write the authored document only to the resolved `Project path`. It already
includes the configured SpecBind root; do not reconstruct it from an artifact
inventory `path`, the template-relative `Output path`, or the default root.
Follow every `create output=<name>` instruction once to produce its named
output. An output may be a short string or a Markdown fragment. Replace every
reference to that name with the same produced output, and omit the `create`
instruction from the live artifact. Copy each complete `maintain` and `consume` comment,
including its opening marker, body, and closing marker, byte-for-byte. The
Requirements section is deliberately empty and is not a valid live artifact.
Replace it with at least one real Requirement and Acceptance Criterion before
the first write; never persist the scaffold as completion.
Do not run a Contract read in this branch. The lifecycle state already says
that Design has not created one, so `ARTIFACT_SELECTOR_NOT_FOUND` would add no
information.
- **Existing Spec** — read the current requirements and revise them in place:
```sh
specbind artifact read <spec> requirements --for maintain
```
Use the artifact inventory as the non-error existence check, then read the
Contract as boundary context only when the inventory lists it:
```sh
specbind artifact list <spec>
specbind artifact read <spec> contract --for consume
```
Immediately after this read and before drafting, build a private preservation
ledger in working memory. Enumerate every existing Requirement group and
acceptance criterion by its canonical ID, plus the unaffected owned behavior
expressed by Context, Scope, and Objective. Do not write this ledger to the
project. If you cannot account for the complete maintain projection, stop
before editing rather than authoring from a partial baseline.
Never author the contract here. A new Spec has none until the design phase runs,
and that is correct.
## 2. Write the contract
Preserve an intentionally abstract but observable boundary from the Brief. For
example, if it says an action is accepted before a named window closes and
rejected afterward, express those outcomes without inventing a duration,
closing event, trigger mechanism, or other unstated policy. Ask for
clarification only when the supplied boundary cannot determine an observable
accepted or rejected outcome without inventing behavior.
Read the protocol that owns semantic quality, and the project's writing
preference, before writing:
```sh
specbind protocol read requirements-review
specbind protocol read okf-authoring
```
Read the project's phrasing preferences through the project-owned rule surface:
```text
specbind rule read ears-format --for consume
```
`NO_CHANGE RULE_ABSENT` means the project supplies no customization; the
protocol still applies. Any `ERROR` line stops this workflow.
Write constraints you took from steering **into the document**, in the
requirements' own terms. Steering is not fingerprinted, so nothing detects a
steering document that changes after this gate is approved. A requirement that
merely points at guidance is a requirement whose meaning can drift silently.
Apply the same rule to Source Items. Restate every accepted behavioral
obligation in the Requirements' own terms so the complete current contract
survives the milestone and can be fingerprinted. Keep provenance in the Brief;
do not make an acceptance criterion depend on following a source link. When two
items disagree about intended behavior, surface the conflict to the user rather
than selecting one silently.
For a new document, omit `create` instructions and copy every `maintain` and
`consume` instruction unchanged. For an existing document, preserve the durable
comments already returned by the maintain projection.
Keep technology, structure, and mechanism out. Those belong to design, which is
also why steering that is technical in nature cannot be carried in this
document — do not try to smuggle it in as a requirement.
A request for automated tests, coverage, or a canonical verification command is
delivery evidence, not by itself observable product behavior. Write the behavior
that evidence must verify; Design and Tasks own the testing mechanism and
coverage work. Do not create a Requirement solely to require tests unless the
test capability is itself part of the user-visible or system-visible product
contract.
Do not renumber existing requirement groups to close gaps. Identity is
positional, so renumbering silently reassigns IDs that `spec.yaml`, design
traceability, and task coverage already reference. Gaps are fine and permanent.
### Retire obligations without removing identities
For an explicitly requested cessation or consolidation, prefix the affected
criterion with the exact `_Retired_` marker. To retire a complete group, put it
at the start of the heading title: `### Requirement 3: _Retired_ Old title`.
Use the artifact's mapped heading label. A group marker covers every child.
Prefer retaining the original prose after the marker; a marker-only criterion
or heading is also valid. Never delete a reserved list position, renumber later
criteria, or reuse a retired group. Add new criteria at the end.
Explain which obligations continue, their successor IDs when applicable, and
which obligations cease in adjacent prose or nested lists. These explanations
are part of Requirements approval, not a separate manifest or fixed DSL. A
successor link alone does not prove preservation. Reconcile partial cessation
against every baseline obligation and update Context and Scope accordingly.
Marker text is historical context, not a live promise or proof of completion.
Read the Requirements at the Roadmap baseline when establishing which IDs are
newly retired. Include every newly retired baseline criterion in the active
set, including all live baseline children of a compact retired group. Already
retired baseline IDs cannot be selected again. New Specs cannot invent retired
identities. If all live obligations would retire, stop before editing: complete
Spec retirement remains unsupported.
## 3. Choose the active set
The active set is the requirement IDs this milestone must **deliver,
re-verify, or retire**. It may consist solely of newly retired IDs; do not add a
dummy behavioral requirement to make retirement work traceable. Not the whole
document, and not only the literal diff.
- Requirements whose behavior this work changes or adds are always in.
- Requirements whose correctness depends on that work are in even when their
text is untouched, because they must be re-verified.
- Requirements unrelated to this work stay out, so the milestone is not forced
to re-plan and re-test the Spec's entire contract.
**When membership is genuinely unclear, include it.** The two mistakes are not
symmetric. Over-including costs design and task effort on behavior that did not
need it. Under-including means design and tasks never cover behavior this
milestone actually changed — and nothing catches it, because coverage is checked
against the set you chose.
State the selection and why each ID is in it. This is part of what gets
approved, not a detail derived quietly at the end.
Use only the canonical positional form the Requirements parser derives: group
number plus acceptance-criterion list position, such as `2.1`, `2.2`, and
`2.3`. Never invent aliases such as `R2.AC1`. Before presenting the selection,
run `specbind check traceability <spec>` against the authored draft; while the
active set is still absent, it must recognize the full Requirements document
without a Requirements diagnostic.
## 4. Review and revise
Present the document and the selection. Revise on feedback rather than approving
something you know to be weak.
For an existing Spec, the review includes a mandatory preservation audit before
approval. Compare the authored file with the current Requirements you read at
the start (and inspect `git diff -- <requirements-path>` when Git is available).
Reconcile the authored file against the private preservation ledger. Account for
every pre-existing requirement group and acceptance criterion by its original
ID: it must remain live with only the requested revision, or be explicitly
retired with its obligations accounted for by continuation or cessation.
Context, Scope, and Objective
must also continue to describe unaffected owned behavior. A rewritten document
that silently narrows the Spec is not ready even when its new criteria are
well-formed. If any existing obligation disappeared, stop before approval;
restore an accidental omission in the same draft unless the requested result
truly needs retirement, in which case use the marker and explanation above.
Before presenting or approving, state to yourself that every ledger entry is
accounted for and zero obligations were lost. Never use the approve command as
the operation that reveals this loss.
When the review has findings, report each one in this shape:
```text
- [BLOCKING|DEFERRED|RESOLVED] <requirement or behavior at risk> — <where> — <consequence>
```
Every finding carries exactly one disposition from the protocol. An approval
with an undisposed finding is not a verdict, and a finding mentioned elsewhere
in the report does not count as disposed.
Stop and ask the user when the same objection survives one revision. A repeated
objection means the disagreement is about intent, not wording, and rewriting
again produces another variation of the same misunderstanding. You have run out
of information you can supply yourself; ask for it.
An observation that is real but does not hold this gate is a **deferred**
finding under the protocol, and it needs the destination this project names:
```sh
specbind adapter read deferred --for consume
```
`NO_CHANGE ADAPTER_ABSENT` or `NO_CHANGE ADAPTER_SCAFFOLD` means there is no
destination: say so in one line and record nothing. Otherwise follow the
returned active guidance as written.
Nothing recorded there is a source of work for you; an entry re-enters this
workflow only when a person puts it on the Roadmap.
## 5. 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:
Immediately before any approval command, rerun the traceability check. For an
existing Spec, also repeat the preservation-ledger reconciliation and require a
zero-lost-obligations result. This is a blocking preflight, including under
delegated approval; discovering a loss after approval is a failed workflow, not
a reason to invalidate the gate and repair it afterwards.
- **Explicit** — the user approved this document and this selection after seeing
them.
- **Delegated** — a run context the user intentionally started authorized this
gate by name. The user does not confirm this document, because delegation is
exactly the decision to skip that pause for artifacts not yet written. Every
check still runs, and you still state the selection in your report so the
delegation stays auditable.
**The workflow name comes from that context. Never invent one.** It identifies
the authority you are exercising, so a name you made up identifies nothing and
makes the record of a skipped confirmation false. 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, so a probe with a placeholder value records a real approval.
```sh
specbind spec requirements approve <spec> --approval-mode explicit --requirement-ids <ids>
```
`--requirement-ids` takes the comma-separated canonical IDs. A delegated run
names the workflow that carries the authority:
```sh
specbind spec requirements approve <spec> --approval-mode delegated --delegation-workflow <workflow> --requirement-ids <ids>
```
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 artifact; report the diagnostic rather than working around it.
`SPEC_REQUIREMENTS_RETIREMENT_UNSUPPORTED` means the approval wrote no gate
evidence and the Spec remains in Requirements. It is mechanical confirmation
that this phase's preservation preflight failed, not a reason to invalidate a
gate. Restore every named baseline ID and its unaffected behavior from the
original maintain projection, repeat the complete preservation reconciliation
and traceability check, then retry approval once. If the diagnostic repeats,
stop. `SPEC_REQUIREMENTS_BASELINE_READ_FAILED` is not authoring feedback; stop
without retry because the immutable comparison source is unavailable.
## 6. 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
Routed work from Discovery arrives with the gate already rewound because
Discovery performs confirmed invalidations before it changes scope. A Contract
Review remediation handoff is different: Review must not mutate Requirements
state on this phase's behalf. It supplies the exact finding, target Spec, command,
rewind cost, and the user's operation-specific confirmation.
When that complete Review handoff matches current status and cost exactly, the
relayed confirmation authorizes this Requirements receiver to invoke that one
`specbind spec requirements invalidate <spec>` operation, then continue through
repair, approval, and this phase's ordinary coherent checkpoint. It is not
general delegation and cannot be reused if the finding, state, or cost changed;
stop and obtain fresh confirmation instead. Carry the Review finding ledger and
remaining remediation budget back to the orchestrator. If you were invoked
directly and `spec status` shows the requirements gate approved, do not edit.
Editing underneath an approved gate leaves evidence describing a revision that no
longer exists, and the CLI then refuses later gates citing freshness rather than
the edit that caused it.
Tell the user what invalidation costs — it clears the design, tasks, and
completion evidence downstream — and run it only after they confirm:
Here, “evidence” means gate evidence in `spec.yaml` and the accepted Contract
Review. The CLI does not delete retained Design, Contract, `tasks.yaml`, Task
execution records, or source. Those documents remain visible repair input until
their owning phases explicitly reconcile them; do not describe a gate rewind as
silently deleting the saved plan or completed progress.
```sh
specbind spec requirements invalidate <spec>
```
Confirmation cannot be inferred, and delegated authority does not cover this.
Delegation authorizes accepting gates, not discarding accepted work.
## Boundaries
- Author the requirements artifact only. The contract belongs to design;
comparing an existing codebase against intended behavior belongs to
`sb-gap-analysis`.
- Write no machine state. Never edit `spec.yaml`. The active set reaches it only
through the approve command.
- Report in the project's language: what the contract now says, what changed,
which IDs are active and why, whether the work was committed, and what runs
next.
## Durable responsibility description
For new Requirements, replace the template's generic Front Matter `description`
with one non-empty, single-line sentence naming the Spec's complete current
responsibility. It is not a Milestone change summary. Maintain it with the body
when that responsibility changes; do not duplicate it in an index or `spec.yaml`.
Existing major-one Requirements without it remain readable. Adding it to an
existing artifact is an authoring edit with ordinary freshness and approval
consequences, not permission to approve or rewrite lifecycle evidence.
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 |