Agentic engineering

Composition / System architecture

The system is the handoffs.

The team becomes dependable when every role receives a bounded input, writes a durable output, and returns control to an explicit state machine.

Architecture

probabilistic workers connected by deterministic state

Choose a stage to inspect its runtime, input, output, and ownership boundary.

01 / Six layers

Separate the things that change for different reasons.

A portable implementation does not begin with eleven prompts. It begins with six architectural responsibilities whose interfaces remain stable when models, languages, or tools change.

01

Interface

Commands expose stable verbs and entry modes.

/feature resume 001
02

Coordination

The orchestrator tracks stage, sequence, rounds, and approvals.

state → next owner
03

Judgment

Agents perform one kind of bounded interpretation.

artifact → artifact
04

Policy

Skills supply shared rules, procedures, and schemas.

role + relevant policy
05

State

Files and logs make progress, evidence, and recovery observable.

filesystem + SQLite + git
06

Isolation

A feature worktree contains mutable implementation work.

feature/001-name
Dependency rule

Each layer may depend on contracts below it, but no specialist should secretly become the state machine above it.

02 / Artifact ledger

The directory is an append-only execution trace.

Sequence numbers express order. Agent IDs express ownership. New rounds append files instead of replacing history.

Feature directorydocs/briefs/001-sync-status/
  1. 01Discovery briefMain branch
  2. 02Architecture specFeature worktree
  3. 03Design specFeature worktree
  4. 04Engineer report · round 1Feature worktree
  5. 05Code review · round 1Parallel
  6. 06Security review · round 1Parallel
  7. 07Performance review · round 1Parallel
  8. 08Fidelity review · round 1Parallel
  9. 09Engineer report · round 2Only if needed
  10. 10–13Four reviews · round 2History preserved
docs/briefs/001-sync-status/001.01-dis-sync-status.md

Discovery brief

    03 / Execution isolation

    Discovery establishes truth. The worktree contains change.

    The discovery brief lands on the main branch. From architecture through synthesis, agents work in a dedicated feature worktree. Shared learning remains outside the branch.

    Project root · main/master

    Shared product state

    • 001.01-dis-*.md committed first
    • Scope ideas filed to GitHub once after success
    • docs/icp/ and docs/roadmap.md
    • db/agent_log.sqlite3 shared learning history
    create onceAGENT_LOG_DBshared evidence
    Feature worktree · feature/001-sync-status

    Isolated delivery state

    • Architecture and design specs
    • Application code and tests
    • Every engineer and review report
    • Final feature synthesis document
    Silent failure

    If a worktree agent writes to a local default log database, its decisions vanish when the worktree is removed. The explicit shared log path is part of every launch contract.

    04 / Parallel gate

    Independent lenses meet at one deterministic verdict.

    Change any reviewer result. The routing rule is mechanical: one NEEDS WORK sends the complete evidence set back to engineering.

    05 · Code review

    Code quality

    Pattern coherence, Rails conventions, coverage, data integrity.

    06 · Security review

    Security

    Authorization, injection, mass assignment, XSS, exposure.

    07 · Performance review

    Performance

    Queries, indexes, callbacks, collection growth, constraints.

    08 · Fidelity review

    Fidelity

    Did code follow the plan—and did the plan solve the original problem?

    Bounded retry

    The loop does not repeat forever. If the same finding category persists into round 2, the orchestrator names it explicitly before routing back again. If it persists into round 3, routing stops—the orchestrator escalates to the human instead of launching another round. Three rounds of the same finding means the spec or the skill is wrong, not the engineer.

    05 / Resumability

    Recovery is a filesystem query, not a memory trick.

    Choose the first missing artifact. The system re-derives its checkout and worktree, reconstructs the current round, and routes to the owner of that missing contract.

    State rule

    Session variables are disposable. Artifact paths, branch names, and sequence rules must be sufficient to reconstruct state in a fresh conversation.

    06 / Completion is another system

    A passing build becomes product evidence and future policy.

    The pipeline does not stop at “all tests green.” It compresses the feature, captures adjacent scope safely, opens a reviewable change, and records whether earlier decisions held.

    07

    Synthesis

    Write 001-summary.md so a downstream reader does not need eight reports.

    07b

    Issue filing

    The orchestrator sweeps tagged scope ideas, checks for duplicates, and files each survivor to GitHub once.

    07c

    Pull request

    Push the feature branch and open the PR. A human owns merge.

    08

    Outcome recording

    Architect and engineer compare expected outcomes with live review evidence.

    Run evidenceagent_log.sqlite3
    Pattern analysisLog Analyst
    Proposed improvementSkill Builder
    Governance gateHuman approval
    Learning boundary

    Agents may propose changes to skills. They should not silently rewrite the rules that govern future agents.

    07 / Port it to another language

    Preserve contracts. Replace domain judgment.

    A Python, Elixir, Go, or Java team needs different engineering policy. It does not need a different execution grammar.

    Keep

    Artifact protocol

    Feature directories, sequence numbers, owner IDs, append-only rounds.

    Keep

    State machine

    Stage prerequisites, routing, parallel barrier, combined verdict, retry math.

    Keep

    Role boundaries

    Discovery, architecture, design, engineering, independent review lenses.

    Replace

    Language doctrine

    Swap Rails principles for the target ecosystem’s native conventions and tooling.

    Replace

    Verification tools

    Use the language’s tests, security scanners, linters, profilers, and package audit.

    Adapt

    Runtime adapter

    Map commands, agent launches, tool permissions, and workspaces to the host platform.

    1. 01

      Implement the artifact grammar

      Make state visible before adding agents.

    2. 02

      Code the route table and gate

      Keep mechanical transitions out of prompts.

    3. 03

      Build one vertical slice

      Coordinator → engineer → one reviewer → retry.

    4. 04

      Add roles only when the contract earns them

      Parallelism follows independent lenses, not organizational theater.

    08 / Portable state machine

    Make the control plane executable.

    This pseudocode is the minimum architecture: determine the first missing contract, run the owner, wait at the four-review barrier, and append another round when any reviewer blocks.

    Inspect the source orchestrator
    orchestrator.pseudoPortable control plane
    feature = identify(invocation)
state   = scan_artifacts(feature)

while !state.complete?
  stage = first_missing_stage(state)

  case stage
  when :discovery
    run_in_conversation(:discovery, user_intent)
  when :architecture, :design, :engineering
    run_agent(stage.owner, stage.required_inputs)
    require_file(stage.expected_output)
  when :reviews
    reports = run_parallel(
      :code_review,
      :security_review,
      :performance_review,
      :fidelity_review
    )
    require_files(reports)

    if reports.any?(&:needs_work?)
      sequence += 5
      run_agent(:engineering, reports: reports)
    else
      state.complete = true
    end
  end

  state = scan_artifacts(feature)
end

write_summary(feature)
capture_todos_once(feature)
open_pull_request(feature)
record_outcomes(feature)