# Witness Plan > Derive an implementation plan from a witness spec's delta — step manifest mapping criteria, write-validated ## Step body — then run the plan gate. Normally invoked by /witness with the spec id. - **Type:** Skill - **Install:** `agentstack add skill-popovych-co-witness-witness-plan` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [popovych-co](https://agentstack.voostack.com/s/popovych-co) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [popovych-co](https://github.com/popovych-co) - **Source:** https://github.com/popovych-co/witness/tree/main/plugin/skills/witness-plan - **Website:** https://www.npmjs.com/package/@popovych.co/witness ## Install ```sh agentstack add skill-popovych-co-witness-witness-plan ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # witness-plan — spec delta → step plan → gate ## Ground rules (every witness skill) Resolve the CLI once per session: ```bash 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. ```bash $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. ```bash 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 ```bash $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](https://github.com/popovych-co) - **Source:** [popovych-co/witness](https://github.com/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. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-popovych-co-witness-witness-plan - Seller: https://agentstack.voostack.com/s/popovych-co - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.