53 lines
2.9 KiB
Markdown
53 lines
2.9 KiB
Markdown
|
# 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)
|