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

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 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.

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 (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 (lines 5-13):

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 (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 (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 (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 (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:

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:

// 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:

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 enables crash recovery and cancellation resume capabilities.
• Transition enforcement in 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.

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). 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 (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}