| name | phase-loop |
| description | Run the osr-editor phase loop — plan a roadmap phase, implement one, and drive the rubber-duck review to SOLID. Use when asked to work up a plan for phase N, implement the plan for phase N, or rubber-duck an artifact. |
The phase loop
Each roadmap phase in docs/spec.md ships as two PRs — a plan, then an implementation — and both follow the same create → rubber-duck → revise-until-solid → PR loop. "Work up a plan for phase N" or "implement the plan for phase N" means run this loop end to end, unprompted. The workflow mirrors osrlib-python's AGENTS.md; keep parity with it unless that file says otherwise.
Planning a phase
- Research first: the phase's roadmap entry and every contract it touches in
docs/spec.md, the prior phase plans in docs/, the existing code, and the osrlib and osr-forge surfaces the phase consumes. Hazards found during research (model validators, forge normalization rules, frozen-model rebuild patterns) belong in the plan so the implementer doesn't rediscover them.
- Write
docs/phase-N-plan.md, structured like the sibling projects' phase plans: intro with the spec milestone, scope (in and out, naming the phase that picks up each deferral), work items, sequencing, definition of done. Plans are decision-complete: every choice an implementer would otherwise guess at is pinned with a rationale.
- Branch
phase-N-plan; commit the draft as add phase N implementation plan (pre-review draft).
- Rubber-duck it (below), revise until SOLID, open the PR.
Implementing a phase
The same loop on branch phase-N-impl: implement to the plan with tests green, commit, rubber-duck the result, and address findings as address rubber-duck review findings. The plan is the contract — when implementation reveals the plan was wrong or silent, amend the plan document on the same branch (amend phase N plan: ...) so plan and code never diverge.
The rubber-duck loop
- Spawn a fresh subagent as a skeptical senior reviewer. Give it an ordered reading list — the spec, prior plans,
AGENTS.md, the artifact under review, the relevant code, and the osrlib or osr-forge models and docs the work touches — and require evidence: every finding must quote the spec, the code, or the artifact, be ranked blocking vs non-blocking, and the review must end in a verdict (SOLID or NEEDS REVISION) plus a verified-good list of claims it actively checked.
- The reviewer's mandate covers design hygiene, not just spec fidelity: it must hunt for the greenfield anti-patterns in
AGENTS.md (back-compat shims, dual import paths, deprecation scaffolding, dead accommodation code) and flag any it finds.
- Judge findings on the merits. Verify disputed claims against the spec, osrlib, osr-forge, or the code yourself; push back on findings that are wrong instead of deferring to the duck. Address what survives and commit as
revise phase N plan per rubber-duck review (or the address-findings message above).
- Send the revision back to the same reviewer, context intact, for re-verification of each fix. Loop until SOLID. Fold in any sign-off notes.
- Commits tell the honest story — draft, revision(s), sign-off tweaks — and the PR description summarizes the notable decisions plus the review provenance (what the duck found, what changed).
