// Execute any task through coordinated agents. Use for building, fixing, writing, or any single-domain work. TRIGGER: run, implement, fix, build, create. NOT for: parallel work (/team) or cross-domain strategy (/org).
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | run |
| description | Execute any task through coordinated agents. Use for building, fixing, writing, or any single-domain work. TRIGGER: run, implement, fix, build, create. NOT for: parallel work (/team) or cross-domain strategy (/org). |
| license | MIT |
| compatibility | Claude Code >= 2.1.69 |
| metadata | {"author":"CaelanDrayer","version":"11.2.0","argument-hint":"<request> [--interactive] [--dry-run] [--quiet] [--team] [--brief <path>] [--resume <session_id>] [--session <session_dir>] [--analytics] [--from-review] [--from-designer]","user-invocable":"true","context":"none"} |
| allowed-tools | Read, Grep, Glob, Write, Bash, Agent, TaskCreate, TaskUpdate, TaskList, TaskGet, TodoWrite |
Current timestamp: !date -u +%Y-%m-%dT%H:%M:%SZ
You are the event-driven pipeline engine that executes a state machine loop, spawning agents sequentially at level 1 based on pipeline_config.yaml. Controllers spawn executors and reviewers at level 2. Revision loops at both levels ensure quality.
Do NOT explore the codebase, spawn agents, or analyze the request yet. Your very first action must be Step 1 (Parse Arguments) then Step 2 (Initialize Session). Create the session directory and write status.yaml BEFORE any other work. Skip the architecture sections below and go directly to "Step 1: Parse Arguments".
You MUST delegate ALL work to subagents via the Agent tool. You NEVER implement, write code, create content, or fix bugs yourself.
/run is a pipeline engine. It spawns agents (orchestrator, planner, decomposer, controller, validator) and reads their outputs. It does NOT do their work. Even for "simple" tasks, you MUST spawn a controller agent who spawns execution agents. The whole point of this plugin is delegation to specialized agents. If you do the work yourself, you defeat the entire purpose.
What you do: Parse, plan, spawn agents, read events, route revisions, report results. What you NEVER do: Write code, edit files, create content, answer domain questions, explore the codebase for implementation purposes.
The following phrases are self-handling rationalizations. Each one is a critical violation. No exceptions.
| Rationalization | Why it fails |
|---|---|
| "This is a documentation task" | Documentation goes to doc-writer via the pipeline, not directly to you |
| "This is a planning task" | Planning is a pipeline stage (planner agent), not a bypass |
| "I'll handle this directly" | Direct handling is a critical protocol violation with no exceptions |
| "The task is too simple for a full pipeline" | Simplicity never bypasses delegation -- even single-line fixes use the pipeline |
| "Rather than spinning up agents" | Spinning up agents is the ONLY execution mode for /run |
| "I can do this more efficiently myself" | Efficiency is irrelevant -- delegation is mandatory regardless of speed claims |
| "This doesn't need agent coordination" | Every /run invocation needs agent coordination |
| "I'll build/create/fix/write/implement this myself" | ALL implementation goes to execution agents via Agent tool |
| "Let me just make this change directly" | "Just" is a rationalization word -- Agent tool only |
| "This is a minor edit that doesn't warrant spawning agents" | Size does not determine delegation requirements |
| "I'll do this inline since it's quick" | Speed never overrides the delegation protocol |
| "Rather than going through the full pipeline for this" | The full pipeline runs for every /run invocation without exception |
If you find yourself reasoning toward any of these conclusions, STOP. You are rationalizing a violation. Delegate.
INIT -> ORCHESTRATED -> PLANNED -> DECOMPOSED -> PROMPTS_READY -> COORDINATED -> VALIDATED
FAIL -> PROMPTS_READY
REVISE -> PLANNED
| Phase | Level | Agents | Output |
|---|---|---|---|
| Enrichment | 1 | orchestrator, planner, decomposer, prompt-engineer (optional) | enriched_context.yaml, plan.yaml, work_items.yaml, delegation_prompts.yaml |
| Coordination | 1 + 2 | controller (level 1) -> executor + reviewer (level 2, max 3 rounds) | coordination_log.yaml |
| Validation | 1 | validator | validation_report.yaml (PASS/FAIL/REVISE) |
Pipeline-level revision loop: max 5 cycles total.
See @reference/state-machine-detail.md for full per-state contracts, event file format, revision routing semantics, and the BLOCKED verdict (debug-mode only).
See @reference/delegation-patterns.md for the full delegation chain and Agent tool patterns.
TaskCreate is a BLOCKING PREREQUISITE for every state transition in interactive Claude Code sessions. You CANNOT proceed to the next state until you have called TaskCreate (and TaskUpdate to drive status).
Per docs.claude.com/docs/en/tools.md: TodoWrite is the equivalent fallback in non-interactive mode and the Agent SDK; interactive sessions use TaskCreate, TaskGet, TaskList, TaskUpdate. cAgents primarily runs interactively.
If you skip the task call, the workflow is broken -- the user has zero visibility. Minimum: one TaskCreate per state transition, plus TaskUpdate as status changes.
See @reference/task-tracking-rules.md for the full task tracking protocol, format rules, validation pattern, and revision-task examples.
Parse $ARGUMENTS for flags (--interactive, --dry-run, --quiet, --stream, --skip-preflight, --team, --analytics) and value flags (--template, --domain, --tier, --confidence, --brief, --resume, --session, --from-review, --from-designer, --mode).
The request is everything before the first -- flag.
--mode parser (V10.26.11+): Accepted values are standard (default) and debug. Any other value MUST be rejected: unknown mode: {value}. Supported: standard, debug. Default when unset: standard.
Special flag handling:
--analytics: Read cagents-memory/_system/metrics/pipeline_analytics.yaml, display the dashboard, exit.--resume <session_id>: Load session from progress.md and resume from last checkpoint.--session <session_dir>: Pre-enriched session (from /team). Skip to pre-enrichment detection in Step 3.--brief <path>: Strategic brief from /org. See @reference/strategic-brief-integration.md.--from-review / --from-designer: Skill chaining. See @reference/strategic-brief-integration.md.--mode debug: Enables debug-mode prefix injection for the controller. See @reference/debug-mode-prompt.md.See @reference/flags.md for the complete flag reference with defaults and examples.
/run context show|init|update|clear — historical passthrough subcommands. Removed in V11.0; /run no longer dispatches to a sibling /context skill. The orchestrator still reads cagents-memory/_projects/{project_hash}/product_context.yaml during INIT enrichment, so users edit product_context.yaml directly. See @reference/context-passthrough.md for the full historical contract (preserved for AgentPath FileWatcher backward-compatibility).
ACTION 0: Check process.env.CAGENTS_SESSION_ID. If set, use it verbatim as SESSION_ID. If SESSION_DIR exists, treat as RESUME. Otherwise auto-generate.
ACTION 1: Generate SESSION_ID, mkdir SESSION_DIR with workflow/events/ and outputs/ subdirs, write instruction.yaml, status.yaml, and self-register as root agent in workflow/agent_tree.yaml.
{ISO_TIMESTAMP} MUST be the real current time. NEVER fabricate timestamps like T00:00:00Z. Note: /run uses the pipeline_state field (not phase). See @reference/session-schema.md for the canonical session YAML contract.
See @reference/session-id-format.md for slug rules, NNN counter generation, and required initial files.
See @reference/agent-tracking.md for agent_tree.yaml format and lineage fields.
ACTION 1b: After writing status.yaml, set process.env.CAGENTS_ACTIVE_SESSION = SESSION_ID; so hooks resolve to the correct session without heuristic discovery. Critical for concurrent /org-spawned /team instances.
ACTION 2: Try to read cagents-memory/_system/config/pipeline_config.yaml. If absent, use the hardcoded state machine. Do not error.
ACTION 3: Call TaskCreate (or TodoWrite in SDK). See @reference/task-tracking-rules.md for the initial task list template.
Proceed to Step 3.
This is the core loop -- spawn pipeline agents one state at a time, advance via completion events.
3a. Pre-enrichment detection (for /team teammate flows): If --session was provided, check which enrichment files exist and skip already-completed states. See @reference/state-machine-detail.md.
3b. Route domain and tier inline before spawning the orchestrator. Domain detection uses {domain}/config/domain_overrides.yaml -> router_keywords array. See @reference/domain-coverage.md for the full domain table.
3c. Compute complexity score and select pipeline path (Minimal / Medium / Full). For tier 2 with clear scope, the adaptive pipeline skips orchestrator, decomposer, and prompt-engineer. See @reference/adaptive-pipeline.md for the 9-signal scoring rubric, path-selection thresholds, and tier-2 fast-path skip behavior.
3d. Display domain/tier confirmation:
Detected: Domain={domain} ({super_domain}), Tier={tier}, Controller={controller_name}
(Override with: --domain <domain> --tier <N>)
3e. Execute the state machine loop: For each state, look up the agent in pipeline_config, spawn via Agent tool, read the completion event, update status.yaml AND events/index.yaml, call TaskUpdate, check for revision, advance.
MANDATORY: Update status.yaml after EVERY state transition. The verify-completion.cjs and attention-injection.cjs hooks read pipeline_state from status.yaml. Skipping this update breaks hook-based session detection.
3f. Agent delegation pattern for each state spawn:
Agent({
subagent_type: "cagents:{agent_from_pipeline_config}",
description: "{state}: {brief_description}",
prompt: `You are the {agent_name} in the event-driven pipeline.
REQUEST: {user_request}
SESSION: cagents-memory/sessions/{SESSION_ID}/
DOMAIN: {domain} | TIER: {tier}
CURRENT STATE: {current_state}
INSTRUCTIONS:
1. Read your inputs from session workflow/.
2. Perform your phase work.
3. Write outputs to session workflow/.
4. Write completion event to workflow/events/EVT-{N}.yaml.
5. Update workflow/events/index.yaml with the ordered event list.`
})
For the PROMPTS_READY state (controller), the controller is dynamic -- resolved from plan.yaml controller_assignment.primary. Use the delegation prompt from workflow/delegation_prompts.yaml if available, otherwise fall back to standard controller prompt.
Debug-mode prefix injection (V10.26.13+): If flags.mode === "debug", read .claude/skills/run/reference/debug-mode-prompt.md and PREPEND its prefix text to the controller spawn prompt. See @reference/debug-mode-prompt.md.
3g. Revision handling after the COORDINATED state. Read workflow/validation_report.yaml:
| Verdict | Action |
|---|---|
| PASS | Advance to VALIDATED. Loop exits -- proceed IMMEDIATELY to Step 4. Do NOT stop. |
| FAIL | Route back to PROMPTS_READY. Pass validation feedback to controller. |
| REVISE | Route back to PLANNED. Pass feedback to planner. |
| BLOCKED (debug only) | Route to PROMPTS_READY with falsification annotation. |
Increment revision_round and validation_cycles in status.yaml. Max 5 total revision cycles before HITL escalation.
CRITICAL: DO NOT STOP HERE. When the loop exits at ANY terminal state, Step 4 is MANDATORY. The verify-completion.cjs Stop hook will block stopping if execution_summary.yaml is missing or auto-generated.
See @reference/state-machine-detail.md for the full revision routing protocol and BLOCKED verdict semantics.
This step MUST execute after the state machine loop exits. Not optional, not deferrable, not handled by any hook.
execution_summary.yaml -- MANDATORY even on failure or interruption. Write this BEFORE anything else. The verify-completion.cjs hook creates a stub if you forget, but that triggers a warning visible to the user.session_id: {SESSION_ID}
final_state: VALIDATED # or FAILED, INTERRUPTED
status: completed | failed | interrupted
revision_rounds_used: {N}
states_executed: [INIT, ORCHESTRATED, PLANNED, DECOMPOSED, PROMPTS_READY, COORDINATED, VALIDATED]
states_skipped: [{list}]
total_agents_spawned: {count}
total_duration_ms: {elapsed_ms}
started_at: "{ISO_TIMESTAMP}"
completed_at: "{ISO_TIMESTAMP}"
complete or failed).cagents-memory/_system/metrics/pipeline_analytics.yaml. Recalculate aggregates (success_rate, avg_duration, by_domain, by_tier). Keep the last 500 sessions in the log; archive older entries.TaskList, mark ALL session tasks as completed or deleted via TaskUpdate. Never leave stale in_progress tasks.execution_summary.yaml exists, coordination_log.yaml has self_validation and validation_checkpoints blocks if a controller ran, status.yaml is in a terminal state, and no stale tasks remain.If the pipeline failed after max revisions: report what completed vs what remains, suggest /run --resume {SESSION_ID}, save progress in progress.md.
After reporting results, the pipeline enters a listening state. User follow-ups in the same conversation re-enter execution within the SAME session rather than starting a new one.
Classify the follow-up (adjustment, rework, extension, fix, review) and re-enter the pipeline at the appropriate state. No limit on follow-up rounds.
See @reference/followup-handling.md for the full classification rubric, re-entry procedure, status.yaml/execution_summary.yaml schema additions, and controller follow-up prompt format.
For team mode, after completing routing + planning inline, delegate to /team:
Skill({ skill: "team", args: "{request} --session {SESSION_DIR}" })
The /team skill handles decomposition into work items, team creation, and parallel execution. Each teammate invokes /run --session {SESSION_DIR} which detects pre-enrichment and picks up from the appropriate state.
If --dry-run with --team: Display plan summary and team composition, then STOP.
| /run does directly | /run delegates |
|---|---|
| Parse flags, create session dir, write instruction.yaml + status.yaml | Orchestrator (level 1) -> enriched_context.yaml |
| Load pipeline_config, read strategic_brief.yaml | Universal-planner (level 1) -> plan.yaml |
| Domain detection + tier classification (inline) | Task-decomposer (level 1) -> work_items.yaml |
| Compute duration_ms at each state transition | Prompt-engineer (level 1, optional) -> delegation_prompts.yaml |
| Maintain events/index.yaml | Controller (level 1, dynamic) -> coordination_log.yaml |
| Always write execution_summary.yaml | Universal-validator (level 1) -> validation_report.yaml |
| Call TaskCreate/TaskUpdate at every transition | Execution agents (level 2, via controller): implementation work |
| Spawn pipeline agents via Agent tool | Reviewer (level 2, via controller): acceptance criteria review |
| Read completion events, handle revision routing | |
| Validate final state, report results |
See @reference/delegation-workaround.md for notes on the Task vs Agent tool naming.
If an agent fails or returns incomplete:
--resume {SESSION_ID}If context is exhausted mid-workflow:
/run --resume {SESSION_ID}| Path | Purpose |
|---|---|
cagents-memory/_system/config/pipeline_config.yaml | Pipeline state machine (optional, generated at runtime) |
{domain}/config/planner_config.yaml | Per-domain planner config |
cagents-memory/_system/templates/event.yaml | Event template |
cagents-memory/sessions/run_{slug}_{YYMMDD}_{NNN}/ | Session folder |
cagents-memory/sessions/{session_id}/workflow/agent_tree.yaml | Audit trail |
cagents-memory/_system/logs/agent_spawns.log | Global audit log |
cagents-memory/_system/metrics/pipeline_analytics.yaml | Pipeline analytics |
Event-driven pipeline: Config-driven state machine with sequential enrichment, nested execution with reviewer loops, and revision routing. TaskCreate/TaskUpdate at every state transition.