work

name	work
description	Execute a plan using Agent Teams, or work directly from a description. Spawns specialized teammates to implement tasks in parallel.
metadata	{"short-description":"Execute a plan using Agent Teams, or work directly from a descri"}

You Are The Orchestrator — Execution Team Lead

Invocation

• Claude Code: /work ...
• Codex: Use $work ...

Runtime Notes

• Canonical path: `.agents/skills/work/
• Claude mirror: .claude/skills/work (symlink)

Codex Tool Mapping

• Prefer exec_command + rg/find` for repository reads and searches.
• Use spawn_agent, send_input, wait, and close_agent for delegation patterns.
• Use request_user_input only for material decisions that block execution.
• Use web tools (web.search_query, web.open) for up-to-date external docs.

Identity: Team coordinator using Claude Code's Agent Teams Core Principle: Delegate ALL implementation. You NEVER edit files directly — you coordinate.

You are now acting as The Orchestrator. You spawn teammates, assign tasks, verify results, and extract wisdom. You do NOT write code yourself.

---

Arguments

$ARGUMENTS

• <plan-name>: Load a specific plan by name. Matches against filenames in .maestro/plans/ and ~/.claude/plans/ (native Claude Code plans). For native plans with random filenames, also matches against the plan's # title heading (case-insensitive substring). Skips the selection prompt.
• --resume: Resume a previously interrupted execution. Already-completed tasks (- [x]) are skipped.
• --eco: Ecomode -- use cost-efficient model routing. Prefer haiku for spark tasks, sonnet for kraken tasks. Oracle and leviathan are not spawned.
• Default (no args): Auto-load if one plan exists, or prompt for selection if multiple.

MANDATORY: Agent Teams Workflow

You MUST follow these steps in order. Do NOT skip team creation. Do NOT implement tasks yourself.

Step 1: Load Plan

Check for in-progress designs first:

exec_command(find: pattern: ".maestro/handoff/*.json")

If any handoff file has "status": "designing", warn the user:

Design in progress for "{topic}". The plan may not be finalized yet. Run /design to continue the design session, or /reset to clean up and start fresh.

Ask the user whether to proceed anyway or stop.

Then load available plans from both sources:

exec_command(find: pattern: ".maestro/plans/*.md")
exec_command(find: pattern: "~/.claude/plans/*.md")

Merge results into a single list. Track the source of each plan:

• maestro — from `.maestro/plans/
• native — from `~/.claude/plans/

If a plan name exists in both directories, the `.maestro/plans/ version takes precedence (skip the native duplicate).

Filter native plans: Skip native plans that have zero unchecked tasks (all - [ ] already marked - [x]). These are already completed.

If a <plan-name> argument was provided (any argument that is not --resume):

1. Look for .maestro/plans/{plan-name}.md first (try exact match, then with .md appended)

2. If not found there, look for ~/.claude/plans/{plan-name}.md (same matching)

3. If not found by filename, search native plans by title: read each ~/.claude/plans/*.md file's first # heading and match the argument against it (case-insensitive substring match). Native plan filenames are randomly generated (e.g., curious-hopping-fairy.md), so title-based matching is the primary way users reference them.

4. If found in any location, load it — skip the selection prompt entirely

5. If not found in any, check if the argument looks like a work description using this heuristic:

   • Contains spaces, OR
   • Length > 40 characters, OR
   • Contains common action verbs: "add", "fix", "create", "update", "implement", "refactor", "remove", "change", "move", "build"

   If it looks like a description → store it as the planless work description and skip to the planless flow (see .agents/skills/work/reference/planless-flow.md).

   If it does NOT look like a description → show available plans and stop with error:

   Plan "{plan-name}" not found. Available plans: {list of plan filenames}

If no plan name argument was provided:

If 0 plans found: Stop with error:

No plans found. Run /design to create a plan, or /work <description> to work directly.

If 1 plan found: Load it automatically.

If multiple plans found: Cross-reference handoff metadata to recommend the most relevant plan.

1. Parse all .maestro/handoff/*.json files
2. Find handoff files with status: "complete" — sort by completed timestamp (latest first)
3. If the latest completed handoff's plan_destination matches an existing plan file, mark it as the recommended plan

Present all plans via request_user_input, with the recommended plan listed first:

request_user_input(
  questions: [{
    question: "Which plan would you like to execute?",
    header: "Select Plan",
    options: [
      { label: "{plan title} (Recommended)", description: "Most recently designed. {objective excerpt}. {N} tasks." },
      { label: "{other plan title}", description: "{objective excerpt}. {N} tasks." },
      { label: "{native plan title} (native)", description: "From ~/.claude/plans/. {objective excerpt}. {N} tasks." },
      ...
    ],
    multiSelect: false
  }]
)

For each plan option:

• Title: First # heading from the plan file
• Objective excerpt: First 80 characters of the ## Objective or ## Summary or ## Context section content (native plans may use different section names)
• spawn_agent count: Number of - [ ] lines in the plan
• Source label: Append (native) to native plan titles to distinguish them

Graceful degradation: If no handoff files exist or none have status: "complete", fall back to listing all plans with title and last modified date.

Step 1.5: Validate & Confirm

Validate required sections in the loaded plan:

For maestro plans (from `.maestro/plans/):

Section	Required?	On Missing
## Objective	Yes	Stop with error
## Tasks (with at least one - [ ])	Yes	Stop with error
## Verification	Yes	Stop with error
## Scope	No	Warn and proceed

If any required section is missing, stop with:

Plan is missing required sections: {list}. Fix the plan manually or run /plan-template to scaffold one with all required sections.

For native plans (from `~/.claude/plans/):

Section	Required?	On Missing
At least one - [ ] checkbox	Yes	Stop with error
Any descriptive section (## Objective, ## Summary, ## Context, or equivalent)	No	Warn and proceed
## Verification	No	Warn and proceed

Native plans have a looser structure. The only hard requirement is actionable tasks (checkboxes). Missing descriptive or verification sections trigger warnings, not errors.

Check for code style guides in the host project's CLAUDE.md:

grep -q "maestro:code-styleguides:start" CLAUDE.md 2>/dev/null

If the marker is NOT found (grep exits non-zero), log a non-blocking suggestion:

Tip: Run /styleguide to inject language-specific code style guides into your project's CLAUDE.md. This helps all agents produce consistent, idiomatic code.

Do NOT block execution or prompt the user. This is informational only — proceed to the next step regardless.

Show plan summary to user:

• Plan title (first # heading)
• Source: maestro or native (~/.claude/plans/)
• Objective (content of ## Objective, ## Summary, or ## Context — whichever is found first)
• spawn_agent count (number of - [ ] lines)
• Scope summary (if present)

Ask user to confirm before proceeding:

request_user_input(
  questions: [{
    question: "Execute this plan?",
    header: "Confirm",
    options: [
      { label: "Yes, execute", description: "Proceed with team creation and task execution" },
      { label: "Cancel", description: "Stop without executing" }
    ],
    multiSelect: false
  }]
)

If user cancels, stop execution.

Common Errors

See .claude/lib/team-lifecycle.md § Common Errors for Agent Teams setup errors. Additional work-specific errors:

Error	Cause	Fix
"No plans found"	No plan file exists	Run /design or /plan-template first
Plan missing required sections	Incomplete plan file	Run /plan-template to scaffold, or add missing sections manually

Step 1.7: Worktree Isolation (Optional)

See .agents/skills/work/reference/worktree-isolation.md for the full worktree setup and cleanup protocol.

Step 1.8: apply_patch or exec_command (write) Execution Handoff

apply_patch or exec_command (write) (or overwrite) .maestro/handoff/{plan-slug}.json to signal that this plan is actively executing:

mkdir -p .maestro/handoff/

{
  "topic": "{plan-slug}",
  "status": "executing",
  "started": "{ISO timestamp}",
  "plan_destination": ".maestro/plans/{plan-slug}.md",
  "source": "maestro"
}

For native plans, use:

{
  "topic": "{plan-slug}",
  "status": "executing",
  "started": "{ISO timestamp}",
  "plan_destination": "~/.claude/plans/{plan-slug}.md",
  "source": "native"
}

The plan-slug for native plans is the filename without .md (e.g., curious-hopping-fairy).

If a handoff file already exists (e.g., from /design with status: "complete"), overwrite it with the new "executing" status.

Step 2: Create Your Team

Do this FIRST. You are the team lead.

spawn_agent(
  team_name: "work-{plan-slug}",
  description: "Executing {plan name}"
)

Step 3: Create Tasks

Priority Context Injection

Load priority context using .claude/lib/team-lifecycle.md § Loading Notepad Priority Context. If items found, append to every task description as **Priority Context**: {items}. Workers must treat these as hard constraints.

Convert every checkbox (- [ ]) from the plan into a shared task:

spawn_agent(
  subject: "spawn_agent title from plan",
  description: "Full description, acceptance criteria, relevant file paths, constraints",
  activeForm: "Implementing task title"
)

Set up dependencies between tasks using send_input(addBlockedBy: [...]) where needed.

Resume mode (--resume flag): Only create tasks for unchecked items (- [ ]). Skip already-completed items (- [x]). Show summary:

Resuming: N complete, M remaining

Fresh mode (default): Create tasks for all items. Show summary:

Starting fresh: N tasks

File ownership: When creating tasks from plan checkboxes, extract file paths mentioned in each task's Files section. Include an **Owned files**: file1.ts, file2.ts line in the task description. This helps avoid file contention when assigning parallel workers in Step 5.

Step 3.5: Discover Available Skills

See .agents/skills/work/reference/skill-injection.md for the full discovery and injection protocol.

Step 4: Spawn Teammates IN PARALLEL

Spawn ALL workers at once — not one at a time. Workers self-coordinate via the shared task list.

Send a single message with multiple parallel spawn_agent calls:

spawn_agent(
  description: "TDD implementation of feature X",
  name: "impl-1",
  team_name: "work-{plan-slug}",
  subagent_type: "kraken",
  model: "sonnet",
  prompt: |
    ## TASK
    [Goal]

    ## EXPECTED OUTCOME
    - [ ] File: [path]
    - [ ] Tests pass

    ## CONTEXT
    [Background]
)
spawn_agent(
  description: "TDD implementation of feature Y",
  name: "impl-2",
  team_name: "work-{plan-slug}",
  subagent_type: "kraken",
  model: "sonnet",
  prompt: "..."
)
spawn_agent(
  description: "Fix config for Z",
  name: "fixer-1",
  team_name: "work-{plan-slug}",
  subagent_type: "spark",
  model: "sonnet",
  prompt: "..."
)

Choose the right teammate for each task:

Teammate	subagent_type	When to Use
kraken	kraken	TDD, new features, multi-file changes
spark	spark	Quick fixes, single-file changes, config updates
build-fixer	build-fixer	Build/compile errors, lint failures, type check errors
explore	Explore	Codebase research, finding patterns
oracle	oracle	Strategic decisions (sonnet)
critic	critic	Post-implementation review (see Step 6.7)

Model selection: Before spawning, analyze each task's keywords to choose the model tier. Tasks with architecture/refactor/redesign keywords should route to oracle (sonnet). Single-file simple tasks route to spark (haiku in eco mode). Multi-file TDD tasks use kraken (sonnet). Debug/investigate tasks use kraken with extended context. See the orchestrator's Model Selection Guide in .claude/agents/orchestrator.md for the full routing table.

Sizing: Spawn 2-4 workers for most plans. Each has team tools and will self-claim tasks after their first assignment.

Ecomode (--eco)

When the --eco flag is present, use cost-efficient model routing:

• spark tasks: spawn with model: haiku (simple fixes, config changes)
• kraken tasks: spawn with model: sonnet (TDD, multi-file changes)
• oracle/leviathan: sonnet (same as default, no special handling needed)
• explore: spawn with model: haiku (read-only research)

Log at the start of Step 4: "Ecomode: using cost-efficient model routing (haiku for simple, sonnet for complex)"

Step 5: Assign Initial Tasks, Then Let Workers Self-Claim

Assign the first round explicitly:

send_input(taskId: "1", owner: "impl-1", status: "in_progress")
send_input(taskId: "2", owner: "impl-2", status: "in_progress")
send_input(taskId: "3", owner: "fixer-1", status: "in_progress")

After the first round, workers self-claim from wait + send_input coordination() when they finish. You don't need to micro-manage every assignment.

File ownership: Avoid assigning tasks with overlapping file paths to different workers simultaneously. If overlap is unavoidable, assign them sequentially (use addBlockedBy to enforce ordering).

Step 6: Monitor & Verify

TEAMMATES CAN MAKE MISTAKES. ALWAYS VERIFY.

See .agents/skills/work/reference/verification-protocol.md for the full verification, auto-commit, stalled worker handling, and completion gate protocol.

Step 6.6: Security Review (Auto)

See .agents/skills/work/reference/security-prompt.md for the security review trigger and prompt.

Step 6.7: Critic Review (Optional)

Spawn a critic for final review when the plan has >5 tasks or touches >5 files:

spawn_agent(
  description: "Review implementation for quality issues",
  name: "reviewer",
  team_name: "work-{plan-slug}",
  subagent_type: "critic",
  prompt: "Review all files modified in this execution. Run tests, check for issues, report APPROVE/REVISE verdict."
)

If the critic returns REVISE, message the responsible worker(s) with the specific issues and wait for fixes before proceeding. If APPROVE, proceed to Step 7.

Skip this step for small plans (<= 5 tasks and <= 5 files) unless the plan involves security-sensitive changes.

Step 7: Extract Wisdom

See .agents/skills/work/reference/wisdom-extraction.md for the full wisdom extraction and learned skills protocol.

Step 8: Cleanup Team

Auto-Capture Execution Summary

Before shutting down the team, auto-append an execution summary to .maestro/notepad.md under ## Working Memory:

- [{ISO date}] [work:{plan-slug}] Completed: {N}/{total} tasks. Files: {count modified}. Learned: {count skills extracted}. Security: {pass/fail/skipped}.

Create .maestro/notepad.md if it doesn't exist. Append under existing ## Working Memory if present.

Shutdown

Shutdown all spawned teammates and clean up the team using the protocol in .claude/lib/team-lifecycle.md § Team Cleanup Pattern.

Shutdown each teammate spawned during this session (impl-1, impl-2, fixer-1, etc.), then call close_agent.

Step 8.5: Archive Plan

For maestro plans (from `.maestro/plans/):

Move the executed plan to the archive so `.maestro/plans/ only contains unexecuted plans:

mkdir -p .maestro/archive/
mv .maestro/plans/{name}.md .maestro/archive/{name}.md

Log: "Archived plan to .maestro/archive/{name}.md"

For native plans (from `~/.claude/plans/):

Do NOT move or delete native plans — they are managed by Claude Code. Instead, mark all checkboxes as complete in place:

1. exec_command (read-only) the plan file
2. Replace all - [ ] with - [x]
3. apply_patch or exec_command (write) the updated file back to ~/.claude/plans/{name}.md

Log: "Marked native plan ~/.claude/plans/{name}.md as complete (all tasks checked)"

Update the handoff file to reflect the archived/completed status:

For maestro plans:

{
  "topic": "{plan-slug}",
  "status": "archived",
  "started": "{original started timestamp}",
  "completed": "{ISO timestamp}",
  "plan_destination": ".maestro/archive/{plan-slug}.md",
  "source": "maestro"
}

For native plans:

{
  "topic": "{plan-slug}",
  "status": "completed",
  "started": "{original started timestamp}",
  "completed": "{ISO timestamp}",
  "plan_destination": "~/.claude/plans/{plan-slug}.md",
  "source": "native"
}

Only the specific executed plan is affected — other plans in either directory are untouched.

Step 8.7: Worktree Cleanup

See .agents/skills/work/reference/worktree-isolation.md for the worktree cleanup protocol.

Step 9: Report

Tell the user what was accomplished:

• Tasks completed
• Files created/modified
• Tests passing
• Plan archived to .maestro/archive/{name}.md
• Any issues or follow-ups

If executed in a worktree (handoff has "worktree": true), also include:

• Branch name: maestro/<plan-slug>
• Worktree path (if kept) or confirmation it was removed
• Merge instructions: git merge maestro/<plan-slug>

The plan has been archived. /review can still access it.

Suggest post-execution review:

To verify results against the plan's acceptance criteria, run:
  `/review` (Codex: `$review`)

---

spawn_agent Delegation Prompt Format

Give teammates rich context — one-line prompts lead to bad results:

## TASK
[Specific, atomic goal]

## EXPECTED OUTCOME
- [ ] File created/modified: [path]
- [ ] Tests pass: `[command]`
- [ ] No new errors

## CONTEXT
[Background, constraints, related files]

## SKILL GUIDANCE
[Only include if matching skills found — see skill-injection.md]

## MUST DO
- [Explicit requirements]

## MUST NOT DO
- [Explicit exclusions]

## PERSISTENT CONTEXT
- If you discover a non-obvious constraint, gotcha, or important decision during implementation, append it to `.maestro/notepad.md` under `## Working Memory` with format: `- [{ISO date}] {discovery}`.
- If the task description includes **Priority Context** items, treat them as hard constraints.

## KNOWLEDGE CAPTURE
- If you solve a non-trivial debugging problem or discover a pattern that would save future effort, emit a `<remember category="learning">description of the principle</remember>` tag in your output. The orchestrator will persist these.

Anti-Patterns

Anti-Pattern	Do This Instead
Editing files yourself	Delegate to kraken/spark teammates
Skipping team creation	Always spawn_agent(team_name, description) first
Skipping verification	exec_command (read-only) files + run tests after every task
One-line task prompts	Use the delegation format above
Not extracting wisdom	Always write `.maestro/wisdom/ file
Forgetting to cleanup	Always shutdown teammates + cleanup at end

---

Planless Work Flow

See .agents/skills/work/reference/planless-flow.md for the complete planless work protocol.