devflow-kit 1.8.2 → 2.0.0

package/src/assets/commands/plan.mds

@@ -0,0 +1,523 @@
+---
+description: Unified design planning - combines requirements discovery, gap analysis, implementation planning, and design review into a single workflow
+output-dir: dist/commands
+---
+@import { knowledge_load } from "./_partials/_knowledge.mds"
+@import { decisions_load } from "./_partials/_decisions.mds"
+@import { compliance_gate } from "./_partials/_compliance.mds"
+
+# Plan Command
+
+Orchestrate design planning from requirements discovery through gap analysis to implementation design. Produces a machine-readable design artifact consumed by `/implement`.
+
+The orchestrator only spawns agents and gates — all analytical work is done by agents.
+
+## Usage
+
+```
+/plan <feature description>
+/plan #42                    (GitHub issue)
+/plan #12 #15 #18           (multi-issue)
+/plan                        (use conversation context)
+```
+
+## Input
+
+`$ARGUMENTS` contains whatever follows `/plan`:
+- Starts with `#` followed by numbers → issue mode (parse all `#N` tokens, space-separated)
+- Path to existing `.md` file → **error**: "Use /implement with plan documents"
+- Other text → feature description
+- Empty → use conversation context
+
+For **multi-issue** mode: collect all `#N` tokens from `$ARGUMENTS` as `ISSUE_NUMBERS`.
+
+## Clarification Gates
+
+**MANDATORY**: Three gates that must complete before proceeding.
+
+| Gate | Phase | Purpose |
+|------|-------|---------|
+| Gate 0 | Phase 1 | Requirements discovery before exploration |
+| Gate 1 | Phase 7 | Validate scope + gap analysis results |
+| Gate 2 | Phase 13 | Confirm final plan + design review |
+
+No gate may be skipped. If user says "proceed" or "whatever you think", state recommendation and get explicit confirmation.
+
+## Phases
+
+---
+
+### Block 1: Requirements Discovery
+
+#### Phase 1: Gate 0 — Requirements Discovery
+
+**Produces:** CONFIRMED_SCOPE
+
+Explore the user's intent through focused Socratic questioning before spawning agents.
+
+**Skip discovery when** (semantic assessment, not word count):
+- User has specified WHAT to build, HOW it should behave, and WHERE it integrates
+- User input references an existing design document or detailed issue
+
+**Process:**
+
+1. **First question**: Confirm your understanding of the core problem and expected outcome. Frame as multiple choice when 2-3 interpretations exist.
+2. **Follow-up questions** (if ambiguity remains): Probe constraints, scope boundaries, or tradeoffs via AskUserQuestion.
+3. **Present approaches**: When multiple valid approaches exist, present 2-3 options with explicit tradeoffs. Lead with your recommendation and why.
+4. **Confirm scope**: Summarize understanding including: core problem, target users, expected outcome, key assumptions, chosen approach (if applicable).
+
+For multi-issue: present unified scope across all issues after individual discovery.
+
+If the user says "skip" or "just proceed" — skip remaining questions, present inferred understanding (core problem, users, outcome, assumptions, recommended approach) in one message for confirmation, then proceed. Gate 0 is satisfied by the confirmation, not by the discovery questions.
+
+**MANDATORY**: Do not spawn any agents until Gate 0 is confirmed.
+
+#### Phase 2: Orient + Load Decisions
+
+**Produces:** SKIM_CONTEXT, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+**Requires:** CONFIRMED_SCOPE
+
+**Load Companion Skills** — Load via Skill tool: `devflow:test-driven-development`, `devflow:patterns`, `devflow:software-design`, `devflow:security`, `devflow:design-review`. If a skill fails to load, continue without it.
+
+Spawn Skim agent for codebase context:
+
+```
+Agent(subagent_type="Skim"):
+"Orient in codebase for design planning: {feature/issues}
+Run rskim on source directories (NOT repo root) to identify:
+- Existing patterns and conventions in the affected area
+- File structure and module boundaries
+- Similar prior implementations
+- Test patterns and coverage approach
+Return codebase context for requirements analysis."
+```
+
+{decisions_load()}
+
+This produces a compact index of active ADR/PF entries. Pass Skim agent context and `DECISIONS_CONTEXT` to all subsequent agents — prior decisions constrain design, known pitfalls inform gap analysis. Agents use `devflow:apply-decisions` to Read full entry bodies on demand.
+
+{knowledge_load()}
+
+Pass `FEATURE_KNOWLEDGE` alongside `DECISIONS_CONTEXT` to Explore and Design agents.
+
+#### Phase 3: Explore Requirements (Parallel)
+
+**Produces:** EXPLORE_OUTPUTS
+**Requires:** SKIM_CONTEXT, DECISIONS_CONTEXT
+
+Spawn 4 Explore agents **in a single message**, each with Skim agent context, `DECISIONS_CONTEXT` (from Phase 2), and `FEATURE_KNOWLEDGE` (from Phase 2). Include instructions: "follow `devflow:apply-decisions` for DECISIONS_CONTEXT" and "The FEATURE_KNOWLEDGE is a baseline — VALIDATE, EXTEND, and CORRECT it, don't repeat it. Focus on areas the feature knowledge doesn't cover and changes since it was last updated."
+
+| Focus | Thoroughness | Find |
+|-------|-------------|------|
+| User perspective | medium | Target users, goals, pain points, user journeys |
+| Similar features | medium | Comparable features, scope patterns, edge cases |
+| Constraints | quick | Dependencies, business rules, prior architectural decisions |
+| Failure modes | quick | Error states, edge cases, known pitfalls |
+
+#### Phase 4: Synthesize Exploration
+
+**Produces:** EXPLORATION_SYNTHESIS
+**Requires:** EXPLORE_OUTPUTS
+
+**WAIT** for Phase 3 to complete.
+
+```
+Agent(subagent_type="Synthesize"):
+"Synthesize EXPLORATION outputs for: {feature/issues}
+Mode: exploration
+Explore outputs: {all 4 outputs}
+Combine into: user needs, similar features, constraints, failure modes"
+```
+
+---
+
+### Block 2: Gap Analysis
+
+#### Phase 5: Gap Analysis (Parallel)
+
+**Produces:** GAP_OUTPUTS, COMPLIANCE_SKILL_INSTALLED
+**Requires:** EXPLORATION_SYNTHESIS, SKIM_CONTEXT, DECISIONS_CONTEXT
+
+{compliance_gate()}
+
+**Single-issue**: Spawn 4 Design agents **in a single message** (**5 when COMPLIANCE_SKILL_INSTALLED**):
+
+| Focus | What it checks |
+|-------|----------------|
+| completeness | Missing AC, undefined error states, vague requirements |
+| architecture | Pattern violations, missing integration points, layering issues |
+| security | Auth gaps, input validation, secret handling, OWASP |
+| performance | N+1 patterns, missing caching, concurrency, query patterns |
+| compliance | Regulatory gaps security doesn't cover: retention/erasure, audit-trail completeness, segregation of duties, IaC exposure (only when COMPLIANCE_SKILL_INSTALLED) |
+
+**Multi-issue**: Spawn 6 Design agents **in a single message** (**7 when COMPLIANCE_SKILL_INSTALLED**; same 4/5 plus):
+
+| Focus | What it checks |
+|-------|----------------|
+| consistency | Cross-issue contradictions, duplicate requirements, conflicting scope |
+| dependencies | Inter-issue ordering, shared resources, breaking change propagation |
+
+Each Design agent receives:
+- Mode: `gap-analysis`
+- Focus: (their assigned focus from table)
+- Exploration synthesis from Phase 4
+- Skim agent context from Phase 2
+- `DECISIONS_CONTEXT` (index from Phase 2)
+- Multi-issue: all issue bodies
+
+```
+Agent(subagent_type="Design"):
+"Mode: gap-analysis
+Focus: {completeness|architecture|security|performance|compliance|consistency|dependencies}
+DECISIONS_CONTEXT: {decisions_context}
+FEATURE_KNOWLEDGE: {feature_knowledge}
+Artifacts:
+  Feature/Issues: {feature description or issue bodies}
+  Exploration synthesis: {Phase 4 output}
+  Codebase context: {Phase 2 output}
+Analyze only your assigned focus area. Follow devflow:apply-decisions for DECISIONS_CONTEXT.
+Cite evidence from provided artifacts."
+```
+
+#### Phase 6: Synthesize Gap Analysis
+
+**Produces:** GAP_SYNTHESIS
+**Requires:** GAP_OUTPUTS
+
+**WAIT** for Phase 5 to complete.
+
+```
+Agent(subagent_type="Synthesize"):
+"Synthesize GAP ANALYSIS outputs for: {feature/issues}
+Mode: design
+Design agent outputs: {all Design agent outputs}
+Deduplicate, boost confidence for multi-agent flags, categorize by severity."
+```
+
+---
+
+### Block 3: Scope Approval
+
+#### Phase 7: Gate 1 — Validate Scope + Gaps
+
+**Produces:** ACCEPTED_SCOPE, ACCEPTED_GAPS
+**Requires:** GAP_SYNTHESIS, EXPLORATION_SYNTHESIS
+
+Use AskUserQuestion to present and validate:
+
+1. **Scope Summary**
+   - Core problem
+   - Priority level (Critical/High/Medium/Low)
+   - v1 scope (what's included)
+   - Explicit exclusions
+
+2. **Gap Analysis Results** (from Phase 6)
+   - Blocking gaps (CRITICAL/HIGH) with proposed resolutions
+   - Should-address recommendations (MEDIUM)
+   - Informational items (LOW)
+
+User can:
+- Accept scope and gaps as presented
+- Modify scope (add/remove items)
+- Override specific gaps (accept risk and proceed)
+
+**MANDATORY**: Do not proceed to implementation design until Gate 1 is confirmed.
+
+---
+
+### Block 4: Implementation Design
+
+#### Phase 8: Explore Implementation (Parallel)
+
+**Produces:** IMPL_EXPLORE_OUTPUTS
+**Requires:** SKIM_CONTEXT, ACCEPTED_SCOPE
+
+Spawn 4 Explore agents **in a single message**, each with Skim agent context + accepted scope:
+
+| Focus | Thoroughness | Find |
+|-------|-------------|------|
+| Architecture | medium | Similar implementations, patterns, module structure |
+| Integration | medium | Entry points, services, database models, configuration |
+| Reusable code | medium | Utilities, helpers, validation patterns, error handling |
+| Edge cases | quick | Error scenarios, race conditions, permission failures |
+
+#### Phase 9: Synthesize Implementation Exploration
+
+**Produces:** IMPL_EXPLORATION_SYNTHESIS
+**Requires:** IMPL_EXPLORE_OUTPUTS
+
+**WAIT** for Phase 8 to complete.
+
+```
+Agent(subagent_type="Synthesize"):
+"Synthesize IMPLEMENTATION EXPLORATION outputs for: {feature/issues}
+Mode: exploration
+Explore outputs: {all 4 outputs}
+Combine into: patterns to follow, integration points, reusable code, edge cases"
+```
+
+#### Phase 10: Plan Implementation (Parallel)
+
+**Produces:** PLAN_OUTPUTS
+**Requires:** IMPL_EXPLORATION_SYNTHESIS, GAP_SYNTHESIS, DECISIONS_CONTEXT
+
+Spawn 3 Plan agents **in a single message**, each with implementation exploration synthesis:
+
+| Focus | Output |
+|-------|--------|
+| Implementation steps | Ordered steps with files, dependencies, gap mitigations |
+| Testing strategy | Unit tests, integration tests, edge case tests |
+| Execution strategy | SINGLE_CODE_AGENT vs SEQUENTIAL_CODE_AGENTS vs PARALLEL_CODE_AGENTS |
+
+Implementation steps planner: include explicit gap mitigations (from Phase 6) in the relevant steps.
+
+#### Phase 11: Synthesize Planning
+
+**Produces:** PLANNING_SYNTHESIS
+**Requires:** PLAN_OUTPUTS
+
+**WAIT** for Phase 10 to complete.
+
+```
+Agent(subagent_type="Synthesize"):
+"Synthesize PLANNING outputs for: {feature/issues}
+Mode: planning
+Planner outputs: {all 3 outputs}
+Combine into: execution plan with strategy decision, gap mitigations integrated"
+```
+
+---
+
+### Block 5: Design Review + Approval
+
+#### Phase 12: Design Review
+
+**Produces:** REVIEW_FINDINGS
+**Requires:** PLANNING_SYNTHESIS
+
+Spawn 1 Design agent with mode `design-review`:
+
+```
+Agent(subagent_type="Design"):
+"Mode: design-review
+Artifacts:
+  Implementation plan: {Phase 11 planning synthesis}
+  Implementation exploration: {Phase 9 exploration synthesis}
+  Codebase context: {Phase 2 output}
+Review the full plan for all 6 anti-patterns. Report all findings with evidence."
+```
+
+#### Phase 13: Gate 2 — Confirm Plan + Design Review
+
+**Produces:** APPROVED_PLAN
+**Requires:** PLANNING_SYNTHESIS, REVIEW_FINDINGS, GAP_SYNTHESIS
+
+Use AskUserQuestion to present:
+
+1. **Implementation Plan Summary**
+   - Execution strategy (SINGLE_CODE_AGENT / SEQUENTIAL_CODE_AGENTS / PARALLEL_CODE_AGENTS)
+   - Key implementation steps with files
+   - Test strategy
+
+2. **Design Review Findings** (from Phase 12)
+   - Each anti-pattern finding with severity and proposed mitigation
+   - Which findings are already addressed in the plan
+
+3. **Acceptance Criteria** (from gap analysis + exploration)
+
+4. **Risk Assessment**
+   - Context risk level (LOW/MEDIUM/HIGH/CRITICAL)
+   - Unresolved gaps carried forward
+
+User can:
+- **Accept** — proceed to output phases
+- **Revise** — re-run phases 10-12 with new constraints (loop back, no limit on revisions)
+- **Cancel** — stop gracefully, no artifact written
+
+**MANDATORY**: Do not write design artifact until Gate 2 is confirmed.
+
+---
+
+### Block 6: Output
+
+#### Phase 14: Output
+
+**Requires:** APPROVED_PLAN
+
+**Store design artifact:**
+
+Write design artifact to disk:
+- If issue number: `.devflow/docs/design/\{issue-number\}-\{topic-slug\}.\{YYYY-MM-DD_HHMM\}.md`
+- If multi-issue: `.devflow/docs/design/\{first-issue-number\}-multi.\{YYYY-MM-DD_HHMM\}.md`
+- If no issue: `.devflow/docs/design/\{topic-slug\}.\{YYYY-MM-DD_HHMM\}.md`
+
+Create parent directory if needed.
+
+**Artifact format:**
+
+```yaml
+---
+type: design-artifact
+version: 1
+status: APPROVED
+issue: 42
+title: "Feature Title"
+slug: feature-slug
+created: 2026-04-07T14:30:00Z
+execution-strategy: SINGLE_CODE_AGENT
+context-risk: LOW
+---
+```
+
+Required sections:
+1. **Problem Statement** — core problem and target users
+2. **Acceptance Criteria** — testable success conditions (from exploration + gap analysis)
+3. **Scope** — v1 included, deferred, excluded
+4. **Gap Analysis Results** — blocking gaps with resolutions, should-address items
+5. **Execution Strategy** — SINGLE_CODE_AGENT/SEQUENTIAL/PARALLEL with rationale
+6. **Subtask Breakdown** — phases with domains and dependencies (if not SINGLE_CODE_AGENT)
+7. **Implementation Plan** — ordered steps with files and gap mitigations
+8. **Patterns to Follow** — from exploration synthesis (file:line references)
+9. **Integration Points** — entry points, services, models to connect
+10. **Design Review Results** — anti-pattern findings with mitigations
+11. **Risk Assessment** — context risk level, unresolved risks
+12. **PR Description Guidance** — problem being solved, key changes, breaking changes, Reviewer Focus Areas
+
+### 12. PR Description Guidance
+
+```markdown
+## PR Description Guidance
+
+### Problem Being Solved
+{1-2 sentences: the "why" behind this change}
+
+### Key Changes to Highlight
+{bulleted list: user-facing framing of what changed}
+
+### Breaking Changes
+{from gap analysis, or "None expected"}
+
+### Reviewer Focus Areas
+{areas needing careful review, with reasons}
+
+### Related Issues
+Closes #{issue number}
+```
+
+**Create or enrich GitHub issue:**
+
+When `COMPLIANCE_SKILL_INSTALLED` is true, issue linking is MANDATORY (DEGRADED states are exempt with a warning in the final summary) — proceed to the spawn below.
+
+When `COMPLIANCE_SKILL_INSTALLED` is false, issue linking is optional. Prompt the user first via AskUserQuestion: "Create or enrich a GitHub issue for this plan?" — skip the spawn entirely if the user declines.
+
+Spawn a Git agent with `OPERATION: ensure-traceable-issue`:
+
+```
+Agent(subagent_type="Git"):
+"OPERATION: ensure-traceable-issue
+ISSUE_INPUT: {issue_number_from_arguments if /plan invoked with #N, else omit}
+TASK_DESCRIPTION: {Gate 0 confirmed scope — one-line title}
+INITIAL_REQUEST: {the Gate 0 confirmed scope statement}
+REQUIREMENTS: {discovered requirements summary from Phase 6 gap synthesis}
+PLAN_ARTIFACT_PATH: {the design artifact path written above}
+LABELS: feature
+The Git agent will create a GitHub issue (or enrich an existing one) using the D3 template,
+post the design artifact as a collapsed details comment, and link it from the Implementation Plan section.
+Return the issue number."
+```
+
+Capture `ISSUE_NUMBER` from the Git agent output for use in the completion report and the `/implement` hand-off suggestion.
+
+Surface any `TRACEABILITY: DEGRADED (\{reason\})` lines from the Git agent output in the report.
+
+**Report:**
+
+Display completion summary:
+- Design artifact path
+- Issue URL (if created or enriched) — and any `TRACEABILITY: DEGRADED (\{reason\})` lines from the Git agent
+- Gap analysis summary (N blocking, M should-address)
+- Design review summary (N anti-patterns found, M mitigated in plan)
+- Suggested next step: `/implement \{artifact-path\}` or `/implement #\{issue-number\}`
+
+---
+
+## Architecture
+
+```
+/plan (orchestrator - spawns agents only)
+│
+├─ Block 1: Requirements Discovery
+│  ├─ Phase 1: GATE 0 - Requirements Discovery ⛔ MANDATORY
+│  │  └─ AskUserQuestion: Validate interpretation
+│  ├─ Phase 2: Orient + Load Decisions
+│  │  ├─ Skim agent (codebase context)
+│  │  └─ Read index.md → DECISIONS_CONTEXT
+│  ├─ Phase 3: Explore Requirements (PARALLEL)
+│  │  ├─ Explore: User perspective
+│  │  ├─ Explore: Similar features
+│  │  ├─ Explore: Constraints
+│  │  └─ Explore: Failure modes
+│  └─ Phase 4: Synthesize Exploration
+│     └─ Synthesize agent (mode: exploration)
+│
+├─ Block 2: Gap Analysis
+│  ├─ Phase 5: Gap Analysis (PARALLEL)
+│  │  ├─ Design agent: completeness
+│  │  ├─ Design agent: architecture
+│  │  ├─ Design agent: security
+│  │  ├─ Design agent: performance
+│  │  ├─ Design agent: compliance (only when COMPLIANCE_SKILL_INSTALLED)
+│  │  ├─ Design agent: consistency (multi-issue only)
+│  │  └─ Design agent: dependencies (multi-issue only)
+│  └─ Phase 6: Synthesize Gap Analysis
+│     └─ Synthesize agent (mode: design)
+│
+├─ Block 3: Scope Approval
+│  └─ Phase 7: GATE 1 - Validate Scope + Gaps ⛔ MANDATORY
+│     └─ AskUserQuestion: Confirm scope and gap resolutions
+│
+├─ Block 4: Implementation Design
+│  ├─ Phase 8: Explore Implementation (PARALLEL)
+│  │  ├─ Explore: Architecture
+│  │  ├─ Explore: Integration
+│  │  ├─ Explore: Reusable code
+│  │  └─ Explore: Edge cases
+│  ├─ Phase 9: Synthesize Implementation Exploration
+│  │  └─ Synthesize agent (mode: exploration)
+│  ├─ Phase 10: Plan Implementation (PARALLEL)
+│  │  ├─ Plan: Implementation steps
+│  │  ├─ Plan: Testing strategy
+│  │  └─ Plan: Execution strategy
+│  └─ Phase 11: Synthesize Planning
+│     └─ Synthesize agent (mode: planning)
+│
+├─ Block 5: Design Review + Approval
+│  ├─ Phase 12: Design Review
+│  │  └─ Design agent (mode: design-review)
+│  └─ Phase 13: GATE 2 - Confirm Plan + Design Review ⛔ MANDATORY
+│     └─ AskUserQuestion: Final plan approval
+│
+├─ Block 6: Output
+│  └─ Phase 14: Output
+│     ├─ Store design artifact (.devflow/docs/design/)
+│     ├─ Create GitHub issue (optional)
+│     └─ Report summary + next step
+│
+```
+
+## Principles
+
+1. **Orchestration only** — Command spawns agents, never does agent work itself
+2. **Three mandatory gates** — Gate 0 (understand), Gate 1 (scope+gaps), Gate 2 (plan+review); none may be skipped
+3. **Parallel execution** — Explore phases and gap analysis run in parallel; synthesis phases wait
+4. **Evidence-based gaps** — Every gap cites specific text; no speculation
+5. **Scope ruthlessly** — Small, focused plans ship faster; gate 1 enforces scope discipline
+6. **Strict delegation** — Never synthesize, analyze, or plan in main session; always spawn agents
+7. **Design artifacts are machine-readable** — `/implement` can consume the YAML frontmatter directly
+
+## Error Handling
+
+- If any agent fails, report the phase, agent type, and error
+- If user selects "Revise" at Gate 2, loop back to Phase 10 with user's constraints
+- If user selects "Cancel" at any gate, stop gracefully without writing artifact
+- If `.devflow/docs/design/` does not exist, create it in Phase 14