# `/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.
