Cy Spec Preflight

Spec Preflight

Authors of AGH PRDs, TechSpecs, and _tasks.md repeatedly produce drafts that miss project-specific directives — frameworks named in PRDs, prose-only TechSpecs, "fraco" test coverage. This skill loads project memory before handing off to cy-create-prd, cy-create-techspec, or cy-create-tasks, then runs the relevant post-draft checks before approval.

Required Inputs

• phase (optional): one of prd, techspec, tasks, or task-body. When omitted, infer from the active cy-create-* skill or from the artifact path (_prd.md, _techspec.md, _tasks.md, task_NN.md).

Procedures

Step 1: Load Project Memory

1. Read docs/_memory/spec-authoring-playbook.md in full.
2. Read docs/_memory/standing_directives.md (SD-001..SD-011).
3. Read docs/_memory/glossary.md (vocabulary discipline — capability vs recipe, AGH is/is-not).
4. Read the matching lessons by phase. Read references/phase-lessons.md for the phase → lesson mapping.
5. Read CLAUDE.md Authoring Posture, Architecture Principles, Autonomy Contracts, Security Invariants sections.

Step 2: Load Active Project Context

1. Resolve the active task slug: the .compozy/tasks/<slug>/ directory the artifact targets.
2. If a _techspec.md exists at the slug, read it before authoring tasks.
3. If adrs/*.md exist, read every one before authoring techspec/tasks.
4. If analysis/*.md exist under the slug, read before authoring techspec.
5. If a prior phase artifact exists (PRD before TechSpec, TechSpec before Tasks), read it.

Step 3: Apply Phase-Specific Checks

Phase-specific checks below. Run only the relevant block. Use the "before authoring" checks before the inner skill writes a draft, and the "after draft" checks before user approval.

Phase: prd

1. Read references/prd-checks.md.
2. Before authoring, confirm the active idea is framed as WHAT/WHY/WHO and not implementation detail.
3. After the draft is produced, run python3 scripts/check-prd-implementation-leak.py <prd_path> to surface framework/storage/error-code/file-format names. Strip every match unless the PRD is about the named technology.
4. Confirm the PRD lists explicit Goals, Non-Goals, Success Metrics, and Open Questions using the canonical cy-create-prd template.
5. Confirm the PRD states the agent/operator manageability outcome and extension ecosystem expectation without naming implementation details.
6. Do not invoke cy-spec-peer-review for PRDs. Peer review is TechSpec-only and user-directed.

Phase: techspec

1. Read references/techspec-six-markers.md.
2. After draft is produced, run python3 scripts/check-techspec-markers.py <techspec_path> to verify the six markers are present.
3. Confirm "No fallback / no compat shim / no placeholder" clauses are present where breaking changes apply.
4. Confirm Test Plan is per-section bullet list with concrete assertions and verification commands.
5. Confirm Public Interfaces / Types section enumerates routes, payloads, CLI verbs, config keys.
6. Confirm Extensibility Integration Plan enumerates extension manifests, hooks, skills/capabilities, tools/resources, bundles, registries, bridge SDKs, MCP sidecars, and protocol docs that are added/changed/removed or explicitly unaffected.
7. Confirm Agent Manageability Plan enumerates CLI verbs, HTTP endpoints, UDS routes, structured outputs, status/config discovery, and deterministic errors agents will use.
8. Confirm Config Lifecycle section enumerates config.toml keys/defaults, merge/overlay behavior, validation, examples, generated CLI/site docs, and tests that are added/changed/removed or explicitly unaffected.
9. Confirm Assumptions/Defaults section closes the spec.
10. Confirm Web/Docs Impact is captured if any contract surface is touched (activate cy-web-docs-impact).
11. After the user approves the baseline TechSpec draft and it has been saved, offer cy-spec-peer-review. Invoke it only if the user explicitly opts in.

Phase: tasks

1. Read references/tasks-checks.md.
2. Confirm the table column order matches cy-create-tasks: # | Title | Status | Complexity | Dependencies.
3. Confirm an MVP Boundary statement above the table.
4. Confirm Dependencies column is populated for every row.
5. Confirm Complexity is rated low | medium | high | critical, with QA execution and safety primitives marked high/critical as appropriate.
6. Confirm last two rows are qa-report (high) + qa-execution (critical) per cy-tasks-tail-qa-pair.
7. Confirm Web/Docs Impact subsection exists in every backend task body (activate cy-web-docs-impact to populate).
8. Confirm Extensibility / Agent Manageability / Config Lifecycle subsections exist in every feature-bearing backend task body.
9. Confirm test density is proportional to behavior count per task. Reject "fraco" plans (1-2 tests for many behaviors).
10. Confirm .resources/<competitor>/path references are cited per task when the TechSpec drew on competitors.
11. Confirm no TBD / placeholder rows.

Phase: task-body

1. Confirm <critical>ALWAYS READ _techspec.md ...</critical> block at the top.
2. Confirm <critical>MINIMIZE CODE, TESTS REQUIRED, NO WORKAROUNDS</critical> block.
3. Confirm Files / Surfaces section enumerates touched files.
4. Confirm Tests section enumerates assertions covering happy path + failure paths + concurrency stress + contract redaction (when relevant).
5. Confirm Web/Docs Impact subitem.
6. Confirm Extensibility / Agent Manageability / Config Lifecycle subitem.
7. Confirm References section cites .resources/<competitor>/path paths from the TechSpec.

Step 4: Coordinate With the Inner Skill

1. Before authoring checks pass: hand off to the inner cy-create-* skill.
2. The inner skill produces the artifact; this preflight skill is not the author.
3. After the draft exists: run the after-draft checks above before user approval or task execution.

Error Handling

• Phase cannot be inferred: ask the user explicitly. Do not guess.
• Playbook missing: halt. The playbook is mandatory context. Direct the user to restore from git or re-run the synthesis.
• scripts/check-*.py fail with structural errors: the artifact does not match the expected shape. Surface the path that broke; do not auto-fix.
• PRD names AGH-Network wire format: allowed exception per lessons/L-013 — confirm with user before stripping.
• TechSpec missing markers: do not let the user skip. Pedro will reject the spec; resolve missing markers first.
• _tasks.md missing QA pair: auto-invoke cy-tasks-tail-qa-pair to repair.
• _tasks.md missing Web/Docs Impact subitems: auto-invoke cy-web-docs-impact to populate.
• TechSpec/task lacks extensibility, agent-manageability, or config lifecycle analysis: block approval until the artifact names the impacted surfaces or gives explicit no-impact evidence.