From Coding Agents to Engineering Systems

Coding agents are privileged processes.

A coding agent can read a repository, change files, run commands, call external tools, and preserve information after the conversation ends. I had been thinking about those capabilities as conveniences. Building this system pushed me toward a stricter model: the agent is a privileged process, and its authority should be explicit.

That model changes the design questions. Who owns the user's intent? Which role may mutate the repository? Who checks the result? Who can challenge an implementation? What may survive into another session? What evidence is required before completion? A stack of product names does not answer any of them.

I started from Cursor's published work on planners, workers, self-coordination, and recursive planning.^[1] I could not inspect their internal system or reproduce its scale. I wanted a smaller system I could run on one machine, open up, and watch fail. That led to a capability architecture whose components are defined by authority rather than by vendor.

Replacing a model, coding tool, memory service, or orchestrator should replace an adapter. The authority contracts should survive.

This version shows that a role-based system can complete one small task while still violating one of its own role constraints. It contains no comparison with a single strong agent. That gap between the declared system and the executed system now drives the role-conformance work in V0.2.

Twelve principles with different levels of evidence.

I wrote these principles as design constraints for the system. They did not all come from the eval. Several borrow familiar ideas from security and software engineering: one owner for intent, separation of duties, least privilege, explicit identity, and acceptance backed by evidence. The recorded runs reinforced some of them. Two remain largely untested hypotheses. Keeping those categories separate prevents a single successful test command from carrying claims it cannot support.

Constraints I brought into V0.1

These shaped the implementation before the validated run began. V0.1 exercised parts of them, but it was too small to establish that they are sufficient or optimally drawn.

Constraints reinforced by the recorded behavior

The validated end-to-end run reinforced boundaries around workers, verification, project identity, policy, and lineage. The earlier dry run reinforced the need to report reduced assurance when a provider disappears. Each finding later in the note names its run.

Open hypotheses

V0.1 did not test parallel mutation in isolated workspaces. It also did not place a known defect in front of the challenger or compare different reviewer models. These principles describe the intended boundary and the next questions. The results have yet to be earned.

I expect the authority and evidence principles to travel better than the current choices about model size, routing, or recursion depth. That expectation is still a design judgment. The roadmap includes the comparisons needed to test it.

Architecture: roles are authority boundaries.

flowchart TD
    H[Human / Goal Owner] --> R[Root Planner]
    R -->|complex scope| P[Subplanner]
    R -->|bounded task| W[Implementation Worker]
    P --> W
    R --> V[Authoritative Verifier]
    R -->|independent review| C[Challenger]
    R <--> M[(Durable Memory)]
    W --> G[(Repository)]
    V --> G
            

A box in this graph names an authority boundary. It does not require a separate agent, model, operating-system process, or machine. One runtime actor may hold more than one logical role if the acceptance and mutation boundaries remain visible. A deployment may also split one role across several actors.

V0.1 makes that distinction concrete. The root planner also performed authoritative verification with Git, PowerShell, and the project's tests. There was no separate verifier agent. I still model verification as its own role because the worker could not grant final acceptance, and the root had to switch from planning authority to an evidence-producing verification step.

Planner

The root planner owns intent, decomposition, routing, integration decisions, final acceptance, and the durable-memory lifecycle. A subplanner owns only the bounded domain delegated to it. It can decompose that domain and report upward, but it cannot accept the full objective or take over global memory. The subplanner is a narrower planner role and never becomes another root.

Worker

The worker owns one bounded implementation. It may inspect and modify the repository within its permissions and run local checks the environment allows. Its report should name the changes, checks, discoveries, and unresolved issues. That report informs acceptance; it cannot declare acceptance.

Verifier

The verifier owns acceptance evidence: diff inspection, tests, builds, linting, static analysis, and checks for unrelated changes as the task requires. Independence here means authority over the acceptance decision. V0.1 assigned that authority to the root rather than creating another runtime actor.

Challenger

The challenger follows a separate review path and looks for correctness defects, requirement gaps, edge cases, and unnecessary changes. It should report and stop. If the challenger edits the work under review, it becomes another implementer and needs a new review. My current adapter uses Codex to introduce model and provider diversity. That is a design choice. V0.1 did not measure whether diversity improves defect detection.

Memory

Memory preserves project knowledge that should outlive a conversation: decisions, conventions, non-obvious discoveries, and reusable lessons. Runtime scheduling, worker status, locks, and temporary todos remain in the coordination layer. The separation reduces the chance that stale progress is recalled later as current state.

flowchart TD
    A[Understand] --> B[Plan]
    B --> C[Delegate]
    C --> D[Implement]
    D --> E[Verify]
    E -->|failed| F[Rework]
    F --> C
    E -->|passed| G[Challenge]
    G -->|defect| F
    G -->|accepted| H[Remember]
    H --> I[Complete]
            

The control loop also describes logical stages. A runtime may combine stages in one process, as V0.1 did for planning and verification. The trace still needs to show which authority was active and what evidence moved the task forward.

Reference implementation: the adapters I use today.

The architecture above can be implemented by many stacks. This is the one I run today. DSH supplies orchestration and scoped tools. Claude Opus 5 fills the root planner role, Claude Sonnet 5 the subplanner role, Claude Code the worker role, Codex the challenger role, and Engram the memory role. The root also fills the verifier role with Git, PowerShell, and project tests.

I made the model assignments as design decisions. I chose a larger reasoning budget for the root, a lower-cost planner for bounded decomposition, and a different provider for challenge. The records do not show that Opus repays its cost, that Sonnet is sufficient for harder decomposition, or that Codex fails differently enough to catch more defects. V0.6 is where those routing assumptions become experiments.

I expect these adapters to change. Replacing Claude Code with another repository worker should leave worker authority unchanged, and replacing Engram should leave the memory boundary unchanged. A separate verifier process could take over the evidence step without changing what verification owns.

Portable contract

roles:
  root_planner:
    owns: [intent, decomposition, routing, acceptance, durable_memory]
    mutates_code: false

  subplanner:
    owns: [bounded_domain, decomposition]
    mutates_code: false

  worker:
    owns: [bounded_implementation]
    final_acceptance: false

  verifier:
    owns: [acceptance_evidence]
    trusts_worker_claims: false

  challenger:
    owns: [independent_review]
    mutates_reviewed_work: false

memory:
  stores: [decisions, conventions, discoveries, reusable_lessons]
  never_stores: [locks, worker_status, transient_todos]

This contract describes ownership without prescribing a process layout. A deployment can use one actor for the root and verifier, as V0.1 did, or split them. It still needs a record of who produced the acceptance evidence.

Current root and memory adapters

agent-default-model:
  provider: anthropic
  model: claude-opus-5
  reasoningEffort: high

- insert:
    - id: mcp-engram
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: engram
        transport: stdio
        command: engram
        args:
          - mcp
          - --tools=agent
        toolCallTimeoutMs: 60000
        failOnStartupError: true

The memory adapter does not hard-code a project. The preset tells the root to read the active workspace directory, initialize memory with that directory, and keep the returned project identity for the session. The validated run showed why: implicit detection could resolve the DSH repository, while explicit initialization resolved the active dsh-mini-demo workspace.

sequenceDiagram
    participant R as Root Planner
    participant W as Active Workspace
    participant M as Memory Service

    R->>W: read authoritative cwd
    R->>M: start_session(directory = cwd)
    M-->>R: project + session identity
    R->>M: search/save under that identity

    Note over R,M: New conversation

    R->>W: read authoritative cwd
    R->>M: start_session(directory = cwd)
    M-->>R: same project identity
    R->>M: retrieve durable memory
            

Where authority lives today

The current implementation divides constraints between prompt text and runtime policy. The root prompt is where intent ownership, verification duty, and completion authority are assigned, and it is worth reading as a contract rather than as instructions:

You own the user's original objective and maintain global understanding
of the project until the objective is complete.

Do not perform routine implementation yourself with write, edit or
PowerShell. Delegate implementation to a worker.

Never blindly trust a worker result.

Never declare the objective complete merely because one worker reports
success.

Completion is your responsibility.

Two of those lines carry most of the weight. "Never blindly trust a worker result" is what keeps a worker's self-report from becoming acceptance, and "completion is your responsibility" is what stops the hierarchy from ending on a child's optimism. Neither is enforced by the runtime. Both are requests, which is the same weakness finding 01 exposes.

Memory receives an explicit allowlist of durable information and a denylist of coordination state:

Good candidates include:
- architecture decisions
- important configuration decisions
- stable project conventions
- non-obvious discoveries
- completed bug fixes with reusable lessons
- recurring failure modes
- significant technical constraints
- patterns that future sessions should follow

Do NOT save:
- task progress
- worker status
- temporary hypotheses
- logs
- transient command output
- implementation chatter
- short-lived todo items
- agent coordination state

The subplanner receives narrower authority. It can inspect, decompose, and delegate, while durable memory and challenger access remain with the root:

You are a SUBPLANNER in a hierarchical autonomous software
engineering system.

You own only the bounded objective delegated to you by your parent.

Do not directly implement code.

You do not have authority over durable project memory.

Do not start Engram sessions.

Do not save Engram memories.

Do not use Engram as a task queue, scratchpad, status mechanism,
lock manager or coordination channel.

You do not have access to Codex by policy.

Escalation to Codex belongs to the root planner.

Prefer the shallowest hierarchy capable of solving the problem.

These prompt rules express the contract, but the runtime cannot enforce every sentence. The subplanner's denied tools are structural policy:

maxDepth: 2

toolFilter:
  deny:
    - write
    - edit
    - pwsh
    - subagent_codex

The preset removed four tools from the subplanner while leaving worker cardinality in prompt text. The subplanner could not call write, edit, pwsh, or subagent_codex. It could call the worker twice, because cardinality remained prompt text. V0.2 moves that boundary into runtime policy.

The complete preset and setup notes live in the implementation repository. These excerpts show the authority-bearing lines; the repository remains the source for reproduction.

V0.1: the safeDivide experiment.

The eval asked the system to add safeDivide(a, b) to a small JavaScript repository. Normal division had to return a / b. A zero divisor had to throw Error("division by zero"). The change required exactly three tests, no dependencies, and no unrelated edits.

The task was deliberately small. Removing application complexity as a major variable makes failures in orchestration, permissions, adapters, providers, and role boundaries easier to see. It does not remove every variable, isolate model behavior, or establish that this role design is better than a single agent.

The eval specified a route as well as an output. The root would delegate to one subplanner, which would use one implementation worker. The result would return to the root for authoritative verification, independent challenge, and a durable memory write.

flowchart TD
    R[Root Planner] --> P[One Subplanner]
    P --> W[Implementation Worker]
    W --> R
    R --> V[Root Verification]
    R --> C[Independent Challenger]
    R --> M[Durable Memory]
            

The validated run executed every named stage, but it did not follow the route exactly. The subplanner made a second coding-agent call for verification. The implementation still came from one worker; the eval's worker-cardinality constraint was nevertheless violated.

flowchart TD
    R[Root Planner] --> P[Subplanner]
    P --> W[Implementation Worker]
    P --> W2[Second Worker, unrequested]
    W --> R
    W2 --> P
    R --> V[Root Verification]
    R --> C[Independent Challenger]
    R --> M[Durable Memory]
            

Both diagrams label verification as Root Verification. That node is a logical role performed by the root planner. V0.1 did not launch a separate verifier agent. The root inspected the repository and ran npm test with Git and PowerShell available to it.

Validated-run results by dimension

A component-level PASS would hide the route violation. The table separates output, role conformance, verification, challenge, memory, and lineage using only result.md.

The code passed. Final verification and independent challenge ran. Role conformance failed because the executed hierarchy contained an extra worker call. Those outcomes can coexist, and the architecture needs to report each one.

Repository result from the validated run

src/math.js | 7 +++++++
test.js     | 6 +++++-
2 files changed, 12 insertions(+), 1 deletion(-)

The root-level test command passed. The record reports no dependency changes and no files outside src/math.js and test.js.

A separate cross-session memory run

The memory result came from another run. A new conversation performed no repository inspection, shell use, or delegation. It initialized memory with the dsh-mini-demo directory and recalled the stored convention: tests use node:assert/strict, npm test runs node test.js, and the project intentionally has no dependencies or devDependencies.

flowchart LR
    A[Session A] --> S[Save durable convention]
    S --> DB[(Persistent Memory)]
    DB --> B[Session B]
    B --> R[Recall same project convention]
            

The recall succeeded, but a direct observation lookup exposed inconsistent project metadata. Finding 06 treats that as a memory-integrity issue from this separate run, not as part of the validated end-to-end result.

Six findings across three runs.

Findings 01 through 04 come from the validated end-to-end run in result.md. Finding 05 comes from an earlier dry run. Finding 06 comes from the cross-session run in memory-result.md. I am keeping the run boundaries visible because each record supports a different claim.

What you can use without my stack.

The authority model carries over without these adapters. You can apply it with one agent, several agents, a homegrown supervisor, or a commercial orchestrator.

Keep final acceptance away from the implementation report. The same runtime actor may implement and run local checks, but completion should depend on evidence inspected by an authority that can reject the work. In V0.1, the worker could not run the final test command and the root performed verification.

Separate durable knowledge from runtime coordination. Define what may persist. Decisions, conventions, discoveries, and reusable lessons have a different lifetime from locks, worker status, logs, and temporary todos. Keeping both in one memory surface makes stale coordination easier to mistake for current state.

Make project identity an input. Pass the active workspace explicitly to any long-lived memory or tool process. Check the identity returned by the service before a read or write. Finding 06 adds a second check: compare retrieval metadata with the session identity.

Move critical constraints into policy. Prompts are useful for role descriptions and reporting formats. Use permission filters, approval gates, cardinality limits, isolated workspaces, and state transitions for constraints whose violation changes the result. The preset denied write tools structurally; its prompt-only worker limit was violated.

Record the executed path. Keep actor identity, assigned role, parent, workspace, permissions, tool results, and acceptance evidence long enough to reconstruct the run. A live agent list cannot provide that after one-shot processes exit.

Report assurance loss directly. If verification, challenge, memory, or a provider is unavailable, name the missing step in the final status. The earlier dry run establishes that quota loss can occur while the remaining hierarchy completes. Its record does not say whether the final status reflected that loss. A future status record should.

When this is overkill.

A small, local, reversible change with good test coverage probably does not need a hierarchy. One coding tool plus human diff review may be the clearer design. I use the simpler path when the work is easy to inspect and a mistake is easy to undo.

Explicit roles become more useful as authority and recovery get harder to reason about: long-running work, multiple repositories, several workers, different permissions or capabilities, sensitive changes, irreversible actions, audit requirements, cross-session memory, and security or production exposure. Even then, each additional runtime actor has to justify its coordination cost.

A logical verifier or challenger does not force another process. Start with the authority boundary. Split it into a separate actor only when independence, permissions, workload, or auditability requires that separation.

What these runs do not establish.

The validated evidence covers one small task and one execution path. It does not show that the hierarchy is more correct, faster, cheaper, or easier to operate than one strong agent. No single-agent baseline has been run. The record also lacks token counts, model-call counts, estimated cost, retries, wall-clock time, and human intervention data.

The task did not test long-running work, parallel isolated workers, adversarial input, production access, rollback, or destructive operations. The challenger found no defect, but the eval did not seed a known defect, so the result says nothing about detection rate. The memory follow-up shows successful recall and one metadata inconsistency; it does not establish isolation across many projects.

Finding 05 belongs to an earlier dry run, and finding 06 belongs to the cross-session memory run. Combining them with the validated run would create a broader story than any one execution supports.

I am willing to remove roles or abandon the hierarchy if the comparisons do not justify it. If one strong agent wins broadly on correctness, time, cost, and required human attention, the extra runtime actors are overhead. The authority boundaries may still be useful inside a simpler process, but this implementation would need to shrink.

Research roadmap.

The next versions turn current assumptions into comparisons, failure injection, and machine-enforced policy. I do not want to answer every problem by adding another agent. A new runtime actor should appear only when an experiment shows that a separate authority needs a separate process.

Metrics belong to the acceptance record

A task can be functionally correct while violating its route, omitting a review step, or changing unrelated files. Future reports should keep output correctness, role conformance, assurance status, resource use, and human intervention separate. V0.1 records enough to expose the worker-count failure, but not enough to compare efficiency.

The pending comparison asks whether the hierarchy earns its extra machinery on a defined class of tasks.

What V0.1 demonstrated.

In the validated run, the root delegated through a subplanner, one worker produced the implementation, the root ran authoritative verification, the independent challenger reported, and memory routing and writing succeeded. The repository result met the functional requirements. The executed route also contained an unrequested second coding-agent call, so role conformance failed.

The separate memory run showed that a new conversation could recall the stored project convention without inspecting the repository, using the explicit workspace identity. It also exposed inconsistent project metadata on direct observation lookup. The earlier dry run contributes only the quota finding described in finding 05.

These records make the role boundaries executable and give the next evaluations specific failure cases. They do not rank this system against a single strong agent. The current preset, eval definition, and result files are in the implementation repository. The pending V0.7 comparison must supply correctness, time, calls, tokens, cost, retries, interventions, unrelated changes, defects, and conformance data before I can argue that the hierarchy earns its overhead.

References and implementation repository.

1. Cursor: Towards self-driving codebases
2. DSH repository
3. DSH subagent architecture
4. Claude Code: programmatic execution
5. OpenAI: Codex interfaces
6. Engram persistent memory
7. Engram technical reference
8. Agentic Engineering system: reference implementation and eval