spec-draft
Skill2 starsChanged 4 months agoMITView on GitHub
Translate the PRD into a spec slice for this repo. Reads the PRD from the meta PRD PR branch or merged develop, extracts capabilities relevant to this repo, drafts docs/specification/product/INIT-*.md locally, and produces a Draft-PR readiness handoff (handoff.forge for open_draft_pr). Publish via /open-draft-pr or orchestrator ForgeClient (spec-pr-action is authorization: automated) — not inside this skill. Run after Gate 1 approval and before /initiative-feasibility.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- inkatze/planwrighttheir own version, first seen Nov 4, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- inkatze/planwright★ 4same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository22 other files it gives its agents.
- ground-specSkill
- initiative-feasibilitySkill
- learning-extractSkill
- loop-specSkill
- pre-implementSkill
- purge-initiative-artifacts-appSkill
- spec-implementation-planSkill
- 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
21 rules. About 0 are common, 5 are distinctive, and 16 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
16
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 40
Every REQ-* must trace to a named PRD CAP-* / REQ-* or section/bullet.
- Distinctive: line 42
Put ambiguities in a "Spec questions" section at the bottom.
- Very specific: line 51
No forge mutations in this skill: Do not create a branch, commit, push, PR, comment, review request, apply labels, create issues, or merge …
- Very specific: line 57
Treat spec-* labels as projections.
- Very specific: line 69
If a codegraph provider is available (MCP tool matching prayog-skills/references/codegraph-tool-contract.md, or a local CLI), prefer it for …
- Very specific: line 93
Dual workspace (orchestrated / Gateflow): when the invocation binds meta_workspace, treat it as the prayog-meta (client-meta) checkout root …
- Very specific: line 126
Write H1–H3 + G1 into the product spec header (see output template).
- Distinctive: line 145
Stop without GitHub side effects.
- Very specific: line 149
Before T5 can emit pass:
- Very specific: line 153
Ask only material questions.
- Very specific: line 158
If any material ambiguity remains unresolved → do not emit pass.
- Very specific: line 174
Check verdicts (PASS/FAIL/NEEDS INPUT) feed this rubric — a FAIL on a blocking check is usually needs-input or blocked, not automatically …
- Very specific: line 180
After T5, always present the PR readiness section from references/output-template.md, including the selected workflow outcome and reason.
- Very specific: line 207
Before /open-draft-pr (or orchestrator forge), spec_pr and Gate 2 fields are pending.
- Distinctive: line 214
When a newer approved impact-map revision appears:
- Distinctive: line 226
After dev reviews the local draft:
- Very specific: line 231
ensure the spec slice is on the Draft spec PR head via /commit-workspace and/or /open-draft-pr / ForgeClient (Forge — not this content …
- Very specific: line 233
run /initiative-feasibility on the published spec on that branch
- Distinctive: line 235
Do not skip the PR-readiness handoff or jump straight to feasibility on a local file only — the Draft spec PR is the engineering review …
- Very specific: line 242
When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before …
- Very specific: line 245
Follow prayog-skills/references/forge-side-effects.md#content-producers — content skill success ≠ PR opened.
≈ “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 draft
Translate the PRD into a spec slice for this repo. The spec slice is the engineering team's interpretation of what the PRD means for their codebase.
Do not implement. Produce docs/specification/product/INIT-{id}.md only.
Why this skill exists
PM writes PRD in feature language. Engineers own the spec.
This skill bridges the gap — it reads the PRD and drafts structured spec
REQ-* rows that the dev team can review, edit, and then run
/initiative-feasibility on.
NON-NEGOTIABLE
- The spec draft is a starting point — dev must review and edit before committing. Do not present it as authoritative without dev review.
- Language in the spec must be engineering terms —
REQ-*, acceptance criteria, module scope — not copied PRD user-story language. Ids followprayog-skills/references/id-conventions.md(REQ-*canonical; legacyFR-*≡ same number). - Scope must be bounded to this repo only. Do not write REQs for other repos.
- Every
REQ-*must trace to a named PRDCAP-*/REQ-*or section/bullet. - Flag anything in the PRD that is ambiguous for this repo — do not guess. Put ambiguities in a "Spec questions" section at the bottom.
- Handoff gate first (Gate 1 / G1 + H1–H3). The canonical impact-map
artifact, source PRD digest (H1), current meta PR head SHA, and
tech-lead APPROVED review must match. A label or old LGTM alone is not
approval. Open
IM-{nn}withBlocking: yesfails closed (D1b) — do not draft the spec until resolved or deferred with default. - This repo must be
affectedin the latest map and not deferred or blocked. Record the repo'sscope_digest(H2) and map revision (H3) in the spec header (H4 citations). If any gate fails: stop. - No forge mutations in this skill. Do not create a branch, commit, push,
PR, comment, review request, apply labels, create issues, or merge here.
Persist the spec locally and fill
handoff.forgereadiness foropen_draft_pr; recommend/open-draft-pror/commit-workspace(or wait for the orchestrator ForgeClient onspec-pr-action). Seeprayog-skills/references/forge-side-effects.md#content-producers. - Treat
spec-*labels as projections. If artifact, review, and label disagree, the gate is closed. Exactly one PE gate label may be active:spec-pending,spec-lgtm, orspec-blocked.spec-revisedandspec-staleare additional invalidation labels and always close the gate. - Ownership boundary. The spec owns observable product behavior,
acceptance, field meaning, invariants, errors, and compatibility. It may
cite existing architectural constraints from
adr_dirbut must not choose implementation architecture. Architecture questions are recorded for feasibility / technical review — not decided here. - Outcome vocabulary. Emit only
pass,needs-input,blocked,stale, orfailed(this stage has nofindingsedge). Map evidence to the outcome rubric below; do not invent lane-specific outcomes. - 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 questions. Always fall back to directsource_rootsreads when unavailable — never block or change outcome selection on its absence. - Carry Capabilities and Journeys. In-scope PRD
CAP-*andJ-{nn}appear in the spec tables (or explicit out-of-repo N/A). Do not drop journeys silently. Live evidence REQs citeCAP-*and/orJ-*when the PRD defines those namespaces (quality-confidence-ladder.md).
Prerequisites
- Meta PRD PR exists (merged or open) with a committed
prd/reports/Impact-Map-{INIT}.md - Latest tech-lead APPROVED review is bound to the current meta PR head SHA carrying that map revision and PRD digest
- This repo is affected in that revision and has a
scope_digest - An existing Draft spec PR is optional when revising; it is not required to
start
/spec-draft
Inputs
Resolve paths from .harness/profile.yaml or references/layout-defaults.md.
Dual workspace (orchestrated / Gateflow): when the invocation binds
meta_workspace, treat it as the prayog-meta (client-meta) checkout root for
PRD and impact-map reads. Treat bound workspace as this app repo root for
product spec writes (docs/specification/…). Do not invent a meta path when
meta_workspace is empty; do not write product decisions only into meta unless
procedure explicitly says so.
- PRD — (REQUIRED) from
<client>-meta/prd/INIT-*.mdundermeta_workspacewhen bound (else resolve meta checkout as today). Read from the meta PRD PR branch or mergeddevelop. Do not assume PRD is on develop if PR is still open — use PR branch when iterating in parallel. - Impact map — (REQUIRED) canonical
<client>-meta/prd/reports/Impact-Map-{INIT}.mdfrom the exact approved meta PR head (undermeta_workspacewhen bound); PR comments are summaries only. - Approval evidence — (REQUIRED) meta PR number/URL, current head SHA, and
latest tech-lead APPROVED review
commit_id; all must match. - As-built —
implementation-status.md(REQUIRED) underworkspace— understand what already exists before writing FRs. - Source —
source_rootsfrom profile — understand current module structure. - Service profile —
docs/specification/product/00-service-profile.mdif it exists — understand the repo's existing domain. adr_dir— existing ADRs constrain what this spec can propose.- Layout —
.harness/profile.yamlor references/layout-defaults.md - Codegraph provider — OPTIONAL — see
prayog-skills/references/codegraph-tool-contract.md
Process
- T0 Gather and gate — PRD, canonical impact map, approval review, as-built,
source, service profile. Verify full Gate 1 and mint H4 citations:
- current meta PR head SHA = approved review
commit_id(G1) - impact-map
source_prd_digest= digest of the PRD read (H1) - impact-map
map_revision/ path = approval attestation (H3) - this repo is affected, not deferred/blocked, with a
scope_digest(H2) Write H1–H3 + G1 into the product spec header (see output template). Stop on any mismatch.stale= authority drift on these identities — not mid-lane report digests.
- current meta PR head SHA = approved review
- T1 Understand — initiative id; approved map revision and scope digest; what capabilities land in this repo; what already exists (as-built + source scan)
- T2 Scope — list ONLY what this repo owns. Explicitly exclude what belongs to other repos. Cross-service contracts are noted but not spec'd here.
- T3 Draft — write INIT-*.md using references/output-template.md
- T4 Flag and clarify — list ambiguities and open questions. Before any
passattempt, run the bounded clarification loop below. - T5 Verify and hand off — run D1–D12 from
references/checks.md; select the workflow outcome
from the rubric; present in chat:
- generated/changed files,
- gate verification summary,
- spec summary and open questions,
- selected workflow outcome + reason,
- proposed branch, base, Draft PR title/body, reviewers, and initial labels,
PR READYorPR BLOCKEDverdict (PR READY only when outcome ispass). Stop without GitHub side effects.
Bounded clarification loop (before pass)
Before T5 can emit pass:
- Classify every open Spec question as material (blocks acceptance or scope) or non-blocking (safe default + revisit trigger).
- Ask only material questions; write each accepted answer into the owning
REQ-*/ acceptance / NFR / contract row — do not leave answers only in chat. - Preserve unresolved non-blockers with owner, default-if-deferred, and revisit trigger (D6).
- Rerun affected D-checks after incorporating answers.
- If any material ambiguity remains unresolved → do not emit
pass; selectneeds-inputorblockedper the outcome rubric.
Outcome selection (workflow edges)
Map evidence to exactly one outcome declared for spec-draft in pinned
workflow.yaml. Do not emit findings or skipped from this stage.
| Outcome | When | Next (from workflow) |
pass | D1–D12 PASS, zero unresolved material questions, PR READY, sources CURRENT | spec-pr-action |
needs-input | Required handoff/source input missing or unreadable; or material PM/domain ambiguity remains after the clarification loop | spec-human-decision |
blocked | Explicit gate closure (approval/label/artifact disagree; repo deferred/blocked; PE gate closed) | spec-human-decision |
stale | Authority drift: H1–H3 / G1 / head mismatch vs approved handoff | prd-impact-map |
failed | Execution/render error on otherwise valid inputs | workflow-stop |
Check verdicts (PASS/FAIL/NEEDS INPUT) feed this rubric — a FAIL on a blocking
check is usually needs-input or blocked, not automatically failed.
Permit complete handoff.forge for open_draft_pr only on pass.
PR readiness (fill handoff.forge — do not open the PR here)
After T5, always present the PR readiness section from
references/output-template.md, including the
selected workflow outcome and reason. On outcome: pass, next node is
spec-pr-action (open_draft_pr). Fill handoff.forge with pin requires
at minimum:
action: open_draft_prdraft: trueapply_labels: [spec-pending](match pin; never*-lgtm)title,body_path(and any other pinrequires)
Recommend /commit-workspace when local publication is needed. On pass, next
is spec-pr-action with pin authorization: automated — Gateflow ForgeClient
opens the Draft PR without interactive STOP when requires are complete. Human
walkers may still run /open-draft-pr after user confirm. Do not run forge
mutations inside /spec-draft. If Forge tooling is unavailable, readiness in
the handoff is still the durable package for a later forge skill or Gateflow
ForgeClient.
See prayog-skills/references/forge-side-effects.md.
Output
Draft saved to {product_spec_dir}/INIT-{id}.md (from profile).
Use references/output-template.md.
Before /open-draft-pr (or orchestrator forge), spec_pr and Gate 2 fields
are pending. After the authorized forge skill / ForgeClient run, the PR body
contains the spec summary, artifact path, meta handoff digests, Gate 2
checklist, and PE review request.
Revision handling
When a newer approved impact-map revision appears:
- Same repo
scope_digest: record the new revision check; existing spec may continue if its PRD digest is unchanged. - Changed
scope_digest: mark this spec stale, revise affected sections, and re-run/initiative-feasibility. - Repo removed/deferred/blocked: stop and mark the spec PR held or out of scope.
- Dependency/order-only change: update cross-service dependencies and invalidate the implementation plan when ordering changes.
Next step
After dev reviews the local draft:
- on
pass/PR READY, let the orchestrator executespec-pr-action(authorization: automated), or authorize and run/open-draft-pras a human walker - ensure the spec slice is on the Draft spec PR head via
/commit-workspaceand/or/open-draft-pr/ ForgeClient (Forge — not this content skill) - run
/initiative-feasibilityon the published spec on that branch
Do not skip the PR-readiness handoff or jump straight to feasibility on a local file only — the Draft spec PR is the engineering review surface for the whole lane.
Workflow handoff
- Append/emit the envelope from
prayog-skills/references/handoff-envelope.mdto the saved spec. Use stagespec-draft. - 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_candidates,human_checkpoint, andexternal_actionfrom pinned rootworkflow.yamlfor(stage: spec-draft, outcome)perprayog-skills/references/handoff-envelope.md(Derive from pinned workflow). Sethuman_checkpoint: trueonly when the resolved next node'stypeishuman-checkpoint. Setexternal_action: truewhen next isexternal-action(e.g.spec-pr-actiononpass). - On
pass, fill completehandoff.forgeforopen_draft_prper pinrequires(prayog-skills/references/forge-side-effects.md#content-producers). Orchestrator:spec-pr-actionisauthorization: automated. Human walker: recommend/open-draft-prafter confirm. - Follow
prayog-skills/references/forge-side-effects.md#content-producers— content skill success ≠ PR opened.
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.
Record D-check findings and source freshness under blockers/signals.
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.

