# Oversight Model `pi-workflow-kit` combines **skills** and **one extension**. The kit enforces a design → execute → finalize workflow: one buildable design doc per feature, executed through the feature gate, shipped once. ## Skills Skills teach the agent the workflow. There are 4 pipeline skills plus 2 utility skills: - **pwk-brainstorming** — explore ideas, produce the single buildable design doc (each `### R:` block carries its acceptance criteria + review tags) that opens with a `## At a glance` digest for the human (plain-language summary → **Key decisions** with rejected-alternative clauses only for real forks → `| R# | Requirement in one line | Risk |` table) immediately before the `## Requirements` blocks. For a requirement too big for one design doc, may start an **umbrella** (multiple design docs under one status-free overview, shipping as one PR). On non-trivial topics, requests the logical `codebase-recon` capability using the `pwk-recon-scout` role and falls back to the same five-section recon inline when unavailable or unsafe. Closes with a **design review**: one fresh-context `pwk-design-reviewer` pass on the written doc — spawn-or-skip (provider, then any generic subagent), never inline — with findings resolved as fix, reject, or human-set deferral before approval. - **pwk-executing-tasks** — feature-gate flow: write the feature E2E first, report it (no stop), implement the design doc's `### R` requirement blocks, then one risk-scaled feature-level review before the **ship checkpoint** (execution summary + code digest + coverage table presented for approval; full diff on request); two hard stops when the design carries `## Setup` (setup + ship), otherwise one (ship), per-requirement ceremony opt-in - **pwk-code-review** — the inline reviewer (code tracing, spec alignment, code smells, production hazards). During `pwk-executing-tasks`, the feature-level review resolves the design's `### Feature review` tag (`auto` by default): four logical fresh-context, read-only roles when the design carries production-risk content, otherwise one inline pass. Successful reports are retained and missing roles are retried or completed inline. It falls back to inline review when no safe compatible provider exists. The canonical provider contract is documented in `docs/provider-delegation-contract.md`. - **pwk-finalizing** — dispose the consumed topic folder `docs/plans/-/` as one unit (archive or delete; a single-leaf topic and an umbrella alike), curate lessons, update docs, create PR or merge Plus 2 on-demand utility skills: - **pwk-status** — read-only overview of all active design topics (phase + progress), for resuming or juggling parallel designs - **pwk-walkthrough** — on-demand explainer; renders a file:line-anchored walkthrough of a shipped feature into `docs/walkthroughs/.md`, regenerated wholesale, never disposed They explain *what* to do and *when* to do it. Phase control is manual — you invoke each skill with `/skill:`; the agent never advances on its own. ## Extension The `workflow-guard` extension registers the Pi-only `/pwk-setup` command and enforces one workflow rule: > During the design phase, `write` and `edit` are **hard-blocked** outside `docs/plans/`. The agent can still use `read` and `bash` for investigation. During those gated phases, `bash` is governed by a simple destructive-command blacklist (`rm`, `>`, `git commit`, `npm install`, in-place editors, etc.) — a command is allowed unless it matches a destructive pattern. A short phase reminder is shown once when the gated phase begins so the model self-restricts. During executing-tasks, code-review, finalizing, and walkthrough, nothing is restricted. `pwk-status` stays inside the gate. Canonical role contracts live in `agents/pwk-*.md` (single source of truth) and can be installed into `.agents/agents/` with `/pwk-setup`. `pwk-executing-tasks` requests logical review roles through the host’s delegation capabilities and passes each role a one-liner pointer to a script-assembled review packet — the packet defines the scope per review level (feature review: the whole feature diff; per-requirement: just that slice). Phases follow the skill you invoke — there is no message-keyword unlock. Invoking `/skill:pwk-executing-tasks`, `pwk-finalizing`, `pwk-code-review`, or `pwk-walkthrough` exits the gated phase (those skills write — walkthrough writes its explainer output under `docs/walkthroughs/`); `pwk-status` deliberately does **not** (read-only orientation). `/pwk-guard on|off|auto` manually overrides the guard. ## Enforcement style Hard block for write boundaries during gated phases. No warnings, no escalation, no prompts. Either the tool call is allowed or it's blocked. The unlock list is hard-coded in the extension and verified by `tests/skill-lint.mjs` against the skills' claims, so a skill that promises "read-only" can't silently unlock. TDD, checkpoints, debugging, and code review are guidance in the skill instructions, not runtime-enforced. The bash blacklist covers common destructive vectors only; exotic escapes (interpreter one-liners, piped shells) rely on the phase reminder — the guard is advisory, not a security boundary.