jdd-sprint-kit 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kangmin Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# JDD Sprint Kit
+
+**"A single-line brief becomes a working prototype."**
+
+Judgment-Driven Development execution extension built on BMad Method. AI builds, humans judge. User inputs (meeting notes, references, existing system context) raise AI's first-generation quality, and human time is spent only at customer-lens judgment points (JP1, JP2).
+
+> Design philosophy: [Judgment-Driven Development](docs/judgment-driven-development.md)
+> Full architecture and Sprint walkthrough: [Blueprint](docs/blueprint.md)
+
+---
+
+## Overall Flow
+
+```mermaid
+flowchart LR
+    A["1. Brief Input"] --> B["2. Existing System\n(Brownfield Scan)"]
+    B --> C["3. Planning\n(BMAD Auto-Pipeline)"]
+    C --> D["4. Specs\n(Specs Generation)"]
+    D --> JP1{{"JP1\nIs this the right\nproduct?"}}
+    JP1 -->|Approve| E["5. Deliverables\n(Deliverables Gen)"]
+    JP1 -->|Revise| C
+    E --> JP2{{"JP2\nIs this the right\nexperience?"}}
+    JP2 -->|Approve| F["6. Parallel\n(Implementation)"]
+    JP2 -->|Revise| E
+    JP2 -.->|Re-examine requirements| JP1
+    F --> G["7. Validate"]
+    G -->|Pass| H["Done"]
+    G -->|Repeated failure| CB["Course Correction\n(Circuit Breaker)"]
+    CB --> C
+
+    style JP1 fill:#FFD700,stroke:#333
+    style JP2 fill:#FFD700,stroke:#333
+    style CB fill:#FF6B6B,stroke:#333
+```
+
+Human involvement happens at exactly **2 points** (JP1, JP2) — everything else runs autonomously. If JP2 reveals issues with the requirements themselves, it loops back to JP1 — this is not a failure, but a normal discovery prompted by concrete deliverables.
+
+---
+
+## What Gets Generated
+
+A single Sprint run auto-generates the following artifacts:
+
+- **3 spec documents** — requirements.md, design.md, tasks.md
+- **OpenAPI 3.1 YAML** — API specification + MSW Mock + Specmatic contract tests
+- **DBML schema** — Database design (viewable as ERD on dbdiagram.io)
+- **BDD/Gherkin scenarios** — Given-When-Then acceptance tests
+- **React + MSW prototype** — Clickable prototype via `npm run dev`
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) CLI
+- Node.js 18+
+- Git, GitHub CLI (`gh`)
+- [BMad Method](https://github.com/nicholasgriffintn/bmad-method) (`npx bmad-method install`)
+
+### Installation
+
+```bash
+npx jdd-sprint-kit init
+```
+
+An interactive wizard detects your environment and installs Sprint Kit files.
+
+### (Optional) MCP Setup
+
+To connect existing service data, configure MCP servers:
+
+```bash
+cp .mcp.json.example .mcp.json
+# Edit .mcp.json: update local paths for your environment
+```
+
+### First Sprint Run
+
+```bash
+# In Claude Code
+/sprint "Describe the feature you want to build"
+```
+
+### Tutorial — Try Without MCP
+
+To experience the full Sprint Kit pipeline, use the included example project:
+
+```bash
+# In Claude Code
+/sprint test-tutor-excl
+```
+
+This is a scenario for adding a "tutor exclusion" feature to a fictional EduTalk service. 4 meeting notes are prepared in `specs/test-tutor-excl/inputs/`, and `brownfield-context.md` substitutes for MCP scan results. No MCP setup required.
+
+---
+
+## Route Selection
+
+3 routes are available based on your input readiness. All routes converge into the same pipeline.
+
+```
+[Input + Brownfield + BMad] → [Specs] → JP1 → [Deliverables] → JP2 → [Execute]
+
+Sprint:   |←──────────────── Fully Auto ───────────────────────→|
+Guided:   |←── BMad Dialog ──→|←────────── Auto ───────────────→|
+Direct:                        |←── Auto ──────────────────────→|
+```
+
+| Route | Entry Point | Best When |
+|-------|-------------|-----------|
+| **Sprint** | `/sprint "Brief"` or `/sprint feature-name` | You have materials (meeting notes, references) — AI builds, you judge |
+| **Guided** | BMad 12-step → `/specs` → `/preview` | Exploration needed — discover and define with AI |
+| **Direct** | `/specs` → `/preview` | Planning is complete — execute immediately |
+
+> For small tasks, use BMad Quick Flow: `/quick-spec` → `/dev-story` → `/code-review`
+
+Routes are not fixed. If you have materials but need deep exploration, use Guided with materials as reference input. After completing BMad 12-step, `/specs` auto-detects the artifacts — same as Direct.
+
+> Details: [Blueprint §4.3 Route Selection](docs/blueprint.md#43-route-selection)
+
+---
+
+## Brownfield — Existing System Integration
+
+AI must understand the existing service structure to avoid creating duplicate APIs or breaking existing screen flows. Brownfield data is cumulatively collected from **3 sources**:
+
+1. **document-project artifacts** — Structured docs generated by BMad `/document-project` workflow scanning the existing codebase
+2. **MCP servers** — External memory stores the AI queries on demand
+3. **Local codebase** — Direct scan of source code in the same repository
+
+### Brownfield Context Generation
+
+#### Auto-Generation (Sprint Route)
+
+`/sprint` automatically generates brownfield-context.md:
+
+1. **Phase 0** — Topology detection: detect document-project presence, MCP connectivity, build tools to determine project type (`standalone` / `co-located` / `msa` / `monorepo`)
+2. **Pass 1 (Broad Scan)** — Collect domain concepts (L1) and behavior patterns (L2) based on Brief keywords
+3. **Pass 2 (Targeted Scan)** — After Architecture/Epics, collect integration points (L3) and code-level details (L4)
+
+Results are recorded in `specs/{feature}/planning-artifacts/brownfield-context.md` as L1~L4 layers.
+
+#### Pre-Sprint Preparation: document-project (Recommended)
+
+Running BMad `/document-project` before Sprint improves scan quality:
+
+```bash
+# In Claude Code
+/document-project
+```
+
+This analyzes the existing codebase and generates structured docs under `_bmad-output/` (`project-overview.md`, `api-contracts.md`, `data-models.md`, etc.). Sprint's Brownfield Scanner uses these as seed data to narrow MCP/local scan scope.
+
+#### MCP Server Configuration
+
+To connect external service data, configure MCP servers:
+
+| MCP Server | Provided Information |
+|------------|---------------------|
+| `backend-docs` | API specs, domain policies, business rules, data models |
+| `client-docs` | Component structure, state management patterns, code conventions, screen flows |
+| `svc-map` | Customer journeys, screen screenshots, flow graphs, service maps |
+| `figma` | Latest wireframes, design tokens, component specs (live OAuth) |
+
+#### Manual Preparation (Without MCP)
+
+You can manually write brownfield-context.md and provide it to Sprint without MCP:
+
+```bash
+# Place directly in the feature directory
+specs/{feature}/brownfield-context.md
+# or
+specs/{feature}/planning-artifacts/brownfield-context.md
+```
+
+Sprint detects existing files and uses them instead of re-scanning those levels. See `_bmad/docs/brownfield-context-format.md` for the format. A manually written brownfield-context.md sample is included in the tutorial example (`specs/test-tutor-excl/`).
+
+#### Greenfield Projects
+
+For Greenfield projects with no existing system, Sprint works normally without Brownfield data. Auto-detected in Phase 0 — no configuration needed.
+
+> Details: [Blueprint §4.1 System Components](docs/blueprint.md#41-system-components)
+
+---
+
+## Project Structure
+
+```
+{project-root}/
+├── CLAUDE.md                        # Project-specific rules (user-maintained)
+├── .mcp.json                        # MCP server config (.gitignored)
+├── .claude/
+│   ├── agents/                      # Sprint agents (8)
+│   ├── commands/                    # Sprint commands + BMad agents/workflows
+│   ├── rules/                       # Sprint rules (bmad-*.md)
+│   ├── hooks/                       # Hook scripts (notification, protection, recovery)
+│   └── settings.json                # Hook settings
+├── _bmad/                           # BMad Method (runtime reference)
+│   └── docs/                        # Format guides
+├── preview-template/                # Prototype scaffold (Vite + React + MSW)
+├── specs/                           # Per-feature Sprint artifacts
+│   └── {feature}/
+│       ├── inputs/                  # User Brief + reference materials
+│       ├── planning-artifacts/      # BMad artifacts (PRD, Architecture, Epics)
+│       ├── requirements.md          # Requirements
+│       ├── design.md                # Design
+│       ├── tasks.md                 # Tasks (Entropy + File Ownership)
+│       ├── brownfield-context.md    # Existing system context
+│       ├── api-spec.yaml            # OpenAPI 3.1
+│       ├── schema.dbml              # DB schema
+│       ├── bdd-scenarios/           # Gherkin acceptance tests
+│       └── preview/                 # React + MSW prototype
+└── docs/                            # Framework documentation
+```
+
+> Sprint Kit files (`.claude/agents/`, `.claude/commands/`, `.claude/rules/bmad-*`, `_bmad/`) should not be modified directly. Update via `npx jdd-sprint-kit update`.
+
+---
+
+## Multi-IDE Support
+
+Sprint Kit's canonical definition files live in `.claude/`. Other AI IDEs beyond Claude Code are also supported.
+
+**Claude Code** — Default IDE. No additional setup required.
+
+**Codex CLI** — Use the `--ide` option during installation to generate Codex files:
+
+```bash
+npx jdd-sprint-kit init --ide claude-code,codex
+```
+
+In Codex, run Sprint commands via `$sprint`, `$specs`, `$preview`, `$parallel`, `$validate`.
+
+**Gemini Code Assist** — TOML wrappers are auto-generated in `.gemini/commands/`.
+
+> When the canonical files (`.claude/`) are modified, `npx jdd-sprint-kit update` also refreshes the converted files.
+
+---
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [Blueprint](docs/blueprint.md) | Full product picture — 8-Section (Problem → Thesis → User Model → Value Chain → Judgment → Constraints → Risk → Current State) |
+| [Judgment-Driven Development](docs/judgment-driven-development.md) | Design philosophy + definition and discussion of design judgments |
+| [BMad Method](https://github.com/nicholasgriffintn/bmad-method) | AI role-play framework (external) |
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
+
+const program = new Command();
+
+program
+  .name('jdd-sprint-kit')
+  .description('Judgment-Driven Development toolkit for BMad Method')
+  .version(pkg.version);
+
+program
+  .command('init')
+  .description('Install Sprint Kit into the current project')
+  .option('-y, --yes', 'Non-interactive mode (accept all defaults)')
+  .option('--ide <tools>', 'IDE tools (comma-separated: claude-code,codex)', 'claude-code')
+  .option('--dry-run', 'Show what would be installed without making changes')
+  .action(async (options) => {
+    const { runInit } = await import('../src/commands/init.js');
+    await runInit(options);
+  });
+
+program
+  .command('update')
+  .description('Update Sprint Kit files to the latest version')
+  .option('-y, --yes', 'Non-interactive mode (accept all defaults)')
+  .option('--dry-run', 'Show what would be updated without making changes')
+  .action(async (options) => {
+    const { runUpdate } = await import('../src/commands/update.js');
+    await runUpdate(options);
+  });
+
+program
+  .command('compat-check')
+  .description('Verify BMad Method compatibility')
+  .option('--json', 'Output results as JSON')
+  .action(async (options) => {
+    const { runCompatCheck } = await import('../src/commands/compat-check.js');
+    await runCompatCheck(options);
+  });
+
+program.parse();

package/compat/baseline.json

@@ -0,0 +1,6 @@
+{
+  "version": "0.1.0",
+  "bmadVersion": "6.0.0-Beta.8",
+  "generatedAt": "2026-02-16",
+  "fingerprints": {}
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "jdd-sprint-kit",
+  "version": "0.3.1",
+  "description": "Judgment-Driven Development toolkit for BMad Method",
+  "type": "module",
+  "bin": {
+    "jdd-sprint-kit": "bin/cli.js"
+  },
+  "scripts": {
+    "prepublishOnly": "node scripts/build-templates.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/",
+    "compat/"
+  ],
+  "dependencies": {
+    "commander": "^12.0.0",
+    "@clack/prompts": "^0.9.0",
+    "fs-extra": "^11.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kangminlee-maker/jdd-sprint-kit.git"
+  },
+  "keywords": [
+    "bmad",
+    "sprint",
+    "ai-agent",
+    "claude-code",
+    "automation",
+    "jdd",
+    "judgment-driven-development"
+  ]
+}

package/src/commands/compat-check.js

@@ -0,0 +1,178 @@
+import * as p from '@clack/prompts';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+import { detect, checkBmadCompat } from '../lib/detect.js';
+import { BMAD_COMPAT, BMAD_INTERFACES, SPRINT_KIT_VERSION } from '../lib/manifest.js';
+import { collectFingerprints, compareFingerprints, resolveBmadPath } from '../lib/fingerprint.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+export async function runCompatCheck(options = {}) {
+  const { json: jsonOutput = false } = options;
+  const projectDir = process.cwd();
+
+  const env = detect(projectDir);
+  const results = {
+    version: SPRINT_KIT_VERSION,
+    bmadVersion: env.bmadVersion,
+    bmadCompat: checkBmadCompat(env.bmadVersion),
+    stages: [],
+    overallVerdict: 'PASS',
+  };
+
+  // --- Stage 1: Existence ---
+  const stage1 = { name: 'existence', checks: [], verdict: 'PASS' };
+
+  for (const iface of BMAD_INTERFACES) {
+    const filePath = resolveBmadPath(projectDir, iface);
+    const exists = filePath ? existsSync(filePath) : false;
+    stage1.checks.push({
+      interface: `${iface.type}:${iface.path}`,
+      exists,
+      path: filePath,
+    });
+    if (!exists) stage1.verdict = 'FAIL';
+  }
+
+  results.stages.push(stage1);
+
+  // --- Stage 2: Structure ---
+  const stage2 = { name: 'structure', checks: [], verdict: 'PASS' };
+
+  // Check config.yaml has required fields
+  const configPath = join(projectDir, '_bmad', 'bmm', 'config.yaml');
+  if (existsSync(configPath)) {
+    const configContent = readFileSync(configPath, 'utf-8');
+    const requiredFields = ['project_name', 'planning_artifacts', 'communication_language'];
+    for (const field of requiredFields) {
+      const has = new RegExp(`^${field}:`, 'm').test(configContent);
+      stage2.checks.push({ file: 'config.yaml', field, exists: has });
+      if (!has) stage2.verdict = 'WARN';
+    }
+  }
+
+  // Check agent-manifest.csv has expected columns
+  const manifestPath = join(projectDir, '_bmad', '_config', 'agent-manifest.csv');
+  if (existsSync(manifestPath)) {
+    const manifestContent = readFileSync(manifestPath, 'utf-8');
+    const firstLine = manifestContent.split('\n')[0] || '';
+    const requiredColumns = ['name', 'role', 'path'];
+    for (const col of requiredColumns) {
+      const has = firstLine.toLowerCase().includes(col);
+      stage2.checks.push({ file: 'agent-manifest.csv', column: col, exists: has });
+      if (!has) stage2.verdict = 'WARN';
+    }
+  }
+
+  results.stages.push(stage2);
+
+  // --- Stage 3: Interface fingerprint ---
+  const stage3 = { name: 'fingerprint', changes: [], verdict: 'PASS' };
+
+  const baselinePath = join(__dirname, '..', '..', 'compat', 'baseline.json');
+  if (existsSync(baselinePath)) {
+    const baseline = JSON.parse(readFileSync(baselinePath, 'utf-8'));
+    const currentFingerprints = collectFingerprints(projectDir);
+
+    for (const [key, currentFp] of Object.entries(currentFingerprints)) {
+      if (baseline.fingerprints[key]) {
+        const diff = compareFingerprints(baseline.fingerprints[key], currentFp);
+        if (diff.changes.length > 0) {
+          stage3.changes.push({ interface: key, ...diff });
+          if (diff.verdict === 'REVIEW_NEEDED') stage3.verdict = 'REVIEW_NEEDED';
+          else if (diff.verdict === 'WARN' && stage3.verdict === 'PASS') stage3.verdict = 'WARN';
+        }
+      }
+    }
+  } else {
+    stage3.verdict = 'SKIP';
+    stage3.reason = 'No baseline.json found';
+  }
+
+  results.stages.push(stage3);
+
+  // Overall verdict
+  if (results.stages.some(s => s.verdict === 'FAIL')) {
+    results.overallVerdict = 'FAIL';
+  } else if (results.stages.some(s => s.verdict === 'REVIEW_NEEDED')) {
+    results.overallVerdict = 'REVIEW_NEEDED';
+  } else if (results.stages.some(s => s.verdict === 'WARN')) {
+    results.overallVerdict = 'WARN';
+  }
+
+  // BMad version compat
+  if (results.bmadCompat === 'below_minimum') {
+    results.overallVerdict = 'FAIL';
+  }
+
+  // Output
+  if (jsonOutput) {
+    console.log(JSON.stringify(results, null, 2));
+    process.exit(results.overallVerdict === 'FAIL' ? 1 : 0);
+    return;
+  }
+
+  // Pretty output
+  p.intro(`BMad Compatibility Check — Sprint Kit v${SPRINT_KIT_VERSION}`);
+
+  // Version info
+  const compatLabel = {
+    compatible: '✓ compatible',
+    above_verified: '⚠ above verified',
+    below_minimum: '✗ below minimum',
+    unknown: '? unknown',
+  }[results.bmadCompat];
+
+  p.note(
+    [
+      `BMad Method: ${env.bmadVersion || 'not found'} ${compatLabel}`,
+      `Verified:    ${BMAD_COMPAT.verified} (${BMAD_COMPAT.verifiedAt})`,
+      `Minimum:     ${BMAD_COMPAT.minimum}`,
+    ].join('\n'),
+    '버전 호환성'
+  );
+
+  // Stage 1: Existence
+  const existLines = stage1.checks.map(c =>
+    `  ${c.exists ? '✓' : '✗'} ${c.interface}`
+  );
+  p.note(existLines.join('\n'), `Stage 1: 존재 검증 — ${stage1.verdict}`);
+
+  // Stage 2: Structure
+  if (stage2.checks.length > 0) {
+    const structLines = stage2.checks.map(c =>
+      `  ${c.exists ? '✓' : '✗'} ${c.file}: ${c.field || c.column}`
+    );
+    p.note(structLines.join('\n'), `Stage 2: 구조 검증 — ${stage2.verdict}`);
+  }
+
+  // Stage 3: Fingerprint
+  if (stage3.verdict === 'SKIP') {
+    p.log.info(`Stage 3: Fingerprint — SKIP (${stage3.reason})`);
+  } else if (stage3.changes.length === 0) {
+    p.log.success('Stage 3: Fingerprint — PASS (변경 없음)');
+  } else {
+    const fpLines = [];
+    for (const change of stage3.changes) {
+      fpLines.push(`  ${change.interface}: ${change.verdict}`);
+      for (const c of change.changes) {
+        fpLines.push(`    ${c.change} ${c.type}: ${c.value}`);
+      }
+    }
+    p.note(fpLines.join('\n'), `Stage 3: Fingerprint — ${stage3.verdict}`);
+  }
+
+  // Overall
+  const verdictEmoji = {
+    PASS: '✓',
+    WARN: '⚠',
+    REVIEW_NEEDED: '⚠',
+    FAIL: '✗',
+  }[results.overallVerdict];
+
+  p.outro(`${verdictEmoji} Overall: ${results.overallVerdict}`);
+
+  process.exit(results.overallVerdict === 'FAIL' ? 1 : 0);
+}