Add a third dev-cycle entry path: a specify skill that produces an
approved spec from given sources (settled in-context discussion or an
exhaustive issue) with review but no interview. Splits brainstorm's
deciding half from its producing half — brainstorm becomes optional
discovery, specify becomes the sole production gate before planner,
mirroring the RED->GREEN split that keeps tdd/debug honest. specify
bounces to brainstorm on an unresolved design fork, the same
discipline tdd uses.
Flip the naming default from `flat` (slug.md) to
`stable_per_directory_4digit` and seed `counter_dirs` with the four
document-producing directories (specs, plans, design contracts,
design models) so the counter policy is effective out of the box.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
boss pointed at 'the project's CLAUDE.md' as the sole source of
universal rules, in both the Iron Law and the cross-references.
That misses the user-level ~/.claude/CLAUDE.md identity/security
layer, which the dev architecture documents as loaded in every
session above the project file — and which carries the most
autonomy-relevant binding of all: external-service-consent rules
that explicitly name /boss and that autonomy does not lift.
The asymmetry was one-directional: the user-level file is
boss-aware (it constrains /boss by name), but boss was not
user-level-aware. Reference both layers so a reader deriving
'what binds me' from boss alone cannot miss the top layer. No
user-specific content is encoded — the consent rule is named
generically and portably.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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>
Remove the price-table cost derivation entirely. The transcript carries
no metered cost, and list prices vary by plan — so converting tokens to
a dollar figure dressed an estimate up as a number. Report raw token
counts instead, kept split by class (input / output / cache-creation /
cache-read) with a `total_tokens` sum per scope.
Script: drop DEFAULT_PRICING / load_pricing / rate_for / cost_of and the
--pricing flag; aggregate_transcript and analyze_subagents no longer take
a pricing arg; every `cost_usd` field becomes `total_tokens`; the pricing
warning is gone. SKILL.md: the first graded axis is now "Token spend &
efficiency", the scorecard and output format cite token counts, and the
Iron Law / Red Flags now forbid converting tokens to a cost.
cache_hit_ratio and the active-session warning are unchanged.
The subagent terminal-status classifier scanned the whole final report
text for status keywords, so `\bBLOCKED\b` fired on the implement
end-report's own template lines (`BLOCKED file: BLOCKED.md`,
`Blocked detail:`) and on prose narrating a surmounted blocker. Shipped
implement runs whose end-report reads `Status: DONE` were flipped to
BLOCKED — making the agent-effectiveness axis actively misleading.
Anchor on the structured `Status:` line of the end-report instead (the
implement-orchestrator emits a fixed `Status: DONE|PARTIAL|BLOCKED|...`
header, optionally markdown-bold). Fall back to a status token standing
alone on its own line for agents that emit a bare terminal token; prose
mentions and `BLOCKED.md`-style substrings no longer match. Agents with
no structured status now read `unknown` rather than a fabricated BLOCKED.
Add an executable spec (postmortem/tests/test_terminal_status.py, plain
asserts, no pytest dep) pinning the issue-#3 case plus the genuine
BLOCKED / bare-token / no-signal guards. RED before, GREEN after.
Verified on the real AILang-style session 2811d227: 3 BLOCKED (one a
false positive) -> 2 genuine BLOCKED + 13 honest unknown.
closes#3
The postmortem skill writes per-run reports under docs/postmortems/.
Those are session artifacts, not source — ignore them so running the
skill inside this repo leaves no tracked output.
A new utility skill that grades a finished session on three axes —
cost & efficiency, toolchain health, agent effectiveness — from the
session's own Claude Code flight recorder (the JSONL transcript plus
one sidechain log per dispatched subagent).
The heavy lifting lives in scripts/postmortem.py, a stdlib-only,
read-only aggregator. It handles the two accounting traps the raw log
sets: usage is repeated per streamed assistant line under a shared
requestId (deduped max-per-field, then summed across requests), and
the transcript carries no costUSD/durationMs (both null) — so cost is
derived from tokens x an overridable list-price table and labelled an
estimate, wall-clock from timestamp deltas. Subagent spend is billed
separately from its own usage objects and graded by terminal status.
Single-session by design: defaults to the newest transcript in the
project's log dir (flagged active if still live), or --session <id>
for a finished run. Secret files are out of bounds in both the Iron
Law and the Red Flags.
Verified end-to-end against a real 15-subagent session.
Step 3 framed `tdd` as a conditional add-on ("if the profile enables
the tdd phase, dispatch tdd") while `brainstorm` read as the default
spine. The orchestrator inherited that tilt and routed feature work to
`brainstorm` by reflex.
Replace it with an explicit Entry-path reflection run before every
feature dispatch: the two are co-equal, the choice is made per item by
the design line, and the one-line verdict is recorded in the loop. The
autonomy asymmetry (tdd proceeds, a fresh brainstorm cycle bounces
back) is reframed as a context-budget consequence, not a ranking, with
a guard against hardening it into an "im Zweifel brainstorm" reflex.
The one principled tilt now lives inside the test: genuine doubt that
one assertion can pin the behaviour is itself the design-fork signal.
Add two rationalisation rows and a red flag naming the default-to-
brainstorm bias.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The tdd skill referenced its neighbours (implement, brainstorm,
debug) but none referenced it back. Close the loop so the new
executable-spec-first entry path is reachable and consistent from
every skill that describes a relationship it now belongs to:
- implement: mini-mode trigger + dispatch example now cover a
RED-first handoff from `debug` OR `tdd` (was debug-only); the
orchestrator's task template and Phase-3 skip note generalised.
This was real drift — mini-mode is no longer debug-exclusive.
- planner: skip rule gains the `tdd` case (it skips brainstorm
AND planner — the RED executable-spec is the plan).
- brainstorm: `tdd` added to the permitted-skip list as the
profile-gated alternative entry path, plus a cross-ref marking
brainstorm as the bounce-back target when behaviour stops being
test-specifiable.
- boss: pipeline diagram, Step-3 routing prose, and cross-refs.
A test-specifiable feature issue is dispatched to `tdd`
autonomously, the same way a bug issue goes to `debug`; this is
NOT a new-cycle bounce-back (the test is the spec). The
bounce-back fires only reactively, when tdd surfaces a genuine
design fork.
- debug: reciprocal sibling note + cross-ref (new behaviour is
tdd's job; debug is for regressions of existing behaviour).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rule 2 (validated-or-flagged) now suggests dropping in a fenced code
snippet where it sharpens the point — the input that triggers the
failure or the call as it should behave — preferred over a prose
paraphrase.
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>
Align the design_ledger profile-slot default and its illustrative
references with the docs/ layout used by the other path slots.
Historical specs/plans are left untouched as cycle records.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cycle-close tidy for the glossary-skill cycle (59c2f4b..4fd5408).
Architect drift review (sole gate — repo ships no
.claude/dev-cycle-profile.yml, so commands.regression is empty and the
regression step is a documented no-op):
- [medium] FIXED. docs/agent-template.md said the Iron Law is rendered
'as a numbered list' (the schematic placeholder at l.37 and the prose
at the § Iron Law section), but all 13 existing agents render it as a
code-fenced block of short imperative lines — and the cycle's new
glossary-extractor.md correctly followed that universal convention. So
the drift was the template wording, stale relative to every one of its
instances, not the new file. Resolution: align the template to reality
(both spots now say 'a code-fenced block of short imperative lines').
The new agent file was carry-on — 'fixing' it to a numbered list would
have made it the lone deviant among 14 agents, i.e. introducing drift,
not removing it.
- [low] CARRY-ON. README now classes issue/glossary as 'utility skills'
but that taxonomy is not mirrored in issue/SKILL.md's or
glossary/SKILL.md's own frontmatter. Accepted as low-severity: the
invocation-class label is a README-level descriptor; mandating every
skill self-declare its class in frontmatter is gold-plating with no
consumer. Revisit only if a tool starts keying off a per-skill class.
What holds: single-sourcing preserved (the new skill cites
glossary-convention.md and restates no rule; paths.glossary semantics
defer to profile-schema.md); authority consistent across the boss
sentence, the convention, and the skill's Authority section; the
utility-vs-phase distinction held (no claim that glossary is a pipeline
phase); glossary-extractor.md conforms to agent-template.md.
Cycle is drift-clean. Not a milestone close (no milestone fieldtest run;
see docs/pipeline.md § Milestone-close gate).
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>
Task-by-task plan for the glossary-skill spec. Two create tasks
(glossary/SKILL.md mode-dispatch utility skill, glossary/agents/
glossary-extractor.md read-only per-slice prose extractor) carrying full
verbatim file bodies, plus three single-sentence wiring edits
(boss/SKILL.md bootstrap bounce-back, docs/glossary-convention.md tooling
pointer, README.md utility-skill listing + count-free framing) and a
final sweep.
Docs/prose-only repo, no test runner: every task closes on a grep
presence-assertion against the touched file. All edit-task gates use
single-token patterns or code-fence lines calibrated against verified
zero baselines (bootstrap/glossary/SKILL.md path / glossary all 0 today),
sidestepping the line-wrap pitfall recorded at c7a56c2.
Implements docs/specs/2026-05-31-glossary-skill-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Adds a new utility skill `glossary` (invoked on demand like `issue`,
not a pipeline phase) carrying two procedures over a project's glossary:
- maintain: guided add / change / remove of one entry with 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.
- bootstrap (user-only): a fan-out of read-only glossary-extractor
agents over the project's prose surface, merged and clustered into
conforming entries; clear winners auto-included, contested clusters
surfaced to the user, unresolved clusters left out (never coined).
Single-sources against docs/glossary-convention.md (the skill executes
the rules, restates none). Authority unchanged: maintain keeps the
existing user-any-time / boss-record-reality rule; bootstrap is
user-only with boss allowed to recommend it via bounce-back.
Grounding-check PASS (9/9 assumptions ratified against live repo bytes;
parse-gate a documented no-op, no spec_validation configured). The
fresh-context pass also surfaced that README's "Eight skills" framing
is already stale (omits the existing `issue` utility skill); the spec's
README edit reconciles that rather than assuming a non-existent
agent-roster note.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Cycle-close tidy for the glossary-integration cycle (fc0e1d0..HEAD).
Architect drift review (sole gate — repo ships no
.claude/dev-cycle-profile.yml, so commands.regression is empty and the
regression step is a documented no-op):
- [medium] FIXED. docs/glossary.md Avoid-lists `release`/`epic` while
profile-schema.md § vocabulary offered the same words as example
slot renamings — opposite verdicts on the same words in two in-repo
docs, with neither stating its scope, reading as contradiction.
Resolution (per the user's steer: the glossary is the new source of
truth for nomenclature): state that authority once, where the
glossary's role is owned. glossary-convention.md now declares the
set glossary the SoT for a project's nomenclature and that its
canonical entry + Avoid list win over any colliding vocabulary
example; profile-schema.md's vocabulary note defers to it with a
pointer rather than restating the rule, keeping the single-sourcing
the architect flagged as clean. The glossary itself is unchanged —
it is the SoT and was already correct.
- [low] CARRY-ON. glossary-convention.md mandates an `**Avoid:** —`
line for synonym-free terms, but no dogfood entry in glossary.md
exercises that arm (all five terms have real synonyms). Accepted as
low-severity documented debt: the rule is unambiguous prose, and
coining a synonym-free term solely to exercise a formatting arm
would be gold-plating. Revisit if a genuinely synonym-free canonical
term enters the dogfood.
What holds: wiring semantics single-sourced at the paths.glossary row;
convention/instance split clean; boss named as the only autonomous
glossary writer; all six spec acceptance criteria landed.
Cycle is drift-clean. Not a milestone close (no milestone fieldtest
run; see docs/pipeline.md § Milestone-close gate).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Pins canonical nomenclature per project so terminology does not drift
and LLM-driven work reuses the established term instead of coining a
synonym each session. The glossary rides the existing standing-reading
mechanism — one optional path slot, no new delivery path.
Single-sourcing, to avoid cross-doc drift:
- `paths.glossary` row in profile-schema.md owns the "set => standing
reading for every role; unset => no-op" semantics; agent-template.md
and pipeline.md each carry one referencing sentence, not a restatement.
- glossary-convention.md owns the format (flat per-term blocks: canonical
heading + Avoid line + <=2-sentence definition) and the boss
record-reality-never-invent write-rule; boss/SKILL.md only points to it.
- glossary.md dogfoods the format on the plugin's own vocabulary
(cycle, milestone, iteration, drift, hard-gate).
Write authority: user any time; boss autonomously but only to record
terms already in consistent use or to settle a drift it just resolved —
never to coin. All other roles are read-only consumers.
No executable surface; this repo has no test runner, so each task closed
on a grep presence-assertion against the file it touched. All eight gates
green (T1 3>=3, T2 5, T3 2, T4 1, T5 1, T6 1, T7 2, final sweep present).
Implements docs/specs/2026-05-31-glossary-integration-design.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task 1's Step-2 verification grepped for `record reality`, but in the
verbatim convention-doc content those two words straddle a line break
(`...**record` / `reality, never...`), so `grep -c` matched 0 lines and
the gate returned 2 against its own >= 3 expectation — a false BLOCKED on
byte-faithful content. Swap the pattern to `reality, never to invent`,
which matches the unwrapped line and yields 3. Content is unchanged; only
the proxy assertion was wrong.
Surfaced by the implement-orchestrator on first dispatch, which correctly
refused to reflow spec-dictated prose to satisfy the proxy and instead
escalated the plan defect.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Task-by-task plan for the glossary-integration spec. Seven tasks
plus a final sweep: create docs/glossary-convention.md and the
dogfooded docs/glossary.md, document the paths.glossary slot in
profile-schema.md, add the commented slot to the project-profile
template, wire one standing-reading sentence each into
agent-template.md and pipeline.md, and point boss/SKILL.md at the
convention's write-rule.
Docs-only cycle: no test runner, so each task closes on a grep
presence assertion calibrated against verified zero baselines.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Optional paths.glossary slot: when set, the file is standing reading
for every role (no separate standing_reading.always entry). Adds a
docs/glossary-convention.md single-sourcing the three-field format,
the standing-reading obligation, and the boss record-reality
write-rule; plus a dogfooded docs/glossary.md over the plugin's own
vocabulary. Guidance, not enforcement — no synonym check.
Grounding-check PASS: the one new semantic (paths.glossary auto-
promotion into standing reading) is carried as deliverable wiring,
not assumed to pre-exist.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Per-skill prose tightening from the same audit swarm; each finding
passed an adversarial second reviewer. No behavioural change.
- audit: drop garbled "Conventions require deferred audits to
compound" sentence (says the opposite of intent; the preceding
line already closes the loophole).
- brainstorm: drop forward-pointing meta-comment about the
Rationalisations table.
- debug: drop third restatement that debugger.md is the single
source for the carrier/handoff fields.
- docwriter: drop motivational opener; Overview starts at the
waste argument.
- fieldtest: fold the 2-4-examples rationale into the dispatch
sentence instead of restating the count a fourth time.
- implement: drop "known platform constraint at the time" aside.
- planner: cut the verbose anti-drift paragraph (which restated
the very table it claimed not to) down to a cross-reference.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Two consistency fixes across the skill suite, both found by a
prose-audit agent swarm.
Trivial-mechanical-edit carve-out: brainstorm and planner each
invented their own bound (≤30 LOC, single file) that contradicts
the canonical definition in the project's CLAUDE.md (which allows
a rename across N files and sets no LOC ceiling) and disagreed
with implement. Both now reference that carve-out instead of
restating a divergent shape.
Parse-block gate: brainstorm Step 7 and planner Step 5 spelled out
the parser-invocation protocol near-verbatim. Both now defer to
docs/profile-schema.md, which owns the protocol, and keep only
their skill-specific parts (target artefacts, failure semantics,
where the parse-trace goes) — matching the single-sourcing the
carrier contracts already use.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Correct the cycle vocabulary description, add the milestone container
slot, fix the minimal-profile example, and document the
milestone_fieldtest phase that gates the milestone close.
Correct the cycle comment (a cycle is a pipeline round, not the
top-level container); add the milestone tracker-container slot and a
commented milestone_fieldtest phase that gates the milestone close.
Reword the green-exit row, annotate the carry-on commit body, and add a
red flag: an audit-clean never licenses closing a milestone — that needs
a green milestone fieldtest (gate in pipeline.md).
Authoritative carrier contract for the milestone fieldtest: scoped to
milestone_promise, scenarios derived top-down rather than as a union of
per-cycle axes.
Define the cycle/milestone distinction and the complete-and-functional
close gate once in pipeline.md; rename audit's cycle-close edge to
drift-clean so it no longer reads as a milestone close.
Nine bite-sized tasks across eight files; pipeline.md as the single
source, fieldtester.md for the milestone carrier, then the referencing
skills and the vocabulary/profile layer, closing with a cross-file
verification sweep.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Separate `cycle` (a pipeline-graph round) from `milestone` (a
Gitea tracker container that closes only when complete AND
functional). `audit` proves drift-clean, never functional, so no
audit signal — and no `/boss` done-state — may close a milestone.
Introduces a milestone-close gate (complete ∧ functional) defined
once in docs/pipeline.md, and a milestone-wide fieldtest as a
carrier-scope variant of the existing fieldtest skill. The
milestone fieldtest runs curated end-to-end scenarios derived
top-down from the milestone's promise — proving the shipped
implementation delivers what the milestone as a whole promised,
not a mechanical union of per-cycle axes. The actual tracker
close stays a manual act; this spec only defines when a milestone
is closeable.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A field test that runs a stale pre-built binary inverts its own
purpose — it reports the previously-shipped state as current, producing
false positives on already-fixed bugs and masking newly-introduced
ones. This bit an AILang raw-buf field test: the agent ran a
target/release binary built before a fix landed, reported a fixed bug as
still-broken, and masked a real check-clean/build-crash defect until
orchestrator re-verification against a fresh build.
Phase 2 now opens with a mandatory build-from-HEAD step (run
commands.build, or invoke the tool through the build system rather than
a path to a pre-existing artefact; build the release profile if the
examples invoke a release binary), and the agent records which build the
run exercised.
Unifies four issue-writing rules — impersonal voice, every claim
validated-with-evidence or flagged as a claim, imperative concise
title (checkboxes allowed for sub-points), and self-containment
(every reference directly resolvable, no unresolvable tags) — and
records the tea-CLI mechanics for create/edit/comment/close.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Apply the debug-skill pattern (commits 6410732..de42974) to the
remaining skills: the agent file is the single source for each
interface field's semantics; the SKILL.md copy is reduced to field
names plus a pointer, marking the agent's contract table
authoritative. Because SKILL.md loads into orchestrator context and
agents/*.md into the subagent's fresh system prompt with no
transclusion, duplicated field tables drift apart over time.
- brainstorm: carrier (spec_path/iteration_scope) -> grounding-check;
the absolute-path requirement now lives only in the agent.
- planner: carrier (spec_path/iteration_scope/focus_hint) ->
plan-recon, including the mandatory/optional markers and the
BLOCKED-on-missing rule SKILL.md had omitted.
- fieldtest: carrier + produced fields -> fieldtester; the skill-level
`status` roll-up (clean/friction_found/bugs_found/infra_blocked),
which is not part of the agent's run-status protocol, stays defined
in SKILL.md only.
- docwriter: carrier + produced fields -> docwriter agent.
- implement: carrier (iter_id scratch-dir/stats/not-a-branch
semantics) -> implement-orchestrator; per-task sub-status vocabulary
moved into the orchestrator-agent (it runs the loop in a fresh
context and could not read SKILL.md at runtime, yet referenced "the
sub-status table" by name); task_text_path single-sourced in
implementer with spec-reviewer cross-referencing.
audit was already the reference implementation (pointers, no restated
contracts) and is unchanged.
closes#2
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The carrier (symptom/repro_known/recent_iter) and handoff
(red_test_path/cause_summary/constraint) field definitions were
tabled in full in both SKILL.md and debugger.md — the exact
duplication that let the `constraint` wording drift earlier.
Since the debugger agent runs in a fresh context, it must carry
both contracts inline regardless; that makes debugger.md the
natural single source. Mark its Carrier-contract and Output-format
tables authoritative, fold in the richer field descriptions that
only SKILL.md had, and reduce SKILL.md to naming the fields plus a
pointer — no field semantics restated. Drift-prone prose now lives
in exactly one place. Consistent with SKILL.md's own stated split
(debugger.md = source of truth; skill = trigger/dispatch/handoff).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The `constraint` handoff field was worded two ways: SKILL.md
omitted the "no opportunistic refactor" clause that debugger.md
carried. Same contract, two strings — exactly the interface drift
the two-file split risks. Align SKILL.md to the fuller wording.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Phase 3 previously said only "smallest possible reproducer" — a
passive property an agent can satisfy by name while still asserting
against the full reproducing fixture. Sharpen it into an explicit
two-step discipline: minimize the trigger (delta-reduce until one
more cut makes the symptom vanish) and make the fixture autonomous
(inline input, no shared fixtures/DB seeds/clocks/server boots
unless the bug is genuinely at that integration boundary).
- Iron Law gains: an un-minimized repro is not a RED test
- Phase 3 rewritten with explicit Minimize + Autonomous steps
- 3 rationalization rows + 4 red flags for the "full fixture
reproduces deterministically, ship it" failure mode
- SKILL.md overview/handoff mirrored at orchestrator altitude
Baseline (writing-skills RED-first): 6 subagent runs showed the old
wording usually steered right but relied on agent instinct; GREEN:
2 runs under the targeted full-fixture pressure now reduce to the
minimal trigger and cite the contract verbatim.
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>
Brings the spec_validation profile slot and the five defense-in-depth
fixes onto main: brainstorm + planner parse gates, grounding-check
code-block pass, plan-recon content-pin blast radius, and the
aspirational-source marker convention.
closes#1
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Brummel