| name | plan-build-verify |
| description | Use this skill for multi-step, spec-driven, or acceptance-gated implementation work in a GitHub repository where specs live as GitHub Issues. Routes work through Plan, Build, and Verify phases, manages the roadmap through issue labels and sub-issues, and triages and grooms the backlog. Also handles migration from file-based specs to GitHub Issues. |
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, and temporary body files. Every other reference file depends on it.
Phase contracts
| Phase | Input | Output | Status label transition |
|---|
| Plan | Idea, vague request, or new build request | Context exploration → alignment dialogue → approach approval → 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 | 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/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 small, verifiable phases over broad unverified changes.
- 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.
