AILang/docs/specs/0016-boss-skill.md

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