|
|
|
@@ -0,0 +1,287 @@
|
|
|
|
|
---
|
|
|
|
|
name: boss
|
|
|
|
|
description: 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 apply regardless of mode. 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 → planner → implement → audit → fieldtest
|
|
|
|
|
+
|
|
|
|
|
debug (bug-triggered)
|
|
|
|
|
+
|
|
|
|
|
docwriter (post-stability)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Match the chosen item to the right entry skill. If a cycle is
|
|
|
|
|
new and no spec exists: **bounce back first** (per §"Direction
|
|
|
|
|
freedom" trigger 4 — new cycles never start autonomously); only
|
|
|
|
|
after the user green-lights the cycle (and the session shape)
|
|
|
|
|
does `brainstorm` get dispatched. 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`. 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 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 clean, fieldtest clean if applicable). Go to
|
|
|
|
|
Step 5.
|
|
|
|
|
|
|
|
|
|
### 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. |
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
|
|
|
|
|
## 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.
|
|
|
|
|
- **Queue:** the URL configured under `git.issue_tracker.url` in
|
|
|
|
|
the profile; CLI command at `git.issue_tracker.list_cmd`.
|
|
|
|
|
- **Downstream skills dispatched:** `../brainstorm`,
|
|
|
|
|
`../planner`, `../implement`, `../audit`, `../fieldtest`,
|
|
|
|
|
`../debug`, `../docwriter`.
|
