plan-build-verify

Plan Build Verify

Route implementation work through a sequential path where GitHub Issues are the source of truth for specs. Two supporting modes, Triage and Migrate, manage the roadmap.

Read the conventions first

Before any mode, read references/conventions.md completely. It defines the repo preflight, label taxonomy, issue body template, status transitions, sub-issue mechanics, issue dependencies, temporary body files, and coexistence with pstack and other skills in this pack. Every other reference file depends on it.

Coexistence with pstack and other skills in this pack

GitHub Issues remain the source of truth for specs, priority, and the Plan / Build / Verify lifecycle. For GitHub-issue product repos (devbox, kata-code, kata-agents, kata-symphony), plan-build-verify is the only product OS.

Skill / layer	Role	Not its job
plan-build-verify	Only product OS: specs, priority, Plan / Build / Verify, labels	Implementation tactics inside a Build or Verify run
pstack (Cursor plugin)	Engineering execution and proof inside Build and Verify; investigation during Plan (architect / how / why)	Planning, labels, approval, or a second issue lifecycle
ps (/ps in this pack)	Historical port of pstack; unwieldy; do not install for product delivery	Substitute for the pstack plugin or a second product OS
okf / finalize's OKF step	Retired. Remains in the library for history only	Any live roadmap or docs-as-spec workflow
kata-linear	Linear-first repos only	These four GitHub-issue product repos

Rules:

• Do not skip an unapproved issue because "the best spec is code."
• For product-shaped work, an architect checkpoint during Plan is investigation only. Do not treat pstack's never-block-on-the-human stance as permission to build past an unapproved spec.
• A per-repo verify-* skill (slash form /verify-<app>, typically under .cursor/skills/verify-*/) and its feature map complement ## Demonstration / ## Verification on the issue. They do not replace acceptance criteria. During Verify, look for and follow /verify-* before relying only on bundled UAT playbooks. Do not generate one mid-Verify.
• Do not invent a second issue tracker or file-based specs. Do not create or maintain product specs under docs/specs/ except the PBV migration index/archive described in references/conventions.md.
• Do not run okf init, okf update, or finalize's OKF step. OKF is retired; it is not an alternative roadmap.
• Do not install ps, okf, or kata-linear for these product repos. Install project-local skills with scripts/install-skills.sh (or the npx command in references/conventions.md). Never npx skills add -g, and never install the whole gannonh/skills pack.

Phase contracts

Phase	Input	Output	Status label transition
Plan	Idea, vague request, or new build request	Context exploration → alignment dialogue → approach approval → vertically sliced spec issue with mandatory ## Acceptance criteria	none → status:draft → status:approved
Build	Approved spec issue number, or explicit user override	Implemented tasks, commits, review results, pushed branch, Build completion report comment	status:approved → status:implemented
Verify	Implemented spec issue plus completed work or Build report	Acceptance evidence, durable acceptance tests, pull request, green CI, resolved review threads, signoff recommendation	status:implemented → status:verified
Triage	Repo issue backlog	Grooming report and applied label, decomposition, and closure actions	corrective, per issue
Migrate	Existing docs/specs/*.md bundle	Assessment report, spec issues, archived local files, rewritten cross-links, updated specs index	derived from each file's declared status

Select the workflow

Default to Plan unless the user explicitly directs you to execute an existing issue, verify completed work, groom the backlog, or migrate specs. A new build request starts at Plan even when the user says "build".

Mode	Reference	Enter when
Plan	references/plan.md	Scoping, designing, or specifying work, or no status:approved issue exists for the request.
Build	references/build.md	Executing a named, approved spec issue.
Verify	references/verify.md	Proving completed work meets the issue's acceptance criteria.
Triage	references/triage.md	Grooming the backlog, or answering "what should we work on next?".
Migrate	references/migration.md	Converting docs/specs/*.md into issues. Assess-first, one-way.

Read references/conventions.md and then the selected reference file completely, and follow both. Only load the workflow you need.

Build and Verify are one continuous run. Build does not stop to ask whether to verify; it enters Verify directly. Verify then runs unattended through evidence, acceptance tests, PR creation, and CI convergence, stopping only at signoff. See the autonomy contract in references/verify.md.

Hard gates:

• Build must not start from a status:draft issue unless the user explicitly overrides the approval gate.
• Verify must not claim signoff without evidence.
• Verify must never merge the PR. Signoff and merge are the user's decision.
• Verify opens the PR, not Build. The PR body carries the acceptance-criteria matrix.
• In Plan, do not draft a spec issue before the user has answered an alignment question or approved a recommended direction. If you are about to, stop and ask instead.
• Migration is assess-first. Run scripts/migrate_specs.sh --assess and settle every unclassified or conflicting file with the user before any write.

For tiny, clearly bounded edits such as a copy change or single config tweak, do not force the full Plan workflow and do not open an issue. State the assumption and ask whether the user wants the full process. If the mode remains ambiguous, ask one focused question that resolves it.

Bundled phase references

Build and Verify load bundled workflows from this skill directory. Read the entry point completely; follow linked files and scripts under the same subtree.

Phase	Workflow	Entry point
Build	TDD	references/tdd/workflow.md
Verify	User acceptance	Project-local verify-* if present, else references/user-acceptance/workflow.md

Verify's convergence loop (Step 7) drives CI with gh pr checks --watch and gh run directly. For review threads it uses one sibling skill, resolved against the installed skills directory:

Purpose	Skill	Entry point
Review-thread inventory and fixes	address-pr-comments	<path-to-skills-directory>/address-pr-comments/SKILL.md

If it is not installed, Verify reads threads with gh api graphql instead; the loop does not depend on it.

Helper scripts

• scripts/ensure_labels.sh: idempotently creates this skill's label taxonomy. --dry-run reports what would change.
• scripts/install-skills.sh: project-local, non-interactive install of plan-build-verify and address-pr-comments only. Product repos can copy it. Never -g; never installs ps, okf, or kata-linear.
• scripts/migrate_specs.sh: bulk-converts docs/specs/*.md into spec issues, archives the sources, rewrites cross-links, and updates the specs index. Run --assess, then --dry-run, then apply.
• scripts/rewrite_spec_links.py: repoints Markdown links after files move into the archive. Called by the migration script; requires python3.

Resolve script paths against the skill directory the runtime actually loaded. If a configured skill path does not exist, stop and ask which installation to use. Never copy skill files into the project working tree to make a path resolve.

Requirements

• gh CLI, authenticated with issue write access for the target repo.
• gh sub-issue extension (yahsan2/gh-sub-issue) for decomposed specs. If absent, install with gh extension install yahsan2/gh-sub-issue or use the task-list fallback in references/conventions.md. Its create subcommand has no --body-file, so children are created with gh issue create and then attached with gh sub-issue add.
• A gh recent enough for issue dependencies (gh issue edit --add-blocked-by). Native; no extension required.
• A git remote pointing at the GitHub repository that owns the roadmap.
• jq, for reading gh sub-issue list --json output. The extension has no -q flag of its own.
• python3, for link rewriting during migration only.

Run the preflight in references/conventions.md before the first gh write of a session. If gh is unavailable or unauthenticated, stop and tell the user. Do not fall back to writing spec files locally.

Shared principles

• Inspect the repo and the issue backlog before making claims about project structure, commands, or existing work.
• Use a todo list when the work has multiple steps.
• In Plan, ask focused alignment questions one at a time before drafting the issue. If no factual clarification is needed, ask the user to confirm your framing, assumptions, and acceptance criteria.
• In Plan, propose 2-3 approaches when more than one viable direction exists. If one is clearly best, state the recommendation and wait for approval or redirection.
• Prefer the smallest end-to-end slice a user can see, use, or evaluate over broad unverified changes. “User” includes a human, operator, or API/SDK consumer.
• Decompose epics by demonstrable behavior, not by architecture layer, component, or team. Do not make storage, backend, protocol, frontend, and testing separate roadmap phases when one thin vertical slice can cross them.
• Use a technical-enablement child only when no safe end-to-end slice is feasible without it. Keep it minimal, explain why it cannot be folded into the first slice, and name the user-facing slice it immediately unlocks.
• Require a passing public-boundary E2E test for every user-facing slice and required starting/final screenshots for visual targets.
• Treat video as ideal temporal evidence, not an unbounded gate: make one bounded attempt, then skip and flag the environment/tooling gap when recording remains unavailable.
• Keep scope tied to the selected issue and its acceptance criteria.
• A spec issue is incomplete unless it has an exact ## Acceptance criteria section with observable pass/fail criteria that Build can implement and Verify can test.
• The issue is the spec. Local Markdown exists only as a temporary body file and is removed after the gh write succeeds.
• Every phase transition updates the issue's status:* label. An issue whose label does not match its real state is a triage defect.
• Surface uncertainty instead of filling gaps with guesses.