# agent design principles

_Status: settled — as of 2026-07-16_
_Connects to: [pipeline-stages](pipeline-stages.md), [deterministic-gates](deterministic-gates.md), [overview](../OVERVIEW.md)_

## 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](pipeline-stages.md)'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)