Agent Primitive Selection

Distilled from Agent Skills, Agent Subagents, Agent Teams, and the agent-orchestration skill. Answers the question: given a task, which primitive do you reac…

Agent Primitive Selection

Distilled from Agent Skills, Agent Subagents, Agent Teams, and the agent-orchestration skill. Answers the question: given a task, which primitive do you reach for?

Decision Tree

Is the domain knowledge reusable across sessions and fits in prompts?
  → SKILL

Is it a reusable workflow but too complex for a single prompt?
  → SUBAGENT

Does the task pollute main context but results are all that matter?
  → SUBAGENT (foreground)

Can it run concurrently without blocking the main session?
  → SUBAGENT (background)

Do workers need to talk to each other?
  → No:  SUBAGENTS (each reports only to parent)
  → Yes: AGENT TEAM (shared task list + mailbox)

Is work genuinely parallel with non-overlapping file scope?
  → Tasks short (<30 min), ≤5 tasks:  AGENT TEAM (in-process, shared task list)
  → Tasks long (>30 min) or >5 tasks: WORKTREE POOL (isolated checkouts, shared inbox)
      See [[concepts/shared-task-queue]], [[concepts/worktree-isolation]]
  → Otherwise: single session or sequential subagents

Do parallel workers need each other's PARTIAL results mid-task?
  → Can the interface be defined upfront?     → CONTRACT-FIRST (seed before spawning)
  → Is the dependency one-directional?        → PIPELINE (make it sequential)
  → Is the dependency bidirectional/emergent? → FILESYSTEM BLACKBOARD
  See [[concepts/worker-coordination]]

Model Tier Routing

Claude Code (wshobson tier routing)

Model	When to use	Example agents
Opus	Judgment, design, architecture, security audits	design-explorer, architecture-reviewer, security-auditor
Sonnet	Implementation, review, debugging, deployment	code-writer, code-reviewer, backend-debug-tester
Haiku	Fast, repetitive, low-judgment	cmd-executor, code-writer-fast, session-report-generator

Rule: Security and architectural decisions go to Opus. Per wshobson benchmarks, Opus achieves 65% fewer tokens on complex tasks — the higher rate is often offset by not needing correction loops.

Harness > model — scope: this holds in the mid-capability band (Sonnet-class models with structure vs without). At the frontier (Opus on a novel architectural decision), no harness closes the gap. Harness wins for: long-horizon AFK loops, parallel work, verification gates, repeatability. Model wins for: one-shot architectural judgment, novel domain reasoning, security threat modeling — tasks where a single inference’s quality is the bottleneck. Note: DeepSeek max-reasoning unlock is a model parameter win, not a harness win.

OpenCode / multi-provider (majority practice among experienced harness users, r/opencodeCLI 2026-05, n≈30)

Role	Model	Notes
Planning / council / architecture	Opus 4.7, GLM-5.2	Opus for judgment; GLM-5.2 for planning via Go plan
Implementation (AFK loop)	DeepSeek V4 Flash (max reasoning)	Direct API only — resellers strip reasoning effort
Implementation (Go plan)	GLM-5.2	Community: lower hallucination than Kimi K2.6
Fast targeted changes	DeepSeek V4 Flash, Qwen 3.6 Plus	Speed + cost
Adversarial review	DeepSeek V4 Pro, Qwen 3.6 Plus	Different training = different blind spots
UI / frontend	Kimi K2.6, Gemini	Visual reasoning strength
Spec writing	Mimo 2.5 Pro	Community: Opus-comparable for spec tasks

Key insight: DeepSeek V4 Flash on max reasoning = dramatically better than default. Must use direct DeepSeek API — not OpenRouter or resellers. Toggle in OpenCode via ctrl+t.

Opus-as-orchestrator pattern (vietphi, r/opencodeCLI): use Opus to generate a bash script that dynamically dispatches the right model per task, capping expensive models by quota (e.g. GLM at 15%). Moves routing from static env config to agent judgment.

DeepSeek max reasoning — when default beats max: short targeted edits, fast iteration loops, latency-sensitive interactive sessions, simple refactors. Max reasoning multiplies time-to-first-token and destabilizes KV-cache reuse. Use max for genuinely hard reasoning; default for everything else.

Vertical slices — when this fails: layer-internal-complexity-dominant systems (compilers, interpreters, ML training pipelines, cryptographic primitives, database internals); library/SDK work with no UI to slice toward; infrastructure pre-integration phases. Tracer bullets are a web-product-shaped heuristic, not universal.

Skill vs Subagent vs Team — At a Glance

Dimension	Skill	Subagent	Agent Team
Own context window	No (injected into caller)	Yes	Yes (each teammate)
Persists state	No	No (unless writes files)	Via shared task list
Parallel execution	No	With background: true	Yes (inherent)
Inter-worker comms	N/A	None (parent only)	Mailbox
Isolation	No	Optional (isolation: worktree)	Per-teammate scope
Use for	Domain knowledge, checklists	Delegated tasks	Parallel cross-domain work

When NOT to Use a Team

• File scope overlaps between teammates → conflicts, merge pain
• Fewer than 3 independent pieces → subagents or sequential is simpler
• Workers need to coordinate mid-task → star topology breaks down; redesign
• Tight iteration loop with human → team coordination latency kills UX

Unstructured “bags of agents” amplify errors 17.2x. Coordination failures account for 36.9% of all multi-agent failures. See Agent Teams.

Common Workflow Patterns

Sequential (steps depend on each other):

design-explorer → architecture-reviewer → code-writer → code-reviewer → project-health-monitor

Parallel review:

Lead spawns: security-auditor + code-reviewer + visual-verifier
Each owns distinct scope → lead synthesizes findings

Debug with competing hypotheses:

Spawn 3–5 subagents, each with a different theory
Each tries to disprove the others' theory
Surviving theory = actual root cause

Security review loop:

security-auditor (threat report) → code-writer (fix Critical/High) → security-auditor (re-audit)

Multi-vendor adversarial review:

Sonnet implements → Opus reviews (same vendor, different tier — minimum)
Claude implements → Codex reviews (cross-vendor — catches model-family blind spots)
/council: all vendors analyze simultaneously → surface disagreements explicitly

See Multi-Vendor Adversarial Review for when each level is appropriate.

Related Pages

• Agent Skills — skill architecture, loading levels, SKILL.md structure
• Agent Subagents — full frontmatter reference, invocation patterns
• Agent Teams — team architecture, quality gate hooks, known limitations
• Agent Harness — harness components; primitives as building blocks
• Verification Pipeline — verification requirements for each tier of work