Agent Team

Purpose-built roles. Structured handoffs. Clean context.

Why named agents

  • Each agent has a narrow job and a clean context
  • Specialization produces sharper output than one generalist doing everything
  • Isolated worktrees mean their noise never touches your main session
  • The protocol picks the right agent for the task so you usually don't have to
Think of named agents as a small team of specialists you can dispatch. The main thread is the manager, not the do-er.

The team (1/2)

investigator
Maps unfamiliar code. Traces data flow and blast radius before you change anything.
Default Tier: 1
debugger
Root cause analysis. Given a failure, returns a diagnosis and fix brief.
Default Tier: 2
orchestration-planner
Picks the team. Given a goal, produces a structured execution plan.
Default Tier: 1
product-discovery
Facilitated discovery before architecture. Frames the problem, names personas, runs an attributed market scan, stages a proposed vision + requirements.
Default Tier: 2
architect
Pre-implementation design. Reads the codebase and returns a structured technical plan.
Default Tier: 2
engineer
Implements the change. Reads conventions, writes code, writes module manifests, adds regression tests for Critical/Major fixes, runs quality gates.
Default Tier: 2
skeptic
Adversarial reviewer. Classifies findings Critical / Major / Minor. Checks module manifests and regression tests.
Default Tier: 2
qa-engineer
Browser verification. Fires on UI-visible diffs after Skeptic sign-off.
Default Tier: 1

The team (2/2)

security-auditor
OWASP-structured review. Auth, secrets, injection, privilege escalation.
Default Tier: 3
adr-generator
Writes decision records. Captures the why behind architectural choices.
Default Tier: 2
adr-drift-detector
Audits codebase compliance against Architecture Decision Records.
Default Tier: 1
perf-analyst
Profiles CPU, memory, and latency hotspots. Returns a measured findings brief; does not implement fixes.
Default Tier: 2
release-orchestrator
End-to-end release sequencing. Pre-flight gates, version bump, tag, deploy, post-deploy verification.
Default Tier: 2
dependency-auditor
Supply-chain review. CVE scanning, license compliance, lockfile analysis across all ecosystems.
Default Tier: 1
learning-extractor
Per-ticket learning extraction at Phase 6 clean exit. Reads resolved findings_log and writes fix-pattern entries to .agentic/learnings.md.
Default Tier: 1
wrap-ticket
Per-ticket learnings capture at Phase 11b (PR open). Appends durable learnings to MEMORY.md, decisions.md, and .agentic/context.md.
Default Tier: 1
learnings-agent
Session-scoped background learnings capture. Receives learning events in real-time and writes structured entries to .agentic/learnings.md immediately.
Default Tier: 1
goal-condition-evaluator
Cheap per-turn stop-condition check for open-goal loops. Gates continuation only, never correctness/safety.
Default Tier: 1

How they work alone

  • Spawned into their own isolated worktree - their own files, their own context
  • Given a structured brief - goal, constraints, acceptance criteria, non-goals
  • Do their narrow job and return a structured result - not raw transcript
  • Most agents are read-only analysis/planning. engineer, adr-generator, release-orchestrator, learning-extractor, learnings-agent, and wrap-ticket write files.
The main thread never sees their raw work - only their conclusion. That's the whole point: heavy work without heavy context.

How they work together - standard feature

architect (plan)
    v
skeptic (plan review)       <- sign-off required
    v
engineer (implement)
    v
skeptic (code review)       <- sign-off required
    v
qa-engineer (verify)        <- conditional: UI-visible diff
    v
done

Plans get reviewed before code. Code gets reviewed before QA. Each stage hands off a structured artifact.

The Skeptic agent is special

  • Always a fresh spawn. Never resumed, never continued from a prior round.
  • A resumed Skeptic has seen its own previous criticism - it gets polite and misses things.
  • Fresh context = adversarial teeth.
  • Classifies findings Critical / Major / Minor. Critical blocks sign-off. Major blocks sign-off until resolved.
  • Two new obligations: (1) tiered manifest enforcement on non-trivial files (missing = Minor, stale = Major, stale-on-correctness/security path = Critical); (2) verifies regression tests exist for any Critical/Major fix before granting sign-off.
  • Domain fit comes from the adversarial brief, not the agent. The conductor writes a brief tailored to the change - auth flow, migration, perf regression - and the Skeptic reviews through that lens.
The Skeptic brings the teeth. The adversarial brief aims them - at auth, at a migration, at a perf regression - so a generic reviewer produces domain-sharp findings.

The planner's planner

  • orchestration-planner is a meta-agent - it plans which other agents to spawn and in what order
  • Given a goal, it returns: agent roster, phased execution plan, Skeptic checkpoints, parallelization map, open questions
  • Each unit in the JSONL output carries a skeptic_strategy: "per-unit" (independent units, parallel Skeptics), "integration" (shared interface, one combined-diff Skeptic), or "multi-dimensional" (high-stakes: correctness-Skeptic + security-auditor + perf-analyst in parallel on the same diff)
  • It does not implement anything - planning only
  • Output is a structured plan the conductor follows directly
Default step: after an architect plan clears Skeptic review, run the orchestration-planner before spawning any workers on a multi-unit plan. See the Orchestration Planner deck for the full protocol.

Conditional gates and composed flows

Bug or broken test

debugger (diagnose)
    v
engineer (fix)
    v
skeptic (review)
    v
done

If debugger confidence is Low, escalate to the human - don't fix blind.

Security-sensitive change

architect -> skeptic
    v
engineer -> skeptic
    v
security-auditor
    v
qa-engineer (if UI)
    v
done

Auth, payments, secrets, user data all route through the auditor.

When to invoke manually vs let the protocol choose

Let the protocol choose (default)

  • You describe the goal in plain English
  • Risk classification + orchestration-planner picks the right team
  • This is the 90% case

Invoke manually

  • You need a specific second opinion ("have the security-auditor look at this")
  • You want to force a Skeptic pass on recent changes: /ds-skeptic
  • You want architecture first: ask for the architect explicitly
Manual invocation is an override, not the default interface. Trust the protocol first.

A team of specialists. One manager.

Named agents do the work. You review the output and decide.

github.com/Space-Dinosaurs/DinoStack