team-lifecycle（团队生命周期）

Team Lifecycle Orchestrator

Full lifecycle team orchestration for specification, implementation, and testing workflows. The orchestrator drives a multi-agent pipeline through five phases: requirement clarification, session initialization, task chain creation, pipeline coordination (spawn/wait/close loop), and completion reporting.

Key design principles:

• Inline discuss subagent: Produce roles (analyst, writer, reviewer) call a discuss subagent internally rather than spawning a dedicated discussion agent. This halves spec pipeline beats from 12 to 6.
• Shared explore cache: All agents share a centralized explorations/ directory with cache-index.json, eliminating duplicate codebase exploration.
• Fast-advance spawning: After an agent completes, the orchestrator immediately spawns the next agent in a linear chain without waiting for a full coordination cycle.
• Consensus severity routing: Discussion verdicts route through HIGH/MEDIUM/LOW severity tiers, each with distinct orchestrator behavior (revision, warn-proceed, or pass-through).
• Beat model: Each pipeline step is a single beat -- spawn agent, wait for result, process output, spawn next. The orchestrator processes one beat per cycle, then yields.

Architecture

+-------------------------------------------------------------+
|  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)

Phase 4 Beat Cycle (single beat):

  event (phase advance / user resume)
      |
      v
  [Orchestrator]
      +-- read state file
      +-- find ready tasks (pending + all blockers completed)
      +-- spawn agent(s) for ready task(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)

Agent Registry

All agent role files MUST be deployed to ~/.codex/agents/ before use. Pattern 2.8 = agent internally spawns discuss subagent for multi-perspective critique. Pattern 2.9 = agent uses shared explore cache before work. Pattern 2.3 = orchestrator may use send_input for iterative correction loops.

Subagent Registry

Subagents are spawned by agents themselves (not by the orchestrator). An agent reads the subagent spec, spawns it inline via spawn_agent, waits for the result, and closes it. The orchestrator never directly manages subagent lifecycle.

Fast-Advance Spawning

After wait() returns a completed agent result, the orchestrator checks whether the next pipeline step is a simple linear successor (exactly one task becomes ready, no parallel window, no checkpoint).

Decision table:

Fast-advance failure recovery: When the orchestrator detects that a fast-advanced agent has failed (wait returns error or timeout with no result):

1. Record failure in state file
2. Mark that task as "pending" again in state
3. Spawn a fresh agent for the same task
4. If the same task fails 3+ times, pause pipeline and report to user

Consensus Severity Routing

When a produce agent (analyst, writer, reviewer) reports a discuss result, the orchestrator parses the verdict from the agent output.

Output format from agents (written to their artifact, also in wait() result):

DISCUSS_RESULT:
- verdict: <consensus_reached | consensus_blocked>
- severity: <HIGH | MEDIUM | LOW>
- average_rating: <N>/5
- divergences: <summary>
- action_items: <list>
- recommendation: <revise | proceed-with-caution | escalate>
- discussion_path: <path-to-discussion-record>

Routing table:

Revision task creation (HIGH severity, not DISCUSS-006):

// Add revision entry to state file
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
}

// Max 1 revision per task. If already revised once, pause for user.
if (stateHasRevision(originalTaskId)) {
  // Pause pipeline, ask user
} else {
  // Insert revision task into state, spawn agent
}

Phase Execution

Phase 0: Session Resume Check (before Phase 1)

Before entering Phase 1, the orchestrator checks for interrupted sessions:

1. Scan .workflow/.team/TLS-*/team-session.json for files with status: "active" or status: "paused"
2. No sessions found -> proceed to Phase 1
3. Single session found -> resume it (Session Reconciliation below)
4. Multiple sessions found -> ask user to select

Session Reconciliation (when resuming):

1. Read state file -> get pipeline state
2. For each task in state file:

- If status is "in_progress" but no agent is running -> reset to "pending" (interrupted) - If status is "completed" -> verify artifact exists

1. Rebuild task readiness from reconciled state
2. Proceed to Phase 4 with reconciled state (spawn ready tasks)

Pipeline Definitions

Spec-only (6 beats)

RESEARCH-001(+D1) -> DRAFT-001(+D2) -> DRAFT-002(+D3) -> DRAFT-003(+D4) -> DRAFT-004(+D5) -> QUALITY-001(+D6)

Each task includes inline discuss. (+DN) = inline discuss round N executed by the agent internally.

Impl-only (3 beats with parallel window)

PLAN-001 -> IMPL-001 -> TEST-001 || REVIEW-001

TEST-001 and REVIEW-001 run in parallel after IMPL-001 completes.

Full-lifecycle (9 beats)

[Spec pipeline: RESEARCH-001 -> DRAFT-001 -> ... -> QUALITY-001]
    |
    CHECKPOINT: pause for user confirmation
    |
PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 || REVIEW-001

FE-only (3 beats)

PLAN-001 -> DEV-FE-001 -> QA-FE-001

GC loop: if QA-FE verdict is NEEDS_FIX, dynamically create DEV-FE-002 -> QA-FE-002 (max 2 rounds).

Fullstack (4 beats with dual parallel)

PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001

REVIEW-001 is blocked by both TEST-001 and QA-FE-001.

Full-lifecycle-FE (12 tasks)

[Spec pipeline] -> PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001

PLAN-001 blockedBy QUALITY-001. Spec-to-impl checkpoint applies.

Task Metadata Registry

Cadence Control

Beat Model

Event-driven pipeline. Each beat = orchestrator processes one event -> spawns agent(s) -> waits -> processes result -> yields.

Beat Cycle (single beat)
======================================================================
  Event                 Orchestrator                  Agents
----------------------------------------------------------------------
  advance/resume --> +- read state file ------+
                     |  find ready tasks       |
                     |  spawn agent(s) --------+--> [Agent A] executes
                     |  wait(ids, timeout) ----+--> [Agent B] executes
                     +- process results -------+         |
                     |  update state file      |         |
                     |  close agents           |         |
                     +- yield -----------------+         |
                                                         |
  next beat <--- result from wait() <-------------------+
======================================================================

  Fast-Advance (skips full yield for linear successors)
======================================================================
  [Agent A] completes via wait()
    +- 1 ready task? simple linear successor?
    |   YES -> spawn Agent B immediately, enter wait() again
    |   NO  -> yield, wait for user/event
======================================================================

Pipeline Beat View

Spec-only (6 beats, was 12 in v3)
-------------------------------------------------------
Beat  1         2         3         4         5         6
      |         |         |         |         |         |
    R1+D1 --> W1+D2 --> W2+D3 --> W3+D4 --> W4+D5 --> Q1+D6
    ^                                                     ^
  pipeline                                            sign-off
   start                                               pause

R=RESEARCH  W=DRAFT(writer)  Q=QUALITY  D=DISCUSS(inline)

Impl-only (3 beats, with parallel window)
-------------------------------------------------------
Beat  1         2              3
      |         |         +----+----+
      PLAN --> IMPL --> TEST || REVIEW    <-- parallel window
                         +----+----+
                           pipeline
                            done

Full-lifecycle (9 beats)
-------------------------------------------------------
Beat 1-6: [Spec pipeline as above]
                                    |
Beat 6 (Q1+D6 done):      CHECKPOINT -- user confirms then resume
                                    |
Beat 7      8           9
 PLAN --> IMPL --> TEST || REVIEW

Fullstack (with dual parallel windows)
-------------------------------------------------------
Beat  1              2                    3                4
      |         +----+----+         +----+----+           |
      PLAN --> IMPL || DEV-FE --> TEST || QA-FE -->  REVIEW
              ^                ^                   ^
         parallel 1       parallel 2          sync barrier

Checkpoints

Stall Detection

Agent Spawn Template

When the orchestrator spawns an agent for a pipeline task, it uses this template:

const agentId = spawn_agent({
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/<agent-role>.md (MUST read first)
2. Read session state: <session-dir>/team-session.json
3. Read wisdom files: <session-dir>/wisdom/*.md (if exists)

---

## Session
Session directory: <session-dir>
Task ID: <task-id>
Pipeline mode: <mode>

## Scope
<scope-description>

## Task
<task-description>

## InlineDiscuss
<discuss-round-id or "none">

## Dependencies
Completed predecessors: <list of completed task IDs and their artifact paths>

## Constraints
- Only process <PREFIX>-* tasks
- All output prefixed with [<agent-role>] tag
- Write artifacts to <session-dir>/<artifact-subdir>/
- Before each major output, read wisdom files for cross-task knowledge
- After task completion, write discoveries to <session-dir>/wisdom/
- If InlineDiscuss is set, call discuss subagent after primary artifact creation

## Completion Protocol
When work is complete, output EXACTLY:

TASK_COMPLETE:
- task_id: <task-id>
- status: <success | failed>
- artifact: <path-to-primary-artifact>
- discuss_verdict: <consensus_reached | consensus_blocked | none>
- discuss_severity: <HIGH | MEDIUM | LOW | none>
- summary: <one-line summary>
`
})

Session Directory

.workflow/.team/TLS-<slug>-<date>/
+-- team-session.json           # Pipeline state (replaces TaskCreate/TaskList)
+-- spec/                       # Spec 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 subagent)
+-- plan/                       # Plan artifacts
|   +-- plan.json
|   +-- tasks/                  # Detailed task specs
+-- explorations/               # Shared explore 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
+-- .msg/                       # Message bus (UI integration)
|   +-- meta.json               # Pipeline metadata (stages, roles, team_name)
|   +-- messages.jsonl          # NDJSON event log
+-- shared-memory.json          # Cross-agent state

State File Schema (team-session.json)

The state file replaces Claude's TaskCreate/TaskList/TaskGet/TaskUpdate system. The orchestrator owns this file exclusively.

{
  "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
}

Message Bus (.msg/)

The .msg/ directory provides pipeline metadata for the frontend UI. This is the same format used by Claude version's team_msg tool with type: "state_update".

meta.json

Pipeline metadata read by the API for frontend display:

{
  "status": "active",
  "pipeline_mode": "<mode>",
  "pipeline_stages": ["role1", "role2", "..."],
  "roles": ["coordinator", "role1", "role2", "..."],
  "team_name": "lifecycle",
  "role_state": {
    "<role>": {
      "status": "completed",
      "task_id": "TASK-ID",
      "_updated_at": "<ISO8601>"
    }
  },
  "updated_at": "<ISO8601>"
}

pipeline_stages by mode:

messages.jsonl

NDJSON event log (one JSON object per line):

{"id":"MSG-001","ts":"<ISO8601>","from":"coordinator","to":"coordinator","type":"state_update","summary":"Session initialized","data":{...}}
{"id":"MSG-002","ts":"<ISO8601>","from":"analyst","to":"coordinator","type":"impl_complete","summary":"RESEARCH-001 completed","data":{...}}

Message types: state_update, impl_complete, impl_progress, test_result, review_result, error, shutdown

Session Resume

When the orchestrator detects an existing active/paused session:

1. Read team-session.json from session directory
2. For each task with status "in_progress":

- No matching active agent -> task was interrupted -> reset to "pending" - Has matching active agent -> verify agent is still alive (attempt wait with 0 timeout)

1. Reconcile: ensure all expected tasks for the mode exist in state
2. Create missing tasks with correct blocked_by dependencies
3. Verify dependency chain integrity (no cycles, no dangling references)
4. Update state file with reconciled state
5. Proceed to Phase 4 to spawn ready tasks

User Commands

During pipeline execution, the user may issue commands:

Status graph output format:

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

[orchestrator] Execution Graph:
  Spec Phase: (if applicable)
    [V RESEARCH-001(+D1)] -> [V DRAFT-001(+D2)] -> [>>> DRAFT-002(+D3)]
    -> [o DRAFT-003(+D4)] -> [o DRAFT-004(+D5)] -> [o QUALITY-001(+D6)]
  Impl Phase: (if applicable)
    [o PLAN-001]
      +- BE: [o IMPL-001] -> [o TEST-001] -> [o REVIEW-001]
      +- FE: [o DEV-FE-001] -> [o QA-FE-001]

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

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

[orchestrator] Ready to spawn: <task-ids>
[orchestrator] Commands: 'resume' to advance | 'check' to refresh

Lifecycle Management

Timeout Protocol

Convergence request (sent via send_input on timeout):

send_input({
  id: <agent-id>,
  message: `
## TIMEOUT NOTIFICATION

Execution timeout reached. Please:
1. Save all current progress to artifact files
2. Output TASK_COMPLETE with status: partial
3. Include summary of completed vs remaining work
`
})

Cleanup Protocol

When the pipeline completes (or is aborted):

// Close all active agents
for (const agentEntry of state.active_agents) {
  try {
    close_agent({ id: agentEntry.agent_id })
  } catch (e) {
    // Agent already closed, ignore
  }
}

// Update state file
state.status = "completed"  // or "aborted"
state.updated_at = new Date().toISOString()
// Write state file

Error Handling

Frontend Auto-Detection

During Phase 1, the orchestrator detects whether frontend work is needed:

Inline Discuss Protocol (for agents)

Produce agents (analyst, writer, reviewer) call the discuss subagent after completing their primary artifact. The protocol is documented here for reference; each agent's role file contains the specific invocation.

Discussion round mapping:

Agent-side discuss invocation (inside the agent, not orchestrator):

// Agent spawns discuss subagent internally
const discussId = spawn_agent({
  message: `
## MANDATORY FIRST STEPS (Agent Execute)
1. **Read agent definition**: ~/.codex/agents/discuss-agent.md (MUST read first)

---

## Multi-Perspective Critique: <round-id>

### Input
- Artifact: <artifact-path>
- Round: <round-id>
- Perspectives: <perspective-list>
- Session: <session-dir>
- Discovery Context: <session-dir>/spec/discovery-context.json

### Execution
Per-perspective CLI analysis -> divergence detection -> consensus determination -> write record.

### Output
Write discussion record to: <session-dir>/discussions/<round-id>-discussion.md
Return verdict summary with: verdict, severity, average_rating, action_items, recommendation.
`
})

const discussResult = wait({ ids: [discussId], timeout_ms: 300000 })
close_agent({ id: discussId })
// Agent includes discuss result in its TASK_COMPLETE output

Shared Explore Protocol (for agents)

Any agent needing codebase context calls the explore subagent. Results are cached in explorations/.

Agent-side explore invocation (inside the agent, not orchestrator):

// Agent spawns explore subagent internally
const exploreId = spawn_agent({
  message: `
## MANDATORY FIRST STEPS (Agent Execute)
1. **Read agent definition**: ~/.codex/agents/explore-agent.md (MUST read first)

---

## Explore Codebase

Query: <query>
Focus angle: <angle>
Keywords: <keyword-list>
Session folder: <session-dir>

## Cache Check
1. Read <session-dir>/explorations/cache-index.json (if exists)
2. If matching angle found AND file exists -> return cached result
3. If not found -> proceed to exploration

## Output
Write JSON to: <session-dir>/explorations/explore-<angle>.json
Update cache-index.json with new entry.
Return summary: file count, pattern count, top 5 files, output path.
`
})

const exploreResult = wait({ ids: [exploreId], timeout_ms: 300000 })
close_agent({ id: exploreId })

Cache lookup rules:

Wisdom Accumulation

Cross-task knowledge accumulation. Orchestrator creates wisdom/ at session init.

Directory:

<session-dir>/wisdom/
+-- learnings.md      # Patterns and insights discovered
+-- decisions.md      # Architecture and design decisions made
+-- conventions.md    # Codebase conventions identified
+-- issues.md         # Known risks and issues flagged

Agent responsibilities:

• On start: read all wisdom files for cross-task context
• During work: append discoveries to appropriate wisdom file
• On complete: include significant findings in TASK_COMPLETE summary

Role Isolation Rules

Orchestrator additionally prohibited: directly write/modify code, call implementation tools, execute analysis/test/review work.

GC Loop (Frontend QA)

For FE pipelines, QA-FE may trigger a fix-retest cycle:

Round 1: DEV-FE-001 -> QA-FE-001
  QA-FE verdict: NEEDS_FIX?
    YES -> Round 2: DEV-FE-002(blocked_by: QA-FE-001) -> QA-FE-002(blocked_by: DEV-FE-002)
    QA-FE-002 verdict: NEEDS_FIX?
      YES -> max rounds reached (2), stop loop, report current state
      NO  -> proceed to next pipeline step
    NO -> proceed to next pipeline step

The orchestrator dynamically adds DEV-FE-NNN and QA-FE-NNN tasks to the state file when a GC loop iteration is needed.

Mode-to-Pipeline Quick Reference

Shared Spec Resources

Coordinator Role Constraints (Main Agent)

CRITICAL: The coordinator (main agent executing this skill) is responsible for orchestration only, NOT implementation.

1. Coordinator Does NOT Execute Code: The main agent MUST NOT write, modify, or implement any code directly. All implementation work is delegated to spawned team agents. The coordinator only:

- Spawns agents with task assignments - Waits for agent callbacks - Merges results and coordinates workflow - Manages workflow transitions between phases

1. Patient Waiting is Mandatory: Agent execution takes significant time (typically 10-30 minutes per phase, sometimes longer). The coordinator MUST:

- Wait patiently for wait() calls to complete - NOT skip workflow steps due to perceived delays - NOT assume agents have failed just because they're taking time - Trust the timeout mechanisms defined in the skill

1. Use send_input for Clarification: When agents need guidance or appear stuck, the coordinator MUST:

- Use send_input() to ask questions or provide clarification - NOT skip the agent or move to next phase prematurely - Give agents opportunity to respond before escalating - Example: send_input({id: agent_id, message: "Please provide status update or clarify blockers"})

1. No Workflow Shortcuts: The coordinator MUST NOT:

- Skip phases or stages defined in the workflow - Bypass required approval or review steps - Execute dependent tasks before prerequisites complete - Assume task completion without explicit agent callback - Make up or fabricate agent results

1. Respect Long-Running Processes: This is a complex multi-agent workflow that requires patience:

- Total execution time may range from 30-90 minutes or longer - Each phase may take 10-30 minutes depending on complexity - The coordinator must remain active and attentive throughout the entire process - Do not terminate or skip steps due to time concerns