spec-implementation-plan
Skill2 starsChanged 4 months agoMITView on GitHub
After feasibility (and technical review when applicable), produce a wave-level implementation plan with REQ/TASK/FILE/TEST tables and a WorkManifest YAML seed section (§9). Runs while the spec PR is open, before spec merge. Board seeding (gh issue create) happens after spec PR merge — not before.
In this repository22 other files it gives its agents.
- ground-specSkill
- initiative-feasibilitySkill
- learning-extractSkill
- loop-specSkill
- pre-implementSkill
- purge-initiative-artifacts-appSkill
- spec-draftSkill
- spec-technical-reviewSkill
- ensure-repo-graphSkill
- post-product-questionsSkill
- prd-codebase-mapSkill
- review-product-questionsSkill
- commit-workspaceSkill
- create-board-ticketsSkill
- open-draft-prSkill
- prd-impact-mapSkill
- prd-qualitySkill
- prd-thinkSkill
- purge-initiative-artifacts-metaSkill
- review-findingsSkill
- update-documentsSkill
- validate-requirementsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 7 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 33
Never skip a check in references/checks.md.
- Distinctive: line 34
Every TASK has objective exit evidence: observable exit criteria, proving command or review, expected result, and evidence location — plus …
- Distinctive: line 39
Every acceptance criterion maps to a verification layer (unit, integration/contract, smoke, or sandbox) in the wave Verification Coverage …
- Distinctive: line 43
Run T0–T5 control loop.
- Very specific: line 46
Every TASK row must include codebase, spec_path, verify_command,
- Distinctive: line 71
Before coding-readiness, run a read-only cross-artifact consistency pass (spec ↔ plan REQ ids, plan ↔ §9 WorkManifest, Accepted ADR …
- Very specific: line 88
If a codegraph provider is available (MCP tool matching prayog-skills/references/codegraph-tool-contract.md, or a local CLI), prefer it for …
- Distinctive: line 100
Do not invent a meta path when empty.
- Distinctive: line 124
Run while the Draft spec PR is open, before spec merge, after:
- Very specific: line 171
Check FAIL is not automatically failed — classify per the table (P12/P13 Draft ADR → blocked.
- Very specific: line 192
When authoring §9, set target.org and target.project from governance (project_board.name in {meta_repo}/config/governance-*.yaml).
- Very specific: line 199
When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before …
- Very specific: line 203
Follow prayog-skills/references/forge-side-effects.md#content-producers when this stage's pin has forge.commit_workspace other than …
- Very specific: line 211
After the spec PR is merged, the workflow selects board-tickets-action (external-action, forge.action: create_board_tickets).
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Spec implementation plan
Turn an accepted initiative spec (+ feasibility report + technical review when present) into an executable plan with a WorkManifest artifact (§9). Do not implement — plan only.
Persist the plan locally and emit Forge readiness for the spec PR branch
alongside spec, feasibility, and TDD. Table shape borrowed from awesome-copilot
create-implementation-plan (REQ/TASK/FILE/TEST/RISK). §9 WorkManifest YAML is
generated here; dev seeds the board after spec PR merge.
Prayog owns the WorkManifest contract (apiVersion: prayog/v1,
prayog-skills/references/workmanifest-contract.md). Launchpad only materializes the pin —
it does not own, parse, or execute WorkManifest.
NON-NEGOTIABLE
- Never skip a check in references/checks.md. Mark SKIPPED with reason.
- Every TASK has objective exit evidence: observable exit criteria, proving
command or review, expected result, and evidence location — plus an
Implements list of product
REQ-*ids and toolchain commands where applicable. Do not invent shadowREQ-W*ids — seeprayog-skills/references/id-conventions.md. - Every acceptance criterion maps to a verification layer (unit, integration/contract, smoke, or sandbox) in the wave Verification Coverage table. Plan scope must not exceed the initiative spec.
- Dual output: chat summary + saved plan file (local + Forge readiness).
- Run T0–T5 control loop.
- Wave IDs must use
W0,W1, … (one GitHub Issue per wave; WorkManifestid:convention). - Every TASK row must include
codebase,spec_path,verify_command, ImplementsREQ-*,depends_on, file path/action scope, and exit proof fields — required for WorkManifest generation. §9 wave entries must includetasks[],verification, and a body table listing those TASK ids. - Spec product-spec H1–H3 citations (and G1 when applicable) must agree
with live handoff; tip continuous. Stop on authority drift. Feas/TDD file
digests are walk-time only — not long-term
staleSSOT. Implementation-Plan is walk-time (§9 → board); may be purged at initiative closure. - Resolve canonical
check_command,test_command,verify_command, andground_commandbefore planning. Required commands may come from the consumer profile,AGENTS.md, ortests_readme; missing required commands block the plan.verify_commandis the live script entry underlive_verify_dir— never{test_command}/ unit-only. Use N/A with reason only when a layer is not applicable. When P15 applies (new/material product surface), bare N/A or unit-as-live is invalid — co-ship the verify FILE and fixture pack path(s) underfixtures_dirfor the capability (CAP-*) and/or journey (J-*) rung being shipped (see references/checks.md P15;prayog-skills/references/live-fixture-contract.md). - Persist the plan locally and fill
handoff.forgefor/commit-workspaceonto the same Draft spec PR. Do not commit, push, branch, open PRs, apply labels, create issues, or merge inside this skill. Coding-readiness label staysspec-pending. After T5, present the coding-readiness unlock checklist from the output template so PE knows when to setspec-lgtm. - Select workflow outcome from the rubric below; map evidence deterministically.
- Before coding-readiness, run a read-only cross-artifact consistency pass (spec ↔ plan REQ ids, plan ↔ §9 WorkManifest, Accepted ADR citations). Corrections belong in the owning artifact — do not invent a parallel truth in chat.
- Live-verify coverage lives in the artifact's own marker, not in
tests/README.mdor as a growing table inimplementation-status.md— seeprayog-skills/references/live-verify-coverage-contract.md. Run the required overlap check (P15) via--capability/--journey/--reqbefore declaring a newlive_verify_diror fixture FILE.coversmust include relevantCAP-*and/orJ-*(plusREQ-*). As-built writes go toImplementation-Status-{INIT}.md(detail) + one index row inimplementation-status.md(pointer) — never a new table appended to the shared index. - Capability ≠ journey. Plan separate prove artifacts/
coverswhen both rungs ship; do not collapse journey proof into “all CAP journeys passed”. Populatedependencies,fixtures, andhuman_observationswhen opaque (logs alone are not pass evidence). - If a codegraph provider is available (MCP tool matching
prayog-skills/references/codegraph-tool-contract.md, or a local CLI), prefer it for architecture/impact/coverage questions. Always fall back to directsource_rootsreads when unavailable — never block or change outcome selection on its absence.
Inputs
Resolve paths from .harness/profile.yaml or references/layout-defaults.md.
Dual workspace: workspace = app coding root (plan / WorkManifest).
meta_workspace when bound = meta checkout for PRD / impact-map freshness.
Do not invent a meta path when empty.
- Initiative spec — on spec branch (REQUIRED)
- Feasibility report — if exists (RECOMMENDED)
- Technical review —
Technical-Review-{initiative}.md(REQUIRED). The pin always routes feasibility (passorfindings) into/spec-technical-reviewbefore planning — a genuinely absent file is a stale/skipped-stage condition (needs-input), not an optional input. A clean feasibility run may still produce a light-confirmation TDD with zero ADRs — that is a valid, present file, not the same thing as no file existing. Do not treat "noNEW-ADRfindings" as license to skip reading this file. - As-built, tests_readme, live_verify_dir layout (REQUIRED for test tasks)
- Layout —
.harness/profile.yamlor references/layout-defaults.md rules_glob— workspace MDC rules (REQUIRED). Read before T2 Analyze.adr_dir— architecture decision records (REQUIRED). Run relevant-ADR pass per references/governance.md before T2 Analyze.- Canonical handoff references — product-spec H1–H3 (+ G1 when applicable)
(REQUIRED; resolve under
meta_workspacewhen bound) - Command contract — canonical check, test, live verify (
verify_command), and ground commands or explicit N/A rationale (REQUIRED) - Codegraph provider — OPTIONAL — see
prayog-skills/references/codegraph-tool-contract.md
Prerequisite
Run while the Draft spec PR is open, before spec merge, after:
- Feasibility accepted (no blocking PM questions on meta PRD PR)
/spec-technical-reviewcompleted (pin always routes feasibility → TDD)technical-review-approvalsatisfied in files — TDDStatus: Acceptedand every required ADR file in{adr_dir}isAcceptedon the current head- Product-spec H1–H3 citations and approval references are CURRENT (authority, not feas/TDD digests as SSOT)
Artifact gate vs GitHub gate Planning requires Accepted TDD/ADR files (P12/P13). It does not require
spec-lgtm. PE setsspec-lgtm+ GitHub Approve + attestation only after this plan is published via Forge — that unlocks merge and/create-board-tickets.
Process
- T0 Gather and freshness gate — spec waves, feasibility findings, technical review, H1–H3 / G1 references, command contract, repo layout; stop if durable authority is stale or a required command is unresolved
- T1 Understand — initiative id, wave boundaries, PR granularity from spec
- T2 Analyze — map each wave to concrete files and tests; cross-reference
rules_globand relevant ADRs; flag spec wording that conflicts with MDC patterns or Accepted ADRs as MDC notes / ADR notes in the TASK table - T3 Plan — build REQ/TASK/FILE tables per wave; verify every TDD §4
ADR_REQUIREDrow links an Accepted file in{adr_dir}(created by/spec-technical-review, accepted during PE review — do not add promotion tasks); cite those ADR ids in TASK ADR notes; collectcodebase/spec_path/verify_command/depends_on/files/exit per TASK; map each acceptance criterion to a verification layer - T4 Execute — write plan; build WorkManifest seed section (
prayog/v1); run P1–P16 checks including shared validator; persist locally and fill Forge readiness (do not commit here) - T5 Verify — self-contained plan readable by a fresh session; WorkManifest contract passes; read-only cross-artifact consistency; select workflow outcome; present coding-readiness unlock checklist (§10) in chat for PE
Outcome selection (workflow edges)
Map evidence to exactly one outcome declared for spec-implementation-plan in
pinned workflow.yaml (this stage has no findings edge):
| Outcome | When | Next (from workflow) |
pass | P1–P16 PASS; sources CURRENT; Accepted TDD/ADRs when required; plan ready for coding-readiness | coding-readiness |
needs-input | Authoritative source is absent or unreadable, so the requirement cannot be determined | spec-human-decision |
blocked | Authoritative source exists and shows an unsatisfied gate: Draft ADR, unaccepted TDD, missing PE approval, or unresolved blocker (P12/P13 FAIL) | spec-human-decision |
stale | Product-spec H1–H3 / G1 / tip authority drift | initiative-feasibility |
failed | Rendering/validation failure, or P4/P15/P16 contract failures (vague exit, dependency cycle, missing proof/live, unit-as-live) on otherwise present inputs | workflow-stop |
Check FAIL is not automatically failed — classify per the table (P12/P13 Draft
ADR → blocked; missing unreadable source → needs-input; mismatch → stale;
WorkManifest/exit/live contract → failed).
Output
Save to {reports_dir}/{plan_prefix}-{initiative}.md.
Use references/output-template.md.
WorkManifest integration
The plan's final section (§9) emits a ready-to-use WorkManifest YAML stub under
the Prayog contract (prayog-skills/references/workmanifest-contract.md). Validate
with scripts/workmanifest_contract.py before claiming P16 PASS.
After spec PR merge — not before — run /create-board-tickets (forge skill,
stack-agnostic). That skill reads §9, governance board binding from read-only
meta, creates EPIC + wave sub-issues on the programme Project, and hands off to
/pre-implement. Board text is a projection, not a second authority.
When authoring §9, set target.org and target.project from governance
(project_board.name in {meta_repo}/config/governance-*.yaml). Do not invent
board names. Do not put mutable board status or runtime evidence in §9.
Workflow handoff
- Append/emit the envelope from
prayog-skills/references/handoff-envelope.mdto the plan. Use stagespec-implementation-plan. - When the invocation binds
handoff_path(orchestrator / AgentRunner baton), also overwrite that path with the samehandoff:envelope before exit. Leaving the baton empty is a failed stage for automated consumers.artifact.pathremains the workspace skill output, not the baton path. Seeprayog-skills/references/handoff-envelope.md(Orchestrator baton). - Derive
next_candidatesandhuman_checkpointfrom pinned rootworkflow.yamlfor(stage: spec-implementation-plan, outcome)perprayog-skills/references/handoff-envelope.md(Derive from pinned workflow). Sethuman_checkpoint: trueonly when the resolved next node'stypeishuman-checkpoint— never because the artifact "should be reviewed." - Follow
prayog-skills/references/forge-side-effects.md#content-producerswhen this stage's pin hasforge.commit_workspaceother thandisabledor next is anexternal-actionwithforge.requires— fillhandoff.forge/ recommend the matching/forgeskill; do not treat local CLI as skill success.
Transitions: pinned root workflow.yaml for this stage (SSOT). Human or
agent may run this skill; legality and auto-dispatch follow dispatch +
delivery contract + latest handoff. pass resolves to human-checkpoint
coding-readiness (purpose: coding-readiness), then authorized spec-merge.
After the spec PR is merged, the workflow selects board-tickets-action
(external-action, forge.action: create_board_tickets); humans run
/create-board-tickets. Planning does not seed the board itself.
next_candidates never authorize invoke.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

