Team Planex

Team PlanEx

Unified team skill: plan-and-execute pipeline for issue-based development. Built on team-worker agent architecture — coordinator orchestrates, workers are team-worker agents loading role-specific instructions from roles/<role>/role.md.

Architecture

Skill(skill="team-planex", args="task description")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze -> dispatch -> spawn workers -> STOP
                                    |
                    +---------------+---------------+
                    v                               v
               [planner]                       [executor]
         (team-worker agent,            (team-worker agent,
          loads roles/planner/role.md)   loads roles/executor/role.md)

Role Registry

Role Router

Parse $ARGUMENTS:

• Has --role <name> → Read roles/<name>/role.md, execute Phase 2-4
• No --role → @roles/coordinator/role.md, execute entry router

Shared Constants

• Session prefix: PEX
• Session path: .workflow/.team/PEX-<slug>-<date>/
• CLI tools: ccw cli --mode analysis (read-only), ccw cli --mode write (modifications)
• Message bus: mcp__ccw-tools__team_msg(session_id=<session-id>, ...)

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: "planex",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: planex
requirement: <task-description>
inner_loop: <true|false>
execution_method: <codex|gemini>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

User Commands

Session Directory

.workflow/.team/PEX-<slug>-<YYYY-MM-DD>/
├── .msg/
│   ├── messages.jsonl          # Message bus log
│   └── meta.json               # Session state
├── task-analysis.json          # Coordinator analyze output
├── artifacts/
│   └── solutions/              # Planner solution output per issue
│       ├── <issueId-1>.json
│       └── <issueId-N>.json
└── wisdom/                     # Cross-task knowledge
    ├── learnings.md
    ├── decisions.md
    ├── conventions.md
    └── issues.md

Specs Reference

• specs/pipelines.md — Pipeline definitions, task metadata registry, execution method selection

Error Handling

Analyze Task

Parse plan-and-execute input -> detect input type -> determine execution method -> assess scope.

CONSTRAINT: Text-level analysis only. NO source code reading, NO codebase exploration.

Signal Detection

Execution Method Selection

Scope Assessment

Output

Write <session>/task-analysis.json:

{
  "task_description": "<original>",
  "input_type": "<issues|text|plan>",
  "raw_input": "<original input>",
  "execution_method": "<codex|gemini>",
  "issue_count_estimate": 0,
  "complexity": { "score": 0, "level": "Low|Medium|High" },
  "pipeline_type": "plan-execute",
  "roles": [
    { "name": "planner", "prefix": "PLAN", "inner_loop": true },
    { "name": "executor", "prefix": "EXEC", "inner_loop": true }
  ]
}

Command: dispatch

Purpose

Create the initial task chain for team-planex pipeline. Creates PLAN-001 for planner. EXEC-* tasks are NOT pre-created — planner creates them at runtime per issue.

Phase 2: Context Loading

Phase 3: Task Chain Creation

Task Creation

Create a single PLAN-001 task for the planner:

TaskCreate({
  subject: "PLAN-001: Requirement decomposition and solution design",
  description: `Decompose requirements into issues and generate solutions.

Input type: <issues|text|plan>
Input: <raw-input>
Session: <session-folder>
Execution method: <agent|codex|gemini>

## Instructions
1. Parse input to get issue list
2. For each issue: call issue-plan-agent → write solution artifact
3. After each solution: create EXEC-* task with solution_file path, then TaskUpdate to set owner: executor
4. After all issues: send all_planned signal

InnerLoop: true`,
  activeForm: "Planning requirements"
})

EXEC-* Task Template (for planner reference)

Planner creates EXEC-* tasks at runtime using this template:

TaskCreate({
  subject: "EXEC-00N: Implement <issue-title>",
  description: `Implement solution for issue <issueId>.

Issue ID: <issueId>
Solution file: <session-folder>/artifacts/solutions/<issueId>.json
Session: <session-folder>
Execution method: <agent|codex|gemini>

InnerLoop: true`,
  activeForm: "Implementing <issue-title>"
})

Add Command Task Template

When coordinator handles add command, create additional PLAN tasks:

TaskCreate({
  subject: "PLAN-00N: Additional requirement decomposition",
  description: `Additional requirements to decompose.

Input type: <issues|text|plan>
Input: <new-input>
Session: <session-folder>
Execution method: <execution-method>

InnerLoop: true`,
  activeForm: "Planning additional requirements"
})

Phase 4: Validation

Command: monitor

Purpose

Event-driven pipeline coordination with Spawn-and-Stop pattern. Three wake-up sources: worker callbacks, user check, user resume.

Constants

Phase 2: Context Loading

Phase 3: Handler Routing

Wake-up Source Detection

---

Handler: handleCallback

Receive callback from [<role>]
  +- Match role: planner or executor
  +- Progress update (not final)?
  |   +- YES -> Update session -> STOP
  +- Task status = completed?
  |   +- YES -> remove from active_workers -> update session
  |   |   +- role = planner?
  |   |   |   +- Check for new EXEC-* tasks (planner creates them)
  |   |   |   +- -> handleSpawnNext (spawn executor for new EXEC-* tasks)
  |   |   +- role = executor?
  |   |       +- Mark issue done
  |   |       +- -> handleSpawnNext (check for more EXEC-* tasks)
  |   +- NO -> progress message -> STOP
  +- No matching worker found
      +- Scan all active workers for completed tasks
      +- Found completed -> process -> handleSpawnNext
      +- None completed -> STOP

---

Handler: handleCheck

Read-only status report. No advancement.

Worker Progress (from message bus):

Before generating status output, read worker milestones:

const progressMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "progress", last: 50
})
const blockerMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "blocker", last: 10
})

// Aggregate latest milestone per task
const taskProgress = {}
for (const msg of (progressMsgs.result?.messages || [])) {
  const tid = msg.data?.task_id
  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
  }
}

Include in status output:

• Per-worker latest milestone (phase + progress_pct) next to task status
• Active blockers section (if any blockerMsgs found)

[coordinator] PlanEx Pipeline Status
[coordinator] Progress: <completed>/<total> (<percent>%)

[coordinator] Task Graph:
  PLAN-001: <status-icon> <summary>
  EXEC-001: <status-icon> <issue-title>
  EXEC-002: <status-icon> <issue-title>
  ...

  done=completed  >>>=running  o=pending

[coordinator] Active Workers:
  > <subject> (<role>) - running <elapsed>

[coordinator] Ready to spawn: <subjects>
[coordinator] Commands: 'resume' to advance | 'check' to refresh

Then STOP.

---

Handler: handleResume

Load active_workers
  +- No active workers -> handleSpawnNext
  +- Has active workers -> check each:
      +- completed -> mark done, log
      +- in_progress -> still running
      +- other -> worker failure -> reset to pending
      After:
        +- Some completed -> handleSpawnNext
        +- All running -> report status -> STOP
        +- All failed -> handleSpawnNext (retry)

---

Handler: handleSpawnNext

Collect task states from TaskList()
  +- Filter tasks: PLAN-* and EXEC-* prefixes
  +- readySubjects: pending + not blocked (no blockedBy or all blockedBy completed)
  +- NONE ready + work in progress -> report waiting -> STOP
  +- NONE ready + nothing running -> PIPELINE_COMPLETE -> Phase 5
  +- HAS ready tasks -> for each:
      +- Inner Loop role AND already has active_worker for that role?
      |   +- YES -> SKIP spawn (existing worker picks up via inner loop)
      |   +- NO -> spawn below
      +- Determine role from task prefix:
      |   +- PLAN-* -> planner
      |   +- EXEC-* -> executor
      +- Spawn team-worker:
         Agent({
           subagent_type: "team-worker",
           description: "Spawn <role> worker for <subject>",
           team_name: <team-name>,
           name: "<role>",
           run_in_background: true,
           prompt: `## Role Assignment
role: <role>
role_spec: ~  or <project>/.claude/skills/team-planex/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: true
execution_method: <method>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.`
         })
      +- Add to session.active_workers
      Update session -> output summary -> STOP

---

Phase 4: Validation

Worker Failure Handling

1. Reset task -> pending via TaskUpdate 2. Log via team_msg (type: error) 3. Report to user

Error Handling

Coordinator Role

Orchestrate team-planex: analyze -> dispatch -> spawn -> monitor -> report.

Identity

• Name: coordinator | Tag: [coordinator]
• Responsibility: Parse input -> Create team -> Dispatch PLAN-001 -> Spawn planner -> Monitor callbacks -> Spawn executors -> Report

Boundaries

MUST

• Parse user input (Issue IDs / --text / --plan) and determine execution method
• Create team and initialize session directory
• Dispatch tasks via commands/dispatch.md
• Monitor progress via commands/monitor.md with Spawn-and-Stop pattern
• Maintain session state (.msg/meta.json)

MUST NOT

• Execute planning or implementation work directly (delegate to workers)
• Modify solution artifacts or code (workers own their deliverables)
• Call implementation CLI tools (code-developer, etc.) directly
• Skip dependency validation when creating task chains

Command Execution Protocol

When coordinator needs to execute a command: 1. Read commands/<command>.md 2. Follow the workflow defined in the command 3. Commands are inline execution guides, NOT separate agents 4. Execute synchronously, complete before proceeding

Entry Router

For callback/check/resume: load @commands/monitor.md and execute the appropriate handler, then STOP.

handleAdd

1. Parse new input (Issue IDs / --text / --plan) 2. Get current max PLAN-* sequence from TaskList 3. TaskCreate new PLAN-00N task, then TaskUpdate to set owner: planner 4. If planner already sent all_planned (check team_msg) -> SendMessage to planner to re-enter loop 5. STOP

Phase 0: Session Resume Check

1. Scan .workflow/.team/PEX-*/.msg/meta.json for sessions with status "active" or "paused" 2. No sessions -> Phase 1 3. Single session -> resume (Session Reconciliation) 4. Multiple sessions -> AskUserQuestion for selection

Session Reconciliation: 1. Audit TaskList -> reconcile session state vs task status 2. Reset in_progress tasks -> pending (they were interrupted) 3. Rebuild team if needed (TeamCreate + spawn needed workers) 4. Kick first executable task -> Phase 4

Phase 1: Input Parsing + Execution Method

TEXT-LEVEL ONLY. No source code reading.

1. Delegate to @commands/analyze.md -> produces task-analysis.json 2. Parse arguments: Extract input type (Issue IDs / --text / --plan) and optional flags (--exec, -y) 3. Determine execution method (see specs/pipelines.md Selection Decision Table):

• Explicit --exec flag -> use specified method
• -y / --yes flag -> Auto mode
• No flags -> AskUserQuestion for method choice

4. Store requirements: input_type, raw_input, execution_method 5. CRITICAL: Always proceed to Phase 2, never skip team workflow

Phase 2: Create Team + Initialize Session

1. Resolve workspace paths (MUST do first):

• project_root = result of Bash({ command: "pwd" })
• skill_root = <project_root>/.claude/skills/team-planex

2. Generate session ID: PEX-<slug>-<date> 3. Create session folder: .workflow/.team/<session-id>/ 4. Create subdirectories: artifacts/solutions/, wisdom/ 5. Call TeamCreate with team name (default: "planex") 6. Initialize wisdom files (learnings.md, decisions.md, conventions.md, issues.md) 7. Initialize meta.json with pipeline metadata:

mcp__ccw-tools__team_msg({
  operation: "log", session_id: "<id>", from: "coordinator",
  type: "state_update", summary: "Session initialized",
  data: {
    pipeline_mode: "plan-execute",
    pipeline_stages: ["planner", "executor"],
    roles: ["coordinator", "planner", "executor"],
    team_name: "planex",
    input_type: "<issues|text|plan>",
    execution_method: "<codex|gemini>"
  }
})

Phase 3: Create Task Chain

Delegate to @commands/dispatch.md: 1. Read roles/coordinator/commands/dispatch.md 2. Execute its workflow to create PLAN-001 task 3. PLAN-001 contains input info + execution method in description

Phase 4: Spawn-and-Stop

1. Load @commands/monitor.md 2. Execute handleSpawnNext to find ready tasks and spawn planner worker 3. Output status summary 4. STOP (idle, wait for worker callback)

ONE_STEP_PER_INVOCATION: true — coordinator does one operation per wake-up, then STOPS.

Phase 5: Report + Completion Action

1. Load session state -> count completed tasks, duration 2. List deliverables with output paths 3. Update session status -> "completed" 4. Execute Completion Action per session.completion_action:

• interactive -> AskUserQuestion (Archive/Keep/Export)
• auto_archive -> Archive & Clean (status=completed, TeamDelete)
• auto_keep -> Keep Active (status=paused)
• auto_yes -> Archive & Clean without prompting

Error Handling

Executor

Single-issue implementation agent. Loads solution from artifact file, routes to execution backend (Codex/Gemini), verifies with tests, commits, and reports completion.

Phase 2: Task & Solution Loading

1. Extract issue ID, solution file path, session folder, execution method 2. Load solution JSON from file (file-first) 3. If file not found -> fallback: ccw issue solution <issueId> --json 4. Load wisdom files for conventions and patterns 5. Verify solution has required fields: title, tasks

Phase 3: Implementation

Backend Selection

CLI Backend (Codex/Gemini)

ccw cli -p "PURPOSE: Implement solution for issue <issueId>; success = all tasks completed, tests pass
TASK: <solution.tasks as bullet points>
MODE: write
CONTEXT: @**/* | Memory: Session wisdom from <session>/wisdom/
EXPECTED: Working implementation with: code changes, test updates, no syntax errors
CONSTRAINTS: Follow existing patterns | Maintain backward compatibility
Issue: <issueId>
Title: <solution.title>
Solution: <solution JSON>" --tool <codex|gemini> --mode write --rule development-implement-feature

Wait for CLI completion before proceeding to verification.

Phase 4: Verification + Commit

Test Verification

If tests fail: retry implementation once, then report impl_failed.

Commit

git add -A
git commit -m "feat(<issueId>): <solution.title>"

Update Issue Status

ccw issue update <issueId> --status completed

Report

Send impl_complete message to coordinator via team_msg + SendMessage.

Boundaries

Planner

Requirement decomposition -> issue creation -> solution design -> EXEC-* task creation. Processes issues one at a time, creating executor tasks as solutions are completed.

Phase 2: Context Loading

1. Extract session path, input type, raw input, execution method from task description 2. Load wisdom files if available 3. Parse input to determine issue list:

Phase 3: Issue Processing Loop

For each issue, execute in sequence:

3a. Generate Solution

Use CLI tool for issue planning:

ccw cli -p "PURPOSE: Generate implementation solution for issue <issueId>; success = actionable task breakdown with file paths
TASK: • Load issue details • Analyze requirements • Design solution approach • Break down into implementation tasks • Identify files to modify/create
MODE: analysis
CONTEXT: @**/* | Memory: Session context from <session>/wisdom/
EXPECTED: JSON solution with: title, description, tasks array (each with description, files_touched), estimated_complexity
CONSTRAINTS: Follow project patterns | Reference existing implementations
" --tool gemini --mode analysis --rule planning-breakdown-task-steps

Parse CLI output to extract solution JSON. If CLI fails, fallback to ccw issue solution <issueId> --json.

3b. Write Solution Artifact

Write solution JSON to: <session>/artifacts/solutions/<issueId>.json

{
  "session_id": "<session-id>",
  "issue_id": "<issueId>",
  "solution": "<solution-from-agent>",
  "planned_at": "<ISO timestamp>"
}

3c. Check Conflicts

Extract files_touched from solution. Compare against prior solutions in session. Overlapping files -> log warning to wisdom/issues.md, continue.

3d. Create EXEC-* Task

TaskCreate({
  subject: "EXEC-00N: Implement <issue-title>",
  description: `Implement solution for issue <issueId>.

Issue ID: <issueId>
Solution file: <session>/artifacts/solutions/<issueId>.json
Session: <session>
Execution method: <method>

InnerLoop: true`,
  activeForm: "Implementing <issue-title>"
})

3e. Signal issue_ready

Send message via team_msg + SendMessage to coordinator:

• type: issue_ready

3f. Continue Loop

Process next issue. Do NOT wait for executor.

Tech Profile Scan

After issue processing, emit context-aware trigger signals (based on detected codebase characteristics):

1. Check issue scope and code patterns → signals (sql_detected, auth_detected, perf_sensitive) 2. Check plan complexity → signals (breaking_change, scaling_concern, data_migration) 3. Include tech_profile in Phase 5 state_update data

Phase 4: Completion Signal

After all issues processed: 1. Send all_planned message to coordinator via team_msg + SendMessage 2. Summary: total issues planned, EXEC-* tasks created

Boundaries

PlanEx Pipeline Definitions

Pipeline Diagram

Issue-based beat pipeline — planner creates EXEC-* tasks at runtime as solutions are completed.

PLAN-001 ──> [planner] issue-1 solution -> EXEC-001
                        issue-2 solution -> EXEC-002
                        ...
                        issue-N solution -> EXEC-00N
                        all_planned signal

EXEC-001 ──> [executor] implement issue-1
EXEC-002 ──> [executor] implement issue-2
...
EXEC-00N ──> [executor] implement issue-N

Beat Cycle

Event-driven Spawn-and-Stop. Each beat = coordinator wake -> process callback -> spawn next -> STOP.

Event                   Coordinator              Workers
----------------------------------------------------------------------
User invokes -------> Phase 1-3:
                        Parse input
                        TeamCreate
                        Create PLAN-001
                      Phase 4:
                        spawn planner ---------> [planner] Phase 1-5
                        STOP (idle)                      |
                                                         |
callback <-- planner issue_ready -(per issue)-----------+
         handleCallback:
           detect new EXEC-* tasks
           spawn executor ---------------------> [executor] Phase 1-5
           STOP (idle)                                   |
                                                         |
callback <-- executor impl_complete ---------------------+
         handleCallback:
           mark issue done
           check next ready EXEC-*
           spawn next executor / STOP

Task Metadata Registry

EXEC-* tasks are created by planner at runtime (per-issue beat), not predefined in the task chain.

Execution Method Selection

Input Type Detection

Checkpoints

Scope Assessment