pm-discovery: Opportunity Solution Tree (Teresa Torres)
pm-strategy: Value Proposition (JTBD 6-Part) + Lean Canvas
pm-research: 3 Personas + 5 Competitors + TAM/SAM/SOM
pm-lead runs Phase 3: PRD Synthesis via pm-prd agent
Beachhead Segment (Geoffrey Moore) + GTM Strategy
8-section PRD generation
Output PRD to docs/00-pm/{feature}.prd.md
Create Task: [PM] {feature}
Update .bkit/state/pdca-status.json: phase = "pm"
Guide user to next step: /pdca plan {feature}
Output Path: docs/00-pm/{feature}.prd.md
Requirements:
Agent Teams enabled: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
Project level: Dynamic or Enterprise (Starter not supported)
plan (Plan Phase)
Template Loading: Read templates/plan.template.md to understand the required Plan document structure and sections. Use this template's sections as your document outline. This is MANDATORY — do not generate Plan documents from memory or assumptions.
PRD Auto-Reference: Check if docs/00-pm/{feature}.prd.md exists
If found: Read PRD and use as context for Plan document (improves quality significantly)
If not found: Proceed normally (tip: run /pdca pm {feature} first for better results)
Check if docs/01-plan/features/{feature}.plan.md exists
If not, create based on plan.template.md
If exists, display content and suggest modifications
Checkpoint 1 — Requirements Confirmation: Present understanding of the feature (problem, scope, constraints) and use AskUserQuestion: "요구사항 이해가 맞나요? 빠진 건 없나요?" Wait for user confirmation before proceeding.
Checkpoint 2 — Clarifying Questions: Identify underspecified elements (edge cases, error handling, integration points, compatibility). Present organized question list. Wait for answers before generating the document.
Generate Plan document with user-confirmed requirements
Complete predecessor Task first: If a [PM] {feature} Task exists and is still in_progress, use TaskList to find it and TaskUpdate it to status: "completed" before creating the Plan Task (see Phase Transition Rule). Then Create Task: [Plan] {feature}
Write ## Executive Summary at document top with 4-perspective table (Problem/Solution/Function UX Effect/Core Value), each 1-2 sentences
Context Anchor Generation: After generating Plan document, extract Context Anchor (WHY/WHO/RISK/SUCCESS/SCOPE) from Executive Summary, Requirements, and Risk sections. Write as ## Context Anchor table between Executive Summary and Section 1. This anchor propagates to Design/Do documents for cross-session context continuity.
MANDATORY: After completing the document, also output the Executive Summary table in your response so the user sees it immediately without opening the file
Tip: For features with ambiguous requirements or multiple implementation approaches,
use /plan-plus {feature} instead. Plan Plus adds brainstorming phases (intent discovery,
alternatives exploration, YAGNI review) before document generation for higher-quality plans.
design (Design Phase)
Template Loading: Read templates/design.template.md to understand the required Design document structure. Use this template's sections as your document outline. This is MANDATORY — do not generate Design documents from memory or assumptions.
Verify Plan document exists (required - suggest running plan first if missing)
Read Plan document to understand requirements and scope
PRD Context Loading: Check if docs/00-pm/{feature}.prd.md exists. If found, read the Executive Summary and Beachhead/GTM sections to inform architecture decisions with market context. This prevents strategic context loss at the Plan→Design handoff.
Context Anchor Embed: Copy Plan's ## Context Anchor table to Design document top (between header metadata and ## 1. Overview). If Plan has no Context Anchor (legacy), skip this step gracefully.
Generate 3 Architecture Options (inspired by feature-dev Phase 4):
Option A — Minimal Changes: Least modification, maximum reuse of existing code. Fast but potentially coupled.
Option B — Clean Architecture: Best separation of concerns, most maintainable. More files, more refactoring.
Option C — Pragmatic Balance: Good boundaries without over-engineering. Recommended default.
Present comparison table with trade-offs (complexity, maintainability, effort, risk)
Checkpoint 3 — Architecture Selection: Use AskUserQuestion: "3가지 설계안 중 어떤 걸 선택하시겠습니까?" Include recommendation. Wait for user selection.
Create docs/02-design/features/{feature}.design.md using selected architecture
Use design.template.md structure + reference Plan content
Session Guide Generation: Analyze Design's ## 11. Implementation Guide structure to generate Module Map and Recommended Session Plan. Add as ### 11.3 Session Guide within Implementation Guide section. This enables /pdca do {feature} --scope module-N for multi-session incremental implementation.
Design Anchor Integration (Pencil MCP): If the feature involves UI and Pencil MCP is available:
Suggest: "UI 컨셉 페이지를 1-2개 먼저 만든 후 /design-anchor capture {feature} 로 디자인 토큰을 잠그세요"
If Design Anchor already exists (docs/02-design/styles/{feature}.design-anchor.md), embed it in the Design document as ## Design Anchor section
This ensures design tokens (colors, typography, spacing) are locked before implementation
Complete predecessor Task first: Use TaskList to find the [Plan] {feature} Task (and any earlier phase Task for this feature still in_progress) and TaskUpdate each to status: "completed" — this resolves the blockedBy chain and prevents stale phase status from leaking into prompt context (see Phase Transition Rule). Then Create Task: [Design] {feature} (blockedBy: Plan task)
Read Design document FULLY (read the entire document, not just a summary. This is critical — full context reload ensures each session starts with complete architectural context)
Full Upstream Context Loading (Phase 2+3): Load the COMPLETE upstream document chain:
Success Criteria Tracking: Extract Success Criteria from Plan document. Display as implementation checklist — each criterion must be addressed during implementation. Mark criteria that are covered by the current --scope.
Parse --scope parameter: If arguments contain --scope <value>, extract module list (comma-separated scope keys). Match against Design's Session Guide Module Map. Filter implementation items to show only matching modules.
Display Context Anchor: Show the Context Anchor table from Design document header. Format: "📌 Context Anchor" + WHY/WHO/RISK/SUCCESS/SCOPE table. This reminds the user WHY we're building this feature.
Session Guide Display:
If no --scope: Show full Module Map from Design + recommend session split + proceed with full implementation guide
If --scope provided: Show only the selected modules' implementation items
Summarize implementation scope:
Files to create: N
Files to modify: M
Estimated changes: ~X lines
Checkpoint 4 — Implementation Approval: Present scope summary and use AskUserQuestion: "이 범위로 구현을 시작해도 되겠습니까?" DO NOT START IMPLEMENTATION WITHOUT USER APPROVAL.
After approval, provide implementation guide based on do.template.md
Reference implementation order from Design document (filtered by --scope if provided)
Code Comment Convention (Phase 3): During implementation, add Design reference comments for key architectural decisions:
At module/file level: // Design Ref: §{section} — {decision rationale}
At critical logic: // Plan SC: {success criteria being addressed}
These comments create traceable links from code back to design decisions
Complete predecessor Task first: Use TaskList to find the [Design] {feature} Task (and any earlier phase Task for this feature still in_progress) and TaskUpdate each to status: "completed" — this resolves the blockedBy chain and prevents stale phase status from leaking into prompt context (see Phase Transition Rule). Then Create Task: [Do] {feature} (blockedBy: Design task)
Update .bkit/state/pdca-status.json: phase = "do"
--scope Parameter:
/pdca do feature # Full scope (backward compatible) + session guide
/pdca do feature --scope module-1 # Only module-1
/pdca do feature --scope module-1,module-2 # Multiple modules
Guide Provided:
Context Anchor (WHY/WHO/RISK/SUCCESS/SCOPE)
Session scope (filtered or full)
Implementation order checklist
Key files/components list
Dependency installation commands
analyze (Check Phase)
Verify Do completion status (implementation code exists)
Full Upstream Context Loading (Phase 2+3): Load the COMPLETE upstream document chain for comprehensive evaluation:
Read PRD (docs/00-pm/{feature}.prd.md) — verify strategic alignment (was the right problem solved?)
Read Plan (docs/01-plan/features/{feature}.plan.md) — verify Requirements fulfillment + Success Criteria
Read Design (docs/02-design/features/{feature}.design.md) — verify structural implementation match
This 3-layer verification catches gaps that single-document comparison misses
Context Anchor Embed: Copy Context Anchor from Design to Analysis document header.
Strategic Alignment Check (Phase 3): Before structural gap analysis, verify:
Does the implementation address the PRD's core problem (WHY)?
Are Plan Success Criteria met or on track?
Were key Design decisions (architecture, data model, API) followed?
Flag strategic misalignments as Critical regardless of structural match rate
Plan Success Criteria Reference: Evaluate each Success Criteria from Plan:
Mark as ✅ Met / ⚠️ Partial / ❌ Not Met
Include evidence (file:line or test result)
Criteria violations are automatically Critical severity
If no server running: skip L1, warn user, use static-only formula
L2 — UI Action Tests (run if Playwright is installed):
Generate Playwright test file from gap-detector's L2 plan
Write to tests/e2e/{feature}-actions.spec.ts
Run: npx playwright test tests/e2e/{feature}-actions.spec.ts
Each test: navigate to page → perform action → assert result
Check: API calls triggered by UI match expected endpoints
If Playwright not installed: skip L2, suggest pnpm add -D @playwright/test
L3 — E2E Scenario Tests (run if Playwright is installed):
Generate Playwright test file from gap-detector's L3 plan
Write to tests/e2e/{feature}-e2e.spec.ts
Run: npx playwright test tests/e2e/{feature}-e2e.spec.ts
Full user journey: multi-page flows with state persistence
Check: complete flow from start to end without errors
Match Rate Formula (v2.3.0):
If runtime executed:
Overall = (Structural × 0.15) + (Functional × 0.25)
+ (Contract × 0.25) + (Runtime × 0.35)
If static only (no server):
Overall = (Structural × 0.2) + (Functional × 0.4) + (Contract × 0.4)
Calculate Match Rate and generate Gap list. Report all rates separately.
Decision Record Verification (Phase 3): Check if key decisions from Decision Record Chain were followed in implementation. Flag deviations.
Checkpoint 5 — Review Decision: Present issues by severity (Critical/Important only, confidence ≥80%). Use AskUserQuestion with options:
"지금 모두 수정" — proceed to iterate
"Critical만 수정" — iterate critical only
"그대로 진행" — accept current state
Wait for user decision before proceeding.
Complete predecessor Task first: Use TaskList to find the [Do] {feature} Task (and any earlier phase Task for this feature still in_progress) and TaskUpdate each to status: "completed" — this resolves the blockedBy chain and prevents stale phase status from leaking into prompt context (see Phase Transition Rule). Then Create Task: [Check] {feature} (blockedBy: Do task)
Optional L4 (perf) / L5 (security) for Enterprise level
Emit one of:
QA_PASS → auto-advance to report phase
QA_FAIL → fall back to iterate phase
QA_SKIP → mark qa as skipped, proceed to report
Complete predecessor Task first: Use TaskList to find the [Check] {feature} Task and the latest [Act-N] {feature} Task (and any earlier phase Task for this feature still in_progress) and TaskUpdate each to status: "completed" (see Phase Transition Rule). Then Create Task: [QA] {feature}
Agent: bkit:qa-lead (mapped via frontmatter agents.qa)
iterate (Act Phase)
Check results (when matchRate < 90%)
Call pdca-iterator Agent
Auto-fix code based on Gap list
Auto re-run Check after fixes
Complete predecessor Task first: Use TaskList to find the [Check] {feature} Task and any prior [Act-*] {feature} Task for this feature still in_progress and TaskUpdate each to status: "completed" (see Phase Transition Rule). Then Create Task: [Act-N] {feature} (N = iteration count)
Stop when >= 90% reached or max iterations (5) hit
Iteration Rules:
Max iterations: 5 (adjustable via bkit.config.json)
Stop conditions: matchRate >= 90% or maxIterations reached
report (Completion Report)
Template Loading: Read templates/report.template.md to understand the required Report document structure. Use this template's sections as your document outline. This is MANDATORY — do not generate Report documents from memory or assumptions.
Verify Check >= 90% (warn if below)
Full Upstream Context Loading (Phase 2+3): Load ALL upstream documents for comprehensive reporting:
Read PRD — compare original value proposition vs delivered value
Read Plan — compare planned Requirements/Success Criteria vs actual results
Read Design — note architecture decisions and deviations
Read Analysis — include final Match Rate and resolved gaps
This ensures the report reflects the FULL journey from PRD→Code
Call report-generator Agent
Integrated report of PRD, Plan, Design, Implementation, Analysis
Decision Record Summary (Phase 3): Include section "Key Decisions & Outcomes":
List decisions from PRD→Plan→Design chain
For each: was it followed? what was the outcome?
This creates a learnable record for future PDCA cycles
Success Criteria Final Status: Include Plan Success Criteria with final status:
Each criterion: ✅ Met (with evidence) / ❌ Not Met (with reason)
Overall Success Rate: X/Y criteria met
Include ## Executive Summary with ### 1.3 Value Delivered reflecting actual results (4 perspectives with metrics)
MANDATORY: After completing the report, also output the Executive Summary table in your response
Complete predecessor Task first: Use TaskList to find the [QA] {feature} Task (or the [Check] {feature} / latest [Act-N] {feature} Task if QA was skipped) and any earlier phase Task for this feature still in_progress, and TaskUpdate each to status: "completed" (see Phase Transition Rule). Then Create Task: [Report] {feature}
Verify Report completion status (phase = "completed" or matchRate >= 90%)
Complete the terminal Task: Use TaskList to find the [Report] {feature} Task and any other [Phase] {feature} Task for this feature still in_progress, and TaskUpdate each to status: "completed" — the feature is terminal, so no phase Task should remain open (see Phase Transition Rule).
Update Archive Index (docs/archive/YYYY-MM/_INDEX.md)
Update .bkit/state/pdca-status.json: phase = "archived", record archivedTo path
Remove feature from status (or preserve summary with --summary option)
Arguments:
Argument
Description
Example
archive {feature}
Archive with complete cleanup (default)
/pdca archive user-auth
archive {feature} --summary
Archive with summary preservation (FR-04)
/pdca archive user-auth --summary
Output Path: docs/archive/YYYY-MM/{feature}/
Documents to Archive:
docs/01-plan/features/{feature}.plan.md
docs/02-design/features/{feature}.design.md
docs/03-analysis/{feature}.analysis.md
docs/04-report/features/{feature}.report.md
FR-04: Summary Preservation Option (v1.4.8):
When using --summary (or --preserve-summary, -s), the feature data in .bkit/state/pdca-status.json
is converted to a lightweight summary instead of being deleted:
// Summary format (70% size reduction){"my-feature":{"phase":"archived","matchRate":100,"iterationCount":2,"startedAt":"2026-01-15T10:00:00Z","archivedAt":"2026-01-20T15:30:00Z","archivedTo":"docs/archive/2026-01/my-feature/"}}
Use --summary when you need:
Historical statistics and metrics
Project duration tracking
PDCA efficiency analysis
Important Notes:
Cannot archive before Report completion
Documents are deleted from original location after move (irreversible)
Feature name must match exactly
Default behavior: complete deletion from status
Use --summary to preserve metrics for future reference
cleanup (Cleanup Phase) - v1.4.8
Clean up archived features from .bkit/state/pdca-status.json to reduce file size.
Read archived features from .bkit/state/pdca-status.json
Display list with timestamps and archive paths
Ask user for confirmation via AskUserQuestion (FR-06)
Delete selected features from status using cleanupArchivedFeatures()
Report cleanup results
Arguments:
Argument
Description
Example
cleanup
Interactive cleanup (shows list)
/pdca cleanup
cleanup all
Delete all archived features
/pdca cleanup all
cleanup {feature}
Delete specific feature
/pdca cleanup old-feature
Output Example:
🧹 PDCA Cleanup
─────────────────────────────
Archived features found: 3
1. feature-a (archived: 2026-01-15)
2. feature-b (archived: 2026-01-20)
3. feature-c (archived: 2026-01-25)
Select features to cleanup:
[ ] All archived features
[ ] Select specific features
[ ] Cancel
Related Functions (lib/pdca/status.js):
getArchivedFeatures() - Get list of archived features
cleanupArchivedFeatures(features?) - Cleanup specific or all archived
deleteFeatureFromStatus(feature) - Delete single feature
enforceFeatureLimit(max=50) - Auto cleanup when limit exceeded
Notes:
Only archived/completed features can be deleted
Active features are protected from deletion
Archive documents remain in docs/archive/ (only status is cleaned)
status (Status Check)
Read .bkit/state/pdca-status.json (the live state-of-truth; via the
lib/pdca/status-core.js API). Note: .bkit-memory.json is a deprecated
v1.6.0 legacy path that no lib module reads or writes.
The diagram above shows task creation. Advancing a phase also requires task completion:
Before creating a new phase's Task, mark every prior [Phase] {feature} Task for
this feature that is still in_progress as completed — use TaskList to find them
and TaskUpdate {status: "completed"} on each. The archive action likewise completes
the terminal [Report] Task.
Why this matters: a blockedBy chain is only semantically correct when the predecessor
is completed by the time the successor is created. More importantly, Claude Code surfaces
the native Task list into ambient prompt context every turn. If a predecessor Task is left
in_progress, that stale phase (e.g. "design" during a "do" phase) keeps leaking back to the
user — disagreeing with .bkit/state/pdca-status.json's phase field, which is the phase
source of truth. Completing predecessors keeps the two in sync. Each phase action above
embeds this step immediately before its Create-Task step.
Agent Integration
Action
Agent
Role
pm
pm-lead
Orchestrate PM Agent Team (4 sub-agents)
analyze
gap-detector
Compare Design vs Implementation
iterate
pdca-iterator
Auto code fix and re-verification
report
report-generator
Generate completion report
Usage Examples
# Run PM analysis (recommended before planning)
/pdca pm user-authentication
# Start new feature
/pdca plan user-authentication
# Create design document
/pdca design user-authentication
# Implementation guide
/pdca do user-authentication
# Gap analysis after implementation
/pdca analyze user-authentication
# Auto improvement (if needed)
/pdca iterate user-authentication
# Completion report
/pdca report user-authentication
# Check current status
/pdca status
# Guide to next phase
/pdca next
Legacy Commands Mapping
Legacy Command
PDCA Skill
/pdca-plan
/pdca plan
/pdca-design
/pdca design
/pdca-analyze
/pdca analyze
/pdca-iterate
/pdca iterate
/pdca-report
/pdca report
/pdca-status
/pdca status
/pdca-next
/pdca next
/archive
/pdca archive
Output Style Integration (v1.5.1)
PDCA workflows benefit from the bkit-pdca-guide output style:
