AILang/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 `docs/roadmap.md`, 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 the way Brummel-as-LLM moves the AILang project forward when the user is away. Inside this mode, Claude reads docs/roadmap.md, 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 roadmap, no multi-iter 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

Triggers:

• The user explicitly types /boss in chat.

Never auto-invoked. The using-superpowers rule that the harness applies — "if a skill might apply, invoke it" — does NOT apply to this skill. /boss is a deliberate mode switch performed by the user, not a heuristic that Claude resolves on its own. A session that wanders into autonomous behaviour without /boss is a 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 MILESTONE NEVER STARTS AUTONOMOUSLY — IT IS A BOUNCE-BACK.
WHATSNEW.MD + NOTIFY ARE ONE TEXT, NOT TWO.

Universal rules (only-Boss-commits, main-is-sacrosanct, language, TDD-for-bugs) come from CLAUDE.md and apply regardless of mode. This skill does not restate them.

The Process

Step 1 — Read the queue

docs/roadmap.md is the priority-ordered forward queue. Read it first. The top item is the candidate for the next dispatch.

If the queue is empty: skip to Step 5 (done-state). Do not invent work; an empty queue is a real signal that the milestone 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 (from skills/README.md):

brainstorm → planner → implement → audit → fieldtest
                  +
                  debug (bug-triggered)
                  +
                  docwriter (post-stability)

Match the chosen item to the right entry skill. If a milestone is new and no spec exists: bounce back first (per §"Direction freedom" trigger 4 — new milestones never start autonomously); only after the user green-lights the milestone (and the session shape) does brainstorm get dispatched. If a spec exists but no plan: planner. If a plan exists: implement. If a milestone is closing: audit. If the iter is a bugfix: debug. Read each skill's SKILL.md trigger section if unsure.

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 three named triggers fired (see "Notifications" below). Send a notify, stop the loop.
• Done-state — queue is empty AND the milestone is fully ratified (audit clean, fieldtest clean if applicable). Go to Step 5.

Step 5 — On done-state: WhatsNew.md + Notify

Run the procedure named in "Done-state notifications: WhatsNew.md" below. The two outputs share one verbatim text.

Direction freedom

I have authority to choose the next iteration, refactor, or feature without asking. Wrong calls are contained, not recovered: only the Boss 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 (Boss-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 milestone — i.e. a roadmap entry that has no docs/specs/ file yet and would require dispatching brainstorm to even begin. Continuing an open milestone (next iter, audit, fieldtest, post-audit tidy) is autonomous; starting a new one is a bounce-back.

  Why this is different from the other three triggers. Cross- milestone 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 milestone left behind. I cannot compact my own context window; only the user can decide that the right shape for the next milestone is a fresh session rather than a continuation. A new milestone is therefore the natural checkpoint: stop, surface the candidate, let the user pick the session shape (continue here / spawn fresh / defer / pick a different roadmap 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 milestone closed, the audit ratified, and no further iteration is obvious from the spec or the roadmap (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 milestone 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 I cannot resolve, an unexpected invariant violation, an external dependency failure, the user has explicitly asked for a checkpoint, or the next roadmap item is a new milestone (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 milestone with obvious follow-up iters, 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 him a decision to make. When in doubt, continue.

~/.claude/notify.sh "Text"

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

By default, I act autonomous. The notification is the exception, not the rule.

Done-state notifications: WhatsNew.md

When the trigger is done-state (autonomous work has wrapped up, nothing left to do for the user to react to), the procedure is two-step and the two outputs share one text:

1. Append a new entry to docs/WhatsNew.md (newest at the bottom, append-only — same chronological convention as the per-iter journals).
2. Send the same text via ~/.claude/notify.sh.

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

• Language: English. Same as the rest of the repo; both WhatsNew.md and the Notify push are permanent enough to be treated as project content.
• 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 his 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) are not done-state and do not produce a WhatsNew entry — they stay as Notify-only.

Format of a WhatsNew entry: a ## YYYY-MM-DD — <short title> heading followed by the message body. The body must match the Notify text verbatim.

Common Rationalisations

Excuse	Reality
"Iter just landed cleanly, let me notify so user can see"	Mid-flow notifications burn user attention without giving them a decision to make. Iter-clean is internal progress, not a notify event.
"Sub-goal of the milestone is done, that counts as done-state"	Done-state is queue-empty, not sub-goal-complete. If the next iter is obvious and substantive, keep dispatching.
"Top of roadmap 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 milestone with obvious follow-up, the user's intent was "wake me when there's nothing else to do" — continue.
"Done-state hit, send notify, append WhatsNew later"	WhatsNew + notify are one text. Append first (atomic), send second. Splitting them is how the WhatsNew gets forgotten.
"WhatsNew can name the iter code — user will figure out what it means"	No. WhatsNew is for the user-as-reader who did not watch me work. Iter codes, crate names, function identifiers, type names — all internal, all banned.
"The previous milestone closed cleanly and the next roadmap item is obvious — just dispatch brainstorm and keep going"	No. Starting a new milestone is itself a bounce-back. A fresh brainstorm is high-context work, and I cannot compact my own context — only the user can decide whether the next milestone wants a fresh session or a continuation of this one. The "obviousness" of the candidate is irrelevant; the cross-milestone hop is the checkpoint, not the topic choice.
"It's the same broad area as the milestone I just closed, that's not really a new milestone"	If there is no docs/specs/<...>.md file for it yet and it would route through brainstorm to get one, it IS a new milestone for this rule's purposes. The rule keys on "needs a fresh spec", not on subjective continuity.

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 write a WhatsNew entry that names a crate, an iter code, or an agent.
• About to bounce back at every iter boundary "just to be safe" — that's reactive deference, not direction freedom.
• About to send the WhatsNew text and the Notify text with different wording — they must be one verbatim text.
• About to dispatch brainstorm on a roadmap item that does not yet have a spec file, without first bouncing back to the user. New milestones never start autonomously.

Cross-references

• Skill system index: skills/README.md — skill table, agent roster, pipeline diagram.
• Universal rules: CLAUDE.md — agent role boundaries, commit discipline, design rationale, authority over skills, feature acceptance, TDD-for-bugs, file-role roster.
• Queue: docs/roadmap.md — priority-ordered forward queue consumed by Step 1.
• Canonical feature-acceptance criterion: design/contracts/feature-acceptance.md — the criterion that gates new features; applied at spec time by skills/brainstorm.
• Downstream skills dispatched: skills/brainstorm, skills/planner, skills/implement, skills/audit, skills/fieldtest, skills/debug, skills/docwriter.