Sb Steering

Maintain durable project guidance

Apply project language style

Before authoring any artifact or user-facing prose, read:

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.

Steering carries what outlives any single change: how this project is built, what it values, and the constraints every change inherits. You author it. The CLI owns discovery and identity.

Nothing else in SpecBind depends on this running, and nothing invalidates when it does — steering is never gate evidence and editing it approves nothing. That cuts the other way too: sb-discovery reads the whole collection and routes work on it, so a document that has quietly gone out of date misroutes real work. Guidance you are not confident is still true is worth removing.

1. Confirm what you are doing

Three things can be asked for, and they are not interchangeable:

Ask when the request does not say. The current inventory is input to that conversation, not the answer to it: an empty steering/ is a valid steady state, not a prompt to bootstrap. A project that decided it does not want steering should not get it because a skill assumed.

2. Read what exists

specbind steering list

Then read every document it lists:

specbind steering read <artifact_id> --for maintain

Never read steering/ directly and never glob it. The selector is the artifact_id, and the listing is what tells you which ones exist.

When the listing reports a diagnostic, steering read will refuse every document, including the healthy ones — a consumer must not act on guidance known to be incomplete. You are the exception, and only for repair:

• A malformed-document diagnostic names the faulty path. Read that file directly, fix what the diagnostic reports, and re-run specbind steering list.
• A duplicate-identity diagnostic names every colliding path but does not decide which one owns the identity. Read those named files directly and inspect Git history. Remove one only when history proves it is the newly introduced duplicate in the repair scope. Matching content or a copy-like filename is not proof. Without provenance, present every path and the effect of each choice, then stop for the maintainer; do not pick a survivor yourself.
• Repair first, then continue. Do not work around a broken collection by authoring alongside it.
• Every other read still goes through the commands above.

Read the project's steering-authoring policy once through its rule surface:

specbind rule read steering-principles --for consume

It covers granularity, examples, and what to leave out. NO_CHANGE RULE_ABSENT means no customization and you proceed on the contract here. Any ERROR line stops this workflow.

3. Understand the codebase before writing about it

Dispatch fresh readers rather than reading everything yourself. Each one starts with no context, so give it a brief that stands alone: what to look at, what question to answer, and that you want the pattern, not an inventory.

Use the registered specbind-researcher role when available, with ordinary fresh readers as the fallback. Fallback is only for an absent role. A configured role whose model cannot start is a configuration or environment failure, not permission to change models.

For bootstrap, three independent readers cover the ground:

• Product — README, package and project metadata, user-facing documentation. What is this for, who uses it, what has it deliberately refused to do?
• Technology — build configuration, dependencies, test setup. What decisions is every change inheriting, and what reasons are recoverable?
• Structure — the tree, naming, import and dependency direction. What rule decides where a new file goes?

For synchronize, ask each reader to compare the codebase against the steering text you already read, and to report specifics: what steering claims that the code no longer does, and what durable pattern the code has established that steering does not mention.

Extract patterns, not catalogs. If new code that follows the existing patterns would require a steering update, the document is written at the wrong level.

4. Author

Materialize from the scaffolds rather than inventing structure:

specbind template list steering
specbind template read steering <selector>
specbind protocol read okf-authoring

product, tech, and structure are the bootstrap defaults and carry their own identity. document is the scaffold for any other subject and deliberately declares none.

Follow every scoped instruction the template returns. 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 create comments from the materialized artifact. Treat each maintain and consume comment as one indivisible block: copy its opening marker, complete body, and closing marker byte-for-byte. Never excerpt or rewrite it. Existing documents already own their durable comments; preserve them when revising unrelated content.

The listing reports both a SpecBind-root-relative output_path and a project-root-relative project_path. Write only to project_path. For document, replace <artifact_id> in that reported project path with the identity you chose; never prepend or remove the configured SpecBind root by inference.

Author guidance from established project evidence. Do not change source, configuration, or tests merely to make a statement in the new document true; that would expand a documentation request into implementation work.

Bootstrap

Propose product, tech, and structure, and say what each would contain before writing. Nothing privileges these three — the user may rename them, merge them, split them, or decline any of them. Write what the project actually has; a section you would have to invent content for is a section to delete.

Synchronize

Revise in place. Do not accumulate. A steering document states the project as it is now, and guidance that keeps its own history makes readers guess which version is in force. Git holds what it used to say.

That is not a licence to rewrite:

• Revise what the codebase demonstrably contradicts.
• Leave alone what is merely not how you would have written it. Restructuring a sound document is churn.
• When you cannot tell whether something is stale or just unfamiliar, propose it and let the user decide. Unclear is not the same as false.

Report drift you are not fixing: patterns the code has established that nobody has decided to make policy are the user's call, not yours.

Add

First establish the subject's current durable convention from project evidence. A request to "write down how we do" the subject is authority to document an existing practice, not to choose a new policy. If the project has no settled convention, report that absence, ask the maintainer for the actual convention or an explicit decision to establish one, and stop before creating a file. Do not combine an accurate statement that tooling is absent with an invented normative policy. After the answer, materialize only the supplied policy and supported project facts.

Read template read steering document, choose the identity, and write it only to the project_path reported by template list steering after replacing <artifact_id>.

The identity is yours to choose here — it is the one place SpecBind asks an agent to pick an artifact_id. Get it right:

• lowercase kebab-case, describing the subject
• not already listed by specbind steering list. A duplicate identity is a hard discovery error and drops both documents from the collection
• stable across later renames and moves, because it is the identity, not the file name

5. Verify what you wrote

specbind steering list

Every document you touched must appear, with the selector you intended. A document that does not appear was authored wrong — bad Front Matter, wrong type, or a colliding identity. Fix it and list again. Do not report success on a document the CLI cannot see.

Every new Steering document requires a non-empty single-line Front Matter description naming its lasting project-wide decision boundary. Carry a fixed template's literal description into the live document. For the generic document scaffold or an old template without this field, write the assessed recurring responsibility, checking overlap with existing Steering. Update the description with the body only when that boundary changes. Existing major-one documents without descriptions remain readable. Descriptions do not narrow Discovery's obligation to read all Steering.

For every newly materialized document, run the mechanical scaffold check with the document identity and the template selector used to create it:

specbind steering check <artifact_id> --template <selector>

It verifies complete durable instruction blocks, leaked create guidance, unresolved named outputs, and scaffold placeholders. Any ERROR stops the workflow; do not recreate this comparison with a project script.

6. Checkpoint

This section is part of completing Steering. A request to stop after Steering or after synchronization still proceeds through this section; it does not mean stop with verified files left dirty. Only an explicit instruction that forbids commits skips an otherwise active adapter-directed checkpoint.

After every touched Steering document passes the applicable verification above, read the active Git adapter:

specbind adapter read git --for consume

NO_CHANGE ADAPTER_ABSENT or NO_CHANGE ADAPTER_SCAFFOLD means there is no adapter-directed checkpoint. Continue to the report with the Steering changes left uncommitted; do not invent a project Git policy.

When the adapter has guidance, follow it. The request to perform this mutating workflow authorizes its narrow local checkpoint as the ordinary final step:

• Inspect git status --short and the exact diff for every Steering path this run changed.
• Stage only those verified Steering paths. Never include pre-existing or unrelated changes; if an unrelated change overlaps a touched path, stop before the Git operation and report the conflict.
• Stay on the current branch. Do not amend, rebase, push, create or switch branches, tag, publish, or rewrite history unless separately authorized.
• If the checkpoint fails, leave the verified Steering changes in place and report the failed operation. Do not stash, reset, or broaden the commit to manufacture a clean result.

7. Report

In the project's language: what you created or revised, what drift you found and did not act on, anything you deliberately left out, and whether the checkpoint was committed, intentionally absent or scaffolded, or failed. Keep it short — the documents are the deliverable.

Boundaries

• Never write secrets. No credentials, keys, tokens, connection strings, or anything that would be a leak if the repository were public.
• Do not document SpecBind's own settings/ tree or agent directories such as .claude/ and .agents/. That is project metadata, not project knowledge, and it ages against a tree the project does not maintain.
• Do not write transient content. Current scope, in-flight migrations, and the status of work under way belong to the milestone that owns them. Do not use Spec or milestone state as evidence for Steering content — if you need it to decide what the document says, that content does not belong there. The specbind milestone status read required by the authoring protocol is only a write-safety preflight for accepted completion and supplies no document content.
• Steering is not a gate. This skill approves nothing, records no evidence, and is never required before other work proceeds.
• Reasoning that changed a routing or scoping decision belongs in that Spec's brief or the Roadmap body, written by the skill that made the decision. Do not relocate it here.