Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
268ee705f42e2c14346ac5ec29f1c2cd94296907
Skills/docs/pipeline.md
T
Brummel 268ee705f4 feat(specify): record in-context fork resolutions as auditable issue comments 
The `spec-skeptic` `scope-fork` juror reads only the seeding issue plus
the spec. On the legitimate `specify` direct-entry path — a fork settled
in a long in-context design discussion — that resolution lives only in
ephemeral chat the juror cannot replay. When the issue body lags the
discussion (still lists the fork open), the juror correctly blocks, and
a design BLOCK escalates without self-correction. The result: auto-sign
was structurally almost unreachable for the in-context entry path.

Close the blind spot by giving the juror an auditable source instead of
weakening the gate. When `specify` enters in-context and a tracker issue
still lists a now-resolved fork as open, the orchestrator posts a
reconciliation comment recording each fork's resolution WITH provenance
(a record of the user's decision, never a fresh orchestrator one) before
writing the spec. The comment is persistent and audit-able — unlike a
carrier digest — so it, not the orchestrator's confidence, is what the
juror checks.

Separation of powers keeps it honest: the orchestrator writes the
comment, the adversarial juror enforces the provenance requirement. A
bare `decision: X` with no provenance does not resolve the fork — the
re-dispatched juror blocks on it. The escalation rule and the
three-field carrier are untouched; only the juror's information changes.

Mechanics:
- specify Step 1.5: reconciliation-comment sub-step, provenance format,
  issue-less fallback (auto-sign -> human sign-off, no weak spec-note).
- spec-skeptic: replace the "quoted in the dispatch" drift; juror reads
  the issue WITH comments via `issue_tracker.show_cmd`; provenance check.
- new profile slot `issue_tracker.show_cmd` (must render comments);
  documented in schema + template.
- issue skill: `tea issues <idx>` is body-only; `--comments` required
  (verified against tea 0.14.1 and Aura #55 — 180 vs 144 lines).
- consistency: design.md out-of-scope, README, pipeline.md, boss skill.
2026-06-12 15:54:47 +02:00

239 lines
10 KiB
Markdown
Raw Blame History

# Pipeline
```
[new cycle] [test-specifiable feature] [bug observed]
| | |
v v v
brainstorm -> specify -> plan -> implement debug -> implement (mini)
^ ^ |
| | tdd -> implement (mini)
| specify -> plan (design settled in sources)
+----(design fork)----------/ (specify/tdd bounce here; RED executable-spec -> GREEN)
(per iteration loop)
|
[cycle close — a loop step, not a milestone close]
|
v
audit --(drift)--> plan + implement (tidy iteration)
--(ratify)-> --update-baseline + ratify paragraph in audit commit body
--(drift-clean)-+
|
[orchestrator: cycle complete? if surface-touch:]
v
fieldtest --(bug)------> debug -> implement (mini)
--(friction)-> brainstorm OR plan (tidy)
--(spec_gap)-> ratify OR tighten ledger
--(clean)----+
|
[orchestrator: surface stable across N cycles?]
v
docwriter
|
v
next cycle
```
## Cycle vs. milestone
These are two distinct axes, and conflating them is a bug.
- A **cycle** is one round in the pipeline graph above
(`brainstorm → specify → planner → implement → audit → [fieldtest]`).
A cycle close is an internal loop step.
- A **milestone** is a tracker container (Gitea milestone,
GitHub milestone, Linear project — whatever the project's
tracker calls a long-running work scope). A milestone spans
potentially many cycles and closes only when the work it
promised is **complete and functional** (see the gate below).
`audit` runs at cycle close and proves *drift-clean* — the code
matches the design ledger. It is blind to whether the work is
*functional* from a downstream consumer's point of view; that is
what `fieldtest` measures. So no `audit` result closes a
milestone, and neither does a `/boss` done-state.
## Milestone-close gate
A milestone may be closed in the tracker only when **both** legs
hold:
1. **Complete** — every cycle filed under the milestone is
`audit` drift-clean (or its drift explicitly ratified), and
the milestone container has no open iterations / issues left.
2. **Functional** — the **milestone fieldtest** has run its
curated end-to-end scenarios against the milestone's promise
and its status roll-up is `clean`: every scenario
demonstrably delivers what the milestone promised; no open
`bug` findings; `friction` / `spec_gap` findings resolved or
ratified into the design ledger.
The milestone fieldtest is the milestone-wide variant of the
`fieldtest` skill: the same fieldtester agent, a carrier scoped
to the milestone's promise rather than one cycle's surface. Its
scenarios are chosen top-down from what the milestone as a whole
promised, not assembled as the union of per-cycle axes.
A milestone whose entire scope is internal (no user-visible
surface) is exempt from the functional leg — the milestone
fieldtest is *not applicable* and the complete leg suffices.
This gate defines *when* a milestone is closeable. The actual
close stays a deliberate human / orchestrator act — the
tracker's own milestone-close action (on Gitea, `tea milestone
close`); no skill performs it automatically.
## Phase descriptions
### brainstorm
Optional discovery front-end. Gathers requirements, explores 2-3
approaches with trade-offs, presents a sectioned design with user
approval, then hands the ratified design to `specify` (it writes no
spec itself). Skipped when the design is already settled in the
sources — that work enters through `specify` directly.
### specify
Hard-gate before plan — the spec-production core and the carrier of the
"no plan without an approved spec" invariant. Takes a settled design
(directly from sources, or a ratified design handed over by
`brainstorm`), applies the feature-acceptance criterion, writes the
spec to the configured `spec_dir`, runs the parse-every-block and
`grounding-check` gates, and takes user sign-off — with review but no
interview. Bounces to `brainstorm` the moment the sources do not
resolve a load-bearing design decision. A core node, not opt-in
(unlike `tdd`).
The sign-off is the user's by default, including under `/boss`. The
one exception is the opt-in `pipeline.boss.spec_auto_sign` slot: with
it on, a `/boss` run may sign a spec in the user's place — but only
when every objective gate is green AND a unanimous five-lens
`spec-skeptic` panel passes; the orchestrator's own confidence never
signs. A `BLOCK` is never signed over: an editorial one (`criterion` /
`ambiguity` / `plan-readiness`) is repaired in a bounded ≤ 2-round loop
that re-runs the objective gates and re-dispatches all five lenses each
round; a design one (`scope-fork` / `grounding`), an `INFRA_ERROR`, or
an exhausted budget falls back to the human sign-off pause. When the
entry is in-context and the seeding issue still lists a now-resolved
fork as open, `specify` posts a provenance-bearing reconciliation
comment on the issue (Step 1.5) so the `scope-fork` juror can ratify the
resolution instead of blocking on the stale body. See
`../specify/SKILL.md` Step 6 and `../boss/SKILL.md` §"Spec auto-sign".
### planner
Hard-gate before implement. Produces a placeholder-free,
bite-sized implementation plan in the configured `plan_dir`
that the implement skill can execute task-by-task. Dispatches
the plan-recon agent for read-only file-structure mapping.
### implement
Dispatches the implement-orchestrator agent, which runs the
entire per-task loop (implementer phase → spec-compliance check
→ quality check) as sequential role-switches inside its own
context. Writes code, tests, and stats files directly in the
working tree as unstaged changes. On `PARTIAL` or `BLOCKED`,
also writes `BLOCKED.md` at the repo root.
### audit
Runs at cycle close. Dispatches the architect agent (read-only
drift review against the design ledger) and the bencher agent
(regression diagnostics). Reports drift and regress.
### debug
Runs whenever a bug is observed. RED-first: produces a failing
test in the working tree before any fix is attempted. Hands off
the GREEN side to the implement skill in mini mode.
### tdd
Opt-in alternative to the `brainstorm → specify → planner` design entry,
for work whose desired behaviour is test-specifiable — expressible
as one failing test. RED-first: the `tdd-author` agent turns a
description or issue into a single minimal, autonomous RED
executable-spec ("how it should work"), then hands the GREEN side
to `implement` in mini mode, exactly as a bug fix. When the
behaviour is not test-specifiable (a genuine design fork surfaces),
or two decomposition rounds fail, it bounces back to `brainstorm`.
When one iteration cannot reach GREEN, the headline test is carved
into a ladder of BLOCKER sub-tests, each its own RED→GREEN
mini-cycle. Distinct from the per-task TDD the implementer already
practices inside `implement`.
### fieldtest
Optional. Orchestrator-dispatched after the audit closes clean
on a cycle that touched user-visible surface. Picks 2-4 real-
world tasks within the cycle's scope, implements them using
only the design ledger and public examples (never the language's
own implementation), runs the results, and writes a friction-
and-bug spec.
### docwriter
Optional. Orchestrator-dispatched after API surface has
stabilised across multiple cycles. Brings docstrings up to a
level where a newcomer can navigate the public API without
reading the design ledger first.
## Status protocol
Agents return one of these terminal states:
| State | Meaning |
|-------|---------|
| `DONE` | Task complete; no concerns. |
| `DONE_WITH_CONCERNS` | Task complete; flagged issues the orchestrator should weigh before committing. |
| `PARTIAL` | Task partially complete; the rest is blocked or out-of-scope. Writes `BLOCKED.md`. |
| `BLOCKED` | Task cannot proceed; explanation in report. Writes `BLOCKED.md`. |
| `NEEDS_CONTEXT` | Task cannot proceed without additional information from the orchestrator. |
Reviewer agents have role-specific states:
| Role | States |
|------|--------|
| spec-reviewer | `compliant` / `non_compliant` / `unclear` / `infra_blocked` |
| quality-reviewer | `approved` / `changes_requested` / `infra_blocked` |
## Skip rules
Skipping is codified per skill, not ad hoc. Each `SKILL.md`
documents what the skill skips and under what conditions:
- `specify` is never skipped at cycle start — it is the spec-production
gate before `planner`. `brainstorm` is the *optional* discovery stage
before it: skipped when the design is already settled in the sources
(the work enters through `specify` directly), run when a load-bearing
decision is still open.
- `planner` is never skipped at iteration start, except for
the bug-driven `debug → implement (mini)` side path.
- `implement` is the iteration body; not skippable.
- `audit` is mandatory at cycle close.
- `debug` is mandatory RED-first for any observable bug.
- `tdd` is an opt-in alternative entry to `brainstorm` for
test-specifiable work; it bounces back to `brainstorm` on a
design fork. A profile that omits the `tdd` phase disables it.
- `fieldtest` and `docwriter` are optional and orchestrator-
dispatched.
If a skill's body says it must run and the orchestrator wants
to skip it, the orchestrator records the reason in the relevant
commit body — never as undocumented practice.
## Pipeline configuration
The phase set, gating, and conditional dispatch are configured
in the project profile under `pipeline:`. A project that does
not want `fieldtest` simply omits the key. A project that wants
a different gate set (e.g. `planner` without a `brainstorm`
gate, for trivial bug-fix iterations) configures it there.
See `profile-schema.md` for the syntax.
If the profile sets `paths.glossary`, that file is standing reading
for every role — the canonical-nomenclature source every skill and
agent consults (see `glossary-convention.md`). Unset, it is a no-op.
Reference in New Issue View Git Blame Copy Permalink