Witness Plan

witness-plan — spec delta → step plan → gate

Ground rules (every witness skill)

Resolve the CLI once per session:

WITNESS="${WITNESS_BIN:-npx -y @popovych.co/witness@0.13.0}"

• Render the CLI's decision output verbatim and in full — every line, unmodified. Never print a command set you remember; never recompose, reformat, summarise or reorder what the CLI emitted. Which decisions are live, how they rank, and what each costs are the CLI's answers, and they change with the round, the bound, the repair grant and the content sha — a remembered set is wrong in more states than it is right.
• The human decides; you may type it. Run a witness decide verb only when the human names an option — its number or its verb — and then run the printed string byte-for-byte: never recomposed, never reformatted, never with a placeholder you resolved yourself. The moment you compose a --note or resolve an id, you are authoring their decision. A bare affirmation ("ok", "sounds good", "yes") is not a selection — ask which option, especially where option 1 is --approve at a stop that exists because a human must look. A selection does not survive session death: killed and re-run, render the block again and ask again.
• Never edit specs/** or plans/** (the canon dirs — paths: in witness.config.yaml may relocate them) — not with an edit tool, not with a write tool, not with Bash redirection. The CLI is the sole writer of state; you author in scratch files under $(mktemp -d) and hand them to the CLI. (The canon guard blocks you; the trailer audit catches what it can't.)
• Read canon with witness read , never by path. Canon lives at the primary root; inside a worktree the files are absent by design, so a path read finds nothing and a stale copy cannot be mistaken for the contract. Fat artifacts: witness read --design --outline, then --lines -.
• Never invoke gate reviewers or relay verdicts. witness gate runs reviewers itself and journals what they said; your summary of a verdict is not evidence.
• Refusal repair loop: a witness verb exiting 2 prints structured violations (field · rule · got · want). Fix your input and retry — 3 total attempts per artifact, then stop, show the human the violation list verbatim, and end your turn.
• A refused or hook-blocked command is a stop, not a step to drop. Re-issue it on its own; if it still refuses, tell the human what was blocked and why. Never proceed by deleting the refused half of a compound command — a dropped step is silent, and silence is how a skipped check becomes a shipped defect.
• Re-entrancy: derive position from CLI output ($WITNESS next, the dashboard, log, index) — never from conversation memory. Killed and re-run, you must converge.

Inputs (rebuild them, never remember them)

Everything below is rebuilt from witness diff and the CLI's read verbs — never from conversation memory, never by path.

$WITNESS diff         # the delta this plan must realize (base: previous plan's pin → last live → empty)
$WITNESS read         # the parent spec, current content (reading is fine — writing is not)
$WITNESS index                 # the plans table names this spec's prior plans, if any
$WITNESS read         # …then read the one you care about
$WITNESS decide plan  --show       # ONLY when re-entered after a revise

Effort slug (write needs --effort): take it from the $WITNESS next line that routed you here — next resolves it to a live effort that wrote this plan or its parent, so the slug in that command is the answer. Deriving your own instead risks booking the write onto an abandoned stream. If you arrived without that line: one active effort → use it; several → $WITNESS log per candidate, and the effort whose write entries name the parent spec owns this plan; still ambiguous → ask the human. If next asks for a recap instead of a write, no live effort can carry this plan — that recap is the owed work, not the plan.

Plan id: -plan- — n = 1 + the highest existing n in plans/ for this spec (a spec accumulates plans over its life; expand-contract amends it twice in one effort).

Author the plan

Every criterion in the delta must be realized by ≥ 1 step; every step maps to ≥ 1 criterion or is honestly scaffolding: true (rigging only — fixtures, wiring, config; never behavior a criterion owns). derives-from is stamped by the CLI from the parent's current content — never put it in the manifest; a supplied stale pin refuses.

If the parent spec is ui-flagged, its design must already be approved (the design stage runs between decompose and plan). Read it with $WITNESS read --design (--outline, then --lines -, when it is fat) — your steps derive from that approved look, not a fresh invention — and put its approved artifact sha in the manifest as "design-from" (the CLI refuses a plan whose pin is missing, stale, or present on a non-ui parent; get it from the spec's design.sha stamp via $WITNESS log ). A UI step names the design section (design#) it realizes alongside its @spec: browser test.

DIR=$(mktemp -d)
cat > "$DIR/meta.json"  "$DIR/body.md"  --meta "$DIR/meta.json" --body "$DIR/body.md"

Body discipline (write-validated: exactly one ## Step: section per manifest step, none missing, none orphaned):

• Each step section is executable by a fresh session with zero context: exact paths, the test to write first, expected red, minimal code, expected green.
• A step realizing browser-visible behavior (markup, styles, routes, client-side interaction) names an end-to-end Puppeteer test as its test-to-write-first — the browser drives the slice's real backend and store, faking only third-party boundaries the repo doesn't own. Browser-level e2e TDD is the implement contract; the implement gate's pr-test lens treats a unit test standing in for the browser — or a browser test stubbing the slice's own backend — as a coverage gap.
• Steps ordered so nothing presumes an artifact a later step creates.
• Chore-class plans choose their own parent here — a chore never reaches the decompose stage, so no earlier stage picked one for you. Take the spec whose implementation area the chore touches; take parent: principles when the chore is repo-wide. Either way the parent must be approved/live or the write refuses. Report the choice so the gate stop shows what you routed to.

Gate

$WITNESS gate plan     # append --manual when the run asked for it

• Auto-pass → done; hand back to /witness.
• Stop → render the gate output verbatim and in full, including its ranked options and run: line, and END YOUR TURN.
• Re-entered after --revise → decide --show gives the verdict + note (findings anchor to > ## Step: ); rewrite via witness write with the same plan id; re-gate. A parent amended mid-flight fails pin-fresh — rewriting through witness write re-stamps the pin to current content; your body must then realize the new delta ($WITNESS diff again). --show also emits state: and exits: — a reopened or settled state means the verdict above it is history, so act on the exits: line, not on remembered findings.
• Findings implicate the spec (plan faithful, spec wrong)? Tell the human --revise --upstream reopens decompose for it.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: popovych-co
• Source: popovych-co/witness
• License: MIT
• Homepage: https://www.npmjs.com/package/@popovych.co/witness

Install and usage instructions live in the source repository linked above.