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

2026-02-05 01:50:27 +08:00 · 2026-01-23 17:41:17 +08:00
parent f363c635f5
commit 79d20add43
4 changed files with 306 additions and 459 deletions
--- a/.codex/skills/parallel-dev-cycle/SKILL.md
+++ b/.codex/skills/parallel-dev-cycle/SKILL.md
@@ -7,12 +7,12 @@ argument-hint: TASK="<task description>" [--cycle-id=<id>] [--auto] [--parallel=
 # 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) - 验证及归档总结
+1. **Requirements Analysis & Extension** (RA) - Requirement analysis and self-enhancement
+2. **Exploration & Planning** (EP) - Exploration and planning
+3. **Code Development** (CD) - Code development with debug strategy support
+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

@@ -61,12 +61,13 @@ Multi-agent parallel development cycle using Codex subagent pattern with four sp

 ## 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**: 使用简短文件路径而非内容传递
+1. **Single File Per Agent**: Each agent maintains only one main file (clean and simple)
+2. **Version-Based Overwrite**: Each version completely rewrites the main file
+3. **Automatic Archival**: Old versions automatically archived to `history/` directory
+4. **Complete Audit Trail**: Changes.log (NDJSON) preserves all change history
+5. **Parallel Execution**: Four agents work simultaneously, no waiting
+6. **File References**: Use short file paths instead of content passing
+7. **Self-Enhancement**: RA agent proactively extends requirements based on context

 ## Session Structure

@@ -75,439 +76,114 @@ Multi-agent parallel development cycle using Codex subagent pattern with four sp
 +-- {cycleId}.json                                 # Master state file
 +-- {cycleId}.progress/
    +-- ra/
-    |   +-- requirements.md                        # v1.2.0 (当前，完全重写)
-    |   +-- changes.log                            # NDJSON 完整历史（append-only）
+    |   +-- requirements.md                        # Current version (complete rewrite)
+    |   +-- changes.log                            # NDJSON complete history (append-only)
    |   └-- history/
-    |       +-- requirements-v1.0.0.md             # 归档快照
-    |       +-- requirements-v1.1.0.md             # 归档快照
+    |       +-- requirements-v1.0.0.md             # Archived snapshot
+    |       +-- requirements-v1.1.0.md             # Archived snapshot
    +-- ep/
-    |   +-- plan.md                                # v1.2.0 (当前)
-    |   +-- changes.log                            # NDJSON 完整历史
+    |   +-- plan.md                                # Current version
+    |   +-- changes.log                            # NDJSON complete history
    |   └-- history/
    |       +-- plan-v1.0.0.md
    |       +-- plan-v1.1.0.md
    +-- cd/
-    |   +-- implementation.md                      # v1.2.0 (当前)
-    |   +-- changes.log                            # NDJSON 完整历史
+    |   +-- implementation.md                      # Current version
+    |   +-- debug-log.ndjson                       # Debug hypothesis tracking
+    |   +-- changes.log                            # NDJSON complete history
    |   └-- history/
    |       +-- implementation-v1.0.0.md
    |       +-- implementation-v1.1.0.md
    +-- vas/
-    |   +-- summary.md                             # v1.2.0 (当前)
-    |   +-- changes.log                            # NDJSON 完整历史
+    |   +-- summary.md                             # Current version
+    |   +-- changes.log                            # NDJSON complete history
    |   └-- history/
    |       +-- summary-v1.0.0.md
    |       +-- summary-v1.1.0.md
    └-- coordination/
-        +-- timeline.md                            # 执行时间线
-        +-- decisions.log                          # 决策日志
+        +-- timeline.md                            # Execution timeline
+        +-- decisions.log                          # Decision log
 ```

 ## 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_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) |
-```
+- Cycle metadata (id, title, status, iterations)
+- Agent states (status, output files, version)
+- Shared context (requirements, plan, changes, test results)
+- Coordination data (feedback log, decisions, blockers)

 ## Versioning Workflow

-### 初始版本 (v1.0.0)
+### Initial Version (v1.0.0)

 ```bash
 /parallel-dev-cycle TASK="Implement OAuth login"
 ```

-生成：
+Generates:
 ```
 requirements.md (v1.0.0)
 plan.md (v1.0.0)
-implementation.md (v1.0.0) - 如适用
-summary.md (v1.0.0) - 如适用
+implementation.md (v1.0.0) - if applicable
+summary.md (v1.0.0) - if applicable
 ```

-### 迭代版本 (v1.1.0, v1.2.0)
+### Iteration Versions (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)
+**Automatic handling**:
+1. Read current `requirements.md (v1.0.0)`
+2. Auto-archive to `history/requirements-v1.0.0.md`
+3. Recreate `requirements.md (v1.1.0)` - complete overwrite
+4. Append changes to `changes.log` (NDJSON)

 ## Changes.log Format (NDJSON)

-保留永久审计日志（append-only，永不删除）：
+Permanent audit log (append-only, never deleted):

 ```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
-# 启动新循环
+# Start new cycle
 /parallel-dev-cycle TASK="Implement real-time notifications"

-# 继续循环
+# Continue cycle
 /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"

-# 自动模式
+# Auto mode
 /parallel-dev-cycle --auto TASK="Add OAuth authentication"
 ```

 ## Key Benefits

-✅ **简洁**: 每个 agent 只维护 1 个文件 + changes.log
-✅ **高效**: 版本重写无需复杂版本标记
-✅ **可查**: 完整历史在 `history/` 和 `changes.log`
-✅ **快速**: Agent 读取当前版本快速（不需解析历史）
-✅ **审计**: NDJSON changes.log 完整追溯每个变更
+- **Simple**: Each agent maintains only 1 file + changes.log
+- **Efficient**: Version rewrite without complex version marking
+- **Traceable**: Complete history in `history/` and `changes.log`
+- **Fast**: Agent reads current version quickly (no history parsing needed)
+- **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

 | 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) | 版本管理 |
+| [phases/orchestrator.md](phases/orchestrator.md) | Orchestrator logic |
+| [phases/state-schema.md](phases/state-schema.md) | State structure definition |
+| [phases/agents/](phases/agents/) | Four agent role definitions |
+| [specs/coordination-protocol.md](specs/coordination-protocol.md) | Communication protocol |
+| [specs/versioning-strategy.md](specs/versioning-strategy.md) | Version management |
--- a/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md
+++ b/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md
@@ -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 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

 Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
@@ -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, code-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]
 ```
--- a/.codex/skills/parallel-dev-cycle/phases/agents/requirements-analyst.md
+++ b/.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
--- a/.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md
+++ b/.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md
@@ -1,50 +1,51 @@
 # 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/
 ├── ra/
-│   ├── requirements.md          # v1.2.0 (当前版本，重新创建)
-│   ├── edge-cases.md            # v1.2.0 (当前版本，重新创建)
-│   ├── changes.log              # NDJSON 完整变更历史（append-only）
+│   ├── requirements.md          # v1.2.0 (current version, complete rewrite)
+│   ├── edge-cases.md            # v1.2.0 (current version, complete rewrite)
+│   ├── changes.log              # NDJSON complete change history (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     (归档)
+│       ├── requirements-v1.0.0.md   (archived)
+│       ├── requirements-v1.1.0.md   (archived)
+│       ├── edge-cases-v1.0.0.md     (archived)
+│       └── edge-cases-v1.1.0.md     (archived)
 ├── ep/
-│   ├── exploration.md           # v1.2.0 (当前)
-│   ├── architecture.md          # v1.2.0 (当前)
-│   ├── plan.json                # v1.2.0 (当前)
+│   ├── exploration.md           # v1.2.0 (current)
+│   ├── architecture.md          # v1.2.0 (current)
+│   ├── plan.json                # v1.2.0 (current)
 │   └── history/
 │       ├── plan-v1.0.0.json
 │       └── plan-v1.1.0.json
 ├── cd/
-│   ├── implementation.md        # v1.2.0 (当前)
-│   ├── code-changes.log         # NDJSON 完整历史
-│   ├── issues.md                # 当前未解决问题
+│   ├── implementation.md        # v1.2.0 (current)
+│   ├── code-changes.log         # NDJSON complete history
+│   ├── debug-log.ndjson         # Debug hypothesis tracking
+│   ├── issues.md                # Current unresolved issues
 │   └── 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 (当前)
+    ├── validation.md            # v1.2.0 (current)
+    ├── test-results.json        # v1.2.0 (current)
+    ├── summary.md               # v1.2.0 (current)
    └── history/
        ├── validation-v1.0.0.md
        └── test-results-v1.0.0.json
 ```

-## 文档模板优化
+## Optimized Document Template

-### Requirements.md (重新创建版本)
+### Requirements.md (Complete Rewrite Version)

 ```markdown
 # Requirements Specification - v1.2.0
@@ -162,7 +163,7 @@ Response time < 500ms for all OAuth flows.
 **Detailed History**: See `history/` directory and `changes.log`
 ```

-### Changes.log (NDJSON - 完整历史)
+### Changes.log (NDJSON - Complete History)

 ```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"}
@@ -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"}
 ```

-## 实现流程
+## Implementation Flow

-### Agent 工作流（RA 为例）
+### Agent Workflow (RA Example)

 ```javascript
-// ==================== RA Agent 迭代流程 ====================
+// ==================== RA Agent Iteration Flow ====================

-// 读取当前状态
+// Read current state
 const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
 const currentVersion = state.requirements?.version || "0.0.0"
 const iteration = state.current_iteration

-// 如果是迭代（已有旧版本）
+// If iteration (old version exists)
 if (currentVersion !== "0.0.0") {
-  // 1. 归档旧版本
+  // 1. Archive old version
  const oldFile = `.workflow/.cycle/${cycleId}.progress/ra/requirements.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)

-  // 3. 读取变更历史
+  // 3. Read change history
  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

-// 5. 生成新文档（完全重写）
+// 5. Generate new document (complete rewrite)
 const newRequirements = generateRequirements({
  version: newVersion,
  previousVersion: currentVersion,
@@ -211,13 +212,13 @@ const newRequirements = generateRequirements({
  currentChanges: "Added MFA and GitHub provider",
  iteration: iteration,
  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)

-// 7. 追加变更到 changes.log
+// 7. Append change to changes.log
 appendNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`, {
  timestamp: getUtc8ISOString(),
  iteration: iteration,
@@ -228,7 +229,7 @@ appendNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`, {
  description: "Added MFA requirement"
 })

-// 8. 更新状态
+// 8. Update state
 state.requirements = {
  version: newVersion,
  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))
 ```

-## 优势对比
+## Advantages Comparison

-| 方面 | 增量更新 | 重新创建 + 归档 |
-|------|----------|----------------|
-| **文档简洁性** | ❌ 越来越长 | ✅ 始终简洁 |
-| **Agent 解析** | ❌ 需要解析历史 | ✅ 只看当前版本 |
-| **维护复杂度** | ❌ 高（版本标记） | ✅ 低（直接重写） |
-| **文件大小** | ❌ 膨胀 | ✅ 固定 |
-| **历史追溯** | ✅ 在主文档 | ✅ 在 history/ + changes.log |
-| **人类可读** | ❌ 需要跳过历史 | ✅ 直接看当前 |
-| **Token 使用** | ❌ 多（读取完整历史） | ✅ 少（只读当前） |
+| Aspect | Incremental Update | Complete Rewrite + Archive |
+|--------|-------------------|---------------------------|
+| **Document Conciseness** | ❌ Gets longer | ✅ Always concise |
+| **Agent Parsing** | ❌ Must parse history | ✅ Only read current version |
+| **Maintenance Complexity** | ❌ High (version marking) | ✅ Low (direct rewrite) |
+| **File Size** | ❌ Bloats | ✅ Fixed |
+| **History Tracking** | ✅ In main document | ✅ In history/ + changes.log |
+| **Human Readability** | ❌ Must skip history | ✅ Direct current view |
+| **Token Usage** | ❌ More (read complete history) | ✅ Less (only read current) |

-## 归档策略
+## Archive Strategy

-### 自动归档触发时机
+### Auto-Archive Trigger

 ```javascript
 function shouldArchive(currentVersion, state) {
-  // 每次版本更新时归档
+  // Archive on each version update
  return currentVersion !== state.requirements?.version
 }

@@ -269,29 +270,29 @@ function archiveOldVersion(cycleId, agent, filename, currentVersion) {
  const archiveDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
  const archiveFile = `${archiveDir}/${filename.replace('.', `-v${currentVersion}.`)}`

-  // 确保归档目录存在
+  // Ensure archive directory exists
  mkdir -p ${archiveDir}

-  // 复制（不是移动，保持当前文件直到新版本写入）
+  // Copy (not move, keep current file until new version written)
  Copy(currentFile, archiveFile)

  console.log(`Archived ${filename} v${currentVersion} to history/`)
 }
 ```

-### 清理策略（可选）
+### Cleanup Strategy (Optional)

-保留最近 N 个版本，删除更老的归档：
+Keep most recent N versions, delete older archives:

 ```javascript
 function cleanupArchives(cycleId, agent, keepVersions = 3) {
  const historyDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
  const archives = listFiles(historyDir)

-  // 按版本号排序
+  // Sort by version number
  archives.sort((a, b) => compareVersions(extractVersion(a), extractVersion(b)))

-  // 删除最老的版本（保留最近 N 个）
+  // Delete oldest versions (keep most recent N)
  if (archives.length > keepVersions) {
    const toDelete = archives.slice(0, archives.length - keepVersions)
    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
-# 查看所有变更
+# View all changes
 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")'

-# 按迭代查看变更
+# View changes by iteration
 cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.iteration==2)'
 ```

-这样：
- **主文档**: 清晰简洁（当前状态）
- **Changes.log**: 完整追溯（所有历史）
- **History/**: 快照备份（按需查看）
+This way:
+- **Main Document**: Clear and concise (current state)
+- **Changes.log**: Complete traceability (all history)
+- **History/**: Snapshot backups (view on demand)

-## 推荐实施
+## Recommended Implementation

-1. ✅ 采用"重新创建"策略
-2. ✅ 主文档只保留"上一版本简要说明"
-3. ✅ 自动归档到 `history/` 目录
-4. ✅ Changes.log (NDJSON) 保留完整历史
-5. ✅ 可选：保留最近 3-5 个历史版本
+1. ✅ Adopt "Complete Rewrite" strategy
+2. ✅ Main document only keeps "previous version summary"
+3. ✅ Auto-archive to `history/` directory
+4. ✅ Changes.log (NDJSON) preserves complete history
+5. ✅ Optional: Keep most recent 3-5 historical versions

-这样既保持了文档简洁（Agent 友好），又保留了完整历史（审计友好）。
+This approach keeps documents concise (agent-friendly) while preserving complete history (audit-friendly).