[Spec 984] Multi-architect coordination layer — spec + plan review (DRAFT, do not merge)#1010
[Spec 984] Multi-architect coordination layer — spec + plan review (DRAFT, do not merge)#1010waleedkadous wants to merge 18 commits into
Conversation
Multi-architect coordination layer: roster, board, dedup-at-spawn ledger, formal lifecycle, bounded state files, per-architect checkout isolation. Six points framed as one SPIR with recommended defaults + flagged Open Questions for the consequential forks (#6 approach/slicing, state rotation mechanism, architect-state-file convention).
Incorporated Gemini/Codex (REQUEST_CHANGES) + Claude (COMMENT) feedback: - Resolved acceptance-critical OQs (state-file location, override flag, rotation mechanism, last-activity source, retire policy) into a new Resolved Design Decisions section. - #5 rotation: parseable <!-- ARCHIVE BOUNDARY --> delimiter, whole-entry moves, loss-free reconstruction test (no markdown-splitting). - #6: .architects/<name>/ (gitignored), dirty-worktree abort-unless-force retire guard, spawn-base-resolution sketch, resolved migration/compat contradiction (main=main checkout, new architects isolated by default). - Ledger: override release-and-reinsert semantics, partial unique index for atomic dedup (concurrent-spawn race), close/reopen + cleanup rules. - Roster: overview-cache intersection for open/closed + unknown-on-outage. - who-owes-next as a total function; CODEV_ARCHITECT_NAME N>1 validation. - Added test scenarios 12-16 + consultation log.
…ect decision) Architect approved at spec-approval gate with one change: Point #6 becomes builder-base SHA-pinning (documented fallback B) instead of per-architect checkout isolation. Capture a fresh integration-branch-tip SHA (fetch + rev-parse) at spawn, branch builder from it, fail-fast on fetch error, --base override. Architects keep sharing the main checkout; 'never switch branches' stays for architects. Dropped: migrate-architect surface, dirty-worktree retire guard, .architects/ worktrees. Consequences: #6 PR-slicing moot (ships in main PR), migration ergonomics moot. Updated #6 section, Desired State, Success Criterion, Current State, Constraints, Assumptions, Performance, Risks, Test Scenarios 10/11/14, non-functional #2, Resolved Decisions, Open Questions, Notes + Amendment log.
7 phases in dependency order: (1) ownership ledger + dedup-at-spawn, (2) afx architects roster, (3) bounded/rotated state files, (4) architect lifecycle (state file on add / archive+release on retire), (5) board / who-owes-next dashboard grouping, (6) builder-base SHA-pin (architect- directed #6), (7) documentation. All ship in one PR. Grounded in verified integration points (schema/migrations, state CRUD, spawn paths, Tower routes/client, overview cache, dashboard, CLI, Vitest patterns).
Incorporated Codex REQUEST_CHANGES + Gemini/Claude APPROVE notes: - Phase 1: claim ownership BEFORE worktree/session creation (+ rollback on failure); scope to numbered spawns only; add types.ts/spawn.test.ts plumbing; resolve closed-issue dedup default (treat same as open). - Phase 6: attached-branch flow (was detaching); modify createWorktree() only (not createWorktreeFromBranch); default-branch fallback chain; stale-HEAD test fixture. - Phase 5: board joins the ledger + synthesizes owned-but-unspawned overview rows (not just architectCount + spawnedByArchitect). - Minor: state-rotation -> codev/src/lib; correct addArchitect/removeArchitect line numbers; mkdir -p for new state dirs; workspace-path risk; SSE optional. - Migration: db.exec(LOCAL_SCHEMA) auto-applies IF NOT EXISTS to existing DBs.
|
A couple of spec-approval-gate concerns: Evidence ambiguity. "Peak 5 architects + 7 builders" is the spec's only quantitative datum, and it's ambiguous. Read as fleet total → ~1.4 builders per architect (12 agents), which makes most of the six points over-scoped relative to the pain (dedup is the only piece that scale-binds at 12 agents). Read as "7 per architect" → 35 agents, all six points justified. The spec's scope decision depends on which reading is correct. Worth a one-line clarification from the source workspace and a sentence calibrating the proposed scope to whichever number it is. So far, in my experience, a single architect can easily manage up to 10 builders per workspace, for me, that would be up to 10 issues on Codev + 10 issues on Shannon + 10 issues on Kids Can Spell - that's way more than enough for a single engineer. Communication-layer gap. The spec adds observability (roster, board) and coordination (ledger, lifecycle) but doesn't address how the human actually talks to N architects. Today that's N independent terminals with no unified send surface, mention syntax, or aggregated feed. Observability is consulted occasionally; communication happens every interaction. The spec helps you remember your fleet but not use it, which risks the spec shipping, working as specified, and still being judged as not having moved the operator's experience. One of the advantages of the architect model is that it eliminates the case for having to deal with many terminals windows . I don't want to go back to that model again. |
2 participants
This builder is paused at the
plan-approvalgate. This draft PR exists solely to get other eyes on the spec and plan before implementation begins. There is no implementation code here yet — the diff is purely the spec, plan, rebuttals, thread, and porch status.What to review
codev/specs/984-multi-architect-coordination-l.mdcodev/plans/984-multi-architect-coordination-l.mdcodev/reviews/984-specify-iter1-rebuttals.mdKey design decision to sanity-check
Phase 6 is SHA-pin (builder-base pinning), NOT per-architect worktrees — this was an architect-level decision that diverged from one earlier option. Reviewers should weigh in on whether SHA-pin is the right mechanism for the multi-architect coordination guarantee.
Prior review
The plan already went through an iter-1 multi-agent consult (Gemini: REQUEST_CHANGES, Codex: REQUEST_CHANGES, Claude: COMMENT); the builder incorporated the findings and posted a rebuttal (above). This round is for independent human / other-architect eyes, not another AI pass.
How to leave feedback
Comment inline on the spec/plan files, or drop overall notes in the PR conversation. Once feedback is in, the human approves the
plan-approvalgate and the builder resumes into the implement phase.