feat(agents): spec-designer role — promote Stub SPECs to Draft via claude #80

Merged

navigator merged 1 commit from feat/spec-designer-role into main

2026-05-26 00:54:45 -03:00

navigator commented

2026-05-25 21:18:09 -03:00

Owner

Summary

Adds a sixth swarm role that promotes rtl/src/pop/specs/<Module>.SPEC.md files from Status: Stub to Status: Draft, gating the only serial step in the design pipeline.

Before this PR, advancing chip RTL required: human writes Draft SPEC → resolver implements Chisel → reviewer checks → approver merges. Step 1 was a single-threaded human bottleneck via the Telegram bridge; the resolver refuses to fabricate widths or behaviour, so without a Draft SPEC there is nothing for it to implement.

With spec-designer, the swarm fans out:

spec-designer  ─┐                              ┌─ pr-reviewer ─ pr-approver
                ├── promotes Stub → Draft ────┤
issue-opener ──┤                              │
                └── resolver implements ───────┘

Constraints baked into the prompt

The system prompt at roles/prompts/spec-designer.md requires the model to resolve every TBD by one of three routes:

Pinned to an ADR — (per ADR-NNN-foo.md) with the verbatim decision.
Pinned to a PLAN section — (per PLAN.md §8.2).
Open question — _Open question:_ <one sentence> when no source pins it.

Fabricated widths / vendor commitments / performance numbers are disallowed. The PR is reviewed by pr-reviewer like any other.

Pieces

roles/spec-designer.sh — long-running poller, one promotion per cycle (default 600s).
roles/prompts/spec-designer.md — system prompt.
units/fluidpop-spec-designer.service — systemd user unit.
install-swarm.sh — state dir + service start order.

Test plan

bash -n clean.
After merge: re-run infra/ops/agents/install-swarm.sh to wire the unit.
Watch first cycle on a known-stub SPEC (e.g. PopSoCConfig.SPEC.md). Confirm a spec/popsocconfig-draft PR is opened and lands review:pass from pr-reviewer.

Notes

Off-limits per ADR-017 (infra/ops/agents/**) — merged manually by navigator.

## Summary Adds a sixth swarm role that promotes `rtl/src/pop/specs/<Module>.SPEC.md` files from `Status: Stub` to `Status: Draft`, gating the only serial step in the design pipeline. Before this PR, advancing chip RTL required: human writes Draft SPEC → resolver implements Chisel → reviewer checks → approver merges. Step 1 was a single-threaded human bottleneck via the Telegram bridge; the resolver refuses to fabricate widths or behaviour, so without a Draft SPEC there is nothing for it to implement. With `spec-designer`, the swarm fans out: ``` spec-designer ─┐ ┌─ pr-reviewer ─ pr-approver ├── promotes Stub → Draft ────┤ issue-opener ──┤ │ └── resolver implements ───────┘ ``` ## Constraints baked into the prompt The system prompt at `roles/prompts/spec-designer.md` requires the model to resolve every TBD by one of three routes: 1. **Pinned to an ADR** — `(per ADR-NNN-foo.md)` with the verbatim decision. 2. **Pinned to a PLAN section** — `(per PLAN.md §8.2)`. 3. **Open question** — `_Open question:_ <one sentence>` when no source pins it. Fabricated widths / vendor commitments / performance numbers are disallowed. The PR is reviewed by `pr-reviewer` like any other. ## Pieces - `roles/spec-designer.sh` — long-running poller, one promotion per cycle (default 600s). - `roles/prompts/spec-designer.md` — system prompt. - `units/fluidpop-spec-designer.service` — systemd user unit. - `install-swarm.sh` — state dir + service start order. ## Test plan - [x] `bash -n` clean. - [ ] After merge: re-run `infra/ops/agents/install-swarm.sh` to wire the unit. - [ ] Watch first cycle on a known-stub SPEC (e.g. `PopSoCConfig.SPEC.md`). Confirm a `spec/popsocconfig-draft` PR is opened and lands `review:pass` from `pr-reviewer`. ## Notes Off-limits per ADR-017 (`infra/ops/agents/**`) — merged manually by navigator.

navigator added 1 commit

2026-05-25 21:18:09 -03:00

feat(agents): spec-designer role — promote Stub SPECs to Draft via claude

build / scalafmt-check (pull_request) Successful in 3s

Details

build / sbt-compile (pull_request) Successful in 3s

Details

build / shell-lint (pull_request) Successful in 11s

Details

8900724ae4

Adds a sixth swarm role that picks one `rtl/src/pop/specs/<Module>.SPEC.md`
file with `Status: Stub`, gathers the ADRs the SPEC references plus the
referenced PLAN.md sections plus any Draft sibling SPECs plus the
existing Chisel IO patterns under `rtl/src/pop/`, and invokes `claude -p`
with a strict promotion prompt. The model is required to either pin
every TBD to an ADR / PLAN section / sibling SPEC, or mark it as an
explicit `_Open question:_`. Fabricated values are disallowed.

The result lands as a PR `spec/<module>-draft → main` labelled
`ready-for-review`, which goes through pr-reviewer and pr-approver
like any other PR.

Operates one SPEC per cycle (default 600s) to keep claude usage bounded.
Per-module fail markers in `${ROLE_STATE}/seen/` suppress retry for an
hour after a failed run.

Rationale: before this, SPEC promotion (Stub → Draft with concrete
Interface / Behavior / Invariants pinned to ADRs) was a serial,
human-only step that bottlenecked all downstream RTL implementation
work — the resolver refuses to fabricate widths or behaviour, and
without a Draft SPEC there is nothing concrete to implement. With this
role the swarm can advance design and implementation in parallel.

Off-limits per ADR-017 (`infra/ops/agents/**`) — must be reviewed and
merged manually by navigator after CI green. Once landed, run
`bash infra/ops/agents/install-swarm.sh` to wire the new unit.