# `/boss` Skill — Design Spec **Date:** 2026-05-12 **Status:** Draft — awaiting user spec review **Authors:** Brummel (orchestrator) + Claude ## Goal Extract autonomous-orchestrator-mode discipline from `CLAUDE.md` into a new user-invoked skill `/boss`. After the change: - **Default session (no `/boss`):** Claude is in collaborative-interactive mode. Responds to user messages, answers questions, makes local edits, but does **not** autonomously pull the next item from `docs/roadmap.md` and dispatch a multi-iter sequence. If the user wants something done, the user asks; Claude executes; Claude stops. - **Inside a `/boss` session:** Claude is the autonomous orchestrator described today in `CLAUDE.md`. Picks the next iter from the roadmap, dispatches the appropriate skill (`brainstorm`, `planner`, `implement`, `audit`, `fieldtest`, `debug`, `docwriter`), continues until *done-state* or a genuine *bounce-back*, notifies via `WhatsNew.md` + the notify hook on done-state. `CLAUDE.md` keeps project description and all universal orchestrator discipline (agent role boundaries, commit rules, main sanctity, design discipline, file-role roster, TDD-for-bugs, authority over skills). It loses only the three mode-specific sections — Direction freedom, Notifications, Done-state notifications: WhatsNew.md — which move into `skills/boss/SKILL.md`, plus gains a one-sentence pointer that autonomous mode is gated to `/boss`. ## Architecture A new skill at `skills/boss/SKILL.md`. No agents under `skills/boss/agents/` — `/boss` itself is the orchestrator role; it dispatches the existing skills (and their agents). This is analogous to how `audit` dispatches `ailang-architect` and `ailang-bencher` but is itself an orchestration layer, not a worker. Symlink `.claude/skills/boss -> ../../skills/boss` makes the skill discoverable to the harness's `Skill` tool, matching the convention codified in `skills/README.md`. `CLAUDE.md` is refactored in place: sections that describe *how the orchestrator behaves in autonomous mode* move into `/boss`. Where a moved section was load-bearing for cross-references elsewhere in the project, a one-line pointer stays behind ("see `skills/boss/SKILL.md`"). ### What moves vs. what stays The split is calibrated to one question: *does this content apply only when the orchestrator is autonomously executing the queue, or does it apply in every session regardless of mode?* Universal content (applies in any session — interactive or `/boss`-active) stays in `CLAUDE.md`. Examples: agent role boundaries (an agent dispatched in any session needs to know what the orchestrator does vs. what the agent does), design discipline (applies whenever a design choice is made, including a `brainstorm` invoked outside `/boss`), authority over skills (the orchestrator can edit skills at any time), the universal commit rules. Mode-specific content (applies only inside an active `/boss` loop) moves into the skill. This is a narrower set than the first draft of this spec implied; recon surfaced that several draft "moved OUT" sections are universal, not mode-specific. **Moved OUT of `CLAUDE.md` and INTO `skills/boss/SKILL.md`:** - "Direction freedom" — autonomously picking the next iter from `docs/roadmap.md`. Outside `/boss`, the orchestrator does not pick autonomously; it responds to the user's message. - "Notifications" — when to bounce back vs. continue silently. Outside `/boss` there is no autonomous loop to break out of; the orchestrator always responds to the user, so the bounce-back-vs-continue judgement does not apply. - "Done-state notifications: WhatsNew.md procedure" — fires when the autonomous queue empties. Outside `/boss` there is no autonomous queue. **Stays in `CLAUDE.md` (universal facts and rules):** - AILang one-paragraph intro ("a language for LLM authors"). - Code layout table. - Skill system pointer (one paragraph), extended with a one-sentence note that autonomous orchestrator mode is gated to `/boss`; details in `skills/boss/SKILL.md`. - "My role: orchestrator" → most of this section stays: - "What this means in practice" — agent role boundaries, what Boss does vs. what agents do, when trivial inline edits are fine, verify-the-work. Universal; agents reading their standing reading list rely on this. - "Commit discipline and main-branch sanctity" — only-Boss-commits, main-is-sacrosanct. Universal; an interactive session can still produce a commit. - "Authority over `skills/` and the agent roster" — universal; the orchestrator may edit skills at any time, not only inside `/boss`. - "When NOT to delegate" — universal; the rules for inline-vs- delegate apply whenever an agent might be dispatched. - "Design rationale ≠ implementation effort" — universal design discipline; applies whenever a design choice is made, including `brainstorm` outside `/boss`. - "Feature acceptance: LLM utility" — paraphrase of the canonical criterion at `docs/DESIGN.md` §"Feature-acceptance criterion"; the paraphrase MAY be reduced to a one-line pointer to DESIGN.md to keep CLAUDE.md leaner (Boss judgement at implement time). - "Bug fixes — TDD, always" — `debug` skill is mandatory in every session in which a bug surfaces. - "Milestone cycle" — short paragraph naming the pipeline; details in `skills/README.md`. - "Roles of `docs/DESIGN.md`, `docs/journals/`, ... `docs/WhatsNew.md`" — universal document-role roster. ## Components 1. **`skills/boss/SKILL.md`** — new file. Follows the standard skill template (frontmatter, spirit-letter lead-in, overview, when-to-use, iron law, process, common rationalisations, red flags, cross-references). Body content: - **Frontmatter description** narrowly trigger-bound: "Use only when the user explicitly types `/boss`. Activates autonomous orchestrator mode." - **Overview** — defines autonomous orchestrator mode and why it is gated to user invocation. - **When to Use / Skipping** — only on explicit `/boss`; never auto-invoked on heuristic match. - **The Iron Law** — the discipline below applies *only* in this mode. Universal rules (commits, main, language, TDD- for-bugs) come from `CLAUDE.md` and apply regardless. - **The Process** — restates the three mode-specific sections: direction freedom (autonomous picking from `docs/roadmap.md`), notification policy (done-state vs. bounce-back), and the WhatsNew.md procedure. References `CLAUDE.md` for the universal rules the skill assumes (agent role boundaries, commit discipline, design rationale, feature acceptance). - **Common Rationalisations** — calibrated to autonomous-mode failure modes (mid-flow notifications burning user attention, bouncing back at every iter boundary instead of continuing, treating sub-goal completion as done-state, forgetting the `WhatsNew.md` append on real done-state). - **Red Flags — STOP** — the existing stop signals. - **Cross-references** — back to `skills/README.md` for the skill table, to `docs/DESIGN.md` for the feature-acceptance criterion, to `docs/roadmap.md` for the queue. 2. **`CLAUDE.md`** — heavy edit. Sections listed above as "moved OUT" are removed; replaced where useful by one-line pointers. 3. **`.claude/skills/boss`** — new symlink to `../../skills/boss`. 4. **`skills/README.md`** — skill table gets a new row: | `boss` | User-invoked (`/boss`) only | Autonomous orchestration session | No — user-gated | The pipeline diagram gets a short note that `/boss` *wraps* the pipeline; it is not a step inside it. 5. **Cross-reference repoint.** Two agent/skill files name the moved sections by sub-heading and need repointing to `skills/boss/SKILL.md`: - `skills/implement/SKILL.md` — citation of `CLAUDE.md` "Done-state notifications" subsection. - `skills/implement/agents/ailang-implement-orchestrator.md` — standing reading list entry for "Done-state notifications: WhatsNew.md subsection". Other agent-file references to "orchestrator framing" continue to resolve correctly because that framing stays in `CLAUDE.md`; no further repointing is in scope for this iter. 6. **`docs/journals/2026-05-12-iter-boss.md`** — per-iter journal entry recording the refactor and the rationale. ## Data flow ``` fresh session | v [user message] -------------------------+ | | v v [no /boss] [user types /boss] | | v v interactive mode: /boss skill loads - chat, answer, edit - rules: direction freedom, - ad-hoc dispatch on notify, WhatsNew, delegation explicit user request - read docs/roadmap.md - universal rules - dispatch first item from CLAUDE.md apply - loop until done-state / bounce-back - notify on done-state, append WhatsNew.md - universal rules from CLAUDE.md still apply ``` The boundary is soft. There is no persistent on-disk flag for "boss mode is on". Mode is established by skill load + adherence to its rules, and is exited by: - The user signalling "stop" / "pause" / "back to chat" - A bounce-back trigger firing (design fork, invariant violation, external failure, explicit checkpoint request) - Done-state (queue empty) A fresh session always starts in interactive mode; the user re-enters boss mode by typing `/boss` again. ## Error handling - **Empty roadmap.** `/boss` invoked but `docs/roadmap.md` has no actionable items: notify done-state immediately ("autonomous queue empty; nothing to do"). Do not invent work. - **Iter mid-flight.** `/boss` invoked while a previous session left an iter half-done (e.g. uncommitted working tree, plan written but not implemented): inspect, then resume the right step. Do not restart from scratch. - **Missing skill prerequisite.** `/boss` is about to dispatch `planner` but no spec exists for the milestone: bounce-back to user proposing to invoke `brainstorm`. Do not silently make one up. - **Ambiguous next item.** `/boss` reads the roadmap and finds no clear top item (two items of equal priority, both nontrivial): bounce-back per the direction-freedom rules. - **User signals "stop" mid-`/boss`.** Revert to interactive on the next message; do not auto-resume the loop. ## Testing strategy Skills are documents, not code; the test is operational, applied once the change lands: 1. **Fresh-session spot-check, no `/boss`.** Open a fresh session, ask a small question. Verify Claude does *not* read the roadmap and dispatch an iter — it just answers. 2. **Fresh-session spot-check, `/boss`.** Open a fresh session, type `/boss`. Verify Claude loads the skill, reads `docs/roadmap.md`, picks the top item, and dispatches the right skill — i.e. behaves as it does today in autonomous mode. 3. **CLAUDE.md scan.** Confirm the sections listed under "Components → moved OUT" are no longer in `CLAUDE.md` except as one-line pointers. Confirm universal rules (commits, main, language, file-role roster, TDD-for-bugs) are still present. 4. **Skill table scan.** `skills/README.md` lists `boss` with the trigger "User-invoked (`/boss`) only". No code change, no compiler change, no `bench/` change, no `docs/DESIGN.md` change (the language proper is untouched). ## Acceptance criteria - `skills/boss/SKILL.md` exists, follows the standard skill template, and consolidates the moved sections without losing rules. - `CLAUDE.md` shrinks by ~100 lines (the three mode-specific sections under "Architecture → Moved OUT" are gone, replaced where useful by a one-line pointer to `skills/boss/SKILL.md`). Universal sections (agent role boundaries, commit discipline, authority over skills, design rationale, when-not-to-delegate, feature acceptance paraphrase, TDD-for-bugs, milestone cycle, document-role roster) remain in place. - `.claude/skills/boss` symlink resolves to `skills/boss`. - `skills/README.md` skill table includes a `boss` row. - The brainstorm-skill Step 7.5 grounding-check on this spec returns `PASS` — the spec makes no claims about AILang compiler / checker / codegen / schema behaviour that would need a ratifying test. The skill-system structure (symlinks, `Skill`-tool discovery, agent dispatch) is harness/repo facts, not language-runtime facts, and is outside the grounding-check's remit. - A per-iter journal entry under `docs/journals/2026-05-12-iter-boss.md` records the refactor with rationale.