Agentic engineering

Primitive 01 / Agent

A specialist with a hard edge.

An agent is not a personality wrapped around a prompt. It is a bounded unit of judgment with named inputs, a defined output, restricted tools, and an explicit stopping point.

Agent

probabilistic judgment inside a deterministic contract

Choose a highlighted region in the definition to see what it controls.

agents/architect.mdReal contract shape

01 / Definition

The prose shapes judgment. The system enforces the perimeter.

A strong definition is deliberately split. Some parts guide a model’s interpretation; other parts give the orchestrator facts it can verify without asking the model.

Deterministic

Things code should know

  • Which agent to launch
  • Which files must exist first
  • Which tools are permitted
  • The exact output address
  • Whether the output exists
  • How a verdict changes the route

Probabilistic

Things the agent should judge

  • Which existing patterns matter
  • What ambiguity blocks a sound decision
  • Which tradeoff best fits the project
  • Whether evidence supports a finding
  • What uncertainty must be handed forward
  • How completely its contract was satisfied
Key insight

If a responsibility has one correct answer for a given input, move it out of the agent definition and into code.

02 / Contract test

Every agent answers seven questions.

These questions are portable. The answers change by language, framework, and role; the contract shape does not.

  1. 01

    Identity

    What expert is this, and which mental model guides its judgment?

  2. 02

    Input

    Which artifacts, source files, and project context may it read?

  3. 03

    Output

    What exact file or code change must exist when it finishes?

  4. 04

    Tools

    Which capabilities are necessary, and which would widen the blast radius?

  5. 05

    Skills

    Which reusable rules and schemas must be injected into this role?

  6. 06

    Prohibitions

    What must it refuse, report, or hand back to another owner?

  7. 07

    Evidence

    Which decisions, findings, assumptions, and outcomes must it record?

agents/architect.md

Identity

    03 / Runtime topology

    Not every agent should become a subagent.

    Isolation is useful when the work benefits from fresh context, narrower tools, independent judgment, or parallel execution. Interactive continuity is useful when the role must stay in conversation with you.

    Main conversation

    YouIntent + approvals
    OrchestratorState + routing
    DiscoveryInteractive interview

    Bounded subagents

    ArchitectBrief → spec
    EngineerSpecs → code
    ReviewersEvidence → verdicts
    RoadmapIssues + ICP → order
    Fresh context

    Do not inherit the builder’s framing when independent judgment matters.

    Scoped tools

    Give a reviewer enough access to inspect, not enough to silently fix.

    Parallel work

    Launch orthogonal review lenses together and wait at one gate.

    Bounded failure

    A failed specialist can be retried without replaying the entire workflow.

    04 / Handoff

    Agents communicate through durable artifacts.

    The next role receives the contract it needs, not the previous role’s transcript. That makes context construction deliberate and recovery possible.

    DiscoveryUser truth001.01-dis-feature.md
    ArchitectSystem contract001.02-arc-feature.md
    EngineerCode + evidence001.04-eng-feature.md
    ReviewerIndependent verdict001.05-cr-feature.md
    Boundary warning

    Passing the whole conversation feels convenient, but it makes hidden context part of the API and weakens reviewer independence.

    05 / Failure modes

    The most common agent definitions are descriptions, not contracts.

    Vague identityYou are a world-class software expert.
    Bounded identityYou turn an approved brief into a technical specification. You do not implement it.

    Expertise without ownership creates role bleed.

    Vague completionReview the code and report back.
    Verifiable completionWrite {SEQ+1}-cr-feature.md with one of three allowed verdicts.

    A response is not a durable done condition.

    Unbounded capabilitytools: [Read, Write, Edit, Shell, Agent]
    Minimum capabilitytools: [Read, Search, WriteReport]

    Tools should follow the output contract, not convenience.

    06 / Portable template

    Start from a contract, then add domain judgment.

    Copy the shape first. Replace the example identity, skills, inputs, process, and evidence rules with your own language-specific decisions.

    agents/<role>.mdPortable skeleton
    ---
name: <role>
model: <model-class>
tools: [<minimum capabilities>]
skills: [<reusable policies>]
---

# <Role>

## Identity
You own <one kind of judgment>.

## Inputs
- <required upstream artifact>
- <approved project context>

## Process
1. <inspect>
2. <decide>
3. <record evidence>

## Output
Write <exact artifact address>.

## Cannot
- <neighbor role's responsibility>
- <unsafe or conflicting action>

## Handoff
Name assumptions, uncertainty, and
what the next role should verify.