vc-agent-strategy-compare

name: vc-agent-strategy-compare description: "Evaluate 4 execution strategies (sequential, parallel-subagents, workflow, agent-team) for a phase or fan-out task. Outputs 7-signal score table, agent count math, cost guards, and strategy recommendation." argument-hint: "[phase context description or fan-out task description]" trigger_keywords: execution strategy, parallel agents, strategy comparison, agent count, fan-out recommendation layer: contract metadata: author: vibecode-pro-max-kit version: "1.2.0"

vc-agent-strategy-compare

Output style: Follow process/development-protocols/communication-standards.md — answer-first, plain language, no unexplained jargon, TL;DR on long responses.

Evaluate 4 execution strategies for any RIPER-5 phase or fan-out task. Computes the 7-signal score, shows explicit agent count math, applies cost guards, and outputs a ranked strategy recommendation.

All strategies use the existing vc-system agents and skills. The question is only how they are orchestrated.

Model Selection Policy

Every spawned agent — across ALL four strategies (sequential, parallel subagents, dynamic workflow, agent team) — defaults to sonnet. Spawn opus ONLY when the agent is carrying out real source-code or build execution (writing/editing code, running builds, applying migrations). Planning, research, analysis, validation, review, and synthesis all run on sonnet.

Concrete rules:

• Default = sonnet for any teammate, parallel subagent, or agent() call in a workflow. State the model explicitly when spawning.
• opus ONLY for execution work: the agent that actually implements code (the vc-execute-agent leg, or a workflow agent() step whose job is to modify source / run a build). The RIPER-5 phase that runs on opus is EXECUTE; all other phases (RESEARCH, SPEC, INNOVATE, PLAN, VALIDATE, UPDATE PROCESS) run on sonnet.
• Agent-team members: assign sonnet to reviewers, researchers, validators, and planners; assign opus only to the teammate doing real code execution.
• Dynamic workflows: pass model: 'sonnet' on agent() calls by default; pass model: 'opus' only on the execution stage that writes code or runs builds.
• Parallel subagents: fan-out investigation/review subagents are sonnet; only an implementing subagent is opus.

Rationale: opus is reserved for the one place judgment-under-execution materially changes code quality. Everything upstream is sonnet-cheap without quality loss, and this keeps fan-outs (which multiply agent count) on the cost-efficient tier. This mirrors the live agent frontmatter: vc-execute-agent, vc-fast-mode-agent, and vc-quick-fix-agent are opus; every other vc-agent is sonnet.

Mode Selection

This skill runs in one of two modes. Choose based on context availability and decision stakes.

Simple Mode (default)

Score the 7 signals from information already present in the conversation context. No additional file scanning.

Use Simple Mode when:

• File count and blast radius are already clear from the current plan or research summary
• Test infrastructure status is already mentioned or irrelevant
• The strategy decision is not gating a phase program kickoff
• No signal is ambiguous given current context

Output format: Signal 3: +1 (estimated 5-10 files)

Deep Mode

Run targeted codebase scans BEFORE scoring signals, then score each signal with concrete evidence.

Trigger conditions — any one is sufficient:

• Signal 3 (file count / directions) cannot be accurately determined from context alone
• Signal 5 (test infra maturity) is unknown — no test files have been mentioned yet
• The strategy recommendation will gate a phase program kickoff (high-stakes decision)
• Caller explicitly requests deep mode (e.g. "run deep mode", "scan first")

Scans to run before scoring:

Signal 3 scan — count actual touchpoint files:

find . -path '*/active/*' -name '*.md' | head -5
grep -A 30 "Touchpoints" [plan path] | grep -E "^\s*-"

Signal 5 scan — assess test infra maturity:

# Check if local test script exists
grep -l "test:local" packages/*/package.json apps/*/package.json 2>/dev/null | head -5
# Count test files in blast radius directories
find [blast-radius-dirs] -name '*.test.ts' -o -name '*.spec.ts' 2>/dev/null | wc -l
# Check validate-contract for tier assignments
grep -A 5 "tier:" [plan path] | head -20

Signal 6 scan — find independent phases for parallelization:

grep -A 5 "Phase Ordering\|phase.*depend" [umbrella plan path] | head -20

Signal 7 scan — check prior parallel execution outcomes:

find process/features/[feature]/active/ process/features/[feature]/completed/ -name '*_REPORT_*' 2>/dev/null | grep -i "parallel\|execute" | head -5

After scanning, score each affected signal with concrete evidence: Signal 3: +1 (14 files confirmed via Touchpoints scan: packages/api/src/router/billing.ts, apps/web/src/components/billing/*, ...)

When To Invoke

Invoke this skill at these five RIPER-5 checkpoints:

1. RESEARCH — when 2+ distinct investigation directions are identified before fanning out (Checkpoint 1: Research Fan-Out)
2. INNOVATE — after 2-3 approaches are surfaced and before the Decision Summary is locked (Checkpoint 2: Innovate Fan-Out)
3. PLAN — when 3+ phase plans will be created (phase program detected; Checkpoint 4: Phase-Program Validation Fan-Out)
4. VALIDATE — at V4 (Validate Menu) — always runs as part of the mandatory VALIDATE sequence
5. UPDATE PROCESS — when post-execute review involves multiple dimensions simultaneously (Checkpoint 5: Post-Execute Review Fan-Out)

Phase-END Invocation Rule

Invoke at the END of each RIPER-5 phase to recommend the execution strategy for the NEXT phase. The skill receives the current phase's output as context and produces a strategy recommendation that the orchestrator carries into the next phase handoff.

Fan-Out-Level Invocation Rule

When any agent is about to spawn multiple parallel subagents for work WITHIN the current phase, invoke vc-agent-strategy-compare FIRST to determine the execution method.

• Input context: describe the specific fan-out task (not the whole phase). Example: "run feasibility checks on 5 phase plans" or "review 3 independent API surface changes."
• Output: Workflow / Parallel-subagents / Agent team / Sequential recommendation for THIS fan-out only.
• This prevents defaulting to parallel subagents for tasks that are better served by a deterministic workflow or a single sequential agent.

Orchestrator Pre-Spawn Rule

Before any multi-file edit begins, the orchestrator surfaces a strategy recommendation from this skill and waits for user confirmation before spawning vc-execute-agent. This is not optional for non-trivial plans (blast radius ≥ 3 files or any high-risk class present).

7-Signal Scoring Table

Count how many signals are present. Each signal counts as 1. Use the score to select a strategy threshold.

Seven Signals

Total score: [0–7]

Threshold Table

Auto-skip rule: single-file or trivial changes always use sequential regardless of score. Do not mention other strategies for trivial changes.

Fit note: the right strategy is the one that fits the work — not the highest tier. Sequential is correct for trivial changes. Workflow is correct for deterministic pipelines and full RIPER-5 automation. Agent team is correct only when 2+ specialists need to coordinate mid-execution.

Strategy Options Table

ALL 4 strategies must always be evaluated and presented. Never omit one.

Cost Guard Rules

• >30 agents total: show the full breakdown (strategy × count math) so the user can judge before proceeding.
• >100 agents total: show breakdown AND ask for explicit confirmation before spawning.
• >6 team members (vc-team only): show each member's role and ask for explicit confirmation.

Note: V5 "Accept" in the VALIDATE sequence satisfies both the cost-guard confirmation and the plan-approval confirmation in one gate. The cost guard is surfaced at V4 (Validate Menu) so the user sees it before deciding at V5. No separate yes/no prompt is required for the cost guard alone.

Recommendation Output

After computing the score and filling the table, output a single recommendation block. Use plain English labels alongside technical ones so readers unfamiliar with the system can follow along.

Score: [N]/7 — signals: [list present signal IDs]
Recommended strategy: [Sequential (one agent at a time) | Parallel subagents (independent work, no coordination) | Workflow (automated pipeline) | Agent team (specialists coordinating live)]
Agent count: [explicit math per row above]
Model: [sonnet for all spawned agents; opus ONLY for the code-execution leg — see §Model Selection Policy]
Cost guard: [triggered / not triggered]
Rationale: [one sentence on dominant signal and why this strategy fits]

Strategy-by-Fit Rules

Use these rules to select and justify the recommendation — not the threshold table alone:

• Sequential: right for trivial or single-file changes; right for /goal phase-program execution where each phase clearly depends on the previous. Hard limit: single context window per phase. Each vc-agent (vc-research-agent, vc-plan-agent, etc.) runs one at a time; orchestrator hands off between them.
• Parallel subagents: right when there are 5+ independent items in different file domains with no mid-task communication needed. Each spawned agent uses the same vc-system agents and skills but works on a scoped slice. Orchestrator must stay clean (parent context must not accumulate all output). Time savings: 50–70%. Cost: approximately N× linear token multiplier.
• Workflow: right for deterministic pipelines (full RIPER-5 automation, TDD loop, metric iteration, quality gate sequences), tasks too big for a single context window, or when the item count is unknown upfront. The workflow script calls vc-system agents as agent() calls in pipeline() or parallel() steps. Quality > cost priority. Up to 1000 agents, 16 concurrent. Total tokens roughly the same as sequential — most cost-effective for large volume.
• Agent team: right when 2+ specialist workstreams must share findings mid-execution (not just consume the same input), when named roles are known upfront (e.g. security reviewer + implementer + tester coordinating live), or when an adversarial challenge pattern is required. Uses Claude Code TeamCreate + TaskCreate + SendMessage. Each teammate runs its own vc-agent and skills. NOT for simple fan-out where agents work independently — use parallel subagents for that. Mechanism: a team shares a TaskList and uses SendMessage to coordinate mid-run; parallel subagents have NO inter-agent channel and CANNOT coordinate — so any task that needs mid-execution coordination (e.g. blast-radius non-overlap across phase plans) MUST be agent-team, never parallel subagents.

Phase Program Rule

When a plan describes a program with 3+ phases (phase program classification, signal S4 present):

• Sequential is NEVER valid for plan creation fan-out OR validate fan-out across the phases.
• 3+ phase-plan CREATION default: AGENT TEAM. Phase plans share files (CLAUDE.md, agent .md files) and MUST coordinate blast-radius non-overlap + dependency declarations — only an agent team can do this (TeamCreate + shared TaskList + SendMessage). Fire-and-forget subagents cannot communicate, so they cannot keep blast radii disjoint and are the WRONG strategy for plan creation. (Outer-PVL VALIDATE fan-out across already-written phase plans, where each validator reads one finished plan with no cross-talk, MAY use independent read-only subagents — see the reconciliation note below.)
• Reconciliation (CREATION vs read-only VALIDATE fan-out): validating N already-written plans needs no inter-agent talk, so bare parallel subagents are valid there; plan CREATION needs cross-talk, so it is agent-team. Note orchestration.md even describes Outer PVL as an agent-team — prefer agent-team for both and reserve bare parallel subagents only for truly independent read-only fan-out.
• If phases have complex interdependencies requiring mid-draft communication (e.g., phase 2 plan depends on design decisions surfaced during phase 1 planning): use agent team instead. Assign one teammate per phase, use SendMessage for cross-phase coordination.
• If the total phase count is unknown upfront (e.g., the program scope is discovered incrementally): use workflow so the pipeline can expand without re-spawning the orchestrator. Each agent() call in the workflow runs the appropriate vc-agent for that phase.

Strategy Reference

1 — Sequential (one vc-agent at a time)

The orchestrator runs one vc-agent, waits for it to complete, then routes to the next.

orchestrator → vc-research-agent → (result) → vc-innovate-agent → (result) → vc-plan-agent → ...

• Each agent invokes its own skills (vc-scout, vc-docs-seeker, vc-sequential-thinking, etc.) independently.
• Simplest option. No fan-out overhead. Single context window per phase.
• Hard limit: cannot parallelize. If a phase has 5 independent sections, all 5 run back-to-back.
• Best for: standard single-feature RIPER-5 runs, /goal phase-program execution, trivial fixes delegated directly to vc-execute-agent.

2 — Parallel Subagents (one agent per direction)

The orchestrator spawns multiple vc-agents simultaneously via the Agent tool. Each agent goes in one direction independently, invokes its own skills, and returns a result. The orchestrator merges all results before proceeding.

orchestrator ──► vc-research-agent (direction A)
             ──► vc-research-agent (direction B)   (all run simultaneously)
             ──► vc-research-agent (direction C)
             └── merge all results → route to vc-innovate-agent

• Parent context must stay clean — pass only scoped input to each agent; collect structured output.
• Time savings: 50–70% vs sequential for the fan-out step. Cost: approximately N× token multiplier.
• NOT appropriate when one agent's findings should influence another agent mid-run — use agent team for that.
• Best for: parallel RESEARCH across 5+ distinct codebase areas; parallel VALIDATE across 5+ phase plans; parallel dimension checks in PLAN.

3 — Dynamic Workflow (full RIPER-5 pipeline)

A deterministic Workflow script orchestrates the vc-system agents as programmatic steps. Each agent() call in the script corresponds to a vc-agent running its phase. pipeline() handles per-item fan-out without a barrier. parallel() handles all-results-needed barriers.

workflow script
  phase('Research')   → agent('run vc-research-agent for feature X', {agentType: 'vc-research-agent'})
  phase('Plan')       → pipeline(items, item => agent('write phase plan for ' + item))
  phase('Validate')   → parallel(plans.map(p => () => agent('validate plan ' + p)))
  phase('Execute')    → agent('run vc-execute-agent for plan path', {agentType: 'vc-execute-agent'})

• Supports loop-until-dry, budget-aware iteration, and unknown item counts.
• Each agent() call runs the appropriate vc-system agent and its skills.
• Up to 1000 agents / 16 concurrent. Total tokens roughly equal to sequential — work is distributed.
• Best for: full RIPER-5 automation across many items, TDD fan-out loops, lint/test sweeps, phase-program pipelines where count is unknown upfront.

4 — Agent Team (multiple specialist teammates)

Claude Code's built-in TeamCreate feature provisions named teammates. Each teammate is assigned a specialized role via TaskCreate. Teammates communicate via SendMessage. TaskList tracks in-flight work.

TeamCreate("security-review") → teammate A: runs vc-validate-agent (security dimension)
TeamCreate("implementation")  → teammate B: runs vc-execute-agent (implements)
TeamCreate("test-coverage")   → teammate C: runs vc-tester (writes/runs tests)
SendMessage: A → B (security findings mid-implementation, not after)

• Each teammate runs its own vc-agent (vc-research-agent, vc-plan-agent, vc-execute-agent, vc-tester, vc-debugger, etc.) and invokes the relevant skills for their specialty.
• Named roles known upfront. Mid-execution coordination via SendMessage.
• Highest cost — all teammates are active simultaneously.
• NOT appropriate for simple fan-out where agents work independently — use parallel subagents for that.
• Best for: security reviewer + implementer + tester coordinating live; adversarial plan challenge (one agent proposes, another attacks); multi-specialist investigation where findings from specialist A must reach specialist B before B finalizes.

Source References

• process/development-protocols/orchestration.md — Two-Tier Fan-Out Escalation, Parallel Fan-Out Checkpoints
• process/development-protocols/orchestration.md §VALIDATE Gate — skip conditions, gate verdicts, BLOCKED escalation path