specross 1.0.0

package/README.md

@@ -0,0 +1,207 @@
+# Specross
+
+**Spec-driven AI collaboration for BA, Dev, and QC teams.**
+
+```
+BA writes story  →  Dev generates tech-spec + scaffold  →  ship
+                 ↘  QC generates test cases + scripts   ↗
+```
+
+One story. Three roles. No drift.
+
+---
+
+## The problem
+
+Specs live in Notion. Test cases live in Jira. Code lives in Git. Nobody's reading the same thing.
+
+BA updates a story — Dev doesn't know. QC writes test cases from memory, not from AC. Tech spec drifts from the story the moment it's written.
+
+Specross fixes this by making the story the single source of truth, and giving each role an AI command that reads directly from it.
+
+---
+
+## How it works
+
+**BA** drafts a story in `ba/` — problem statement, actors, acceptance criteria, edge cases — and releases it to `stories/` when ready.
+
+**Dev** runs `/dev:gen-tech-spec` — AI reads the story and generates a tech spec in the exact format your team uses. Then `/dev:gen-scaffold` to generate a code scaffold.
+
+**QC** runs `/qc:gen-test-cases` — AI reads the same story and generates test cases covering every AC and edge case, with a coverage matrix.
+
+**When BA updates the story** — `/ba:release` auto-diffs the new version against the previous one and tells Dev and QC exactly what changed. They run `/dev:sync` and `/qc:sync` to see what needs updating.
+
+No meetings. No copy-paste. No guessing.
+
+---
+
+## Install
+
+**Option 1 — npx (no install needed):**
+```bash
+npx specross init
+```
+
+**Option 2 — global install:**
+```bash
+npm install -g specross
+specross init
+```
+
+Run in your project root. It asks which AI tool you're using, then copies commands and agents to the right place.
+
+```
+Which AI tool are you using?
+
+  1. Claude Code   →  .claude/commands/  +  .claude/agents/
+  2. Cursor        →  .cursor/rules/
+  3. Windsurf      →  .windsurf/rules/
+  4. Other         →  ai/commands/  +  ai/agents/
+```
+
+**Update commands to latest version:**
+```bash
+npx specross update
+# or
+specross update
+```
+
+Never overwrites your agent and template customizations.
+
+**Requirements:** Node.js 16+
+
+---
+
+## What gets installed
+
+```
+your-project/
+├── {ai-folder}/             ← commands + agents (location depends on your AI tool)
+│   ├── commands/
+│   │   ├── ba/              ← /ba:new-story, /ba:review, /ba:release, /ba:impact
+│   │   ├── dev/             ← /dev:gen-tech-spec, /dev:gen-scaffold, /dev:review, /dev:sync
+│   │   └── qc/              ← /qc:gen-test-cases, /qc:gen-scripts, /qc:bug-report, /qc:sync
+│   └── agents/
+│       ├── ba.md            ← HOW the AI thinks as BA
+│       ├── dev.md           ← HOW the AI thinks as Dev
+│       └── qc.md            ← HOW the AI thinks as QC
+│
+├── _templates/              ← WHAT format the AI outputs
+│   ├── story.md
+│   ├── tech-spec.md
+│   ├── test-cases.md
+│   └── bug-report.md
+│
+├── ba/                      ← BA draft workspace (work in progress)
+├── stories/                 ← released stories (source of truth for Dev & QC)
+└── CLAUDE.md                ← fill in your tech stack, team conventions, architecture
+```
+
+---
+
+## Workflow
+
+### BA — write and release
+
+```bash
+# Create a feature and break it into specs
+/ba:new-story order-management
+/ba:new-story order-management/create-order
+/ba:new-story order-management/list-orders
+
+# Review for gaps before releasing
+/ba:review order-management/create-order
+
+# Release draft → stories/ (auto-diffs if update)
+/ba:release order-management/create-order v1.0.0
+```
+
+Story lives at `ba/order-management/create-order/story.md` while in draft. On release, it's promoted to `stories/` — that's the version Dev and QC work from.
+
+---
+
+### Dev — from story to code
+
+```bash
+/dev:gen-tech-spec order-management/create-order   # story → tech spec
+/dev:gen-scaffold  order-management/create-order   # tech spec → code scaffold
+/dev:review        order-management/create-order   # check impl vs AC
+/dev:sync          order-management/create-order   # story updated? see what changed
+```
+
+Output: `stories/order-management/create-order/tech/tech-spec.md`
+
+---
+
+### QC — from story to tests
+
+```bash
+/qc:gen-test-cases order-management/create-order          # story → test cases
+/qc:gen-scripts    order-management/create-order          # test cases → automation scripts
+/qc:bug-report     order-management/create-order TC-003   # structured bug report
+/qc:sync           order-management/create-order          # story updated? see what changed
+```
+
+Output: `stories/order-management/create-order/test/test-cases.md`
+
+---
+
+### Story update flow
+
+```bash
+# BA edits ba/order-management/create-order/story.md
+/ba:release order-management/create-order v1.1.0
+# → auto-diffs vs stories/, summarizes what changed, estimates impact on Dev + QC
+
+/dev:sync order-management/create-order   # AI shows which parts of tech-spec need updating
+/qc:sync  order-management/create-order   # AI shows which test cases are now invalid
+```
+
+---
+
+## Story folder structure
+
+```
+stories/
+└── order-management/
+    ├── story.md                       ← overview spec
+    ├── CHANGELOG.md
+    ├── create-order/                  ← sub-spec (one per flow)
+    │   ├── story.md                   ← source of truth
+    │   ├── CHANGELOG.md
+    │   ├── docs/
+    │   │   └── release-v1.0.0.md
+    │   ├── tech/
+    │   │   ├── tech-spec.md           ← Dev output
+    │   │   └── .spec-lock             ← which story version this is based on
+    │   └── test/
+    │       ├── test-cases.md          ← QC output
+    │       └── .spec-lock
+    └── list-orders/
+        └── ...
+```
+
+---
+
+## Customize
+
+Two layers, both preserved on `npx specross update`:
+
+**Agents** — change how the AI behaves per role (seniority, tone, rules, red flags):
+```
+agents/ba.md    agents/dev.md    agents/qc.md
+```
+
+**Templates** — change the output format for your team:
+```
+_templates/story.md        _templates/tech-spec.md
+_templates/test-cases.md   _templates/bug-report.md
+```
+
+Edit agents to change how the AI *thinks*. Edit templates to change what it *outputs*.
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// ─── Colours ──────────────────────────────────────────────────────────────────
+const c = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  green:  '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue:   '\x1b[34m',
+  cyan:   '\x1b[36m',
+  red:    '\x1b[31m',
+};
+
+const ok   = (msg) => console.log(`${c.green}✓${c.reset}  ${msg}`);
+const skip = (msg) => console.log(`${c.yellow}→${c.reset}  ${c.dim}${msg}${c.reset}`);
+const info = (msg) => console.log(`${c.blue}ℹ${c.reset}  ${msg}`);
+const err  = (msg) => console.log(`${c.red}✗${c.reset}  ${msg}`);
+const head = (msg) => console.log(`\n${c.bold}${c.cyan}${msg}${c.reset}`);
+const rule = ()    => console.log(`${c.dim}${'─'.repeat(56)}${c.reset}`);
+
+// ─── AI tool destinations ──────────────────────────────────────────────────────
+const AI_TOOLS = {
+  '1': {
+    name: 'Claude Code',
+    commandsDir: '.claude/commands',
+    agentsDir:   '.claude/agents',
+    hint: 'Slash commands auto-loaded. Run: claude .',
+  },
+  '2': {
+    name: 'Cursor',
+    commandsDir: '.cursor/rules',
+    agentsDir:   '.cursor/rules',
+    hint: 'Rules auto-loaded by Cursor. Open your project in Cursor.',
+  },
+  '3': {
+    name: 'Windsurf',
+    commandsDir: '.windsurf/rules',
+    agentsDir:   '.windsurf/rules',
+    hint: 'Rules auto-loaded by Windsurf. Open your project in Windsurf.',
+  },
+  '4': {
+    name: 'Other / Manual',
+    commandsDir: 'ai/commands',
+    agentsDir:   'ai/agents',
+    hint: 'Files copied to ai/. Load them manually into your AI tool.',
+  },
+};
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => rl.question(question, ans => { rl.close(); resolve(ans.trim()); }));
+}
+
+function copyDir(src, dest, overwrite = false) {
+  const results = { copied: [], skipped: [] };
+  if (!fs.existsSync(src)) return results;
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath  = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      const sub = copyDir(srcPath, destPath, overwrite);
+      results.copied.push(...sub.copied);
+      results.skipped.push(...sub.skipped);
+    } else {
+      if (fs.existsSync(destPath) && !overwrite) {
+        results.skipped.push(destPath);
+      } else {
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+        fs.copyFileSync(srcPath, destPath);
+        results.copied.push(destPath);
+      }
+    }
+  }
+  return results;
+}
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+    return true;
+  }
+  return false;
+}
+
+function rel(p) { return path.relative(process.cwd(), p); }
+
+function readConfig(cwd) {
+  const cfgPath = path.join(cwd, '.specross.json');
+  if (fs.existsSync(cfgPath)) return JSON.parse(fs.readFileSync(cfgPath, 'utf8'));
+  return null;
+}
+
+function writeConfig(cwd, cfg) {
+  fs.writeFileSync(path.join(cwd, '.specross.json'), JSON.stringify(cfg, null, 2));
+}
+
+// ─── init ─────────────────────────────────────────────────────────────────────
+
+async function cmdInit() {
+  const cwd  = process.cwd();
+  const tmpl = path.join(__dirname, '..', 'template');
+
+  console.log(`\n${c.bold}${c.cyan}Specross${c.reset} — installing into ${c.bold}${cwd}${c.reset}\n`);
+  rule();
+
+  // Ask which AI tool
+  head('Which AI tool are you using?');
+  console.log('');
+  Object.entries(AI_TOOLS).forEach(([key, tool]) => {
+    console.log(`  ${c.bold}${key}${c.reset}. ${tool.name}`);
+  });
+  console.log('');
+
+  let toolKey = await ask(`  ${c.yellow}Enter number (default: 1) ${c.reset}`);
+  if (!toolKey || !AI_TOOLS[toolKey]) toolKey = '1';
+  const tool = AI_TOOLS[toolKey];
+
+  console.log(`\n  Installing for ${c.bold}${c.cyan}${tool.name}${c.reset}\n`);
+  rule();
+
+  // Save choice so `update` knows where to update
+  writeConfig(cwd, { aiTool: toolKey, commandsDir: tool.commandsDir, agentsDir: tool.agentsDir });
+
+  // 1. commands — always safe to overwrite
+  head('Step 1 — Commands');
+  const cmdRes = copyDir(path.join(tmpl, 'commands'), path.join(cwd, tool.commandsDir), true);
+  cmdRes.copied.forEach(f => ok(`Installed  ${rel(f)}`));
+
+  // 2. agents — skip if already exist (user may have customized)
+  head('Step 2 — Role agents  (yours if already customized)');
+  const agentRes = copyDir(path.join(tmpl, 'agents'), path.join(cwd, tool.agentsDir), false);
+  agentRes.copied.forEach(f  => ok(`Installed  ${rel(f)}`));
+  agentRes.skipped.forEach(f => skip(`Kept       ${rel(f)}  (your custom version)`));
+
+  // 3. templates — skip if already exist
+  head('Step 3 — Output templates  (yours if already customized)');
+  const tmplRes = copyDir(path.join(tmpl, '_templates'), path.join(cwd, '_templates'), false);
+  tmplRes.copied.forEach(f  => ok(`Installed  ${rel(f)}`));
+  tmplRes.skipped.forEach(f => skip(`Kept       ${rel(f)}  (your custom version)`));
+
+  // 4. project folders
+  head('Step 4 — Project folders');
+  for (const folder of ['ba', 'stories']) {
+    const dir = path.join(cwd, folder);
+    if (ensureDir(dir)) {
+      fs.writeFileSync(path.join(dir, '.gitkeep'), '');
+      ok(`Created    ${folder}/`);
+    } else {
+      skip(`Exists     ${folder}/`);
+    }
+  }
+
+  // 5. CLAUDE.md
+  head('Step 5 — CLAUDE.md');
+  const mdDest = path.join(cwd, 'CLAUDE.md');
+  if (!fs.existsSync(mdDest)) {
+    fs.copyFileSync(path.join(tmpl, 'CLAUDE.md'), mdDest);
+    ok('Created    CLAUDE.md');
+  } else {
+    skip('Kept       CLAUDE.md  (already exists)');
+  }
+
+  rule();
+  console.log(`\n${c.green}${c.bold}Specross installed!${c.reset}\n`);
+  console.log(`${c.bold}Next steps:${c.reset}`);
+  console.log(`  1. Fill in ${c.bold}CLAUDE.md${c.reset} with your tech stack and team`);
+  console.log(`  2. Customize agents in:   ${c.cyan}${tool.agentsDir}/${c.reset}`);
+  console.log(`  3. Customize templates in: ${c.cyan}_templates/${c.reset}`);
+  console.log(`  4. ${tool.hint}`);
+  console.log(`  5. First story:  ${c.cyan}/ba:new-story my-feature${c.reset}\n`);
+}
+
+// ─── update ───────────────────────────────────────────────────────────────────
+
+async function cmdUpdate() {
+  const cwd  = process.cwd();
+  const tmpl = path.join(__dirname, '..', 'template');
+
+  console.log(`\n${c.bold}${c.cyan}Specross${c.reset} — updating\n`);
+  rule();
+
+  // Read saved config to know where commands live
+  const cfg = readConfig(cwd);
+  let tool;
+
+  if (cfg) {
+    tool = AI_TOOLS[cfg.aiTool];
+    info(`Detected: ${tool.name} (from .specross.json)\n`);
+  } else {
+    head('Which AI tool are you using?');
+    console.log('');
+    Object.entries(AI_TOOLS).forEach(([key, t]) => {
+      console.log(`  ${c.bold}${key}${c.reset}. ${t.name}`);
+    });
+    console.log('');
+    let toolKey = await ask(`  ${c.yellow}Enter number (default: 1) ${c.reset}`);
+    if (!toolKey || !AI_TOOLS[toolKey]) toolKey = '1';
+    tool = AI_TOOLS[toolKey];
+    writeConfig(cwd, { aiTool: toolKey, commandsDir: tool.commandsDir, agentsDir: tool.agentsDir });
+  }
+
+  info('Commands will be updated to the latest version.');
+  info('Agents and templates will NOT be touched — your customizations are safe.\n');
+
+  const ans = await ask(`  ${c.yellow}Continue? (y/N) ${c.reset}`);
+  if (ans.toLowerCase() !== 'y') { console.log('\nCancelled.\n'); process.exit(0); }
+
+  // Only overwrite commands
+  head('Updating commands');
+  const cmdRes = copyDir(path.join(tmpl, 'commands'), path.join(cwd, tool.commandsDir), true);
+  cmdRes.copied.forEach(f => ok(`Updated  ${rel(f)}`));
+
+  rule();
+  console.log(`\n${c.green}${c.bold}Commands updated!${c.reset}`);
+  console.log(`${c.dim}Agents and templates were not changed.${c.reset}\n`);
+
+  // Offer optional resets
+  const resetAgents = await ask(`  ${c.yellow}Also reset agents to default? Overwrites customizations. (y/N) ${c.reset}`);
+  if (resetAgents.toLowerCase() === 'y') {
+    const res = copyDir(path.join(tmpl, 'agents'), path.join(cwd, tool.agentsDir), true);
+    res.copied.forEach(f => ok(`Reset  ${rel(f)}`));
+    console.log('');
+  }
+
+  const resetTmpls = await ask(`  ${c.yellow}Also reset templates to default? Overwrites customizations. (y/N) ${c.reset}`);
+  if (resetTmpls.toLowerCase() === 'y') {
+    const res = copyDir(path.join(tmpl, '_templates'), path.join(cwd, '_templates'), true);
+    res.copied.forEach(f => ok(`Reset  ${rel(f)}`));
+    console.log('');
+  }
+
+  console.log(`${c.green}${c.bold}Done!${c.reset}\n`);
+}
+
+// ─── help ─────────────────────────────────────────────────────────────────────
+
+function cmdHelp() {
+  console.log(`
+${c.bold}${c.cyan}specross${c.reset} — Spec-driven AI collaboration for BA, Dev & QC teams
+
+${c.bold}Usage:${c.reset}
+  npx specross init      Install Specross into the current project
+  npx specross update    Update commands only (keeps your customizations)
+  npx specross help      Show this help
+
+${c.bold}Supported AI tools:${c.reset}
+  1. Claude Code  → .claude/commands/  + .claude/agents/
+  2. Cursor       → .cursor/rules/
+  3. Windsurf     → .windsurf/rules/
+  4. Other        → ai/commands/  + ai/agents/
+
+${c.bold}What gets installed:${c.reset}
+  commands/       12 slash commands for BA, Dev, QC
+  agents/         Role personas — customize per role (never overwritten by update)
+  _templates/     Output format — customize freely (never overwritten by update)
+  ba/             BA draft workspace
+  stories/        Released stories (source of truth for Dev & QC)
+  CLAUDE.md       Project config — fill this in!
+
+${c.bold}Commands available after install:${c.reset}
+  /help  (list all commands with descriptions)
+
+  /ba:new-story   /ba:review   /ba:release   /ba:impact
+  /dev:gen-tech-spec   /dev:gen-scaffold   /dev:review   /dev:sync   /dev:status
+  /qc:gen-test-cases   /qc:gen-scripts   /qc:bug-report   /qc:sync   /qc:status
+
+${c.dim}Docs: https://github.com/ethandev147/specross${c.reset}
+`);
+}
+
+// ─── Entry ────────────────────────────────────────────────────────────────────
+
+const command = process.argv[2] || 'help';
+switch (command) {
+  case 'init':   cmdInit().catch(console.error);   break;
+  case 'update': cmdUpdate().catch(console.error); break;
+  case 'help': case '--help': case '-h': cmdHelp(); break;
+  default:
+    err(`Unknown command: ${command}`);
+    cmdHelp();
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "specross",
+  "version": "1.0.0",
+  "description": "Spec-driven AI collaboration for BA, Dev, and QC teams — built for Claude Code",
+  "keywords": ["claude", "claude-code", "ai", "agile", "ba", "dev", "qc", "specflow"],
+  "homepage": "https://github.com/ethandev147/specross",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ethandev147/specross.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=16"
+  },
+  "bin": {
+    "specross": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "scripts": {
+    "test": "node bin/cli.js --help"
+  }
+}

package/template/CLAUDE.md

@@ -0,0 +1,106 @@
+# Specross — Project Context for Claude
+
+> This file tells Claude about your project. Fill in the sections below before your team starts using the commands.
+
+---
+
+## What We're Building
+
+<!-- Describe the product in 2–4 sentences. What is it? Who uses it? What problem does it solve? -->
+
+---
+
+## Tech Stack
+
+<!-- List your languages, frameworks, and key libraries. Claude uses this when generating tech specs and scaffolds. -->
+
+- **Language:** e.g. TypeScript / Python / Go
+- **Frontend:** e.g. React, Next.js / Vue / None
+- **Backend:** e.g. Node.js + Express / FastAPI / Rails
+- **Database:** e.g. PostgreSQL / MongoDB / MySQL
+- **Testing:** e.g. Jest + Playwright / pytest + Selenium / Cypress
+- **Infrastructure:** e.g. AWS / GCP / Vercel
+
+---
+
+## Folder Conventions
+
+<!-- Tell Claude where things live in your project. -->
+
+- **Source code:** `src/`
+- **Tests:** `tests/`
+- **Stories:** `stories/`
+
+### Naming conventions
+- Files: `kebab-case` (e.g. `user-auth.service.ts`)
+- Classes / Components: `PascalCase`
+- Variables / Functions: `camelCase`
+
+---
+
+## Architecture Patterns
+
+<!-- Describe how your codebase is structured so Claude generates consistent code. -->
+
+- **Pattern:** e.g. MVC / Clean Architecture / Feature-based folders
+- **API style:** e.g. REST / GraphQL / tRPC
+- **Auth:** e.g. JWT in Authorization header / Session cookie / OAuth2
+
+---
+
+## Coding Standards
+
+<!-- Any rules Claude should follow when generating code. -->
+
+- Always add JSDoc / docstrings to public functions
+- Prefer `const` over `let`; avoid `var`
+- Use async/await over `.then()` chains
+- Error responses use format: `{ error: { code: string, message: string } }`
+- (Add your own standards here)
+
+---
+
+## Team
+
+<!-- Optional: list role names and owners so Claude can reference them in outputs. -->
+
+| Role | Name |
+|------|------|
+| BA | |
+| Dev Lead | |
+| QC Lead | |
+| Product Owner | |
+
+---
+
+## Specross — How We Work
+
+This repo uses Specross. Commands are available via Claude Code:
+
+| Role | Command | Purpose |
+|------|---------|---------|
+| BA | `/ba:new-story [name]` | Create a new story |
+| BA | `/ba:review [story]` | Review story for gaps |
+| BA | `/ba:impact [story] [v-old] [v-new]` | Impact report on spec changes |
+| Dev | `/dev:gen-tech-spec [story]` | Generate tech spec from story |
+| Dev | `/dev:gen-scaffold [story]` | Generate code scaffold from tech spec |
+| Dev | `/dev:review [story]` | Review implementation vs requirements |
+| QC | `/qc:gen-test-cases [story]` | Generate test cases from story |
+| QC | `/qc:gen-scripts [story]` | Generate automation scripts |
+| QC | `/qc:bug-report [story] [TC-ID]` | Generate structured bug report |
+
+### Story lifecycle
+
+```
+BA: /ba:new-story → fill in story.md → /ba:review
+                                              ↓
+                         Dev: /dev:gen-tech-spec → /dev:gen-scaffold → implement → /dev:review
+                         QC:  /qc:gen-test-cases → /qc:gen-scripts  → test      → /qc:bug-report
+```
+
+### AI principles for this project
+
+1. AI assists, humans decide. All AI output is a first draft.
+2. Review all generated tech specs and test cases before treating them as final.
+3. Prompts with more context produce better output — fill in this CLAUDE.md fully.
+4. If output is wrong, refine and re-run the command. Don't accept poor output.