catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-11 02:33:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat: Enhance Code Developer and Requirements Analyst agents with proactive debugging and self-enhancement strategies

Browse Source
This commit is contained in:
catlog22
2026-01-23 17:41:17 +08:00
parent f363c635f5
commit 79d20add43
4 changed files with 306 additions and 459 deletions
Download Patch File Download Diff File Expand all files Collapse all files

438
.codex/skills/parallel-dev-cycle/SKILL.md
View File

@@ -7,12 +7,12 @@ argument-hint: TASK="<task description>" [--cycle-id=<id>] [--auto] [--parallel=
# Parallel Dev Cycle - Multi-Agent Development Workflow # Parallel Dev Cycle - Multi-Agent Development Workflow
Multi-agent parallel development cycle using Codex subagent pattern with four specialized workers: Multi-agent parallel development cycle using Codex subagent pattern with four specialized workers:
1. **Requirements Analysis & Extension** (RA) - 需求分析及扩展 1. **Requirements Analysis & Extension** (RA) - Requirement analysis and self-enhancement
2. **Exploration & Planning** (EP) - 探索规划 2. **Exploration & Planning** (EP) - Exploration and planning
3. **Code Development** (CD) - 代码开发 3. **Code Development** (CD) - Code development with debug strategy support
4. **Validation & Archival Summary** (VAS) - 验证及归档总结 4. **Validation & Archival Summary** (VAS) - Validation and archival summary
每个 agent **仅维护一个主文档文件**，支持版本化、自动归档、完整历史追溯。 Each agent **maintains only one main document file**, supporting versioning, automatic archival, and complete history tracking.
## Arguments ## Arguments
@@ -61,12 +61,13 @@ Multi-agent parallel development cycle using Codex subagent pattern with four sp
## Key Design Principles ## Key Design Principles
1. **Single File Per Agent**: 每个 agent 仅维护一个主文件（精简清晰） 1. **Single File Per Agent**: Each agent maintains only one main file (clean and simple)
2. **Version-Based Overwrite**: 每个版本完全重写主文件 2. **Version-Based Overwrite**: Each version completely rewrites the main file
3. **Automatic Archival**: 旧版本自动归档到 `history/` 目录 3. **Automatic Archival**: Old versions automatically archived to `history/` directory
4. **Complete Audit Trail**: Changes.log (NDJSON) 保留所有变更历史 4. **Complete Audit Trail**: Changes.log (NDJSON) preserves all change history
5. **Parallel Execution**: 四个 agent 同时工作，无需等待 5. **Parallel Execution**: Four agents work simultaneously, no waiting
6. **File References**: 使用简短文件路径而非内容传递 6. **File References**: Use short file paths instead of content passing
7. **Self-Enhancement**: RA agent proactively extends requirements based on context
## Session Structure ## Session Structure
@@ -75,439 +76,114 @@ Multi-agent parallel development cycle using Codex subagent pattern with four sp
+-- {cycleId}.json # Master state file +-- {cycleId}.json # Master state file
+-- {cycleId}.progress/ +-- {cycleId}.progress/
+-- ra/ +-- ra/
| +-- requirements.md # v1.2.0 (当前，完全重写) | +-- requirements.md # Current version (complete rewrite)
| +-- changes.log # NDJSON 完整历史（append-only） | +-- changes.log # NDJSON complete history (append-only)
| └-- history/ | └-- history/
| +-- requirements-v1.0.0.md # 归档快照 | +-- requirements-v1.0.0.md # Archived snapshot
| +-- requirements-v1.1.0.md # 归档快照 | +-- requirements-v1.1.0.md # Archived snapshot
+-- ep/ +-- ep/
| +-- plan.md # v1.2.0 (当前) | +-- plan.md # Current version
| +-- changes.log # NDJSON 完整历史 | +-- changes.log # NDJSON complete history
| └-- history/ | └-- history/
| +-- plan-v1.0.0.md | +-- plan-v1.0.0.md
| +-- plan-v1.1.0.md | +-- plan-v1.1.0.md
+-- cd/ +-- cd/
| +-- implementation.md # v1.2.0 (当前) | +-- implementation.md # Current version
| +-- changes.log # NDJSON 完整历史 | +-- debug-log.ndjson # Debug hypothesis tracking
| +-- changes.log # NDJSON complete history
| └-- history/ | └-- history/
| +-- implementation-v1.0.0.md | +-- implementation-v1.0.0.md
| +-- implementation-v1.1.0.md | +-- implementation-v1.1.0.md
+-- vas/ +-- vas/
| +-- summary.md # v1.2.0 (当前) | +-- summary.md # Current version
| +-- changes.log # NDJSON 完整历史 | +-- changes.log # NDJSON complete history
| └-- history/ | └-- history/
| +-- summary-v1.0.0.md | +-- summary-v1.0.0.md
| +-- summary-v1.1.0.md | +-- summary-v1.1.0.md
└-- coordination/ └-- coordination/
+-- timeline.md # 执行时间线 +-- timeline.md # Execution timeline
+-- decisions.log # 决策日志 +-- decisions.log # Decision log
``` ```
## State Management ## State Management
### Unified Cycle State State schema is defined in [phases/state-schema.md](phases/state-schema.md). The master state file (`{cycleId}.json`) tracks:
```json - Cycle metadata (id, title, status, iterations)
{ - Agent states (status, output files, version)
"cycle_id": "cycle-v1-20260122-abc123", - Shared context (requirements, plan, changes, test results)
"title": "Task title", - Coordination data (feedback log, decisions, blockers)
"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 ## Versioning Workflow
### 初始版本 (v1.0.0) ### Initial Version (v1.0.0)
```bash ```bash
/parallel-dev-cycle TASK="Implement OAuth login" /parallel-dev-cycle TASK="Implement OAuth login"
``` ```
生成： Generates:
``` ```
requirements.md (v1.0.0) requirements.md (v1.0.0)
plan.md (v1.0.0) plan.md (v1.0.0)
implementation.md (v1.0.0) - 如适用 implementation.md (v1.0.0) - if applicable
summary.md (v1.0.0) - 如适用 summary.md (v1.0.0) - if applicable
``` ```
### 迭代版本 (v1.1.0, v1.2.0) ### Iteration Versions (v1.1.0, v1.2.0)
```bash ```bash
/parallel-dev-cycle --cycle-id=cycle-v1-xxx --extend="Add GitHub support" /parallel-dev-cycle --cycle-id=cycle-v1-xxx --extend="Add GitHub support"
``` ```
**自动处理**： **Automatic handling**:
1. 读取当前 `requirements.md (v1.0.0)` 1. Read current `requirements.md (v1.0.0)`
2. 自动归档到 `history/requirements-v1.0.0.md` 2. Auto-archive to `history/requirements-v1.0.0.md`
3. 重新创建 `requirements.md (v1.1.0)` - 完全覆盖 3. Recreate `requirements.md (v1.1.0)` - complete overwrite
4. 追加变更到 `changes.log` (NDJSON) 4. Append changes to `changes.log` (NDJSON)
## Changes.log Format (NDJSON) ## Changes.log Format (NDJSON)
保留永久审计日志（append-only，永不删除）： Permanent audit log (append-only, never deleted):
```jsonl ```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-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: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-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 ## Usage
```bash ```bash
# 启动新循环 # Start new cycle
/parallel-dev-cycle TASK="Implement real-time notifications" /parallel-dev-cycle TASK="Implement real-time notifications"
# 继续循环 # Continue cycle
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 /parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
# 带扩展需求的迭代 # Iteration with extension
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Also add email notifications" /parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Also add email notifications"
# 自动模式 # Auto mode
/parallel-dev-cycle --auto TASK="Add OAuth authentication" /parallel-dev-cycle --auto TASK="Add OAuth authentication"
``` ```
## Key Benefits ## Key Benefits
✅ **简洁**: 每个 agent 只维护 1 个文件 + changes.log - **Simple**: Each agent maintains only 1 file + changes.log
✅ **高效**: 版本重写无需复杂版本标记 - **Efficient**: Version rewrite without complex version marking
✅ **可查**: 完整历史在 `history/` 和 `changes.log` - **Traceable**: Complete history in `history/` and `changes.log`
✅ **快速**: Agent 读取当前版本快速（不需解析历史） - **Fast**: Agent reads current version quickly (no history parsing needed)
✅ **审计**: NDJSON changes.log 完整追溯每个变更 - **Auditable**: NDJSON changes.log fully traces every change
- **Self-Enhancing**: RA agent proactively extends requirements
- **Debug-Ready**: CD agent supports hypothesis-driven debugging
## Reference Documents ## Reference Documents
| Document | Purpose | | Document | Purpose |
|----------|---------| |----------|---------|
| [phases/orchestrator.md](phases/orchestrator.md) | 协调器逻辑 | | [phases/orchestrator.md](phases/orchestrator.md) | Orchestrator logic |
| [phases/state-schema.md](phases/state-schema.md) | 状态结构 | | [phases/state-schema.md](phases/state-schema.md) | State structure definition |
| [phases/agents/](phases/agents/) | 四个 agent 角色 | | [phases/agents/](phases/agents/) | Four agent role definitions |
| [specs/coordination-protocol.md](specs/coordination-protocol.md) | 通信协议 | | [specs/coordination-protocol.md](specs/coordination-protocol.md) | Communication protocol |
| [specs/versioning-strategy.md](specs/versioning-strategy.md) | 版本管理 | | [specs/versioning-strategy.md](specs/versioning-strategy.md) | Version management |

87
.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md
View File

@@ -99,12 +99,96 @@ For each task in the plan:
- Verify integration - Verify integration
- Test error cases - Test error cases
- Check performance - Check performance
- **If tests fail**: Initiate Debug Workflow (see Debug Workflow section)
5. **Report Progress** 5. **Report Progress**
- Update implementation.md - Update implementation.md
- Log any issues or blockers - Log any issues or blockers
- Note decisions made - 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 code-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 `code-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 ### Phase 3: Output
Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`: Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
@@ -190,11 +274,12 @@ Overview of what was implemented in this iteration.
PHASE_RESULT: PHASE_RESULT:
- phase: cd - phase: cd
- status: success | failed | partial - status: success | failed | partial
- files_written: [implementation.md, code-changes.log, issues.md] - files_written: [implementation.md, code-changes.log, debug-log.ndjson (if debug executed), issues.md]
- summary: N tasks completed, M files modified, X blockers identified - summary: N tasks completed, M files modified, X blockers identified
- tasks_completed: N - tasks_completed: N
- files_modified: M - files_modified: M
- tests_passing: X/Y - tests_passing: X/Y
- debug_cycles: Z (if debug executed)
- blockers: [] - blockers: []
- issues: [list of open issues] - issues: [list of open issues]
``` ```

93
.codex/skills/parallel-dev-cycle/phases/agents/requirements-analyst.md
View File

@@ -59,13 +59,24 @@ The Requirements Analyst maintains **a single file** (`requirements.md`) contain
- Task description from state - Task description from state
- Project tech stack and guidelines - Project tech stack and guidelines
2. **Analyze Requirements** 2. **Analyze Explicit Requirements**
- Functional requirements - Functional requirements from user task
- Non-functional requirements - Non-functional requirements (explicit)
- Constraints and assumptions - Constraints and assumptions
- Edge cases - 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 - Write `requirements.md` v1.0.0
- Include all sections in one document - Include all sections in one document
- Add version header - Add version header
@@ -283,3 +294,77 @@ appendNDJSON('changes.log', {
5. **Audit Trail**: Changes.log tracks every modification 5. **Audit Trail**: Changes.log tracks every modification
6. **Readability First**: File should be clear and concise 6. **Readability First**: File should be clear and concise
7. **Version Markers**: Mark new items with "(NEW v1.x.0)" 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

147
.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md
View File

@@ -1,50 +1,51 @@
# Document Versioning Strategy # Document Versioning Strategy
文档版本管理策略：重新创建 vs 增量更新 Document version management strategy: Complete Rewrite + Archive History
## 推荐方案：重新创建 + 归档历史 ## Recommended Approach: Complete Rewrite + Archive History
每次迭代，**完全重写**主文档，旧版本自动归档到 `history/` 目录。 For each iteration, **completely rewrite** the main document, and automatically archive the old version to the `history/` directory.
### 文件结构 ### File Structure
``` ```
.workflow/.cycle/cycle-v1-20260122-abc123.progress/ .workflow/.cycle/cycle-v1-20260122-abc123.progress/
├── ra/ ├── ra/
│ ├── requirements.md # v1.2.0 (当前版本，重新创建) │ ├── requirements.md # v1.2.0 (current version, complete rewrite)
│ ├── edge-cases.md # v1.2.0 (当前版本，重新创建) │ ├── edge-cases.md # v1.2.0 (current version, complete rewrite)
│ ├── changes.log # NDJSON 完整变更历史（append-only） │ ├── changes.log # NDJSON complete change history (append-only)
│ └── history/ │ └── history/
│ ├── requirements-v1.0.0.md (归档) │ ├── requirements-v1.0.0.md (archived)
│ ├── requirements-v1.1.0.md (归档) │ ├── requirements-v1.1.0.md (archived)
│ ├── edge-cases-v1.0.0.md (归档) │ ├── edge-cases-v1.0.0.md (archived)
│ └── edge-cases-v1.1.0.md (归档) │ └── edge-cases-v1.1.0.md (archived)
├── ep/ ├── ep/
│ ├── exploration.md # v1.2.0 (当前) │ ├── exploration.md # v1.2.0 (current)
│ ├── architecture.md # v1.2.0 (当前) │ ├── architecture.md # v1.2.0 (current)
│ ├── plan.json # v1.2.0 (当前) │ ├── plan.json # v1.2.0 (current)
│ └── history/ │ └── history/
│ ├── plan-v1.0.0.json │ ├── plan-v1.0.0.json
│ └── plan-v1.1.0.json │ └── plan-v1.1.0.json
├── cd/ ├── cd/
│ ├── implementation.md # v1.2.0 (当前) │ ├── implementation.md # v1.2.0 (current)
│ ├── code-changes.log # NDJSON 完整历史 │ ├── code-changes.log # NDJSON complete history
│ ├── issues.md # 当前未解决问题 │ ├── debug-log.ndjson # Debug hypothesis tracking
│ ├── issues.md # Current unresolved issues
│ └── history/ │ └── history/
│ ├── implementation-v1.0.0.md │ ├── implementation-v1.0.0.md
│ └── implementation-v1.1.0.md │ └── implementation-v1.1.0.md
└── vas/ └── vas/
├── validation.md # v1.2.0 (当前) ├── validation.md # v1.2.0 (current)
├── test-results.json # v1.2.0 (当前) ├── test-results.json # v1.2.0 (current)
├── summary.md # v1.2.0 (当前) ├── summary.md # v1.2.0 (current)
└── history/ └── history/
├── validation-v1.0.0.md ├── validation-v1.0.0.md
└── test-results-v1.0.0.json └── test-results-v1.0.0.json
``` ```
## 文档模板优化 ## Optimized Document Template
### Requirements.md (重新创建版本) ### Requirements.md (Complete Rewrite Version)
```markdown ```markdown
# Requirements Specification - v1.2.0 # Requirements Specification - v1.2.0
@@ -162,7 +163,7 @@ Response time < 500ms for all OAuth flows.
**Detailed History**: See `history/` directory and `changes.log` **Detailed History**: See `history/` directory and `changes.log`
``` ```
### Changes.log (NDJSON - 完整历史) ### Changes.log (NDJSON - Complete History)
```jsonl ```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:00:00+08:00","iteration":1,"version":"1.0.0","action":"create","type":"requirement","id":"FR-001","description":"Initial OAuth requirement"}
@@ -173,37 +174,37 @@ Response time < 500ms for all OAuth flows.
{"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"} {"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"}
``` ```
## 实现流程 ## Implementation Flow
### Agent 工作流（RA 为例） ### Agent Workflow (RA Example)
```javascript ```javascript
// ==================== RA Agent 迭代流程 ==================== // ==================== RA Agent Iteration Flow ====================
// 读取当前状态 // Read current state
const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`)) const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
const currentVersion = state.requirements?.version || "0.0.0" const currentVersion = state.requirements?.version || "0.0.0"
const iteration = state.current_iteration const iteration = state.current_iteration
// 如果是迭代（已有旧版本） // If iteration (old version exists)
if (currentVersion !== "0.0.0") { if (currentVersion !== "0.0.0") {
// 1. 归档旧版本 // 1. Archive old version
const oldFile = `.workflow/.cycle/${cycleId}.progress/ra/requirements.md` const oldFile = `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`
const archiveFile = `.workflow/.cycle/${cycleId}.progress/ra/history/requirements-v${currentVersion}.md` const archiveFile = `.workflow/.cycle/${cycleId}.progress/ra/history/requirements-v${currentVersion}.md`
Copy(oldFile, archiveFile) // 归档 Copy(oldFile, archiveFile) // Archive
// 2. 读取旧版本（可选，用于理解上下文） // 2. Read old version (optional, for context understanding)
const oldRequirements = Read(oldFile) const oldRequirements = Read(oldFile)
// 3. 读取变更历史 // 3. Read change history
const changesLog = readNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`) const changesLog = readNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`)
} }
// 4. 生成新版本号 // 4. Generate new version number
const newVersion = bumpVersion(currentVersion, 'minor') // 1.1.0 -> 1.2.0 const newVersion = bumpVersion(currentVersion, 'minor') // 1.1.0 -> 1.2.0
// 5. 生成新文档（完全重写） // 5. Generate new document (complete rewrite)
const newRequirements = generateRequirements({ const newRequirements = generateRequirements({
version: newVersion, version: newVersion,
previousVersion: currentVersion, previousVersion: currentVersion,
@@ -211,13 +212,13 @@ const newRequirements = generateRequirements({
currentChanges: "Added MFA and GitHub provider", currentChanges: "Added MFA and GitHub provider",
iteration: iteration, iteration: iteration,
taskDescription: state.description, taskDescription: state.description,
changesLog: changesLog // 用于理解历史 changesLog: changesLog // For understanding history
}) })
// 6. 写入新文档（覆盖旧的） // 6. Write new document (overwrite old)
Write(`.workflow/.cycle/${cycleId}.progress/ra/requirements.md`, newRequirements) Write(`.workflow/.cycle/${cycleId}.progress/ra/requirements.md`, newRequirements)
// 7. 追加变更到 changes.log // 7. Append change to changes.log
appendNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`, { appendNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`, {
timestamp: getUtc8ISOString(), timestamp: getUtc8ISOString(),
iteration: iteration, iteration: iteration,
@@ -228,7 +229,7 @@ appendNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`, {
description: "Added MFA requirement" description: "Added MFA requirement"
}) })
// 8. 更新状态 // 8. Update state
state.requirements = { state.requirements = {
version: newVersion, version: newVersion,
output_file: `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`, output_file: `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`,
@@ -242,25 +243,25 @@ state.requirements = {
Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2)) Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
``` ```
## 优势对比 ## Advantages Comparison
| 方面 | 增量更新 | 重新创建 + 归档 | | Aspect | Incremental Update | Complete Rewrite + Archive |
|------|----------|----------------| |--------|-------------------|---------------------------|
| **文档简洁性** | ❌ 越来越长 | ✅ 始终简洁 | | **Document Conciseness** | ❌ Gets longer | ✅ Always concise |
| **Agent 解析** | ❌ 需要解析历史 | ✅ 只看当前版本 | | **Agent Parsing** | ❌ Must parse history | ✅ Only read current version |
| **维护复杂度** | ❌ 高（版本标记） | ✅ 低（直接重写） | | **Maintenance Complexity** | ❌ High (version marking) | ✅ Low (direct rewrite) |
| **文件大小** | ❌ 膨胀 | ✅ 固定 | | **File Size** | ❌ Bloats | ✅ Fixed |
| **历史追溯** | ✅ 在主文档 | ✅ 在 history/ + changes.log | | **History Tracking** | ✅ In main document | ✅ In history/ + changes.log |
| **人类可读** | ❌ 需要跳过历史 | ✅ 直接看当前 | | **Human Readability** | ❌ Must skip history | ✅ Direct current view |
| **Token 使用** | ❌ 多（读取完整历史） | ✅ 少（只读当前） | | **Token Usage** | ❌ More (read complete history) | ✅ Less (only read current) |
## 归档策略 ## Archive Strategy
### 自动归档触发时机 ### Auto-Archive Trigger
```javascript ```javascript
function shouldArchive(currentVersion, state) { function shouldArchive(currentVersion, state) {
// 每次版本更新时归档 // Archive on each version update
return currentVersion !== state.requirements?.version return currentVersion !== state.requirements?.version
} }
@@ -269,29 +270,29 @@ function archiveOldVersion(cycleId, agent, filename, currentVersion) {
const archiveDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history` const archiveDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
const archiveFile = `${archiveDir}/${filename.replace('.', `-v${currentVersion}.`)}` const archiveFile = `${archiveDir}/${filename.replace('.', `-v${currentVersion}.`)}`
// 确保归档目录存在 // Ensure archive directory exists
mkdir -p ${archiveDir} mkdir -p ${archiveDir}
// 复制（不是移动，保持当前文件直到新版本写入） // Copy (not move, keep current file until new version written)
Copy(currentFile, archiveFile) Copy(currentFile, archiveFile)
console.log(`Archived ${filename} v${currentVersion} to history/`) console.log(`Archived ${filename} v${currentVersion} to history/`)
} }
``` ```
### 清理策略（可选） ### Cleanup Strategy (Optional)
保留最近 N 个版本，删除更老的归档： Keep most recent N versions, delete older archives:
```javascript ```javascript
function cleanupArchives(cycleId, agent, keepVersions = 3) { function cleanupArchives(cycleId, agent, keepVersions = 3) {
const historyDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history` const historyDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
const archives = listFiles(historyDir) const archives = listFiles(historyDir)
// 按版本号排序 // Sort by version number
archives.sort((a, b) => compareVersions(extractVersion(a), extractVersion(b))) archives.sort((a, b) => compareVersions(extractVersion(a), extractVersion(b)))
// 删除最老的版本（保留最近 N 个） // Delete oldest versions (keep most recent N)
if (archives.length > keepVersions) { if (archives.length > keepVersions) {
const toDelete = archives.slice(0, archives.length - keepVersions) const toDelete = archives.slice(0, archives.length - keepVersions)
toDelete.forEach(file => Delete(`${historyDir}/${file}`)) toDelete.forEach(file => Delete(`${historyDir}/${file}`))
@@ -299,32 +300,32 @@ function cleanupArchives(cycleId, agent, keepVersions = 3) {
} }
``` ```
## Changes.log 的重要性 ## Importance of Changes.log
虽然主文档重新创建，但 **changes.log (NDJSON) 永久保留完整历史**： Although main document is completely rewritten, **changes.log (NDJSON) permanently preserves complete history**:
```bash ```bash
# 查看所有变更 # View all changes
cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq . cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq .
# 查看某个需求的历史 # View history of specific requirement
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(.id=="FR-001")'
# 按迭代查看变更 # View changes by iteration
cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.iteration==2)' cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.iteration==2)'
``` ```
这样： This way:
- **主文档**: 清晰简洁（当前状态） - **Main Document**: Clear and concise (current state)
- **Changes.log**: 完整追溯（所有历史） - **Changes.log**: Complete traceability (all history)
- **History/**: 快照备份（按需查看） - **History/**: Snapshot backups (view on demand)
## 推荐实施 ## Recommended Implementation
1. ✅ 采用"重新创建"策略 1. ✅ Adopt "Complete Rewrite" strategy
2. ✅ 主文档只保留"上一版本简要说明" 2. ✅ Main document only keeps "previous version summary"
3. ✅ 自动归档到 `history/` 目录 3. ✅ Auto-archive to `history/` directory
4. ✅ Changes.log (NDJSON) 保留完整历史 4. ✅ Changes.log (NDJSON) preserves complete history
5. ✅ 可选：保留最近 3-5 个历史版本 5. ✅ Optional: Keep most recent 3-5 historical versions
这样既保持了文档简洁（Agent 友好），又保留了完整历史（审计友好）。 This approach keeps documents concise (agent-friendly) while preserving complete history (audit-friendly).