From eb0f600ee041caf447663ee89a993a2e62716543 Mon Sep 17 00:00:00 2001 From: Satyam Rastogi Date: Fri, 29 May 2026 02:21:24 +0530 Subject: [PATCH] docs: subagent execution protocol (sequential, lane ownership, conflict prevention) --- .../plans/2026-05-29-execution-protocol.md | 112 ++++++++++++++++++ 1 file changed, 112 insertions(+) create mode 100644 docs/superpowers/plans/2026-05-29-execution-protocol.md diff --git a/docs/superpowers/plans/2026-05-29-execution-protocol.md b/docs/superpowers/plans/2026-05-29-execution-protocol.md new file mode 100644 index 0000000..5cc517a --- /dev/null +++ b/docs/superpowers/plans/2026-05-29-execution-protocol.md @@ -0,0 +1,112 @@ +# Execution Protocol — Subagent-Driven Build (Demo Data & Simulation) + +This is the operating manual for executing the demo build plans via subagents. It exists to guarantee **no two agents walk over each other's work, and no conflicts/errors slip through.** Every dispatched subagent operates under these rules. The **controller** (the orchestrating agent) owns this protocol. + +--- + +## 0. The one rule that prevents all conflicts + +> **SEQUENTIAL ONLY. One implementer subagent at a time. Commit after every task before dispatching the next.** + +**Why:** Almost every task edits the *same file* — `src/data/mockStore.jsx` (~6,950 lines) — and some edit the *same array* within it. Two agents editing it concurrently would clobber each other. Sequential execution + a clean commit between tasks means each agent starts from a clean, up-to-date tree and there is never a merge to resolve. + +**Never:** +- Dispatch two implementer subagents in parallel. +- Start a task while the previous task's changes are uncommitted. +- Let an agent edit a file/region outside its assigned lane (see §3 ownership map). + +(Reviewer subagents are read-only and may run, but we still do them one task at a time.) + +--- + +## 1. Branch & workspace + +- Work happens on the **`revamp`** branch (current feature branch — not main). Confirmed acceptable; no worktree needed because execution is sequential and self-committing. +- Working tree MUST be clean before each task starts. Controller verifies with `git status --short` (empty) before dispatching. + +--- + +## 2. Roles + +| Role | Who | Responsibility | Tools | +|------|-----|----------------|-------| +| **Controller** | orchestrating agent (me) | Extracts full task text, dispatches one subagent at a time, answers questions, runs the review gates, commits gate, marks TodoWrite, keeps order | all | +| **Implementer** | fresh subagent per task | Implements exactly its task, runs `npm run build` + verification, commits, self-reviews, reports status | all | +| **Spec reviewer** | fresh subagent | Confirms the change matches the task spec — nothing missing, nothing extra | read-only | +| **Code-quality reviewer** | fresh subagent | Reviews the committed diff for correctness/quality | read-only | + +The controller **provides each subagent the full task text + scene-setting context** — subagents do **not** read the plan file themselves (avoids them grabbing other tasks). + +--- + +## 3. Task ownership map (lanes — an agent may ONLY touch these) + +Execution order is the task number. Each task's editable surface: + +| # | Task | May edit ONLY | Shared-surface flag | +|---|------|---------------|--------------------| +| 1 | DEMO_TODAY anchor | `mockStore.jsx` (top-of-file constant) + `KanbanCard.jsx:~14` | — | +| 2 | `resolvePerson` selector | `mockStore.jsx` (provider body: people index + context `value` object) | — | +| 3 | Remap `orgMembers` | `mockStore.jsx` → the `orgMembers` useState array only | — | +| 4 | Remap sub-task actor ids | `mockStore.jsx` → `MOCK_SUBCONTRACTOR_TASKS` + `MOCK_NOTIFICATIONS` (actor/sender id + denormalized name fields only) | ⚠ shares `MOCK_SUBCONTRACTOR_TASKS` with Task 8 — must run before Task 8 | +| 5 | Financial reconciliation + breakdowns | `mockStore.jsx` → the `projects` array only | — | +| 6 | Seed `leads` | `mockStore.jsx` → the `leads` useState + a new `seedLeadsFromAttribution()` helper | — | +| 7 | Sub logins | `mockStore.jsx` → `MOCK_USERS` only | — | +| 8 | Task↔project + On Hold | `mockStore.jsx` → `MOCK_SUBCONTRACTOR_TASKS` (`projectId`/`location` only) + `SubcontractorTasksPage.jsx` + `TaskViewModal.jsx` | ⚠ shares array with Task 4 — runs after Task 4 | +| 9 | Kanban values + Complete fixes | `mockStore.jsx` → `KANBAN_LEADS_INITIAL` + `KANBAN_PROJECT_DATA` only | — | + +**Lane rule:** if an implementer believes it must touch a surface outside its lane, it STOPS and reports `NEEDS_CONTEXT` to the controller — it does not edit out of lane. + +**Invariant every task must preserve:** the canonical ID scheme from the plan (`own_001/own_002`, `e1–e5`, `a1–a3`, `con_001`, `sub_001–005`). No task may reintroduce `owner_001`/`FA0*`/`ADM0*` ids or the names "Maria Garcia"/"Admin One/Two/Three". + +--- + +## 4. Per-task lifecycle (controller runs this for each task, in order) + +1. **Pre-flight:** `git status --short` must be empty. Confirm previous task committed. +2. **Dispatch implementer** (fresh subagent) with: the task's full text (all steps), the Canonical ID table, the scene-setting context (what the file is, where the task fits), its **lane** from §3, and the verification commands. Use the model tier from §6. +3. **Questions:** if the implementer asks, answer fully, then let it proceed. Do not rush it. +4. **Implementer does:** edits within its lane → runs `npm run build` (must be clean) → runs the task's grep/reconciliation verification → commits with the task's commit message → self-reviews → reports status (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED). +5. **Status handling** (per skill): DONE→review; DONE_WITH_CONCERNS→read concerns, address if correctness/scope; NEEDS_CONTEXT→provide & re-dispatch; BLOCKED→diagnose (more context / stronger model / split task / escalate). +6. **Spec review** (fresh read-only subagent): does the committed diff implement the task — nothing missing, nothing extra, lane respected, invariant preserved? If issues → same implementer fixes → re-review. Do not proceed until ✅. +7. **Code-quality review** (fresh read-only subagent) — only after spec ✅: review the diff for correctness/quality. Issues → implementer fixes → re-review until ✅. +8. **Mark task complete** in TodoWrite. Go to next task. + +**Continuous execution:** the controller runs tasks 1→9 back-to-back without pausing to ask the human "should I continue?". Stop only on an unresolvable BLOCKED, genuine ambiguity, or all-tasks-complete. + +--- + +## 5. Verification gates (every task) + +A task is not DONE until ALL pass: +- ✅ `npm run build` → `✓ built`, **zero** errors (this is what caught the duplicate-declaration bug; treat any build error as a hard stop). +- ✅ The task's specific check (e.g., `git grep -nE "owner_00[12]|\bADM0[123]\b|FA00[12345]"` returns no matches after Tasks 3–4; breakdown sums == totals after Task 5; dev-run shows non-empty Leads after Task 6). +- ✅ Change is committed; working tree clean. + +Final gate after Task 9: run the plan's **self-review checklist**, then a whole-implementation code review subagent, then `superpowers:finishing-a-development-branch`. + +--- + +## 6. Model selection + +- Mechanical data edits (Tasks 1, 3, 4, 7, 9): **cheap/fast model** — clear specs, single region. +- Judgment edits (Task 5 financial reconciliation, Task 6 leads seed, Task 8 cross-references): **standard model**. +- All reviewers: **standard model**; final whole-implementation review: **most capable**. + +--- + +## 7. Conflict & error prevention — quick checklist for the controller + +- [ ] Only one implementer in flight at any time. +- [ ] Tree clean before each dispatch. +- [ ] Each task committed before the next starts. +- [ ] Task 4 ran before Task 8 (shared array). +- [ ] No agent edited outside its §3 lane. +- [ ] Canonical-ID invariant intact after every task. +- [ ] Build green after every task. + +--- + +## 8. Notes for future plans (2–5) + +The same protocol applies. Plans 3–5 add new component files, which reduces shared-file contention — but the sequential-and-commit rule and the lane/ownership map (regenerated per plan) still hold. Re-author §3 for each plan before executing it.