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
|
genuine *bounce-back*, notifies via `WhatsNew.md` + the
|
||||||
notify hook on done-state.
|
notify hook on done-state.
|
||||||
|
|
||||||
`CLAUDE.md` shrinks to project description, universal rules
|
`CLAUDE.md` keeps project description and all universal
|
||||||
(commits, main sanctity, language, file-role roster, TDD-for-
|
orchestrator discipline (agent role boundaries, commit rules,
|
||||||
bugs), and a pointer to `/boss` for the autonomous mode.
|
main sanctity, design discipline, file-role roster, TDD-for-bugs,
|
||||||
Mode-specific discipline lives in `skills/boss/SKILL.md`.
|
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
|
## Architecture
|
||||||
|
|
||||||
@@ -49,35 +53,70 @@ stays behind ("see `skills/boss/SKILL.md`").
|
|||||||
|
|
||||||
### What moves vs. what stays
|
### 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`:**
|
**Moved OUT of `CLAUDE.md` and INTO `skills/boss/SKILL.md`:**
|
||||||
|
|
||||||
- "My role: orchestrator" (delegation defaults, when-not-to-delegate)
|
- "Direction freedom" — autonomously picking the next iter from
|
||||||
- "Authority over `skills/` and the agent roster"
|
`docs/roadmap.md`. Outside `/boss`, the orchestrator does not
|
||||||
- "Design rationale ≠ implementation effort"
|
pick autonomously; it responds to the user's message.
|
||||||
- "Feature acceptance: LLM utility" (kept as pointer in DESIGN.md
|
- "Notifications" — when to bounce back vs. continue silently.
|
||||||
via the existing cross-reference)
|
Outside `/boss` there is no autonomous loop to break out of;
|
||||||
- "Direction freedom" (autonomous picking)
|
the orchestrator always responds to the user, so the
|
||||||
- "Notifications" (done-state vs. bounce-back)
|
bounce-back-vs-continue judgement does not apply.
|
||||||
- "Done-state notifications: WhatsNew.md" procedure
|
- "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):**
|
**Stays in `CLAUDE.md` (universal facts and rules):**
|
||||||
|
|
||||||
- AILang one-paragraph intro ("a language for LLM authors")
|
- AILang one-paragraph intro ("a language for LLM authors").
|
||||||
- Code layout table
|
- Code layout table.
|
||||||
- Skill system pointer (one paragraph)
|
- Skill system pointer (one paragraph), extended with a
|
||||||
- "Commit discipline and main-branch sanctity" — only-Boss-commits
|
one-sentence note that autonomous orchestrator mode is gated to
|
||||||
and main-is-sacrosanct apply in every session regardless of
|
`/boss`; details in `skills/boss/SKILL.md`.
|
||||||
mode. An interactive session can still produce a commit (Boss
|
- "My role: orchestrator" → most of this section stays:
|
||||||
doing a small edit on the user's request).
|
- "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
|
- "Bug fixes — TDD, always" — `debug` skill is mandatory in every
|
||||||
session in which a bug surfaces, not just `/boss` sessions.
|
session in which a bug surfaces.
|
||||||
- "Milestone cycle" — one short paragraph naming the pipeline
|
- "Milestone cycle" — short paragraph naming the pipeline; details
|
||||||
(`brainstorm → plan → implement → audit → fieldtest`); details
|
|
||||||
in `skills/README.md`.
|
in `skills/README.md`.
|
||||||
- "Roles of `docs/DESIGN.md`, `docs/journals/`, ... `docs/WhatsNew.md`"
|
- "Roles of `docs/DESIGN.md`, `docs/journals/`, ... `docs/WhatsNew.md`"
|
||||||
— these document roles are universal project facts.
|
— universal document-role roster.
|
||||||
- New short paragraph: "Autonomous mode is gated to `/boss`; see
|
|
||||||
`skills/boss/SKILL.md` for the discipline."
|
|
||||||
|
|
||||||
## Components
|
## Components
|
||||||
|
|
||||||
@@ -96,13 +135,17 @@ stays behind ("see `skills/boss/SKILL.md`").
|
|||||||
- **The Iron Law** — the discipline below applies *only* in
|
- **The Iron Law** — the discipline below applies *only* in
|
||||||
this mode. Universal rules (commits, main, language, TDD-
|
this mode. Universal rules (commits, main, language, TDD-
|
||||||
for-bugs) come from `CLAUDE.md` and apply regardless.
|
for-bugs) come from `CLAUDE.md` and apply regardless.
|
||||||
- **The Process** — restated sections (delegation defaults,
|
- **The Process** — restates the three mode-specific sections:
|
||||||
when-not-to-delegate, authority over skills, design-rationale-
|
direction freedom (autonomous picking from `docs/roadmap.md`),
|
||||||
≠-effort, feature acceptance, direction freedom, notification
|
notification policy (done-state vs. bounce-back), and the
|
||||||
policy, WhatsNew procedure).
|
WhatsNew.md procedure. References `CLAUDE.md` for the
|
||||||
- **Common Rationalisations** — calibrated to the failure modes
|
universal rules the skill assumes (agent role boundaries,
|
||||||
these rules guard against (premature implementation, reactive
|
commit discipline, design rationale, feature acceptance).
|
||||||
deference, mid-flow notifications, effort-as-rationale).
|
- **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.
|
- **Red Flags — STOP** — the existing stop signals.
|
||||||
- **Cross-references** — back to `skills/README.md` for the
|
- **Cross-references** — back to `skills/README.md` for the
|
||||||
skill table, to `docs/DESIGN.md` for the feature-acceptance
|
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
|
The pipeline diagram gets a short note that `/boss` *wraps* the
|
||||||
pipeline; it is not a step inside it.
|
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.
|
entry recording the refactor and the rationale.
|
||||||
|
|
||||||
## Data flow
|
## 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
|
- `skills/boss/SKILL.md` exists, follows the standard skill
|
||||||
template, and consolidates the moved sections without losing
|
template, and consolidates the moved sections without losing
|
||||||
rules.
|
rules.
|
||||||
- `CLAUDE.md` line count drops materially. The sections listed
|
- `CLAUDE.md` shrinks by ~100 lines (the three mode-specific
|
||||||
under "Components → moved OUT" are gone (or reduced to one-line
|
sections under "Architecture → Moved OUT" are gone, replaced
|
||||||
pointers).
|
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`.
|
- `.claude/skills/boss` symlink resolves to `skills/boss`.
|
||||||
- `skills/README.md` skill table includes a `boss` row.
|
- `skills/README.md` skill table includes a `boss` row.
|
||||||
- The brainstorm-skill Step 7.5 grounding-check on this spec
|
- The brainstorm-skill Step 7.5 grounding-check on this spec
|
||||||
|
|||||||
Reference in New Issue
Block a user