cc-os/plugins/os-sdlc/reference/agent-design-principles.md

agent design principles

Status: settled — as of 2026-07-16 Connects to: pipeline-stages, deterministic-gates, overview

Purpose

Fixes the shape every os-sdlc agent definition must follow: one job, minimal reads, minimal tools, minimal returns. Load this before writing or reviewing any agents/*.md definition in this plugin.

Design

• One clearly-defined job per agent. It reads only what it needs for that job; it returns the minimum under an explicit return format, so the next stage's context stays clean rather than accumulating everything every prior stage touched.
• Minimal tool allowlists via tools: frontmatter in agents/*.md. The programmer/build agent gets Read/Write/Edit only — no Bash. This is a deliberate [jrs] decision in the vault taxonomy note, stronger than IndyDevDan's "separate invocation" stance: rather than merely running build and test in separate agent invocations, the build agent is architecturally incapable of running tests or shells at all. No WebFetch/MCP/other-plugin tools unless the specific job needs them. Effect observed in DeltaRefinery: agents scoped this tightly were more focused, cheaper per invocation, and faster — the constraint is a feature, not friction.
• Settled facts travel in via the spawn prompt — an agent never "re-reads what the orchestrator already read." The orchestrating stage resolves context once and hands the agent exactly what it needs in the prompt itself.
• Inter-stage state travels via small on-disk handoff artifacts — a file-based analog of DeltaRefinery's in-memory Handoff (intra-level) and DB-persisted Artifact (inter-level). os-sdlc keeps this lightweight (files, not a database) because v1 is a single-session tracer-bullet pipeline, not DeltaRefinery's multi-session resumable system.
• Model tiering: mechanical work → haiku; judgment work → sonnet; hard reasoning → opus. Applied per-agent-definition, not per-pipeline — a test-writer doing mechanical transcription of ticket acceptance criteria into test stubs is a different tier than a reviewer judging spec alignment.

Open questions

• Concrete handoff artifact file format (plain markdown, JSON, frontmatter'd markdown) — not yet chosen.
• Whether DeltaRefinery-style persisted resumability is needed before multi-session pipelines actually exist. Per the standing "don't build ahead of need" convention (see pipeline-stages's tracer-bullet framing), this stays undecided until a real multi-session use case shows up.

Sources

• SecondBrain vault: agentic-sdlc-ai-developer-workflow-taxonomy.md ([jrs] tool-allowlist stance vs. [dan] separate-invocation stance)
• ~/dev/delta-refinery (Handoff/Artifact pattern this generalizes from)
• plugins/os-sdlc/OVERVIEW.md
• 2026-07-16 design session (this doc's origin)