jdd-sprint-kit 0.3.1

package/templates/.claude/commands/summarize-prd.md

@@ -0,0 +1,290 @@
+---
+name: summarize-prd
+description: 'Summarize and analyze a PRD document, collect feedback, and edit the original PRD. Use the analyze subcommand for PRD analysis. Pass the project folder name as an argument.'
+---
+
+# /summarize-prd — PRD Summary, Analysis & Edit
+
+> **Dispatch Target**: None (direct CLI execution, no sub-agent delegation)
+
+## Purpose
+
+Summarize and analyze PRD documents in `prd/`, then **directly edit the original PRD file** based on user feedback.
+
+## When to Use
+
+When you need to summarize, analyze, or edit a PRD document.
+
+## Inputs
+
+Parse `$ARGUMENTS`:
+- `$ARGUMENTS[0]`: project-name or `help`
+- `$ARGUMENTS[1]`: optional `analyze`
+
+Formats:
+- `<project-name>` → Default Mode (summary → feedback → edit original)
+- `<project-name> analyze` → Analyze Mode (summary + PRD analysis → feedback → edit original)
+- `help` → Help Mode (usage instructions)
+
+If argument is `help` → **Help Mode**. If last argument is `analyze` → **Analyze Mode**. Otherwise → **Default Mode**.
+
+## Procedure
+
+Load config per Language Protocol in bmad-sprint-guide.md.
+
+### Help Mode
+
+If argument is `help`, output the following (in {communication_language}) and exit.
+
+```
+/summarize-prd Usage
+
+Summarize a PRD document, collect feedback, and edit the original PRD.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Usage:
+  /summarize-prd <project-name>           Default mode
+  /summarize-prd <project-name> analyze   Analyze mode
+  /summarize-prd help                     This help
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Default Mode
+  Summarize the PRD, then collect feedback to directly edit the original PRD.
+
+  Flow: Select PRD → Summary output → Feedback → Edit original → Repeat → Done
+
+  Example:
+    /summarize-prd trial-lesson-flow
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Analyze Mode (analyze)
+  Outputs a PRD analysis report in addition to the summary.
+  Auto-reviews internal conflicts, ambiguous definitions, missing edge cases, etc.
+
+  Analysis items:
+    1. Internal conflicts     - Contradictory content between sections
+    2. Ambiguous definitions  - Vague expressions like TBD, "appropriate"
+    3. Missing edge cases     - Unhandled error/state combinations
+    4. Success metric issues  - Unmeasurable metrics
+    5. Priority/dependency    - P0 depending on P1, etc.
+    6. Technical risks        - Concurrency, API design gaps, etc.
+
+  Severity: CRITICAL | WARNING | INFO
+
+  Example:
+    /summarize-prd trial-lesson-flow analyze
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Feedback Loop (shared by Default/Analyze)
+  After summary (+analysis) output, your feedback directly edits the original PRD.
+  A preview is shown before applying changes, requiring your approval.
+  Enter "done" to finish.
+
+  Feedback examples:
+    - "Fix the conflict issue #1 from the analysis report"
+    - "Add DAU metric to success metrics"
+    - "Change the error message in FR17"
+    - "Make the reservation failure UX policy more specific"
+```
+
+### Common Steps
+
+#### 1. Verify Project Folder
+
+If project folder name is empty, list projects in `prd/` and ask for selection (in {communication_language}).
+
+Verify that `prd/<project-name>/` folder exists. If not, list projects in `prd/` and guide to the correct name (in {communication_language}).
+
+#### 2. Select PRD File
+
+List all `.md` files in the folder and **confirm which file is the latest PRD** (in {communication_language}).
+
+#### 3. Read and Summarize PRD
+
+Read the user-specified file and summarize with the following structure (in {document_output_language}):
+
+```markdown
+# [Project Name] PRD Summary
+
+## One-Line Summary
+[Core purpose of the project in one sentence]
+
+## Background & Intent
+- Why this project is needed
+- Core problem being solved
+
+## Key Features (by priority)
+
+### MVP (P0)
+- Feature 1: description
+- Feature 2: description
+
+### MVP (P1)
+- Feature 3: description
+
+### Growth Phase
+- Feature 4: description
+
+## Success Metrics
+| Metric | Current | Target |
+|--------|---------|--------|
+| Metric name | Current value | Target value |
+
+## Technical Considerations
+- Key technical issues or constraints
+
+## MVP Scope vs Follow-up
+- What's included in MVP / what's excluded (summary)
+```
+
+### Default Mode
+
+After summary output, enter **Feedback Loop** immediately.
+
+### Analyze Mode
+
+After summary output, **output PRD analysis report** then enter Feedback Loop.
+
+#### Analysis Report Writing
+
+Thoroughly review the full PRD and find issues per category. Mark categories with no issues as "No issues found."
+
+```markdown
+# PRD Analysis Report
+
+## 1. Internal Conflicts
+Find contradictory or conflicting content within the document.
+- Section A says X, but Section B says Y
+- Numbers/conditions differ across sections
+- Priorities stated differently across sections
+
+Example:
+> WARNING: **[Conflict]** Executive Summary says "reservation period +2 days", but
+> FR4-1 says "3 days including today". Same policy but confusing expression.
+> Location: Executive Summary vs FR4-1
+
+## 2. Ambiguous or Unclear Definitions
+Find vague expressions that make development/QA judgment difficult.
+- Unclear expressions like "appropriate", "as needed", "etc."
+- Requirements missing specific values/conditions
+- Items remaining as TBD
+
+Example:
+> WARNING: **[Ambiguous]** FR3 says "specific image assets require further discussion (TBD)".
+> Must be finalized before development starts.
+> Location: FR3
+
+## 3. Missing Edge Cases / Omitted Scenarios
+Find unhandled cases in documented flows.
+- Missing error/failure scenarios
+- Unaddressed user state combinations
+- Concurrency/timing issues
+
+Example:
+> WARNING: **[Missing]** When network disconnects right after reservation completion,
+> server sees success but client perceives failure — this case is not in test scenarios.
+> Location: QA Considerations > Test Scenarios
+
+## 4. Success Metrics / Measurability Issues
+Review realism of target numbers and specificity of measurement methods.
+- Metrics with unclear measurement methods
+- Metrics lacking current values to judge achievement
+- Misaligned causal relationships between metrics
+
+## 5. Priority / Dependency Issues
+Find problems with feature dependencies or priority placement.
+- P0 feature depending on P1 feature
+- Growth Phase features conflicting with MVP features
+- Features that should come first but are placed later
+
+## 6. Technical Risks
+Find implementation concerns.
+- Inadequate concurrency/race condition handling
+- Gap between performance targets and feature complexity
+- Missing parts of API design
+
+## Summary
+
+| Severity | Count | Key Issues |
+|----------|-------|------------|
+| CRITICAL (must fix) | N | ... |
+| WARNING (recommend fix) | N | ... |
+| INFO (can improve) | N | ... |
+```
+
+### Feedback Loop
+
+#### 5. Request Feedback
+
+After summary (+ analysis report in Analyze Mode) output, request feedback for editing the original PRD (in {communication_language}).
+
+```
+---
+If there are parts to modify/improve in the original PRD, please provide feedback.
+If none, enter "done".
+
+Examples:
+- "Fix the conflict issue #1 from the analysis report"
+- "Success metrics are missing DAU. Add it."
+- "Reservation failure UX policy is vague. Make it specific."
+- "Change the error message in FR17 requirement."
+```
+
+#### 6. Edit Original PRD
+
+When user provides feedback:
+
+1. **Find the relevant section in the original PRD file.**
+   - Read the original PRD file selected in step 2 to locate the edit target.
+
+2. **Show edit preview** (in {communication_language}):
+   ```
+   Edit target: prd/<project-name>/<filename>
+
+   Changes:
+   - (before) ...
+   + (after) ...
+
+   Apply these changes?
+   ```
+
+3. **Edit the original file after user approval.**
+   - On approval: edit the original PRD file using the Edit tool.
+   - On rejection: collect additional feedback on the edit direction.
+
+4. **Request feedback again after edit** (in {communication_language}):
+   ```
+   ---
+   Original PRD has been updated.
+   If there are more parts to modify, please provide feedback. If none, enter "done".
+   ```
+
+Repeat this process until user enters "done".
+
+#### 7. Completion
+
+Output (in {communication_language}):
+```
+PRD editing complete.
+Modified file: prd/<project-name>/<filename>
+```
+
+## Outputs
+
+- Modified PRD file: `prd/<project-name>/<filename>`
+
+## Constraints
+
+1. **Always cite evidence.** Specify the exact location in the original PRD (section name, FR number, table, etc.) with a `Location:` marker.
+2. **Classify severity.**
+   - CRITICAL: Conflicts/omissions that must be resolved before development
+   - WARNING: Should fix, but development can proceed
+   - INFO: Suggestions for quality improvement
+3. **Provide fix suggestions.** Don't just point out problems — concretely suggest how to fix them.
+4. **Don't force issues.** Mark categories with genuinely no problems as "No issues found."
+
+$ARGUMENTS

package/templates/.claude/commands/validate.md

@@ -0,0 +1,143 @@
+---
+description: "Entropy-based 3-Phase verification pipeline (Auto + AI Judge + Visual)"
+---
+
+# /validate — Multi-Phase Verification Pipeline
+
+> **Dispatch Target**: `@judge-quality` + `@judge-security` + `@judge-business` (parallel)
+
+## Purpose
+
+A multi-dimensional verification pipeline that adjusts verification density based on Entropy Tolerance.
+
+## When to Use
+
+After Worker implementation is complete. Run after PARALLEL completion + merge.
+
+## Inputs
+
+`$ARGUMENTS`: not used
+
+Prerequisites:
+- PARALLEL complete: all Worker tasks done
+- Code merged into main branch
+- Build succeeds
+
+## Procedure
+
+Load config per Language Protocol in bmad-sprint-guide.md.
+
+### Phase 1: Automated Verification (all tasks)
+Applied to all Entropy levels:
+
+```bash
+npm run lint
+npm run type-check
+npm run test
+npm run build
+```
+
+Phase 1 failure → request fix from file's owning Worker → re-run Phase 1 after fix
+
+### Phase 2: AI Judge Verification (Medium + Low Entropy)
+Run Judge agents in parallel. Pass each Judge:
+- `changed_files`: result of `git diff --name-only {base_branch}...HEAD`
+- `feature_dir`: `specs/{feature}/`
+- `brownfield_path`: `specs/{feature}/brownfield-context.md`
+
+1. **Code Quality Judge** (`judge-quality`):
+   - Code structure, patterns, duplication
+   - Project convention compliance
+   - **Existing codebase pattern compliance** (based on configured client-docs MCP)
+   - Specmatic API contract final verification
+
+2. **Security Judge** (`judge-security`):
+   - OWASP Top 10 vulnerability check
+   - Injection, XSS, auth bypass
+   - **Consistency with existing auth/permission patterns** (based on configured backend-docs MCP)
+
+3. **Business Logic Judge** (`judge-business`):
+   - Implementation verification against BMad PRD acceptance criteria
+   - Architecture ADR compliance
+   - **Alignment with existing domain policies/customer journeys** (based on configured backend-docs, svc-map MCP)
+
+**Low Entropy tasks**: Judges operate in Adversarial mode — thorough review, findings classified by severity:
+- `CRITICAL`: Functional failure or security vulnerability. Must fix.
+- `HIGH`: Design violation or performance issue. Must fix.
+- `SUGGESTION`: Style, refactoring suggestions. Record only, does not block.
+
+**Adversarial exit condition**: PASS when 0 new CRITICAL/HIGH findings. SUGGESTION-only means pass.
+
+Judge invocation — **must invoke all 3 Tasks simultaneously in a single response**:
+```
+Task(subagent_type: "judge-quality", model: "sonnet")
+  prompt: "Read .claude/agents/judge-quality.md and follow it.
+    changed_files: {changed_files}
+    feature_dir: specs/{feature}/
+    brownfield_path: specs/{feature}/brownfield-context.md"
+
+Task(subagent_type: "judge-security", model: "sonnet")
+  prompt: "Read .claude/agents/judge-security.md and follow it.
+    changed_files: {changed_files}
+    feature_dir: specs/{feature}/
+    brownfield_path: specs/{feature}/brownfield-context.md"
+
+Task(subagent_type: "judge-business", model: "sonnet")
+  prompt: "Read .claude/agents/judge-business.md and follow it.
+    changed_files: {changed_files}
+    feature_dir: specs/{feature}/
+    brownfield_path: specs/{feature}/brownfield-context.md
+    sprint_input_path: specs/{feature}/inputs/sprint-input.md"
+```
+→ Collect all 3 results
+→ Critical finding present → FAIL
+→ Classify each finding's `failure_source`:
+  - `local`: Worker can fix (code bugs, test failures, etc.)
+  - `upstream:architecture`: Architecture ADR violation, design mismatch
+  - `upstream:prd`: PRD AC contradiction, requirements conflict
+→ `local` findings → request Worker fix → re-run only affected Judge
+→ `upstream` findings → forward to Circuit Breaker (include failure_source)
+
+### Phase 3: Visual Verification (UI-related tasks)
+Applied only to tasks with UI:
+1. Visual regression check against BMad UX Design
+2. **Change verification against existing service map screens** (configured svc-map MCP screenshots)
+3. **Match verification against latest Figma design mockups** (`figma` MCP)
+4. Responsive design check
+5. Basic accessibility check
+
+### Entropy-Based Phase Matrix
+
+| Entropy | Phase 1 | Phase 2 | Phase 3 |
+|---------|---------|---------|---------|
+| High    | O       | -       | -       |
+| Medium  | O       | O       | (if UI) |
+| Low     | O       | O (Adversarial) | (if UI) |
+
+## Constraints
+
+### Fix Process
+After `/parallel` completion, Workers are inactive. On verification failure, follow this procedure:
+1. Judge generates failure report (file path + line number + severity + fix suggestion)
+2. **Create new fix tasks** (TaskCreate) per failed task
+3. Re-run small-scale `/parallel` for fix implementation
+4. Re-run `/validate` for re-verification
+
+### Retry Limits
+- Max **5 iterations** of the above cycle
+- Adversarial mode (Low Entropy): failure determined by CRITICAL/HIGH only. SUGGESTIONs do not count toward loop
+- **5 cumulative failures** or **3 consecutive failures in same category** → Circuit Breaker auto-triggers
+- On Circuit Breaker trigger → run `/circuit-breaker`
+
+## Outputs
+Verification result report:
+```markdown
+## VALIDATE Report: {feature}
+- Phase 1 (Auto): PASS/FAIL — [details]
+- Phase 2 (Judge): PASS/FAIL — [X critical, Y warnings]
+  - Failure Sources: {N} local, {M} upstream
+- Phase 3 (Visual): PASS/FAIL/SKIP
+- **Overall: PASS/FAIL**
+- **Upstream Issues** (if any):
+  - {finding} → failure_source: upstream:{stage} → suggested_fix: {fix}
+```

package/templates/.claude/hooks/desktop-notify.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+# Notification hook: Send desktop notification when Claude needs user input
+# macOS only — JP1/JP2 대기 시 사용자에게 알림
+
+if [[ "$(uname)" == "Darwin" ]]; then
+  osascript -e 'display notification "Claude Code needs your attention" with title "JDD Sprint Kit"' 2>/dev/null
+fi
+
+exit 0

package/templates/.claude/hooks/protect-readonly-paths.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# PreToolUse(Write|Edit) hook: Block writes to read-only paths
+# Sprint 원본 입력 파일과 BMad 설정 파일을 보호
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Protected patterns
+case "$FILE_PATH" in
+  */specs/*/inputs/*)
+    # Extract feature dir from path: specs/{feature}/inputs/...
+    FEATURE_DIR=$(echo "$FILE_PATH" | sed -n 's|.*/specs/\([^/]*\)/inputs/.*|\1|p')
+    SPRINT_INPUT="specs/${FEATURE_DIR}/inputs/sprint-input.md"
+    # Allow writes before Phase 0 completes (sprint-input.md not yet generated)
+    if [ -n "$FEATURE_DIR" ] && [ -f "$SPRINT_INPUT" ]; then
+      jq -n '{
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          permissionDecision: "deny",
+          permissionDecisionReason: "specs/*/inputs/ is read-only after Phase 0. sprint-input.md already exists."
+        }
+      }'
+      exit 0
+    fi
+    ;;
+  */_bmad/_config/*)
+    jq -n '{
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "deny",
+        permissionDecisionReason: "_bmad/_config/ is read-only. Agent manifest and config must not be modified during Sprint."
+      }
+    }'
+    exit 0
+    ;;
+esac
+
+exit 0

package/templates/.claude/hooks/sprint-pre-compact.sh

@@ -0,0 +1,42 @@
+#!/bin/bash
+# PreCompact hook: Save active Sprint state before compaction
+# Sprint 진행 중 auto-compaction 발생 시 상태를 recovery 파일에 저장
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd')
+
+# Find the most recently modified sprint-log.md
+SPRINT_LOG=$(find "$CWD/specs" -name "sprint-log.md" -type f -maxdepth 3 2>/dev/null | head -1)
+
+if [ -z "$SPRINT_LOG" ]; then
+  exit 0  # No active sprint
+fi
+
+FEATURE_DIR=$(dirname "$SPRINT_LOG")
+FEATURE_NAME=$(basename "$FEATURE_DIR")
+SPRINT_INPUT="$FEATURE_DIR/inputs/sprint-input.md"
+
+# Extract sprint-input frontmatter (between --- markers)
+FRONTMATTER=""
+if [ -f "$SPRINT_INPUT" ]; then
+  FRONTMATTER=$(sed -n '/^---$/,/^---$/p' "$SPRINT_INPUT" 2>/dev/null)
+fi
+
+# Read sprint-log
+LOG_CONTENT=$(cat "$SPRINT_LOG" 2>/dev/null)
+
+# Save recovery file
+RECOVERY_FILE="$CWD/.claude/sprint-recovery.json"
+jq -n \
+  --arg feature "$FEATURE_NAME" \
+  --arg log "$LOG_CONTENT" \
+  --arg input "$FRONTMATTER" \
+  --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  '{
+    feature_name: $feature,
+    saved_at: $ts,
+    sprint_log: $log,
+    sprint_input_frontmatter: $input
+  }' > "$RECOVERY_FILE"
+
+exit 0

package/templates/.claude/hooks/sprint-session-recovery.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# SessionStart(compact) hook: Reinject Sprint state after compaction
+# Compaction 후 Sprint 상태를 additionalContext로 복원
+
+INPUT=$(cat)
+CWD=$(echo "$INPUT" | jq -r '.cwd')
+RECOVERY_FILE="$CWD/.claude/sprint-recovery.json"
+
+if [ ! -f "$RECOVERY_FILE" ]; then
+  exit 0  # No recovery data
+fi
+
+FEATURE=$(jq -r '.feature_name' "$RECOVERY_FILE")
+SAVED_AT=$(jq -r '.saved_at' "$RECOVERY_FILE")
+SPRINT_LOG=$(jq -r '.sprint_log' "$RECOVERY_FILE")
+SPRINT_INPUT=$(jq -r '.sprint_input_frontmatter' "$RECOVERY_FILE")
+
+CONTEXT="[Sprint Recovery — saved at ${SAVED_AT}]
+Active Sprint: ${FEATURE}
+
+Sprint Input (frontmatter):
+${SPRINT_INPUT}
+
+Sprint Log:
+${SPRINT_LOG}"
+
+jq -n --arg ctx "$CONTEXT" '{
+  hookSpecificOutput: {
+    hookEventName: "SessionStart",
+    additionalContext: $ctx
+  }
+}'
+exit 0

package/templates/.claude/rules/bmad-mcp-search.md

@@ -0,0 +1,97 @@
+# MCP Search Protocol
+
+## Project MCP Server Configuration
+
+This project can reference existing service backend, client, and design data through MCP servers.
+
+### MCP Server Setup
+
+Create a `.mcp.json` file at the project root to configure MCP servers. See `.mcp.json.example` for reference.
+
+MCP server roles used in Sprint:
+
+| Role              | Purpose                                                     | Agent Reference Name |
+| ----------------- | ----------------------------------------------------------- | -------------------- |
+| **backend-docs**  | Backend domain policies, API specs, business logic          | `backend-docs MCP`   |
+| **client-docs**   | Client UI/UX, screen flows, component structure             | `client-docs MCP`    |
+| **svc-map**       | Brownfield service map: customer journeys, screenshots, flow data | `svc-map MCP`  |
+| **figma**         | Figma live design data: wireframes, components, design tokens | `figma MCP`        |
+
+> - The `figma` MCP server uses OAuth authentication. Add via `claude mcp add --transport http figma https://mcp.figma.com/mcp`, then authenticate at `/mcp`.
+> - When `svc-map` and `figma` data conflict, prefer `figma` (more recent).
+
+### Search Strategy
+
+When answering domain-related questions, **always search from multiple perspectives and provide an integrated answer**.
+
+#### Search Order
+
+1. **Classify question**: Determine if it concerns client / backend / design / multiple areas
+2. **Multi-search**: Search relevant MCP servers in parallel when possible
+3. **Integrated answer**: Distinguish backend, client, and design perspectives in the response
+
+#### Search Criteria by Perspective
+
+| Keywords/Topics                                            | Search Target                         |
+| ---------------------------------------------------------- | ------------------------------------- |
+| API, endpoints, data models, business logic, auth, permissions | backend-docs MCP                   |
+| UI code, component implementation, state management, code structure | client-docs MCP                |
+| Customer journeys, screen flows, service maps, screenshots | svc-map MCP                           |
+| Wireframes, design mockups, layouts, design tokens, styles | figma MCP                             |
+| Full feature, domain policies, service flows               | **backend + client + svc-map + Figma** |
+
+### Response Format
+
+Use the following format when answering domain-related questions:
+
+```
+## [Topic]
+
+### Backend Perspective
+- API endpoints: ...
+- Business logic: ...
+- Data models: ...
+
+### Client Perspective
+- Screen flows: ...
+- State management: ...
+- UI components: ...
+
+### Design Perspective
+- Wireframes/mockups: ...
+- Design tokens: ...
+- Component specs: ...
+
+### Integrated Summary
+[Explain how backend, client, and design connect]
+```
+
+## Local Codebase Search Protocol
+
+In co-located topologies (monolith, MSA, monorepo), the local codebase can be searched directly.
+
+### Local Search Tool Mapping
+
+| MCP Action     | Local Equivalent | Purpose                            |
+|----------------|------------------|------------------------------------|
+| MCP index read | **Glob**         | Directory structure, file patterns |
+| MCP search     | **Grep**         | Code keyword and pattern search    |
+| MCP file read  | **Read**         | Full file content reading          |
+
+### Search Priority (co-located)
+
+When the same information is found in multiple sources within a co-located topology:
+
+1. **Local codebase** (most accurate — actual code)
+2. **document-project artifacts** (structured documentation)
+3. **MCP servers** (external reference)
+
+### Excluded Paths
+
+Always exclude the following paths from local searches:
+
+```
+node_modules/    .git/         dist/        build/
+vendor/          target/       __pycache__/  coverage/
+.next/           .nuxt/        out/          .cache/
+```