spec-development

name	spec_development
description	StagedSpec: Guides iterative development and assessment of project specs in /specs with an architecture index, staged specs, implemented status tracking, and feature documentation. Use when creating, refining, or checking specs, architecture.md, stage files, features.md, security.md, or testing.md.

<task_block> StagedSpec — Spec Development

The skill drives iterative, human-in-the-loop refinement; the target quality bar is a spec that a one-shot AI coding agent can implement correctly from the spec alone. Use a `/specs` folder at the project root for all specification documents. Use `specs/architecture.md` as the single index and entry point with stage links, status markers, global constraints, and future features. Keep global constraints visible in `specs/architecture.md`, including links to `specs/intent.md`, `specs/security.md`, and `specs/testing.md`. When `specs/security.md` or `specs/testing.md` are missing, point the user to the spec_init skill for full framework bootstrap. The following files are project-level guardrails, not regular stage deliverables: `specs/intent.md` — project identity and non-negotiable boundaries. `specs/security.md` — security constraints and threat model. `specs/testing.md` — testing strategy and quality requirements. Treat the full `/specs` set as one system: improve clarity and consistency without eroding already-established valid behavior. Use `specs/features.md` as the authoritative source for all implemented behavior — it defines what the system does today. Use planned stage files for upcoming work and its dependencies. Stages are relevant while planned; once implemented, their behavioral content lives in `features.md`. Treat implemented and in-progress stage files as historical records for audit and link validation only — source behavioral context from `features.md`. **Never reference implemented or in-progress stage files from a planned stage's Dependencies, Desired behavior, Scope boundary, Implementation steps, or Tests and verification.** Already-built behavior is owned by `specs/features.md`, and the correct pointer is always the matching `features.md` topic — the stage that delivered it is irrelevant. Treat an implemented-stage link in any of those sections as an issue to flag during assessment and fix during refinement. Frame stage content in terms of what the system does today (`features.md`) and what this stage will add — orient toward the present and the future. Keep specs contradiction-free and outcome-focused; include implementation detail only when required for correctness, safety, or integration. Add an explicit out-of-scope section in `specs/architecture.md` to prevent scope creep. Plan staged work to reduce avoidable refactors by keeping scope cohesive, dependencies explicit, and build order free of forward dependencies. Size of each stage must be the most compact scope that delivers a meaningful, testable capability —> the fundamental unit a one-shot AI coding agent can implement correctly in a single pass. Use the staged plan to guide steady progress while balancing over-engineering with under-specification.

<decision_rules>
  <rule>Rules for guardrail documents:</rule>
  <rule>Never create, modify, or delete a guardrail document as a side-effect of stage creation, refinement, implementation, or status updates.</rule>
  <rule>Changes to guardrail documents require an explicit, direct request from the human user in the current conversation.</rule>
  <rule>When a stage update conflicts with a guardrail document, fix the stage spec to align with the guardrail. Escalate to the user when alignment requires a trade-off or when the conflict touches a core constraint.</rule>
  <rule>Treat guardrail constraints as project-wide defaults that apply to every stage automatically — stage specs comply with them.</rule>
  <rule>Automated or batch workflows that touch multiple specs must skip guardrail documents entirely.</rule>
  <rule>Preserve history when restructuring tracked spec files: use `git mv` for renames/moves and `git rm` for permanent retirement.</rule>
</decision_rules>

<output_contract> <response_shape> When initializing a new project or bootstrapping the /specs folder, point the user to the spec_init skill. When creating a new stage spec or writing content into an existing one, read references/single_stage_structure.md for required sections, naming, and formatting. When refining or iterating a stage spec toward implementation-readiness (adding detail, removing over-specification, relocating to Out of scope, splitting, merging, or restructuring dependencies), read references/single_stage_refinement.md. When reviewing or checking a single stage spec for implementation readiness, read references/single_stage_assessment.md. When assessing the spec framework as a whole for completeness and coherence, read references/framework_assessment.md. When creating, validating, or checking alignment against the project intent, read references/spec_intent.md. </response_shape> </output_contract> </task_block>