docs: subagent execution protocol (sequential, lane ownership, conflict prevention)

2026-05-29 02:21:24 +05:30
parent 10450b05de
commit eb0f600ee0
1 changed files with 112 additions and 0 deletions
@@ -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.