Team Planex
Productivityteam-planexTeam Planex is an Agent Skill for productivity published in the catlog22/maestro-flow repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Unified team skill for plan-and-execute pipeline. Pure router — coordinator always. Beat model is coordinator-only in monitor.md. Triggers on "team planex".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/catlog22/maestro-flow/blob/HEAD/.codex/skills/team-planex/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/team-planex, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Agent timeout:
spawn_agent异步执行且无内置超时 — 除明确短任务外一律spawn_agent后立即wait_agent({ timeout_ms: 3600000 })(上限 1 小时)阻塞等待,绝不依赖 30000 默认值;timed_out: true且 Agent 未完成时再次wait_agent续等,不丢弃。批量场景使用spawn_agents_on_csv({ max_runtime_seconds: 3600, ... })。
<required_reading> @~/.maestro/workflows/run-mode-lite.md </required_reading>
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
spawn_agent({ task_name: "team_planex", message: "Execute 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 | Path | Prefix | Inner Loop |
|---|---|---|---|
| coordinator | roles/coordinator/role.md | — | — |
| planner | roles/planner/role.md | PLAN-* | true |
| executor | roles/executor/role.md | EXEC-* | true |
Pre-load (coordinator, before dispatch)
- Codebase docs: If
.workflow/codebase/ARCHITECTURE.mdexists, read for module boundaries - Specs (arch):
maestro load --type spec --category arch— load arch constraints as shared context - Specs (coding):
maestro load --type spec --category coding— load coding constraints as shared context - Wiki knowledge:
maestro search "plan execute implementation" --json— top 5 entries as prior context - All optional — proceed without if unavailable
Role Router
Parse $ARGUMENTS:
- Has
--role <name>→ Readroles/<name>/role.md, execute Phase 2-4 - No
--role→@roles/coordinator/role.md, execute entry router
Shared Constants
- Session prefix:
PEX - Session path:
{run_dir}/work/team/ - CLI tools:
maestro delegate --mode analysis(read-only),maestro delegate --mode write(modifications) - Message bus:
mcp__maestro__team_msg(session_id=<run-id>, ...)
Worker Spawn Template
Coordinator spawns workers using this template:
spawn_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: {run_dir}/work/team
session_id: <run-id>
team_name: planex
requirement: <task-description>
inner_loop: <true|false>
run_dir: <run-dir from team-session.json run.run_dir>
execution_method: <codex|agy>
## Progress Milestones
session_id: <run-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 send_message.
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
| Command | Action |
|---|---|
check / status | View execution status graph |
resume / continue | Advance to next step |
add <issue-ids or --text '...' or --plan path> | Append new tasks to planner queue |
Session Directory
{run_dir}/
├── outputs/
│ └── solutions/ # Planner solution output per issue
│ ├── <issueId-1>.json
│ └── <issueId-N>.json
├── report.md # Human-readable synthesis + handoff
└── work/team/ # Team coordination (non-artifact)
├── team-session.json # Coordination state + run block
├── .msg/
│ ├── messages.jsonl # Message bus log
│ └── meta.json # Message-bus state (state_update log)
├── task-analysis.json # Coordinator analyze output
└── 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
| Scenario | Resolution |
|---|---|
| Unknown command | Error with available command list |
| Role not found | Error with role registry |
| Role spec file not found | Error with expected path (roles//role.md) |
| team-worker agent unavailable | Error: requires .claude/agents/team-worker.md |
| Planner issue planning failure | Retry once, then skip to next issue |
| Executor impl failure | Report to coordinator, continue with next EXEC-* task |
| Pipeline stall | Coordinator monitors, escalate to user |
| Worker no response | Report waiting task, suggest user resume |