boss-advanced

Boss Advanced Orchestration Patterns

Capability Lanes

Boss discovers capabilities at runtime. This is the ownership map for resolving overlaps between what it finds — one owner per lane, no cross-lane duplicates.

| Lane | Owner | Contents | |------|-------|----------| | Core orchestration | this repo (skills/core/) | boss-advanced, boss-briefing, briefing-vault, gstack-sprint (4) | | Execution modes | OMC | autopilot, ralph, ultrawork, ultraqa, team, ralplan, cancel, ccg, ask, deep-interview, ai-slop-cleaner, hud, omc-reference, omc-setup, omc-doctor, setup (16) | | Dev discipline | superpowers | test-driven-development, systematic-debugging, brainstorming, writing-plans, executing-plans, requesting/receiving-code-review, verification-before-completion, using-git-worktrees, subagent-driven-development, writing-skills, using-superpowers, finishing-a-development-branch (13) | | P0 workflows | gstack | 26 skills + the gstack root router (27) — see the Priority 0 table in boss.md | | Stack + AI knowledge | ECC | 79 skills — language/framework patterns, agent and LLM engineering, codebase tooling | | Document deliverables | Anthropic doc skills | pdf, docx, pptx, xlsx | | Agents | this repo + OMC | 32 total: boss (core) + omo 9 + omc 19 + vendored AI-lane 3 |

A name outside these lanes is not installed. Never route to a capability Phase 0 did not discover.

Skill vs Agent Conflict Resolution

When both a skill and an agent could handle the request, evaluate three dimensions:

| Dimension | -> Skill | -> Agent | |-----------|---------|---------| | Scope | Narrow (single file/function/document) | Wide (multi-file, project-wide, cross-module) | | Depth (weighted 2x) | Shallow (template, format, generate, lookup) | Deep (analyze patterns, trace dependencies, investigate, reason about code) | | Interactivity | One-shot (produce output, done) | Iterative (explore -> decide -> act -> verify) |

Scoring: Depth counts double. Tally: Skill-points vs Agent-points (max 4). Higher score wins.

• Scope->Skill = 1pt, Depth->Skill = 2pt, Interactivity->Skill = 1pt -> Skill total
• Scope->Agent = 1pt, Depth->Agent = 2pt, Interactivity->Agent = 1pt -> Agent total
• Tie -> ask the user one clarifying question

Special cases:

• File-format deliverable (the output IS a pdf/docx/xlsx/pptx) -> Skill always wins, regardless of dimensions
• Visual design deliverable (landing page, component, UI) where the primary output is rendered HTML/CSS -> Skill wins (one-shot generation); design consultation (evaluate existing design, propose improvements iteratively) -> Agent wins (iterative exploration)
• Single-file security review -> If scope is exactly 1 file, prefer gstack /cso Skill (checklist-based review is more thorough for single files); if multi-file -> gstack /cso also preferred
• Security audit cadence -> gstack /cso is the representative Skill for periodic/scheduled security audits (threat modeling, broader review); security-scan is the representative Skill for pre-commit/pre-push diff-scoped scans (fast, blocking gate). Do not conflate the two roles.
• Methodology + implementation (e.g. "implement this feature using TDD") -> Skill inside Agent — skill provides methodology, agent executes
• Chained routing — when a task requires two distinct steps handled by different capabilities (e.g. "read this PDF and do a security analysis"), Boss orchestrates as P3a: step 1 (Skill or Agent) -> step 2 (Skill or Agent), each matched independently
• Ambiguous scope -> ask the user one clarifying question rather than guessing
• No candidate exists -> skip to next Priority level, never force-match a nonexistent skill/agent
• gstack priority: When gstack skills are in the Registry, always prefer gstack in overlapping areas. Also propose gstack skills first in counter-proposals. gstack takes priority regardless of whether the browse binary is present (if the binary is absent, the skill handles graceful fallback internally).
• gstack 3-Phase Sprint: For end-to-end tasks, invoke Skill(skill: "gstack-sprint"). The gstack-sprint skill manages the full Phase 1 (design/conversation) → Phase 2 (execution/autonomous) → Phase 3 (review/conversation) lifecycle. Falls back to the prompt instructions in boss.md when gstack-sprint is not installed.

Multi-Agent Decision Flowchart

When a task requires multiple agents, use this 2-step decision tree:

Q1. Are the subtasks fully independent? (no file overlap)
    |
    +- YES -> Priority 3a (Boss direct parallel) or 3b (delegate to sisyphus)
    |
    +- NO (shared files, common types/utilities, etc.)
        |
        Q2. Is inter-agent communication needed? (feedback, review, cross-referencing)
            |
            +- YES -> Priority 3c-DIRECT (Agent Teams, peer-to-peer SendMessage)
            |
            +- NO  -> Priority 3b (delegate to one sisyphus, handled sequentially internally)

Priority 3a: Boss Direct Orchestration (Mid-sized tasks)

When 2-4 agents are needed and dependencies are simple:

• Boss spawns agents directly (parallel where independent, sequential where dependent)
• No sub-orchestrator overhead
• Boss verifies each result directly

Criteria: task can be decomposed into <=4 clear steps, each mappable to a single agent.

Example: "refactor and code review" -> Agent(name="executor", description="executor refactoring", model="sonnet") then Agent(name="code-reviewer", description="code-reviewer review", model="opus")

Worktree Isolation for Parallel File-Modifying Delegations

When 2+ agents run in parallel (run_in_background=true) and may touch the same repo's files, pass isolation: "worktree" on each Agent() call — each agent works in an isolated git worktree, avoiding overwrite races. Skip isolation for read-only agents (Explore, code-reviewer) or agents scoped to separate repos/directories.

Merge procedure: after each agent completes, review its worktree diff, then merge (cherry-pick, rebase, or manual patch apply) into the main working tree before the next dependent step.

Priority 3b: Sub-Orchestrator Delegation (Complex workflows)

When 5+ agents needed OR complex dependency chains OR iterative planning required:

• Multi-agent workflow needing a plan -> delegate to sisyphus
• Execution of an existing plan -> delegate to atlas
• Autonomous "just do it" task -> delegate to hephaestus

Priority 3c: Agent Teams (Inter-agent communication required)

When teammates need to communicate directly with each other, share intermediate results, or coordinate on overlapping files across long-running work:

• Invoke the team skill: Skill(skill: "team") or with args for specific configuration
• The team skill handles all orchestration: TeamCreate, teammate spawning, shared task list, SendMessage, shutdown, cleanup
• Boss acts as the team leader automatically (via "agent": "boss" in settings.json)

Decision: Agent Teams vs Subagents

| Signal | -> Agent Teams | -> Subagents | |--------|--------------|-------------| | Inter-agent communication | Needed (share intermediate results, peer review) | Not needed (report only to Boss) | | Task persistence | Long-running (teammates do multiple tasks) | Short (complete and terminate) | | File overlap | Teammates may edit overlapping files | Completely separate files | | Cost tolerance | Higher (each teammate = separate Claude instance) | Lower (results summarized back) | | Task count | 5-20 parallel tasks | 1-4 focused tasks |

When NOT to use teams:

• Trivial tasks (< 5 min)
• Single-agent tasks (no coordination needed)
• Read-only analysis (subagents are cheaper)
• When CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS env var is not set -> fall back to Priority 3b

Advanced Team Controls (from official docs):

• Plan approval: Require teammates to plan before implementing:

`"Spawn an architect teammate. Re