ground-spec
Skill2 starsChanged 4 months agoMITView on GitHub
Validate a completed wave against REQs assigned to that wave by the plan / WorkManifest, plus repo artifacts and cross-spec contracts. Produces a Ground Report (GF-* findings) including Contracts Produced for next-wave pre-implement. Writes locally and emits Forge readiness — never commits or merges. Use after Pass-2 learning-extract (closes the wave), before wave-done-action / human wave-signoff (merge only).
In this repository22 other files it gives its agents.
- initiative-feasibilitySkill
- learning-extractSkill
- loop-specSkill
- pre-implementSkill
- purge-initiative-artifacts-appSkill
- spec-draftSkill
- 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
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 2 are distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 39
Run the repo's automated ground check when {ground_command} is defined in the harness profile.
- Very specific: line 43
Check every REQ-* assigned to this wave via plan / WorkManifest TASK rows — map each to a verifiable artifact (test result, entry point, …
- Distinctive: line 52
Check cross-spec contracts: modules from this wave may only consume interfaces from prior waves as documented in those waves' Ground …
- Distinctive: line 54
Check boundary rules per ADRs and domain-filtered MDC rules (G5/G6).
- Very specific: line 65
Write Ground Report and as-built updates locally.
- Very specific: line 73
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 136
When the invocation binds handoff_path (orchestrator / AgentRunner baton), also overwrite that path with the same handoff: envelope before …
- Very specific: line 146
Follow prayog-skills/references/forge-side-effects.md#content-producers when this stage's pin has forge.commit_workspace other than …
≈ “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
Ground spec
Validate implementation against the product spec REQs assigned to this
completed wave (plan / WorkManifest TASK implements lists) and actual
repo artifacts — not every future REQ in the full product spec, and not PRD
text alone. Produce a Ground Report that the next wave's /pre-implement
consumes as a contract baseline.
Content skills write locally and emit Forge readiness; they do not commit, push, branch, open PRs, label, create issues, or merge.
Canonical artifact:
{reports_dir}/Ground-Report-{SPEC}-W{N}.md
(prayog-skills/references/artifact-write-contract.md).
Checks: references/checks.md (G1–G10).
Ids: prayog-skills/references/id-conventions.md (GF-* for findings).
NON-NEGOTIABLE
- Resolve paths from
.harness/profile.yamlor references/layout-defaults.md. Includetests/**in scope when mapping evidence. - Run the repo's automated ground check when
{ground_command}is defined in the harness profile. Include full output in the report. If{ground_command}is not defined, perform manual REQ validation by readingsource_rootsandtests/**directly. - Check every
REQ-*assigned to this wave via plan / WorkManifest TASK rows — map each to a verifiable artifact (test result, entry point, module boundary, verify script output). Do not require coverage of REQs owned only by future waves. Use engineering terms: "entry point", "module boundary", "output shape" — not language-specific terms. - Consume approved plan/manifest intent plus actual loop/unit evidence
and human accept (
Wave-Execution-*, unit results,wave-accepted/ wave-acceptance). Optional/legacyLive-Verify-*is not required. Cite layers separately. - Check cross-spec contracts: modules from this wave may only consume interfaces from prior waves as documented in those waves' Ground Reports.
- Check boundary rules per ADRs and domain-filtered MDC rules (G5/G6).
- Do not mark spec
human_approved— already set atwave-acceptance(only approval signal). This skill prepares the merge package forwave-signoff(merge/publish only). - Populate the Contracts Produced section — structured handoff for
/pre-implementof the next wave. Without it, the chain is broken. - Cite learning ids — when
{reports_dir}/Learning-Extract-{initiative}-W{N}.mdexists, add a Learning cited table ofL-*ids (do not re-author learning SSOT). - Discrepancy / blocker ids use stable
GF-*— citeREQ-*in the row, not as the blocker primary key. Do not reuse feasibilityFF-*. - Write Ground Report and as-built updates locally; prepare the
exact-head merge package for
wave-signoff; pin routes towave-done-actionthenwave-signoff(merge only). Never commit or merge from this skill. As-built writes follow the split inprayog-skills/references/artifact-write-contract.md—Implementation-Status-{INIT}.mdfor detail, one index row inimplementation-status.mdfor the pointer; never append a new table to the shared index. - If a codegraph provider is available (MCP tool matching
prayog-skills/references/codegraph-tool-contract.md, or a local CLI), prefer it for cross-spec contract / boundary questions. Always fall back to directsource_rootsreads when unavailable — never block or change outcome selection on its absence.
Outcome selection
| Outcome | When |
pass | G1–G10 satisfied (or SKIPPED with reason); no open Blocking GF-*; Contracts produced complete; exact-head sign-off package ready |
findings | One or more GF-* require code/spec fix before sign-off |
needs-input | Authoritative wave assignment, evidence, or prior Ground Report absent/unreadable |
blocked | Gate prevents grounding (e.g. Pass-1 incomplete, missing accept when required) |
failed | Execution error running ground command or writing the report |
Happy path: pass → wave-done-action → wave-signoff.
Chain position
Illustrative only — transitions SSOT: pinned root workflow.yaml
(dispatch: orchestrated on this node). Closeout path: learning-extract
→ this skill → wave-done-action → wave-signoff. Pass-1 does not route here from loop-spec.
/learning-extract (Pass-2 / Enter-at)
↓
/ground-spec ← YOU ARE HERE
produces: Ground-Report-W{N}.md
└── §Contracts produced ← pre-implement for WN+1 reads this
└── cites L-* from Learning-Extract when present
└── GF-* findings (not FF-*)
↓
wave-done-action (Forge update_board_status → Done)
human checkpoint wave-signoff (exact head; merge/publish only)
→ human_approved already from wave-acceptance; record merge SHA
↓
/pre-implement (next wave)
reads: Ground-Report-W{N}.md §Contracts producedRead order
AGENTS.md- Plan / WorkManifest wave section — assigned REQ set for W{N}
- Product spec:
docs/specification/product/— only rows for assigned REQs docs/specification/as-built/implementation-status.mdWave-Execution-{INIT}-W{N}.md; accept signal (wave-accepted/ wave-acceptance); optional/legacyLive-Verify-*when present- Ground reports of prior waves (for cross-spec contract baseline)
- Codegraph provider — OPTIONAL — see
prayog-skills/references/codegraph-tool-contract.md - Relevant ADRs + domain-filtered MDC
- Ground check output (
{ground_command}) + unit verification ({test_command}) Learning-Extract-{INIT}-W{N}.mdwhen present
Output format
Save report to {reports_dir}/Ground-Report-{SPEC}-W{N}.md using
references/output-template.md. Run
references/checks.md.
Workflow handoff
- Append/emit the envelope from
prayog-skills/references/handoff-envelope.mdto the saved Ground Report. Use stageground-spec. - 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: ground-spec, 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." - Happy path:
outcome: pass→ nextwave-done-action(type: external-action,forge.action: update_board_status,authorization: automated) →human_checkpoint: false,external_action: true. Fillhandoff.forgeticketwhen bound so ForgeClient can apply Done. Then pin routes towave-signoff(human merge/publish only). Do not copyhuman_checkpoint: trueinto earlier implement-lane skills on skill→skill edges. - 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; orchestrators may auto-dispatch when authorized.
Same legality for both invoke paths.
handoff:
contract: sdd-delivery/v2
stage: ground-spec
outcome: {pass | findings | needs-input | blocked | failed}
artifact:
path: {reports_dir}/Ground-Report-{SPEC}-W{N}.md
# digest omitted — walk-time PURGE report, not a durable identity
blockers: [] # GF-* when findings
signals:
wave: W{N}
contracts_produced: {count}
assigned_reqs: [...]
next_candidates:
# Must match workflow.yaml for outcome — typically wave-done-action
- wave-done-action
human_checkpoint: false
external_action: true
forge:
action: update_board_status
ticket: {bound_wave_ticket}The Ground Report is not complete without this handoff. Outcome routes follow
workflow.yaml (not hardcoded elsewhere). 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.

