ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

conductor(track): superpowers review section 7 — subagent-driven-development (deep-dive)

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-07-05 13:21:03 -04:00
parent b97fed2538
commit 2a48e0d164
1 changed files with 71 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/tracks/superpowers_review_20260619/report.md
+71 -1
View File
@@ -385,7 +385,77 @@ The project follows the systematic-debugging discipline with significant elabora
## 7. Subagent-Driven Development
<!-- Section 7 deep-dive (200-400 LOC). Skill: subagent-driven-development. Verdict pending. -->
## 7. Subagent-Driven Development
### 7.1 What the skill prescribes
The `subagent-driven-development` skill is the "execute plan by dispatching fresh subagent per task, with two-stage review after each" pattern. Core principle: "Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration." The "continuous execution" rule says: "Do not pause to check in with your human partner between tasks. Execute all tasks from the plan without stopping. The only reasons to stop are: BLOCKED status you cannot resolve, ambiguity that genuinely prevents progress, or all tasks complete. 'Should I continue?' prompts and progress summaries waste their time — they asked you to execute the plan, so execute it."
The Process flow per task: (1) Dispatch implementer subagent; (2) Implementer asks questions? (yes → answer, no → proceed); (3) Implementer implements, tests, commits, self-reviews; (4) Dispatch spec reviewer subagent; (5) Spec reviewer confirms code matches spec? (yes → dispatch code quality reviewer; no → implementer fixes); (6) Dispatch code quality reviewer subagent; (7) Code quality reviewer approves? (yes → mark task complete; no → implementer fixes); (8) Loop to next task.
The Model Selection guidance is hierarchical: cheap models for mechanical implementation (1-2 files, clear specs); standard models for integration (multi-file coordination); most capable models for architecture/design/review.
The Implementer Status enum is 4-state: DONE (proceed to spec review); DONE_WITH_CONCERNS (read concerns; address correctness/scope concerns before review; note observations and proceed); NEEDS_CONTEXT (provide missing context, re-dispatch); BLOCKED (assess: context problem → provide more; needs more reasoning → upgrade model; too large → break into smaller; plan wrong → escalate to human).
The Red Flags list: "Never start implementation on main/master without explicit user consent"; "Never skip reviews"; "Never proceed with unfixed issues"; "Never dispatch multiple implementation subagents in parallel"; "Never make subagent read plan file (provide full text)"; "Never skip scene-setting context"; "Never ignore subagent questions"; "Never accept 'close enough' on spec compliance"; "Never start code quality review before spec compliance is ✅"; "Never move to next task while either review has open issues".
### 7.2 Mapping to the project's existing pattern
The project's MMA (Multi-Model Architecture) is a faithful re-encoding of subagent-driven-development with three elaborations (4-tier hierarchy, context-amnesia tier-3 workers, tier-4 QA as second-stage review):
| Skill rule | Project equivalent | Where |
|---|---|---|
| "Fresh subagent per task" | "Tier 3 Worker: Stateless Tier 3 Worker for surgical code implementation and TDD" (per `.agents/skills/mma-tier3-worker/SKILL.md`); "Context Amnesia (Tiers 3 & 4): The OpenCode Task tool enforces 'Context Amnesia' by executing sub-agents in a stateless manner." | `conductor/workflow.md` §"Conductor Token Firewalling" + `.agents/skills/mma-orchestrator/SKILL.md` |
| "Two-stage review (spec then quality)" | The Tier 4 QA agent as the second-stage review (per `conductor/workflow.md` §"Conductor Token Firewalling"): "Tier 4 (Utility/QA): gemini-2.5-flash-lite. Used for log summarization and error analysis. Operates statelessly (Context Amnesia) but has access to diagnostic tools." | `conductor/workflow.md` §"Conductor Token Firewalling" |
| "Continuous execution" | The Tier 2 Tech Lead maintains persistent memory (per the same section): "Unlike the stateless sub-agents (Tiers 3 & 4), the Tier 2 Tech Lead does NOT use Context Amnesia during track implementation to ensure continuity of technical strategy." | `conductor/workflow.md` §"Conductor Token Firewalling" |
| "Spec compliance review" | Tier 3 worker's surgical prompt includes "specification" via file:line references + behavior verification; the tier-2 tech-lead reviews the diff before committing (per `conductor/workflow.md` §"Task Workflow" step 9: per-task atomic commits + git notes) | `conductor/workflow.md` §"Task Workflow" |
| "Code quality review" | Tier 4 QA agent dispatched on failure: "If you run a test or command that fails with a significant error or large traceback... DO spawn a stateless Tier 4 agent to diagnose the failure." | `.agents/skills/mma-orchestrator/SKILL.md` §"The Tier 4 QA Agent (Diagnostics)" |
| "Model Selection" | The project's model selection is hierarchical: Tier 1 (gemini-3.1-pro-preview, strategic), Tier 2 (gemini-3-flash-preview, tech-lead), Tier 3 (gemini-2.5-flash-lite, worker), Tier 4 (gemini-2.5-flash-lite, qa). The "least powerful model that can handle each role" rule applies. | `conductor/workflow.md` §"Conductor Token Firewalling" |
| "Implementer Status: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED" | The project's tier-3 worker dispatch is via OpenCode Task tool with `subagent_type: 'tier3-worker'`; the tier-3 worker reports back to the tier-2 orchestrator. The project doesn't have a strict 4-state status enum but the equivalent is the worker's response ("completed successfully" vs "needs context" vs "blocked"). | `conductor/workflow.md` §"Task Workflow" step 5 |
| "Surgical prompt: WHERE/WHAT/HOW/SAFETY/COMMIT" | The project's tier-3 worker dispatch prompt template (per `conductor/workflow.md` §"Task Workflow" step 4 + step 5): "WHERE (file:line range), WHAT (test to create), HOW (which assertions/fixtures to use), and SAFETY (thread constraints if applicable)" | `conductor/workflow.md` §"Task Workflow" steps 4-5 |
| "Pre-Delegation Checkpoint" | `conductor/workflow.md` §"Task Workflow" step 4 + step 5: "Pre-Delegation Checkpoint: Before spawning a worker for dangerous or non-trivial changes, ensure your current progress is staged (git add .) or committed. This prevents losing iterations if a sub-agent incorrectly uses git restore." | `conductor/workflow.md` §"Task Workflow" |
| "Never dispatch multiple implementation subagents in parallel" | The project's tier-2 orchestrator dispatches tier-3 workers one at a time (no parallel worker dispatches); the parallel-execution pattern is for *tasks*, not subagents within a task | Project-wide |
| "Never make subagent read plan file (provide full text)" | The project's tier-3 dispatch prompts include the full task context inline (per `conductor/workflow.md` §"Task Workflow" step 4-5 example prompts) | `conductor/workflow.md` §"Task Workflow" |
| "Subagent follow TDD for each task" | The project's tier-3 worker is required to follow TDD: "Subagents follow TDD naturally" (per the skill) + the project's workflow step 4 ("Write Failing Tests (Red Phase)") is part of every tier-3 dispatch prompt | `conductor/workflow.md` |
| "AST Skeleton & Outline Views" for subagent context | The project's tier-2 uses `manual-slop_py_get_skeleton` and `manual-slop_py_get_code_outline` MCP tools to provide curated context to tier-3 workers (per `.agents/skills/mma-orchestrator/SKILL.md` §"AST Skeleton & Outline Views") | `.agents/skills/mma-orchestrator/SKILL.md` |
| "Repeated failures → upgrade model" | The project's tier-3 dispatch supports `--failure-count` for model escalation: "If a Tier 3 Worker fails multiple times on the same task, it may lack the necessary capability. You must track failures and retry with --failure-count <N> (e.g., --failure-count 2). This tells mma_exec.py to escalate the sub-agent to a more powerful reasoning model" | `.agents/skills/mma-orchestrator/SKILL.md` §"Handling Repeated Failures" |
| "Per-Task Decision Protocol" (architectural vs cosmetic) | `conductor/workflow.md` §"Per-Task Decision Protocol": small decisions decide yourself; large decisions escalate. Maps to the skill's "If the task requires more reasoning, re-dispatch with a more capable model" + "If the plan itself is wrong, escalate to the human" | `conductor/workflow.md` §"Per-Task Decision Protocol" |
### 7.3 Where the project already follows the discipline
- **The 4-tier MMA is a direct implementation of subagent-driven-development.** The Tier 3 Worker is "fresh subagent per task" with surgical prompts. The Tier 4 QA is "two-stage review" (specifically for error analysis, not success claims). The Tier 2 Tech Lead is "persistent memory" (the skill doesn't have this role, but the project uses it for continuity).
- **The "Domain Distinction" (Meta-Tooling vs Application) is a project-specific addition.** Per `conductor/workflow.md` §"Conductor Token Firewalling" §0: "This doc describes META-TOOLING — the AI agent orchestration layer used by Conductor agents to coordinate their own work. It is NOT the Application domain (the manual-slop GUI app being built)." This disambiguates the project's MMA from the application's MMA (in `src/multi_agent_conductor.py`), which is critical because they share a name but operate in different domains.
- **The "Pre-Delegation Checkpoint" is a project-specific rule** that's stricter than the skill's "stage or commit before delegating". The project's rule explicitly calls out the `git restore` failure mode ("git restore destroyed user in-progress src/* edits twice in one session 2026-06-07").
- **The "Repeated failures → upgrade model" rule is explicitly named** (`--failure-count`) and is a project-specific operationalization of the skill's BLOCKED handler.
### 7.4 Where the project doesn't follow the discipline
- **"Two-stage review" — the project's tier-4 QA is for error analysis, not code-quality review.** The skill's "code quality reviewer" subagent reviews the code itself (style, structure, naming); the project's tier-4 QA reviews errors (log summarization, failure root cause). This is ARCH-DIFF: the project uses tier-4 for a narrower purpose.
- **"Continuous execution" — the project DOES pause for user review at phase boundaries.** The skill says "execute all tasks from the plan without stopping"; the project's Phase Completion Verification and Checkpointing Protocol §5 says "PAUSE and await the user's response. Do not proceed without an explicit yes or confirmation from the user to proceed if tests pass." The project is *more* user-interactive than the skill.
- **"Subagent-driven vs executing-plans: same session vs parallel session"** — the project doesn't make this distinction explicitly. Tier 3 workers run in the same session as the orchestrator (via OpenCode Task tool); there is no parallel-session option.
- **"If subagent asks questions: Answer clearly and completely"** — partially followed. The project's tier-3 dispatch prompt is fully specified (WHERE/WHAT/HOW/SAFETY), but if the tier-3 worker asks a clarifying question during execution, the tier-2 may not have a structured response protocol (the project relies on the agent's conversational context).
- **"Never accept 'close enough' on spec compliance"** — partially followed. The project's tier-2 reviews the commit + git note but doesn't have a structured "spec compliance review" subagent.
### 7.5 Recommendations summary
The project follows the subagent-driven-development discipline with significant elaborations (4-tier MMA, Domain Distinction, Pre-Delegation Checkpoint, repeated-failure model escalation). The project's Tier 4 QA is narrower than the skill's "code quality reviewer" but the project compensates with per-task atomic commits + git notes that are reviewed by the user at phase boundaries. The deferred rebuild may want to:
- **MEDIUM:** Consider adding a tier-4b "code quality reviewer" subagent (the skill's two-stage review's second stage) to complement the tier-4 QA (first stage). This would close the ARCH-DIFF gap with the skill.
- **LOW:** Codify the "if subagent asks questions, answer clearly" rule as a tier-2 orchestrator prompt template. Currently this is implicit in the tier-2's behavior.
- **LOW:** Add a "parallel session execution" option for tracks where tasks are highly independent (e.g., research-style tracks like this one). The project has sequential dispatch; the skill offers a parallel option.
**Verdict.**
| Field | Value |
|---|---|
| **Primary** | `PARITY` |
| **Integration tag** | `INTEGRATED` |
| **Section size** | deep-dive |
| **Cross-refs** | nagent_review_20260608 §5 (the durable-work thesis shapes how subagents are dispatched); fable_review_20260617 §3 (the cluster-sub-agent dispatch pattern); intent_dsl_survey_20260612 §6 (MMA is one of the project's "AI-agent properties") |
**Rationale.** The project's 4-tier MMA is a faithful elaboration of subagent-driven-development. Tier 3 workers = fresh subagent per task (skill-compliant); Tier 4 QA = first-stage review (narrower than skill's two-stage); Tier 2 Tech Lead = persistent memory (project elaboration, not in skill); Tier 1 Orchestrator = strategic planning (project elaboration, not in skill). The Pre-Delegation Checkpoint + Domain Distinction + Repeated-failure model escalation are project-specific operationalizations.
**Recommended change.** Consider a tier-4b "code quality reviewer" subagent for the second-stage review; codify the "answer subagent questions" rule as a tier-2 template; consider parallel-session execution for highly independent tracks.
## 8. Executing Plans