Forbid the footnote/legend pattern: explanations for a marked
line must live inline at that line (rule 2), never in a
post-block `[1] = …, [2] = …` key that forces the reader to
bounce between code and a legend below it. A marker is purely a
label so the user can point ('expand [2]'); a line that reads
for itself carries a bare marker and no comment.
Rework rule 4 accordingly, add the Iron Law line, guard rule 1's
supporting-prose clause against becoming a legend, and rewrite
the worked example's trailing commentary to demonstrate inline
explanation with no marker key. Frontmatter and README updated.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add rule 2: comment only what the code cannot say itself;
self-explanatory pseudocode needs none. Put any comment on its
own line above the code; reserve trailing end-of-line comments
for the briefest notes (a bare marker, one or two words), since a
column of trailing prose scans worse than a short note above.
Rework rule 4 (markers) so the bare marker rides trailing while
any explanation it needs moves to an own line. Renumber the rule
list (now 1-10) and fix the mechanics->reduce cross-reference.
Iron Law, worked example, frontmatter, and README updated to
match; the example now demonstrates the sparse-comment style.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Remove the hard one-screen length limit entirely; replace the
former cap (rule 9) with a single-altitude guidance that leans
on the reference markers to let the user steer the zoom instead
of a fixed length.
Loosen the prose ban: prose is now allowed, but only in a
supporting role — the pseudocode block stays the centre of every
answer and prose explains what the code cannot show on its own.
Iron Law, overview, rule 1, worked example, frontmatter, and
README updated to match.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add rule 7: alongside the control flow, sketch the layout of the
data structures the code in focus reads or builds — record
fields, collection nesting, variant cases relevant to the
question — placed beside the code that touches them and reduced
in the same spirit (only the fields on the topic path). When the
data layout is the question, it leads and the flow becomes the
stub. Iron Law, worked example, frontmatter, and README updated
to match.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A user-invoked conversational skill: while active, every reply
explains code in commented, human-readable pseudocode instead of
prose. Each answer opens with a source-file-and-approximate-line
anchor, tags notable steps with reference markers ([1], [A]) the
user can point back at, reduces off-topic paths to stubs, omits
low-level mechanics unless asked, defaults to the project main
entry, and never runs longer than one screen.
Dispatches no agents and runs no pipeline; documented in the
README as a conversational skill standing outside the pipeline.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A new opt-in alternative to the brainstorm -> planner design entry,
for work whose desired behaviour is test-specifiable. Instead of a
prose spec the user approves, `tdd` produces one minimal RED
executable-spec ("how it should work") and treats it like a bug to
be fixed: the GREEN side hands off to `implement` mini-mode, the
same two-stage RED-first handoff `debug` uses.
Skill + agent split mirrors debug/debugger: a thin SKILL.md owns
trigger, dispatch, the orchestrator-side loop, and handoff; the
agent (tdd-author) carries the authoring discipline. The agent
guards two failure modes specifically — guessing a design into a
test (a genuine design fork bounces back to `brainstorm` rather
than ratifying an un-chosen design), and pushing harder on a
headline test that won't go green (one iteration that can't reach
GREEN triggers a reactive decompose into a ladder of BLOCKER
sub-tests; two failed rounds bounce to `brainstorm`).
The boundary is the design line: `tdd` owns the work iff one honest
minimal assertion pins it; otherwise `brainstorm` reclaims it. This
is distinct from the per-task TDD the implementer already practices
inside `implement` — `tdd` authors the one headline spec above it.
Wires the phase into the docs it references:
- docs/profile-schema.md: opt-in `tdd` pipeline slot
- README.md: skill table row
- docs/pipeline.md: entry-path in the graph, phase description, skip rule
- templates/project-profile.yml: commented-out slot
install.sh picks up tdd/ automatically (top-level dir with SKILL.md).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Gives the plugin an executable procedure over a project's glossary,
closing the two gaps the glossary-convention infrastructure left open:
no on-ramp to build a glossary for an existing project, and no
conformance check around hand-maintenance.
New `glossary` utility skill (invoked on demand like `issue`, not a
pipeline phase) with a mode dispatch:
- maintain: guided add / change / remove of one entry under a local
conformance check (three-field shape, <=2-sentence definition,
collision scan against existing entries) plus a stale-usage sweep on
change/rename. A non-conforming entry is rejected with the named rule,
not written. The sweep reports drift; it does not block (guidance, not
enforcement).
- bootstrap (user-only): fans out one read-only glossary-extractor agent
per prose slice, merges and clusters their observed variants, auto-
includes clear winners, surfaces contested clusters to the user for the
canonical choice, and leaves unresolved clusters out (never coined).
New `glossary-extractor` agent (read-only, template-conforming): sweeps
one prose slice, reports recurring concept terms + competing variants
with frequencies and locations, coins nothing.
Single-sourcing held throughout: the skill applies the rules in
docs/glossary-convention.md and restates none of them. Authority is
unchanged — maintain keeps the user-any-time / boss-record-reality rule;
bootstrap is user-only, with boss allowed to recommend it via bounce-back
(one wired sentence in boss/SKILL.md). docs/glossary-convention.md gains
a one-line tooling pointer to the skill; README.md lists `glossary` and
`issue` as utility skills and drops the stale 'Eight skills' count the
fresh-context grounding-check flagged (it had silently omitted `issue`).
install.sh links the new skill + agent with no installer change (its glob
covers any top-level dir with a SKILL.md + agents/ subdir; verified).
Docs/prose-only repo, no test runner: all 13 grep presence-gates green
against verified zero baselines; final sweep ALL_PRESENT, install.sh
still parses (bash -n). Implements
docs/specs/2026-05-31-glossary-skill-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The nested-subagent-dispatch constraint is unchanged in Opus 4.8.
Workflows added a top-level fan-out mechanism alongside it, but a
workflow's spawned agents still cannot spawn further agents. Record
this in both the design rationale and the README capability list so a
future reader does not read the plugin as unaware of Workflows.
Documents that profile slots are versioned with the plugin, not the
project: optional slots degrade to documented no-ops when absent, so
an out-of-date profile silently skips the gates a new slot powers.
Tells maintainers to skim the template's commented blocks and the
schema after a plugin update, and gives a concrete retrofit recipe
for `spec_validation` (the slot the compound-hallucination hardening
added) and the three gates it powers.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
~/dev/skills/skills/boss/ was visually awkward (skills/skills
read twice) and structurally unnecessary — the skills ARE the
repo's main content, not a sub-collection inside it.
Layout changes:
- boss/SKILL.md moves to the repo root
- skills/README.md (migration notes) moves to docs/migration.md
where documentation-about-the-system belongs
- install.sh discovers skills via the SKILL.md marker file
instead of a hardcoded skills/<name>/ path, so future skill
additions just drop in at the root
Cross-references in boss/SKILL.md (../README.md, ../brainstorm,
etc.) now resolve against the repo root instead of the old
skills/ subdir, which is what they describe: top-level
README is the skill table; sibling skill dirs are the other
migrated skills.
First skill migrated from AILang's in-tree skills/. boss carries
the autonomous orchestrator authority (god-mode: dispatches every
other skill, decides done-state vs bounce-back), so it is the
load-bearing pilot for the migration pattern.
Profile schema gains three slots that boss needs:
- `git.issue_tracker.url` — browsable issue list URL
- `git.issue_tracker.list_cmd` — shell command listing open issues
- `notifications.command` — script invoked on done-state /
bounce-back; falls back to chat if empty
AILang-specific bits dropped from the prose:
- AILang/Gitea URL + tea CLI hardcoding → profile slots
- `design/contracts/0004-feature-acceptance.md` cross-reference
→ project CLAUDE.md (not the plugin's concern)
- "Boss" terminology → "orchestrator" (the plugin term; "Boss"
was AILang vocabulary)
- "Brummel-as-LLM" → "the orchestrator"
- "milestone" → "cycle" (the profile's vocabulary slot)
Universal substance preserved verbatim: Iron Law, the five
process steps, the four bounce-back triggers + new-cycle
rationale, notification protocol, done-state editorial rules,
Common Rationalisations, Red Flags. No discipline-prose compression.
design/out-of-scope claim retracted: boss DOES generalise, and
its body now demonstrates how — the queue mechanic is a single
shell-command slot, not a transport-coupled contract.
skills/README.md flags boss as the landed pilot; the other seven
skills follow once the pattern is approved.
Establishes the repository structure for the skills plugin:
- README + INSTALL describing the two-layer split (plugin
mechanics vs per-project profile)
- docs/design, profile-schema, pipeline, agent-template covering
the universal discipline constants and the profile slot model
- templates/project-profile.yml as a copy-and-fill starting point
- templates/CLAUDE.md.fragment with the baseline orchestrator
rules a project can import
- install.sh / uninstall.sh wiring skills/ + agents/ into
~/.claude/ via idempotent symlinks
- skills/ and agents/ directories empty except for migration
READMEs; the actual SKILL bodies and agent files migrate
from ~/dev/ailang/skills/ in the next iteration.
No skill or agent runs yet — this commit only stands up the
structure and documents the substitution model.
Brummel