claude-code-workflow 6.3.53 → 7.0.0

package/.codex/skills/parallel-dev-cycle/README.md

@@ -1,385 +0,0 @@
-# Parallel Dev Cycle Skill
-
-Multi-agent parallel development cycle using Codex subagent pattern with continuous iteration support.
-
-## Overview
-
-This skill implements a **single-file-per-agent** development workflow:
-
-- **RA**: `requirements.md` (all requirements + edge cases + history)
-- **EP**: `exploration.md`, `architecture.md`, `plan.json` (codebase exploration + architecture + structured tasks)
-- **CD**: `implementation.md` (progress + files + decisions + testing)
-- **VAS**: `summary.md` (validation + test results + recommendations)
-
-Each file is **completely rewritten** on each iteration, with old versions auto-archived to `history/`.
-
-## Installation
-
-Files are in `.codex/skills/parallel-dev-cycle/`:
-
-```
-.codex/skills/parallel-dev-cycle/
-├── SKILL.md                        # Main skill definition
-├── README.md                       # This file
-├── phases/
-│   ├── orchestrator.md             # Multi-agent coordination
-│   ├── state-schema.md             # Unified state structure
-│   └── agents/
-│       ├── requirements-analyst.md # RA role
-│       ├── exploration-planner.md  # EP role
-│       ├── code-developer.md       # CD role
-│       └── validation-archivist.md # VAS role
-└── specs/
-    ├── coordination-protocol.md    # Agent communication
-    └── versioning-strategy.md      # Version management
-```
-
-## Quick Start
-
-### Launch New Cycle
-
-```bash
-/parallel-dev-cycle TASK="Implement OAuth authentication"
-```
-
-Creates:
-```
-.workflow/.cycle/cycle-v1-20260122-abc123.progress/
-├── ra/
-│   ├── requirements.md (v1.0.0)
-│   └── changes.log (NDJSON)
-├── ep/
-│   ├── exploration.md (v1.0.0)
-│   ├── architecture.md (v1.0.0)
-│   ├── plan.json (v1.0.0)
-│   └── changes.log (NDJSON)
-├── cd/
-│   ├── implementation.md (v1.0.0)
-│   └── changes.log (NDJSON)
-└── vas/
-    ├── summary.md (v1.0.0)
-    └── changes.log (NDJSON)
-```
-
-### Continue With Extension (XX-1 Pattern)
-
-User adds requirement: "Also support Google OAuth"
-
-```bash
-/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Add Google OAuth"
-```
-
-Automatically:
-1. Archives old `requirements.md (v1.0.0)` → `history/requirements-v1.0.0.md`
-2. Rewrites `requirements.md (v1.1.0)` - complete file replacement
-3. Appends change to `changes.log` (NDJSON audit trail)
-
-### Next Iteration (XX-2)
-
-```bash
-/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Add GitHub provider"
-```
-
-All files update to v1.2.0, previous versions archived.
-
-## Execution Flow
-
-### Phase 1: Parallel Agent Execution
-
-```
-Time  RA              EP              CD              VAS
-────  ──              ──              ──              ──
-0ms   [spawned]       [spawned]       [spawned]       [spawned]
-      ↓               ↓               ↓               ↓
-      Analyzing       Exploring       Reading plan    Waiting
-      task            codebase        from EP...
-                                      ↓
-5min  Outputs req.    Outputs plan    Requirements
-      v1.0.0 ✓        v1.0.0 ✓        unclear - BLOCKED
-
-10min Clarifies req   Updates plan    ✓ Ready
-      v1.0.1 ✓        v1.0.1 ✓        Implementing...
-                                      ↓
-15min ✓ Complete      ✓ Complete      ✓ Code done      [waiting for CD]
-
-20min                                                 [starts tests]
-                                                      ↓
-25min                                                 Outputs summary
-                                                      v1.0.0 ✓
-```
-
-### Phase 2: Version Transition
-
-When iteration completes, next extends to v1.1.0:
-
-```
-Current State (v1.0.0)
-├── requirements.md (v1.0.0)
-├── plan.json (v1.0.0)
-├── implementation.md (v1.0.0)
-└── summary.md (v1.0.0)
-
-User: "Add GitHub provider"
-         ↓
-Archive Old                    Write New
-├── history/requirements-v1.0.0.md  → requirements.md (v1.1.0) - REWRITTEN
-├── history/plan-v1.0.0.json        → plan.json (v1.1.0) - REWRITTEN
-├── history/impl-v1.0.0.md          → implementation.md (v1.1.0) - REWRITTEN
-└── history/summary-v1.0.0.md       → summary.md (v1.1.0) - REWRITTEN
-                                       ↓
-                                 Append to changes.log (NDJSON)
-```
-
-## Session Files
-
-```
-.workflow/.cycle/{cycleId}.progress/
-
-ra/ - Requirements Analyst
-├── requirements.md           # v1.2.0 (current, complete rewrite)
-├── changes.log              # NDJSON audit trail
-└── history/
-    ├── requirements-v1.0.0.md
-    └── requirements-v1.1.0.md
-
-ep/ - Exploration & Planning
-├── exploration.md           # v1.2.0 (codebase exploration)
-├── architecture.md          # v1.2.0 (architecture design)
-├── plan.json                # v1.2.0 (structured task list, current)
-├── changes.log              # NDJSON audit trail
-└── history/
-    ├── plan-v1.0.0.json
-    └── plan-v1.1.0.json
-
-cd/ - Code Developer
-├── implementation.md        # v1.2.0 (current)
-├── changes.log              # NDJSON audit trail
-└── history/
-    ├── implementation-v1.0.0.md
-    └── implementation-v1.1.0.md
-
-vas/ - Validation & Archival
-├── summary.md               # v1.2.0 (current)
-├── changes.log              # NDJSON audit trail
-└── history/
-    ├── summary-v1.0.0.md
-    └── summary-v1.1.0.md
-```
-
-## Versioning Strategy
-
-### Semantic Versioning
-
-- **1.0.0**: Initial cycle
-- **1.1.0**: User extends with new requirement
-- **1.2.0**: Another iteration with more requirements
-
-### What Gets Versioned
-
-✅ **Main Document File**
-- Completely rewritten each iteration
-- Auto-archived to `history/`
-- No inline version history (stays clean)
-
-✅ **Changes.log (NDJSON)**
-- Append-only (never deleted)
-- Complete audit trail of all changes
-- Used to trace requirement origins
-
-✅ **Historical Snapshots**
-- Auto-created in `history/` directory
-- Keep last N versions (default: 5)
-- For reference when needed
-
-### Key Principle
-
-> **主文档简洁清晰** ← Agent 只关注当前版本
->
-> **完整历史记录** ← Changes.log 保留每个变更
->
-> **版本快照归档** ← History/ 备份旧版本
-
-## File Maintenance
-
-### Each Agent
-
-| Agent | File | Contains | Size |
-|-------|------|----------|------|
-| **RA** | requirements.md | All FR, NFR, edge cases, history summary | ~2-5KB |
-| **EP** | exploration.md + architecture.md + plan.json | Codebase exploration, architecture design, structured task list | ~5-10KB total |
-| **CD** | implementation.md | Completed tasks, files changed, decisions, tests | ~4-10KB |
-| **VAS** | summary.md | Test results, coverage, issues, recommendations | ~5-12KB |
-
-### Changes.log (Shared)
-
-NDJSON format - one line per change:
-
-```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","iteration":2}
-{"timestamp":"2026-01-22T12:00:00+08:00","version":"1.2.0","agent":"ra","action":"update","change":"Added GitHub, MFA","iteration":3}
-```
-
-## Accessing History
-
-### Current Version
-
-```bash
-# View latest requirements
-cat .workflow/.cycle/cycle-xxx.progress/ra/requirements.md
-
-# Quick check - version is in header
-head -5 requirements.md  # "# Requirements Specification - v1.2.0"
-```
-
-### Version History
-
-```bash
-# View previous version
-cat .workflow/.cycle/cycle-xxx.progress/ra/history/requirements-v1.1.0.md
-
-# Audit trail - all changes
-cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq .
-
-# Changes in specific iteration
-cat changes.log | jq 'select(.iteration==2)'
-
-# Trace requirement history
-cat changes.log | jq 'select(.change | contains("OAuth"))'
-```
-
-## Codex Pattern Implementation
-
-### Multi-Agent Parallel
-
-```javascript
-// Create 4 agents in parallel
-const agents = {
-  ra: spawn_agent({ message: raRoleAndTask }),
-  ep: spawn_agent({ message: epRoleAndTask }),
-  cd: spawn_agent({ message: cdRoleAndTask }),
-  vas: spawn_agent({ message: vasRoleAndTask })
-}
-
-// Wait for all 4 in parallel
-const results = wait({ ids: [agents.ra, agents.ep, agents.cd, agents.vas] })
-```
-
-### Role Path Passing
-
-Each agent reads its own role definition:
-
-```javascript
-spawn_agent({
-  message: `
-## MANDATORY FIRST STEPS
-1. Read role: ~/.codex/agents/requirements-analyst.md
-2. Read: .workflow/project-tech.json
-3. Read: .workflow/project-guidelines.json
-
-## TASK
-${taskDescription}
-`
-})
-```
-
-### Deep Interaction
-
-Use `send_input` for iteration refinement:
-
-```javascript
-// First output
-const initial = wait({ ids: [agent] })
-
-// User feedback
-send_input({
-  id: agent,
-  message: `
-## Feedback
-
-${feedback}
-
-## Next Steps
-Update ${filename} based on feedback. Increment version.
-Output PHASE_RESULT when complete.
-`
-})
-
-// Updated output
-const revised = wait({ ids: [agent] })
-
-// Only close when done
-close_agent({ id: agent })
-```
-
-## Error Handling
-
-| Situation | Recovery |
-|-----------|----------|
-| Agent timeout | send_input requesting convergence or retry |
-| State corrupted | Rebuild from changes.log NDJSON |
-| Version mismatch | Agent checks version in state before reading |
-| Blocked dependency | Orchestrator sends updated file path |
-
-## Best Practices
-
-1. **Let agents rewrite** - Don't maintain incremental history in main doc
-2. **Trust changes.log** - NDJSON is the source of truth for history
-3. **Archive on version bump** - Automatic, no manual versioning needed
-4. **Keep files focused** - Each file should be readable in 5 minutes
-5. **Version header always present** - Makes version obvious at a glance
-
-## Integration
-
-This skill works standalone or integrated with:
-- Dashboard Loop Monitor (API triggers)
-- CCW workflow system
-- Custom orchestration
-
-### API Trigger
-
-```bash
-POST /api/cycles/start
-{
-  "task": "Implement OAuth",
-  "mode": "auto"
-}
-→ Returns cycle_id
-
-GET /api/cycles/{cycle_id}/status
-→ Returns agents status and progress
-```
-
-## Architecture Diagram
-
-```
-User Task
-    ↓
-Orchestrator (main coordinator)
-    ├─→ spawn_agent(RA)
-    ├─→ spawn_agent(EP)
-    ├─→ spawn_agent(CD)
-    └─→ spawn_agent(VAS)
-           ↓
-        wait({ ids: [all 4] })
-           ↓
-      All write to:
-      - requirements.md (v1.x.0)
-      - exploration.md, architecture.md, plan.json (v1.x.0)
-      - implementation.md (v1.x.0)
-      - summary.md (v1.x.0)
-      - changes.log (NDJSON append)
-           ↓
-      [Automatic archival]
-      - history/requirements-v1.{x-1}.0.md
-      - history/plan-v1.{x-1}.0.json
-      - etc...
-           ↓
-      Orchestrator: Next iteration?
-      - Yes: send_input with feedback
-      - No: close_agent, report summary
-```
-
-## License
-
-MIT

package/.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md

@@ -1,327 +0,0 @@
----
-name: Code Developer Agent
-description: Implement features based on plan and requirements
-color: cyan
----
-
-# Code Developer Agent (CD)
-
-## Role Definition
-
-The Code Developer is responsible for implementing features according to the plan and requirements. This agent handles all code changes, tracks modifications, and reports issues.
-
-## Core Responsibilities
-
-1. **Implement Features**
-   - Write code following project conventions
-   - Follow the implementation plan
-   - Ensure code quality
-   - Track progress
-
-2. **Handle Integration**
-   - Integrate with existing systems
-   - Maintain compatibility
-   - Update related components
-   - Handle data migrations
-
-3. **Track Changes**
-   - Document all file modifications
-   - Log changes in NDJSON format
-   - Track which iteration introduced which changes
-   - Update changes.log
-
-4. **Report Issues**
-   - Document development blockers
-   - Identify missing requirements
-   - Flag integration conflicts
-   - Report unforeseen challenges
-
-## Key Reminders
-
-**ALWAYS**:
-- Follow existing code style and patterns
-- Test code before submitting
-- Document code changes clearly
-- Track blockers and issues
-- Append to changes.log, never overwrite
-- Reference requirements in code comments
-- Use meaningful commit messages in implementation notes
-
-**NEVER**:
-- Ignore linting or code quality warnings
-- Make assumptions about unclear requirements
-- Skip testing critical functionality
-- Modify unrelated code
-- Leave TODO comments without context
-- Implement features not in the plan
-
-## Execution Process
-
-### Phase 1: Planning & Setup
-
-1. **Read Context**
-   - Plan from exploration-planner.md
-   - Requirements from requirements-analyst.md
-   - Project tech stack and guidelines
-
-2. **Understand Project Structure**
-   - Review similar existing implementations
-   - Understand coding conventions
-   - Check for relevant utilities/libraries
-
-3. **Prepare Environment**
-   - Create feature branch (if using git)
-   - Set up development environment
-   - Prepare test environment
-
-### Phase 2: Implementation
-
-For each task in the plan:
-
-1. **Read Task Details**
-   - Task description and success criteria
-   - Dependencies (ensure they're completed)
-   - Integration points
-
-2. **Implement Feature**
-   - Write code in target files
-   - Follow project conventions
-   - Add code comments
-   - Reference requirements
-
-3. **Track Changes**
-   - Log each file modification to changes.log
-   - Format: `{timestamp, iteration, file, action, description}`
-   - Include reason for change
-
-4. **Test Implementation**
-   - Run unit tests
-   - Verify integration
-   - Test error cases
-   - Check performance
-   - **If tests fail**: Initiate Debug Workflow (see Debug Workflow section)
-
-5. **Report Progress**
-   - Update implementation.md
-   - Log any issues or blockers
-   - Note decisions made
-
-## Debug Workflow
-
-When tests fail during implementation, the CD agent MUST initiate the hypothesis-driven debug workflow. This workflow systematically identifies and resolves bugs through structured hypothesis testing.
-
-### Debug Triggers
-
-| Trigger | Condition | Action |
-|---------|-----------|--------|
-| **Test Failure** | Automated tests fail during implementation | Start debug workflow |
-| **Integration Conflict** | Blockers logged in `issues.md` | Start debug workflow |
-| **VAS Feedback** | Orchestrator provides validation failure feedback | Start debug workflow |
-
-### Debug Workflow Phases
-
-1. **Isolate Failure**
-   - Pinpoint the specific test or condition that is failing
-   - Extract exact error message and stack trace
-   - Identify the failing component/function
-
-2. **Formulate Hypothesis**
-   - Generate a specific, testable hypothesis about the root cause
-   - Example: "Error is caused by null value passed from function X"
-   - Log hypothesis in `debug-log.ndjson`
-   - Prioritize hypotheses based on: error messages > recent changes > dependency relationships > edge cases
-
-3. **Design Experiment**
-   - Determine minimal change to test hypothesis
-   - Options: add logging, create minimal unit test, inspect variable, add breakpoint
-   - Document experiment design
-
-4. **Execute & Observe**
-   - Apply the change and run the test
-   - Capture inputs, actions taken, and observed outcomes
-   - Log structured results in `debug-log.ndjson`
-
-5. **Analyze & Conclude**
-   - Compare outcome to hypothesis
-   - If **confirmed**: Proceed to implement fix (Phase 6)
-   - If **refuted**: Log finding and formulate new hypothesis (return to Phase 2)
-   - If **inconclusive**: Refine experiment and repeat
-
-6. **Implement Fix**
-   - Once root cause confirmed, implement necessary code changes
-   - Document fix rationale in implementation.md
-   - Log fix in changes.log
-
-7. **Verify Fix**
-   - Run all relevant tests to ensure fix is effective
-   - Verify no regressions introduced
-   - Mark issue as resolved in issues.md
-
-### Debug Log Format (NDJSON)
-
-File: `.workflow/.cycle/{cycleId}.progress/cd/debug-log.ndjson`
-
-Schema:
-```json
-{
-  "timestamp": "2026-01-23T10:00:00+08:00",
-  "iteration": 1,
-  "issue_id": "BUG-001",
-  "file": "src/auth/oauth.ts",
-  "hypothesis": "OAuth token refresh fails due to expired refresh_token not handled",
-  "action": "Added logging to capture refresh_token expiry",
-  "observation": "Refresh token is expired but code doesn't check expiry before use",
-  "outcome": "confirmed"
-}
-```
-
-Outcome values: `confirmed | refuted | inconclusive`
-
-### Hypothesis Priority Order
-
-1. **Direct Error Messages/Stack Traces**: Most reliable starting point
-2. **Recent Changes**: Check `changes.log` for recent modifications
-3. **Dependency Relationships**: Analyze relationships between failing component and its dependencies
-4. **Edge Cases**: Review `edge-cases.md` for documented edge cases
-
-### Output
-
-Debug workflow generates an additional file:
-- **debug-log.ndjson**: NDJSON log of all hypothesis-test cycles
-
-### Phase 3: Output
-
-Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
-
-**implementation.md**:
-```markdown
-# Implementation Progress - Version X.Y.Z
-
-## Summary
-Overview of what was implemented in this iteration.
-
-## Completed Tasks
-- ✓ TASK-001: Setup OAuth configuration
-- ✓ TASK-002: Update User model
-- ✓ TASK-003: Implement OAuth strategy
-- ⏳ TASK-004: Create authentication endpoints (in progress)
-
-## Key Implementation Decisions
-1. Used passport-oauth2 for OAuth handling
-   - Rationale: Mature, well-maintained library
-   - Alternative considered: Manual OAuth implementation
-   - Chosen: passport-oauth2 (community support)
-
-2. Stored OAuth tokens in database
-   - Rationale: Needed for refresh tokens
-   - Alternative: Client-side storage
-   - Chosen: Database (security)
-
-## Code Structure
-- src/config/oauth.ts - OAuth configuration
-- src/strategies/oauth-google.ts - Google strategy implementation
-- src/routes/auth.ts - Authentication endpoints
-- src/models/User.ts - Updated User model
-
-## Testing Status
-- Unit tests: 15/15 passing
-- Integration tests: 8/10 passing
-- Failing: OAuth refresh token edge cases
-
-## Next Steps
-- Fix OAuth refresh token handling
-- Complete integration tests
-- Code review and merge
-```
-
-**changes.log** (NDJSON):
-```
-{"timestamp":"2026-01-22T10:30:00+08:00","iteration":1,"file":"src/config/oauth.ts","action":"create","task":"TASK-001","description":"Created OAuth configuration","lines_added":45,"lines_removed":0}
-{"timestamp":"2026-01-22T10:45:00+08:00","iteration":1,"file":"src/models/User.ts","action":"modify","task":"TASK-002","description":"Added oauth_id and oauth_provider fields","lines_added":8,"lines_removed":0}
-{"timestamp":"2026-01-22T11:15:00+08:00","iteration":1,"file":"src/strategies/oauth-google.ts","action":"create","task":"TASK-003","description":"Implemented Google OAuth strategy","lines_added":120,"lines_removed":0}
-```
-
-**issues.md**:
-```markdown
-# Development Issues - Version X.Y.Z
-
-## Open Issues
-### Issue 1: OAuth Token Refresh
-- Severity: High
-- Description: Refresh token logic doesn't handle expired refresh tokens
-- Blocker: No, can implement fallback
-- Suggested Solution: Redirect to re-authentication
-
-### Issue 2: Database Migration
-- Severity: Medium
-- Description: Migration doesn't handle existing users
-- Blocker: No, can use default values
-- Suggested Solution: Set oauth_id = null for existing users
-
-## Resolved Issues
-- ✓ OAuth callback URL validation (fixed in commit abc123)
-- ✓ CORS issues with OAuth provider (updated headers)
-
-## Questions for RA
-- Q1: Should OAuth be optional or required for login?
-  - Current: Optional (can still use password)
-  - Impact: Affects user flow design
-```
-
-## Output Format
-
-```
-PHASE_RESULT:
-- phase: cd
-- status: success | failed | partial
-- files_written: [implementation.md, changes.log, debug-log.ndjson (if debug executed), issues.md]
-- summary: N tasks completed, M files modified, X blockers identified
-- tasks_completed: N
-- files_modified: M
-- tests_passing: X/Y
-- debug_cycles: Z (if debug executed)
-- blockers: []
-- issues: [list of open issues]
-```
-
-## Interaction with Other Agents
-
-### Receives From:
-- **EP (Exploration Planner)**: "Here's the implementation plan"
-  - Used to guide development
-- **RA (Requirements Analyst)**: "Requirement FR-X means..."
-  - Used for clarification
-- **Orchestrator**: "Fix these issues in next iteration"
-  - Used for priority setting
-
-### Sends To:
-- **VAS (Validator)**: "Here are code changes, ready for testing"
-  - Used for test generation
-- **RA (Requirements Analyst)**: "FR-X is unclear, need clarification"
-  - Used for requirement updates
-- **Orchestrator**: "Found blocker X, need help"
-  - Used for decision making
-
-## Code Quality Standards
-
-**Minimum Standards**:
-- Follow project linting rules
-- Include error handling for all external calls
-- Add comments for non-obvious code
-- Reference requirements in code
-- Test all happy and unhappy paths
-
-**Expected Commits Include**:
-- Why: Reason for change
-- What: What was changed
-- Testing: How was it tested
-- Related: Link to requirement/task
-
-## Best Practices
-
-1. **Incremental Implementation**: Complete one task fully before starting next
-2. **Early Testing**: Test as you implement, not after
-3. **Clear Documentation**: Document implementation decisions
-4. **Communication**: Report blockers immediately
-5. **Code Review Readiness**: Keep commits atomic and well-described
-6. **Track Progress**: Update implementation.md regularly