cy-create-techspec

# Create TechSpec Translate business requirements into a detailed technical specification and its companion test contract. <HARD-GATE> - Explore before designing: every TechSpec MUST be informed by the existing architecture. - Questions before writing: the user MUST shape the design by answering technical clarification questions — for every TechSpec, however simple. "Simple" changes are where unexamined architecture assumptions cause the most integration failures; brief review is fine, skipped review is not. - Decide, then write: once the questions are answered and the ADRs are recorded, write the files directly. The user reviews the generated files and requests changes afterward — no draft-approval loops. </HARD-GATE> ## Full Scope, One Design Design for the complete PRD scope in this single TechSpec. Agents run long and `cy-create-tasks` decomposes the work later, so design size is never a reason to trim scope or stage the design into phases. Design minimalism still applies — to the design, never to the scope: include no component, interface, or abstraction the design does not strictly need, and prefer adding a file to an existing package over proposing new packages or directories. ## Asking Questions Ask every question through the runtime's dedicated interactive question tool — the mechanism that presents a question and pauses execution until the user responds. If the runtime has no such tool, present the question as the complete message and stop generating; never answer a question on the user's behalf. - One question per message: exactly one question mark, then stop; follow-ups go in the next message, after the user answers. - Lead with a recommendation: state which option you would pick and why in one line, so the user reacts to a position instead of facing a blank menu. - Multiple-choice whenever the options can be predetermined, with your recommendation first and a fallback option ("D) Other — describe"). - Never spend a question on what the codebase can answer: explore first; user answers are for genuine trade-offs — priorities, risk appetite, and the product intent behind technical choices. ## Required Inputs - Feature name identifying the `.compozy/tasks/<name>/` directory. - Optional: existing `_prd.md` and `_user_stories.md` as primary input. - Optional: existing `_techspec.md` for update mode. ## Workflow Track each step as a task in the runtime's task tracker when one is available, and complete the steps in order. 1. Gather context. - Read `_prd.md` and `_user_stories.md` from `.compozy/tasks/<name>/` as the primary input. If no PRD exists, ask the user for a description of what needs technical specification. - Read existing ADRs from `.compozy/tasks/<name>/adrs/` (create the directory if missing) to understand decisions already made. - Spawn an Agent tool call to explore the codebase for architecture patterns, existing components, dependencies, and technology stack. - If `_techspec.md` already exists, read it and operate in update mode. 2. Grill the design. - Focus on HOW to implement, WHERE components live, and WHICH technologies to use. Map the load-bearing technical decisions into a decision tree — architecture approach and component boundaries, data models and storage, API design and integration points, testing strategy and performance requirements — and walk it branch by branch, resolving dependencies between decisions one at a time. - Chase vague answers until each branch is concrete; a load-bearing decision left fuzzy resurfaces as an integration failure. - Keep grilling until every branch that shapes the design is resolved or explicitly parked — the question count is an output of the tree, not a budget. 3. Record ADRs for significant technical decisions. - For each significant decision (architecture pattern, technology choice, data model approach): read `references/adr-template.md`, determine the next number from the files in `adrs/`, fill the template (chosen design as Decision, rejected alternatives as Alternatives Considered, trade-offs as Consequences; Status "Accepted", Date today), and write `adrs/adr-NNN.md` (zero-padded 3-digit sequential number). - Even simple features get at least one ADR documenting the primary technical approach chosen and the alternatives rejected. 4. Write the TechSpec. - Read `references/techspec-template.md` and fill every applicable section; the template carries the per-section rules. - Map every PRD goal and every story in `_user_stories.md` to a technical component; reference PRD sections by name without duplicating business context. - Core Interfaces must show the primary type other components depend on, in the project's primary language. - List every ADR in the Architecture Decision Records section; if step 3 produced none, go back and create at least one first. - Prefer active voice and definite, specific language; every sentence earns its place. Language: English. - Write `.compozy/tasks/<name>/_techspec.md`. 5. Write the test contract. - Read `references/tests-template.md` and write `.compozy/tasks/<name>/_tests.md`. - Derive unit cases from every component and interface in the TechSpec, including every error path; integration cases from every component boundary and external integration; end-to-end cases from every user journey in `_user_stories.md`. - Done when the coverage matrix satisfies the template's Coverage Demands and every case meets its Case-Writing Rules. 6. Hand off. - Confirm both file paths to the user and invite change requests directly on the generated files. - Point to `cy-create-tasks` as the next step. ## Error Handling - PRD missing: proceed with user-provided context and note the absence in the Executive Summary. - `_user_stories.md` missing: derive journeys from the PRD's User Stories section and note the coverage gap in `_tests.md`. - Conflicting architectural patterns in the codebase: document both and recommend one with rationale. - Target directory missing: create it. - Update mode: preserve sections the user has not asked to change, and mirror any behavior or interface change into `_tests.md` so the contract stays in sync.