Claude-Code-Workflow/docs/skills/codex-lifecycle.md

Codex Skills - Lifecycle Category

One-Liner

Lifecycle Codex Skills is a full lifecycle orchestration system — implementing complete development flow automation from specification to implementation to testing to review through team-lifecycle and parallel-dev-cycle.

vs Traditional Methods Comparison

Dimension	Traditional Methods	Codex Skills
Pipeline orchestration	Manual task management	Automatic spawn-wait-close pipeline
Agent communication	Direct communication	Subagent inline calls
Codebase exploration	Repeated exploration	Shared cache system
Coordination overhead	Coordinate every step	Fast-advance linear skip

Skills List

Skill	Function	Trigger
team-lifecycle	Full lifecycle orchestrator	/team-lifecycle <task>
parallel-dev-cycle	Multi-agent parallel development cycle	/parallel-dev-cycle TASK="..."

Skills Details

team-lifecycle

One-Liner: Full lifecycle orchestrator — spawn-wait-close pipeline for spec/implementation/test

Architecture Overview:

+-------------------------------------------------------------+
|  Team Lifecycle Orchestrator                                  |
|  Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5         |
|  Require    Init       Dispatch   Coordinate   Report         |
+----------+------------------------------------------------+--+
           |
     +-----+------+----------+-----------+-----------+
     v            v          v           v           v
+---------+ +---------+ +---------+ +---------+ +---------+
| Phase 1 | | Phase 2 | | Phase 3 | | Phase 4 | | Phase 5 |
| Require | | Init    | | Dispatch| | Coord   | | Report  |
+---------+ +---------+ +---------+ +---------+ +---------+
     |            |          |          |||          |
  params       session     tasks     agents      summary
                                    /  |  \
                              spawn  wait  close
                              /        |        \
                       +------+   +-------+   +--------+
                       |agent1|   |agent2 |   |agent N |
                       +------+   +-------+   +--------+
                          |           |            |
                     (may call discuss/explore subagents internally)

Key Design Principles:

1. Inline discuss subagent: Production roles (analyst, writer, reviewer) inline invoke discuss subagents, reducing spec pipeline from 12 beats to 6
2. Shared explore cache: All agents share centralized explorations/ directory, eliminating duplicate codebase exploration
3. Fast-advance spawning: Immediately spawn next linear successor after agent completion
4. Consensus severity routing: Discussion results routed through HIGH/MEDIUM/LOW severity levels
5. Beat model: Each pipeline step is a beat — spawn agent, wait for results, process output, spawn next

Agent Registry:

Agent	Role File	Responsibility	Mode
analyst	~/.codex/agents/analyst.md	Seed analysis, context collection, DISCUSS-001	2.8 Inline Subagent
writer	~/.codex/agents/writer.md	Documentation generation, DISCUSS-002 to DISCUSS-005	2.8 Inline Subagent
planner	~/.codex/agents/planner.md	Multi-angle exploration, plan generation	2.9 Cached Exploration
executor	~/.codex/agents/executor.md	Code implementation	2.1 Standard
tester	~/.codex/agents/tester.md	Test-fix loop	2.3 Deep Interaction
reviewer	~/.codex/agents/reviewer.md	Code review + spec quality, DISCUSS-006	2.8 Inline Subagent
architect	~/.codex/agents/architect.md	Architecture consultation (on-demand)	2.1 Standard
fe-developer	~/.codex/agents/fe-developer.md	Frontend implementation	2.1 Standard
fe-qa	~/.codex/agents/fe-qa.md	Frontend QA, GC loop	2.3 Deep Interaction

Subagent Registry:

Subagent	Agent File	Callable By	Purpose
discuss	~/.codex/agents/discuss-agent.md	analyst, writer, reviewer	Multi-perspective critique via CLI tool
explore	~/.codex/agents/explore-agent.md	analyst, planner, any agent	Codebase exploration with shared cache

Pipeline Definition:

Spec-only (6 beats):
  RESEARCH-001(+D1) → DRAFT-001(+D2) → DRAFT-002(+D3) → DRAFT-003(+D4) → DRAFT-004(+D5) → QUALITY-001(+D6)

Impl-only (3 beats):
  PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001

Full-lifecycle (9 beats):
  [Spec pipeline] → PLAN-001 → IMPL-001 → TEST-001 || REVIEW-001

Beat Cycle:

event (phase advance / user resume)
      ↓
  [Orchestrator]
      +-- read state file
      +-- find ready tasks
      +-- spawn agent(s)
      +-- wait(agent_ids, timeout)
      +-- process results (consensus routing, artifacts)
      +-- update state file
      +-- close completed agents
      +-- fast-advance: immediately spawn next if linear successor
      +-- yield (wait for next event or user command)

Fast-Advance Decision Table:

Condition	Action
1 ready task, simple linear successor, no checkpoint	Immediately spawn_agent next task (fast-advance)
Multiple ready tasks (parallel window)	Batch spawn all ready tasks, then wait all
No ready tasks, other agents running	Yield, wait for those agents to complete
No ready tasks, nothing running	Pipeline complete, enter Phase 5
Checkpoint task complete (e.g., QUALITY-001)	Pause, output checkpoint message, wait for user

Consensus Severity Routing:

Verdict	Severity	Orchestrator Action
consensus_reached	-	Proceed normally, fast-advance to next task
consensus_blocked	LOW	Treat as reached with notes, proceed
consensus_blocked	MEDIUM	Log warning to wisdom/issues.md, include divergences in next task context, continue
consensus_blocked	HIGH	Create revision task or pause waiting for user
consensus_blocked	HIGH (DISCUSS-006)	Always pause waiting for user decision (final sign-off gate)

Revision Task Creation (HIGH severity, non-DISCUSS-006):

const revisionTask = {
  id: "<original-task-id>-R1",
  owner: "<same-agent-role>",
  blocked_by: [],
  description: "Revision of <original-task-id>: address consensus-blocked divergences.\n"
    + "Session: <session-dir>\n"
    + "Original artifact: <artifact-path>\n"
    + "Divergences: <divergence-details>\n"
    + "Action items: <action-items-from-discuss>\n"
    + "InlineDiscuss: <same-round-id>",
  status: "pending",
  is_revision: true
}

Session Directory Structure:

.workflow/.team/TLS-<slug>-<date>/
├── team-session.json           # Pipeline state (replaces TaskCreate/TaskList)
├── spec/                       # Specification artifacts
│   ├── spec-config.json
│   ├── discovery-context.json
│   ├── product-brief.md
│   ├── requirements/
│   ├── architecture/
│   ├── epics/
│   ├── readiness-report.md
│   └── spec-summary.md
├── discussions/                # Discussion records (written by discuss subagents)
├── plan/                       # Plan artifacts
│   ├── plan.json
│   └── tasks/                  # Detailed task specifications
├── explorations/               # Shared exploration cache
│   ├── cache-index.json        # { angle -> file_path }
│   └── explore-<angle>.json
├── architecture/               # Architect assessments + design-tokens.json
├── analysis/                   # Analyst design-intelligence.json (UI mode)
├── qa/                         # QA audit reports
├── wisdom/                     # Cross-task knowledge accumulation
│   ├── learnings.md            # Patterns and insights
│   ├── decisions.md            # Architecture and design decisions
│   ├── conventions.md          # Codebase conventions
│   └── issues.md               # Known risks and issues
└── shared-memory.json          # Cross-agent state

State File Schema (team-session.json):

{
  "session_id": "TLS-<slug>-<date>",
  "mode": "<spec-only | impl-only | full-lifecycle | fe-only | fullstack | full-lifecycle-fe>",
  "scope": "<project description>",
  "status": "<active | paused | completed>",
  "started_at": "<ISO8601>",
  "updated_at": "<ISO8601>",
  "tasks_total": 0,
  "tasks_completed": 0,
  "pipeline": [
    {
      "id": "RESEARCH-001",
      "owner": "analyst",
      "status": "pending | in_progress | completed | failed",
      "blocked_by": [],
      "description": "...",
      "inline_discuss": "DISCUSS-001",
      "agent_id": null,
      "artifact_path": null,
      "discuss_verdict": null,
      "discuss_severity": null,
      "started_at": null,
      "completed_at": null,
      "revision_of": null,
      "revision_count": 0
    }
  ],
  "active_agents": [],
  "completed_tasks": [],
  "revision_chains": {},
  "wisdom_entries": [],
  "checkpoints_hit": [],
  "gc_loop_count": 0
}

User Commands:

Command	Action
check / status	Output execution status graph (read-only, no progress)
resume / continue	Check agent status, advance pipeline
New session request	Phase 0 detection, enter normal Phase 1-5 flow

Status Graph Output Format:

[orchestrator] Pipeline Status
[orchestrator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)

[orchestrator] Execution Graph:
  Spec Phase:
    [V RESEARCH-001(+D1)] -> [V DRAFT-001(+D2)] -> [>>> DRAFT-002(+D3)]
    -> [o DRAFT-003(+D4)] -> [o DRAFT-004(+D5)] -> [o QUALITY-001(+D6)]

  V=completed  >>>=running  o=pending  .=not created

[orchestrator] Active Agents:
  > <task-id> (<agent-role>) - running <elapsed>

[orchestrator] Commands: 'resume' to advance | 'check' to refresh

---

parallel-dev-cycle

One-Liner: Multi-agent parallel development cycle — requirements analysis, exploration planning, code development, validation

Architecture Overview:

┌─────────────────────────────────────────────────────────────┐
│                    User Input (Task)                        │
└────────────────────────────┬────────────────────────────────┘
                             │
                             v
              ┌──────────────────────────────┐
              │  Main Flow (Inline Orchestration)  │
              │  Phase 1 → 2 → 3 → 4              │
              └──────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        v                    v                    v
    ┌────────┐         ┌────────┐         ┌────────┐
    │  RA    │         │  EP    │         │  CD    │
    │Agent   │         │Agent   │         │Agent   │
    └────────┘         └────────┘         └────────┘
        │                    │                    │
        └────────────────────┼────────────────────┘
                             │
                             v
                         ┌────────┐
                         │  VAS   │
                         │ Agent  │
                         └────────┘
                             │
                             v
              ┌──────────────────────────────┐
              │    Summary Report            │
              │  & Markdown Docs             │
              └──────────────────────────────┘

Key Design Principles:

1. Main document + auxiliary log: Each agent maintains one main document (complete rewrite per iteration) and auxiliary log (append)
2. Version-based overwriting: Main document completely rewritten each iteration; log append-only
3. Automatic archiving: Old main document versions automatically archived to history/ directory
4. Complete audit trail: Changes.log (NDJSON) retains all change history
5. Parallel coordination: Four agents started simultaneously; coordinated via shared state and inline main flow
6. File references: Use short file paths rather than content passing
7. Self-enhancement: RA agent proactively expands requirements based on context
8. Shared discovery board: All agents share exploration discoveries via discoveries.ndjson

Workers:

Worker	Main Document (rewrite each iteration)	Append Log
RA	requirements.md	changes.log
EP	exploration.md, architecture.md, plan.json	changes.log
CD	implementation.md, issues.md	changes.log, debug-log.ndjson
VAS	summary.md, test-results.json	changes.log

Shared Discovery Board:

• All agents share real-time discovery board coordination/discoveries.ndjson
• Agents read at start, append discoveries during work
• Eliminates redundant codebase exploration

Discovery Types:

Type	Dedup Key	Writer	Readers
tech_stack	singleton	RA	EP, CD, VAS
project_config	data.path	RA	EP, CD
existing_feature	data.name	RA, EP	CD
architecture	singleton	EP	CD, VAS
code_pattern	data.name	EP, CD	CD, VAS
integration_point	data.file	EP	CD
test_command	singleton	CD, VAS	VAS, CD
blocker	data.issue	Any	All

Execution Flow:

Phase 1: Session initialization
    ├─ Create new cycle OR resume existing cycle
    ├─ Initialize state file and directory structure
    └─ Output: cycleId, state, progressDir

Phase 2: Agent execution (parallel)
    ├─ Attached task: spawn RA → spawn EP → spawn CD → spawn VAS → wait all
    ├─ Parallel spawn RA, EP, CD, VAS agents
    ├─ Wait for all agents to complete (with timeout handling)
    └─ Output: agentOutputs (4 agent results)

Phase 3: Result aggregation & iteration
    ├─ Parse PHASE_RESULT from each agent
    ├─ Detect issues (test failures, blockers)
    ├─ Decision: Issues found AND iteration < max?
    │   ├─ Yes → Send feedback via send_input, loop back to Phase 2
    │   └─ No → Proceed to Phase 4
    └─ Output: parsedResults, iteration status

Phase 4: Completion and summary
    ├─ Generate unified summary report
    ├─ Update final state
    ├─ Close all agents
    └─ Output: Final cycle report and continuation instructions

Session Structure:

{projectRoot}/.workflow/.cycle/
├── {cycleId}.json                     # Main state file
├── {cycleId}.progress/
│   ├── ra/                         # RA agent artifacts
│   │   ├── requirements.md        # Current version (complete rewrite)
│   │   ├── changes.log           # NDJSON full history (append)
│   │   └── history/              # Archived snapshots
│   ├── ep/                         # EP agent artifacts
│   │   ├── exploration.md        # Codebase exploration report
│   │   ├── architecture.md       # Architecture design
│   │   ├── plan.json             # Structured task list (current version)
│   │   ├── changes.log           # NDJSON full history
│   │   └── history/
│   ├── cd/                         # CD agent artifacts
│   │   ├── implementation.md     # Current version
│   │   ├── debug-log.ndjson      # Debug hypothesis tracking
│   │   ├── changes.log           # NDJSON full history
│   │   └── history/
│   ├── vas/                        # VAS agent artifacts
│   │   ├── summary.md            # Current version
│   │   ├── changes.log           # NDJSON full history
│   │   └── history/
│   └── coordination/               # Coordination data
│       ├── discoveries.ndjson      # Shared discovery board (all agents append)
│       ├── timeline.md             # Execution timeline
│       └── decisions.log            # Decision log

Version Control:

• 1.0.0: Initial cycle → 1.x.0: Each iteration (minor version increment)
• Each iteration: Archive old version → Complete rewrite → Append changes.log

Related Commands

• Codex Skills - Workflow
• Codex Skills - Specialized
• Claude Skills - Team Collaboration

Best Practices

1. Choose the right team type:

   • Full feature development → team-lifecycle
   • Parallel development cycle → parallel-dev-cycle

2. Leverage Inline Discuss: Production roles inline invoke discuss subagents, reducing orchestration overhead

3. Shared Cache: Utilize shared exploration cache to avoid duplicate codebase exploration

4. Fast-Advance: Linear successor tasks automatically skip orchestrator, improving efficiency

5. Consensus Routing: Understand consensus routing behavior for different severity levels

Usage Examples

# Full lifecycle development
/team-lifecycle "Build user authentication API"

# Specification pipeline
/team-lifecycle --mode=spec-only "Design payment system"

# Parallel development
/parallel-dev-cycle TASK="Implement notifications"

# Continue cycle
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123

# Auto mode
/parallel-dev-cycle --auto TASK="Add OAuth"