[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M73A5FXDS85DRB2SXQJ1GGVR":3,"skill-same:01M73A5FXDS85DRB2SXQJ1GGVR":74},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M73A5FXDS85DRB2SXQJ1GGVR","spec-driven-workflow",null,"Use when the user asks to write specs before code, define acceptance criteria, plan features before implementation, generate tests from specifications, or follow spec-first development practices.","kalash33\u002Fkstack","kalash33","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F90259149?v=4","01M7365X8Q0B73NYHA730SMZWN","Kalash Poddar","01M7365X9D0JK47C3Q0YCCK9Z2",0,"MIT","https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fnginity-engineering\u002Fspec-driven-workflow\u002FSKILL.md",[],[],"2026-11-11 15:11:14",false,"---\nname: \"spec-driven-workflow\"\ndescription: \"Use when the user asks to write specs before code, define acceptance criteria, plan features before implementation, generate tests from specifications, or follow spec-first development practices.\"\n---\n\n# Spec-Driven Workflow — POWERFUL\n\n## Overview\n\nSpec-driven workflow enforces a single, non-negotiable rule: **write the specification BEFORE you write any code.** Not alongside. Not after. Before.\n\nThis is not documentation. This is a contract. A spec defines what the system MUST do, what it SHOULD do, and what it explicitly WILL NOT do. Every line of code you write traces back to a requirement in the spec. Every test traces back to an acceptance criterion. If it is not in the spec, it does not get built.\n\n### Why Spec-First Matters\n\n1. **Eliminates rework.** 60-80% of defects originate from requirements, not implementation. Catching ambiguity in a spec costs minutes; catching it in production costs days.\n2. **Forces clarity.** If you cannot write what the system should do in plain language, you do not understand the problem well enough to write code.\n3. **Enables parallelism.** Once a spec is approved, frontend, backend, QA, and documentation can all start simultaneously.\n4. **Creates accountability.** The spec is the definition of done. No arguments about whether a feature is \"complete\" — either it satisfies the acceptance criteria or it does not.\n5. **Feeds TDD directly.** Acceptance criteria in Given\u002FWhen\u002FThen format translate 1:1 into test cases. The spec IS the test plan.\n\n### The Iron Law\n\n```\nNO CODE WITHOUT AN APPROVED SPEC.\nNO EXCEPTIONS. NO \"QUICK PROTOTYPES.\" NO \"I'LL DOCUMENT IT LATER.\"\n```\n\nIf the spec is not written, reviewed, and approved, implementation does not begin. Period.\n\n---\n\n## The Spec Format\n\nEvery spec follows this structure. No sections are optional — if a section does not apply, write \"N\u002FA — [reason]\" so reviewers know it was considered, not forgotten.\n\n### Mandatory Sections\n\n| # | Section | Key Rules |\n|---|---------|-----------|\n| 1 | **Title and Metadata** | Author, date, status (Draft\u002FIn Review\u002FApproved\u002FSuperseded), reviewers |\n| 2 | **Context** | Why this feature exists. 2-4 paragraphs with evidence (metrics, tickets). |\n| 3 | **Functional Requirements** | RFC 2119 keywords (MUST\u002FSHOULD\u002FMAY). Numbered FR-N. Each is atomic and testable. |\n| 4 | **Non-Functional Requirements** | Performance, security, accessibility, scalability, reliability — all with measurable thresholds. |\n| 5 | **Acceptance Criteria** | Given\u002FWhen\u002FThen format. Every AC references at least one FR-* or NFR-*. |\n| 6 | **Edge Cases** | Numbered EC-N. Cover failure modes for every external dependency. |\n| 7 | **API Contracts** | TypeScript-style interfaces. Cover success and error responses. |\n| 8 | **Data Models** | Table format with field, type, constraints. Every entity from requirements must have a model. |\n| 9 | **Out of Scope** | Explicit exclusions with reasons. Prevents scope creep during implementation. |\n\n### RFC 2119 Keywords\n\n| Keyword | Meaning |\n|---------|---------|\n| **MUST** | Absolute requirement. Non-conformant without it. |\n| **MUST NOT** | Absolute prohibition. |\n| **SHOULD** | Recommended. Omit only with documented justification. |\n| **MAY** | Optional. Implementer's discretion. |\n\nSee [spec_format_guide.md](references\u002Fspec_format_guide.md) for the complete template with section-by-section examples, good\u002Fbad requirement patterns, and feature-type templates (CRUD, Integration, Migration).\n\nSee [acceptance_criteria_patterns.md](references\u002Facceptance_criteria_patterns.md) for a full pattern library of Given\u002FWhen\u002FThen criteria across authentication, CRUD, search, file upload, payment, notification, and accessibility scenarios.\n\n---\n\n## Bounded Autonomy Rules\n\nThese rules define when an agent (human or AI) MUST stop and ask for guidance vs. when they can proceed independently.\n\n### STOP and Ask When:\n\n1. **Scope creep detected.** The implementation requires something not in the spec. Even if it seems obviously needed, STOP. The spec might have excluded it deliberately.\n\n2. **Ambiguity exceeds 30%.** If you cannot determine the correct behavior from the spec for more than 30% of a given requirement, the spec is incomplete. Do not guess.\n\n3. **Breaking changes required.** The implementation would change an existing API contract, database schema, or public interface. Always escalate.\n\n4. **Security implications.** Any change that touches authentication, authorization, encryption, or PII handling requires explicit approval.\n\n5. **Performance characteristics unknown.** If a requirement says \"MUST complete in \u003C 500ms\" but you have no way to measure or guarantee that, escalate before implementing a guess.\n\n6. **Cross-team dependencies.** If the spec requires coordination with another team or service, confirm the dependency before building against it.\n\n### Continue Autonomously When:\n\n1. **Spec is clear and unambiguous** for the current task.\n2. **All acceptance criteria have passing tests** and you are refactoring internals.\n3. **Changes are non-breaking** — no public API, schema, or behavior changes.\n4. **Implementation is a direct translation** of a well-defined acceptance criterion.\n5. **Error handling follows established patterns** already documented in the codebase.\n\n### Escalation Protocol\n\nWhen you must stop, provide:\n\n```markdown\n## Escalation: [Brief Title]\n\n**Blocked on:** [requirement ID, e.g., FR-3]\n**Question:** [Specific, answerable question — not \"what should I do?\"]\n**Options considered:**\n  A. [Option] — Pros: [...] Cons: [...]\n  B. [Option] — Pros: [...] Cons: [...]\n**My recommendation:** [A or B, with reasoning]\n**Impact of waiting:** [What is blocked until this is resolved?]\n```\n\nNever escalate without a recommendation. Never present an open-ended question. Always give options.\n\nSee `references\u002Fbounded_autonomy_rules.md` for the complete decision matrix.\n\n---\n\n## Workflow — 6 Phases\n\n### Phase 1: Gather Requirements\n\n**Goal:** Understand what needs to be built and why.\n\n1. **Interview the user.** Ask:\n   - What problem does this solve?\n   - Who are the users?\n   - What does success look like?\n   - What explicitly should NOT be built?\n2. **Read existing code.** Understand the current system before proposing changes.\n3. **Identify constraints.** Performance budgets, security requirements, backward compatibility.\n4. **List unknowns.** Every unknown is a risk. Surface them now, not during implementation.\n\n**Exit criteria:** You can explain the feature to someone unfamiliar with the project in 2 minutes.\n\n### Phase 2: Write Spec\n\n**Goal:** Produce a complete spec document following The Spec Format above.\n\n1. Fill every section of the template. No section left blank.\n2. Number all requirements (FR-*, NFR-*, AC-*, EC-*, OS-*).\n3. Use RFC 2119 keywords precisely.\n4. Write acceptance criteria in Given\u002FWhen\u002FThen format.\n5. Define API contracts with TypeScript-style types.\n6. List explicit exclusions in Out of Scope.\n\n**Exit criteria:** The spec can be handed to a developer who was not in the requirements meeting, and they can implement the feature without asking clarifying questions.\n\n### Phase 3: Validate Spec\n\n**Goal:** Verify the spec is complete, consistent, and implementable.\n\nRun `spec_validator.py` against the spec file:\n\n```bash\npython spec_validator.py --file spec.md --strict\n```\n\nManual validation checklist:\n- [ ] Every functional requirement has at least one acceptance criterion\n- [ ] Every acceptance criterion is testable (no subjective language)\n- [ ] API contracts cover all endpoints mentioned in requirements\n- [ ] Data models cover all entities mentioned in requirements\n- [ ] Edge cases cover failure modes for every external dependency\n- [ ] Out of scope is explicit about what was considered and rejected\n- [ ] Non-functional requirements have measurable thresholds\n\n**Exit criteria:** Spec scores 80+ on validator, and all manual checklist items pass.\n\n### Phase 4: Generate Tests\n\n**Goal:** Extract test cases from acceptance criteria before writing implementation code.\n\nRun `test_extractor.py` against the approved spec:\n\n```bash\npython test_extractor.py --file spec.md --framework pytest --output tests\u002F\n```\n\n1. Each acceptance criterion becomes one or more test cases.\n2. Each edge case becomes a test case.\n3. Tests are stubs — they define the assertion but not the implementation.\n4. All tests MUST fail initially (red phase of TDD).\n\n**Exit criteria:** You have a test file where every test fails with \"not implemented\" or equivalent.\n\n### Phase 5: Implement\n\n**Goal:** Write code that makes failing tests pass, one acceptance criterion at a time.\n\n1. Pick one acceptance criterion (start with the simplest).\n2. Make its test(s) pass with minimal code.\n3. Run the full test suite — no regressions.\n4. Commit.\n5. Pick the next acceptance criterion. Repeat.\n\n**Rules:**\n- Do NOT implement anything not in the spec.\n- Do NOT optimize before all acceptance criteria pass.\n- Do NOT refactor before all acceptance criteria pass.\n- If you discover a missing requirement, STOP and update the spec first.\n\n**Exit criteria:** All tests pass. All acceptance criteria satisfied.\n\n### Phase 6: Self-Review\n\n**Goal:** Verify implementation matches spec before marking done.\n\nRun through the Self-Review Checklist below. If any item fails, fix it before declaring the task complete.\n\n---\n\n## Self-Review Checklist\n\nBefore marking any implementation as done, verify ALL of the following:\n\n- [ ] **Every acceptance criterion has a passing test.** No exceptions. If AC-3 exists, a test for AC-3 exists and passes.\n- [ ] **Every edge case has a test.** EC-1 through EC-N all have corresponding test cases.\n- [ ] **No scope creep.** The implementation does not include features not in the spec. If you added something, either update the spec or remove it.\n- [ ] **API contracts match implementation.** Request\u002Fresponse shapes in code match the spec exactly. Field names, types, status codes — all of it.\n- [ ] **Error scenarios tested.** Every error response defined in the spec has a test that triggers it.\n- [ ] **Non-functional requirements verified.** If the spec says \u003C 500ms, you have evidence (benchmark, load test, profiling) that it meets the threshold.\n- [ ] **Data model matches.** Database schema matches the spec. No extra columns, no missing constraints.\n- [ ] **Out-of-scope items not built.** Double-check that nothing from the Out of Scope section leaked into the implementation.\n\n---\n\n## Integration with TDD Guide\n\nSpec-driven workflow and TDD are complementary, not competing:\n\n```\nSpec-Driven Workflow          TDD (Red-Green-Refactor)\n─────────────────────         ──────────────────────────\nPhase 1: Gather Requirements\nPhase 2: Write Spec\nPhase 3: Validate Spec\nPhase 4: Generate Tests  ──→  RED: Tests exist and fail\nPhase 5: Implement       ──→  GREEN: Minimal code to pass\nPhase 6: Self-Review     ──→  REFACTOR: Clean up internals\n```\n\n**The handoff:** Spec-driven workflow produces the test stubs (Phase 4). TDD takes over from there. The spec tells you WHAT to test. TDD tells you HOW to implement.\n\nUse `engineering-team\u002Ftdd-guide` for:\n- Red-green-refactor cycle discipline\n- Coverage analysis and gap detection\n- Framework-specific test patterns (Jest, Pytest, JUnit)\n\nUse `engineering\u002Fspec-driven-workflow` for:\n- Defining what to build before building it\n- Acceptance criteria authoring\n- Completeness validation\n- Scope control\n\n---\n\n## Examples\n\nA complete worked example (Password Reset spec with extracted test cases) is available in [spec_format_guide.md](references\u002Fspec_format_guide.md#full-example-password-reset). It demonstrates all 9 sections, requirement numbering, acceptance criteria, edge cases, and the corresponding pytest stubs generated by `test_extractor.py`.\n\n---\n\n## Anti-Patterns\n\n### 1. Coding Before Spec Approval\n\n**Symptom:** \"I'll start coding while the spec is being reviewed.\"\n**Problem:** The review will surface changes. Now you have code that implements a rejected design.\n**Rule:** Implementation does not begin until spec status is \"Approved.\"\n\n### 2. Vague Acceptance Criteria\n\n**Symptom:** \"The system should work well\" or \"The UI should be responsive.\"\n**Problem:** Untestable. What does \"well\" mean? What does \"responsive\" mean?\n**Rule:** Every acceptance criterion must be verifiable by a machine. If you cannot write a test for it, rewrite the criterion.\n\n### 3. Missing Edge Cases\n\n**Symptom:** Happy path is specified, error paths are not.\n**Problem:** Developers invent error handling on the fly, leading to inconsistent behavior.\n**Rule:** For every external dependency (API, database, file system, user input), specify at least one failure scenario.\n\n### 4. Spec as Post-Hoc Documentation\n\n**Symptom:** \"Let me write the spec now that the feature is done.\"\n**Problem:** This is documentation, not specification. It describes what was built, not what should have been built. It cannot catch design errors because the design is already frozen.\n**Rule:** If the spec was written after the code, it is not a spec. Relabel it as documentation.\n\n### 5. Gold-Plating Beyond Spec\n\n**Symptom:** \"While I was in there, I also added...\"\n**Problem:** Untested code. Unreviewed design. Potential for subtle bugs in the \"bonus\" feature.\n**Rule:** If it is not in the spec, it does not get built. File a new spec for additional features.\n\n### 6. Acceptance Criteria Without Requirement Traceability\n\n**Symptom:** AC-7 exists but does not reference any FR-* or NFR-*.\n**Problem:** Orphaned criteria mean either a requirement is missing or the criterion is unnecessary.\n**Rule:** Every AC-* MUST reference at least one FR-* or NFR-*.\n\n### 7. Skipping Validation\n\n**Symptom:** \"The spec looks fine, let's just start.\"\n**Problem:** Missing sections discovered during implementation cause blocking delays.\n**Rule:** Always run `spec_validator.py --strict` before starting implementation. Fix all warnings.\n\n---\n\n## Cross-References\n\n- **`engineering-team\u002Ftdd-guide`** — Red-green-refactor cycle, test generation, coverage analysis. Use after Phase 4 of this workflow.\n- **`engineering\u002Ffocused-fix`** — Deep-dive feature repair. When a spec-driven implementation has systemic issues, use focused-fix for diagnosis.\n- **`engineering\u002Frag-architect`** — If the feature involves retrieval or knowledge systems, use rag-architect for the technical design within the spec.\n- **`references\u002Fspec_format_guide.md`** — Complete template with section-by-section explanations.\n- **`references\u002Fbounded_autonomy_rules.md`** — Full decision matrix for when to stop vs. continue.\n- **`references\u002Facceptance_criteria_patterns.md`** — Pattern library for writing Given\u002FWhen\u002FThen criteria.\n\n---\n\n## Tools\n\n| Script | Purpose | Key Flags |\n|--------|---------|-----------|\n| `spec_generator.py` | Generate spec template from feature name\u002Fdescription | `--name`, `--description`, `--format`, `--json` |\n| `spec_validator.py` | Validate spec completeness (0-100 score) | `--file`, `--strict`, `--json` |\n| `test_extractor.py` | Extract test stubs from acceptance criteria | `--file`, `--framework`, `--output`, `--json` |\n\n```bash\n# Generate a spec template\npython spec_generator.py --name \"User Authentication\" --description \"OAuth 2.0 login flow\"\n\n# Validate a spec\npython spec_validator.py --file specs\u002Fauth.md --strict\n\n# Extract test cases\npython test_extractor.py --file specs\u002Fauth.md --framework pytest --output tests\u002Ftest_auth.py\n```\n","# Spec-Driven Workflow — POWERFUL\n\n## Overview\n\nSpec-driven workflow enforces a single, non-negotiable rule: **write the specification BEFORE you write any code.** Not alongside. Not after. Before.\n\nThis is not documentation. This is a contract. A spec defines what the system MUST do, what it SHOULD do, and what it explicitly WILL NOT do. Every line of code you write traces back to a requirement in the spec. Every test traces back to an acceptance criterion. If it is not in the spec, it does not get built.\n\n### Why Spec-First Matters\n\n1. **Eliminates rework.** 60-80% of defects originate from requirements, not implementation. Catching ambiguity in a spec costs minutes; catching it in production costs days.\n2. **Forces clarity.** If you cannot write what the system should do in plain language, you do not understand the problem well enough to write code.\n3. **Enables parallelism.** Once a spec is approved, frontend, backend, QA, and documentation can all start simultaneously.\n4. **Creates accountability.** The spec is the definition of done. No arguments about whether a feature is \"complete\" — either it satisfies the acceptance criteria or it does not.\n5. **Feeds TDD directly.** Acceptance criteria in Given\u002FWhen\u002FThen format translate 1:1 into test cases. The spec IS the test plan.\n\n### The Iron Law\n\n```\nNO CODE WITHOUT AN APPROVED SPEC.\nNO EXCEPTIONS. NO \"QUICK PROTOTYPES.\" NO \"I'LL DOCUMENT IT LATER.\"\n```\n\nIf the spec is not written, reviewed, and approved, implementation does not begin. Period.\n\n---\n\n## The Spec Format\n\nEvery spec follows this structure. No sections are optional — if a section does not apply, write \"N\u002FA — [reason]\" so reviewers know it was considered, not forgotten.\n\n### Mandatory Sections\n\n| # | Section | Key Rules |\n|---|---------|-----------|\n| 1 | **Title and Metadata** | Author, date, status (Draft\u002FIn Review\u002FApproved\u002FSuperseded), reviewers |\n| 2 | **Context** | Why this feature exists. 2-4 paragraphs with evidence (metrics, tickets). |\n| 3 | **Functional Requirements** | RFC 2119 keywords (MUST\u002FSHOULD\u002FMAY). Numbered FR-N. Each is atomic and testable. |\n| 4 | **Non-Functional Requirements** | Performance, security, accessibility, scalability, reliability — all with measurable thresholds. |\n| 5 | **Acceptance Criteria** | Given\u002FWhen\u002FThen format. Every AC references at least one FR-* or NFR-*. |\n| 6 | **Edge Cases** | Numbered EC-N. Cover failure modes for every external dependency. |\n| 7 | **API Contracts** | TypeScript-style interfaces. Cover success and error responses. |\n| 8 | **Data Models** | Table format with field, type, constraints. Every entity from requirements must have a model. |\n| 9 | **Out of Scope** | Explicit exclusions with reasons. Prevents scope creep during implementation. |\n\n### RFC 2119 Keywords\n\n| Keyword | Meaning |\n|---------|---------|\n| **MUST** | Absolute requirement. Non-conformant without it. |\n| **MUST NOT** | Absolute prohibition. |\n| **SHOULD** | Recommended. Omit only with documented justification. |\n| **MAY** | Optional. Implementer's discretion. |\n\nSee [spec_format_guide.md](references\u002Fspec_format_guide.md) for the complete template with section-by-section examples, good\u002Fbad requirement patterns, and feature-type templates (CRUD, Integration, Migration).\n\nSee [acceptance_criteria_patterns.md](references\u002Facceptance_criteria_patterns.md) for a full pattern library of Given\u002FWhen\u002FThen criteria across authentication, CRUD, search, file upload, payment, notification, and accessibility scenarios.\n\n---\n\n## Bounded Autonomy Rules\n\nThese rules define when an agent (human or AI) MUST stop and ask for guidance vs. when they can proceed independently.\n\n### STOP and Ask When:\n\n1. **Scope creep detected.** The implementation requires something not in the spec. Even if it seems obviously needed, STOP. The spec might have excluded it deliberately.\n\n2. **Ambiguity exceeds 30%.** If you cannot determine the correct behavior from the spec for more than 30% of a given requirement, the spec is incomplete. Do not guess.\n\n3. **Breaking changes required.** The implementation would change an existing API contract, database schema, or public interface. Always escalate.\n\n4. **Security implications.** Any change that touches authentication, authorization, encryption, or PII handling requires explicit approval.\n\n5. **Performance characteristics unknown.** If a requirement says \"MUST complete in \u003C 500ms\" but you have no way to measure or guarantee that, escalate before implementing a guess.\n\n6. **Cross-team dependencies.** If the spec requires coordination with another team or service, confirm the dependency before building against it.\n\n### Continue Autonomously When:\n\n1. **Spec is clear and unambiguous** for the current task.\n2. **All acceptance criteria have passing tests** and you are refactoring internals.\n3. **Changes are non-breaking** — no public API, schema, or behavior changes.\n4. **Implementation is a direct translation** of a well-defined acceptance criterion.\n5. **Error handling follows established patterns** already documented in the codebase.\n\n### Escalation Protocol\n\nWhen you must stop, provide:\n\n```markdown\n## Escalation: [Brief Title]\n\n**Blocked on:** [requirement ID, e.g., FR-3]\n**Question:** [Specific, answerable question — not \"what should I do?\"]\n**Options considered:**\n  A. [Option] — Pros: [...] Cons: [...]\n  B. [Option] — Pros: [...] Cons: [...]\n**My recommendation:** [A or B, with reasoning]\n**Impact of waiting:** [What is blocked until this is resolved?]\n```\n\nNever escalate without a recommendation. Never present an open-ended question. Always give options.\n\nSee `references\u002Fbounded_autonomy_rules.md` for the complete decision matrix.\n\n---\n\n## Workflow — 6 Phases\n\n### Phase 1: Gather Requirements\n\n**Goal:** Understand what needs to be built and why.\n\n1. **Interview the user.** Ask:\n   - What problem does this solve?\n   - Who are the users?\n   - What does success look like?\n   - What explicitly should NOT be built?\n2. **Read existing code.** Understand the current system before proposing changes.\n3. **Identify constraints.** Performance budgets, security requirements, backward compatibility.\n4. **List unknowns.** Every unknown is a risk. Surface them now, not during implementation.\n\n**Exit criteria:** You can explain the feature to someone unfamiliar with the project in 2 minutes.\n\n### Phase 2: Write Spec\n\n**Goal:** Produce a complete spec document following The Spec Format above.\n\n1. Fill every section of the template. No section left blank.\n2. Number all requirements (FR-*, NFR-*, AC-*, EC-*, OS-*).\n3. Use RFC 2119 keywords precisely.\n4. Write acceptance criteria in Given\u002FWhen\u002FThen format.\n5. Define API contracts with TypeScript-style types.\n6. List explicit exclusions in Out of Scope.\n\n**Exit criteria:** The spec can be handed to a developer who was not in the requirements meeting, and they can implement the feature without asking clarifying questions.\n\n### Phase 3: Validate Spec\n\n**Goal:** Verify the spec is complete, consistent, and implementable.\n\nRun `spec_validator.py` against the spec file:\n\n```bash\npython spec_validator.py --file spec.md --strict\n```\n\nManual validation checklist:\n- [ ] Every functional requirement has at least one acceptance criterion\n- [ ] Every acceptance criterion is testable (no subjective language)\n- [ ] API contracts cover all endpoints mentioned in requirements\n- [ ] Data models cover all entities mentioned in requirements\n- [ ] Edge cases cover failure modes for every external dependency\n- [ ] Out of scope is explicit about what was considered and rejected\n- [ ] Non-functional requirements have measurable thresholds\n\n**Exit criteria:** Spec scores 80+ on validator, and all manual checklist items pass.\n\n### Phase 4: Generate Tests\n\n**Goal:** Extract test cases from acceptance criteria before writing implementation code.\n\nRun `test_extractor.py` against the approved spec:\n\n```bash\npython test_extractor.py --file spec.md --framework pytest --output tests\u002F\n```\n\n1. Each acceptance criterion becomes one or more test cases.\n2. Each edge case becomes a test case.\n3. Tests are stubs — they define the assertion but not the implementation.\n4. All tests MUST fail initially (red phase of TDD).\n\n**Exit criteria:** You have a test file where every test fails with \"not implemented\" or equivalent.\n\n### Phase 5: Implement\n\n**Goal:** Write code that makes failing tests pass, one acceptance criterion at a time.\n\n1. Pick one acceptance criterion (start with the simplest).\n2. Make its test(s) pass with minimal code.\n3. Run the full test suite — no regressions.\n4. Commit.\n5. Pick the next acceptance criterion. Repeat.\n\n**Rules:**\n- Do NOT implement anything not in the spec.\n- Do NOT optimize before all acceptance criteria pass.\n- Do NOT refactor before all acceptance criteria pass.\n- If you discover a missing requirement, STOP and update the spec first.\n\n**Exit criteria:** All tests pass. All acceptance criteria satisfied.\n\n### Phase 6: Self-Review\n\n**Goal:** Verify implementation matches spec before marking done.\n\nRun through the Self-Review Checklist below. If any item fails, fix it before declaring the task complete.\n\n---\n\n## Self-Review Checklist\n\nBefore marking any implementation as done, verify ALL of the following:\n\n- [ ] **Every acceptance criterion has a passing test.** No exceptions. If AC-3 exists, a test for AC-3 exists and passes.\n- [ ] **Every edge case has a test.** EC-1 through EC-N all have corresponding test cases.\n- [ ] **No scope creep.** The implementation does not include features not in the spec. If you added something, either update the spec or remove it.\n- [ ] **API contracts match implementation.** Request\u002Fresponse shapes in code match the spec exactly. Field names, types, status codes — all of it.\n- [ ] **Error scenarios tested.** Every error response defined in the spec has a test that triggers it.\n- [ ] **Non-functional requirements verified.** If the spec says \u003C 500ms, you have evidence (benchmark, load test, profiling) that it meets the threshold.\n- [ ] **Data model matches.** Database schema matches the spec. No extra columns, no missing constraints.\n- [ ] **Out-of-scope items not built.** Double-check that nothing from the Out of Scope section leaked into the implementation.\n\n---\n\n## Integration with TDD Guide\n\nSpec-driven workflow and TDD are complementary, not competing:\n\n```\nSpec-Driven Workflow          TDD (Red-Green-Refactor)\n─────────────────────         ──────────────────────────\nPhase 1: Gather Requirements\nPhase 2: Write Spec\nPhase 3: Validate Spec\nPhase 4: Generate Tests  ──→  RED: Tests exist and fail\nPhase 5: Implement       ──→  GREEN: Minimal code to pass\nPhase 6: Self-Review     ──→  REFACTOR: Clean up internals\n```\n\n**The handoff:** Spec-driven workflow produces the test stubs (Phase 4). TDD takes over from there. The spec tells you WHAT to test. TDD tells you HOW to implement.\n\nUse `engineering-team\u002Ftdd-guide` for:\n- Red-green-refactor cycle discipline\n- Coverage analysis and gap detection\n- Framework-specific test patterns (Jest, Pytest, JUnit)\n\nUse `engineering\u002Fspec-driven-workflow` for:\n- Defining what to build before building it\n- Acceptance criteria authoring\n- Completeness validation\n- Scope control\n\n---\n\n## Examples\n\nA complete worked example (Password Reset spec with extracted test cases) is available in [spec_format_guide.md](references\u002Fspec_format_guide.md#full-example-password-reset). It demonstrates all 9 sections, requirement numbering, acceptance criteria, edge cases, and the corresponding pytest stubs generated by `test_extractor.py`.\n\n---\n\n## Anti-Patterns\n\n### 1. Coding Before Spec Approval\n\n**Symptom:** \"I'll start coding while the spec is being reviewed.\"\n**Problem:** The review will surface changes. Now you have code that implements a rejected design.\n**Rule:** Implementation does not begin until spec status is \"Approved.\"\n\n### 2. Vague Acceptance Criteria\n\n**Symptom:** \"The system should work well\" or \"The UI should be responsive.\"\n**Problem:** Untestable. What does \"well\" mean? What does \"responsive\" mean?\n**Rule:** Every acceptance criterion must be verifiable by a machine. If you cannot write a test for it, rewrite the criterion.\n\n### 3. Missing Edge Cases\n\n**Symptom:** Happy path is specified, error paths are not.\n**Problem:** Developers invent error handling on the fly, leading to inconsistent behavior.\n**Rule:** For every external dependency (API, database, file system, user input), specify at least one failure scenario.\n\n### 4. Spec as Post-Hoc Documentation\n\n**Symptom:** \"Let me write the spec now that the feature is done.\"\n**Problem:** This is documentation, not specification. It describes what was built, not what should have been built. It cannot catch design errors because the design is already frozen.\n**Rule:** If the spec was written after the code, it is not a spec. Relabel it as documentation.\n\n### 5. Gold-Plating Beyond Spec\n\n**Symptom:** \"While I was in there, I also added...\"\n**Problem:** Untested code. Unreviewed design. Potential for subtle bugs in the \"bonus\" feature.\n**Rule:** If it is not in the spec, it does not get built. File a new spec for additional features.\n\n### 6. Acceptance Criteria Without Requirement Traceability\n\n**Symptom:** AC-7 exists but does not reference any FR-* or NFR-*.\n**Problem:** Orphaned criteria mean either a requirement is missing or the criterion is unnecessary.\n**Rule:** Every AC-* MUST reference at least one FR-* or NFR-*.\n\n### 7. Skipping Validation\n\n**Symptom:** \"The spec looks fine, let's just start.\"\n**Problem:** Missing sections discovered during implementation cause blocking delays.\n**Rule:** Always run `spec_validator.py --strict` before starting implementation. Fix all warnings.\n\n---\n\n## Cross-References\n\n- **`engineering-team\u002Ftdd-guide`** — Red-green-refactor cycle, test generation, coverage analysis. Use after Phase 4 of this workflow.\n- **`engineering\u002Ffocused-fix`** — Deep-dive feature repair. When a spec-driven implementation has systemic issues, use focused-fix for diagnosis.\n- **`engineering\u002Frag-architect`** — If the feature involves retrieval or knowledge systems, use rag-architect for the technical design within the spec.\n- **`references\u002Fspec_format_guide.md`** — Complete template with section-by-section explanations.\n- **`references\u002Fbounded_autonomy_rules.md`** — Full decision matrix for when to stop vs. continue.\n- **`references\u002Facceptance_criteria_patterns.md`** — Pattern library for writing Given\u002FWhen\u002FThen criteria.\n\n---\n\n## Tools\n\n| Script | Purpose | Key Flags |\n|--------|---------|-----------|\n| `spec_generator.py` | Generate spec template from feature name\u002Fdescription | `--name`, `--description`, `--format`, `--json` |\n| `spec_validator.py` | Validate spec completeness (0-100 score) | `--file`, `--strict`, `--json` |\n| `test_extractor.py` | Extract test stubs from acceptance criteria | `--file`, `--framework`, `--output`, `--json` |\n\n```bash\n# Generate a spec template\npython spec_generator.py --name \"User Authentication\" --description \"OAuth 2.0 login flow\"\n\n# Validate a spec\npython spec_validator.py --file specs\u002Fauth.md --strict\n\n# Extract test cases\npython test_extractor.py --file specs\u002Fauth.md --framework pytest --output tests\u002Ftest_auth.py\n```\n",{"name":5,"description":7},"main","b30820b3248f6676d5389f0ccabd4e5250c9c536","skills\u002Fnginity-engineering\u002Fspec-driven-workflow","https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack","https:\u002F\u002Fgithub.com\u002Fkalash33","kalashpoddar.me","Tech-savvy Full Stack Developer 🚀 | Cybersecurity enthusiast 🔒 | Passionate about innovation and securing the digital world 🌐 | Let's code securely! 💻🔐","2026-05-20 04:11:22",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add kalash33\u002Fkstack --skill spec-driven-workflow",{"tool":38,"command":39},"bunx","bunx skills add kalash33\u002Fkstack --skill spec-driven-workflow",{"tool":41,"command":42},"pnpm","pnpm dlx skills add kalash33\u002Fkstack --skill spec-driven-workflow","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fnginity-engineering\u002Fspec-driven-workflow\u002FSKILL.md",true,[46,52,56,60,66,70],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Facceptance_criteria_patterns.md","REFERENCE","参考文档",15278,"https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fnginity-engineering\u002Fspec-driven-workflow\u002Freferences\u002Facceptance_criteria_patterns.md",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Fbounded_autonomy_rules.md",11607,"https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fnginity-engineering\u002Fspec-driven-workflow\u002Freferences\u002Fbounded_autonomy_rules.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fspec_format_guide.md",19127,"https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fnginity-engineering\u002Fspec-driven-workflow\u002Freferences\u002Fspec_format_guide.md",{"path":61,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":64,"sourceHtmlUrl":65},"scripts\u002Fspec_generator.py","SCRIPT","脚本",10423,"https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fnginity-engineering\u002Fspec-driven-workflow\u002Fscripts\u002Fspec_generator.py",{"path":67,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":68,"sourceHtmlUrl":69},"scripts\u002Fspec_validator.py",17483,"https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fnginity-engineering\u002Fspec-driven-workflow\u002Fscripts\u002Fspec_validator.py",{"path":71,"resourceType":62,"resourceTypeDesc":63,"sizeBytes":72,"sourceHtmlUrl":73},"scripts\u002Ftest_extractor.py",14890,"https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fnginity-engineering\u002Fspec-driven-workflow\u002Fscripts\u002Ftest_extractor.py",[75,82,89,96,103,110],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":19},"01M73CFERCR43JCAP606E41EFB","zustand-store-ts","Create Zustand stores with TypeScript, subscribeWithSelector middleware, and proper state\u002Faction separation. Use when building React state management, creating global stores, or implementing reacti...","https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fzustand-store-ts\u002FSKILL.md",[],[],{"skillNo":83,"name":84,"nameZh":6,"description":85,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":86,"categories":87,"keywords":88,"publishedAt":19},"01M73CFCMFVTAQEMTZ5HR10X8V","zoom-automation","Automate Zoom meeting creation, management, recordings, webinars, and participant tracking via Rube MCP (Composio). Always search tools first for current schemas.","https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fzoom-automation\u002FSKILL.md",[],[],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":95,"publishedAt":19},"01M73CFAA7EBWXJVXDQ1X555MB","zoho-crm-automation","Automate Zoho CRM tasks via Rube MCP (Composio): create\u002Fupdate records, search contacts, manage leads, and convert leads. Always search tools first for current schemas.","https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fzoho-crm-automation\u002FSKILL.md",[],[],{"skillNo":97,"name":98,"nameZh":6,"description":99,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":19},"01M73CF80XCM9K81567MJ8QZFW","zod-validation-expert","Expert in Zod — TypeScript-first schema validation. Covers parsing, custom errors, refinements, type inference, and integration with React Hook Form, Next.js, and tRPC.","https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fzod-validation-expert\u002FSKILL.md",[],[],{"skillNo":104,"name":105,"nameZh":6,"description":106,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":107,"categories":108,"keywords":109,"publishedAt":19},"01M73CF4YPMF3RA8ZJDXZSMD93","zeroize-audit","Detects missing zeroization of sensitive data in source code and identifies zeroization removed by compiler optimizations, with assembly-level analysis, and control-flow verification. Use for auditing C\u002FC++\u002FRust code handling secrets, keys, passwords, or other sensitive data.","https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fzeroize-audit\u002FSKILL.md",[],[],{"skillNo":111,"name":112,"nameZh":6,"description":113,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":114,"categories":115,"keywords":116,"publishedAt":19},"01M73CF2S25EN3XNAMKY47XHPS","zendesk-automation","Automate Zendesk tasks via Rube MCP (Composio): tickets, users, organizations, replies. Always search tools first for current schemas.","https:\u002F\u002Fgithub.com\u002Fkalash33\u002Fkstack\u002Fblob\u002Fmain\u002Fskills\u002Fzendesk-automation\u002FSKILL.md",[],[]]