jdd-sprint-kit 0.3.1

package/templates/.claude/rules/bmad-sprint-guide.md

@@ -0,0 +1,176 @@
+# Sprint Kit — BMad Method Execution Extension
+
+> Core principle: **Human judgment is the only lasting asset. All AI artifacts are disposable and regenerable.**
+>
+> AI builds, humans judge. Human input raises generation quality; human judgment sets direction.
+> — Judgment-Driven Development (`docs/judgment-driven-development.md`)
+>
+> Full product picture: `docs/blueprint.md` (§1 Problem ~ §8 Current State + Appendix)
+
+## Language Protocol
+
+### Config Loading
+
+1. Read `_bmad/bmm/config.yaml` — extract `communication_language`, `document_output_language`
+2. If not found, read `_bmad/core/config.yaml`
+3. If neither found, default both to `English`
+
+### Language Usage
+
+- **User-facing output** (progress messages, confirmations, errors, JP summaries): use `{communication_language}`
+- **Artifact content** (sprint-input.md body, specs, reports): use `{document_output_language}`
+- **YAML keys, enum values, file paths**: always English (machine-parseable)
+
+### Placeholder Interpretation
+
+`{communication_language}` is a **directive**, not a literal variable. It means: "Output this message in the language specified by `communication_language` from config.yaml." Commands and agents reference this protocol rather than loading config independently.
+
+### Context Passing Exception
+
+`communication_language` and `document_output_language` are **environment metadata** — execution settings, not domain data. The Conductor may pass them as parameters. This is equivalent to a BMad agent loading config.yaml directly.
+
+## Tool Stack
+
+| Tool | Role |
+|------|------|
+| **BMad Method** | Base platform: agents, workflow engine, facilitation (`_bmad/`) |
+| **Sprint Kit** | BMad execution extension: auto-pipeline, Specs, Deliverables, Prototype |
+| **Claude Code** | AI IDE — agent execution environment |
+| **Claude Code Native Teams** | Agent coordination, task dependency tracking (`Task`, `SendMessage`) |
+| **gh CLI** | GitHub Issue/PR management |
+
+## Route Selection
+
+Sprint Kit offers 3 routes based on user's input readiness.
+All routes converge into the same pipeline:
+
+```
+[Input + Brownfield + BMad] → [Specs] → JP1 → [Deliverables] → JP2 → [Execute]
+```
+
+### Sprint — When you have materials: AI builds, you judge
+
+Use when meeting notes, references, or a brief exist as unstructured context.
+AI auto-generates all planning artifacts; product expert judges at JP1/JP2.
+
+```
+Place materials in specs/{feature}/inputs/ → /sprint {feature-name}
+  Phase 0: Smart Launcher — analyze materials + generate sprint-input.md
+  → @auto-sprint (auto-invoked)
+  Phase 1: Brownfield 2-Pass → BMad Auto-Pipeline → Specs 4-file
+  → JP1: "Is this the right product for the customer?" (requirements judgment)
+  Phase 2: Deliverables (OpenAPI + DBML + BDD + Prototype)
+  → JP2: "Is this the experience the customer wants?" (prototype judgment)
+  → On approval: /parallel → /validate
+```
+
+### Guided — When exploration is needed: discover and define with AI
+
+Use for new products, new markets, or idea-stage work requiring systematic exploration.
+Build planning artifacts step-by-step through conversation with BMad agents.
+
+```
+BMad 12-step (human-AI dialogue):
+  /create-product-brief → /create-prd → /create-architecture → /create-epics
+→ /specs → JP1 → /preview → JP2
+→ /parallel → /validate
+```
+
+### Direct — When planning is complete: execute immediately
+
+Use when finished PRD + Architecture + Epics already exist.
+
+```
+/specs → JP1 → /preview → JP2
+→ /parallel → /validate
+```
+
+### Crossover
+
+Routes are not fixed. Adapt as needed:
+- Have materials but need deep exploration → use **Guided** route with materials as reference input
+- No materials, just want a quick prototype → start **Sprint** with a one-line brief
+- After completing BMad 12-step → same as **Direct** (`/specs` auto-detects BMad artifacts)
+
+**Format compatibility**: All routes use the same BMad format (YAML frontmatter + workflow sections) for planning-artifacts. Sprint Kit artifacts are directly recognized by BMad workflows, and vice versa.
+
+**Crossover support matrix**:
+
+| Transition | Support | Description |
+|------------|---------|-------------|
+| Guided → Sprint Kit | ✅ | `/specs` auto-detects `_bmad-output/`. "Continue fast" |
+| Sprint Kit → Guided deep-dive | ✅ | Guided agents read planning-artifacts for deeper exploration. "Start fast, explore deep" |
+| Sprint Kit → BMad validate | ✅ | planning-artifacts/ directly usable |
+| Sprint Kit → BMad Phase 4 | ⚠ | No auto-conversion. planning-artifacts are compatible, but tasks.md-specific data (DAG, Entropy, File Ownership) requires manual transfer |
+
+**Sprint Kit-exclusive concepts**: Entropy Tolerance, File Ownership, DAG-based parallel execution, and SSOT Reference Priority are Sprint Kit-only concepts not present in BMad. They are optimized for `/parallel` execution and are not carried over when switching to BMad Phase 4.
+
+**Scope Gate vs Implementation Readiness**: Sprint Kit's per-step Scope Gate is a finer-grained check than BMad's Implementation Readiness. If all Scope Gates PASS, BMad Implementation Readiness is also likely to pass. To run BMad `check-implementation-readiness` separately, reference planning-artifacts/ directly.
+
+> For small tasks, use BMad Quick Flow: `/quick-spec` → `/dev-story` → `/code-review`
+
+## BMad Agents
+
+- Mary (Analyst): brainstorming, research, Product Brief
+- John (PM): PRD, Epics & Stories
+- Winston (Architect): Architecture, ADR
+- Amelia (Dev): story implementation
+- Bob (SM): Sprint Planning, story preparation
+- Sally (UX Designer): UX Design
+- Barry (Quick Flow Solo Dev): Quick Spec → Dev → Review
+- Murat (Test Architect): Master Test Architect
+- Paige (Tech Writer): Technical Documentation
+
+## Sprint Agents
+
+### Auto Sprint
+- `@auto-sprint` — Sprint orchestration + Conductor 4 roles (Goal Tracking, Scope Gate, Budget, Redirect)
+- `@scope-gate` — 3-stage validation (Structured Probe + Checklist + Holistic Review)
+- `@brownfield-scanner` — MCP Brownfield collection (L1~L4)
+- `@deliverable-generator` — Full-stack artifact generation (Specs + OpenAPI + DBML + BDD + Prototype)
+
+### Execute
+- `@worker` — Task implementation in isolated worktree + Specmatic API contract self-verification
+- `@judge-quality` — Code structure, patterns, duplication, conventions + Specmatic contract compliance
+- `@judge-security` — OWASP Top 10 vulnerabilities, injection, auth bypass
+- `@judge-business` — Implementation verification against BMad PRD acceptance criteria
+
+## Sprint Commands
+
+- `/sprint` — **Sprint route**: Brief/materials → auto Specs + Deliverables + Prototype (2 JPs)
+- `/specs` — **Specs generation**: Planning Artifacts → Specs 4-file
+- `/preview` — **Deliverables generation**: Specs → OpenAPI + DBML + BDD + Prototype
+- `/parallel` — Multi-agent parallel execution
+- `/validate` — 3-Phase verification pipeline
+- `/circuit-breaker` — Course correction
+- `/summarize-prd` — PRD summary/analysis + feedback integration
+
+## Project Structure
+
+```
+{project-root}/
+├── CLAUDE.md                           # User project rules (not modified by Sprint Kit)
+├── .mcp.json                           # MCP server configuration
+├── .claude/
+│   ├── rules/                          # Sprint Kit rules
+│   ├── agents/                         # Sprint agents
+│   └── commands/                       # BMad + Sprint commands
+├── _bmad/                              # BMad Method (base platform)
+│   ├── bmm/                            # BMad agents, workflows
+│   └── docs/                           # Format guides (PRD, Blueprint, Sprint Input, etc.)
+├── _bmad-output/                       # BMad artifact output (Guided route)
+│   └── planning-artifacts/             # Product Brief, PRD, Architecture, Epics
+├── docs/                               # Framework documentation
+│   ├── blueprint.md                    # Product Blueprint (§1~§8 + Appendix)
+│   └── judgment-driven-development.md  # Design philosophy (JDD)
+├── specs/                              # Sprint artifacts (per feature)
+│   └── {feature}/
+│       ├── inputs/                     # User originals + sprint-input.md
+│       ├── planning-artifacts/         # BMad artifacts (Sprint/Direct route)
+│       ├── brownfield-context.md       # Frozen snapshot
+│       ├── requirements.md
+│       ├── design.md
+│       ├── tasks.md
+│       └── preview/                    # React + MSW prototype
+└── src/                                # Source code
+```

package/templates/.claude/rules/bmad-sprint-protocol.md

@@ -0,0 +1,178 @@
+# Sprint Execution Protocol
+
+## BMad Artifact Writing Rules
+
+- **When writing a PRD, always read `_bmad/docs/prd-format-guide.md` first and follow its format.** Comply with all rules: YAML frontmatter, section structure, FR/NFR quality criteria, Brownfield notation, etc.
+
+## Brownfield Data Flow (Sprint x MCP)
+
+Brownfield data is used at every Sprint phase. Sources are cumulatively collected from 3 origins: document-project, MCP, and local codebase.
+
+| Phase | Brownfield Usage |
+|-------|-----------------|
+| **Phase 0 Step 0f** (pre-Sprint) | Detect document-project + MCP + build tools → determine topology + `brownfield_status` |
+| **Pass 1: Broad Scan** (Sprint start) | Stage 0: consume document-project → Stage 1~4: MCP + local scan → brownfield-context.md **L1 + L2** |
+| **BMad Phase 1-3** | Reference brownfield-context.md L1+L2 |
+| **Pass 2: Targeted Scan** (post-Epics) | Reference Stage 0 data + backend-docs/client-docs MCP + local scan → brownfield-context.md **L3 + L4** |
+| **Specs generation** (`/specs`) | Copy frozen snapshot (@deliverable-generator Stage 2) |
+| **Parallel** (`/parallel`) | Workers read frozen snapshot |
+| **Validate** (`/validate`) | Judges verify against brownfield-context.md |
+
+## Causal Chain Propagation Flow (Optional)
+
+Causal Chain is optional. Only propagated when user opts in during Phase 0.
+
+| Phase | Causal Chain Usage |
+|-------|-------------------|
+| **Phase 0** (sprint.md) | Extract causal chain from Brief + References (opt-in) → record in sprint-input.md |
+| **Product Brief** (Mary) | Layer 1+2 problem definition (when causal_chain provided) |
+| **PRD** (John) | Classify FRs as core/enabling/supporting (when causal_chain provided); core FRs link to root_cause |
+| **Scope Gate** | causal_alignment check (when sprint_input_path provided): FR classification validation + unlinked FR warnings |
+| **JP1** | Advanced (Layer 3): Causal Chain Alignment + FR Linkage visualization (only when not feature_only) |
+| **Validate** (@judge-business) | Verify that core FR implementations actually resolve root_cause (when causal_chain provided) |
+
+## Brief Tracking Flow
+
+| Phase | Brief Tracking Usage |
+|-------|---------------------|
+| **Phase 0** (sprint.md) | Decompose Brief into sentences + assign BRIEF-N IDs → record in sprint-input.md `brief_sentences` |
+| **PRD** (John) | Tag each FR with `(source: BRIEF-N / DISC-N / AI-inferred)` |
+| **JP1** | Section 1: Brief sentence ↔ FR mapping table. Warn on unmapped sentences |
+| **JP1** | Section 2: Items beyond Brief (reference discovery vs AI inference, separated) |
+
+### Tracking Source Determination
+
+Tracking source is auto-determined by the `brief_sentences` field in sprint-input.md:
+
+| Condition | Tracking Source | Route |
+|-----------|----------------|-------|
+| `brief_sentences` exists and is non-empty | BRIEF-N based tracking | Sprint route |
+| `brief_sentences` missing or empty array | PRD Success Criteria > Measurable Outcomes | Guided / Direct route |
+
+In either case:
+- Verify each PRD FR maps to a tracking source item
+- Present "original intent ↔ FR mapping table" at JP1
+- Flag unmapped tracking source items as warnings
+
+## Specs File Pattern
+
+```
+specs/{feature}/
+├── inputs/                     # Phase 0 (user originals + Sprint Input SSOT, read-only)
+│   ├── brief.md                # User Brief (AI-generated if only references exist)
+│   ├── *.md / *.pdf / ...      # Reference materials (optional)
+│   └── sprint-input.md         # Phase 0 auto-generated SSOT (includes Causal Chain)
+│
+├── planning-artifacts/         # BMad Phase 1-3 artifacts (retained per project)
+│   ├── product-brief.md        # Product Brief
+│   ├── prd.md                  # PRD
+│   ├── architecture.md         # Architecture + ADR
+│   ├── epics-and-stories.md    # Epics & Stories
+│   └── brownfield-context.md   # L1~L4 raw collection (appended during work)
+│
+├── sprint-log.md               # Sprint execution log (timeline + decisions + issues)
+├── brownfield-context.md       # Frozen snapshot (L1~L4, for Workers)
+├── entity-dictionary.md        # Entity Dictionary
+├── requirements.md             # PRD → requirements
+├── design.md                   # Architecture → design
+├── tasks.md                    # Epics → parallel tasks + Entropy + File Ownership
+│
+├── api-spec.yaml               # OpenAPI 3.1 (API contract — shared by MSW Mock + Specmatic)
+├── api-sequences.md            # Mermaid sequence diagrams
+├── schema.dbml                 # Database schema (DBML)
+├── bdd-scenarios/              # Gherkin acceptance tests
+├── state-machines/             # XState definitions (when applicable)
+├── decision-log.md             # ADRs + AI reasoning trace
+├── traceability-matrix.md      # FR → Design → Task → BDD → API mapping
+├── key-flows.md                # Key user flows step-by-step (for JP2 verification)
+├── readiness.md                # JP1/JP2 Readiness data (for Layer 0 auto-approval)
+└── preview/                    # React + MSW prototype (npm run dev)
+```
+
+## Handoff Rules
+
+### BMad → Execute (on Phase 3 completion)
+
+When BMad Phase 3 passes Implementation Readiness:
+1. Verify artifacts in `specs/{feature}/planning-artifacts/` (PRD, Architecture, Epics)
+2. Run `/specs` to generate Specs 4-file
+3. Tag Entropy Tolerance + assign File Ownership
+
+### BMad Guided Route → Sprint Execution
+
+When BMad 12-step artifacts exist in `_bmad-output/planning-artifacts/`:
+1. `/specs` auto-discovers and places them into `specs/{feature}/planning-artifacts/`
+2. `/specs` runs without sprint-input.md
+3. Goals are extracted from PRD's Success Criteria > Measurable Outcomes
+4. Brownfield scan runs normally within `/specs`
+
+### On Worker Completion
+
+When a Worker completes a task:
+1. Mark task as completed via TaskUpdate
+2. Close GitHub Issue via `gh issue close`
+3. Notify dependent Workers via SendMessage
+
+### On Circuit Breaker Trigger
+
+- 3 consecutive or 5 cumulative VALIDATE failures in the same category → `/circuit-breaker` auto-triggers
+- Minor → fix specs → re-execute
+- Major → re-run Auto Sprint Phase 1 (non-Auto Sprint: BMad `/bmad/bmm/workflows/correct-course`)
+
+## File Ownership Rules
+
+Rules to prevent file conflicts during PARALLEL phase:
+1. Each task's owned files are declared in `specs/{feature}/tasks.md`
+2. Workers may only modify files assigned to them
+3. Shared type/interface files are created before PARALLEL starts
+4. To modify shared files, request via SendMessage to team lead
+
+## Judgment Point Criteria
+
+JPs are not technical quality gates — they are customer-lens judgment moments for product experts.
+See `docs/judgment-driven-development.md` Customer-Lens Judgment Points.
+
+### JP1: "Is this the right product for the customer?"
+
+- **Judgment target**: requirements, user scenarios, feature scope, priorities
+- **Presentation format**: customer journey narrative + original intent ↔ FR mapping + structural checklist
+- **Response**: Confirm / Comment
+
+### JP2: "Is this the experience the customer wants?"
+
+- **Judgment target**: prototype, screen flows, interactions
+- **Presentation format**: working prototype + key scenario walkthrough guide
+- **Response**: Confirm / Comment
+
+### Comment Handling Flow
+
+When Comment is selected at a JP, the following flow applies.
+This flow handles Party Mode discoveries, Advanced Elicitation results, and direct feedback identically.
+Regardless of how the feedback was discovered, the processing mechanism is the same.
+
+1. **Feedback input**: User provides modification details as free text
+2. **Impact analysis**: System analyzes feedback scope and produces:
+   - For apply-fix: list of affected files (upstream + downstream) + estimated time
+   - For regenerate: restart Phase + estimated time
+3. **Present options**: Two options with cost:
+   - **Apply fix + propagate**: Direct edits in existing artifacts + bidirectional propagation to dependent files (N files, ~M min)
+   - **Regenerate**: Re-run pipeline from the affected Phase (~M min)
+4. **User selects**: User chooses based on cost
+5. **Execute + verify**:
+   - Apply fix: edit all files → mandatory Scope Gate verification → return to JP on PASS
+   - Regenerate: re-run pipeline from the affected Phase → includes Scope Gate
+
+### Regeneration Scope Reference Table
+
+Guide for determining regeneration start point based on feedback magnitude:
+
+| Feedback Magnitude | JP1 Regeneration Scope | JP2 Regeneration Scope |
+|-------------------|----------------------|----------------------|
+| Direction change (what to build changes) | Abort Sprint → edit brief.md → restart | Phase 1 from start (PRD onward, re-pass JP1) |
+| Scope/UX change | From PRD (Step 2b) | From PRD (Step 2b, re-pass JP1) |
+| Technical/design change | From Architecture (Step 2c) | From affected BMad step (re-pass JP1) |
+| Task structure change | Regenerate Specs (Step 3) | Regenerate Deliverables only (Step 5) |
+| Spec/prototype adjustment | N/A | Regenerate Deliverables only (Step 5) |
+
+This table is a reference for the system when calculating regeneration scope during impact analysis.
+Users see the calculated cost alongside the options.

package/templates/.claude/settings.json

@@ -0,0 +1,50 @@
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sprint-pre-compact.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sprint-session-recovery.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-readonly-paths.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/desktop-notify.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/.mcp.json.example

@@ -0,0 +1,16 @@
+{
+  "mcpServers": {
+    "my-backend-docs": {
+      "command": "sh",
+      "args": ["-c", "npx -y @modelcontextprotocol/server-filesystem ~/path/to/backend-docs"]
+    },
+    "my-client-docs": {
+      "command": "sh",
+      "args": ["-c", "npx -y @modelcontextprotocol/server-filesystem ~/path/to/client-docs"]
+    },
+    "my-svc-map": {
+      "command": "sh",
+      "args": ["-c", "npx -y @modelcontextprotocol/server-filesystem path/to/svc-map-data"]
+    }
+  }
+}

package/templates/_bmad/docs/architecture-to-epics-checklist.md

@@ -0,0 +1,59 @@
+# Architecture → Epics 변환 체크리스트
+
+Architecture 문서에서 Epics & Stories로 변환할 때 누락되기 쉬운 항목을 점검합니다.
+이 체크리스트는 create-epics-and-stories 워크플로우의 Step 1 (Validate Prerequisites)에서 참조합니다.
+
+## 1. FR → Story 매핑 완전성
+
+- [ ] 모든 FR이 최소 1개 Story에 매핑되었는가?
+- [ ] FR Coverage Map에 누락된 FR이 없는가?
+- [ ] Phase별 FR이 올바른 Epic에 배치되었는가? (Phase 1a FR이 Phase 1b Epic에 있지 않은가?)
+
+## 2. BROWNFIELD 태그 전파
+
+- [ ] PRD의 `[BROWNFIELD]` 태그가 Story에 전파되었는가?
+- [ ] Story의 Tags에 `(기존 확장)` vs `(신규)` 구분이 정확한가?
+- [ ] brownfield-context.md의 L2/L3 발견 사항이 관련 Story의 Brownfield 필드에 반영되었는가?
+- [ ] 기존 확장 Story에 확장 대상 서비스/컴포넌트명이 명시되었는가?
+
+## 3. Architecture 결정 → Story AC 반영
+
+| Architecture 결정 | Story에 반영되어야 할 항목 |
+|-------------------|--------------------------|
+| DDD 패키지 구조 | Story AC에 패키지 경로 명시 |
+| 캐시 전략 (Redis Set) | 캐시 관련 Story에 구체적 Redis 명령어 |
+| 레이스 컨디션 방지 (Redis Lock) | API Story AC에 Lock 사양 명시 |
+| AOP 감사 로깅 | 감사 로깅 Story에 @BizLog 활용 명시 |
+| 피처 플래그 | 각 Phase Story에 Flagsmith 플래그명 |
+| 크로스 프레임워크 브릿지 | Vue↔React 전환 Story에 bridge 함수명 |
+| DB 테이블 네이밍 | 엔티티 Story에 le_ prefix 준수 명시 |
+
+## 4. NFR → Story 반영
+
+- [ ] 성능 NFR이 관련 Story의 AC에 수치로 반영되었는가? (예: NFR1 → Story 2.6 AC "< 1초")
+- [ ] 보안 NFR이 인증/권한 Story의 AC에 반영되었는가?
+- [ ] 접근성 NFR이 UI Story의 AC에 반영되었는가? (WCAG, 터치 타겟)
+- [ ] 신뢰성 NFR이 교차 검증 Story의 AC에 반영되었는가?
+
+## 5. Story 크기 & 의존성
+
+- [ ] 모든 Story가 단일 개발자 세션에 완료 가능한 크기인가?
+- [ ] 3개 이상의 독립적 관심사를 포함하는 Story가 없는가? (Entity + Cache + Logging → 분할 필요)
+- [ ] Dependencies/Enables 필드가 모든 Story에 존재하는가?
+- [ ] 순환 의존성이 없는가?
+- [ ] 전방 의존성(미래 Story에 의존)이 없는가?
+
+## 6. Phase 독립성
+
+- [ ] Phase 1a Epic은 Phase 1b 없이 독립 배포 가능한가?
+- [ ] Phase 1b Epic은 Phase 1a 위에서 독립 배포 가능한가?
+- [ ] Growth Epic은 Phase 1a+1b 위에서 독립 배포 가능한가?
+- [ ] 각 Phase 내 Epic 간 순환 의존이 없는가?
+
+## 사용법
+
+Epic 워크플로우의 Step 1 또는 Step 4 (Final Validation)에서:
+```
+이 체크리스트를 로드하여 누락 항목을 점검한다:
+_bmad/docs/architecture-to-epics-checklist.md
+```