claude-code-workflow 6.3.42 → 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)
-   └─ Create batches by size (max 3 per batch by default)
+   └─ 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,17 +119,11 @@ if (useAllPending) {
 }
 // Note: Agent fetches full issue content via `ccw issue status <id> --json`
 
-// Simple size-based batching (max batchSize issues per group)
-function createBatches(issues, batchSize) {
-  const batches = [];
-  for (let i = 0; i < issues.length; i += batchSize) {
-    batches.push(issues.slice(i, i + batchSize));
-  }
-  return batches;
-}
+// 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 = createBatches(issues, batchSize);
-console.log(`Processing ${issues.length} issues in ${batches.length} batch(es) (max ${batchSize} issues/agent)`);
+console.log(`Processing ${issues.length} issues in ${batches.length} batch(es)`);
 
 TodoWrite({
   todos: batches.map((_, i) => ({

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