mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-28 20:01:17 +08:00
feat: Add communication optimization and coordination protocol for multi-agent system
- Introduced a new specification for agent communication optimization focusing on file references instead of content transfer to enhance efficiency and reduce message size. - Established a coordination protocol detailing communication channels, message formats, and dependency resolution strategies among agents (RA, EP, CD, VAS). - Created a unified progress format specification for all agents, standardizing documentation structure and versioning practices.
This commit is contained in:
catlog22
512
.codex/skills/parallel-dev-cycle/SKILL.md
Normal file
512
.codex/skills/parallel-dev-cycle/SKILL.md
Normal file
@@ -0,0 +1,512 @@
|
||||
---
|
||||
description: Multi-agent parallel development cycle with requirement analysis, exploration planning, code development, and validation. Supports continuous iteration with markdown progress documentation.
|
||||
argument-hint: TASK="<task description>" [--cycle-id=<id>] [--auto] [--parallel=<count>]
|
||||
---
|
||||
|
||||
# Parallel Dev Cycle - Multi-Agent Development Workflow
|
||||
|
||||
Multi-agent parallel development cycle using Codex subagent pattern with four specialized workers:
|
||||
1. **Requirements Analysis & Extension** (RA) - 需求分析及扩展
|
||||
2. **Exploration & Planning** (EP) - 探索规划
|
||||
3. **Code Development** (CD) - 代码开发
|
||||
4. **Validation & Archival Summary** (VAS) - 验证及归档总结
|
||||
|
||||
每个 agent **仅维护一个主文档文件**，支持版本化、自动归档、完整历史追溯。
|
||||
|
||||
## Arguments
|
||||
|
||||
| Arg | Required | Description |
|
||||
|-----|----------|-------------|
|
||||
| TASK | No | Task description (for new cycle, mutually exclusive with --cycle-id) |
|
||||
| --cycle-id | No | Existing cycle ID to continue (from API or previous session) |
|
||||
| --auto | No | Auto-cycle mode (run all phases sequentially) |
|
||||
| --parallel | No | Number of parallel agents (default: 4, max: 4) |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ User Input (Task) │
|
||||
└────────────────────────────┬────────────────────────────────┘
|
||||
│
|
||||
v
|
||||
┌──────────────────────┐
|
||||
│ Orchestrator Agent │ (Coordinator)
|
||||
│ (spawned once) │
|
||||
└──────────────────────┘
|
||||
│
|
||||
┌────────────────────┼────────────────────┐
|
||||
│ │ │
|
||||
v v v
|
||||
┌────────┐ ┌────────┐ ┌────────┐
|
||||
│ RA │ │ EP │ │ CD │
|
||||
│Agent │ │Agent │ │Agent │
|
||||
└────────┘ └────────┘ └────────┘
|
||||
│ │ │
|
||||
└────────────────────┼────────────────────┘
|
||||
│
|
||||
v
|
||||
┌────────┐
|
||||
│ VAS │
|
||||
│ Agent │
|
||||
└────────┘
|
||||
│
|
||||
v
|
||||
┌──────────────────────┐
|
||||
│ Summary Report │
|
||||
│ & Markdown Docs │
|
||||
└──────────────────────┘
|
||||
```
|
||||
|
||||
## Key Design Principles
|
||||
|
||||
1. **Single File Per Agent**: 每个 agent 仅维护一个主文件（精简清晰）
|
||||
2. **Version-Based Overwrite**: 每个版本完全重写主文件
|
||||
3. **Automatic Archival**: 旧版本自动归档到 `history/` 目录
|
||||
4. **Complete Audit Trail**: Changes.log (NDJSON) 保留所有变更历史
|
||||
5. **Parallel Execution**: 四个 agent 同时工作，无需等待
|
||||
6. **File References**: 使用简短文件路径而非内容传递
|
||||
|
||||
## Session Structure
|
||||
|
||||
```
|
||||
.workflow/.cycle/
|
||||
+-- {cycleId}.json # Master state file
|
||||
+-- {cycleId}.progress/
|
||||
+-- ra/
|
||||
| +-- requirements.md # v1.2.0 (当前，完全重写)
|
||||
| +-- changes.log # NDJSON 完整历史（append-only）
|
||||
| └-- history/
|
||||
| +-- requirements-v1.0.0.md # 归档快照
|
||||
| +-- requirements-v1.1.0.md # 归档快照
|
||||
+-- ep/
|
||||
| +-- plan.md # v1.2.0 (当前)
|
||||
| +-- changes.log # NDJSON 完整历史
|
||||
| └-- history/
|
||||
| +-- plan-v1.0.0.md
|
||||
| +-- plan-v1.1.0.md
|
||||
+-- cd/
|
||||
| +-- implementation.md # v1.2.0 (当前)
|
||||
| +-- changes.log # NDJSON 完整历史
|
||||
| └-- history/
|
||||
| +-- implementation-v1.0.0.md
|
||||
| +-- implementation-v1.1.0.md
|
||||
+-- vas/
|
||||
| +-- summary.md # v1.2.0 (当前)
|
||||
| +-- changes.log # NDJSON 完整历史
|
||||
| └-- history/
|
||||
| +-- summary-v1.0.0.md
|
||||
| +-- summary-v1.1.0.md
|
||||
└-- coordination/
|
||||
+-- timeline.md # 执行时间线
|
||||
+-- decisions.log # 决策日志
|
||||
```
|
||||
|
||||
## State Management
|
||||
|
||||
### Unified Cycle State
|
||||
|
||||
```json
|
||||
{
|
||||
"cycle_id": "cycle-v1-20260122-abc123",
|
||||
"title": "Task title",
|
||||
"status": "running",
|
||||
"current_iteration": 2,
|
||||
"current_phase": "cd",
|
||||
|
||||
"agents": {
|
||||
"ra": {
|
||||
"status": "completed",
|
||||
"version": "1.2.0",
|
||||
"output_file": ".workflow/.cycle/cycle-v1-xxx.progress/ra/requirements.md",
|
||||
"summary": { "requirements": 10, "edge_cases": 5 }
|
||||
},
|
||||
"ep": {
|
||||
"status": "completed",
|
||||
"version": "1.2.0",
|
||||
"output_file": ".workflow/.cycle/cycle-v1-xxx.progress/ep/plan.md",
|
||||
"summary": { "tasks": 8, "critical_path": 4 }
|
||||
},
|
||||
"cd": {
|
||||
"status": "running",
|
||||
"version": "1.1.0",
|
||||
"output_file": ".workflow/.cycle/cycle-v1-xxx.progress/cd/implementation.md",
|
||||
"summary": { "completed_tasks": 3, "files_modified": 5 }
|
||||
},
|
||||
"vas": {
|
||||
"status": "idle",
|
||||
"version": "0.0.0",
|
||||
"output_file": null
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Agent Output Format
|
||||
|
||||
### RA: requirements.md (单文件完整输出)
|
||||
|
||||
```markdown
|
||||
# Requirements Specification - v1.2.0
|
||||
|
||||
## Document Status
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version** | 1.2.0 |
|
||||
| **Previous Version** | 1.1.0 (Added Google OAuth) |
|
||||
| **This Version** | Added MFA support, GitHub provider |
|
||||
| **Iteration** | 3 |
|
||||
| **Updated** | 2026-01-23T10:00:00+08:00 |
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements
|
||||
- FR-001: OAuth authentication via Google/GitHub (v1.0.0, enhanced v1.1.0-1.2.0)
|
||||
- FR-002: Multi-provider support (v1.1.0)
|
||||
- FR-003: MFA/TOTP support (NEW v1.2.0)
|
||||
|
||||
## Non-Functional Requirements
|
||||
- NFR-001: Response time < 500ms
|
||||
- NFR-002: Support 1000 concurrent users
|
||||
|
||||
## Edge Cases
|
||||
- EC-001: OAuth timeout → Fallback retry
|
||||
- EC-002: Invalid TOTP → Max 3 attempts (NEW v1.2.0)
|
||||
|
||||
## Success Criteria
|
||||
- [ ] All FRs implemented
|
||||
- [ ] NFRs validated
|
||||
- [ ] Coverage > 80%
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Initial OAuth |
|
||||
| 1.1.0 | 2026-01-22 | + Google OAuth |
|
||||
| 1.2.0 | 2026-01-23 | + GitHub, + MFA (current) |
|
||||
|
||||
For detailed history, see `history/` and `changes.log`
|
||||
```
|
||||
|
||||
### EP: plan.md (单文件完整输出)
|
||||
|
||||
```markdown
|
||||
# Implementation Plan - v1.2.0
|
||||
|
||||
## Plan Status
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version** | 1.2.0 |
|
||||
| **Previous** | 1.1.0 (Added GitHub integration) |
|
||||
| **This Version** | Added MFA tasks (current) |
|
||||
| **Total Tasks** | 10 |
|
||||
| **Estimated Hours** | 20 |
|
||||
|
||||
---
|
||||
|
||||
## Architecture Highlights
|
||||
- OAuth: passport-oauth2 library
|
||||
- Providers: Google, GitHub
|
||||
- Providers: Store in User.oauth_id, oauth_provider
|
||||
- MFA: TOTP-based (NEW v1.2.0)
|
||||
|
||||
---
|
||||
|
||||
## Implementation Tasks
|
||||
### Phase 1: Foundation (TASK-001-003)
|
||||
- TASK-001: Setup OAuth config (1h, small)
|
||||
- TASK-002: Update User model (2h, medium)
|
||||
- TASK-003: Google OAuth strategy (4h, large)
|
||||
|
||||
### Phase 2: Multi-Provider (TASK-004-005)
|
||||
- TASK-004: GitHub OAuth strategy (3h, medium) [NEW v1.2.0]
|
||||
- TASK-005: Provider selection UI (2h, medium)
|
||||
|
||||
### Phase 3: MFA (TASK-006-008) [NEW v1.2.0]
|
||||
- TASK-006: TOTP setup endpoint (3h, medium)
|
||||
- TASK-007: TOTP verification (2h, medium)
|
||||
- TASK-008: Recovery codes (1h, small)
|
||||
|
||||
### Phase 4: Testing & Docs (TASK-009-010)
|
||||
- TASK-009: Integration tests (4h, large)
|
||||
- TASK-010: Documentation (2h, medium)
|
||||
|
||||
---
|
||||
|
||||
## Critical Path
|
||||
1. TASK-001 → TASK-002 → TASK-003 → TASK-005
|
||||
2. TASK-006 → TASK-007 → TASK-008 → TASK-009
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
- Location: src/middleware/auth.ts
|
||||
- Database: User table oauth_* columns
|
||||
- Frontend: login.tsx OAuth buttons
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Basic OAuth plan |
|
||||
| 1.1.0 | 2026-01-22 | + GitHub task |
|
||||
| 1.2.0 | 2026-01-23 | + MFA tasks (current) |
|
||||
```
|
||||
|
||||
### CD: implementation.md (单文件完整输出)
|
||||
|
||||
```markdown
|
||||
# Implementation Progress - v1.1.0
|
||||
|
||||
## Progress Status
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Version** | 1.1.0 |
|
||||
| **Previous** | 1.0.0 (Initial OAuth) |
|
||||
| **This Version** | GitHub OAuth support (current) |
|
||||
| **Iteration** | 2 |
|
||||
| **Updated** | 2026-01-23T09:30:00+08:00 |
|
||||
|
||||
---
|
||||
|
||||
## Completed Tasks
|
||||
- ✓ TASK-001: Setup OAuth config (1h)
|
||||
- ✓ TASK-002: Update User model (2h)
|
||||
- ✓ TASK-003: Google OAuth strategy (4h)
|
||||
- ✓ TASK-004: GitHub OAuth strategy (3h) [NEW v1.1.0]
|
||||
|
||||
## In Progress
|
||||
- 🔄 TASK-005: Provider selection UI (50% complete)
|
||||
|
||||
## Next Tasks
|
||||
- ☐ TASK-006: TOTP setup (v1.2.0)
|
||||
- ☐ Tests & documentation
|
||||
|
||||
---
|
||||
|
||||
## Files Modified
|
||||
| File | Action | Description |
|
||||
|------|--------|-------------|
|
||||
| src/config/oauth.ts | create | OAuth config (45 lines) |
|
||||
| src/strategies/oauth-google.ts | create | Google strategy (120 lines) |
|
||||
| src/strategies/oauth-github.ts | create | GitHub strategy (100 lines) [NEW v1.1.0] |
|
||||
| src/models/User.ts | modify | +oauth_id, oauth_provider (8 lines) |
|
||||
| src/routes/auth.ts | modify | +/auth/google, /auth/github (+75 lines) |
|
||||
|
||||
---
|
||||
|
||||
## Key Decisions Made
|
||||
1. **OAuth Library**: passport-oauth2 (mature, well-maintained)
|
||||
2. **Token Storage**: Database (for refresh tokens)
|
||||
3. **Provider Selection**: Buttons on login page
|
||||
|
||||
---
|
||||
|
||||
## Issues & Blockers
|
||||
### Current
|
||||
- None
|
||||
|
||||
### Resolved (v1.0.0 → v1.1.0)
|
||||
- ✓ OAuth callback URL validation (fixed)
|
||||
- ✓ CORS issues (headers updated)
|
||||
|
||||
---
|
||||
|
||||
## Testing Status
|
||||
| Test Type | v1.0.0 | v1.1.0 |
|
||||
|-----------|--------|--------|
|
||||
| Unit | 20/20 ✓ | 25/25 ✓ |
|
||||
| Integration | 8/10 ⚠ | 12/14 ⚠ |
|
||||
| E2E | 3/5 ⚠ | 5/8 ⚠ |
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Google OAuth implementation |
|
||||
| 1.1.0 | 2026-01-23 | + GitHub OAuth (current) |
|
||||
```
|
||||
|
||||
### VAS: summary.md (单文件完整输出)
|
||||
|
||||
```markdown
|
||||
# Validation & Summary Report - v1.0.0
|
||||
|
||||
## Validation Status
|
||||
| Metric | Value | Target | Status |
|
||||
|--------|-------|--------|--------|
|
||||
| **Test Pass Rate** | 92% | 90% | ✓ |
|
||||
| **Code Coverage** | 87% | 80% | ✓ |
|
||||
| **Requirements Met** | 3/3 | 100% | ✓ |
|
||||
| **Critical Issues** | 0 | 0 | ✓ |
|
||||
| **Production Ready** | YES | - | ✓ |
|
||||
|
||||
---
|
||||
|
||||
## Test Execution Results
|
||||
- **Total Tests**: 50
|
||||
- **Passed**: 46 (92%)
|
||||
- **Failed**: 4 (8%)
|
||||
- **Duration**: 2m 34s
|
||||
|
||||
### Failures
|
||||
1. **oauth-refresh**: Expected token refresh, got error
|
||||
- Severity: Medium
|
||||
- Recommendation: Handle expired refresh tokens (v1.1.0 task)
|
||||
|
||||
2. **concurrent-login**: Race condition in session writes
|
||||
- Severity: High
|
||||
- Recommendation: Add mutex for session writes (v1.1.0 task)
|
||||
|
||||
3. **github-provider**: Timeout on provider response
|
||||
- Severity: Medium
|
||||
- Recommendation: Add retry logic with backoff
|
||||
|
||||
4. **totp-edge-case**: Invalid TOTP timing window
|
||||
- Severity: Low
|
||||
- Recommendation: Expand timing window by ±30s
|
||||
|
||||
---
|
||||
|
||||
## Code Coverage Analysis
|
||||
- **Overall**: 87% (target: 80%) ✓
|
||||
- **OAuth Module**: 95%
|
||||
- **Routes**: 82%
|
||||
- **User Model**: 78%
|
||||
|
||||
### Gaps
|
||||
- Error recovery paths (15% uncovered)
|
||||
- Concurrent request handling (20% uncovered)
|
||||
|
||||
---
|
||||
|
||||
## Requirements Verification
|
||||
- ✓ FR-001: OAuth authentication (100% implemented)
|
||||
- ✓ FR-002: Multi-provider support (Google: 100%, GitHub: 95%)
|
||||
- ⚠ FR-003: MFA support (0% - planned v1.2.0)
|
||||
|
||||
- ✓ NFR-001: Response time < 500ms (avg 245ms)
|
||||
- ✓ NFR-002: Handle 100 concurrent (sustained 120)
|
||||
|
||||
---
|
||||
|
||||
## Known Issues Summary
|
||||
1. **MEDIUM**: OAuth refresh token edge case
|
||||
- Impact: Users may need re-auth
|
||||
- Status: Will fix in v1.1.0
|
||||
|
||||
2. **MEDIUM**: GitHub provider timeout
|
||||
- Impact: Occasional login failures
|
||||
- Status: Will fix in v1.1.0
|
||||
|
||||
---
|
||||
|
||||
## Deliverables Checklist
|
||||
- ✓ Code implementation complete
|
||||
- ✓ Unit tests written (20/20)
|
||||
- ✓ Integration tests written (12/14)
|
||||
- ✓ Documentation updated
|
||||
- ✓ Security review: PASSED
|
||||
- ✓ Performance benchmarks: MET
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
1. **For v1.1.0**: Fix refresh token and concurrent login issues
|
||||
2. **For v1.2.0**: Implement MFA/TOTP support
|
||||
3. **For v1.3.0**: Add provider error recovery
|
||||
4. **General**: Increase timeout tolerances
|
||||
|
||||
---
|
||||
|
||||
## Sign-Off
|
||||
- **Status**: ✓ APPROVED FOR PRODUCTION
|
||||
- **Validating Agent**: VAS-v1.0.0
|
||||
- **Timestamp**: 2026-01-22T12:00:00+08:00
|
||||
- **By**: Validation & Archival Specialist
|
||||
|
||||
---
|
||||
|
||||
## History Summary
|
||||
| Version | Date | Summary |
|
||||
|---------|------|---------|
|
||||
| 1.0.0 | 2026-01-22 | Initial validation report (current) |
|
||||
```
|
||||
|
||||
## Versioning Workflow
|
||||
|
||||
### 初始版本 (v1.0.0)
|
||||
|
||||
```bash
|
||||
/parallel-dev-cycle TASK="Implement OAuth login"
|
||||
```
|
||||
|
||||
生成：
|
||||
```
|
||||
requirements.md (v1.0.0)
|
||||
plan.md (v1.0.0)
|
||||
implementation.md (v1.0.0) - 如适用
|
||||
summary.md (v1.0.0) - 如适用
|
||||
```
|
||||
|
||||
### 迭代版本 (v1.1.0, v1.2.0)
|
||||
|
||||
```bash
|
||||
/parallel-dev-cycle --cycle-id=cycle-v1-xxx --extend="Add GitHub support"
|
||||
```
|
||||
|
||||
**自动处理**：
|
||||
1. 读取当前 `requirements.md (v1.0.0)`
|
||||
2. 自动归档到 `history/requirements-v1.0.0.md`
|
||||
3. 重新创建 `requirements.md (v1.1.0)` - 完全覆盖
|
||||
4. 追加变更到 `changes.log` (NDJSON)
|
||||
|
||||
## Changes.log Format (NDJSON)
|
||||
|
||||
保留永久审计日志（append-only，永不删除）：
|
||||
|
||||
```jsonl
|
||||
{"timestamp":"2026-01-22T10:00:00+08:00","version":"1.0.0","agent":"ra","action":"create","change":"Initial requirements","iteration":1}
|
||||
{"timestamp":"2026-01-22T11:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth requirement","iteration":2}
|
||||
{"timestamp":"2026-01-22T11:30:00+08:00","version":"1.0.0","agent":"ep","action":"create","change":"Initial implementation plan","iteration":1}
|
||||
{"timestamp":"2026-01-22T12:00:00+08:00","version":"1.1.0","agent":"ep","action":"update","change":"Added GitHub OAuth tasks","iteration":2}
|
||||
{"timestamp":"2026-01-22T13:00:00+08:00","version":"1.0.0","agent":"cd","action":"create","change":"Started OAuth implementation","iteration":1}
|
||||
```
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# 启动新循环
|
||||
/parallel-dev-cycle TASK="Implement real-time notifications"
|
||||
|
||||
# 继续循环
|
||||
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
|
||||
|
||||
# 带扩展需求的迭代
|
||||
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Also add email notifications"
|
||||
|
||||
# 自动模式
|
||||
/parallel-dev-cycle --auto TASK="Add OAuth authentication"
|
||||
```
|
||||
|
||||
## Key Benefits
|
||||
|
||||
✅ **简洁**: 每个 agent 只维护 1 个文件 + changes.log
|
||||
✅ **高效**: 版本重写无需复杂版本标记
|
||||
✅ **可查**: 完整历史在 `history/` 和 `changes.log`
|
||||
✅ **快速**: Agent 读取当前版本快速（不需解析历史）
|
||||
✅ **审计**: NDJSON changes.log 完整追溯每个变更
|
||||
|
||||
## Reference Documents
|
||||
|
||||
| Document | Purpose |
|
||||
|----------|---------|
|
||||
| [phases/orchestrator.md](phases/orchestrator.md) | 协调器逻辑 |
|
||||
| [phases/state-schema.md](phases/state-schema.md) | 状态结构 |
|
||||
| [phases/agents/](phases/agents/) | 四个 agent 角色 |
|
||||
| [specs/coordination-protocol.md](specs/coordination-protocol.md) | 通信协议 |
|
||||
| [specs/versioning-strategy.md](specs/versioning-strategy.md) | 版本管理 |
|
||||
Reference in New Issue
Block a user