SPIR: builder-prompt ambiguous on one-PR-per-spec vs per-phase PRs

[waleedkadous]

Summary

The SPIR builder-prompt template (codev/protocols/spir/builder-prompt.md + skeleton mirror) does not explicitly state the one-PR-per-spec convention. Builders interpret the plan's "each phase commits independently" as "each phase gets its own PR," and ship per-phase PRs that the architect then has to close.

Reporter

Shannon architect, 2026-05-14 ~20:35 PDT via team channel.

Concrete case

Shannon Spec 1353's builder opened PR #1373 for Phase 1 alone, expecting to open more PRs for subsequent phases. Project convention is one PR per spec with phase-commits inside. Architect pushed back; builder closed the PR and continued on the branch. ~10 min of architect time to redirect.

Fix shape

Add an explicit statement to codev/protocols/spir/builder-prompt.md (and the skeleton mirror):

All phases ship in ONE PR opened at the end of Phase N (the final implementation phase). Phase-commits land on the same branch as [Spec NNNN][Phase: phase-name] commits, but do NOT open a separate PR per phase unless the architect explicitly requests it.

Plus a clarifying note that the plan's "each phase commits independently" refers to git commits, not PRs.

Files to fix

1. codev/protocols/spir/builder-prompt.md
2. packages/codev/skeleton/protocols/spir/builder-prompt.md

(Check if ASPIR has the same ambiguity — likely yes since it inherits from SPIR.)

Suggested protocol

BUGFIX — small, isolated, well-defined fix.

[waleedkadous]

On it! Working on a fix now.