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:
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user