diff --git a/docs/specs/2026-05-12-boss-skill.md b/docs/specs/2026-05-12-boss-skill.md index e383487..4be18b1 100644 --- a/docs/specs/2026-05-12-boss-skill.md +++ b/docs/specs/2026-05-12-boss-skill.md @@ -23,10 +23,14 @@ into a new user-invoked skill `/boss`. After the change: 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`. +`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 @@ -49,35 +53,70 @@ 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`:** -- "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 +- "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) -- "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). +- 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, not just `/boss` sessions. -- "Milestone cycle" — one short paragraph naming the pipeline - (`brainstorm → plan → implement → audit → fieldtest`); details + 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`" - — these document roles are universal project facts. -- New short paragraph: "Autonomous mode is gated to `/boss`; see - `skills/boss/SKILL.md` for the discipline." + — universal document-role roster. ## Components @@ -96,13 +135,17 @@ stays behind ("see `skills/boss/SKILL.md`"). - **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). + - **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 @@ -120,7 +163,21 @@ stays behind ("see `skills/boss/SKILL.md`"). 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 +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 @@ -206,9 +263,13 @@ No code change, no compiler change, no `bench/` change, no - `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.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