# Specross [![npm version](https://img.shields.io/npm/v/specross.svg)](https://www.npmjs.com/package/specross) [![npm downloads](https://img.shields.io/npm/dm/specross.svg)](https://www.npmjs.com/package/specross) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) **Spec-driven development (SDD) for AI coding assistants.** --- ## What Specross does Specross is built for teams that practice SDD โ€” where one story spec drives everything: tech design, test cases, bug reports, handoff. It installs AI slash commands into your editor, each one spec-aware and traceable back to an AC. - BA writes and refines the spec - Dev generates tech notes from the spec - QC generates test cases from the spec - When the spec changes, Dev and QC get an exact diff of what breaks Every artifact is traceable: `TC-003 โ†’ AC-02 โ†’ US-4`. One chain, end to end. --- ## Install ```bash npx specross init ``` Supports **Claude Code**, **Cursor**, **Windsurf**, and **Codex**. Picks up whichever tools you use. Requires Node 16+. --- ## The SDD workflow ### Step 1 โ€” Write the spec (BA) ``` /ba:new-story order-management/create-order ``` Assigns a Story ID (`US-1`, `US-2`, ...) and asks questions to surface gaps before writing: ``` ๐Ÿ“‹ Open questions for: US-4 โ€” Create Order โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” 1. Which roles can create an order? Any permission differences? 2. What triggers this โ€” form submit, API call, scheduled job? 3. What does success look like from the user's perspective? 4. What happens if an item goes out of stock mid-checkout? 5. Can duplicate orders be submitted? How should that be handled? 6. Which fields are required vs optional? 7. Is payment captured at creation or later? โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ”โ” ``` BA answers โ†’ AI fills in `story.md`. Run `/ba:review` โ€” AI checks for vague AC, missing edge cases, undefined actors. ### Step 2 โ€” Release the spec (BA) ``` /ba:release order-management/create-order v1.0.0 ``` Story moves `ba/` โ†’ `stories/`. Dev and QC work from `stories/` only โ€” never from a draft. ### Step 3 โ€” Design and implement (Dev) ``` /dev:gen-tech-spec order-management/create-order ``` AI reads the story and generates: architecture overview, one file per API endpoint, data model changes, and a task list โ€” each task prefixed with the Story ID (`US-4-BE-01`, `US-4-BE-02`, ...) for full traceability. ``` /dev:implement order-management/create-order US-4-BE-01 ``` AI picks up that specific task, reads the relevant API contract and AC, checks the existing codebase for patterns, then implements it. Marks the task done in `tasks.md` when finished. When all tasks are done: ``` /dev:review order-management/create-order ``` AI reads the actual code, compares against story AC. Flags any gaps. ``` /dev:done order-management/create-order ``` Creates `handoff.md` โ€” what was built, known limitations, test environment setup. QC picks this up automatically. ### Step 4 โ€” Test against the spec (QC) ``` /qc:gen-test-cases order-management/create-order ``` AI generates test cases from the story, each TC-ID traceable to an AC. ``` /qc:run order-management/create-order ``` Interactive test run. `p` = pass, `f` = fail. On fail โ†’ AI generates a bug report linked to the AC. After a fix, run `/qc:run {story} TC-003` to retest โ€” on pass, bug auto-closes. ### Step 5 โ€” Spec changes (everyone) ``` /ba:impact order-management/create-order # preview what breaks before releasing /ba:release order-management/create-order v1.1.0 /dev:sync order-management/create-order # exact diff: what tech notes need updating /qc:sync order-management/create-order # exact diff: which TCs are now invalid ``` No one is surprised by a spec change. No one is working from a stale version. --- ## Traceability chain Every artifact in SDD links back to the spec: ``` US-4 (story) โ””โ”€โ”€ AC-02 โ€” item must be in stock at time of order โ”œโ”€โ”€ US-4-BE-02 (dev task) checkout validation in OrderService โ”œโ”€โ”€ TC-007 (test case) out-of-stock item blocked at checkout โ””โ”€โ”€ BUG-003 (bug report) stock check fires after payment intent ``` When a bug is filed, Dev knows exactly which AC it violated and which task was supposed to cover it. --- ## What gets installed ``` your-project/ โ”œโ”€โ”€ .claude/commands/ (or .cursor/rules/, .windsurf/rules/, .codex/instructions/) โ”‚ โ”œโ”€โ”€ ba/ โ† new-story ยท review ยท impact ยท release โ”‚ โ”œโ”€โ”€ dev/ โ† review ยท sync ยท done โ”‚ โ””โ”€โ”€ qc/ โ† gen-test-cases ยท run ยท retest ยท sync ยท bug-report โ”‚ โ”œโ”€โ”€ .claude/agents/ โ† ba.md ยท dev.md ยท qc.md (role personas) โ”œโ”€โ”€ _templates/ โ† output format (customize freely) โ”‚ โ”œโ”€โ”€ ba/ โ† BA drafts (work in progress) โ”œโ”€โ”€ stories/ โ† released specs (source of truth) โ””โ”€โ”€ CLAUDE.md โ† your stack, conventions, team ``` --- ## Command reference | Role | Command | What it does | |------|---------|--------------| | BA | `/ba:new-story {story}` | Create spec, assign US-N ID, surface gaps with questions | | BA | `/ba:review {story}` | Check AC completeness before releasing | | BA | `/ba:impact {story}` | Preview Dev/QC impact before releasing an update | | BA | `/ba:release {story} {version}` | Promote to stories/, write CHANGELOG | | Dev | `/dev:gen-tech-spec {story}` | spec โ†’ architecture, API contracts, task list | | Dev | `/dev:implement {story} {task-id}` | Implement a specific task against the spec | | Dev | `/dev:review {story}` | Check implementation vs AC | | Dev | `/dev:sync {story}` | Spec updated? Diff what tech notes need changing | | Dev | `/dev:done {story}` | Mark complete, write handoff.md for QC | | QC | `/qc:gen-test-cases {story}` | spec โ†’ test cases organized by AC | | QC | `/qc:run {story} [TC-ID]` | Run TCs interactively โ€” auto bug report on fail, auto-close on retest pass | | QC | `/qc:sync {story}` | Spec updated? Regenerate affected test cases | --- ## Customize `npx specross update` refreshes commands only โ€” agents and templates are never touched. **Agents** โ€” tune how AI thinks per role: seniority level, tone, team conventions, what to flag. **Templates** โ€” tune what AI outputs: add sections, rename fields, match your team's format. --- ## License MIT