diff --git a/.claude/commands/workflow/execute.md b/.claude/skills/workflow-execute/SKILL.md similarity index 97% rename from .claude/commands/workflow/execute.md rename to .claude/skills/workflow-execute/SKILL.md index 6c57dd6b..cdeb4556 100644 --- a/.claude/commands/workflow/execute.md +++ b/.claude/skills/workflow-execute/SKILL.md @@ -1,12 +1,11 @@ --- -name: execute -description: Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking -argument-hint: "[-y|--yes] [--resume-session=\"session-id\"] [--with-commit]" +name: workflow-execute +description: Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking. Triggers on "workflow:execute". +allowed-tools: Skill, Task, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep --- -# Workflow Execute Command +# Workflow Execute -## Overview Orchestrates autonomous workflow execution through systematic task discovery, agent coordination, and progress tracking. **Executes entire workflow without user interruption** (except initial session selection if multiple active sessions exist), providing complete context to agents and ensuring proper flow control execution with comprehensive TodoWrite tracking. **Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session. @@ -366,7 +365,7 @@ if (autoYes) { - Serialization Requirements (which tasks must run sequentially) - Critical Path (priority execution order) 3. **Use TODO_LIST.md for status tracking** only -4. **IMPL_PLAN decides "HOW"**, execute.md implements it +4. **IMPL_PLAN decides "HOW"**, workflow-execute implements it **Intelligent Fallback (When IMPL_PLAN lacks execution details)**: 1. **Analyze task structure**: @@ -595,5 +594,14 @@ meta.agent missing → Infer from meta.type: **Error Handling**: Skip commit on no changes/missing summary, log errors, continue workflow. +## Related Skills +**Prerequisite Skills**: +- `/workflow:plan` - Generate implementation plan and task JSONs +**Called During Execution**: +- `/workflow:session:complete` - Archive session after all tasks complete +- `/workflow:review` - Post-implementation review + +**Follow-up Skills**: +- `/issue:new` - Create follow-up issues (test/enhance/refactor/doc) diff --git a/.claude/skills/workflow-plan/SKILL.md b/.claude/skills/workflow-plan/SKILL.md new file mode 100644 index 00000000..82d5ed8c --- /dev/null +++ b/.claude/skills/workflow-plan/SKILL.md @@ -0,0 +1,380 @@ +--- +name: workflow-plan +description: Unified planning skill - 4-phase planning workflow, plan verification, and interactive replanning. Triggers on "workflow:plan", "workflow:plan-verify", "workflow:replan". +allowed-tools: Skill, Task, AskUserQuestion, TodoWrite, Read, Write, Edit, Bash, Glob, Grep +--- + +# Workflow Plan + +Unified planning skill combining 4-phase planning workflow, plan quality verification, and interactive replanning. Produces IMPL_PLAN.md, task JSONs, verification reports, and manages plan lifecycle through session-level artifact updates. + +## Architecture Overview + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ Workflow Plan Orchestrator (SKILL.md) │ +│ → Route by mode: plan | verify | replan │ +│ → Pure coordinator: Execute phases, parse outputs, pass context │ +└──────────────────────────────┬───────────────────────────────────┘ + │ + ┌───────────────────────┼───────────────────────┐ + ↓ ↓ ↓ + ┌───────────┐ ┌───────────┐ ┌───────────┐ + │ Plan Mode │ │ Verify │ │ Replan │ + │ (default) │ │ Mode │ │ Mode │ + │ Phase 1-4 │ │ Phase 5 │ │ Phase 6 │ + └─────┬─────┘ └───────────┘ └───────────┘ + │ + ┌───┼───┬───┐ + ↓ ↓ ↓ ↓ + ┌───┐┌───┐┌───┐┌───┐ + │ 1 ││ 2 ││ 3 ││ 4 │ + │Ses││Ctx││Con││Gen│ + └───┘└───┘└───┘└─┬─┘ + ↓ + ┌───────────┐ + │ Confirm │─── Verify ──→ Phase 5 + │ (choice) │─── Execute ─→ Skill("workflow-execute") + └───────────┘─── Review ──→ /workflow:status +``` + +## Key Design Principles + +1. **Pure Orchestrator**: SKILL.md routes and coordinates only; execution detail lives in phase files +2. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute +3. **Multi-Mode Routing**: Single skill handles plan/verify/replan via mode detection +4. **Task Attachment Model**: Sub-command tasks are ATTACHED, executed sequentially, then COLLAPSED +5. **Auto-Continue**: After each phase completes, automatically execute next pending phase +6. **Accumulated State**: planning-notes.md carries context across phases for N+1 decisions + +## Auto Mode + +When `--yes` or `-y`: Auto-continue all phases (skip confirmations), use recommended conflict resolutions, use safe defaults for replan. + +## Mode Detection + +```javascript +const args = $ARGUMENTS +const mode = detectMode(args) + +function detectMode(args) { + // Skill trigger determines mode + if (skillName === 'workflow:plan-verify') return 'verify' + if (skillName === 'workflow:replan') return 'replan' + return 'plan' // default: workflow:plan +} +``` + +## Execution Flow + +### Plan Mode (default) + +``` +Input Parsing: + └─ Convert user input to structured format (GOAL/SCOPE/CONTEXT) + +Phase 1: Session Discovery + └─ Ref: phases/01-session-discovery.md + └─ Output: sessionId (WFS-xxx), planning-notes.md + +Phase 2: Context Gathering + └─ Ref: phases/02-context-gathering.md + ├─ Tasks attached: Analyze structure → Identify integration → Generate package + └─ Output: contextPath + conflictRisk + +Phase 3: Conflict Resolution (conditional: conflictRisk ≥ medium) + └─ Decision (conflictRisk check): + ├─ conflictRisk ≥ medium → Ref: phases/03-conflict-resolution.md + │ ├─ Tasks attached: Detect conflicts → Present to user → Apply strategies + │ └─ Output: Modified brainstorm artifacts + └─ conflictRisk < medium → Skip to Phase 4 + +Phase 4: Task Generation + └─ Ref: phases/04-task-generation.md + └─ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md + +Plan Confirmation (User Decision Gate): + └─ Decision (user choice): + ├─ "Verify Plan Quality" (Recommended) → Route to Phase 5 (plan-verify) + ├─ "Start Execution" → Skill(skill="workflow-execute") + └─ "Review Status Only" → Route to /workflow:status +``` + +### Verify Mode + +``` +Phase 5: Plan Verification + └─ Ref: phases/05-plan-verify.md + └─ Output: PLAN_VERIFICATION.md with quality gate recommendation +``` + +### Replan Mode + +``` +Phase 6: Interactive Replan + └─ Ref: phases/06-replan.md + └─ Output: Updated IMPL_PLAN.md, task JSONs, TODO_LIST.md +``` + +**Phase Reference Documents** (read on-demand when phase executes): + +| Phase | Document | Purpose | Mode | +|-------|----------|---------|------| +| 1 | [phases/01-session-discovery.md](phases/01-session-discovery.md) | Create or discover workflow session | plan | +| 2 | [phases/02-context-gathering.md](phases/02-context-gathering.md) | Gather project context and analyze codebase | plan | +| 3 | [phases/03-conflict-resolution.md](phases/03-conflict-resolution.md) | Detect and resolve conflicts (conditional) | plan | +| 4 | [phases/04-task-generation.md](phases/04-task-generation.md) | Generate implementation plan and task JSONs | plan | +| 5 | [phases/05-plan-verify.md](phases/05-plan-verify.md) | Read-only verification with quality gate | verify | +| 6 | [phases/06-replan.md](phases/06-replan.md) | Interactive replanning with boundary clarification | replan | + +## Core Rules + +1. **Start Immediately**: First action is mode detection + TodoWrite initialization, second action is phase execution +2. **No Preliminary Analysis**: Do not read files, analyze structure, or gather context before Phase 1 +3. **Parse Every Output**: Extract required data from each phase output for next phase +4. **Auto-Continue via TodoList**: Check TodoList status to execute next pending phase automatically +5. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern +6. **Task Attachment Model**: Skill execute **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion +7. **Progressive Phase Loading**: Read phase docs ONLY when that phase is about to execute +8. **DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase + +## Input Processing + +**Convert User Input to Structured Format**: + +1. **Simple Text** → Structure it: + ``` + User: "Build authentication system" + + Structured: + GOAL: Build authentication system + SCOPE: Core authentication features + CONTEXT: New implementation + ``` + +2. **Detailed Text** → Extract components: + ``` + User: "Add JWT authentication with email/password login and token refresh" + + Structured: + GOAL: Implement JWT-based authentication + SCOPE: Email/password login, token generation, token refresh endpoints + CONTEXT: JWT token-based security, refresh token rotation + ``` + +3. **File Reference** (e.g., `requirements.md`) → Read and structure: + - Read file content + - Extract goal, scope, requirements + - Format into structured description + +## Data Flow + +### Plan Mode + +``` +User Input (task description) + ↓ +[Convert to Structured Format] + ↓ Structured Description: + ↓ GOAL: [objective] + ↓ SCOPE: [boundaries] + ↓ CONTEXT: [background] + ↓ +Phase 1: session:start --auto "structured-description" + ↓ Output: sessionId + ↓ Write: planning-notes.md (User Intent section) + ↓ +Phase 2: context-gather --session sessionId "structured-description" + ↓ Input: sessionId + structured description + ↓ Output: contextPath (context-package.json) + conflictRisk + ↓ Update: planning-notes.md (Context Findings + Consolidated Constraints) + ↓ +Phase 3: conflict-resolution [conditional: conflictRisk ≥ medium] + ↓ Input: sessionId + contextPath + conflictRisk + ↓ Output: Modified brainstorm artifacts + ↓ Update: planning-notes.md (Conflict Decisions + Consolidated Constraints) + ↓ Skip if conflictRisk is none/low → proceed directly to Phase 4 + ↓ +Phase 4: task-generate-agent --session sessionId + ↓ Input: sessionId + planning-notes.md + context-package.json + brainstorm artifacts + ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md + ↓ +Plan Confirmation (User Decision Gate): + ├─ "Verify Plan Quality" (Recommended) → Route to Phase 5 + ├─ "Start Execution" → Skill(skill="workflow-execute") + └─ "Review Status Only" → Route to /workflow:status +``` + +**Session Memory Flow**: Each phase receives session ID, which provides access to: +- Previous task summaries +- Existing context and analysis +- Brainstorming artifacts (potentially modified by Phase 3) +- Session-specific configuration + +### Verify Mode + +``` +Input: --session sessionId (or auto-detect) + ↓ +Phase 5: Load artifacts → Agent-driven verification → Generate report + ↓ Output: PLAN_VERIFICATION.md with quality gate +``` + +### Replan Mode + +``` +Input: [--session sessionId] [task-id] "requirements" + ↓ +Phase 6: Mode detection → Clarification → Impact analysis → Backup → Apply → Verify + ↓ Output: Updated artifacts + change summary +``` + +## TodoWrite Pattern + +**Core Concept**: Dynamic task attachment and collapse for real-time visibility into workflow execution. + +### Key Principles + +1. **Task Attachment** (when phase executed): + - Sub-tasks are **attached** to orchestrator's TodoWrite + - **Phase 2, 3**: Multiple sub-tasks attached + - **Phase 1, 4**: Single task (atomic) + - First attached task marked as `in_progress`, others as `pending` + - Orchestrator **executes** these attached tasks sequentially + +2. **Task Collapse** (after sub-tasks complete): + - **Applies to Phase 2, 3**: Remove detailed sub-tasks from TodoWrite + - **Collapse** to high-level phase summary + - **Phase 1, 4**: No collapse needed (single task, just mark completed) + - Maintains clean orchestrator-level view + +3. **Continuous Execution**: After completion, automatically proceed to next pending phase + +**Lifecycle**: Initial pending → Phase executed (tasks ATTACHED) → Sub-tasks executed → Phase completed (tasks COLLAPSED for 2/3, marked completed for 1/4) → Next phase → Repeat + +### Phase 2 (Tasks Attached): +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed"}, + {"content": "Phase 2: Context Gathering", "status": "in_progress"}, + {"content": " → Analyze codebase structure", "status": "in_progress"}, + {"content": " → Identify integration points", "status": "pending"}, + {"content": " → Generate context package", "status": "pending"}, + {"content": "Phase 4: Task Generation", "status": "pending"} +] +``` + +### Phase 2 (Collapsed): +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed"}, + {"content": "Phase 2: Context Gathering", "status": "completed"}, + {"content": "Phase 4: Task Generation", "status": "pending"} +] +``` + +### Phase 3 (Tasks Attached, conditional): +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed"}, + {"content": "Phase 2: Context Gathering", "status": "completed"}, + {"content": "Phase 3: Conflict Resolution", "status": "in_progress"}, + {"content": " → Detect conflicts with CLI analysis", "status": "in_progress"}, + {"content": " → Present conflicts to user", "status": "pending"}, + {"content": " → Apply resolution strategies", "status": "pending"}, + {"content": "Phase 4: Task Generation", "status": "pending"} +] +``` + +**Note**: See individual Phase descriptions for detailed TodoWrite Update examples. + +## Post-Phase Updates + +After each phase completes, update planning-notes.md: + +- **After Phase 1**: Initialize with user intent (GOAL, KEY_CONSTRAINTS) +- **After Phase 2**: Add context findings (CRITICAL_FILES, ARCHITECTURE, CONFLICT_RISK, CONSTRAINTS) +- **After Phase 3**: Add conflict decisions (RESOLVED, MODIFIED_ARTIFACTS, CONSTRAINTS) if executed +- **Memory State Check**: After heavy phases (Phase 2-3), evaluate context window usage; if high (>120K tokens), trigger `compact` + +See phase files for detailed update code. + +## Error Handling + +- **Parsing Failure**: If output parsing fails, retry command once, then report error +- **Validation Failure**: If validation fails, report which file/data is missing +- **Command Failure**: Keep phase `in_progress`, report error to user, do not proceed to next phase +- **Session Not Found** (verify/replan): Report error with available sessions list +- **Task Not Found** (replan): Report error with available tasks list + +## Coordinator Checklist + +### Plan Mode +- **Pre-Phase**: Convert user input to structured format (GOAL/SCOPE/CONTEXT) +- Initialize TodoWrite before any command (Phase 3 added dynamically after Phase 2) +- Execute Phase 1 immediately with structured description +- Parse session ID from Phase 1 output, store in memory +- Pass session ID and structured description to Phase 2 command +- Parse context path from Phase 2 output, store in memory +- **Extract conflictRisk from context-package.json**: Determine Phase 3 execution +- **If conflictRisk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath +- Wait for Phase 3 to finish executing (if executed), verify conflict-resolution.json created +- **If conflictRisk is none/low**: Skip Phase 3, proceed directly to Phase 4 +- Pass session ID to Phase 4 command +- Verify all Phase 4 outputs +- **Plan Confirmation Gate**: Present user with choice (Verify → Phase 5 / Execute / Review Status) +- **If user selects Verify**: Read phases/05-plan-verify.md, execute Phase 5 in-process +- **If user selects Execute**: Skill(skill="workflow-execute") +- **If user selects Review**: Route to /workflow:status +- **Auto mode (--yes)**: Auto-select "Verify Plan Quality", then auto-continue to execute if PROCEED +- Update TodoWrite after each phase +- After each phase, automatically continue to next phase based on TodoList status + +### Verify Mode +- Detect/validate session (from --session flag or auto-detect) +- Initialize TodoWrite with single verification task +- Execute Phase 5 verification agent +- Present quality gate result and next step options + +### Replan Mode +- Parse flags (--session, --interactive, task-id) +- Detect operation mode (task vs session) +- Initialize TodoWrite with replan-specific tasks +- Execute Phase 6 through all sub-phases (clarification → impact → backup → apply → verify) + +## Structure Template Reference + +**Minimal Structure**: +``` +GOAL: [What to achieve] +SCOPE: [What's included] +CONTEXT: [Relevant info] +``` + +**Detailed Structure** (optional, when more context available): +``` +GOAL: [Primary objective] +SCOPE: [Included features/components] +CONTEXT: [Existing system, constraints, dependencies] +REQUIREMENTS: [Specific technical requirements] +CONSTRAINTS: [Limitations or boundaries] +``` + +## Related Skills + +**Prerequisite Skills**: +- `/workflow:brainstorm:artifacts` - Optional: Generate role-based analyses before planning +- `/workflow:brainstorm:synthesis` - Optional: Refine brainstorm analyses with clarifications + +**Called by Plan Mode** (4 phases): +- `/workflow:session:start` - Phase 1: Create or discover workflow session +- `/workflow:tools:context-gather` - Phase 2: Gather project context and analyze codebase +- `/workflow:tools:conflict-resolution` - Phase 3: Detect and resolve conflicts (conditional) +- `/compact` - Phase 3: Memory optimization (if context approaching limits) +- `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files + +**Follow-up Skills**: +- `/workflow:plan-verify` - Verify plan quality (can also invoke via verify mode) +- `/workflow:status` - Review task breakdown and current progress +- `Skill(skill="workflow-execute")` - Begin implementation of generated tasks (skill: workflow-execute) +- `/workflow:replan` - Modify plan (can also invoke via replan mode) diff --git a/.claude/skills/workflow-plan/phases/04-task-generation.md b/.claude/skills/workflow-plan/phases/04-task-generation.md new file mode 100644 index 00000000..d8b564d7 --- /dev/null +++ b/.claude/skills/workflow-plan/phases/04-task-generation.md @@ -0,0 +1,135 @@ +# Phase 4: Task Generation + +Generate implementation plan and task JSONs via action-planning-agent. + +## Objective + +- Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md +- Present user with plan confirmation choices (verify / execute / review) +- Route to Phase 5 (verify) if user selects verification + +## Relationship with Brainstorm Phase + +- If brainstorm role analyses exist ([role]/analysis.md files), they are incorporated as input +- **User's original intent is ALWAYS primary**: New or refined user goals override brainstorm recommendations +- **Role analysis.md files define "WHAT"**: Requirements, design specs, role-specific insights +- **IMPL_PLAN.md defines "HOW"**: Executable task breakdown, dependencies, implementation sequence +- Task generation translates high-level role analyses into concrete, actionable work items +- **Intent priority**: Current user prompt > role analysis.md files > guidance-specification.md + +## Execution + +### Step 4.1: Execute Task Generation + +```javascript +Skill(skill="workflow:tools:task-generate-agent", args="--session [sessionId]") +``` + +**CLI Execution Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description. If user specifies "use Codex/Gemini/Qwen for X", CLI tool usage is controlled by `meta.execution_config.method` per task, not by `command` fields in implementation steps. + +**Input**: +- `sessionId` from Phase 1 +- **planning-notes.md**: Consolidated constraints from all phases (Phase 1-3) + - Path: `.workflow/active/[sessionId]/planning-notes.md` + - Contains: User intent, context findings, conflict decisions, consolidated constraints + - **Purpose**: Provides structured, minimal context summary to action-planning-agent + +**Validation**: +- `.workflow/active/[sessionId]/plan.json` exists (structured plan overview) +- `.workflow/active/[sessionId]/IMPL_PLAN.md` exists +- `.workflow/active/[sessionId]/.task/IMPL-*.json` exists (at least one) +- `.workflow/active/[sessionId]/TODO_LIST.md` exists + +### TodoWrite Update (Phase 4 Skill executed - agent task attached) + +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Phase 4: Task Generation", "status": "in_progress", "activeForm": "Executing task generation"} +] +``` + +**Note**: Single agent task attached. Agent autonomously completes discovery, planning, and output generation internally. + +### TodoWrite Update (Phase 4 completed) + +```json +[ + {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"}, + {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"}, + {"content": "Phase 4: Task Generation", "status": "completed", "activeForm": "Executing task generation"} +] +``` + +**Note**: Agent task completed. No collapse needed (single task). + +### Step 4.2: Plan Confirmation (User Decision Gate) + +After Phase 4 completes, present user with action choices: + +```javascript +console.log(` +Planning complete for session: ${sessionId} +Tasks generated: ${taskCount} +Plan: .workflow/active/${sessionId}/IMPL_PLAN.md +`); + +// Ask user for next action +const userChoice = AskUserQuestion({ + questions: [{ + question: "Planning complete. What would you like to do next?", + header: "Next Action", + multiSelect: false, + options: [ + { + label: "Verify Plan Quality (Recommended)", + description: "Run quality verification to catch issues before execution. Checks plan structure, task dependencies, and completeness." + }, + { + label: "Start Execution", + description: "Begin implementing tasks immediately. Use this if you've already reviewed the plan or want to start quickly." + }, + { + label: "Review Status Only", + description: "View task breakdown and session status without taking further action. You can decide what to do next manually." + } + ] + }] +}); + +// Execute based on user choice +if (userChoice.answers["Next Action"] === "Verify Plan Quality (Recommended)") { + console.log("\nStarting plan verification...\n"); + // Route to Phase 5 (plan-verify) within this skill + // Orchestrator reads phases/05-plan-verify.md and executes +} else if (userChoice.answers["Next Action"] === "Start Execution") { + console.log("\nStarting task execution...\n"); + Skill(skill="workflow-execute", args="--session " + sessionId); +} else if (userChoice.answers["Next Action"] === "Review Status Only") { + console.log("\nDisplaying session status...\n"); + Skill(skill="workflow:status", args="--session " + sessionId); +} +``` + +**Auto Mode (--yes)**: Auto-select "Verify Plan Quality", then auto-continue to execute if quality gate is PROCEED. + +**Return to Orchestrator**: Based on user's choice: +- **Verify** → Orchestrator reads phases/05-plan-verify.md and executes Phase 5 in-process +- **Execute** → Skill(skill="workflow-execute") +- **Review** → Route to /workflow:status + +## Output + +- **File**: `IMPL_PLAN.md` (implementation plan) +- **File**: `IMPL-*.json` (task JSON files) +- **File**: `TODO_LIST.md` (task list) +- **File**: `plan.json` (structured plan overview) +- **TodoWrite**: Mark Phase 4 completed + +## Next Phase (Conditional) + +Based on user's plan confirmation choice: +- If "Verify" → [Phase 5: Plan Verification](05-plan-verify.md) +- If "Execute" → Skill(skill="workflow-execute") +- If "Review" → External: /workflow:status diff --git a/.claude/skills/workflow-plan/phases/05-plan-verify.md b/.claude/skills/workflow-plan/phases/05-plan-verify.md new file mode 100644 index 00000000..c536aa38 --- /dev/null +++ b/.claude/skills/workflow-plan/phases/05-plan-verify.md @@ -0,0 +1,388 @@ +# Phase 5: Plan Verification + +Perform READ-ONLY verification analysis between IMPL_PLAN.md, task JSONs, and brainstorming artifacts. Generates structured report with quality gate recommendation. Does NOT modify any source files. + +## Objective + +- Generate comprehensive verification report identifying inconsistencies, duplications, ambiguities +- Produce quality gate recommendation (BLOCK_EXECUTION / PROCEED_WITH_FIXES / PROCEED_WITH_CAUTION / PROCEED) +- Route to next action based on quality gate result + +## Entry Points + +- **From Plan Mode**: After Phase 4 completes, user selects "Verify Plan Quality" +- **From Verify Mode**: Directly triggered via `/workflow:plan-verify` + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Operating Constraints + +**STRICTLY READ-ONLY FOR SOURCE ARTIFACTS**: +- **MUST NOT** modify `IMPL_PLAN.md`, any `task.json` files, or brainstorming artifacts +- **MUST NOT** create or delete task files +- **MUST ONLY** write the verification report to `.process/PLAN_VERIFICATION.md` + +**Synthesis Authority**: The `role analysis documents` are **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements. + +**Quality Gate Authority**: The verification report provides a binding recommendation based on objective severity criteria. User MUST review critical/high issues before proceeding with implementation. + +## Execution + +### Step 5.1: Initialize Analysis Context + +```bash +# Detect active workflow session +IF --session parameter provided: + session_id = provided session +ELSE: + # Auto-detect active session + active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null) + IF active_sessions is empty: + ERROR: "No active workflow session found. Use --session " + EXIT + ELSE IF active_sessions has multiple entries: + # Use most recently modified session + session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename) + ELSE: + session_id = basename(active_sessions[0]) + +# Derive absolute paths +session_dir = .workflow/active/WFS-{session} +brainstorm_dir = session_dir/.brainstorming +task_dir = session_dir/.task +process_dir = session_dir/.process +session_file = session_dir/workflow-session.json + +# Create .process directory if not exists (report output location) +IF NOT EXISTS(process_dir): + bash(mkdir -p "{process_dir}") + +# Validate required artifacts +# Note: "role analysis documents" refers to [role]/analysis.md files (e.g., product-manager/analysis.md) +SYNTHESIS_DIR = brainstorm_dir # Contains role analysis files: */analysis.md +IMPL_PLAN = session_dir/IMPL_PLAN.md +TASK_FILES = Glob(task_dir/*.json) +PLANNING_NOTES = session_dir/planning-notes.md # N+1 context and constraints + +# Abort if missing - in order of dependency +SESSION_FILE_EXISTS = EXISTS(session_file) +IF NOT SESSION_FILE_EXISTS: + WARNING: "workflow-session.json not found. User intent alignment verification will be skipped." + # Continue execution - this is optional context, not blocking + +PLANNING_NOTES_EXISTS = EXISTS(PLANNING_NOTES) +IF NOT PLANNING_NOTES_EXISTS: + WARNING: "planning-notes.md not found. Constraints/N+1 context verification will be skipped." + # Continue execution - optional context + +SYNTHESIS_FILES = Glob(brainstorm_dir/*/analysis.md) +IF SYNTHESIS_FILES.count == 0: + WARNING: "No role analysis documents found in .brainstorming/*/analysis.md. Synthesis-based dimensions (E, G) will use reduced coverage." + SYNTHESIS_AVAILABLE = false + # Continue execution - brainstorm artifacts are optional for direct planning workflows +ELSE: + SYNTHESIS_AVAILABLE = true + +IF NOT EXISTS(IMPL_PLAN): + ERROR: "IMPL_PLAN.md not found. Run /workflow:plan first" + EXIT + +IF TASK_FILES.count == 0: + ERROR: "No task JSON files found. Run /workflow:plan first" + EXIT +``` + +### Step 5.2: Load Artifacts (Progressive Disclosure) + +Load only minimal necessary context from each artifact: + +**From workflow-session.json** (OPTIONAL - Primary Reference for User Intent): +- **ONLY IF EXISTS**: Load user intent context +- Original user prompt/intent (project or description field) +- User's stated goals and objectives +- User's scope definition +- **IF MISSING**: Set user_intent_analysis = "SKIPPED: workflow-session.json not found" + +**From planning-notes.md** (OPTIONAL - Constraints & N+1 Context): +- **ONLY IF EXISTS**: Load planning context +- Consolidated Constraints (numbered list from Phase 1-3) +- N+1 Context: Decisions table (Decision | Rationale | Revisit?) +- N+1 Context: Deferred items list +- **IF MISSING**: Set planning_notes_analysis = "SKIPPED: planning-notes.md not found" + +**From role analysis documents** (AUTHORITATIVE SOURCE): +- Functional Requirements (IDs, descriptions, acceptance criteria) +- Non-Functional Requirements (IDs, targets) +- Business Requirements (IDs, success metrics) +- Key Architecture Decisions +- Risk factors and mitigation strategies +- Implementation Roadmap (high-level phases) + +**From IMPL_PLAN.md**: +- Summary and objectives +- Context Analysis +- Implementation Strategy +- Task Breakdown Summary +- Success Criteria +- Brainstorming Artifacts References (if present) + +**From task.json files**: +- Task IDs +- Titles and descriptions +- Status +- Dependencies (depends_on, blocks) +- Context (requirements, focus_paths, acceptance, artifacts) +- Flow control (pre_analysis, implementation_approach) +- Meta (complexity, priority) + +### Step 5.3: Build Semantic Models + +Create internal representations (do not include raw artifacts in output): + +**Requirements inventory**: +- Each functional/non-functional/business requirement with stable ID +- Requirement text, acceptance criteria, priority + +**Architecture decisions inventory**: +- ADRs from synthesis +- Technology choices +- Data model references + +**Task coverage mapping**: +- Map each task to one or more requirements (by ID reference or keyword inference) +- Map each requirement to covering tasks + +**Dependency graph**: +- Task-to-task dependencies (depends_on, blocks) +- Requirement-level dependencies (from synthesis) + +### Step 5.4: Detection Passes (Agent-Driven Multi-Dimensional Analysis) + +**Execution Strategy**: +- Single `cli-explore-agent` invocation +- Agent executes multiple CLI analyses internally (different dimensions: A-J) +- Token Budget: 50 findings maximum (aggregate remainder in overflow summary) +- Priority Allocation: CRITICAL (unlimited) → HIGH (15) → MEDIUM (20) → LOW (15) +- Early Exit: If CRITICAL findings > 0 in User Intent/Requirements Coverage, skip LOW/MEDIUM checks + +**Execution Order** (Agent orchestrates internally): + +1. **Tier 1 (CRITICAL Path)**: A, B, C, I - User intent, coverage, consistency, constraints compliance (full analysis) +2. **Tier 2 (HIGH Priority)**: D, E, J - Dependencies, synthesis alignment, N+1 context validation (limit 15 findings) +3. **Tier 3 (MEDIUM Priority)**: F - Specification quality (limit 20 findings) +4. **Tier 4 (LOW Priority)**: G, H - Duplication, feasibility (limit 15 findings) + +--- + +#### Step 5.4.1: Launch Unified Verification Agent + +```javascript +Task( + subagent_type="cli-explore-agent", + run_in_background=false, + description="Multi-dimensional plan verification", + prompt=` +## Plan Verification Task + +### MANDATORY FIRST STEPS +1. Read: ~/.ccw/workflows/cli-templates/schemas/plan-verify-agent-schema.json (dimensions & rules) +2. Read: ~/.ccw/workflows/cli-templates/schemas/verify-json-schema.json (output schema) +3. Read: ${session_file} (user intent) +4. Read: ${PLANNING_NOTES} (constraints & N+1 context) +5. Read: ${IMPL_PLAN} (implementation plan) +6. Glob: ${task_dir}/*.json (task files) +7. Glob: ${SYNTHESIS_DIR}/*/analysis.md (role analyses) + +### Execution Flow + +**Load schema → Execute tiered CLI analysis → Aggregate findings → Write JSON** + +FOR each tier in [1, 2, 3, 4]: + - Load tier config from plan-verify-agent-schema.json + - Execute: ccw cli -p "PURPOSE: Verify dimensions {tier.dimensions} + TASK: {tier.checks from schema} + CONTEXT: @${session_dir}/**/* + EXPECTED: Findings JSON with dimension, severity, location, summary, recommendation + CONSTRAINTS: Limit {tier.limit} findings + " --tool gemini --mode analysis --rule {tier.rule} + - Parse findings, check early exit condition + - IF tier == 1 AND critical_count > 0: skip tier 3-4 + +### Output +Write: ${process_dir}/verification-findings.json (follow verify-json-schema.json) +Return: Quality gate decision + 2-3 sentence summary +` +) +``` + +--- + +#### Step 5.4.2: Load and Organize Findings + +```javascript +// Load findings (single parse for all subsequent use) +const data = JSON.parse(Read(`${process_dir}/verification-findings.json`)) +const { session_id, timestamp, verification_tiers_completed, findings, summary } = data +const { critical_count, high_count, medium_count, low_count, total_findings, coverage_percentage, recommendation } = summary + +// Group by severity and dimension +const bySeverity = Object.groupBy(findings, f => f.severity) +const byDimension = Object.groupBy(findings, f => f.dimension) + +// Dimension metadata (from schema) +const DIMS = { + A: "User Intent Alignment", B: "Requirements Coverage", C: "Consistency Validation", + D: "Dependency Integrity", E: "Synthesis Alignment", F: "Task Specification Quality", + G: "Duplication Detection", H: "Feasibility Assessment", + I: "Constraints Compliance", J: "N+1 Context Validation" +} +``` + +### Step 5.5: Generate Report + +```javascript +// Helper: render dimension section +const renderDimension = (dim) => { + const items = byDimension[dim] || [] + return items.length > 0 + ? items.map(f => `### ${f.id}: ${f.summary}\n- **Severity**: ${f.severity}\n- **Location**: ${f.location.join(', ')}\n- **Recommendation**: ${f.recommendation}`).join('\n\n') + : `> No ${DIMS[dim]} issues detected.` +} + +// Helper: render severity section +const renderSeverity = (severity, impact) => { + const items = bySeverity[severity] || [] + return items.length > 0 + ? items.map(f => `#### ${f.id}: ${f.summary}\n- **Dimension**: ${f.dimension_name}\n- **Location**: ${f.location.join(', ')}\n- **Impact**: ${impact}\n- **Recommendation**: ${f.recommendation}`).join('\n\n') + : `> No ${severity.toLowerCase()}-severity issues detected.` +} + +// Build Markdown report +const fullReport = ` +# Plan Verification Report + +**Session**: WFS-${session_id} | **Generated**: ${timestamp} +**Tiers Completed**: ${verification_tiers_completed.join(', ')} + +--- + +## Executive Summary + +| Metric | Value | Status | +|--------|-------|--------| +| Risk Level | ${critical_count > 0 ? 'CRITICAL' : high_count > 0 ? 'HIGH' : medium_count > 0 ? 'MEDIUM' : 'LOW'} | ${critical_count > 0 ? 'RED' : high_count > 0 ? 'ORANGE' : medium_count > 0 ? 'YELLOW' : 'GREEN'} | +| Critical/High/Medium/Low | ${critical_count}/${high_count}/${medium_count}/${low_count} | | +| Coverage | ${coverage_percentage}% | ${coverage_percentage >= 90 ? 'GREEN' : coverage_percentage >= 75 ? 'YELLOW' : 'RED'} | + +**Recommendation**: **${recommendation}** + +--- + +## Findings Summary + +| ID | Dimension | Severity | Location | Summary | +|----|-----------|----------|----------|---------| +${findings.map(f => `| ${f.id} | ${f.dimension_name} | ${f.severity} | ${f.location.join(', ')} | ${f.summary} |`).join('\n')} + +--- + +## Analysis by Dimension + +${['A','B','C','D','E','F','G','H','I','J'].map(d => `### ${d}. ${DIMS[d]}\n\n${renderDimension(d)}`).join('\n\n---\n\n')} + +--- + +## Findings by Severity + +### CRITICAL (${critical_count}) +${renderSeverity('CRITICAL', 'Blocks execution')} + +### HIGH (${high_count}) +${renderSeverity('HIGH', 'Fix before execution recommended')} + +### MEDIUM (${medium_count}) +${renderSeverity('MEDIUM', 'Address during/after implementation')} + +### LOW (${low_count}) +${renderSeverity('LOW', 'Optional improvement')} + +--- + +## Next Steps + +${recommendation === 'BLOCK_EXECUTION' ? 'BLOCK: Fix critical issues then re-verify' : + recommendation === 'PROCEED_WITH_FIXES' ? 'FIX RECOMMENDED: Address high issues then re-verify or execute' : + 'READY: Proceed to Skill(skill="workflow-execute")'} + +Re-verify: \`/workflow:plan-verify --session ${session_id}\` +Execute: \`Skill(skill="workflow-execute", args="--resume-session=${session_id}")\` +` + +// Write report +Write(`${process_dir}/PLAN_VERIFICATION.md`, fullReport) +console.log(`Report: ${process_dir}/PLAN_VERIFICATION.md\n${recommendation} | C:${critical_count} H:${high_count} M:${medium_count} L:${low_count} | Coverage:${coverage_percentage}%`) +``` + +### Step 5.6: Next Step Selection + +```javascript +const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const canExecute = recommendation !== 'BLOCK_EXECUTION' + +// Auto mode +if (autoYes) { + if (canExecute) { + Skill(skill="workflow-execute", args="--yes --resume-session=\"${session_id}\"") + } else { + console.log(`[--yes] BLOCK_EXECUTION - Fix ${critical_count} critical issues first.`) + } + return +} + +// Interactive mode - build options based on quality gate +const options = canExecute + ? [ + { label: canExecute && recommendation === 'PROCEED_WITH_FIXES' ? "Execute Anyway" : "Execute (Recommended)", + description: "Proceed to Skill(skill=\"workflow-execute\")" }, + { label: "Review Report", description: "Review findings before deciding" }, + { label: "Re-verify", description: "Re-run after manual fixes" } + ] + : [ + { label: "Review Report", description: "Review critical issues" }, + { label: "Re-verify", description: "Re-run after fixing issues" } + ] + +const selection = AskUserQuestion({ + questions: [{ + question: `Quality gate: ${recommendation}. Next step?`, + header: "Action", + multiSelect: false, + options + }] +}) + +// Handle selection +if (selection.includes("Execute")) { + Skill(skill="workflow-execute", args="--resume-session=\"${session_id}\"") +} else if (selection === "Re-verify") { + Skill(skill="workflow:plan-verify", args="--session ${session_id}") +} +``` + +## Output + +- **File**: `PLAN_VERIFICATION.md` (verification report with quality gate) +- **File**: `verification-findings.json` (structured findings data) + +## Completion + +Phase 5 is a terminal phase. Based on quality gate result, user routes to: +- Execute → Skill(skill="workflow-execute") +- Re-verify → Re-run Phase 5 +- Review → Manual inspection