Brummel
832375f2ac
All 176 files in the four accumulating directories now use a zero-padded 4-digit counter prefix that reflects creation order (`NNNN-slug.md`). The counter is assigned per directory in strict git-log creation order; ties broken alphabetically by original name. The old `YYYY-MM-DD-` prefix on docs/specs/ and docs/plans/ files is dropped — the date is recoverable from git log and the counter carries the ordering. A file's counter is stable for the life of the file: never reassigned, never reused, never compacted. Deleted files retire their counter; subsequent files do not fill the gap. This is the property that lets cross-references stay literal — refs use the full filename including the counter (`design/contracts/0007-honesty-rule.md`) so they grep cleanly and resolve directly without a glob step. 313 cross-references updated across .md/.rs/.toml/.c/.json files (test pins, include_str! paths, design-INDEX entries, baseline notes, runtime C comments, inter-contract markdown links incl. bare basename and `../models/foo.md` forms). CLAUDE.md gets a new "File-naming convention" section spelling out the rule and rationale. skills/brainstorm/SKILL.md and skills/planner/SKILL.md updated so new spec/plan creation produces counter-prefixed names from the start. The full test suite (cargo test --workspace) passes.
284 lines
13 KiB
Markdown
284 lines
13 KiB
Markdown
# `/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` 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
|
|
|
|
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
|
|
|
|
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`:**
|
|
|
|
- "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), 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.
|
|
- "Milestone cycle" — short paragraph naming the pipeline; details
|
|
in `skills/README.md`.
|
|
- "Roles of `docs/DESIGN.md`, `docs/journals/`, ... `docs/WhatsNew.md`"
|
|
— universal document-role roster.
|
|
|
|
## 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** — 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
|
|
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. **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
|
|
|
|
```
|
|
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` 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
|
|
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.
|