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
- Read
docs/_memory/spec-authoring-playbook.md in full.
- Read
docs/_memory/standing_directives.md (SD-001..SD-011).
- Read
docs/_memory/glossary.md (vocabulary discipline — capability vs recipe, AGH is/is-not).
- Read the matching lessons by phase. Read
references/phase-lessons.md for the phase → lesson mapping.
- Read
CLAUDE.md Authoring Posture, Architecture Principles, Autonomy Contracts, Security Invariants sections.
Step 2: Load Active Project Context
- Resolve the active task slug: the
.compozy/tasks/<slug>/ directory the artifact targets.
- If a
_techspec.md exists at the slug, read it before authoring tasks.
- If
adrs/*.md exist, read every one before authoring techspec/tasks.
- If
analysis/*.md exist (e.g., from cy-research-competitors), read before authoring techspec.
- 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
- Read
references/prd-checks.md.
- Before authoring, confirm the active idea is framed as WHAT/WHY/WHO and not implementation detail.
- 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.
- Confirm the PRD lists explicit Goals, Non-Goals, Success Metrics, and Open Questions using the canonical
cy-create-prd template.
- Confirm the PRD states the agent/operator manageability outcome and extension ecosystem expectation without naming implementation details.
- Do not invoke
cy-spec-peer-review for PRDs. Peer review is TechSpec-only and user-directed.
Phase: techspec
- Read
references/techspec-six-markers.md.
- After draft is produced, run
python3 scripts/check-techspec-markers.py <techspec_path> to verify the six markers are present.
- Confirm "No fallback / no compat shim / no placeholder" clauses are present where breaking changes apply.
- Confirm Test Plan is per-section bullet list with concrete assertions and verification commands.
- Confirm Public Interfaces / Types section enumerates routes, payloads, CLI verbs, config keys.
- 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.
- Confirm Agent Manageability Plan enumerates CLI verbs, HTTP endpoints, UDS routes, structured outputs, status/config discovery, and deterministic errors agents will use.
- 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.
- Confirm Assumptions/Defaults section closes the spec.
- Confirm Web/Docs Impact is captured if any contract surface is touched (activate
cy-web-docs-impact).
- 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
- Read
references/tasks-checks.md.
- Confirm the table column order matches
cy-create-tasks: # | Title | Status | Complexity | Dependencies.
- Confirm an MVP Boundary statement above the table.
- Confirm Dependencies column is populated for every row.
- Confirm Complexity is rated
low | medium | high | critical, with QA execution and safety primitives marked high/critical as appropriate.
- Confirm last two rows are
qa-report (high) + qa-execution (critical) per cy-tasks-tail-qa-pair.
- Confirm Web/Docs Impact subsection exists in every backend task body (activate
cy-web-docs-impact to populate).
- Confirm Extensibility / Agent Manageability / Config Lifecycle subsections exist in every feature-bearing backend task body.
- Confirm test density is proportional to behavior count per task. Reject "fraco" plans (1-2 tests for many behaviors).
- Confirm
.resources/<competitor>/path references are cited per task when the TechSpec drew on competitors.
- Confirm no TBD / placeholder rows.
Phase: task-body
- Confirm
<critical>ALWAYS READ _techspec.md ...</critical> block at the top.
- Confirm
<critical>MINIMIZE CODE, TESTS REQUIRED, NO WORKAROUNDS</critical> block.
- Confirm Files / Surfaces section enumerates touched files.
- Confirm Tests section enumerates assertions covering happy path + failure paths + concurrency stress + contract redaction (when relevant).
- Confirm Web/Docs Impact subitem.
- Confirm Extensibility / Agent Manageability / Config Lifecycle subitem.
- Confirm References section cites
.resources/<competitor>/path paths from the TechSpec.
Step 4: Coordinate With the Inner Skill
- Before authoring checks pass: hand off to the inner
cy-create-* skill.
- The inner skill produces the artifact; this preflight skill is not the author.
- 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.
1---2name: cy-spec-preflight-43description: >-4 Loads the AGH spec authoring playbook plus relevant lessons, standing5 directives, glossary, and active context before cy-create-prd,6 cy-create-techspec, or cy-create-tasks runs. Applies phase-specific checks:7 PRDs stay business-focused, TechSpecs carry the six quality markers, and8 every spec/task captures extensibility integration, agent-manageability,9 config lifecycle, QA tail coverage, and Web/Docs Impact. Use whenever an AGH10 spec authoring skill is about to run. Do not use for spec execution, review11 remediation, or non-spec brainstorming12 output.13trigger: implicit14argument-hint: "[phase]"15metadata:16 source: https://skillmd.com/skills/compozy/cy-spec-preflight-417---1819# Spec Preflight2021Authors 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.2223## Required Inputs2425- **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`).2627## Procedures2829**Step 1: Load Project Memory**30311. Read `docs/_memory/spec-authoring-playbook.md` in full.322. Read `docs/_memory/standing_directives.md` (SD-001..SD-011).333. Read `docs/_memory/glossary.md` (vocabulary discipline — `capability` vs `recipe`, AGH is/is-not).344. Read the matching lessons by phase. Read `references/phase-lessons.md` for the phase → lesson mapping.355. Read `CLAUDE.md` Authoring Posture, Architecture Principles, Autonomy Contracts, Security Invariants sections.3637**Step 2: Load Active Project Context**38391. Resolve the active task slug: the `.compozy/tasks/<slug>/` directory the artifact targets.402. If a `_techspec.md` exists at the slug, read it before authoring tasks.413. If `adrs/*.md` exist, read every one before authoring techspec/tasks.424. If `analysis/*.md` exist (e.g., from `cy-research-competitors`), read before authoring techspec.435. If a prior phase artifact exists (PRD before TechSpec, TechSpec before Tasks), read it.4445**Step 3: Apply Phase-Specific Checks**4647Phase-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.4849### Phase: `prd`50511. Read `references/prd-checks.md`.522. Before authoring, confirm the active idea is framed as WHAT/WHY/WHO and not implementation detail.533. 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.544. Confirm the PRD lists explicit Goals, Non-Goals, Success Metrics, and Open Questions using the canonical `cy-create-prd` template.555. Confirm the PRD states the agent/operator manageability outcome and extension ecosystem expectation without naming implementation details.566. Do not invoke `cy-spec-peer-review` for PRDs. Peer review is TechSpec-only and user-directed.5758### Phase: `techspec`59601. Read `references/techspec-six-markers.md`.612. After draft is produced, run `python3 scripts/check-techspec-markers.py <techspec_path>` to verify the six markers are present.623. Confirm "No fallback / no compat shim / no placeholder" clauses are present where breaking changes apply.634. Confirm Test Plan is per-section bullet list with concrete assertions and verification commands.645. Confirm Public Interfaces / Types section enumerates routes, payloads, CLI verbs, config keys.656. 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.667. Confirm Agent Manageability Plan enumerates CLI verbs, HTTP endpoints, UDS routes, structured outputs, status/config discovery, and deterministic errors agents will use.678. 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.689. Confirm Assumptions/Defaults section closes the spec.6910. Confirm Web/Docs Impact is captured if any contract surface is touched (activate `cy-web-docs-impact`).7011. 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.7172### Phase: `tasks`73741. Read `references/tasks-checks.md`.752. Confirm the table column order matches `cy-create-tasks`: `# | Title | Status | Complexity | Dependencies`.763. Confirm an MVP Boundary statement above the table.774. Confirm Dependencies column is populated for every row.785. Confirm Complexity is rated `low | medium | high | critical`, with QA execution and safety primitives marked high/critical as appropriate.796. Confirm last two rows are `qa-report` (high) + `qa-execution` (critical) per `cy-tasks-tail-qa-pair`.807. Confirm Web/Docs Impact subsection exists in every backend task body (activate `cy-web-docs-impact` to populate).818. Confirm Extensibility / Agent Manageability / Config Lifecycle subsections exist in every feature-bearing backend task body.829. Confirm test density is proportional to behavior count per task. Reject "fraco" plans (1-2 tests for many behaviors).8310. Confirm `.resources/<competitor>/path` references are cited per task when the TechSpec drew on competitors.8411. Confirm no TBD / placeholder rows.8586### Phase: `task-body`87881. Confirm `<critical>ALWAYS READ _techspec.md ...</critical>` block at the top.892. Confirm `<critical>MINIMIZE CODE, TESTS REQUIRED, NO WORKAROUNDS</critical>` block.903. Confirm Files / Surfaces section enumerates touched files.914. Confirm Tests section enumerates assertions covering happy path + failure paths + concurrency stress + contract redaction (when relevant).925. Confirm Web/Docs Impact subitem.936. Confirm Extensibility / Agent Manageability / Config Lifecycle subitem.947. Confirm References section cites `.resources/<competitor>/path` paths from the TechSpec.9596**Step 4: Coordinate With the Inner Skill**97981. Before authoring checks pass: hand off to the inner `cy-create-*` skill.992. The inner skill produces the artifact; this preflight skill is not the author.1003. After the draft exists: run the after-draft checks above before user approval or task execution.101102## Error Handling103104- **Phase cannot be inferred:** ask the user explicitly. Do not guess.105- **Playbook missing:** halt. The playbook is mandatory context. Direct the user to restore from git or re-run the synthesis.106- **`scripts/check-*.py` fail with structural errors:** the artifact does not match the expected shape. Surface the path that broke; do not auto-fix.107- **PRD names AGH-Network wire format:** allowed exception per `lessons/L-013` — confirm with user before stripping.108- **TechSpec missing markers:** do not let the user skip. Pedro will reject the spec; resolve missing markers first.109- **`_tasks.md` missing QA pair:** auto-invoke `cy-tasks-tail-qa-pair` to repair.110- **`_tasks.md` missing Web/Docs Impact subitems:** auto-invoke `cy-web-docs-impact` to populate.111- **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.