docs: subagent execution protocol (sequential, lane ownership, conflict prevention)
This commit is contained in:
Satyam Rastogi
@@ -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.
|
||||
Reference in New Issue
Block a user