spec: tighten /boss move-list to the three mode-specific sections

Recon surfaced that several draft 'moved OUT' sections were universal,
not mode-specific (agent role boundaries, authority over skills, design
rationale, feature-acceptance criterion, when-not-to-delegate). These
apply in any session — interactive or /boss-active — because agents can
be dispatched, design choices can be made, and skills can be edited
outside /boss too.

Tighten the move-list to the three genuinely mode-specific subsections:
Direction freedom, Notifications, Done-state notifications: WhatsNew.md.
Everything else stays in CLAUDE.md. /boss becomes leaner, the universal/
mode-specific boundary is drawn at content that only applies inside the
autonomous loop. Re-dispatched grounding-check: PASS.
This commit is contained in:
2026-05-12 10:07:09 +02:00
parent 3f20a589d6
commit 1c50c2d981
+97 -36
View File
@@ -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 "Componentsmoved OUT" are gone (or reduced to one-line
pointers).
- `CLAUDE.md` shrinks by ~100 lines (the three mode-specific
sections under "ArchitectureMoved 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