claude-code-workflow 6.3.37 → 6.3.39

package/.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md

@@ -0,0 +1,391 @@
+# Coordination Protocol - Multi-Agent Communication
+
+Inter-agent communication protocols and patterns for parallel-dev-cycle skill.
+
+## Overview
+
+The coordination protocol enables four parallel agents (RA, EP, CD, VAS) to communicate efficiently while maintaining clear responsibilities and avoiding conflicts.
+
+## Communication Channels
+
+### 1. Shared State File (Primary)
+
+**Location**: `.workflow/.cycle/{cycleId}.json`
+
+All agents read from and write to the unified state file:
+
+```javascript
+// Every agent: Read fresh state at action start
+const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
+
+// Every agent: Write updated state at action end
+Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+```
+
+**Protocol**:
+- Read-Update-Write pattern (no lock needed, orchestrator serializes)
+- Timestamp all updates with ISO8601 format
+- Never delete existing data, only append
+
+### 2. Progress Markdown Files (Async Log)
+
+**Location**: `.workflow/.cycle/{cycleId}.progress/{agent}/`
+
+Each agent writes progress to dedicated markdown files:
+
+| Agent | Files |
+|-------|-------|
+| RA | requirements.md, edge-cases.md, changes.log |
+| EP | exploration.md, architecture.md, plan.json |
+| CD | implementation.md, code-changes.log, issues.md |
+| VAS | validation.md, test-results.json, coverage.md, summary.md |
+
+**Protocol**:
+- Append-only pattern (no overwrites)
+- Version each document independently
+- Include timestamp on each update
+- Maintain backward compatibility
+
+### 3. Orchestrator send_input (Synchronous)
+
+**When**: Orchestrator needs to send feedback or corrections
+
+```javascript
+// Example: CD agent receives test failure feedback
+send_input({
+  id: agents.cd,
+  message: `
+## FEEDBACK FROM VALIDATION
+
+Test failures detected: ${failures}
+
+## REQUIRED ACTION
+
+Fix the following:
+${actionItems}
+
+## NEXT STEP
+Update implementation.md with fixes, then re-run tests.
+Output PHASE_RESULT when complete.
+`
+})
+```
+
+**Protocol**:
+- Only orchestrator initiates send_input
+- Clear action items and expected output
+- Single message per iteration (no rapid-fire sends)
+
+### 4. Coordination Log
+
+**Location**: `.workflow/.cycle/{cycleId}.progress/coordination/`
+
+Centralized log for inter-agent decisions and communication:
+
+**feedback.md**:
+```markdown
+# Feedback & Coordination Log - Version X.Y.Z
+
+## Timeline
+- [10:00:00] Orchestrator: Created cycle
+- [10:05:00] RA: Requirements analysis started
+- [10:10:00] RA: Requirements completed, v1.0.0
+- [10:10:01] EP: Starting exploration (depends on RA output)
+- [10:15:00] EP: Architecture designed, plan.json v1.0.0
+- [10:15:01] CD: Starting implementation (depends on EP plan)
+- [10:30:00] CD: Implementation progressing, found blocker
+- [10:31:00] RA: Clarified requirement after CD blocker
+- [10:31:01] CD: Continuing with clarification
+- [10:40:00] CD: Implementation complete
+- [10:40:01] VAS: Starting validation
+- [10:45:00] VAS: Testing complete, found failures
+- [10:45:01] Orchestrator: Sending feedback to CD
+- [10:46:00] CD: Fixed issues
+- [10:50:00] VAS: Re-validation, all passing
+- [10:50:01] Orchestrator: Cycle complete
+
+## Decision Records
+- [10:31:00] RA Clarification: OAuth optional vs required?
+  - Decision: Optional (can use password)
+  - Rationale: More flexible for users
+  - Impact: Affects FR-003 implementation
+
+## Blockers & Resolutions
+- [10:30:00] Blocker: Database migration for existing users
+  - Reported by: CD
+  - Resolution: Set oauth_id = null for existing users
+  - Status: Resolved
+
+## Cross-Agent Dependencies
+- EP depends on: RA requirements (v1.0.0)
+- CD depends on: EP plan (v1.0.0)
+- VAS depends on: CD code changes
+```
+
+## Message Formats
+
+### Agent Status Update
+
+Each agent updates state with its status:
+
+```json
+{
+  "agents": {
+    "ra": {
+      "status": "completed",
+      "started_at": "2026-01-22T10:05:00+08:00",
+      "completed_at": "2026-01-22T10:15:00+08:00",
+      "output_files": [
+        ".workflow/.cycle/cycle-xxx.progress/ra/requirements.md",
+        ".workflow/.cycle/cycle-xxx.progress/ra/edge-cases.md",
+        ".workflow/.cycle/cycle-xxx.progress/ra/changes.log"
+      ],
+      "iterations_completed": 1
+    }
+  }
+}
+```
+
+### Feedback Message Format
+
+When orchestrator sends feedback via send_input:
+
+```text
+## FEEDBACK FROM [Agent Name]
+
+[Summary of findings or issues]
+
+## REFERENCED OUTPUT
+File: [path to agent output]
+Version: [X.Y.Z]
+
+## REQUIRED ACTION
+
+1. [Action 1 with specific details]
+2. [Action 2 with specific details]
+
+## SUCCESS CRITERIA
+
+- [ ] Item 1
+- [ ] Item 2
+
+## NEXT STEP
+[What agent should do next]
+Output PHASE_RESULT when complete.
+
+## CONTEXT
+
+Previous iteration: [N]
+Current iteration: [N+1]
+```
+
+### Phase Result Format
+
+Every agent outputs PHASE_RESULT:
+
+```text
+PHASE_RESULT:
+- phase: [ra|ep|cd|vas]
+- status: success | failed | partial
+- files_written: [list of files]
+- summary: [one-line summary]
+- [agent-specific fields]
+- issues: [list of issues if any]
+
+PHASE_DETAILS:
+[Additional details or metrics]
+```
+
+## Dependency Resolution
+
+### Build Order (Default)
+
+```
+RA (Requirements) → EP (Planning) → CD (Development) → VAS (Validation)
+       ↓                  ↓               ↓                 ↓
+   Block EP         Block CD         Block VAS         Block completion
+```
+
+### Parallel Opportunities
+
+Some phases can run in parallel:
+
+```
+RA + FrontendCode (independent)
+EP + RA (not blocking)
+CD.Task1 + CD.Task2 (if no dependencies)
+```
+
+### Dependency Tracking
+
+State file tracks dependencies:
+
+```json
+{
+  "agents": {
+    "ep": {
+      "depends_on": ["ra"],
+      "ready": true,  // RA completed
+      "can_start": true
+    },
+    "cd": {
+      "depends_on": ["ep"],
+      "ready": true,  // EP completed
+      "can_start": true
+    },
+    "vas": {
+      "depends_on": ["cd"],
+      "ready": false,  // CD not yet complete
+      "can_start": false
+    }
+  }
+}
+```
+
+## Iteration Flow with Communication
+
+### Iteration 1: Initial Execution
+
+```
+Time   Agent    Action                State Update
+──────────────────────────────────────────────────────
+10:00  Init     Create cycle          status: running
+10:05  RA       Start analysis        agents.ra.status: running
+10:10  RA       Complete (v1.0.0)     agents.ra.status: completed
+10:10  EP       Start planning        agents.ep.status: running
+       (depends on RA completion)
+10:15  EP       Complete (v1.0.0)     agents.ep.status: completed
+10:15  CD       Start development     agents.cd.status: running
+       (depends on EP completion)
+10:30  CD       Found blocker         coordination.blockers.add()
+10:31  RA       Clarify blocker       requirements.v1.1.0 created
+10:35  CD       Continue (with fix)   agents.cd.status: running
+10:40  CD       Complete              agents.cd.status: completed
+10:40  VAS      Start validation      agents.vas.status: running
+       (depends on CD completion)
+10:45  VAS      Tests failing         coordination.feedback_log.add()
+10:45  Orch     Send feedback         agents.cd.message: "Fix these tests"
+10:46  CD       Resume (send_input)   agents.cd.status: running
+10:48  CD       Fix complete          agents.cd.status: completed
+10:50  VAS      Re-validate           agents.vas.status: running
+10:55  VAS      All pass              agents.vas.status: completed
+11:00  Orch     Complete cycle        status: completed
+```
+
+## Conflict Resolution
+
+### Conflict Type 1: Unclear Requirement
+
+**Scenario**: CD needs clarification on FR-X
+
+**Resolution Flow**:
+1. CD reports blocker in issues.md
+2. Orchestrator extracts blocker
+3. Orchestrator sends message to RA
+4. RA updates requirements with clarification
+5. RA outputs new requirements.md (v1.1.0)
+6. Orchestrator sends message to CD with clarification
+7. CD resumes and continues
+
+### Conflict Type 2: Test Failure
+
+**Scenario**: VAS finds test failures
+
+**Resolution Flow**:
+1. VAS reports failures in validation.md
+2. VAS outputs test-results.json with details
+3. Orchestrator extracts failure details
+4. Orchestrator categorizes failures
+5. If blocker: Orchestrator sends to CD/RA for fixes
+6. CD/RA fix and report completion
+7. Orchestrator sends CD/VAS to retry
+8. VAS re-validates
+
+### Conflict Type 3: Plan Mismatch
+
+**Scenario**: CD realizes plan tasks are incomplete
+
+**Resolution Flow**:
+1. CD reports in issues.md
+2. Orchestrator extracts issue
+3. Orchestrator sends to EP to revise plan
+4. EP updates plan.json (v1.1.0)
+5. EP adds new tasks or dependencies
+6. Orchestrator sends to CD with updated plan
+7. CD implements remaining tasks
+
+## Escalation Path
+
+For issues that block resolution:
+
+```
+Agent Issue
+    ↓
+Agent reports blocker
+    ↓
+Orchestrator analyzes
+    ↓
+Can fix automatically?
+    ├─ Yes: send_input to agent with fix
+    └─ No: Escalate to user
+         ↓
+         User provides guidance
+         ↓
+         Orchestrator applies guidance
+         ↓
+         Resume agents
+```
+
+## Communication Best Practices
+
+1. **Clear Timestamps**: All events timestamped ISO8601 format
+2. **Structured Messages**: Use consistent format for feedback
+3. **Version Tracking**: Always include version numbers
+4. **Audit Trail**: Maintain complete log of decisions
+5. **No Direct Agent Communication**: All communication via orchestrator
+6. **Document Decisions**: Record why decisions were made
+7. **Append-Only Logs**: Never delete history
+
+## State Consistency Rules
+
+1. **Single Writer Per Field**: Only one agent updates each field
+   - RA writes: requirements, edge_cases
+   - EP writes: exploration, plan
+   - CD writes: changes, implementation
+   - VAS writes: test_results, summary
+
+2. **Read-Write Serialization**: Orchestrator ensures no conflicts
+
+3. **Version Synchronization**: All versions increment together
+   - v1.0.0 → v1.1.0 (all docs updated)
+
+4. **Timestamp Consistency**: All timestamps in state file UTC+8
+
+## Monitoring & Debugging
+
+### State Inspection
+
+```javascript
+// Check agent status
+const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
+console.log(state.agents)  // See status of all agents
+
+// Check for blockers
+console.log(state.coordination.blockers)
+
+// Check feedback history
+console.log(state.coordination.feedback_log)
+```
+
+### Log Analysis
+
+```bash
+# Check RA progress
+tail .workflow/.cycle/cycle-xxx.progress/ra/changes.log
+
+# Check CD changes
+grep "TASK-001" .workflow/.cycle/cycle-xxx.progress/cd/code-changes.log
+
+# Check coordination timeline
+tail -50 .workflow/.cycle/cycle-xxx.progress/coordination/feedback.md
+```

package/.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md

@@ -0,0 +1,330 @@
+# Document Versioning Strategy
+
+文档版本管理策略：重新创建 vs 增量更新
+
+## 推荐方案：重新创建 + 归档历史
+
+每次迭代，**完全重写**主文档，旧版本自动归档到 `history/` 目录。
+
+### 文件结构
+
+```
+.workflow/.cycle/cycle-v1-20260122-abc123.progress/
+├── ra/
+│   ├── requirements.md          # v1.2.0 (当前版本，重新创建)
+│   ├── edge-cases.md            # v1.2.0 (当前版本，重新创建)
+│   ├── changes.log              # NDJSON 完整变更历史（append-only）
+│   └── history/
+│       ├── requirements-v1.0.0.md   (归档)
+│       ├── requirements-v1.1.0.md   (归档)
+│       ├── edge-cases-v1.0.0.md     (归档)
+│       └── edge-cases-v1.1.0.md     (归档)
+├── ep/
+│   ├── exploration.md           # v1.2.0 (当前)
+│   ├── architecture.md          # v1.2.0 (当前)
+│   ├── plan.json                # v1.2.0 (当前)
+│   └── history/
+│       ├── plan-v1.0.0.json
+│       └── plan-v1.1.0.json
+├── cd/
+│   ├── implementation.md        # v1.2.0 (当前)
+│   ├── code-changes.log         # NDJSON 完整历史
+│   ├── issues.md                # 当前未解决问题
+│   └── history/
+│       ├── implementation-v1.0.0.md
+│       └── implementation-v1.1.0.md
+└── vas/
+    ├── validation.md            # v1.2.0 (当前)
+    ├── test-results.json        # v1.2.0 (当前)
+    ├── summary.md               # v1.2.0 (当前)
+    └── history/
+        ├── validation-v1.0.0.md
+        └── test-results-v1.0.0.json
+```
+
+## 文档模板优化
+
+### Requirements.md (重新创建版本)
+
+```markdown
+# Requirements Specification - v1.2.0
+
+## Document Metadata
+| Field | Value |
+|-------|-------|
+| Version | 1.2.0 |
+| Previous | 1.1.0 (Added Google OAuth) |
+| Changes | Added MFA, GitHub provider |
+| Date | 2026-01-23T10:00:00+08:00 |
+| Cycle | cycle-v1-20260122-abc123 |
+| Iteration | 3 |
+
+---
+
+## Functional Requirements
+
+### FR-001: OAuth Authentication
+**Description**: Users can log in using OAuth providers.
+
+**Supported Providers**: Google, GitHub
+
+**Priority**: High
+
+**Status**: ✓ Implemented (v1.0.0), Enhanced (v1.1.0, v1.2.0)
+
+**Success Criteria**:
+- User can click provider button
+- Redirect to provider
+- Return with valid token
+- Session created
+
+---
+
+### FR-002: Multi-Provider Support
+**Description**: System supports multiple OAuth providers simultaneously.
+
+**Providers**:
+- Google (v1.1.0)
+- GitHub (v1.2.0)
+
+**Priority**: High
+
+**Status**: ✓ Implemented
+
+---
+
+### FR-003: Multi-Factor Authentication
+**Description**: Optional MFA for enhanced security.
+
+**Method**: TOTP (Time-based One-Time Password)
+
+**Priority**: Medium
+
+**Status**: 🆕 New in v1.2.0
+
+**Success Criteria**:
+- User can enable MFA in settings
+- TOTP QR code generated
+- Verification on login
+
+---
+
+## Non-Functional Requirements
+
+### NFR-001: Performance
+Response time < 500ms for all OAuth flows.
+
+**Status**: ✓ Met (v1.0.0)
+
+---
+
+## Edge Cases
+
+### EC-001: OAuth Provider Timeout
+**Scenario**: Provider doesn't respond in 5 seconds
+
+**Expected**: Display error, offer retry
+
+**Status**: ✓ Handled
+
+---
+
+### EC-002: Invalid MFA Code (NEW v1.2.0)
+**Scenario**: User enters incorrect TOTP code
+
+**Expected**: Display error, max 3 attempts, lock after
+
+**Status**: 🔄 To be implemented
+
+---
+
+## Constraints
+- Must use existing JWT session management
+- No new database servers
+- Compatible with existing user table
+
+---
+
+## Assumptions
+- Users have access to authenticator app for MFA
+- OAuth providers are always available
+
+---
+
+## Version History Summary
+
+| Version | Date | Summary |
+|---------|------|---------|
+| 1.0.0 | 2026-01-22 | Initial OAuth login (Google only implicit) |
+| 1.1.0 | 2026-01-22 | + Explicit Google OAuth support |
+| 1.2.0 | 2026-01-23 | + GitHub provider, + MFA (current) |
+
+**Detailed History**: See `history/` directory and `changes.log`
+```
+
+### Changes.log (NDJSON - 完整历史)
+
+```jsonl
+{"timestamp":"2026-01-22T10:00:00+08:00","iteration":1,"version":"1.0.0","action":"create","type":"requirement","id":"FR-001","description":"Initial OAuth requirement"}
+{"timestamp":"2026-01-22T10:05:00+08:00","iteration":1,"version":"1.0.0","action":"create","type":"requirement","id":"NFR-001","description":"Performance requirement"}
+{"timestamp":"2026-01-22T11:00:00+08:00","iteration":2,"version":"1.1.0","action":"update","type":"requirement","id":"FR-001","description":"Clarified Google OAuth support"}
+{"timestamp":"2026-01-22T11:05:00+08:00","iteration":2,"version":"1.1.0","action":"create","type":"requirement","id":"FR-002","description":"Multi-provider support"}
+{"timestamp":"2026-01-23T10:00:00+08:00","iteration":3,"version":"1.2.0","action":"create","type":"requirement","id":"FR-003","description":"MFA requirement"}
+{"timestamp":"2026-01-23T10:05:00+08:00","iteration":3,"version":"1.2.0","action":"update","type":"requirement","id":"FR-002","description":"Added GitHub provider"}
+```
+
+## 实现流程
+
+### Agent 工作流（RA 为例）
+
+```javascript
+// ==================== RA Agent 迭代流程 ====================
+
+// 读取当前状态
+const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
+const currentVersion = state.requirements?.version || "0.0.0"
+const iteration = state.current_iteration
+
+// 如果是迭代（已有旧版本）
+if (currentVersion !== "0.0.0") {
+  // 1. 归档旧版本
+  const oldFile = `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`
+  const archiveFile = `.workflow/.cycle/${cycleId}.progress/ra/history/requirements-v${currentVersion}.md`
+
+  Copy(oldFile, archiveFile)  // 归档
+
+  // 2. 读取旧版本（可选，用于理解上下文）
+  const oldRequirements = Read(oldFile)
+
+  // 3. 读取变更历史
+  const changesLog = readNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`)
+}
+
+// 4. 生成新版本号
+const newVersion = bumpVersion(currentVersion, 'minor')  // 1.1.0 -> 1.2.0
+
+// 5. 生成新文档（完全重写）
+const newRequirements = generateRequirements({
+  version: newVersion,
+  previousVersion: currentVersion,
+  previousSummary: "Added Google OAuth support",
+  currentChanges: "Added MFA and GitHub provider",
+  iteration: iteration,
+  taskDescription: state.description,
+  changesLog: changesLog  // 用于理解历史
+})
+
+// 6. 写入新文档（覆盖旧的）
+Write(`.workflow/.cycle/${cycleId}.progress/ra/requirements.md`, newRequirements)
+
+// 7. 追加变更到 changes.log
+appendNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`, {
+  timestamp: getUtc8ISOString(),
+  iteration: iteration,
+  version: newVersion,
+  action: "create",
+  type: "requirement",
+  id: "FR-003",
+  description: "Added MFA requirement"
+})
+
+// 8. 更新状态
+state.requirements = {
+  version: newVersion,
+  output_file: `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`,
+  summary: {
+    functional_requirements: 3,
+    edge_cases: 2,
+    constraints: 3
+  }
+}
+
+Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+```
+
+## 优势对比
+
+| 方面 | 增量更新 | 重新创建 + 归档 |
+|------|----------|----------------|
+| **文档简洁性** | ❌ 越来越长 | ✅ 始终简洁 |
+| **Agent 解析** | ❌ 需要解析历史 | ✅ 只看当前版本 |
+| **维护复杂度** | ❌ 高（版本标记） | ✅ 低（直接重写） |
+| **文件大小** | ❌ 膨胀 | ✅ 固定 |
+| **历史追溯** | ✅ 在主文档 | ✅ 在 history/ + changes.log |
+| **人类可读** | ❌ 需要跳过历史 | ✅ 直接看当前 |
+| **Token 使用** | ❌ 多（读取完整历史） | ✅ 少（只读当前） |
+
+## 归档策略
+
+### 自动归档触发时机
+
+```javascript
+function shouldArchive(currentVersion, state) {
+  // 每次版本更新时归档
+  return currentVersion !== state.requirements?.version
+}
+
+function archiveOldVersion(cycleId, agent, filename, currentVersion) {
+  const currentFile = `.workflow/.cycle/${cycleId}.progress/${agent}/${filename}`
+  const archiveDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
+  const archiveFile = `${archiveDir}/${filename.replace('.', `-v${currentVersion}.`)}`
+
+  // 确保归档目录存在
+  mkdir -p ${archiveDir}
+
+  // 复制（不是移动，保持当前文件直到新版本写入）
+  Copy(currentFile, archiveFile)
+
+  console.log(`Archived ${filename} v${currentVersion} to history/`)
+}
+```
+
+### 清理策略（可选）
+
+保留最近 N 个版本，删除更老的归档：
+
+```javascript
+function cleanupArchives(cycleId, agent, keepVersions = 3) {
+  const historyDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
+  const archives = listFiles(historyDir)
+
+  // 按版本号排序
+  archives.sort((a, b) => compareVersions(extractVersion(a), extractVersion(b)))
+
+  // 删除最老的版本（保留最近 N 个）
+  if (archives.length > keepVersions) {
+    const toDelete = archives.slice(0, archives.length - keepVersions)
+    toDelete.forEach(file => Delete(`${historyDir}/${file}`))
+  }
+}
+```
+
+## Changes.log 的重要性
+
+虽然主文档重新创建，但 **changes.log (NDJSON) 永久保留完整历史**：
+
+```bash
+# 查看所有变更
+cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq .
+
+# 查看某个需求的历史
+cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.id=="FR-001")'
+
+# 按迭代查看变更
+cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.iteration==2)'
+```
+
+这样：
+- **主文档**: 清晰简洁（当前状态）
+- **Changes.log**: 完整追溯（所有历史）
+- **History/**: 快照备份（按需查看）
+
+## 推荐实施
+
+1. ✅ 采用"重新创建"策略
+2. ✅ 主文档只保留"上一版本简要说明"
+3. ✅ 自动归档到 `history/` 目录
+4. ✅ Changes.log (NDJSON) 保留完整历史
+5. ✅ 可选：保留最近 3-5 个历史版本
+
+这样既保持了文档简洁（Agent 友好），又保留了完整历史（审计友好）。