# Witness Implement > Implement a witness plan — you are the implementer; CLI-managed worktree, session slices under the dispatch budget with a CLI-printed relay, red/green TDD with CLI-witnessed evidence per step, then the implement gate. Normally invoked by /witness with the plan id. - **Type:** Skill - **Install:** `agentstack add skill-popovych-co-witness-witness-implement` - **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-implement - **Website:** https://www.npmjs.com/package/@popovych.co/witness ## Install ```sh agentstack add skill-popovych-co-witness-witness-implement ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # witness-implement — plan → tagged tests + code → 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. ## Start (idempotent) `witness start ` creates or re-attaches the worktree: ```bash $WITNESS start ``` Prints the worktree path (`.witness/worktrees/`, branch `witness/`) and `agent-model:`. The worktree carries **code only** — the canon dirs are excluded from it deliberately, so the plan you are implementing is not a file in there; `$WITNESS read ` is how you read it, and what comes back is current rather than whatever was true when the worktree was cut. `agent-model:` is the config's implement-stage model pin (`gates.implement.model`, falling back to `gates.model`). Re-entry is safe: `in-progress` re-attaches or recreates. Refusals go to the human, with the remedy the CLI names: `blocked-deps` (a dependency isn't live/done yet), `needs-unmet` (show `witness satisfy …` for manual needs), `not-approved`. ## Work the plan in slices (session relay) A fresh session is the execution model: **this session is the implementer**, working inside the worktree `start` printed. `start` also prints `dispatch-budget:` (the config's `implement.stepsPerDispatch`) and `dispatches:` (the run's shape). Work the plan as a **relay of session slices**: this session takes **at most the next `dispatch-budget` unfinished steps**, then relays. Derive which steps remain from the journal (`$WITNESS log ` — steps with a green `test-evidence` are done), never from conversation memory. Protocol per step, in order — red/green/refactor with witnessed evidence: 1. Write the failing test FIRST. The test's NAME carries the tag `@spec:` (in the title string — never a comment; e.g. `it("rotates token before expiry @spec:auth-refresh")`). Run the inner TDD loop against exactly the test under work — `-t` with the test's own name, never the spec tag. Rerunning a failing test is legal; rerunning the suite to watch one test is not. The tagged suite runs only inside the witnessed evidence cycle (the `test-evidence` phases below) at step close — "check nothing broke mid-step" duplicates a run the CLI already witnesses. 2. Run `$WITNESS test-evidence --phase red` from the worktree. It must record a genuine red. If it reports the test passes before implementation (`vacuous`), STOP — never proceed to green on a vacuous red. First suspect the runner: a filter that never reaches the tagged tests (e.g. a dropped trailing `--` in the root test script) makes every phase lie. Fix the runner or the test until red genuinely fails, then re-record — a later genuine red supersedes the vacuous one (the gate judges the latest cycle). A `filter-matched-nothing` refusal is the same stop signal with the diagnosis built in. If neither applies, the behavior already exists — report instead of implementing. 3. Write the minimal code to make it pass. No speculative generality. 4. Run `$WITNESS test-evidence --phase green` — it must record green. 5. Refactor freely while green; leave everything uncommitted — the worktree stays dirty by design. 6. Early exit: if you exceed **~15 inner-loop iterations** inside one step, or you have left the step's scope to fight infrastructure, the economy is to relay — finish the red→green you are in (never stop mid-red), report, and relay so a fresh context continues. Exceeding your slice is never the right economy. 7. Fat artifacts (the living design, long docs) are read **by section** — `$WITNESS read --design --outline` names every anchor with its line range, then `--lines -` fetches the one you need — never whole into your context; you would re-pay their tokens on every subsequent request. **Tests you did not come to change.** When a step makes you edit a test file tagged for a spec other than your parent — a shared fixture, a helper, a suite-wide rename — you owe that spec **green now**, never a red→green pair: `red` means you observed the behavior missing before you built it, and you are not building that spec. The gate's `regression` check runs those specs' tagged tests and fails if any is red. Fix them in the worktree; never journal evidence under a tag this plan does not own, and never weaken the foreign test to pass. UI work TDDs at the browser, end-to-end: when a step changes what the browser renders or how the user interacts with it (markup, styles, routes, client-side behavior), the failing test in step 1 is a **Puppeteer** test driving the real UI **through the whole slice** — headless, tagged in its NAME like any test, living in the repo's regular suite so the criteria runner reaches it (Puppeteer is a library, not a runner — a test the runner can't reach has unwitnessable evidence). Everything the repo owns runs real: the test owns the slice's lifecycle — build, boot the backend and its store, serve the frontend; never assume a running dev server (evidence runs in a clean worktree) — but inside your own inner loop, keep the app server alive across iterations where the harness allows; the per-run floor is boot + compile, not test time. Fake only what the repo does not own (third-party services). Stubbing the slice's own backend — request interception, mocked fetch, canned API fixtures — turns the test UI-only, and the implement gate's pr-test lens flags it like any substitution. Unit/component tests may accompany a browser test, never replace it. **Capture the screens you build.** When `$WITNESS_SCREENS_DIR` is set (the CLI exports it during `test-evidence`), the browser test writes a named PNG per screen-level moment the step produces — `$WITNESS_SCREENS_DIR/.png` via the driver's screenshot call. Name captures for the moments a reviewer must see, not every frame: `initial` (screen as it opens), `filled` (primary inputs populated), `error` (a validation/error state the slice can reach), `success` (the post-action confirmation). One capture per meaningful state; skip states the step doesn't touch. Guard the writes on the env var so the same test screenshots nothing during the gate's own drift lane. These captures are the design-reviewer's evidence — `test-evidence` witnesses a sha per PNG, and at the gate a **vision `design-reviewer`** (feature and fix batteries, only when the plan pins a `design-from` design) judges them against the repo's `docs.design` canon and the approved look (`$WITNESS read --design`). A UI plan that witnesses zero captures is refused `screens-matched-nothing` before any reviewer runs — a screen with no screenshot has unwitnessable design evidence, exactly as a browser test outside the runner has unwitnessable behavior evidence. Never touch `specs/` or `plans/` (state lives on main; the CLI routes it) — they are not in your worktree at all, and `$WITNESS read ` is the route to their current content. Never `git commit`, never push, never open PRs — ship is a later stage and owns the sole code commit (evidence and gates read the working tree directly, so nothing needs committing here). Scaffolding steps skip evidence (nothing tagged changes). When every step is done, report the worktree diff summary. **Relay at the slice boundary.** When your slice's steps are done (or you early-exited), report telemetry — ```bash $WITNESS dispatch-report --steps-assigned --steps-completed \ --tool-uses --duration-ms ``` (numbers are your own best-effort report; omit flags you don't have — `--tokens` is usually unknowable from inside the session. Labeled reported telemetry, never gate evidence). Then, if unfinished steps remain, print exactly this and **END YOUR TURN**: > Slice done. Run the `relay:` line `dispatch-report` just printed — the next slice continues with fresh context (position re-derives from the journal). `dispatch-report` prints a `relay:` line resolved for whatever harness you are running on — print it verbatim. If no `relay:` line came back, the CLI could not resolve the harness: say so, show the human `witness check`, and end your turn rather than guessing a command. The fresh session re-enters through `/witness` and converges from CLI output — that re-entrancy is the relay mechanism, and it is why nothing may live only in conversation memory. When NO unfinished steps remain, skip the relay and go to the gate below. If code landed before its red was witnessed (a slice slipped), reconstruct instead of faking: `$WITNESS verify-red ` (stashes non-test changes, expects red, restores, expects green — safe in the isolated worktree). ## Gate ```bash $WITNESS gate implement # append --manual when the run asked for it ``` Its deterministic checks are the exit bar: a diff exists, every diff-added/modified tagged test has its red→green pair (no vacuous reds), and the parent's whole deterministic lane runs green locally — so ship confirms rather than discovers. The reviewer battery is class-scaled by the CLI. - **Auto-pass** (green path — no standing stop here) → hand back to /witness. - **Stop** (blocking findings or `--manual`) → 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` for the verdict + note (code findings anchor to `path#symbol`); fix in the worktree yourself under the same TDD protocol (new behavior = new red first); re-gate. Rounds are counted by the CLI; at the bound it forces the human. `--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 **plan** (code faithful, plan wrong)? Tell the human `--revise --upstream ` reopens the plan stage. - A **design-reviewer** stop anchors to a capture filename (e.g. `initial.png`) — the finding is about the rendered screen, not the code. Fix the UI in the worktree, re-run the browser test so `test-evidence` witnesses the new capture, then re-gate; `$WITNESS read --design` is the approved direction to fix toward. ## 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-implement - 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%.