spec: /boss skill — extract autonomous-mode discipline from CLAUDE.md

2026-05-12 10:01:12 +02:00
parent d1e514f2e7
commit 3f20a589d6
1 changed files with 222 additions and 0 deletions
@@ -0,0 +1,222 @@
+# `/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` shrinks to project description, universal rules
+(commits, main sanctity, language, file-role roster, TDD-for-
+bugs), and a pointer to `/boss` for the autonomous mode.
+Mode-specific discipline lives in `skills/boss/SKILL.md`.
+
+## 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
+
+**Moved OUT of `CLAUDE.md` and INTO `skills/boss/SKILL.md`:**
+
+- "My role: orchestrator" (delegation defaults, when-not-to-delegate)
+- "Authority over `skills/` and the agent roster"
+- "Design rationale ≠ implementation effort"
+- "Feature acceptance: LLM utility" (kept as pointer in DESIGN.md
+  via the existing cross-reference)
+- "Direction freedom" (autonomous picking)
+- "Notifications" (done-state vs. bounce-back)
+- "Done-state notifications: WhatsNew.md" procedure
+
+**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)
+- "Commit discipline and main-branch sanctity" — only-Boss-commits
+  and main-is-sacrosanct apply in every session regardless of
+  mode. An interactive session can still produce a commit (Boss
+  doing a small edit on the user's request).
+- "Bug fixes — TDD, always" — `debug` skill is mandatory in every
+  session in which a bug surfaces, not just `/boss` sessions.
+- "Milestone cycle" — one short paragraph naming the pipeline
+  (`brainstorm → plan → implement → audit → fieldtest`); details
+  in `skills/README.md`.
+- "Roles of `docs/DESIGN.md`, `docs/journals/`, ... `docs/WhatsNew.md`"
+  — these document roles are universal project facts.
+- New short paragraph: "Autonomous mode is gated to `/boss`; see
+  `skills/boss/SKILL.md` for the discipline."
+
+## 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** — restated sections (delegation defaults,
+     when-not-to-delegate, authority over skills, design-rationale-
+     ≠-effort, feature acceptance, direction freedom, notification
+     policy, WhatsNew procedure).
+   - **Common Rationalisations** — calibrated to the failure modes
+     these rules guard against (premature implementation, reactive
+     deference, mid-flow notifications, effort-as-rationale).
+   - **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. **`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` line count drops materially. The sections listed
+  under "Components → moved OUT" are gone (or reduced to one-line
+  pointers).
+- `.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.