# How the Team Staged Pipeline Works in oh-my-claudecode: A Complete Guide to team-plan, team-prd, team-exec, team-verify, and team-fix

> Understand the Team staged pipeline in oh-my-claudecode. Explore teamplan, teamprd, teamexec, teamverify, and teamfix for efficient AI agent coordination in software tasks.

- Repository: [Bellman/oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)
- Tags: how-to-guide
- Published: 2026-03-27

---

**The Team staged pipeline in oh-my-claudecode operates as a canonical five-phase orchestration system—team-plan → team-prd → team-exec → team-verify → team-fix—that uses persistent state management, enforced transitions, and bounded verification loops to coordinate multiple AI agents through complex software tasks.**

The oh-my-claudecode repository implements a native multi-agent orchestration layer called **Team mode** that executes software development tasks through a rigid staged pipeline. This system ensures that specialized agents collaborate sequentially while maintaining state persistence across crashes and cancellations, as defined in [`skills/team/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/skills/team/SKILL.md) lines 96-98.

## Pipeline Architecture and State Management

### The Five Canonical Stages

The pipeline follows a strict progression through five phases:

```

team-plan → team-prd → team-exec → team-verify → team-fix (loop)

```

Each stage represents a distinct phase of software development: architectural planning, requirements analysis, task execution, verification, and defect remediation. The sequence is enforced by the transition logic in [`src/hooks/team-pipeline/transitions.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/team-pipeline/transitions.ts).

### Persistent State Schema

The runtime state lives in a JSON file managed by the `state_write` MCP tool, with its TypeScript schema defined in [`src/hooks/team-pipeline/types.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/team-pipeline/types.ts) (lines 9-49). The state object tracks:

- **`phase`**: Current stage—one of `team-plan`, `team-prd`, `team-exec`, `team-verify`, `team-fix`, `complete`, `failed`, or `cancelled` (lines 9-17)
- **`artifacts`**: Paths to deliverables including `plan_path`, `prd_path`, and `verify_report_path` (lines 25-30)
- **`execution`**: Counters for task tracking including `tasks_total` and `tasks_completed` (lines 31-37)
- **`fix_loop`**: Iteration bookkeeping with `attempt` and `max_attempts` fields (lines 39-43)
- **`cancel`**: Metadata including the `preserve_for_resume` flag for crash recovery (lines 45-49)

## Transition Enforcement and Guard Conditions

### Allowed Transitions Map

State transitions are strictly enforced by the `ALLOWED` constant in [`src/hooks/team-pipeline/transitions.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/team-pipeline/transitions.ts) (lines 5-13):

```typescript
const ALLOWED: Record<TeamPipelinePhase, TeamPipelinePhase[]> = {
  'team-plan': ['team-prd'],
  'team-prd':  ['team-exec'],
  'team-exec': ['team-verify'],
  'team-verify': ['team-fix', 'complete', 'failed'],
  'team-fix':   ['team-exec', 'team-verify', 'complete', 'failed'],
};

```

The `isAllowedTransition` helper (lines 16-18) validates requests against this map. If a request violates the allowed transitions, the system returns a clear error with `ok: false` (lines 55-60).

### Artifact and Execution Guards

Before accepting transitions, the pipeline validates prerequisites through guard conditions implemented in `hasRequiredArtifactsForPhase`:

- **`team-exec`**: Requires either `plan_path` or `prd_path` artifacts from previous planning phases (lines 25-30)
- **`team-verify`**: Validates that `tasks_total` and `tasks_completed` are non-negative, finite, and that all tasks reach terminal states (lines 32-45)

If guards fail, `transitionTeamPhase` returns `{ ok: false, reason: '...' }` with a human-readable explanation (lines 81-88).

## Stage Contracts and Agent Responsibilities

Each stage maintains strict entry and exit contracts defined in [`skills/team/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/skills/team/SKILL.md) (lines 119-140):

**team-plan**: Entry requires parsed invocation and orchestration start with `explore` and `planner` agents; exit requires complete decomposition with a runnable task graph.

**team-prd**: Entry triggers when scope is ambiguous or acceptance criteria are missing, activating the `analyst` agent; exit produces explicit acceptance criteria and boundaries.

**team-exec**: Entry occurs after team/task creation with properly owned workers; exit requires all tasks to reach `completed` or `failed` terminal states.

**team-verify**: Entry follows execution completion with `verifier` agents; exit routes to `complete` if verification passes, `team-fix` if defects exist, or `failed` for terminal errors.

**team-fix**: Entry spawns fix-oriented agents (`executor`, `debugger`); exit returns to `team-exec` or `team-verify` to revalidate fixes.

## The Verify-Fix Loop and Bounded Iterations

The `team-verify` stage implements a bounded feedback loop for defect remediation. When verification identifies defects, the pipeline transitions to `team-fix` rather than failing immediately.

The fix loop is bounded by `fix_loop.max_attempts` defined in the state. As implemented in [`transitions.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/transitions.ts) (lines 47-48), if `fix_loop.attempt` exceeds this limit, `transitionTeamPhase` routes to the `failed` terminal state instead of allowing another iteration. This prevents infinite cycles between verification and remediation.

## Cancellation, Resume, and Handoff Protocols

### Crash-Resistant State Management

If a user cancels the team, `requestTeamCancel` in [`transitions.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/transitions.ts) (lines 96-108) sets `phase: 'cancelled'` and `active: false`. Resumption requires `preserve_for_resume: true`; otherwise, the transition is rejected (lines 63-71).

### Handoff Documents

Every stage must emit a handoff file under `.omc/handoffs/` before transitioning, as specified in [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) (lines 151-166). These files preserve decision history, enabling crash-restarted lead agents to reconstruct context without losing progress.

## Practical Code Examples

### Initializing Team State

When invoking the Team mode, the system writes initial state via the `state_write` tool:

```typescript
state_write(
  mode="team",
  active=true,
  current_phase="team-plan",
  state={
    "team_name": "refactor-auth",
    "agent_count": 3,
    "task": "refactor authentication module",
    "stage_history": "team-plan"
  }
)

```

### Validating Transitions with Guards

Attempting to enter execution without planning artifacts triggers guard failures:

```typescript
// Missing required artifacts
transitionTeamPhase(state, 'team-exec')
/* Returns:
{
  ok: false,
  reason: 'team-exec requires plan_path or prd_path artifact'
}
*/

```

The guard logic in `hasRequiredArtifactsForPhase` (lines 25-31) enforces this requirement to ensure execution agents have architectural guidance.

### Implementing the Fix Loop

After failed verification, the bounded loop logic executes:

```typescript
state.fix_loop.attempt += 1;
if (state.fix_loop.attempt > state.fix_loop.max_attempts) {
  transitionTeamPhase(state, 'failed', 'fix loop exhausted')
} else {
  transitionTeamPhase(state, 'team-fix', 'defects found')
}

```

This pattern appears in the transition handler to prevent infinite remediation attempts.

## Summary

- The **Team staged pipeline** in oh-my-claudecode implements a rigid five-phase workflow: **team-plan → team-prd → team-exec → team-verify → team-fix**.
- **State persistence** via `state_write` and the schema in [`src/hooks/team-pipeline/types.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/src/hooks/team-pipeline/types.ts) enables crash recovery and cancellation resume capabilities.
- **Transition enforcement** in [`transitions.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/transitions.ts) uses an `ALLOWED` map and `isAllowedTransition` to prevent invalid stage jumps.
- **Guard conditions** ensure `team-exec` has planning artifacts and `team-verify` has completed task counters before activation.
- The **verify-fix loop** is bounded by `max_attempts` to prevent infinite remediation cycles.
- **Handoff files** in `.omc/handoffs/` preserve context across stage boundaries and system restarts.

## Frequently Asked Questions

### What happens if the team-fix loop exceeds max_attempts?

When `fix_loop.attempt` exceeds `fix_loop.max_attempts` in the state, the `transitionTeamPhase` function routes the pipeline to the `failed` terminal state rather than allowing another iteration. This bounds the remediation process and prevents infinite loops between verification and fixing, as implemented in lines 47-48 of [`transitions.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/transitions.ts).

### Can I resume a cancelled Team mode session?

Yes, but only if the cancellation was requested with `preserve_for_resume: true`. The `requestTeamCancel` function sets this flag in the state metadata (lines 96-108 of [`transitions.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/transitions.ts)). When resuming, the transition logic checks this flag; if false, the resume transition is rejected to prevent corruption of stale state.

### Why does team-exec require either plan_path or prd_path?

The `hasRequiredArtifactsForPhase` guard in [`transitions.ts`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/transitions.ts) (lines 25-31) enforces this requirement because execution agents cannot operate without the planning outputs from either the `team-plan` or `team-prd` phases. This ensures architectural decisions and requirements analysis precede implementation work.

### How does the pipeline handle crashes during stage transitions?

The pipeline maintains persistent state through the `state_write` MCP tool. Each stage emits handoff documents to `.omc/handoffs/` before transitioning, as documented in [`SKILL.md`](https://github.com/Yeachan-Heo/oh-my-claudecode/blob/main/SKILL.md) lines 151-166. If the system crashes, the lead agent reads these handoffs upon restart to reconstruct the decision history and resume from the last valid `phase` recorded in the state JSON.