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)	—
R	Canonical roster rename (real Texan names + LUP empIds)	`mockStore.jsx` people source records (`MOCK_USERS`/personnel/owners/subcontractors) + repo-wide replacement of the old name strings	⚠ cross-cutting (touches many regions/files) — runs after Task 2, before Task 3, alone, then commits
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	—
L	Login per-role person picker	`src/pages/Login.jsx` + `src/context/AuthContext.jsx` only	runs last

Canonical execution order: 1 → 2 → R → 3 → 4 → 5 → 6 → 7 → 8 → 9 → L. (Task R establishes names before the id-remaps; Task L wires the picker after all people exist.)

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 (own_001/own_002, e1–e5, a1–a3, con_001, sub_001–005) and the canonical roster names/empIds (see the plan's roster table — Wade Hollis, Cody Tatum, Carlos Mendoza, etc., with LUP-#### empIds). After Task R, no task may reintroduce old ids (owner_001/FA0*/ADM0*) or old placeholder names ("Frank Agent", "Adam Admin", "Admin One/Two/Three", "Maria Garcia", "Sarah Sales", "Carlos Subcontractor", "Mike Contractor", etc.).

4. Per-task lifecycle (controller runs this for each task, in order)

Pre-flight: git status --short must be empty. Confirm previous task committed.
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.
Questions: if the implementer asks, answer fully, then let it proceed. Do not rush it.
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).
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).
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 ✅.
Code-quality review (fresh read-only subagent) — only after spec ✅: review the diff for correctness/quality. Issues → implementer fixes → re-review until ✅.
Mark task complete in TodoWrite. Go to next task.

Continuous execution: the controller runs the canonical order (1 → 2 → R → 3 → 4 → 5 → 6 → 7 → 8 → 9 → L) 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); Task R ran after Task 2 and before Task 3.
No agent edited outside its §3 lane.
Canonical-ID and roster-name invariant intact after every task (no old ids/names reintroduced).
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.

8.5 KiB Raw Blame History Unescape Escape