Contents
- 01The Builder's Starting Line
- 02Your Computer, Explained
- 03How Software Fits Together
- 04Start With the Work
- 05Build Your First Useful Tool
- 06Make Changes Safely
- 07Prompts Are Specifications
- 08Models Are Components
- 09Give Agents Jobs, Not Vibes
- 10Tools, APIs, and the Harness
- 11Truth Before Intelligence
- 12Patterns for Real Systems
- 13Approval Is a Feature
- 14Receipts or It Didn’t Happen
- 15Operate and Debug the Loop
- 16Design Your Own OS
- 17Make It Ready for Real Life
- 18Build and Evolve Your OS
Patterns for Real Systems
Choose an execution shape that matches uncertainty, consequence, and ownership.
Plan, build, review
Separate understanding from implementation when the work is consequential or broad. The planning stage researches the environment, resolves assumptions, chooses an approach, and writes acceptance criteria. The build stage executes that bounded plan. The review stage compares the artifact and behavior against the plan and the real user outcome.
Review upstream thinking more intensely than generated volume. A flawed plan can produce thousands of internally consistent lines that solve the wrong problem. Check research, domain assumptions, architecture, scope, risk, and proof before implementation makes them expensive.
“A pattern is useful when it makes control flow, failure, and accountability easier to see.”
Observe before the next action
In an observe-and-act loop, the worker chooses one bounded action, receives an environmental result, updates task state, and decides what to do next. This is useful when the path cannot be known in advance: researching an unfamiliar issue, diagnosing a failing system, or navigating a changing external interface.
The loop needs stopping conditions, action budgets, error categories, and protection against repeating the same failed move. Tool output is evidence, not a command. Persist enough state that a retry or human handoff does not restart the investigation from zero.
Orchestrator and specialists
An orchestrator retains the objective and delegates bounded work to specialists. It is valuable when tasks require different tools or forms of expertise but one owner must reconcile the results. Specialists can run sequentially, in parallel where independent, or on demand as tools.
The orchestrator should not merely relay prose. Give each specialist a typed input and return artifact, establish context boundaries, and define who integrates conflicts. Use a direct function or one worker when specialization does not improve quality enough to repay coordination cost.
Case file
orchestrating employee onboarding
A growing company onboards employees through email, a checklist, and several systems. People Operations understands the full outcome, but payroll, IT, security, facilities, and the hiring manager each own different actions and evidence.
A single all-powerful agent would need broad access to sensitive records, identity systems, devices, money, and physical facilities. Instead, one orchestrator holds the onboarding objective and state. It delegates typed tasks to bounded workers or existing automations. Each returns completion evidence or a structured blocker.
The employee and manager see one coherent status. Compensation and privileged access remain human-approved. The orchestrator closes the workflow only when all required receipts match the person, role, location, start date, and policy version.
Decisions made
- 01Keep one onboarding identity and task graph across departmental systems.
- 02Delegate by authority boundary rather than asking one agent to own everything.
- 03Run independent preparation in parallel but preserve dependency order for side effects.
- 04Require human decisions for compensation, exceptions, and privileged access.
The orchestrator pattern creates one experience without centralizing every credential or erasing the accountability of specialist owners.
Bounded autonomous loops
A repeat-until-done loop can help when progress is objectively measurable: fix failing tests, process a known queue, reconcile records, or search until specified evidence is found. The loop should carry a stable objective, current state, remaining work, budget, and a validator that can end it.
Never use ‘keep going until it works’ as the only control. Add maximum turns, cost and time limits, duplicate-action detection, escalating retry policy, a no-progress condition, and a safe terminal state. Autonomy is a loop with rails, not permission to wander.
Progressive disclosure and expert skills
Do not load every instruction, tool, and document at startup. Begin with the task and a small capability index. Reveal specialized guidance, examples, schemas, or tools only when the current state requires them. This preserves attention and reduces accidental authority.
Recurring expert work can become a versioned skill: instructions, references, templates, scripts, and evaluation cases packaged together. Let corrections improve the skill, but require review before a worker rewrites the rules that govern its own behavior.
Human in the loop—and on the loop
A person can participate inside the workflow by approving a specific action, resolving ambiguity, or handling an exception. A person can also supervise the loop from above by setting policy, reviewing metrics, examining failures, and deciding which action classes have earned more autonomy.
Do not convert human accountability into rubber-stamp clicking. Present the smallest meaningful decision with relevant evidence and recovery. Improve the workflow when approvals are routinely accepted, routinely revised, or asking the wrong person.
Swarms require a task graph
An expert swarm is appropriate when several independent analyses or work packages can create real coverage, disagreement is useful, and synthesis has an owner. Examples include research across distinct domains, parallel evaluation of alternatives, or implementation across isolated packages.
Production collaboration needs a task graph, ownership, shared identifiers, dependency state, budgets, cancellation, conflict policy, and integration verification. More agents increase the number of interfaces and possible partial failures. Treat swarm size as a cost to justify, not a maturity badge.
Choose by uncertainty and consequence
Use deterministic code for stable rules, a single model call for bounded semantic transformation, an observe-and-act loop for adaptive exploration, an orchestrator for genuine specialization, and a human gate where consequences require accountability. Combine patterns only when each boundary remains legible.
The best architecture often begins as a simple workflow and earns agentic freedom at one uncertain seam. Start where the environment can supply feedback and the outcome can be evaluated. Complexity should follow measured failure, not anticipation of scale.
Across the business
What this looks like in other departments
The engineering principle stays the same; the workflow, risk, and proof change with the domain.
People & HR
Onboarding orchestration
An orchestrator coordinates payroll, IT, facilities, policy, and manager tasks while each owner returns state and a person approves access or compensation consequences.
Customer support
Observe-and-resolve
The worker inspects the case, queries account state, proposes one action, observes the result, and stops or escalates according to evidence.
Marketing
Plan-build-review campaign
Research and approve the brief first, produce bounded assets second, then review claims, brand, rights, links, audience, and live publication.
Operations
Bounded exception loops
Work a known queue until every item is resolved, escalated, or blocked with an owner—under time, action, and no-progress limits.
Technical deep dive
The pattern selection matrix
Choose execution topology from the structure of the work instead of beginning with the number of agents.
- 01MeasureAssess path uncertainty, task coupling, evaluation clarity, consequence, time horizon, and the number of genuinely different capabilities required.
- 02MinimizeSelect the least complex topology that can complete the loop: rule, call, pipeline, adaptive loop, orchestrator, or supervised swarm.
- 03ContractDefine state, ownership, inputs, outputs, authority, budgets, stopping conditions, and integration evidence at every boundary.
- 04SimulateWalk normal, failure, timeout, cancellation, disagreement, and human-interruption cases before increasing concurrency or autonomy.
- 05GraduateUse traces and evals to expand one dimension at a time: duration, tool access, parallelism, or action authority.
Reference schema
work.shape: uncertainty + coupling + consequence + horizon topology: rule | call | pipeline | loop | orchestrator | swarm node: owner + input + output + authority + budget edge: dependency + artifact + validation + failure policy control: stop + cancel + retry + escalate + approve integration: canonical artifact + conflict resolution + proof graduation: evidence + new autonomy dimension + rollback
Try it yourself
Choose the simplest useful pattern
Take one workflow and compare a deterministic pipeline, a single adaptive agent, and an orchestrated multi-worker design.
- 1Mark which steps are predictable and which require environmental feedback.
- 2Identify capability and authority boundaries that justify specialization.
- 3Estimate coordination, evaluation, and recovery cost for each topology.
- 4Choose the smallest pattern and write the evidence required to outgrow it.
Reusable artifact
Execution topology record
A decision record for how work flows through people, code, and agents.
Workflow: [outcome and consequence] Uncertainty: [known path vs adaptive search] Topology: [rule / call / pipeline / loop / orchestrator / swarm] Nodes: [owners, contracts, authority] Edges: [artifacts, dependencies, validation] Controls: [budget, stop, retry, approval, cancellation] Integration: [owner and final proof]
Before you move on
Receipt checklist
- The topology follows uncertainty and ownership rather than fashion.
- Every worker boundary has a typed artifact and validation rule.
- Loops have budgets, no-progress detection, and safe terminal states.
- Parallel work has explicit integration and cancellation behavior.
Primary sources
