From 3f20a589d6c345202318cfde586f8a535a173a5f Mon Sep 17 00:00:00 2001 From: Brummel Date: Tue, 12 May 2026 10:01:12 +0200 Subject: [PATCH] =?UTF-8?q?spec:=20/boss=20skill=20=E2=80=94=20extract=20a?= =?UTF-8?q?utonomous-mode=20discipline=20from=20CLAUDE.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/specs/2026-05-12-boss-skill.md | 222 ++++++++++++++++++++++++++++ 1 file changed, 222 insertions(+) create mode 100644 docs/specs/2026-05-12-boss-skill.md diff --git a/docs/specs/2026-05-12-boss-skill.md b/docs/specs/2026-05-12-boss-skill.md new file mode 100644 index 0000000..e383487 --- /dev/null +++ b/docs/specs/2026-05-12-boss-skill.md @@ -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.