diff --git a/.claude/commands/workflow/merge-plans-with-file.md b/.claude/commands/workflow/merge-plans-with-file.md new file mode 100644 index 00000000..3e0d2249 --- /dev/null +++ b/.claude/commands/workflow/merge-plans-with-file.md @@ -0,0 +1,807 @@ +--- +name: merge-plans-with-file +description: Merge multiple planning/brainstorm/analysis outputs, resolve conflicts, and synthesize unified plan. Designed for multi-team input aggregation and final plan crystallization +argument-hint: "[-y|--yes] [-r|--rule consensus|priority|hierarchy] \"plan or topic name\"" +allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*) +--- + +## Auto Mode + +When `--yes` or `-y`: Auto-resolve conflicts using specified rule (consensus/priority/hierarchy), minimal user prompts. + +# Workflow Merge-Plans-With-File Command (/workflow:merge-plans-with-file) + +## Overview + +Plan aggregation and conflict resolution workflow. Takes multiple planning artifacts (brainstorm conclusions, analysis recommendations, quick-plans, implementation plans) and synthesizes them into a unified, conflict-resolved execution plan. + +**Core workflow**: Load Sources → Parse Plans → Conflict Analysis → Arbitration → Unified Plan + +**Key features**: +- **Multi-Source Support**: Brainstorm, analysis, quick-plan, IMPL_PLAN, task JSONs +- **Parallel Conflict Detection**: Identify all contradictions across input plans +- **Conflict Resolution**: Consensus, priority-based, or hierarchical resolution modes +- **Unified Synthesis**: Single authoritative plan from multiple perspectives +- **Decision Tracking**: Full audit trail of conflicts and resolutions +- **Resumable**: Save intermediate states, refine resolutions + +## Usage + +```bash +/workflow:merge-plans-with-file [FLAGS] + +# Flags +-y, --yes Auto-resolve conflicts using rule, skip confirmations +-r, --rule Conflict resolution rule: consensus (default) | priority | hierarchy +-o, --output Output directory (default: .workflow/.merged/{name}) + +# Arguments + Plan name or glob pattern to identify input files/sessions + Examples: "auth-module", "*.analysis-*.json", "PLAN-*" + +# Examples +/workflow:merge-plans-with-file "authentication" # Auto-detect all auth-related plans +/workflow:merge-plans-with-file -y -r priority "payment-system" # Auto-resolve with priority rule +/workflow:merge-plans-with-file -r hierarchy "feature-complete" # Use hierarchy rule (requires user ranking) +``` + +## Execution Process + +``` +Discovery & Loading: + ├─ Search for planning artifacts matching pattern + ├─ Load all synthesis.json, conclusions.json, IMPL_PLAN.md + ├─ Parse each into normalized task/plan structure + └─ Validate data completeness + +Session Initialization: + ├─ Create .workflow/.merged/{sessionId}/ + ├─ Initialize merge.md with plan summary + ├─ Index all source plans + └─ Extract planning metadata and constraints + +Phase 1: Plan Normalization + ├─ Convert all formats to common task representation + ├─ Extract tasks, dependencies, effort, risks + ├─ Identify plan scope and boundaries + ├─ Validate no duplicate tasks + └─ Aggregate recommendations from each plan + +Phase 2: Conflict Detection (Parallel) + ├─ Architecture conflicts: different design approaches + ├─ Task conflicts: overlapping responsibilities or different priorities + ├─ Effort conflicts: vastly different estimates + ├─ Risk assessment conflicts: different risk levels + ├─ Scope conflicts: different feature inclusions + └─ Generate conflict matrix with severity levels + +Phase 3: Consensus Building / Arbitration + ├─ For each conflict, analyze source rationale + ├─ Apply resolution rule (consensus/priority/hierarchy) + ├─ Escalate unresolvable conflicts to user (unless --yes) + ├─ Document decision rationale + └─ Generate resolutions.json + +Phase 4: Plan Synthesis + ├─ Merge task lists (remove duplicates, combine insights) + ├─ Integrate dependencies from all sources + ├─ Consolidate effort and risk estimates + ├─ Generate unified execution sequence + ├─ Create final unified plan + └─ Output ready for execution + +Output: + ├─ .workflow/.merged/{sessionId}/merge.md (merge process & decisions) + ├─ .workflow/.merged/{sessionId}/source-index.json (input sources) + ├─ .workflow/.merged/{sessionId}/conflicts.json (conflict matrix) + ├─ .workflow/.merged/{sessionId}/resolutions.json (how conflicts were resolved) + ├─ .workflow/.merged/{sessionId}/unified-plan.json (final merged plan) + └─ .workflow/.merged/{sessionId}/unified-plan.md (execution-ready markdown) +``` + +## Implementation + +### Phase 1: Plan Discovery & Loading + +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +// Parse arguments +const planPattern = "$PLAN_NAME_OR_PATTERN" +const resolutionRule = $ARGUMENTS.match(/--rule\s+(\w+)/)?.[1] || 'consensus' +const isAutoMode = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') + +// Generate session ID +const mergeSlug = planPattern.toLowerCase() + .replace(/[*?]/g, '-') + .replace(/[^a-z0-9\u4e00-\u9fa5-]+/g, '-') + .substring(0, 30) +const dateStr = getUtc8ISOString().substring(0, 10) +const sessionId = `MERGE-${mergeSlug}-${dateStr}` +const sessionFolder = `.workflow/.merged/${sessionId}` + +bash(`mkdir -p ${sessionFolder}`) + +// Discover all relevant planning artifacts +const discoveryPaths = [ + `.workflow/.brainstorm/*/${planPattern}*/synthesis.json`, + `.workflow/.analysis/*/${planPattern}*/conclusions.json`, + `.workflow/.planning/*/${planPattern}*/synthesis.json`, + `.workflow/.plan/${planPattern}*IMPL_PLAN.md`, + `.workflow/*/${planPattern}*.json` +] + +const sourcePlans = [] + +for (const pattern of discoveryPaths) { + const matches = glob(pattern) + for (const path of matches) { + try { + const content = Read(path) + const plan = parsePlanFile(path, content) + if (plan && plan.tasks?.length > 0) { + sourcePlans.push({ + source_path: path, + source_type: identifySourceType(path), + plan: plan, + loaded_at: getUtc8ISOString() + }) + } + } catch (e) { + console.warn(`Failed to load plan from ${path}: ${e.message}`) + } + } +} + +if (sourcePlans.length === 0) { + console.error(` +## Error: No Plans Found + +Pattern: ${planPattern} +Searched locations: +${discoveryPaths.join('\n')} + +Available plans in .workflow/: +`) + bash(`find .workflow -name "*.json" -o -name "*PLAN.md" | head -20`) + return { status: 'error', message: 'No plans found' } +} + +console.log(` +## Plans Discovered + +Total: ${sourcePlans.length} +${sourcePlans.map(sp => `- ${sp.source_type}: ${sp.source_path}`).join('\n')} +`) +``` + +--- + +### Phase 2: Plan Normalization + +```javascript +// Normalize all plans to common format +const normalizedPlans = sourcePlans.map((sourcePlan, idx) => { + const plan = sourcePlan.plan + const tasks = plan.tasks || [] + + return { + index: idx, + source: sourcePlan.source_path, + source_type: sourcePlan.source_type, + + metadata: { + title: plan.title || `Plan ${idx + 1}`, + topic: plan.topic || plan.planning_topic || 'unknown', + timestamp: plan.completed || plan.timestamp || sourcePlan.loaded_at, + source_ideas: plan.top_ideas?.length || 0, + complexity: plan.complexity_level || 'unknown' + }, + + // Normalized tasks + tasks: tasks.map(task => ({ + id: task.id || `T${idx}-${task.title?.substring(0, 20)}`, + title: task.title || task.content, + description: task.description || '', + type: task.type || inferType(task), + priority: task.priority || 'normal', + + // Effort estimation + effort: { + estimated: task.estimated_duration || task.effort_estimate || 'unknown', + from_plan: idx + }, + + // Risk assessment + risk: { + level: task.risk_level || 'medium', + from_plan: idx + }, + + // Dependencies + dependencies: task.dependencies || [], + + // Source tracking + source_plan_index: idx, + original_id: task.id, + + // Quality tracking + success_criteria: task.success_criteria || [], + challenges: task.challenges || [] + })) + } +}) + +// Save source index +const sourceIndex = { + session_id: sessionId, + merge_timestamp: getUtc8ISOString(), + pattern: planPattern, + total_source_plans: sourcePlans.length, + + sources: normalizedPlans.map(p => ({ + index: p.index, + source_path: p.source, + source_type: p.source_type, + topic: p.metadata.topic, + task_count: p.tasks.length + })) +} + +Write(`${sessionFolder}/source-index.json`, JSON.stringify(sourceIndex, null, 2)) +``` + +--- + +### Phase 3: Conflict Detection + +```javascript +// Detect conflicts across plans +const conflictDetector = { + // Architecture conflicts + architectureConflicts: [], + + // Task conflicts (duplicates, different scope) + taskConflicts: [], + + // Effort conflicts + effortConflicts: [], + + // Risk assessment conflicts + riskConflicts: [], + + // Scope conflicts + scopeConflicts: [], + + // Priority conflicts + priorityConflicts: [] +} + +// Algorithm 1: Detect similar tasks across plans +const allTasks = normalizedPlans.flatMap(p => p.tasks) +const taskGroups = groupSimilarTasks(allTasks) + +for (const group of taskGroups) { + if (group.tasks.length > 1) { + // Same task appears in multiple plans + const efforts = group.tasks.map(t => t.effort.estimated) + const effortVariance = calculateVariance(efforts) + + if (effortVariance > 0.5) { + // Significant difference in effort estimates + conflictDetector.effortConflicts.push({ + task_group: group.title, + conflicting_tasks: group.tasks.map((t, i) => ({ + id: t.id, + from_plan: t.source_plan_index, + effort: t.effort.estimated + })), + variance: effortVariance, + severity: 'high' + }) + } + + // Check for scope differences + const scopeDifferences = analyzeScopeDifferences(group.tasks) + if (scopeDifferences.length > 0) { + conflictDetector.taskConflicts.push({ + task_group: group.title, + scope_differences: scopeDifferences, + severity: 'medium' + }) + } + } +} + +// Algorithm 2: Architecture conflicts +const architectures = normalizedPlans.map(p => p.metadata.complexity) +if (new Set(architectures).size > 1) { + conflictDetector.architectureConflicts.push({ + different_approaches: true, + complexity_levels: architectures.map((a, i) => ({ + plan: i, + complexity: a + })), + severity: 'high' + }) +} + +// Algorithm 3: Risk assessment conflicts +const riskLevels = allTasks.map(t => ({ task: t.id, risk: t.risk.level })) +const taskRisks = {} +for (const tr of riskLevels) { + if (!taskRisks[tr.task]) taskRisks[tr.task] = [] + taskRisks[tr.task].push(tr.risk) +} + +for (const [task, risks] of Object.entries(taskRisks)) { + if (new Set(risks).size > 1) { + conflictDetector.riskConflicts.push({ + task: task, + conflicting_risk_levels: risks, + severity: 'medium' + }) + } +} + +// Save conflicts +Write(`${sessionFolder}/conflicts.json`, JSON.stringify(conflictDetector, null, 2)) +``` + +--- + +### Phase 4: Conflict Resolution + +```javascript +// Resolve conflicts based on selected rule +const resolutions = { + resolution_rule: resolutionRule, + timestamp: getUtc8ISOString(), + + effort_resolutions: [], + architecture_resolutions: [], + risk_resolutions: [], + scope_resolutions: [], + priority_resolutions: [] +} + +// Resolution Strategy 1: Consensus +if (resolutionRule === 'consensus') { + for (const conflict of conflictDetector.effortConflicts) { + // Use median or average + const efforts = conflict.conflicting_tasks.map(t => parseEffort(t.effort)) + const resolved_effort = calculateMedian(efforts) + + resolutions.effort_resolutions.push({ + conflict: conflict.task_group, + original_estimates: efforts, + resolved_estimate: resolved_effort, + method: 'consensus-median', + rationale: 'Used median of all estimates' + }) + } +} + +// Resolution Strategy 2: Priority-Based +else if (resolutionRule === 'priority') { + // Use the plan from highest priority source (first or most recent) + for (const conflict of conflictDetector.effortConflicts) { + const highestPriority = conflict.conflicting_tasks[0] // First plan has priority + + resolutions.effort_resolutions.push({ + conflict: conflict.task_group, + conflicting_estimates: conflict.conflicting_tasks.map(t => t.effort), + resolved_estimate: highestPriority.effort, + selected_from_plan: highestPriority.from_plan, + method: 'priority-based', + rationale: `Selected estimate from plan ${highestPriority.from_plan} (highest priority)` + }) + } +} + +// Resolution Strategy 3: Hierarchy (requires user ranking) +else if (resolutionRule === 'hierarchy') { + if (!isAutoMode) { + // Ask user to rank plan importance + const planRanking = AskUserQuestion({ + questions: [{ + question: "请按重要性排序这些规划(从最重要到最不重要):", + header: "Plan Ranking", + multiSelect: false, + options: normalizedPlans.slice(0, 5).map(p => ({ + label: `Plan ${p.index}: ${p.metadata.title.substring(0, 40)}`, + description: `${p.tasks.length} tasks, complexity: ${p.metadata.complexity}` + })) + }] + }) + + // Apply hierarchy + const hierarchy = extractHierarchy(planRanking) + for (const conflict of conflictDetector.effortConflicts) { + const topPriorityTask = conflict.conflicting_tasks + .sort((a, b) => hierarchy[a.from_plan] - hierarchy[b.from_plan])[0] + + resolutions.effort_resolutions.push({ + conflict: conflict.task_group, + resolved_estimate: topPriorityTask.effort, + selected_from_plan: topPriorityTask.from_plan, + method: 'hierarchy-based', + rationale: `Selected from highest-ranked plan` + }) + } + } +} + +Write(`${sessionFolder}/resolutions.json`, JSON.stringify(resolutions, null, 2)) +``` + +--- + +### Phase 5: Plan Synthesis + +```javascript +// Merge all tasks into unified plan +const unifiedTasks = [] +const processedTaskIds = new Set() + +for (const task of allTasks) { + const taskKey = generateTaskKey(task) + + if (processedTaskIds.has(taskKey)) { + // Task already added, skip + continue + } + + processedTaskIds.add(taskKey) + + // Apply resolution if this task has conflicts + let resolvedTask = { ...task } + + const effortResolution = resolutions.effort_resolutions + .find(r => r.conflict === taskKey) + if (effortResolution) { + resolvedTask.effort.estimated = effortResolution.resolved_estimate + resolvedTask.effort.resolution_method = effortResolution.method + } + + unifiedTasks.push({ + id: taskKey, + title: task.title, + description: task.description, + type: task.type, + priority: task.priority, + + effort: resolvedTask.effort, + risk: task.risk, + dependencies: task.dependencies, + + success_criteria: [...new Set([ + ...task.success_criteria, + ...findRelatedTasks(task, allTasks) + .flatMap(t => t.success_criteria) + ])], + + challenges: [...new Set([ + ...task.challenges, + ...findRelatedTasks(task, allTasks) + .flatMap(t => t.challenges) + ])], + + source_plans: [ + ...new Set(allTasks + .filter(t => generateTaskKey(t) === taskKey) + .map(t => t.source_plan_index)) + ] + }) +} + +// Generate execution sequence +const executionSequence = topologicalSort(unifiedTasks) +const criticalPath = identifyCriticalPath(unifiedTasks, executionSequence) + +// Final unified plan +const unifiedPlan = { + session_id: sessionId, + merge_timestamp: getUtc8ISOString(), + + summary: { + total_source_plans: normalizedPlans.length, + original_tasks_total: allTasks.length, + merged_tasks: unifiedTasks.length, + conflicts_resolved: Object.values(conflictDetector).flat().length, + resolution_rule: resolutionRule + }, + + merged_metadata: { + topics: [...new Set(normalizedPlans.map(p => p.metadata.topic))], + average_complexity: calculateAverage(normalizedPlans.map(p => parseComplexity(p.metadata.complexity))), + combined_scope: estimateScope(unifiedTasks) + }, + + tasks: unifiedTasks, + + execution_sequence: executionSequence, + critical_path: criticalPath, + + risks: aggregateRisks(unifiedTasks), + success_criteria: aggregateSuccessCriteria(unifiedTasks), + + audit_trail: { + source_plans: normalizedPlans.length, + conflicts_detected: Object.values(conflictDetector).flat().length, + conflicts_resolved: Object.values(resolutions).flat().length, + resolution_method: resolutionRule + } +} + +Write(`${sessionFolder}/unified-plan.json`, JSON.stringify(unifiedPlan, null, 2)) +``` + +--- + +### Phase 6: Generate Execution Plan + +```markdown +# Merged Planning Session + +**Session ID**: ${sessionId} +**Pattern**: ${planPattern} +**Created**: ${getUtc8ISOString()} + +--- + +## Merge Summary + +**Source Plans**: ${unifiedPlan.summary.total_source_plans} +**Original Tasks**: ${unifiedPlan.summary.original_tasks_total} +**Merged Tasks**: ${unifiedPlan.summary.merged_tasks} +**Tasks Deduplicated**: ${unifiedPlan.summary.original_tasks_total - unifiedPlan.summary.merged_tasks} +**Conflicts Resolved**: ${unifiedPlan.summary.conflicts_resolved} + +**Resolution Method**: ${unifiedPlan.summary.resolution_rule} + +--- + +## Merged Plan Overview + +**Topics**: ${unifiedPlan.merged_metadata.topics.join(', ')} +**Combined Complexity**: ${unifiedPlan.merged_metadata.average_complexity} +**Total Scope**: ${unifiedPlan.merged_metadata.combined_scope} + +--- + +## Unified Task List + +${unifiedPlan.tasks.map((task, i) => ` +${i+1}. **${task.id}: ${task.title}** + - Type: ${task.type} + - Effort: ${task.effort.estimated} + - Risk: ${task.risk.level} + - Source Plans: ${task.source_plans.join(', ')} + - ${task.description} +`).join('\n')} + +--- + +## Execution Sequence + +**Critical Path**: ${unifiedPlan.critical_path.join(' → ')} + +**Execution Order**: +${unifiedPlan.execution_sequence.map((id, i) => `${i+1}. ${id}`).join('\n')} + +--- + +## Conflict Resolution Report + +**Total Conflicts**: ${unifiedPlan.summary.conflicts_resolved} + +**Resolved Conflicts**: +${Object.entries(resolutions).flatMap(([key, items]) => + items.slice(0, 3).map((item, i) => ` +- ${key.replace('_', ' ')}: ${item.rationale || item.method} +`) +).join('\n')} + +**Full Report**: See \`conflicts.json\` and \`resolutions.json\` + +--- + +## Risks & Considerations + +**Aggregated Risks**: +${unifiedPlan.risks.slice(0, 5).map(r => `- **${r.title}**: ${r.mitigation}`).join('\n')} + +**Combined Success Criteria**: +${unifiedPlan.success_criteria.slice(0, 5).map(c => `- ${c}`).join('\n')} + +--- + +## Next Steps + +### Option 1: Direct Execution +Execute merged plan with unified-execute-with-file: +\`\`\` +/workflow:unified-execute-with-file -p ${sessionFolder}/unified-plan.json +\`\`\` + +### Option 2: Detailed Planning +Create detailed IMPL_PLAN from merged plan: +\`\`\` +/workflow:plan "Based on merged plan from $(echo ${planPattern})" +\`\`\` + +### Option 3: Review Conflicts +Review detailed conflict analysis: +\`\`\` +cat ${sessionFolder}/resolutions.json +\`\`\` + +--- + +## Artifacts + +- **source-index.json** - All input plans and sources +- **conflicts.json** - Conflict detection results +- **resolutions.json** - How each conflict was resolved +- **unified-plan.json** - Merged plan data structure (for execution) +- **unified-plan.md** - This document (human-readable) +``` + +--- + +## Session Folder Structure + +``` +.workflow/.merged/{sessionId}/ +├── merge.md # Merge process and decisions +├── source-index.json # All input plan sources +├── conflicts.json # Detected conflicts +├── resolutions.json # Conflict resolutions applied +├── unified-plan.json # Merged plan (machine-parseable, for execution) +└── unified-plan.md # Execution-ready plan (human-readable) +``` + +--- + +## Resolution Rules + +### Rule 1: Consensus (default) +- Use median or average of conflicting estimates +- Good for: Multiple similar perspectives +- Tradeoff: May miss important minority viewpoints + +### Rule 2: Priority-Based +- First plan has highest priority, subsequent plans are fallback +- Good for: Clear ranking of plan sources +- Tradeoff: Discards valuable alternative perspectives + +### Rule 3: Hierarchy +- User explicitly ranks importance of each plan +- Good for: Mixed-source plans (engineering + product + leadership) +- Tradeoff: Requires user input + +--- + +## Input Format Support + +| Source Type | Detection | Parsing | Notes | +|-------------|-----------|---------|-------| +| **Brainstorm** | `.brainstorm/*/synthesis.json` | Top ideas → tasks | Ideas converted to work items | +| **Analysis** | `.analysis/*/conclusions.json` | Recommendations → tasks | Recommendations prioritized | +| **Quick-Plan** | `.planning/*/synthesis.json` | Direct task list | Already normalized | +| **IMPL_PLAN** | `*IMPL_PLAN.md` | Markdown → tasks | Parsed from markdown structure | +| **Task JSON** | `.json` with `tasks` key | Direct mapping | Requires standard schema | + +--- + +## Error Handling + +| Situation | Action | +|-----------|--------| +| No plans found | Suggest search terms, list available plans | +| Incompatible formats | Skip unsupported format, continue with others | +| Circular dependencies | Alert user, suggest manual review | +| Unresolvable conflicts | Require user decision (unless --yes + conflict rule) | +| Contradictory recommendations | Document both options for user consideration | + +--- + +## Usage Patterns + +### Pattern 1: Merge Multiple Brainstorms + +```bash +/workflow:merge-plans-with-file "authentication" -y -r consensus +# → Finds all brainstorm sessions with "auth" +# → Merges top ideas into unified task list +# → Uses consensus method for conflicts +``` + +### Pattern 2: Synthesize Team Input + +```bash +/workflow:merge-plans-with-file "payment-integration" -r hierarchy +# → Loads plans from different team members +# → Asks for ranking by importance +# → Applies hierarchy-based conflict resolution +``` + +### Pattern 3: Bridge Planning Phases + +```bash +/workflow:merge-plans-with-file "user-auth" -f analysis +# → Takes analysis conclusions +# → Merges with existing quick-plans +# → Produces execution-ready plan +``` + +--- + +## Advanced: Custom Conflict Resolution + +For complex conflict scenarios, create custom resolution script: + +``` +.workflow/.merged/{sessionId}/ +└── custom-resolutions.js (optional) + - Define custom conflict resolution logic + - Applied after automatic resolution + - Override specific decisions +``` + +--- + +## Best Practices + +1. **Before merging**: + - Ensure all source plans have same quality level + - Verify plans address same scope/topic + - Document any special considerations + +2. **During merging**: + - Review conflict matrix (conflicts.json) + - Understand resolution rationale (resolutions.json) + - Challenge assumptions if results seem odd + +3. **After merging**: + - Validate unified plan makes sense + - Review critical path + - Ensure no important details lost + - Execute or iterate if needed + +--- + +## Integration with Other Workflows + +``` +Multiple Brainstorms / Analyses + │ + ├─ brainstorm-with-file (session 1) + ├─ brainstorm-with-file (session 2) + ├─ analyze-with-file (session 3) + │ + ▼ +merge-plans-with-file ◄──── This workflow + │ + ▼ +unified-plan.json + │ + ├─ /workflow:unified-execute-with-file (direct execution) + ├─ /workflow:plan (detailed planning) + └─ /workflow:quick-plan-with-file (refinement) +``` + +--- + +## Comparison: When to Use Which Merge Rule + +| Rule | Use When | Pros | Cons | +|------|----------|------|------| +| **Consensus** | Similar-quality inputs | Fair, balanced | May miss extremes | +| **Priority** | Clear hierarchy | Simple, predictable | May bias to first input | +| **Hierarchy** | Mixed stakeholders | Respects importance | Requires user ranking | + +--- + +**Ready to execute**: Run `/workflow:merge-plans-with-file` to start merging plans! diff --git a/.claude/commands/workflow/quick-plan-with-file.md b/.claude/commands/workflow/quick-plan-with-file.md new file mode 100644 index 00000000..bc850bbf --- /dev/null +++ b/.claude/commands/workflow/quick-plan-with-file.md @@ -0,0 +1,808 @@ +--- +name: quick-plan-with-file +description: Multi-agent rapid planning with minimal documentation, conflict resolution, and actionable synthesis. Designed as a lightweight planning supplement between brainstorm and full implementation planning +argument-hint: "[-y|--yes] [-c|--continue] [-f|--from ] \"planning topic or task description\"" +allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*) +--- + +## Auto Mode + +When `--yes` or `-y`: Auto-confirm planning decisions, use aggressive parallelization, minimal user interaction. + +# Workflow Quick-Plan-With-File Command (/workflow:quick-plan-with-file) + +## Overview + +Multi-agent rapid planning workflow with **minimal documentation overhead**. Coordinates parallel agent analysis, synthesizes conflicting perspectives into actionable decisions, and generates a lightweight implementation-ready plan. + +**Core workflow**: Parse Input → Parallel Analysis → Conflict Resolution → Plan Synthesis → Output + +**Key features**: +- **Plan Format Agnostic**: Consumes brainstorm conclusions, analysis recommendations, or raw task descriptions +- **Minimal Docs**: Single `plan.md` (no lengthy brainstorm.md or discussion.md) +- **Parallel Multi-Agent**: 3-4 concurrent agent perspectives (architecture, implementation, validation, risk) +- **Conflict Resolution**: Automatic conflict detection and resolution via synthesis agent +- **Actionable Output**: Direct task breakdown ready for execution +- **Session Resumable**: Continue if interrupted, checkpoint at each phase + +## Usage + +```bash +/workflow:quick-plan-with-file [FLAGS] + +# Flags +-y, --yes Auto-confirm decisions, use defaults +-c, --continue Continue existing session (auto-detected) +-f, --from Input source type: brainstorm|analysis|task|raw + +# Arguments + Planning topic, task, or reference to planning artifact + +# Examples +/workflow:quick-plan-with-file "实现分布式缓存层，支持Redis和内存后端" +/workflow:quick-plan-with-file --continue "缓存层规划" # Continue +/workflow:quick-plan-with-file -y -f analysis "从分析结论生成实施规划" # Auto mode +/workflow:quick-plan-with-file --from brainstorm BS-rate-limiting-2025-01-28 # From artifact +``` + +## Execution Process + +``` +Input Validation & Loading: + ├─ Parse input (topic | artifact reference) + ├─ Load artifact if referenced (synthesis.json | conclusions.json | etc.) + ├─ Extract key constraints and requirements + └─ Initialize session folder and plan.md + +Session Initialization: + ├─ Create .workflow/.planning/{sessionId}/ + ├─ Initialize plan.md with input summary + ├─ Parse existing output (if --from artifact) + └─ Define planning dimensions & focus areas + +Phase 1: Parallel Multi-Agent Analysis (concurrent) + ├─ Agent 1 (Architecture): High-level design & decomposition + ├─ Agent 2 (Implementation): Technical approach & feasibility + ├─ Agent 3 (Validation): Risk analysis & edge cases + ├─ Agent 4 (Decision): Recommendations & tradeoffs + └─ Aggregate findings into perspectives.json + +Phase 2: Conflict Detection & Resolution + ├─ Analyze agent perspectives for contradictions + ├─ Identify critical decision points + ├─ Generate synthesis via arbitration agent + ├─ Document conflicts and resolutions + └─ Update plan.md with decisive recommendations + +Phase 3: Plan Synthesis + ├─ Consolidate all insights + ├─ Generate actionable task breakdown + ├─ Create execution strategy + ├─ Document assumptions & risks + └─ Generate synthesis.md with ready-to-execute tasks + +Output: + ├─ .workflow/.planning/{sessionId}/plan.md (minimal, actionable) + ├─ .workflow/.planning/{sessionId}/perspectives.json (agent findings) + ├─ .workflow/.planning/{sessionId}/conflicts.json (decision points) + ├─ .workflow/.planning/{sessionId}/synthesis.md (task breakdown) + └─ Optional: Feed to /workflow:unified-execute-with-file +``` + +## Implementation + +### Session Setup & Input Loading + +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +// Parse arguments +const planningTopic = "$PLANNING_TOPIC" +const inputType = $ARGUMENTS.match(/--from\s+(\w+)/)?.[1] || 'raw' +const isAutoMode = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y') +const isContinue = $ARGUMENTS.includes('--continue') || $ARGUMENTS.includes('-c') + +// Auto-detect artifact if referenced +let artifact = null +let artifactContent = null + +if (inputType === 'brainstorm' || planningTopic.startsWith('BS-')) { + const sessionId = planningTopic + const synthesisPath = `.workflow/.brainstorm/${sessionId}/synthesis.json` + if (fs.existsSync(synthesisPath)) { + artifact = { type: 'brainstorm', path: synthesisPath } + artifactContent = JSON.parse(Read(synthesisPath)) + } +} else if (inputType === 'analysis' || planningTopic.startsWith('ANL-')) { + const sessionId = planningTopic + const conclusionsPath = `.workflow/.analysis/${sessionId}/conclusions.json` + if (fs.existsSync(conclusionsPath)) { + artifact = { type: 'analysis', path: conclusionsPath } + artifactContent = JSON.parse(Read(conclusionsPath)) + } +} + +// Generate session ID +const planSlug = planningTopic.toLowerCase() + .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-') + .substring(0, 30) +const dateStr = getUtc8ISOString().substring(0, 10) +const sessionId = `PLAN-${planSlug}-${dateStr}` +const sessionFolder = `.workflow/.planning/${sessionId}` + +// Session mode detection +const sessionExists = fs.existsSync(sessionFolder) +const hasPlan = sessionExists && fs.existsSync(`${sessionFolder}/plan.md`) +const mode = (hasPlan || isContinue) ? 'continue' : 'new' + +if (!sessionExists) { + bash(`mkdir -p ${sessionFolder}`) +} +``` + +--- + +### Phase 1: Initialize plan.md (Minimal) + +```markdown +# Quick Planning Session + +**Session ID**: ${sessionId} +**Topic**: ${planningTopic} +**Started**: ${getUtc8ISOString()} +**Mode**: ${mode} + +--- + +## Input Context + +${artifact ? ` +**Source**: ${artifact.type} artifact +**Path**: ${artifact.path} + +**Artifact Summary**: +${artifact.type === 'brainstorm' ? ` +- Topic: ${artifactContent.topic} +- Top Ideas: ${artifactContent.top_ideas?.length || 0} +- Key Insights: ${artifactContent.key_insights?.slice(0, 2).join(', ') || 'N/A'} +` : artifact.type === 'analysis' ? ` +- Topic: ${artifactContent.topic} +- Key Conclusions: ${artifactContent.key_conclusions?.length || 0} +- Recommendations: ${artifactContent.recommendations?.length || 0} +` : ''} +` : ` +**User Input**: ${planningTopic} +`} + +--- + +## Planning Dimensions + +*To be populated after agent analysis* + +--- + +## Key Decisions + +*Conflict resolution and recommendations - to be populated* + +--- + +## Implementation Plan + +*Task breakdown - to be populated after synthesis* + +--- + +## Progress + +- [ ] Multi-agent analysis +- [ ] Conflict detection +- [ ] Plan synthesis +- [ ] Ready for execution +``` + +--- + +### Phase 2: Parallel Multi-Agent Analysis + +```javascript +const analysisPrompt = artifact + ? `Convert ${artifact.type} artifact to planning requirements and execute parallel analysis` + : `Create planning breakdown for: ${planningTopic}` + +// Prepare context for agents +const agentContext = { + topic: planningTopic, + artifact: artifact ? { + type: artifact.type, + summary: extractArtifactSummary(artifactContent) + } : null, + planning_focus: determineFocusAreas(planningTopic), + constraints: extractConstraints(planningTopic, artifactContent) +} + +// Agent 1: Architecture & Design +const archPromise = Bash({ + command: `ccw cli -p " +PURPOSE: Architecture & high-level design planning for '${planningTopic}' +Success: Clear component decomposition, interface design, and data flow + +TASK: +• Decompose problem into major components/modules +• Identify architectural patterns and integration points +• Design interfaces and data models +• Assess scalability and maintainability implications +• Propose architectural approach with rationale + +MODE: analysis + +CONTEXT: @**/* +${artifact ? `| Source artifact: ${artifact.type}` : ''} + +EXPECTED: +- Component decomposition (box diagram in text) +- Module interfaces and responsibilities +- Data flow between components +- Architectural patterns applied +- Scalability assessment (1-5 rating) +- Risks from architectural perspective + +CONSTRAINTS: Focus on long-term maintainability +" --tool gemini --mode analysis`, + run_in_background: true +}) + +// Agent 2: Implementation & Feasibility +const implPromise = Bash({ + command: `ccw cli -p " +PURPOSE: Implementation approach & technical feasibility for '${planningTopic}' +Success: Concrete implementation strategy with realistic resource estimates + +TASK: +• Evaluate technical feasibility of approach +• Identify required technologies and dependencies +• Estimate effort: high/medium/low + rationale +• Suggest implementation phases and milestones +• Highlight technical blockers or challenges + +MODE: analysis + +CONTEXT: @**/* +${artifact ? `| Source artifact: ${artifact.type}` : ''} + +EXPECTED: +- Technology stack recommendation +- Implementation complexity: high|medium|low with justification +- Estimated effort breakdown (analysis/design/coding/testing/deployment) +- Key technical decisions with tradeoffs +- Potential blockers and mitigations +- Suggested implementation phases +- Reusable components or libraries + +CONSTRAINTS: Realistic with current tech stack +" --tool codex --mode analysis`, + run_in_background: true +}) + +// Agent 3: Risk & Validation +const riskPromise = Bash({ + command: `ccw cli -p " +PURPOSE: Risk analysis and validation strategy for '${planningTopic}' +Success: Comprehensive risk matrix with testing strategy + +TASK: +• Identify technical risks and failure scenarios +• Assess business/timeline risks +• Define validation/testing strategy +• Suggest monitoring and observability requirements +• Rate overall risk level (low/medium/high) + +MODE: analysis + +CONTEXT: @**/* +${artifact ? `| Source artifact: ${artifact.type}` : ''} + +EXPECTED: +- Risk matrix (likelihood × impact, 1-5 each) +- Top 3 technical risks with mitigations +- Top 3 timeline/resource risks with mitigations +- Testing strategy (unit/integration/e2e/performance) +- Deployment strategy and rollback plan +- Monitoring/observability requirements +- Overall risk rating with confidence (low/medium/high) + +CONSTRAINTS: Be realistic, not pessimistic +" --tool claude --mode analysis`, + run_in_background: true +}) + +// Agent 4: Decisions & Recommendations +const decisionPromise = Bash({ + command: `ccw cli -p " +PURPOSE: Strategic decisions and execution recommendations for '${planningTopic}' +Success: Clear recommended approach with tradeoff analysis + +TASK: +• Synthesize all considerations into recommendations +• Clearly identify critical decision points +• Outline key tradeoffs (speed vs quality, scope vs timeline, etc.) +• Propose go/no-go decision criteria +• Suggest execution strategy and sequencing + +MODE: analysis + +CONTEXT: @**/* +${artifact ? `| Source artifact: ${artifact.type}` : ''} + +EXPECTED: +- Primary recommendation with strong rationale +- Alternative approaches with pros/cons +- 2-3 critical decision points with recommended choices +- Key tradeoffs and what we're optimizing for +- Success metrics and go/no-go criteria +- Suggested execution sequencing +- Resource requirements and dependencies + +CONSTRAINTS: Focus on actionable decisions, not analysis +" --tool gemini --mode analysis`, + run_in_background: true +}) + +// Wait for all parallel analyses +const [archResult, implResult, riskResult, decisionResult] = await Promise.all([ + archPromise, implPromise, riskPromise, decisionPromise +]) +``` + +--- + +### Phase 3: Aggregate Perspectives + +```javascript +// Parse and structure agent findings +const perspectives = { + session_id: sessionId, + timestamp: getUtc8ISOString(), + topic: planningTopic, + source_artifact: artifact?.type || 'raw', + + architecture: { + source: 'gemini (design)', + components: extractComponents(archResult), + interfaces: extractInterfaces(archResult), + patterns: extractPatterns(archResult), + scalability_rating: extractRating(archResult, 'scalability'), + risks_from_design: extractRisks(archResult) + }, + + implementation: { + source: 'codex (pragmatic)', + technology_stack: extractStack(implResult), + complexity: extractComplexity(implResult), + effort_breakdown: extractEffort(implResult), + blockers: extractBlockers(implResult), + phases: extractPhases(implResult) + }, + + validation: { + source: 'claude (systematic)', + risk_matrix: extractRiskMatrix(riskResult), + top_risks: extractTopRisks(riskResult), + testing_strategy: extractTestingStrategy(riskResult), + deployment_strategy: extractDeploymentStrategy(riskResult), + monitoring_requirements: extractMonitoring(riskResult), + overall_risk_rating: extractRiskRating(riskResult) + }, + + recommendation: { + source: 'gemini (synthesis)', + primary_approach: extractPrimaryApproach(decisionResult), + alternatives: extractAlternatives(decisionResult), + critical_decisions: extractDecisions(decisionResult), + tradeoffs: extractTradeoffs(decisionResult), + success_criteria: extractCriteria(decisionResult), + execution_sequence: extractSequence(decisionResult) + }, + + analysis_timestamp: getUtc8ISOString() +} + +Write(`${sessionFolder}/perspectives.json`, JSON.stringify(perspectives, null, 2)) +``` + +--- + +### Phase 4: Conflict Detection & Resolution + +```javascript +// Analyze for conflicts and contradictions +const conflicts = detectConflicts({ + arch_vs_impl: compareArchitectureAndImplementation(perspectives), + design_vs_risk: compareDesignAndRisk(perspectives), + effort_vs_scope: compareEffortAndScope(perspectives), + timeline_implications: extractTimingConflicts(perspectives) +}) + +// If conflicts exist, invoke arbitration agent +if (conflicts.critical.length > 0) { + const arbitrationResult = await Bash({ + command: `ccw cli -p " +PURPOSE: Resolve planning conflicts and generate unified recommendation +Input: ${JSON.stringify(conflicts, null, 2)} + +TASK: +• Review all conflicts presented +• Recommend resolution for each critical conflict +• Explain tradeoff choices +• Identify what we're optimizing for (speed/quality/risk/resource) +• Generate unified execution strategy + +MODE: analysis + +EXPECTED: +- For each conflict: recommended resolution + rationale +- Unified optimization criteria (what matters most?) +- Final recommendation with confidence level +- Any unresolved tensions that need user input + +CONSTRAINTS: Be decisive, not fence-sitting +" --tool gemini --mode analysis`, + run_in_background: false + }) + + const conflictResolution = { + detected_conflicts: conflicts, + arbitration_result: arbitrationResult, + timestamp: getUtc8ISOString() + } + + Write(`${sessionFolder}/conflicts.json`, JSON.stringify(conflictResolution, null, 2)) +} +``` + +--- + +### Phase 5: Plan Synthesis & Task Breakdown + +```javascript +const synthesisPrompt = ` +Given the planning context: +- Topic: ${planningTopic} +- Architecture: ${perspectives.architecture.components.map(c => c.name).join(', ')} +- Implementation Complexity: ${perspectives.implementation.complexity} +- Timeline Risk: ${perspectives.validation.overall_risk_rating} +- Primary Recommendation: ${perspectives.recommendation.primary_approach.summary} + +Generate a minimal but complete implementation plan with: +1. Task breakdown (5-8 major tasks) +2. Dependencies between tasks +3. For each task: what needs to be done, why, and key considerations +4. Success criteria for the entire effort +5. Known risks and mitigation strategies + +Output as structured task list ready for execution. +` + +const synthesisResult = await Bash({ + command: `ccw cli -p "${synthesisPrompt}" --tool gemini --mode analysis`, + run_in_background: false +}) + +// Parse synthesis and generate task breakdown +const tasks = parseTaskBreakdown(synthesisResult) + +const synthesis = { + session_id: sessionId, + planning_topic: planningTopic, + completed: getUtc8ISOString(), + + // Summary + executive_summary: perspectives.recommendation.primary_approach.summary, + optimization_focus: extractOptimizationFocus(perspectives), + + // Architecture + architecture_approach: perspectives.architecture.patterns[0] || 'TBD', + key_components: perspectives.architecture.components.slice(0, 5), + + // Implementation + technology_stack: perspectives.implementation.technology_stack, + complexity_level: perspectives.implementation.complexity, + estimated_effort: perspectives.implementation.effort_breakdown, + + // Risks & Validation + top_risks: perspectives.validation.top_risks.slice(0, 3), + testing_approach: perspectives.validation.testing_strategy, + + // Execution + phases: perspectives.implementation.phases, + critical_path_tasks: extractCriticalPath(tasks), + total_tasks: tasks.length, + + // Task breakdown (ready for unified-execute-with-file) + tasks: tasks.map(task => ({ + id: task.id, + title: task.title, + description: task.description, + type: task.type, + dependencies: task.dependencies, + effort_estimate: task.effort, + success_criteria: task.criteria + })) +} + +Write(`${sessionFolder}/synthesis.md`, formatSynthesisMarkdown(synthesis)) +Write(`${sessionFolder}/synthesis.json`, JSON.stringify(synthesis, null, 2)) +``` + +--- + +### Phase 6: Update plan.md with Results + +```markdown +# Quick Planning Session + +**Session ID**: ${sessionId} +**Topic**: ${planningTopic} +**Started**: ${startTime} +**Completed**: ${completionTime} + +--- + +## Executive Summary + +${synthesis.executive_summary} + +**Optimization Focus**: ${synthesis.optimization_focus} +**Complexity**: ${synthesis.complexity_level} +**Estimated Effort**: ${formatEffort(synthesis.estimated_effort)} + +--- + +## Architecture + +**Primary Pattern**: ${synthesis.architecture_approach} + +**Key Components**: +${synthesis.key_components.map((c, i) => `${i+1}. ${c.name}: ${c.responsibility}`).join('\n')} + +--- + +## Implementation Strategy + +**Technology Stack**: +${synthesis.technology_stack.map(t => `- ${t}`).join('\n')} + +**Phases**: +${synthesis.phases.map((p, i) => `${i+1}. ${p.name} (${p.effort})`).join('\n')} + +--- + +## Risk Assessment + +**Overall Risk Level**: ${synthesis.top_risks[0].risk_level} + +**Top 3 Risks**: +${synthesis.top_risks.map((r, i) => ` +${i+1}. **${r.title}** (Impact: ${r.impact}) + - Mitigation: ${r.mitigation} +`).join('\n')} + +**Testing Approach**: ${synthesis.testing_approach} + +--- + +## Execution Plan + +**Total Tasks**: ${synthesis.total_tasks} +**Critical Path**: ${synthesis.critical_path_tasks.map(t => t.id).join(' → ')} + +### Task Breakdown + +${synthesis.tasks.map((task, i) => ` +${i+1}. **${task.id}: ${task.title}** (Effort: ${task.effort_estimate}) + - ${task.description} + - Depends on: ${task.dependencies.join(', ') || 'none'} + - Success: ${task.success_criteria} +`).join('\n')} + +--- + +## Next Steps + +**Recommended**: Execute with \`/workflow:unified-execute-with-file\` using: +\`\`\` +/workflow:unified-execute-with-file -p ${sessionFolder}/synthesis.json +\`\`\` + +--- + +## Artifacts + +- **Perspectives**: ${sessionFolder}/perspectives.json (all agent findings) +- **Conflicts**: ${sessionFolder}/conflicts.json (decision points and resolutions) +- **Synthesis**: ${sessionFolder}/synthesis.json (task breakdown for execution) +``` + +--- + +## Session Folder Structure + +``` +.workflow/.planning/{sessionId}/ +├── plan.md # Minimal, actionable planning doc +├── perspectives.json # Multi-agent findings (architecture, impl, risk, decision) +├── conflicts.json # Detected conflicts and resolutions (if any) +├── synthesis.json # Task breakdown ready for execution +└── synthesis.md # Human-readable execution plan +``` + +--- + +## Multi-Agent Roles + +| Agent | Focus | Input | Output | +|-------|-------|-------|--------| +| **Gemini (Design)** | Architecture & design patterns | Topic + constraints | Components, interfaces, patterns, scalability | +| **Codex (Pragmatic)** | Implementation reality | Topic + architecture | Tech stack, effort, phases, blockers | +| **Claude (Validation)** | Risk & testing | Architecture + impl | Risk matrix, test strategy, monitoring | +| **Gemini (Decision)** | Synthesis & strategy | All findings | Recommendations, tradeoffs, execution plan | + +--- + +## Conflict Resolution Strategy + +**Auto-Resolution for conflicts**: +1. **Architecture vs Implementation**: Recommend design-for-feasibility approach +2. **Scope vs Timeline**: Prioritize critical path, defer nice-to-haves +3. **Quality vs Speed**: Suggest iterative approach (MVP + iterations) +4. **Resource vs Effort**: Identify parallelizable tasks + +**Require User Input for**: +- Strategic choices (which feature to prioritize?) +- Tool/technology decisions with strong team preferences +- Budget/resource constraints not stated in planning topic + +--- + +## Continue & Resume + +```bash +/workflow:quick-plan-with-file --continue "planning-topic" +``` + +When continuing: +1. Load existing plan.md and perspectives.json +2. Identify what's incomplete +3. Re-run affected agents (if planning has changed) +4. Update plan.md with new findings +5. Generate updated synthesis.json + +--- + +## Integration Flow + +``` +Input Source: + ├─ Raw task description + ├─ Brainstorm synthesis.json + └─ Analysis conclusions.json + ↓ +/workflow:quick-plan-with-file + ↓ +plan.md + synthesis.json + ↓ +/workflow:unified-execute-with-file + ↓ +Implementation +``` + +--- + +## Usage Patterns + +### Pattern 1: Quick Planning from Task + +```bash +# User has a task, needs rapid multi-perspective plan +/workflow:quick-plan-with-file -y "实现实时通知系统，支持推送和WebSocket" +# → Creates plan in ~5 minutes +# → Ready for execution +``` + +### Pattern 2: Convert Brainstorm to Executable Plan + +```bash +# User completed brainstorm, wants to convert top idea to executable plan +/workflow:quick-plan-with-file --from brainstorm BS-notifications-2025-01-28 +# → Reads synthesis.json from brainstorm +# → Generates implementation plan +# → Ready for unified-execute-with-file +``` + +### Pattern 3: From Analysis to Implementation + +```bash +# Analysis completed, now need execution plan +/workflow:quick-plan-with-file --from analysis ANL-auth-architecture-2025-01-28 +# → Reads conclusions.json from analysis +# → Generates planning with recommendations +# → Output task breakdown +``` + +### Pattern 4: Planning with Interactive Conflict Resolution + +```bash +# Full planning with user involvement in decision-making +/workflow:quick-plan-with-file "新的支付流程集成" +# → Without -y flag +# → After conflict detection, asks user about tradeoffs +# → Generates plan based on user preferences +``` + +--- + +## Comparison with Other Workflows + +| Feature | brainstorm | analyze | quick-plan | plan | +|---------|-----------|---------|-----------|------| +| **Purpose** | Ideation | Investigation | Lightweight planning | Detailed planning | +| **Multi-agent** | 3 perspectives | 2 CLI + explore | 4 concurrent agents | N/A (single) | +| **Documentation** | Extensive | Extensive | Minimal | Standard | +| **Output** | Ideas + synthesis | Conclusions | Executable tasks | IMPL_PLAN | +| **Typical Duration** | 30-60 min | 20-30 min | 5-10 min | 15-20 min | +| **User Interaction** | High (multi-round) | High (Q&A) | Low (decisions) | Medium | + +--- + +## Error Handling + +| Situation | Action | +|-----------|--------| +| Agents conflict on approach | Arbitration agent decides, document in conflicts.json | +| Missing critical files | Continue with available context, note limitations | +| Insufficient task breakdown | Ask user for planning focus areas | +| Effort estimate too high | Suggest MVP approach or phasing | +| Unclear requirements | Ask clarifying questions via AskUserQuestion | +| Agent timeout | Use last successful result, note partial analysis | + +--- + +## Best Practices + +1. **Use when**: + - You have clarity on WHAT but not HOW + - Need rapid multi-perspective planning + - Converting brainstorm/analysis into execution + - Want minimal planning overhead + +2. **Avoid when**: + - Requirements are highly ambiguous (use brainstorm instead) + - Need deep investigation (use analyze instead) + - Want extensive planning document (use plan instead) + - No tech stack clarity (use analyze first) + +3. **For best results**: + - Provide complete task/requirement description + - Include constraints and success criteria + - Specify preferences (speed vs quality vs risk) + - Review conflicts.json and make conscious tradeoff decisions + +--- + +## Next Steps After Planning + +### Feed to Execution +```bash +/workflow:unified-execute-with-file -p .workflow/.planning/{sessionId}/synthesis.json +``` + +### Detailed Planning if Needed +```bash +/workflow:plan "Based on quick-plan recommendations..." +``` + +### Continuous Refinement +```bash +/workflow:quick-plan-with-file --continue "{topic}" # Update plan with new constraints +``` diff --git a/.codex/prompts/brainstorm-with-file.md b/.codex/prompts/brainstorm-with-file.md index e572f08c..7c93e312 100644 --- a/.codex/prompts/brainstorm-with-file.md +++ b/.codex/prompts/brainstorm-with-file.md @@ -231,53 +231,97 @@ ${newFocusFromUser} ### Phase 2: Divergent Exploration (Multi-Perspective) -#### Step 2.1: Creative Perspective Analysis +Launch 3 parallel agents for multi-perspective brainstorming: -Explore from creative/innovative angle: +```javascript +const cliPromises = [] -- Think beyond obvious solutions - what would be surprising/delightful? -- Cross-domain inspiration (what can we learn from other industries?) -- Challenge assumptions - what if the opposite were true? -- Generate 'moonshot' ideas alongside practical ones -- Consider future trends and emerging technologies +// Agent 1: Creative/Innovative Perspective (Gemini) +cliPromises.push( + Bash({ + command: `ccw cli -p " +PURPOSE: Creative brainstorming for '$TOPIC' - generate innovative, unconventional ideas +Success: 5+ unique creative solutions that push boundaries -Output: +TASK: +• Think beyond obvious solutions - what would be surprising/delightful? +• Explore cross-domain inspiration (what can we learn from other industries?) +• Challenge assumptions - what if the opposite were true? +• Generate 'moonshot' ideas alongside practical ones +• Consider future trends and emerging technologies + +MODE: analysis + +CONTEXT: @**/* | Topic: $TOPIC +Exploration vectors: ${explorationVectors.map(v => v.title).join(', ')} + +EXPECTED: - 5+ creative ideas with brief descriptions - Each idea rated: novelty (1-5), potential impact (1-5) - Key assumptions challenged - Cross-domain inspirations - One 'crazy' idea that might just work -#### Step 2.2: Pragmatic Perspective Analysis +CONSTRAINTS: ${brainstormMode === 'structured' ? 'Keep ideas technically feasible' : 'No constraints - think freely'} +" --tool gemini --mode analysis`, + run_in_background: true + }) +) -Evaluate from implementation reality: +// Agent 2: Pragmatic/Implementation Perspective (Codex) +cliPromises.push( + Bash({ + command: \`ccw cli -p " +PURPOSE: Pragmatic analysis for '$TOPIC' - focus on implementation reality +Success: Actionable approaches with clear implementation paths -- Technical feasibility of core concept -- Existing patterns/libraries that could help -- Integration with current codebase -- Implementation complexity estimates -- Potential technical blockers -- Incremental implementation approach +TASK: +• Evaluate technical feasibility of core concept +• Identify existing patterns/libraries that could help +• Consider integration with current codebase +• Estimate implementation complexity +• Highlight potential technical blockers +• Suggest incremental implementation approach -Output: +MODE: analysis + +CONTEXT: @**/* | Topic: $TOPIC +Exploration vectors: \${explorationVectors.map(v => v.title).join(', ')} + +EXPECTED: - 3-5 practical implementation approaches - Each rated: effort (1-5), risk (1-5), reuse potential (1-5) - Technical dependencies identified - Quick wins vs long-term solutions - Recommended starting point -#### Step 2.3: Systematic Perspective Analysis +CONSTRAINTS: Focus on what can actually be built with current tech stack +" --tool codex --mode analysis\`, + run_in_background: true + }) +) -Analyze from architectural standpoint: +// Agent 3: Systematic/Architectural Perspective (Claude) +cliPromises.push( + Bash({ + command: \`ccw cli -p " +PURPOSE: Systematic analysis for '$TOPIC' - architectural and structural thinking +Success: Well-structured solution framework with clear tradeoffs -- Decompose the problem into sub-problems -- Identify architectural patterns that apply -- Map dependencies and interactions -- Consider scalability implications -- Evaluate long-term maintainability -- Propose systematic solution structure +TASK: +• Decompose the problem into sub-problems +• Identify architectural patterns that apply +• Map dependencies and interactions +• Consider scalability implications +• Evaluate long-term maintainability +• Propose systematic solution structure -Output: +MODE: analysis + +CONTEXT: @**/* | Topic: $TOPIC +Exploration vectors: \${explorationVectors.map(v => v.title).join(', ')} + +EXPECTED: - Problem decomposition diagram (text) - 2-3 architectural approaches with tradeoffs - Dependency mapping @@ -285,6 +329,29 @@ Output: - Recommended architecture pattern - Risk matrix +CONSTRAINTS: Consider existing system architecture +" --tool claude --mode analysis\`, + run_in_background: true + }) +) + +// Wait for all CLI analyses to complete +const [creativeResult, pragmaticResult, systematicResult] = await Promise.all(cliPromises) + +// Parse results from each perspective +const creativeIdeas = parseCreativeResult(creativeResult) +const pragmaticApproaches = parsePragmaticResult(pragmaticResult) +const architecturalOptions = parseSystematicResult(systematicResult) +``` + +**Multi-Perspective Coordination**: + +| Agent | Perspective | Tool | Focus Areas | +|-------|-------------|------|-------------| +| 1 | Creative/Innovative | Gemini | Novel ideas, cross-domain inspiration, moonshots | +| 2 | Pragmatic/Implementation | Codex | Feasibility, tech stack, blockers, quick wins | +| 3 | Systematic/Architectural | Claude | Decomposition, patterns, scalability, risks | + #### Step 2.4: Aggregate Multi-Perspective Findings ```javascript diff --git a/.codex/prompts/merge-plans-with-file.md b/.codex/prompts/merge-plans-with-file.md new file mode 100644 index 00000000..4d70fc49 --- /dev/null +++ b/.codex/prompts/merge-plans-with-file.md @@ -0,0 +1,530 @@ +--- +description: Merge multiple planning/brainstorm/analysis outputs, resolve conflicts, and synthesize unified plan. Multi-team input aggregation and plan crystallization +argument-hint: "PATTERN=\"\" [--rule=consensus|priority|hierarchy] [--output=] [--auto] [--verbose]" +--- + +# Codex Merge-Plans-With-File Prompt + +## Overview + +Plan aggregation and conflict resolution workflow. Takes multiple planning artifacts (brainstorm conclusions, analysis recommendations, quick-plans, implementation plans) and synthesizes them into a unified, conflict-resolved execution plan. + +**Core workflow**: Load Sources → Parse Plans → Conflict Analysis → Arbitration → Unified Plan + +**Key features**: +- **Multi-Source Support**: brainstorm, analysis, quick-plan, IMPL_PLAN, task JSONs +- **Conflict Detection**: Identify contradictions across all input plans +- **Resolution Rules**: consensus, priority-based, or hierarchical resolution +- **Unified Synthesis**: Single authoritative plan from multiple perspectives +- **Decision Tracking**: Full audit trail of conflicts and resolutions + +## Target Pattern + +**$PATTERN** + +- `--rule`: Conflict resolution (consensus | priority | hierarchy) - consensus by default +- `--output`: Output directory (default: .workflow/.merged/{pattern}) +- `--auto`: Auto-resolve conflicts using rule, skip confirmations +- `--verbose`: Include detailed conflict analysis + +## Execution Process + +``` +Phase 1: Discovery & Loading + ├─ Search for artifacts matching pattern + ├─ Load synthesis.json, conclusions.json, IMPL_PLAN.md, task JSONs + ├─ Parse into normalized task structure + └─ Validate completeness + +Phase 2: Plan Normalization + ├─ Convert all formats to common task representation + ├─ Extract: tasks, dependencies, effort, risks + ├─ Identify scope and boundaries + └─ Aggregate recommendations + +Phase 3: Conflict Detection (Parallel) + ├─ Architecture conflicts: different design approaches + ├─ Task conflicts: overlapping or duplicated tasks + ├─ Effort conflicts: different estimates + ├─ Risk conflicts: different risk assessments + ├─ Scope conflicts: different feature sets + └─ Generate conflict matrix + +Phase 4: Conflict Resolution + ├─ Analyze source rationale for each conflict + ├─ Apply resolution rule (consensus / priority / hierarchy) + ├─ Escalate unresolvable conflicts to user (unless --auto) + ├─ Document decision rationale + └─ Generate resolutions.json + +Phase 5: Plan Synthesis + ├─ Merge task lists (deduplicate, combine insights) + ├─ Integrate dependencies + ├─ Consolidate effort and risk estimates + ├─ Generate execution sequence + └─ Output unified-plan.json + +Output: + ├─ .workflow/.merged/{sessionId}/merge.md (process log) + ├─ .workflow/.merged/{sessionId}/source-index.json (input sources) + ├─ .workflow/.merged/{sessionId}/conflicts.json (conflict matrix) + ├─ .workflow/.merged/{sessionId}/resolutions.json (decisions) + ├─ .workflow/.merged/{sessionId}/unified-plan.json (for execution) + └─ .workflow/.merged/{sessionId}/unified-plan.md (human-readable) +``` + +## Implementation Details + +### Phase 1: Discover & Load Sources + +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +const mergeSlug = "$PATTERN".toLowerCase() + .replace(/[*?]/g, '-') + .replace(/[^a-z0-9\u4e00-\u9fa5-]+/g, '-') + .substring(0, 30) +const sessionId = `MERGE-${mergeSlug}-${getUtc8ISOString().substring(0, 10)}` +const sessionFolder = `.workflow/.merged/${sessionId}` + +bash(`mkdir -p ${sessionFolder}`) + +// Search paths for matching artifacts +const searchPaths = [ + `.workflow/.brainstorm/*${$PATTERN}*/synthesis.json`, + `.workflow/.analysis/*${$PATTERN}*/conclusions.json`, + `.workflow/.planning/*${$PATTERN}*/synthesis.json`, + `.workflow/.plan/*${$PATTERN}*IMPL_PLAN.md`, + `.workflow/**/*${$PATTERN}*.json` +] + +// Load and validate each source +const sourcePlans = [] +for (const pattern of searchPaths) { + const matches = glob(pattern) + for (const path of matches) { + const plan = loadAndParsePlan(path) + if (plan?.tasks?.length > 0) { + sourcePlans.push({ path, type: inferType(path), plan }) + } + } +} +``` + +### Phase 2: Normalize Plans + +Convert all source formats to common structure: + +```javascript +const normalizedPlans = sourcePlans.map((src, idx) => ({ + index: idx, + source: src.path, + type: src.type, + + metadata: { + title: src.plan.title || `Plan ${idx + 1}`, + topic: src.plan.topic, + complexity: src.plan.complexity_level || 'unknown' + }, + + tasks: src.plan.tasks.map(task => ({ + id: `T${idx}-${task.id || task.title.substring(0, 20)}`, + title: task.title, + description: task.description, + type: task.type || inferTaskType(task), + priority: task.priority || 'normal', + + effort: { estimated: task.effort_estimate, from_plan: idx }, + risk: { level: task.risk_level || 'medium', from_plan: idx }, + dependencies: task.dependencies || [], + + source_plan_index: idx + })) +})) +``` + +### Phase 3: Parallel Conflict Detection + +Launch parallel agents to detect and analyze conflicts: + +```javascript +// Parallel conflict detection with CLI agents +const conflictPromises = [] + +// Agent 1: Detect effort and task conflicts +conflictPromises.push( + Bash({ + command: `ccw cli -p " +PURPOSE: Detect effort conflicts and task duplicates across multiple plans +Success: Complete identification of conflicting estimates and duplicate tasks + +TASK: +• Identify tasks with significantly different effort estimates (>50% variance) +• Detect duplicate/similar tasks across plans +• Analyze effort estimation reasoning +• Suggest resolution for each conflict + +MODE: analysis + +CONTEXT: +- Plan 1: ${JSON.stringify(normalizedPlans[0]?.tasks?.slice(0,3) || [], null, 2)} +- Plan 2: ${JSON.stringify(normalizedPlans[1]?.tasks?.slice(0,3) || [], null, 2)} +- [Additional plans...] + +EXPECTED: +- Effort conflicts detected (task name, estimate in each plan, variance %) +- Duplicate task analysis (similar tasks, scope differences) +- Resolution recommendation for each conflict +- Confidence level for each detection + +CONSTRAINTS: Focus on significant conflicts (>30% effort variance) +" --tool gemini --mode analysis`, + run_in_background: true + }) +) + +// Agent 2: Analyze architecture and scope conflicts +conflictPromises.push( + Bash({ + command: \`ccw cli -p " +PURPOSE: Analyze architecture and scope conflicts across plans +Success: Clear identification of design approach differences and scope gaps + +TASK: +• Identify different architectural approaches in plans +• Detect scope differences (features included/excluded) +• Analyze design philosophy conflicts +• Suggest approach to reconcile different visions + +MODE: analysis + +CONTEXT: +- Plan 1 architecture: \${normalizedPlans[0]?.metadata?.complexity || 'unknown'} +- Plan 2 architecture: \${normalizedPlans[1]?.metadata?.complexity || 'unknown'} +- Different design approaches detected: \${JSON.stringify(['approach1', 'approach2'])} + +EXPECTED: +- Architecture conflicts identified (approach names and trade-offs) +- Scope conflicts (features/components in plan A but not B, vice versa) +- Design philosophy alignment/misalignment +- Recommendation for unified approach +- Pros/cons of each architectural approach + +CONSTRAINTS: Consider both perspectives objectively +" --tool codex --mode analysis\`, + run_in_background: true + }) +) + +// Agent 3: Analyze risk assessment conflicts +conflictPromises.push( + Bash({ + command: \`ccw cli -p " +PURPOSE: Analyze risk assessment conflicts across plans +Success: Unified risk assessment with conflict resolution + +TASK: +• Identify tasks/areas with significantly different risk ratings +• Analyze risk assessment reasoning +• Detect missing risks in some plans +• Propose unified risk assessment + +MODE: analysis + +CONTEXT: +- Risk areas with disagreement: [list areas] +- Plan 1 risk ratings: [risk matrix] +- Plan 2 risk ratings: [risk matrix] + +EXPECTED: +- Risk conflicts identified (area, plan A rating, plan B rating) +- Explanation of why assessments differ +- Missing risks analysis (important in one plan but not others) +- Unified risk rating recommendation +- Confidence level for each assessment + +CONSTRAINTS: Be realistic in risk assessment, not pessimistic +" --tool claude --mode analysis\`, + run_in_background: true + }) +) + +// Agent 4: Synthesize conflicts into resolution strategy +conflictPromises.push( + Bash({ + command: \`ccw cli -p " +PURPOSE: Synthesize all conflicts into unified resolution strategy +Success: Clear path to merge plans with informed trade-off decisions + +TASK: +• Analyze all detected conflicts holistically +• Identify which conflicts are critical vs. non-critical +• Propose resolution for each conflict type +• Suggest unified approach that honors valid insights from all plans + +MODE: analysis + +CONTEXT: +- Total conflicts detected: [number] +- Conflict types: effort, architecture, scope, risk +- Resolution rule: \${resolutionRule} +- Plan importance: \${normalizedPlans.map(p => p.metadata.title).join(', ')} + +EXPECTED: +- Conflict priority ranking (critical, important, minor) +- Recommended resolution for each conflict +- Rationale for each recommendation +- Potential issues with proposed resolution +- Fallback options if recommendation not accepted +- Overall merge strategy and sequencing + +CONSTRAINTS: Aim for solution that maximizes learning from all perspectives +" --tool gemini --mode analysis\`, + run_in_background: true + }) +) + +// Wait for all conflict detection agents to complete +const [effortConflicts, archConflicts, riskConflicts, resolutionStrategy] = + await Promise.all(conflictPromises) + +// Parse and consolidate all conflict findings +const allConflicts = { + effort: parseEffortConflicts(effortConflicts), + architecture: parseArchConflicts(archConflicts), + risk: parseRiskConflicts(riskConflicts), + strategy: parseResolutionStrategy(resolutionStrategy), + timestamp: getUtc8ISOString() +} + +Write(\`\${sessionFolder}/conflicts.json\`, JSON.stringify(allConflicts, null, 2)) +``` + +**Conflict Detection Workflow**: + +| Agent | Conflict Type | Focus | Output | +|-------|--------------|--------|--------| +| Gemini | Effort & Tasks | Duplicate detection, estimate variance | Conflicts with variance %, resolution suggestions | +| Codex | Architecture & Scope | Design approach differences | Design conflicts, scope gaps, recommendations | +| Claude | Risk Assessment | Risk rating disagreements | Risk conflicts, missing risks, unified assessment | +| Gemini | Resolution Strategy | Holistic synthesis | Priority ranking, resolution path, trade-offs | + +### Phase 4: Resolve Conflicts + +**Rule: Consensus (default)** +- Use median/average of conflicting estimates +- Merge scope differences +- Document minority viewpoints + +**Rule: Priority** +- First plan has highest authority +- Later plans supplement but don't override + +**Rule: Hierarchy** +- User ranks plan importance +- Higher-ranked plan wins conflicts + +```javascript +const resolutions = {} + +if (rule === 'consensus') { + for (const conflict of conflicts.effort) { + resolutions[conflict.task] = { + resolved: calculateMedian(conflict.estimates), + method: 'consensus-median', + rationale: 'Used median of all estimates' + } + } +} else if (rule === 'priority') { + for (const conflict of conflicts.effort) { + const primary = conflict.estimates[0] // First plan + resolutions[conflict.task] = { + resolved: primary.value, + method: 'priority-based', + rationale: `Selected from plan ${primary.from_plan} (highest priority)` + } + } +} else if (rule === 'hierarchy') { + // Request user ranking if not --auto + const ranking = getUserPlanRanking(normalizedPlans) + // Apply hierarchy-based resolution +} + +Write(`${sessionFolder}/resolutions.json`, JSON.stringify(resolutions, null, 2)) +``` + +### Phase 5: Generate Unified Plan + +```javascript +const unifiedPlan = { + session_id: sessionId, + merge_timestamp: getUtc8ISOString(), + + summary: { + total_source_plans: sourcePlans.length, + original_tasks: allTasks.length, + merged_tasks: deduplicatedTasks.length, + conflicts_resolved: Object.keys(resolutions).length, + resolution_rule: rule + }, + + tasks: deduplicatedTasks.map(task => ({ + id: task.id, + title: task.title, + description: task.description, + effort: task.resolved_effort, + risk: task.resolved_risk, + dependencies: task.merged_dependencies, + source_plans: task.contributing_plans + })), + + execution_sequence: topologicalSort(tasks), + critical_path: identifyCriticalPath(tasks), + + risks: aggregateRisks(tasks), + success_criteria: aggregateCriteria(tasks) +} + +Write(`${sessionFolder}/unified-plan.json`, JSON.stringify(unifiedPlan, null, 2)) +``` + +### Phase 6: Generate Human-Readable Plan + +```markdown +# Merged Planning Session + +**Session ID**: ${sessionId} +**Pattern**: $PATTERN +**Created**: ${timestamp} + +--- + +## Merge Summary + +**Source Plans**: ${summary.total_source_plans} +**Original Tasks**: ${summary.original_tasks} +**Merged Tasks**: ${summary.merged_tasks} +**Conflicts Resolved**: ${summary.conflicts_resolved} +**Resolution Method**: ${summary.resolution_rule} + +--- + +## Unified Task List + +${tasks.map((task, i) => ` +${i+1}. **${task.id}: ${task.title}** + - Effort: ${task.effort} + - Risk: ${task.risk} + - From plans: ${task.source_plans.join(', ')} +`).join('\n')} + +--- + +## Execution Sequence + +**Critical Path**: ${critical_path.join(' → ')} + +--- + +## Conflict Resolution Report + +${Object.entries(resolutions).map(([key, res]) => ` +- **${key}**: ${res.rationale} +`).join('\n')} + +--- + +## Next Steps + +**Execute**: +\`\`\` +/workflow:unified-execute-with-file -p ${sessionFolder}/unified-plan.json +\`\`\` +``` + +## Session Folder Structure + +``` +.workflow/.merged/{sessionId}/ +├── merge.md # Process log +├── source-index.json # All input sources +├── conflicts.json # Detected conflicts +├── resolutions.json # How resolved +├── unified-plan.json # Merged plan (for execution) +└── unified-plan.md # Human-readable +``` + +## Resolution Rules Comparison + +| Rule | Method | Best For | Tradeoff | +|------|--------|----------|----------| +| **Consensus** | Median/average | Similar-quality inputs | May miss extremes | +| **Priority** | First wins | Clear authority order | Discards alternatives | +| **Hierarchy** | User-ranked | Mixed stakeholders | Needs user input | + +## Input Format Support + +| Source Type | Detection Pattern | Parsing | +|-------------|-------------------|---------| +| Brainstorm | `.brainstorm/*/synthesis.json` | Top ideas → tasks | +| Analysis | `.analysis/*/conclusions.json` | Recommendations → tasks | +| Quick-Plan | `.planning/*/synthesis.json` | Direct task list | +| IMPL_PLAN | `*IMPL_PLAN.md` | Markdown → tasks | +| Task JSON | `*.json` with `tasks` | Direct mapping | + +## Error Handling + +| Situation | Action | +|-----------|--------| +| No plans found | List available plans, suggest search terms | +| Incompatible format | Skip, continue with others | +| Circular dependencies | Alert user, suggest manual review | +| Unresolvable conflict | Require user decision (unless --auto) | + +## Integration Flow + +``` +Brainstorm Sessions / Analyses / Plans + │ + ├─ synthesis.json (session 1) + ├─ conclusions.json (session 2) + ├─ synthesis.json (session 3) + │ + ▼ +merge-plans-with-file + │ + ├─ unified-plan.json + │ + ▼ +unified-execute-with-file + │ + ▼ +Implementation +``` + +## Usage Patterns + +**Pattern 1: Merge all auth-related plans** +``` +PATTERN="authentication" --rule=consensus --auto +→ Finds all auth plans +→ Merges with consensus method +``` + +**Pattern 2: Prioritized merge** +``` +PATTERN="payment" --rule=priority +→ First plan has authority +→ Others supplement +``` + +**Pattern 3: Team input merge** +``` +PATTERN="feature-*" --rule=hierarchy +→ Asks for plan ranking +→ Applies hierarchy resolution +``` + +--- + +**Now execute merge-plans-with-file for pattern**: $PATTERN diff --git a/.codex/prompts/quick-plan-with-file.md b/.codex/prompts/quick-plan-with-file.md new file mode 100644 index 00000000..4f4bc045 --- /dev/null +++ b/.codex/prompts/quick-plan-with-file.md @@ -0,0 +1,450 @@ +--- +description: Multi-agent rapid planning with minimal documentation, conflict resolution, and actionable synthesis. Lightweight planning from raw task, brainstorm, or analysis artifacts +argument-hint: "TOPIC=\"\" [--from=brainstorm|analysis|task|raw] [--perspectives=arch,impl,risk,decision] [--auto] [--verbose]" +--- + +# Codex Quick-Plan-With-File Prompt + +## Overview + +Multi-agent rapid planning workflow with **minimal documentation overhead**. Coordinates parallel agent analysis (architecture, implementation, validation, decision), synthesizes conflicting perspectives into actionable decisions, and generates an implementation-ready plan. + +**Core workflow**: Parse Input → Parallel Analysis → Conflict Resolution → Plan Synthesis → Output + +**Key features**: +- **Format Agnostic**: Consumes brainstorm conclusions, analysis recommendations, quick tasks, or raw descriptions +- **Minimal Docs**: Single plan.md (no lengthy timeline documentation) +- **Parallel Multi-Agent**: 4 concurrent perspectives for rapid analysis +- **Conflict Resolution**: Automatic conflict detection and synthesis +- **Actionable Output**: Direct task breakdown ready for execution + +## Target Planning + +**$TOPIC** + +- `--from`: Input source type (brainstorm | analysis | task | raw) - auto-detected if omitted +- `--perspectives`: Which perspectives to use (arch, impl, risk, decision) - all by default +- `--auto`: Auto-confirm decisions, minimal user prompts +- `--verbose`: Verbose output with all reasoning + +## Execution Process + +``` +Phase 1: Input Validation & Loading + ├─ Parse input: topic | artifact reference + ├─ Load artifact if referenced (synthesis.json | conclusions.json) + ├─ Extract constraints and key requirements + └─ Initialize session folder + +Phase 2: Parallel Multi-Agent Analysis (concurrent) + ├─ Agent 1 (Architecture): Design decomposition, patterns, scalability + ├─ Agent 2 (Implementation): Tech stack, feasibility, effort estimates + ├─ Agent 3 (Validation): Risk matrix, testing strategy, monitoring + ├─ Agent 4 (Decision): Recommendations, tradeoffs, execution strategy + └─ Aggregate findings into perspectives.json + +Phase 3: Conflict Detection & Resolution + ├─ Detect: effort conflicts, architecture conflicts, risk conflicts + ├─ Analyze rationale for each conflict + ├─ Synthesis via arbitration: generate unified recommendation + ├─ Document conflicts and resolutions + └─ Update plan.md + +Phase 4: Plan Synthesis + ├─ Consolidate all insights + ├─ Generate task breakdown (5-8 major tasks) + ├─ Create execution strategy and dependencies + ├─ Document assumptions and risks + └─ Output plan.md + synthesis.json + +Output: + ├─ .workflow/.planning/{sessionId}/plan.md (minimal, actionable) + ├─ .workflow/.planning/{sessionId}/perspectives.json (agent findings) + ├─ .workflow/.planning/{sessionId}/conflicts.json (decision points) + └─ .workflow/.planning/{sessionId}/synthesis.json (task breakdown for execution) +``` + +## Implementation Details + +### Phase 1: Session Setup & Input Loading + +```javascript +const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString() + +// Parse input +const planSlug = "$TOPIC".toLowerCase() + .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-') + .substring(0, 30) +const sessionId = `PLAN-${planSlug}-${getUtc8ISOString().substring(0, 10)}` +const sessionFolder = `.workflow/.planning/${sessionId}` + +// Detect input type +let artifact = null +if ($TOPIC.startsWith('BS-') || "$TOPIC".includes('brainstorm')) { + artifact = loadBrainstormArtifact($TOPIC) +} else if ($TOPIC.startsWith('ANL-') || "$TOPIC".includes('analysis')) { + artifact = loadAnalysisArtifact($TOPIC) +} + +bash(`mkdir -p ${sessionFolder}`) +``` + +### Phase 2: Parallel Multi-Agent Analysis + +Run 4 agents in parallel using ccw cli: + +```javascript +// Launch all 4 agents concurrently with Bash run_in_background +const agentPromises = [] + +// Agent 1 - Architecture (Gemini) +agentPromises.push( + Bash({ + command: `ccw cli -p " +PURPOSE: Architecture & high-level design for '${planningTopic}' +Success: Clear component decomposition and architectural approach + +TASK: +• Decompose problem into major components/modules +• Identify architectural patterns and integration points +• Design component interfaces and data models +• Assess scalability and maintainability implications +• Propose architectural approach with rationale + +MODE: analysis + +CONTEXT: @**/* +${artifact ? \`| Source artifact: \${artifact.type}\` : ''} + +EXPECTED: +- Component decomposition (list with responsibilities) +- Module interfaces and contracts +- Data flow between components +- Architectural patterns applied (e.g., MVC, Event-Driven, etc.) +- Scalability assessment (1-5 rating with rationale) +- Architectural risks identified + +CONSTRAINTS: Focus on long-term maintainability and extensibility +" --tool gemini --mode analysis`, + run_in_background: true + }) +) + +// Agent 2 - Implementation (Codex) +agentPromises.push( + Bash({ + command: \`ccw cli -p " +PURPOSE: Implementation approach & technical feasibility for '\${planningTopic}' +Success: Concrete implementation strategy with realistic estimates + +TASK: +• Evaluate technical feasibility of proposed approach +• Identify required technologies and dependencies +• Estimate effort: analysis/design/coding/testing/deployment +• Suggest implementation phases and milestones +• Highlight technical blockers and challenges + +MODE: analysis + +CONTEXT: @**/* +\${artifact ? \`| Source artifact: \${artifact.type}\` : ''} + +EXPECTED: +- Technology stack recommendation (languages, frameworks, tools) +- Implementation complexity: high|medium|low (with justification) +- Effort breakdown (hours or complexity: analysis, design, coding, testing, deployment) +- Key technical decisions with tradeoffs explained +- Potential blockers and mitigation strategies +- Suggested implementation phases with sequencing +- Reusable components or libraries identified + +CONSTRAINTS: Realistic with current tech stack +" --tool codex --mode analysis\`, + run_in_background: true + }) +) + +// Agent 3 - Validation & Risk (Claude) +agentPromises.push( + Bash({ + command: \`ccw cli -p " +PURPOSE: Risk analysis and validation strategy for '\${planningTopic}' +Success: Comprehensive risk matrix with testing and deployment strategy + +TASK: +• Identify technical risks and failure scenarios +• Assess timeline and resource risks +• Define validation/testing strategy (unit, integration, e2e, performance) +• Suggest monitoring and observability requirements +• Propose deployment strategy and rollback plan + +MODE: analysis + +CONTEXT: @**/* +\${artifact ? \`| Source artifact: \${artifact.type}\` : ''} + +EXPECTED: +- Risk matrix (likelihood × impact, each 1-5) +- Top 3 technical risks with mitigation approaches +- Top 3 timeline/resource risks with mitigation +- Testing strategy (what to test, how, when, acceptance criteria) +- Deployment strategy (staged rollout, blue-green, canary, etc.) +- Rollback plan and recovery procedures +- Monitoring/observability requirements (metrics, logs, alerts) +- Overall risk rating: low|medium|high (with confidence) + +CONSTRAINTS: Be realistic, not pessimistic +" --tool claude --mode analysis\`, + run_in_background: true + }) +) + +// Agent 4 - Strategic Decision (Gemini) +agentPromises.push( + Bash({ + command: \`ccw cli -p " +PURPOSE: Strategic decisions and execution recommendations for '\${planningTopic}' +Success: Clear recommended approach with tradeoff analysis + +TASK: +• Synthesize all perspectives into strategic recommendations +• Identify 2-3 critical decision points with recommended choices +• Clearly outline key tradeoffs (speed vs quality, scope vs timeline, risk vs cost) +• Propose go/no-go decision criteria and success metrics +• Suggest execution strategy and resource sequencing + +MODE: analysis + +CONTEXT: @**/* +\${artifact ? \`| Source artifact: \${artifact.type}\` : ''} + +EXPECTED: +- Primary recommendation with strong rationale (1-2 paragraphs) +- Alternative approaches with pros/cons (2-3 alternatives) +- 2-3 critical decision points: + - What decision needs to be made + - Trade-offs for each option + - Recommended choice and why +- Key trade-offs explained (what we're optimizing for: speed/quality/risk/cost) +- Success metrics and go/no-go criteria +- Resource requirements and critical path items +- Suggested execution sequencing and phases + +CONSTRAINTS: Focus on actionable decisions, provide clear rationale +" --tool gemini --mode analysis\`, + run_in_background: true + }) +) + +// Wait for all agents to complete +const [archResult, implResult, riskResult, decisionResult] = await Promise.all(agentPromises) + +// Parse and extract findings from each agent result +const architecture = parseArchitectureResult(archResult) +const implementation = parseImplementationResult(implResult) +const validation = parseValidationResult(riskResult) +const recommendation = parseDecisionResult(decisionResult) +``` + +**Agent Focus Areas**: + +| Agent | Perspective | Focus Areas | +|-------|-------------|------------| +| Gemini (Design) | Architecture patterns | Components, interfaces, scalability, patterns | +| Codex (Build) | Implementation reality | Tech stack, complexity, effort, blockers | +| Claude (Validate) | Risk & testing | Risk matrix, testing strategy, deployment, monitoring | +| Gemini (Decide) | Strategic synthesis | Recommendations, trade-offs, critical decisions | + +### Phase 3: Parse & Aggregate Perspectives + +```javascript +const perspectives = { + session_id: sessionId, + topic: "$TOPIC", + timestamp: getUtc8ISOString(), + + architecture: { + components: [...], + patterns: [...], + scalability_rating: 3, + risks: [...] + }, + + implementation: { + technology_stack: [...], + complexity: "medium", + effort_breakdown: { analysis: 2, design: 3, coding: 8, testing: 4 }, + blockers: [...] + }, + + validation: { + risk_matrix: [...], + top_risks: [{ title, impact, mitigation }, ...], + testing_strategy: "...", + monitoring: [...] + }, + + recommendation: { + primary_approach: "...", + alternatives: [...], + critical_decisions: [...], + tradeoffs: [...] + } +} + +Write(`${sessionFolder}/perspectives.json`, JSON.stringify(perspectives, null, 2)) +``` + +### Phase 4: Conflict Detection + +Detect conflicts: +- Effort variance: Are estimates consistent? +- Risk disagreement: Do arch and validation agree on risks? +- Scope confusion: Are recommendations aligned? +- Architecture mismatch: Do design and implementation agree? + +For each conflict: document it, then run synthesis arbitration. + +### Phase 5: Generate Plan + +```markdown +# Quick Planning Session + +**Session ID**: ${sessionId} +**Topic**: $TOPIC +**Created**: ${timestamp} + +--- + +## Executive Summary + +${synthesis.executive_summary} + +**Complexity**: ${synthesis.complexity_level} +**Estimated Effort**: ${formatEffort(synthesis.effort_breakdown)} +**Optimization Focus**: ${synthesis.optimization_focus} + +--- + +## Architecture + +**Primary Pattern**: ${synthesis.architecture_approach} + +**Key Components**: +${synthesis.key_components.map((c, i) => `${i+1}. ${c.name}: ${c.responsibility}`).join('\n')} + +--- + +## Implementation Strategy + +**Technology Stack**: +${synthesis.technology_stack.map(t => `- ${t}`).join('\n')} + +**Phases**: +${synthesis.phases.map((p, i) => `${i+1}. ${p.name} (${p.effort})`).join('\n')} + +--- + +## Risk Assessment + +**Overall Risk**: ${synthesis.overall_risk_level} + +**Top 3 Risks**: +${synthesis.top_risks.map((r, i) => `${i+1}. **${r.title}** (Impact: ${r.impact})\n Mitigation: ${r.mitigation}`).join('\n\n')} + +--- + +## Task Breakdown (Ready for Execution) + +${synthesis.tasks.map((task, i) => ` +${i+1}. **${task.id}: ${task.title}** (Effort: ${task.effort}) + ${task.description} + Dependencies: ${task.dependencies.join(', ') || 'none'} +`).join('\n')} + +--- + +## Next Steps + +**Execute with**: +\`\`\` +/workflow:unified-execute-with-file -p ${sessionFolder}/synthesis.json +\`\`\` + +**Detailed planning if needed**: +\`\`\` +/workflow:plan "Based on: $TOPIC" +\`\`\` +``` + +## Session Folder Structure + +``` +.workflow/.planning/{sessionId}/ +├── plan.md # Minimal, actionable +├── perspectives.json # Agent findings +├── conflicts.json # Conflicts & resolutions (if any) +└── synthesis.json # Task breakdown for execution +``` + +## Multi-Agent Coordination + +| Agent | Perspective | Tools | Output | +|-------|-------------|-------|--------| +| Gemini (Design) | Architecture patterns | Design thinking, cross-domain | Components, patterns, scalability | +| Codex (Build) | Implementation reality | Tech stack evaluation | Stack, effort, feasibility | +| Claude (Validate) | Risk & testing | Risk assessment, QA | Risks, testing strategy | +| Gemini (Decide) | Strategic synthesis | Decision analysis | Recommendations, tradeoffs | + +## Error Handling + +| Situation | Action | +|-----------|--------| +| Agents conflict | Arbitration agent synthesizes recommendation | +| Missing blockers | Continue with available context, note gaps | +| Unclear input | Ask for clarification on planning focus | +| Estimate too high | Suggest MVP approach or phasing | + +## Integration Flow + +``` +Raw Task / Brainstorm / Analysis + │ + ▼ +quick-plan-with-file (5-10 min) + │ + ├─ plan.md + ├─ perspectives.json + └─ synthesis.json + │ + ▼ +unified-execute-with-file + │ + ▼ +Implementation +``` + +## Usage Patterns + +**Pattern 1: Quick planning from task** +``` +TOPIC="实现实时通知系统" --auto +→ Creates actionable plan in ~5 minutes +``` + +**Pattern 2: Convert brainstorm to execution plan** +``` +TOPIC="BS-notifications-2025-01-28" --from=brainstorm +→ Reads synthesis.json from brainstorm +→ Generates implementation plan +``` + +**Pattern 3: From analysis to plan** +``` +TOPIC="ANL-auth-2025-01-28" --from=analysis +→ Converts conclusions.json to executable plan +``` + +--- + +**Now execute quick-plan-with-file for topic**: $TOPIC