claude-code-workflow 6.3.41 → 6.3.43

package/.claude/commands/issue/plan.md

@@ -55,11 +55,11 @@ Unified planning command using **issue-plan-agent** that combines exploration an
 ## Execution Process
 
 ```
-Phase 1: Issue Loading
+Phase 1: Issue Loading & Intelligent Grouping
    ├─ Parse input (single, comma-separated, or --all-pending)
    ├─ Fetch issue metadata (ID, title, tags)
    ├─ Validate issues exist (create if needed)
-   └─ Group by similarity (shared tags or title keywords, max 3 per batch)
+   └─ Intelligent grouping via Gemini (semantic similarity, max 3 per batch)
 
 Phase 2: Unified Explore + Plan (issue-plan-agent)
    ├─ Launch issue-plan-agent per batch
@@ -119,46 +119,11 @@ if (useAllPending) {
 }
 // Note: Agent fetches full issue content via `ccw issue status <id> --json`
 
-// Semantic grouping via Gemini CLI (max 4 issues per group)
-async function groupBySimilarityGemini(issues) {
-  const issueSummaries = issues.map(i => ({
-    id: i.id, title: i.title, tags: i.tags
-  }));
-
-  const prompt = `
-PURPOSE: Group similar issues by semantic similarity for batch processing; maximize within-group coherence; max 4 issues per group
-TASK: • Analyze issue titles/tags semantically • Identify functional/architectural clusters • Assign each issue to one group
-MODE: analysis
-CONTEXT: Issue metadata only
-EXPECTED: JSON with groups array, each containing max 4 issue_ids, theme, rationale
-CONSTRAINTS: Each issue in exactly one group | Max 4 issues per group | Balance group sizes
-
-INPUT:
-${JSON.stringify(issueSummaries, null, 2)}
-
-OUTPUT FORMAT:
-{"groups":[{"group_id":1,"theme":"...","issue_ids":["..."],"rationale":"..."}],"ungrouped":[]}
-`;
-
-  const taskId = Bash({
-    command: `ccw cli -p "${prompt}" --tool gemini --mode analysis`,
-    run_in_background: true, timeout: 600000
-  });
-  const output = TaskOutput({ task_id: taskId, block: true });
-
-  // Extract JSON from potential markdown code blocks
-  function extractJsonFromMarkdown(text) {
-    const jsonMatch = text.match(/```json\s*\n([\s\S]*?)\n```/) ||
-                      text.match(/```\s*\n([\s\S]*?)\n```/);
-    return jsonMatch ? jsonMatch[1] : text;
-  }
-
-  const result = JSON.parse(extractJsonFromMarkdown(output));
-  return result.groups.map(g => g.issue_ids.map(id => issues.find(i => i.id === id)));
-}
+// Intelligent grouping: Analyze issues by title/tags, group semantically similar ones
+// Strategy: Same module/component, related bugs, feature clusters
+// Constraint: Max ${batchSize} issues per batch
 
-const batches = await groupBySimilarityGemini(issues);
-console.log(`Processing ${issues.length} issues in ${batches.length} batch(es) (max 4 issues/agent)`);
+console.log(`Processing ${issues.length} issues in ${batches.length} batch(es)`);
 
 TodoWrite({
   todos: batches.map((_, i) => ({
@@ -207,7 +172,9 @@ ${issueList}
    -  Add explicit verification steps to prevent same failure mode
 6. **If github_url exists**: Add final task to comment on GitHub issue
 7. Write solution to: .workflow/issues/solutions/{issue-id}.jsonl
-8. Single solution → auto-bind; Multiple → return for selection
+8. **CRITICAL - Binding Decision**:
+   - Single solution → **MUST execute**: ccw issue bind <issue-id> <solution-id>
+   - Multiple solutions → Return pending_selection only (no bind)
 
 ### Failure-Aware Planning Rules
 - **Extract failure patterns**: Parse issue.feedback where type='failure' and stage='execute'
@@ -265,35 +232,55 @@ for (let i = 0; i < agentTasks.length; i += MAX_PARALLEL) {
     }
     agentResults.push(summary);  // Store for Phase 3 conflict aggregation
 
+    // Verify binding for bound issues (agent should have executed bind)
     for (const item of summary.bound || []) {
-      console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
+      const status = JSON.parse(Bash(`ccw issue status ${item.issue_id} --json`).trim());
+      if (status.bound_solution_id === item.solution_id) {
+        console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
+      } else {
+        // Fallback: agent failed to bind, execute here
+        Bash(`ccw issue bind ${item.issue_id} ${item.solution_id}`);
+        console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks) [recovered]`);
+      }
     }
-    // Collect and notify pending selections
+    // Collect pending selections for Phase 3
     for (const pending of summary.pending_selection || []) {
-      console.log(`⏳ ${pending.issue_id}: ${pending.solutions.length} solutions → awaiting selection`);
       pendingSelections.push(pending);
     }
-    if (summary.conflicts?.length > 0) {
-      console.log(`⚠ Conflicts: ${summary.conflicts.length} detected (will resolve in Phase 3)`);
-    }
     updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
   }
 }
 ```
 
-### Phase 3: Conflict Resolution & Solution Selection
+### Phase 3: Solution Selection (if pending)
+
+```javascript
+// Handle multi-solution issues
+for (const pending of pendingSelections) {
+  if (pending.solutions.length === 0) continue;
+
+  const options = pending.solutions.slice(0, 4).map(sol => ({
+    label: `${sol.id} (${sol.task_count} tasks)`,
+    description: sol.description || sol.approach || 'No description'
+  }));
+
+  const answer = AskUserQuestion({
+    questions: [{
+      question: `Issue ${pending.issue_id}: which solution to bind?`,
+      header: pending.issue_id,
+      options: options,
+      multiSelect: false
+    }]
+  });
 
-**Conflict Handling:**
-- Collect `conflicts` from all agent results
-- Low/Medium severity → auto-resolve with `recommended_resolution`
-- High severity → use `AskUserQuestion` to let user choose resolution
+  const selected = answer[Object.keys(answer)[0]];
+  if (!selected || selected === 'Other') continue;
 
-**Multi-Solution Selection:**
-- If `pending_selection` contains issues with multiple solutions:
-  - Use `AskUserQuestion` to present options (solution ID + task count + description)
-  - Extract selected solution ID from user response
-  - Verify solution file exists, recover from payload if missing
-  - Bind selected solution via `ccw issue bind <issue-id> <solution-id>`
+  const solId = selected.split(' ')[0];
+  Bash(`ccw issue bind ${pending.issue_id} ${solId}`);
+  console.log(`✓ ${pending.issue_id}: ${solId} bound`);
+}
+```
 
 ### Phase 4: Summary
 

package/.claude/commands/issue/queue.md

@@ -28,12 +28,13 @@ Queue formation command using **issue-queue-agent** that analyzes all bound solu
 | Operation | Correct | Incorrect |
 |-----------|---------|-----------|
 | List issues (brief) | `ccw issue list --status planned --brief` | `Read('issues.jsonl')` |
+| **Batch solutions (NEW)** | `ccw issue solutions --status planned --brief` | Loop `ccw issue solution <id>` |
 | List queue (brief) | `ccw issue queue --brief` | `Read('queues/*.json')` |
 | Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
 | Get next item | `ccw issue next --json` | `Read('queues/*.json')` |
 | Update status | `ccw issue update <id> --status ...` | Direct file edit |
 | Sync from queue | `ccw issue update --from-queue` | Direct file edit |
-| **Read solution (brief)** | `ccw issue solution <id> --brief` | `Read('solutions/*.jsonl')` |
+| Read solution (single) | `ccw issue solution <id> --brief` | `Read('solutions/*.jsonl')` |
 
 **Output Options**:
 - `--brief`: JSON with minimal fields (id, status, counts)
@@ -131,24 +132,23 @@ Phase 7: Active Queue Check & Decision (REQUIRED)
 ### Phase 1: Solution Loading & Distribution
 
 **Data Loading:**
-- Use `ccw issue list --status planned --brief` to get planned issues with `bound_solution_id`
-- If no planned issues found → display message, suggest `/issue:plan`
-
-**Solution Brief Loading** (for each planned issue):
-```bash
-ccw issue solution <issue-id> --brief
-# Returns: [{ solution_id, is_bound, task_count, files_touched[] }]
-```
+- Use `ccw issue solutions --status planned --brief` to get all planned issues with solutions in **one call**
+- Returns: Array of `{ issue_id, solution_id, is_bound, task_count, files_touched[], priority }`
+- If no bound solutions found → display message, suggest `/issue:plan`
 
 **Build Solution Objects:**
-```json
-{
-  "issue_id": "ISS-xxx",
-  "solution_id": "SOL-ISS-xxx-1",
-  "task_count": 3,
-  "files_touched": ["src/auth.ts", "src/utils.ts"],
-  "priority": "medium"
+```javascript
+// Single CLI call replaces N individual queries
+const result = Bash(`ccw issue solutions --status planned --brief`).trim();
+const solutions = result ? JSON.parse(result) : [];
+
+if (solutions.length === 0) {
+  console.log('No bound solutions found. Run /issue:plan first.');
+  return;
 }
+
+// solutions already in correct format:
+// { issue_id, solution_id, is_bound, task_count, files_touched[], priority }
 ```
 
 **Multi-Queue Distribution** (if `--queues > 1`):

package/.codex/skills/parallel-dev-cycle/README.md

@@ -7,7 +7,7 @@ Multi-agent parallel development cycle using Codex subagent pattern with continu
 This skill implements a **single-file-per-agent** development workflow:
 
 - **RA**: `requirements.md` (all requirements + edge cases + history)
-- **EP**: `plan.md` (architecture + tasks + integration points)
+- **EP**: `exploration.md`, `architecture.md`, `plan.json` (codebase exploration + architecture + structured tasks)
 - **CD**: `implementation.md` (progress + files + decisions + testing)
 - **VAS**: `summary.md` (validation + test results + recommendations)
 
@@ -49,7 +49,9 @@ Creates:
 │   ├── requirements.md (v1.0.0)
 │   └── changes.log (NDJSON)
 ├── ep/
-│   ├── plan.md (v1.0.0)
+│   ├── exploration.md (v1.0.0)
+│   ├── architecture.md (v1.0.0)
+│   ├── plan.json (v1.0.0)
 │   └── changes.log (NDJSON)
 ├── cd/
 │   ├── implementation.md (v1.0.0)
@@ -113,20 +115,19 @@ When iteration completes, next extends to v1.1.0:
 ```
 Current State (v1.0.0)
 ├── requirements.md (v1.0.0)
-├── plan.md (v1.0.0)
+├── plan.json (v1.0.0)
 ├── implementation.md (v1.0.0)
 └── summary.md (v1.0.0)
 
 User: "Add GitHub provider"
          ↓
 Archive Old                    Write New
-├── history/requirements-v1.0.0.md
-├── history/plan-v1.0.0.md    → requirements.md (v1.1.0) - REWRITTEN
-├── history/impl-v1.0.0.md    → plan.md (v1.1.0) - REWRITTEN
-└── history/summary-v1.0.0.md → implementation.md (v1.1.0) - REWRITTEN
-                               → summary.md (v1.1.0) - REWRITTEN
-                                  ↓
-                           Append to changes.log (NDJSON)
+├── history/requirements-v1.0.0.md  → requirements.md (v1.1.0) - REWRITTEN
+├── history/plan-v1.0.0.json        → plan.json (v1.1.0) - REWRITTEN
+├── history/impl-v1.0.0.md          → implementation.md (v1.1.0) - REWRITTEN
+└── history/summary-v1.0.0.md       → summary.md (v1.1.0) - REWRITTEN
+                                       ↓
+                                 Append to changes.log (NDJSON)
 ```
 
 ## Session Files
@@ -142,11 +143,13 @@ ra/ - Requirements Analyst
     └── requirements-v1.1.0.md
 
 ep/ - Exploration & Planning
-├── plan.md                  # v1.2.0 (current)
+├── exploration.md           # v1.2.0 (codebase exploration)
+├── architecture.md          # v1.2.0 (architecture design)
+├── plan.json                # v1.2.0 (structured task list, current)
 ├── changes.log              # NDJSON audit trail
 └── history/
-    ├── plan-v1.0.0.md
-    └── plan-v1.1.0.md
+    ├── plan-v1.0.0.json
+    └── plan-v1.1.0.json
 
 cd/ - Code Developer
 ├── implementation.md        # v1.2.0 (current)
@@ -203,7 +206,7 @@ vas/ - Validation & Archival
 | Agent | File | Contains | Size |
 |-------|------|----------|------|
 | **RA** | requirements.md | All FR, NFR, edge cases, history summary | ~2-5KB |
-| **EP** | plan.md | Architecture, all tasks, critical path, history | ~3-8KB |
+| **EP** | exploration.md + architecture.md + plan.json | Codebase exploration, architecture design, structured task list | ~5-10KB total |
 | **CD** | implementation.md | Completed tasks, files changed, decisions, tests | ~4-10KB |
 | **VAS** | summary.md | Test results, coverage, issues, recommendations | ~5-12KB |
 
@@ -362,14 +365,14 @@ Orchestrator (main coordinator)
            ↓
       All write to:
       - requirements.md (v1.x.0)
-      - plan.md (v1.x.0)
+      - exploration.md, architecture.md, plan.json (v1.x.0)
       - implementation.md (v1.x.0)
       - summary.md (v1.x.0)
       - changes.log (NDJSON append)
            ↓
       [Automatic archival]
       - history/requirements-v1.{x-1}.0.md
-      - history/plan-v1.{x-1}.0.md
+      - history/plan-v1.{x-1}.0.json
       - etc...
            ↓
       Orchestrator: Next iteration?

package/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md

@@ -28,7 +28,7 @@ The Code Developer is responsible for implementing features according to the pla
    - Document all file modifications
    - Log changes in NDJSON format
    - Track which iteration introduced which changes
-   - Update code-changes.log
+   - Update changes.log
 
 4. **Report Issues**
    - Document development blockers
@@ -43,7 +43,7 @@ The Code Developer is responsible for implementing features according to the pla
 - Test code before submitting
 - Document code changes clearly
 - Track blockers and issues
-- Append to code-changes.log, never overwrite
+- Append to changes.log, never overwrite
 - Reference requirements in code comments
 - Use meaningful commit messages in implementation notes
 
@@ -90,7 +90,7 @@ For each task in the plan:
    - Reference requirements
 
 3. **Track Changes**
-   - Log each file modification to code-changes.log
+   - Log each file modification to changes.log
    - Format: `{timestamp, iteration, file, action, description}`
    - Include reason for change
 
@@ -99,12 +99,96 @@ For each task in the plan:
    - Verify integration
    - Test error cases
    - Check performance
+   - **If tests fail**: Initiate Debug Workflow (see Debug Workflow section)
 
 5. **Report Progress**
    - Update implementation.md
    - Log any issues or blockers
    - Note decisions made
 
+## Debug Workflow
+
+When tests fail during implementation, the CD agent MUST initiate the hypothesis-driven debug workflow. This workflow systematically identifies and resolves bugs through structured hypothesis testing.
+
+### Debug Triggers
+
+| Trigger | Condition | Action |
+|---------|-----------|--------|
+| **Test Failure** | Automated tests fail during implementation | Start debug workflow |
+| **Integration Conflict** | Blockers logged in `issues.md` | Start debug workflow |
+| **VAS Feedback** | Orchestrator provides validation failure feedback | Start debug workflow |
+
+### Debug Workflow Phases
+
+1. **Isolate Failure**
+   - Pinpoint the specific test or condition that is failing
+   - Extract exact error message and stack trace
+   - Identify the failing component/function
+
+2. **Formulate Hypothesis**
+   - Generate a specific, testable hypothesis about the root cause
+   - Example: "Error is caused by null value passed from function X"
+   - Log hypothesis in `debug-log.ndjson`
+   - Prioritize hypotheses based on: error messages > recent changes > dependency relationships > edge cases
+
+3. **Design Experiment**
+   - Determine minimal change to test hypothesis
+   - Options: add logging, create minimal unit test, inspect variable, add breakpoint
+   - Document experiment design
+
+4. **Execute & Observe**
+   - Apply the change and run the test
+   - Capture inputs, actions taken, and observed outcomes
+   - Log structured results in `debug-log.ndjson`
+
+5. **Analyze & Conclude**
+   - Compare outcome to hypothesis
+   - If **confirmed**: Proceed to implement fix (Phase 6)
+   - If **refuted**: Log finding and formulate new hypothesis (return to Phase 2)
+   - If **inconclusive**: Refine experiment and repeat
+
+6. **Implement Fix**
+   - Once root cause confirmed, implement necessary code changes
+   - Document fix rationale in implementation.md
+   - Log fix in changes.log
+
+7. **Verify Fix**
+   - Run all relevant tests to ensure fix is effective
+   - Verify no regressions introduced
+   - Mark issue as resolved in issues.md
+
+### Debug Log Format (NDJSON)
+
+File: `.workflow/.cycle/{cycleId}.progress/cd/debug-log.ndjson`
+
+Schema:
+```json
+{
+  "timestamp": "2026-01-23T10:00:00+08:00",
+  "iteration": 1,
+  "issue_id": "BUG-001",
+  "file": "src/auth/oauth.ts",
+  "hypothesis": "OAuth token refresh fails due to expired refresh_token not handled",
+  "action": "Added logging to capture refresh_token expiry",
+  "observation": "Refresh token is expired but code doesn't check expiry before use",
+  "outcome": "confirmed"
+}
+```
+
+Outcome values: `confirmed | refuted | inconclusive`
+
+### Hypothesis Priority Order
+
+1. **Direct Error Messages/Stack Traces**: Most reliable starting point
+2. **Recent Changes**: Check `changes.log` for recent modifications
+3. **Dependency Relationships**: Analyze relationships between failing component and its dependencies
+4. **Edge Cases**: Review `edge-cases.md` for documented edge cases
+
+### Output
+
+Debug workflow generates an additional file:
+- **debug-log.ndjson**: NDJSON log of all hypothesis-test cycles
+
 ### Phase 3: Output
 
 Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
@@ -150,7 +234,7 @@ Overview of what was implemented in this iteration.
 - Code review and merge
 ```
 
-**code-changes.log** (NDJSON):
+**changes.log** (NDJSON):
 ```
 {"timestamp":"2026-01-22T10:30:00+08:00","iteration":1,"file":"src/config/oauth.ts","action":"create","task":"TASK-001","description":"Created OAuth configuration","lines_added":45,"lines_removed":0}
 {"timestamp":"2026-01-22T10:45:00+08:00","iteration":1,"file":"src/models/User.ts","action":"modify","task":"TASK-002","description":"Added oauth_id and oauth_provider fields","lines_added":8,"lines_removed":0}
@@ -190,11 +274,12 @@ Overview of what was implemented in this iteration.
 PHASE_RESULT:
 - phase: cd
 - status: success | failed | partial
-- files_written: [implementation.md, code-changes.log, issues.md]
+- files_written: [implementation.md, changes.log, debug-log.ndjson (if debug executed), issues.md]
 - summary: N tasks completed, M files modified, X blockers identified
 - tasks_completed: N
 - files_modified: M
 - tests_passing: X/Y
+- debug_cycles: Z (if debug executed)
 - blockers: []
 - issues: [list of open issues]
 ```

package/.codex/skills/parallel-dev-cycle/phases/agents/requirements-analyst.md

@@ -59,13 +59,24 @@ The Requirements Analyst maintains **a single file** (`requirements.md`) contain
    - Task description from state
    - Project tech stack and guidelines
 
-2. **Analyze Requirements**
-   - Functional requirements
-   - Non-functional requirements
+2. **Analyze Explicit Requirements**
+   - Functional requirements from user task
+   - Non-functional requirements (explicit)
    - Constraints and assumptions
    - Edge cases
 
-3. **Generate Single File**
+3. **Proactive Enhancement** (NEW - Self-Enhancement Phase)
+   - Execute enhancement strategies based on triggers
+   - Scan codebase for implied requirements
+   - Analyze peer agent outputs (EP, CD, VAS from previous iteration)
+   - Suggest associated features and NFR scaffolding
+
+4. **Consolidate & Finalize**
+   - Merge explicit requirements with proactively generated ones
+   - Mark enhanced items with "(ENHANCED v1.0.0 by RA)"
+   - Add optional "## Proactive Enhancements" section with justification
+
+5. **Generate Single File**
    - Write `requirements.md` v1.0.0
    - Include all sections in one document
    - Add version header
@@ -283,3 +294,77 @@ appendNDJSON('changes.log', {
 5. **Audit Trail**: Changes.log tracks every modification
 6. **Readability First**: File should be clear and concise
 7. **Version Markers**: Mark new items with "(NEW v1.x.0)"
+8. **Proactive Enhancement**: Always apply self-enhancement phase
+
+## Self-Enhancement Mechanism
+
+The RA agent proactively extends requirements based on context analysis.
+
+### Enhancement Triggers
+
+| Trigger | Condition | Action |
+|---------|-----------|--------|
+| **Initial Analysis** | First iteration (v1.0.0) | Expand vague or high-level requests |
+| **Implicit Context** | Key config files detected (package.json, Dockerfile, CI config) | Infer NFRs and constraints |
+| **Cross-Agent Feedback** | Previous iteration has `exploration.identified_risks`, `cd.blockers`, or `vas.test_results.failed_tests` | Cover uncovered requirements |
+
+### Enhancement Strategies
+
+1. **Codebase Analysis**
+   - Scan key project files (package.json, Dockerfile, CI/CD configs)
+   - Infer technological constraints and dependencies
+   - Identify operational requirements
+   - Example: Detecting `storybook` dependency → suggest component-driven UI process
+
+2. **Peer Output Mining**
+   - Analyze EP agent's `exploration.architecture_summary`
+   - Review CD agent's blockers and issues
+   - Examine VAS agent's `test_results.failed_tests`
+   - Formalize insights as new requirements
+
+3. **Common Feature Association**
+   - Based on functional requirements, suggest associated features
+   - Example: "build user login" → suggest "password reset", "MFA"
+   - Mark as enhancement candidates for user confirmation
+
+4. **NFR Scaffolding**
+   - For each major functional requirement, add standard NFRs
+   - Categories: Performance, Security, Scalability, Accessibility
+   - Set initial values as "TBD" to ensure consideration
+
+### Output Format for Enhanced Requirements
+
+Enhanced requirements are integrated directly into `requirements.md`:
+
+```markdown
+## Functional Requirements
+
+### FR-001: OAuth Authentication
+User can authenticate via OAuth providers.
+**Status**: Defined (v1.0.0)
+**Priority**: High
+
+### FR-002: Password Reset (ENHANCED v1.0.0 by RA)
+Users can reset their password via email link.
+**Status**: Enhanced (auto-suggested)
+**Priority**: Medium
+**Trigger**: Common Feature Association (FR-001 → password reset)
+
+---
+
+## Proactive Enhancements
+
+This section documents auto-generated requirements by the RA agent.
+
+| ID | Trigger | Strategy | Justification |
+|----|---------|----------|---------------|
+| FR-002 | FR-001 requires login | Common Feature Association | Standard auth feature set |
+| NFR-003 | package.json has `jest` | Codebase Analysis | Test framework implies testability NFR |
+```
+
+### Integration Notes
+
+- Self-enhancement is **internal to RA agent** - no orchestrator changes needed
+- Read-only access to codebase and cycle state required
+- Enhanced requirements are **transparently marked** for user review
+- User can accept, modify, or reject enhanced requirements in next iteration