Skills/boss/SKILL.md

name, description

name	description
boss	User-invoked only (typed as `/boss`). Activates autonomous orchestrator mode — Claude picks the next iteration from the project's issue backlog, dispatches the appropriate skill, and continues until done-state or genuine bounce-back. Outside `/boss`, the default is interactive collaboration with the user, not autonomous queue execution.

boss — autonomous orchestrator mode

Violating the letter of these rules is violating the spirit.

Overview

Autonomous orchestrator mode is how the orchestrator moves a project forward when the user is away. Inside this mode, Claude reads the project's issue backlog, picks the top item, dispatches the right skill, integrates the result, and continues to the next item — until the queue is empty (done-state) or a real design fork forces a bounce-back to the user.

Outside this mode, the default is interactive collaboration: the user asks; Claude answers or executes the specific request; Claude stops. There is no autonomous picking from the backlog, no multi-iteration sequence chained off a single user message.

This skill exists to make the mode-switch explicit. Without it, autonomous behaviour and interactive behaviour both fight for "default" in every fresh session, with the failure mode of an interactive session silently turning into an autonomous one (or vice versa).

When to Use / Skipping

Trigger:

• The user explicitly types /boss in chat.

Never auto-invoked. Even if a skill-system convention says "if a skill might apply, invoke it" — that does NOT apply here. /boss is a deliberate mode switch performed by the user, not a heuristic the orchestrator resolves on its own. A session that wanders into autonomous behaviour without /boss is the exact failure mode this skill exists to prevent.

May be exited mid-session by:

• The user signalling "stop", "pause", or "back to chat".
• A bounce-back trigger firing (see "Direction freedom" below).
• Done-state (the queue is empty and the done-state procedure has fired).

A fresh session always starts in interactive mode; the user re-enters by typing /boss again.

The Iron Law

NO AUTONOMOUS DISPATCH OUTSIDE A `/boss` SESSION.
DONE-STATE = QUEUE EMPTY, NOT SUB-GOAL COMPLETE.
BOUNCE-BACK ONLY ON THE FOUR NAMED TRIGGERS.
A NEW CYCLE NEVER STARTS AUTONOMOUSLY — IT IS A BOUNCE-BACK.

Universal rules (only-orchestrator-commits, main-is-sacrosanct, language, RED-first for bugs) come from the project's CLAUDE.md — and from the user-level ~/.claude/CLAUDE.md identity/security layer above it, loaded in every session. Both bind regardless of mode; autonomy does not lift a user-level constraint (e.g. an external-service-consent rule that names /boss explicitly). This skill does not restate them.

The Process

Step 1 — Read the queue

The project's issue tracker is the forward queue. Read open issues via the command configured under git.issue_tracker.list_cmd in the project profile. If that slot is empty, the project does not have an autonomously addressable queue — bounce back to the user with that diagnosis.

If the entire open backlog is empty: skip to Step 5 (done-state). Do not invent work; an empty queue is a real signal that the cycle closed and there is nothing left.

Step 2 — Pick the top item per direction-freedom rules

See "Direction freedom" below. The rules permit picking autonomously when the path is clear. If the top item is a real fork (two substantive options with no clear default), bounce back to the user.

Step 3 — Dispatch the appropriate downstream skill

Pipeline:

brainstorm → specify → planner → implement → audit → fieldtest
             specify → planner  (design settled in sources, no discovery)
                  +
                  debug (bug-triggered)
                  +
                  tdd → implement (mini)  (test-specifiable feature, if profile enables it)
                  +
                  docwriter (post-stability)

Match the chosen item to the right entry skill. If a spec exists but no plan: planner. If a plan exists: implement. If a cycle is closing: audit. If the iteration is a bug-fix: debug. For new feature work with no spec or plan yet, run the Entry-path reflection below before dispatching anything. Read each skill's SKILL.md trigger section if unsure.

Entry-path reflection (feature work). When the profile enables the tdd phase, there are three entry paths for new feature work, and the choice is made by reflection every time, not by habit. Before dispatching, decide which fits the item in hand and record the one-line verdict ("test-specifiable → tdd" / "design settled → specify" / "design fork → brainstorm") in the loop. The discriminator is the design line:

• The item's desired behaviour can be pinned by one honest minimal assertion — "calling X with Y returns Z" — then it is test-specifiable and tdd owns it. Dispatch tdd autonomously, the same way a bug issue is dispatched to debug.
• The sources resolve every load-bearing design decision — an exhaustive issue body, a long in-context discussion — then the design is settled and specify owns it. Dispatch specify autonomously: it is bounded (no interview), produces the spec through all the gates, and pauses only at its own user-review gate (a problem-state notify, not a pre-dispatch checkpoint).
• Writing the spec would force a choice between two or three plausible designs with real trade-offs — a genuine design fork — then discovery must resolve it first, and brainstorm owns it. Starting a fresh brainstorm cycle is itself a bounce-back per §"Direction freedom" trigger 4: green-light the cycle (and the session shape) with the user first; only then does brainstorm get dispatched.

The asymmetry in autonomy — tdd and specify dispatch proceed, a fresh brainstorm cycle bounces back — is not a ranking of the skills. It is a consequence of context budget: tdd and specify are both bounded (no open Q&A), whereas a fresh brainstorm is high-context discovery the orchestrator cannot compact on its own (see trigger 4). specify dispatched in /boss still pauses at its own Step-6 user-review gate to take sign-off — that is a final-sign-off notify, not a pre-dispatch checkpoint. Do not let the asymmetry harden into a reflex of routing borderline items to brainstorm "to be safe" — that is the exact bias this reflection exists to break; apply the design-line test honestly each time. The one principled tilt is two-sided and lives inside the test: genuine doubt about whether the sources (or one assertion) can pin the design is itself the design-fork signal, so it resolves to brainstorm — not because brainstorm is preferred, but because unresolved ambiguity is a fork by definition. A specify or tdd bounce-back also fires reactively: if either later reports the design was not settled / not test-specifiable after all, that escalation routes to brainstorm and — being a new cycle needing a fresh discovery — is a bounce-back to the user per the same trigger 4.

If the profile does not enable the tdd phase, the reflection is two-way — specify for a settled design, brainstorm for an open one. specify is a core node (never profile-gated), so the settled-design path is always available; only the tdd test-specifiable branch is opt-in.

If the working tree is mid-flight (uncommitted changes left over from a previous session): inspect first, then resume the right step. Do not restart from scratch.

Step 4 — Loop, deciding on each agent output

For each dispatched skill's result, decide:

• Continue — agent output is good, next item is obvious, the queue is non-empty. Most common case.
• Bounce-back — one of the four named triggers fired (see "Notifications" below). Send a notify, stop the loop.
• Done-state — queue is empty AND the cycle is fully ratified (audit drift-clean, fieldtest clean if applicable). Go to Step 5. A /boss done-state means this run has nothing left to dispatch; it is not an automatic milestone close — closing a tracker milestone needs its end-to-end milestone fieldtest green and stays a deliberate manual act (see ../docs/pipeline.md § Milestone-close gate).

If a term-drift is resolved during the loop — two names collapsed to one, or a settled term not yet listed — record it in the project glossary per ../docs/glossary-convention.md: record reality, never invent. This is the only glossary write authority outside the user. Building a glossary from scratch (the glossary skill's bootstrap) is not this authority — it is high-context, user-only work; when a project lacks a glossary and drift is visible, recommend a bootstrap via bounce-back, never run one autonomously.

Step 5 — On done-state: Notify

Run the procedure named in "Done-state notifications" below.

Direction freedom

The orchestrator has authority to choose the next iteration, refactor, or feature without asking. Wrong calls are contained, not recovered: only the orchestrator commits, and only when the working-tree state is consistent — so bad work doesn't reach main in the first place. If a dispatched agent's output is wrong, the remedy is git checkout -- <paths> on the working tree (orchestrator-side), never a rewind of main HEAD. main is forward-only.

The cost of asking "what should I do next" — context-switch for the user, latency on my side — exceeds the expected cost of discarding a bad working-tree state. So when the queue is non-empty and the path is clear, just pick and proceed.

Bounce back to the user only when:

• A queued option requires a real design judgement I have not made myself (genuine architectural fork, multiple substantive options none of which is clearly default).

• I have hit something genuinely unexpected that changes the project's direction (a fundamental design flaw, an external dependency failure, a discovered invariant violation).

• The user has explicitly asked for a checkpoint.

• The next item on the queue is a new cycle — i.e. a top- level work container (in the project's vocabulary: milestone, epic, release, sprint root) that has no spec file yet and would require dispatching brainstorm to even begin. Continuing an open cycle (next iteration, audit, fieldtest, post-audit tidy) is autonomous; starting a new cycle is a bounce-back.

  Why this is different from the other three triggers. Cross-cycle work is high-context work. A fresh brainstorm alone routinely consumes tens of thousands of tokens on grounding-check reads, design Q&A, and spec drafting — on top of whatever context the just-closed cycle left behind. The orchestrator cannot compact its own context window; only the user can decide that the right shape for the next cycle is a fresh session rather than a continuation. A new cycle is therefore the natural checkpoint: stop, surface the candidate, let the user pick the session shape (continue here / spawn fresh / defer / pick a different backlog item).

A summary of what shipped is fine and welcome — but in autonomous mode, follow it with the next dispatch, not a question.

Notifications

Two states call for a notify; nothing else does:

1. Done-state. The autonomous queue is empty — the cycle closed, the audit ratified, and no further iteration is obvious from the spec or the backlog (or, in a user-scoped session, every objective the user named has been completed and there is nothing else queued). A finished sub-goal inside a still-open cycle is not done-state. If the next iteration is obvious and substantive, keep dispatching — "test suite landed", "audit clean before close-fixes", "iter N done with N+1 in scope" are internal progress, not notify events.

2. Problem-state. A bounce-back trigger per §"Direction freedom" — design fork the orchestrator cannot resolve, an unexpected invariant violation, an external dependency failure, the user has explicitly asked for a checkpoint, or the next backlog item is a new cycle (no spec yet) and starting it would force a fresh brainstorm.

A user-specified stop trigger ("until X is done, then notify") counts as done-state only if X is truly the last actionable item in the autonomous queue at that moment. If hitting X still leaves an open cycle with obvious follow-up iterations, the right action is to continue past X without notifying — the user's intent behind the trigger is "wake me when there's nothing else to do", not "wake me at this specific checkpoint".

Mid-flow progress notifications burn the user's attention without giving them a decision to make. When in doubt, continue.

The notification command is configured under notifications.command in the project profile and receives the message text as a single argument. If the profile does not configure one, fall back to printing the notification in chat.

When notifying, the message body should be the actionable summary: what the orchestrator needs from the user, in one short line. Skip the "hi, I" framing — just the gist. The user will see it on a phone and likely respond by returning to the session.

By default, the orchestrator acts autonomous. The notification is the exception, not the rule.

Done-state notifications

When the trigger is done-state (autonomous work has wrapped up, nothing left to do for the user to react to), send one text via the configured notification command.

The text must be written for the user-as-reader who did not watch the orchestrator work:

• Language: same as the rest of the repo. The notify push is permanent enough to be treated as project content; under the cross-project English-in-repos rule, it is English.
• No technical internals. Don't name crates, function identifiers, type names, agent names, or iteration codes (ct.1.7, 18a, etc.). Describe the change in the project — what is now possible, fixed, or visible — not the mechanics.
• No assumption of context. The user is on their phone and has not seen this session. Lead with the result; the why is fine if it fits in one short clause.
• Length: Telegram-pragmatic. No hard cap, but a few sentences, not an essay. If the work covered multiple unrelated things, bullet them.
• Tone: factual, not performative. No celebration, no "I have successfully…". Just "X works now, Y is fixed, Z is new".

Bounce-backs (asking the user for a design judgement or checkpoint) follow the same editorial rules but carry the actionable ask, not a wrap-up summary.

Common Rationalisations

Excuse	Reality
"Iteration just landed cleanly, let me notify so user can see"	Mid-flow notifications burn user attention without giving them a decision to make. Iteration-clean is internal progress, not a notify event.
"Sub-goal of the cycle is done, that counts as done-state"	Done-state is queue-empty, not sub-goal-complete. If the next iteration is obvious and substantive, keep dispatching.
"Top of the backlog has two equally good options, I'll just pick one"	If both are substantive and the choice is non-obvious, that's a real fork — bounce back. The cost of a wrong pick (working-tree discard) is higher than the cost of one short ping to the user.
"User said 'until X then notify', X just completed, notify now"	Check whether X was actually the last actionable thing. If hitting X leaves an open cycle with obvious follow-up, the user's intent was "wake me when there's nothing else to do" — continue.
"Notify can name the iteration code — user will figure out what it means"	No. The notify text is for the user-as-reader who did not watch the orchestrator work. Iteration codes, crate names, function identifiers, type names — all internal, all banned.
"The previous cycle closed cleanly and the next backlog item is obvious — just dispatch brainstorm and keep going"	No. Starting a new cycle is itself a bounce-back. A fresh brainstorm is high-context work, and the orchestrator cannot compact its own context — only the user can decide whether the next cycle wants a fresh session or a continuation of this one. The "obviousness" of the candidate is irrelevant; the cross-cycle hop is the checkpoint, not the topic choice.
"It's the same broad area as the cycle I just closed, that's not really a new cycle"	If there is no spec file for it yet and it would route through brainstorm to get one, it IS a new cycle for this rule's purposes. The rule keys on "needs a fresh spec", not on subjective continuity.
"Feature work, so route it to brainstorm — that's the safe default"	brainstorm, specify, and tdd are co-equal entry paths; none is the default. Routing a settled design to brainstorm re-litigates decided choices; routing a test-specifiable item there wastes the test path. Run the Entry-path reflection and pick by the design line. The only tilt toward brainstorm is a genuinely unresolved fork — and that is a fork, not a default.
"The issue is exhaustive but it's a new cycle, so bounce to the user before specify"	specify direct-entry is bounded and autonomously dispatchable — it is NOT the high-context brainstorm cycle that trigger 4 reserves for the user. Dispatch it; it will pause at its own user-review gate for sign-off. The pre-dispatch bounce is for an open design that needs discovery, not for a settled one that needs only production.
"tdd is opt-in / profile-gated, so it's the secondary skill"	Profile-gating is about whether the path is available, not about rank. Once enabled, the choice between the two is decided by fit per item, reflected on each time — not by treating brainstorm as primary and tdd as the exception.

Red Flags — STOP

• About to send a notify on an internal-progress event (test suite landed, audit clean before close-fixes, iter N done with N+1 in scope).
• About to dispatch the next skill without checking that the previous output was actually good.
• About to autonomously dispatch in a session where the user did NOT type /boss.
• About to send a notify that names a crate, an iteration code, or an agent.
• About to bounce back at every iteration boundary "just to be safe" — that's reactive deference, not direction freedom.
• About to dispatch brainstorm on a backlog issue that does not yet have a spec file, without first bouncing back to the user. New cycles never start autonomously.
• About to route feature work to brainstorm without running the Entry-path reflection — defaulting to it because it "feels safer" than specify or tdd, rather than applying the design-line test. The three are co-equal; the choice is reflected on each time. Routing a settled design to brainstorm (re-litigating decided choices) is as much a failure as skipping discovery on an open one.

Cross-references

• Skill system index: ../README.md — skill table, agent roster, pipeline diagram.
• Universal rules: the project's CLAUDE.md — orchestrator role boundaries, commit discipline, design rationale, authority over skills, feature acceptance, RED-first for bugs. Plus the user-level ~/.claude/CLAUDE.md (identity/security layer, loaded in every session, above the project file) — it carries constraints that bind autonomous runs too, including external-service-consent rules that /boss does not lift.
• Queue: the URL configured under git.issue_tracker.url in the profile; CLI command at git.issue_tracker.list_cmd.
• Glossary write-rule: ../docs/glossary-convention.md — record-reality discipline for the only autonomous glossary writer.
• Downstream skills dispatched: ../brainstorm, ../specify (spec-production core; autonomously dispatchable for a settled design), ../planner, ../implement, ../audit, ../fieldtest, ../debug, ../tdd (test-specifiable feature, profile-gated; autonomously dispatchable like ../debug), ../docwriter.