claude-code-workflow 6.3.53 → 6.3.54

package/.claude/commands/workflow/plan.md

@@ -119,7 +119,7 @@ CONTEXT: Existing user database schema, REST API endpoints
 **After Phase 1**: Initialize planning-notes.md with user intent
 
 ```javascript
-// Create minimal planning notes document
+// Create planning notes document with N+1 context support
 const planningNotesPath = `.workflow/active/${sessionId}/planning-notes.md`
 const userGoal = structuredDescription.goal
 const userConstraints = structuredDescription.context || "None specified"
@@ -144,6 +144,19 @@ Write(planningNotesPath, `# Planning Notes
 
 ## Consolidated Constraints (Phase 4 Input)
 1. ${userConstraints}
+
+---
+
+## Task Generation (Phase 4)
+(To be filled by action-planning-agent)
+
+## N+1 Context
+### Decisions
+| Decision | Rationale | Revisit? |
+|----------|-----------|----------|
+
+### Deferred
+- [ ] (For N+1)
 `)
 ```
 

package/.claude/commands/workflow/tools/task-generate-agent.md

@@ -378,16 +378,26 @@ Hard Constraints:
 - Return completion status with document count and task breakdown summary
 
 ## PLANNING NOTES RECORD (REQUIRED)
-After completing all documents, append a brief execution record to planning-notes.md:
+After completing, update planning-notes.md:
 
 **File**: .workflow/active/{session_id}/planning-notes.md
-**Location**: Create new section after "## Consolidated Constraints"
-**Format**:
-\`\`\`
-## Task Generation (Phase 4)
 
+1. **Task Generation (Phase 4)**: Task count and key tasks
+2. **N+1 Context**: Key decisions (with rationale) + deferred items
+
+\`\`\`markdown
+## Task Generation (Phase 4)
 ### [Action-Planning Agent] YYYY-MM-DD
-- **Note**: [智能补充：简短总结任务数量、关键任务、依赖关系等]
+- **Tasks**: [count] ([IDs])
+
+## N+1 Context
+### Decisions
+| Decision | Rationale | Revisit? |
+|----------|-----------|----------|
+| [choice] | [why] | [Yes/No] |
+
+### Deferred
+- [ ] [item] - [reason]
 \`\`\`
 `
 )
@@ -543,19 +553,13 @@ Hard Constraints:
 - Return: task count, task IDs, dependency summary (internal + cross-module)
 
 ## PLANNING NOTES RECORD (REQUIRED)
-After completing module task JSONs, append a brief execution record to planning-notes.md:
+After completing, append to planning-notes.md:
 
-**File**: .workflow/active/{session_id}/planning-notes.md
-**Location**: Create new section after "## Consolidated Constraints" (if not exists)
-**Format**:
+\`\`\`markdown
+### [${module.name}] YYYY-MM-DD
+- **Tasks**: [count] ([IDs])
+- **CROSS deps**: [placeholders used]
 \`\`\`
-## Task Generation (Phase 4)
-
-### [Action-Planning Agent - ${module.name}] YYYY-MM-DD
-- **Note**: [智能补充：简短总结本模块任务数量、关键任务等]
-\`\`\`
-
-**Note**: Multiple module agents will append their records. Phase 3 Integration Coordinator will add final summary.
     `
   )
 );
@@ -638,14 +642,21 @@ Module Count: ${modules.length}
 - Return: task count, per-module breakdown, resolved dependency count
 
 ## PLANNING NOTES RECORD (REQUIRED)
-After completing integration, append final summary to planning-notes.md:
+After integration, update planning-notes.md:
 
-**File**: .workflow/active/{session_id}/planning-notes.md
-**Location**: Under "## Task Generation (Phase 4)" section (after module agent records)
-**Format**:
-\`\`\`
-### [Integration Coordinator] YYYY-MM-DD
-- **Note**: [智能补充：简短总结总任务数、跨模块依赖解决情况等]
+\`\`\`markdown
+### [Coordinator] YYYY-MM-DD
+- **Total**: [count] tasks
+- **Resolved**: [CROSS:: resolutions]
+
+## N+1 Context
+### Decisions
+| Decision | Rationale | Revisit? |
+|----------|-----------|----------|
+| CROSS::X → IMPL-Y | [why this resolution] | [Yes/No] |
+
+### Deferred
+- [ ] [unresolved CROSS or conflict] - [reason]
 \`\`\`
   `
 )

package/.claude/commands/workflow/unified-execute-with-file.md

@@ -873,21 +873,6 @@ function calculateParallel(tasks) {
 | Agent unavailable | Fallback to universal-executor |
 | Execution interrupted | Support resume with `/workflow:unified-execute-with-file --continue` |
 
-## Usage Recommendations
-
-Use `/workflow:unified-execute-with-file` when:
-- Executing any planning document (IMPL_PLAN.md, brainstorm conclusions, analysis recommendations)
-- Multiple tasks with dependencies need orchestration
-- Want minimal progress tracking without clutter
-- Need to handle failures gracefully and resume
-- Want to parallelize where possible but ensure correctness
-
-Use for consuming output from:
-- `/workflow:plan` → IMPL_PLAN.md
-- `/workflow:brainstorm-with-file` → synthesis.json → execution
-- `/workflow:analyze-with-file` → conclusions.json → execution
-- `/workflow:debug-with-file` → recommendations → execution
-- `/workflow:lite-plan` → task JSONs → execution
 
 ## Session Resume
 

package/.claude/skills/flow-coordinator/SKILL.md

@@ -0,0 +1,394 @@
+---
+name: flow-coordinator
+description: Template-driven workflow coordinator with minimal state tracking. Executes command chains from workflow templates with slash-command execution (mainprocess/async). Triggers on "flow-coordinator", "workflow template", "orchestrate".
+allowed-tools: Task, AskUserQuestion, Read, Write, Bash, Glob, Grep
+---
+
+# Flow Coordinator
+
+Lightweight workflow coordinator that executes command chains from predefined templates, supporting slash-command execution with mainprocess (blocking) and async (background) modes.
+
+## Architecture
+
+```
+User Task → Select Template → status.json Init → Execute Steps → Complete
+     ↑                                                │
+     └──────────────── Resume (from status.json) ─────┘
+
+Step Execution:
+  execution mode?
+    ├─ mainprocess  → SlashCommand (blocking, main process)
+    └─ async        → ccw cli --tool claude --mode write (background)
+```
+
+## Core Concepts
+
+**Template-Driven**: Workflows defined as JSON templates in `templates/`, decoupled from coordinator logic.
+
+**Execution Type**: `slash-command` only
+- ALL workflow commands (`/workflow:*`) use `slash-command` type
+- Two execution modes:
+  - `mainprocess`: SlashCommand (blocking, main process)
+  - `async`: CLI background (ccw cli with claude tool)
+
+**Dynamic Discovery**: Templates discovered at runtime via Glob, not hardcoded.
+
+---
+
+## Execution Flow
+
+```javascript
+async function execute(task) {
+  // 1. Discover and select template
+  const templates = await discoverTemplates();
+  const template = await selectTemplate(templates);
+
+  // 2. Init status
+  const sessionId = `fc-${timestamp()}`;
+  const statusPath = `.workflow/.flow-coordinator/${sessionId}/status.json`;
+  const status = initStatus(template, task);
+  write(statusPath, JSON.stringify(status, null, 2));
+
+  // 3. Execute steps based on execution config
+  await executeSteps(status, statusPath);
+}
+
+async function executeSteps(status, statusPath) {
+  for (let i = status.current; i < status.steps.length; i++) {
+    const step = status.steps[i];
+    status.current = i;
+
+    // Execute based on step mode (all steps use slash-command type)
+    const execConfig = step.execution || { type: 'slash-command', mode: 'mainprocess' };
+
+    if (execConfig.mode === 'async') {
+      // Async execution - stop and wait for hook callback
+      await executeSlashCommandAsync(step, status, statusPath);
+      break;
+    } else {
+      // Mainprocess execution - continue immediately
+      await executeSlashCommandSync(step, status);
+      step.status = 'done';
+      write(statusPath, JSON.stringify(status, null, 2));
+    }
+  }
+
+  // All steps complete
+  if (status.current >= status.steps.length) {
+    status.complete = true;
+    write(statusPath, JSON.stringify(status, null, 2));
+  }
+}
+```
+
+---
+
+## Template Discovery
+
+**Dynamic query** - never hardcode template list:
+
+```javascript
+async function discoverTemplates() {
+  // Discover all JSON templates
+  const files = Glob('*.json', { path: 'templates/' });
+
+  // Parse each template
+  const templates = [];
+  for (const file of files) {
+    const content = JSON.parse(Read(file));
+    templates.push({
+      name: content.name,
+      description: content.description,
+      steps: content.steps.map(s => s.cmd).join(' → '),
+      file: file
+    });
+  }
+
+  return templates;
+}
+```
+
+---
+
+## Template Selection
+
+User chooses from discovered templates:
+
+```javascript
+async function selectTemplate(templates) {
+  // Build options from discovered templates
+  const options = templates.slice(0, 4).map(t => ({
+    label: t.name,
+    description: t.steps
+  }));
+
+  const response = await AskUserQuestion({
+    questions: [{
+      question: 'Select workflow template:',
+      header: 'Template',
+      options: options,
+      multiSelect: false
+    }]
+  });
+
+  // Handle "Other" - show remaining templates or custom input
+  if (response.template === 'Other') {
+    return await selectFromRemainingTemplates(templates.slice(4));
+  }
+
+  return templates.find(t => t.name === response.template);
+}
+```
+
+---
+
+## Status Schema
+
+**Creation**: Copy template JSON → Update `id`, `template`, `goal`, set all steps `status: "pending"`
+
+**Location**: `.workflow/.flow-coordinator/{session-id}/status.json`
+
+**Core Fields**:
+- `id`: Session ID (fc-YYYYMMDD-HHMMSS)
+- `template`: Template name
+- `goal`: User task description
+- `current`: Current step index
+- `steps[]`: Step array from template (with runtime `status`, `session`, `taskId`)
+- `complete`: All steps done?
+
+**Step Status**: `pending` → `running` → `done` | `failed` | `skipped`
+
+---
+
+## Extended Template Schema
+
+**Templates stored in**: `templates/*.json` (discovered at runtime via Glob)
+
+**TemplateStep Fields**:
+- `cmd`: Full command path (e.g., `/workflow:lite-plan`, `/workflow:execute`)
+- `args?`: Arguments with `{{goal}}` and `{{prev}}` placeholders
+- `unit?`: Minimum execution unit name (groups related commands)
+- `optional?`: Can be skipped by user
+- `execution`: Type and mode configuration
+  - `type`: Always `'slash-command'` (for all workflow commands)
+  - `mode`: `'mainprocess'` (blocking) or `'async'` (background)
+- `contextHint?`: Natural language guidance for context assembly
+
+**Template Example**:
+```json
+{
+  "name": "rapid",
+  "steps": [
+    {
+      "cmd": "/workflow:lite-plan",
+      "args": "\"{{goal}}\"",
+      "unit": "quick-implementation",
+      "execution": { "type": "slash-command", "mode": "mainprocess" },
+      "contextHint": "Create lightweight implementation plan"
+    },
+    {
+      "cmd": "/workflow:lite-execute",
+      "args": "--in-memory",
+      "unit": "quick-implementation",
+      "execution": { "type": "slash-command", "mode": "async" },
+      "contextHint": "Execute plan from previous step"
+    }
+  ]
+}
+```
+
+---
+
+## Execution Implementation
+
+### Mainprocess Mode (Blocking)
+
+```javascript
+async function executeSlashCommandSync(step, status) {
+  // Build command: /workflow:cmd -y args
+  const cmd = buildCommand(step, status);
+  const result = await SlashCommand({ command: cmd });
+
+  step.session = result.session_id;
+  step.status = 'done';
+  return result;
+}
+```
+
+### Async Mode (Background)
+
+```javascript
+async function executeSlashCommandAsync(step, status, statusPath) {
+  // Build prompt: /workflow:cmd -y args + context
+  const prompt = buildCommandPrompt(step, status);
+
+  step.status = 'running';
+  write(statusPath, JSON.stringify(status, null, 2));
+
+  // Execute via ccw cli in background
+  const taskId = Bash(
+    `ccw cli -p "${escapePrompt(prompt)}" --tool claude --mode write`,
+    { run_in_background: true }
+  ).task_id;
+
+  step.taskId = taskId;
+  write(statusPath, JSON.stringify(status, null, 2));
+
+  console.log(`Executing: ${step.cmd} (async)`);
+  console.log(`Resume: /flow-coordinator --resume ${status.id}`);
+}
+```
+
+---
+
+## Prompt Building
+
+Prompts are built in format: `/workflow:cmd -y args` + context
+
+```javascript
+function buildCommandPrompt(step, status) {
+  // step.cmd already contains full path: /workflow:lite-plan, /workflow:execute, etc.
+  let prompt = `${step.cmd} -y`;
+
+  // Add arguments (with placeholder replacement)
+  if (step.args) {
+    const args = step.args
+      .replace('{{goal}}', status.goal)
+      .replace('{{prev}}', getPreviousSessionId(status));
+    prompt += ` ${args}`;
+  }
+
+  // Add context based on contextHint
+  if (step.contextHint) {
+    const context = buildContextFromHint(step.contextHint, status);
+    prompt += `\n\nContext:\n${context}`;
+  } else {
+    // Default context: previous session IDs
+    const previousContext = collectPreviousResults(status);
+    if (previousContext) {
+      prompt += `\n\nPrevious results:\n${previousContext}`;
+    }
+  }
+
+  return prompt;
+}
+
+function buildContextFromHint(hint, status) {
+  // Parse contextHint instruction and build context accordingly
+  // Examples:
+  // "Summarize IMPL_PLAN.md" → read and summarize plan
+  // "List test coverage gaps" → analyze previous test results
+  // "Pass session ID" → just return session reference
+
+  return parseAndBuildContext(hint, status);
+}
+```
+
+### Example Prompt Output
+
+```
+/workflow:lite-plan -y "Implement user registration"
+
+Context:
+Task: Implement user registration
+Previous results:
+- None (first step)
+```
+
+```
+/workflow:execute -y --in-memory
+
+Context:
+Task: Implement user registration
+Previous results:
+- lite-plan: WFS-plan-20250130 (planning-context.md)
+```
+
+---
+
+## User Interaction
+
+### Step 1: Select Template
+
+```
+Select workflow template:
+
+○ rapid      lite-plan → lite-execute → test-cycle-execute
+○ coupled    plan → plan-verify → execute → review → test
+○ bugfix     lite-fix → lite-execute → test-cycle-execute
+○ tdd        tdd-plan → execute → tdd-verify
+○ Other      (more templates or custom)
+```
+
+### Step 2: Review Execution Plan
+
+```
+Template: coupled
+Steps:
+  1. /workflow:plan (slash-command mainprocess)
+  2. /workflow:plan-verify (slash-command mainprocess)
+  3. /workflow:execute (slash-command async)
+  4. /workflow:review-session-cycle (slash-command mainprocess)
+  5. /workflow:review-cycle-fix (slash-command mainprocess)
+  6. /workflow:test-fix-gen (slash-command mainprocess)
+  7. /workflow:test-cycle-execute (slash-command async)
+
+Proceed? [Confirm / Cancel]
+```
+
+---
+
+## Resume Capability
+
+```javascript
+async function resume(sessionId) {
+  const statusPath = `.workflow/.flow-coordinator/${sessionId}/status.json`;
+  const status = JSON.parse(Read(statusPath));
+
+  // Find first incomplete step
+  status.current = status.steps.findIndex(s => s.status !== 'done');
+  if (status.current === -1) {
+    console.log('All steps complete');
+    return;
+  }
+
+  // Continue executing steps
+  await executeSteps(status, statusPath);
+}
+```
+
+---
+
+## Available Templates
+
+Templates discovered from `templates/*.json`:
+
+| Template | Use Case | Steps |
+|----------|----------|-------|
+| rapid | Simple feature | /workflow:lite-plan → /workflow:lite-execute → /workflow:test-cycle-execute |
+| coupled | Complex feature | /workflow:plan → /workflow:plan-verify → /workflow:execute → /workflow:review-session-cycle → /workflow:test-fix-gen |
+| bugfix | Bug fix | /workflow:lite-fix → /workflow:lite-execute → /workflow:test-cycle-execute |
+| tdd | Test-driven | /workflow:tdd-plan → /workflow:execute → /workflow:tdd-verify |
+| test-fix | Fix failing tests | /workflow:test-fix-gen → /workflow:test-cycle-execute |
+| brainstorm | Exploration | /workflow:brainstorm-with-file |
+| debug | Debug with docs | /workflow:debug-with-file |
+| analyze | Collaborative analysis | /workflow:analyze-with-file |
+| issue | Issue workflow | /workflow:issue:plan → /workflow:issue:queue → /workflow:issue:execute |
+
+---
+
+## Design Principles
+
+1. **Minimal fields**: Only essential tracking data
+2. **Flat structure**: No nested objects beyond steps array
+3. **Step-level execution**: Each step defines how it's executed
+4. **Resumable**: Any step can be resumed from status
+5. **Human readable**: Clear JSON format
+
+---
+
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| templates/*.json | Workflow templates (dynamic discovery) |

package/.claude/skills/flow-coordinator/templates/analyze.json

@@ -0,0 +1,16 @@
+{
+  "name": "analyze",
+  "description": "Collaborative analysis with multi-round discussion - deep exploration and understanding",
+  "level": 3,
+  "steps": [
+    {
+      "cmd": "/workflow:analyze-with-file",
+      "args": "\"{{goal}}\"",
+      "execution": {
+        "type": "slash-command",
+        "mode": "mainprocess"
+      },
+      "contextHint": "Multi-round collaborative analysis with iterative understanding. Generate discussion.md with comprehensive analysis and conclusions"
+    }
+  ]
+}

package/.claude/skills/flow-coordinator/templates/brainstorm-to-issue.json

@@ -0,0 +1,36 @@
+{
+  "name": "brainstorm-to-issue",
+  "description": "Bridge brainstorm session to issue workflow - convert exploration insights to executable issues",
+  "level": 4,
+  "steps": [
+    {
+      "cmd": "/workflow:issue:from-brainstorm",
+      "args": "--auto",
+      "unit": "brainstorm-to-issue",
+      "execution": {
+        "type": "slash-command",
+        "mode": "mainprocess"
+      },
+      "contextHint": "Convert brainstorm session findings into issue plans and solutions"
+    },
+    {
+      "cmd": "/workflow:issue:queue",
+      "unit": "brainstorm-to-issue",
+      "execution": {
+        "type": "slash-command",
+        "mode": "mainprocess"
+      },
+      "contextHint": "Build execution queue from converted brainstorm issues"
+    },
+    {
+      "cmd": "/workflow:issue:execute",
+      "args": "--queue auto",
+      "unit": "brainstorm-to-issue",
+      "execution": {
+        "type": "slash-command",
+        "mode": "async"
+      },
+      "contextHint": "Execute issues from queue with state tracking"
+    }
+  ]
+}

package/.claude/skills/flow-coordinator/templates/brainstorm.json

@@ -0,0 +1,16 @@
+{
+  "name": "brainstorm",
+  "description": "Multi-perspective ideation with documentation - explore possibilities with multiple analytical viewpoints",
+  "level": 4,
+  "steps": [
+    {
+      "cmd": "/workflow:brainstorm-with-file",
+      "args": "\"{{goal}}\"",
+      "execution": {
+        "type": "slash-command",
+        "mode": "mainprocess"
+      },
+      "contextHint": "Multi-perspective ideation with interactive diverge-converge cycles. Generate brainstorm.md with synthesis of ideas and recommendations"
+    }
+  ]
+}

package/.claude/skills/flow-coordinator/templates/bugfix-hotfix.json

@@ -0,0 +1,16 @@
+{
+  "name": "bugfix-hotfix",
+  "description": "Urgent production fix - immediate diagnosis and fix with minimal overhead",
+  "level": 1,
+  "steps": [
+    {
+      "cmd": "/workflow:lite-fix",
+      "args": "--hotfix \"{{goal}}\"",
+      "execution": {
+        "type": "slash-command",
+        "mode": "async"
+      },
+      "contextHint": "Urgent hotfix mode: quick diagnosis and immediate fix for critical production issue"
+    }
+  ]
+}

package/.claude/skills/flow-coordinator/templates/bugfix.json

@@ -0,0 +1,47 @@
+{
+  "name": "bugfix",
+  "description": "Standard bug fix workflow - lightweight diagnosis and execution with testing",
+  "level": 2,
+  "steps": [
+    {
+      "cmd": "/workflow:lite-fix",
+      "args": "\"{{goal}}\"",
+      "unit": "bug-fix",
+      "execution": {
+        "type": "slash-command",
+        "mode": "mainprocess"
+      },
+      "contextHint": "Analyze bug report, trace execution flow, identify root cause with fix strategy"
+    },
+    {
+      "cmd": "/workflow:lite-execute",
+      "args": "--in-memory",
+      "unit": "bug-fix",
+      "execution": {
+        "type": "slash-command",
+        "mode": "async"
+      },
+      "contextHint": "Implement fix based on diagnosis. Execute against in-memory state from lite-fix analysis."
+    },
+    {
+      "cmd": "/workflow:test-fix-gen",
+      "unit": "test-validation",
+      "optional": true,
+      "execution": {
+        "type": "slash-command",
+        "mode": "mainprocess"
+      },
+      "contextHint": "Generate test tasks to verify bug fix and prevent regression"
+    },
+    {
+      "cmd": "/workflow:test-cycle-execute",
+      "unit": "test-validation",
+      "optional": true,
+      "execution": {
+        "type": "slash-command",
+        "mode": "async"
+      },
+      "contextHint": "Execute test-fix cycle until all tests pass"
+    }
+  ]
+}