Forem: John Attebury

Intent first, stacks second: why Topogram centers contracts

John Attebury — Sun, 17 May 2026 00:03:23 +0000

Topogram chains three layers:

Spec — durable intent in topo/ (.tg statements, projections, widgets, SDLC records, and supporting docs).
Contract — the engine validates and resolves that graph into normalized semantics per surface (screens and widget bindings on a ui_contract, endpoints on an api_contract, tables on a db_contract, and so on).
Slice — topogram query slice returns a context_slice: one focus (task, widget, journey, projection, …), its depends_on closure, summary payloads, and related summaries—without loading the whole workspace into context.

Projection type is how contracts divide the problem: ui_contract vs web_surface / native surfaces, api_contract, db_contract, cli_surface.

Spec snippet → slice payload

Author intent in topo/ (example: a reusable widget):

widget widget_data_grid {
  patterns [resource_table, data_grid_view]
  regions [results, toolbar]
}

Ask for a bounded packet:

topogram query slice ./topo --widget widget_data_grid --json

You get a context_slice object: focus (what this slice is about), depends_on (IDs in closure order), summary (normalized semantics for that focus), optional agent_guidance (read_first, next_queries), plus related, verification_targets, ownership_boundary, ui_agent_packet, and other fields omitted below for length.

Representative excerpt (shape matches CLI output from the app-basic fixture workspace):

{
  "type": "context_slice",
  "focus": { "kind": "widget", "id": "widget_data_grid" },
  "depends_on": {
    "shapes": ["shape_output_item_card"],
    "projections": ["proj_ui_contract", "proj_web_surface", "proj_web_surface_react"],
    "capabilities": [],
    "entities": [],
    "widgets": [],
    "verifications": []
  },
  "summary": {
    "kind": "widget",
    "id": "widget_data_grid",
    "name": "Data Grid",
    "description": "Reusable tabular display for item rows",
    "patterns": ["data_grid_view", "resource_table"],
    "behavior": ["selection", "sorting"],
    "regions": ["results", "toolbar"]
  },
  "agent_guidance": {
    "mode": "implementation",
    "read_first": [
      "focus",
      "summary",
      "depends_on",
      "related",
      "standing_rules",
      "verification_targets",
      "write_scope"
    ]
  }
}

Same pattern for --task, --journey, --projection, and other selectors: one focus, explicit dependencies, and summaries rather than the whole graph.

Benefits

Portable semantics — one graph backs UI, API, DB, CLI intent.
Slice-first workflows — humans and agents load contract-shaped packets keyed to one surface or SDLC artifact instead of scraping the repo.

Tradeoffs

topo/ authoring cost pays off when shared intent matters more than one-off edits.
Semantic contracts intentionally stop short of pixel-perfect CSS or every framework detail.

Bottom line

Spec → contract → slice: declare intent once, resolve it into portable semantics, then pull only the closure you need into an actionable packet.

Topogram slice as focused subgraph

John Attebury — Fri, 15 May 2026 22:57:39 +0000

Plenty of tools will scan a codebase or platform and hand you a graph:

dependencies
services
packages
tables
endpoints
ownership tags

That can be genuinely useful for exploration and incident response. It is also, almost by definition, derived, lossy, and moving.

“The system” as one giant graph is often too big to reason about in a single session, for humans or for agents that need stable context windows.

So we get drift: several overlapping graphs, the actual runtime, the import graph, the org chart in microservice form, and the story people tell in chat.

But do you have an authoritative slice for “the work you're doing right now?”

RAG and “just retrieve the right files”?

Retrieval-augmented generation (RAG) and similar “chunk the repo, embed, fetch what looks relevant” setups can shorten searches and surface starting points, but they do not replace an agreed source of truth.

If the corpus is contradictory or stale, retrieval tends to return plausible fragments that still disagree on names, invariants, or “what we decided.”

The model then smooths those fragments into an answer that sounds aligned.

So RAG often shares the same failure mode as giant inferred graphs: high recall, weak guarantees.

What changes the game is small, curated context: a bounded packet tied to a unit of work, produced from declared structure (or at least reviewed and versioned), not from “whatever ranked well this afternoon.”

That’s the same intuition as a Topogram slice whether you paste it into a prompt, check it in CI, or ship it as JSON to an agent.

Why the slice matters more than the wallpaper graph

The unit of serious engineering is rarely “the entire architecture.” It’s a task, a journey, a widget, a bug, a requirement and its proof.

What teams need is not another poster-sized dependency map they scroll once and forget. We need a focused subgraph: just enough typed intent, constraints, and verification to:

Agree on what “done” means.
Implement or review without rereading the whole repo.
Check changes against explicit references, not vibes.

That’s the importance of the slice: it is

bounded
portable
aligned to the work item

It is small enough to be consistent and to stay consistent when the broader inferred graph shifts underneath you.

Authored intent + queryable slices (how Topogram thinks about it)

Topogram treats durable product and delivery intent as declarative records under topo/—a structured graph the CLI validates, not something you reverse-engineer after the fact and hope still matches Sunday’s deploy.

From that graph you can pull slices for the thing you’re doing: for example task-scoped or journey-scoped query output (topogram query slice ...) instead of asking a human or an agent to absorb the entire repository as “context.”

Example (proof repo): The brownfield proof program checks in a real exported task slice as an artifact—proof/artifacts/step-04-task-slice.json. (Also available at the bottom of this post.)

Developers and Agents inspect one task’s focused context as JSON, rather than spelunking the whole graph by hand.

For background on the structured graph idea (intent vs. stack realization, validation, contracts), see Topogram’s structured graph: concept and implementation.

For the SDLC slice of the same graph (pitches, requirements, tasks, proof), see the companion draft in this repo under dx/posts/topogram-sdlc-graph-devto.md until it is published.

Repository: github.com/attebury/topogram

{
  "depends_on": {
    "acceptance_refs": [
      "ac_maintained_bulk_approve"
    ],
    "affects": [
      "cap_bulk_approve_submissions",
      "cap_list_submissions"
    ],
    "blocked_by": [],
    "blocks": [],
    "plans": [],
    "satisfies": [
      "req_maintained_bulk_approve"
    ],
    "verification_refs": [
      "verification_maintained_bulk_approve"
    ],
    "verifications": [
      "verification_adopt_brownfield_spec",
      "verification_maintained_bulk_approve"
    ]
  },
  "focus": {
    "id": "task_maintained_bulk_approve",
    "kind": "task"
  },
  "ownership_boundary": {
    "canonical_topogram": {
      "agent_mode": "propose_review_adopt",
      "owner": "human"
    },
    "generated_artifacts": {
      "agent_mode": "regenerate_or_compare",
      "owner": "engine"
    },
    "maintained_code": {
      "agent_mode": "bounded_edit_only",
      "owner": "human"
    },
    "proposal_surfaces": {
      "agent_mode": "stage_map_customize_reject",
      "owner": "human"
    }
  },
  "related": {
    "acceptance_refs": [
      {
        "description": "Given the brownfield app has an adopted Topogram spec, when bulk approval is added to the API, queue UI, widgets, and projections, then Topogram check, SDLC check, and app verification pass without generated source writes.",
        "id": "ac_maintained_bulk_approve",
        "kind": "acceptance_criterion",
        "name": "Maintained Bulk Approve",
        "ownership_boundary": {
          "canonical_topogram": {
            "agent_mode": "propose_review_adopt",
            "owner": "human"
          },
          "generated_artifacts": {
            "agent_mode": "regenerate_or_compare",
            "owner": "engine"
          },
          "maintained_code": {
            "agent_mode": "bounded_edit_only",
            "owner": "human"
          },
          "proposal_surfaces": {
            "agent_mode": "stage_map_customize_reject",
            "owner": "human"
          }
        }
      }
    ],
    "affects": [
      {
        "actors": [
          "actor_operator"
        ],
        "creates": [],
        "deletes": [],
        "description": "Approves multiple selected content submissions.",
        "id": "cap_bulk_approve_submissions",
        "input": [
          "shape_input_bulk_review"
        ],
        "kind": "capability",
        "name": "Bulk Approve Submissions",
        "output": [
          "shape_output_submission_card"
        ],
        "ownership_boundary": {
          "canonical_topogram": {
            "agent_mode": "propose_review_adopt",
            "owner": "human"
          },
          "generated_artifacts": {
            "agent_mode": "regenerate_or_compare",
            "owner": "engine"
          },
          "maintained_code": {
            "agent_mode": "bounded_edit_only",
            "owner": "human"
          },
          "proposal_surfaces": {
            "agent_mode": "stage_map_customize_reject",
            "owner": "human"
          }
        },
        "reads": [
          "entity_content_submission"
        ],
        "reviewBoundary": {
          "automation_class": "review_required",
          "reasons": [
            "writes_modeled_state"
          ]
        },
        "roles": [],
        "updates": [
          "entity_content_submission"
        ]
      },
      {
        "actors": [
          "actor_operator"
        ],
        "creates": [],
        "deletes": [],
        "description": "Lists submitted content in review order.",
        "id": "cap_list_submissions",
        "input": [
          "shape_input_list_submissions"
        ],
        "kind": "capability",
        "name": "List Submissions",
        "output": [
          "shape_output_submission_card"
        ],
        "ownership_boundary": {
          "canonical_topogram": {
            "agent_mode": "propose_review_adopt",
            "owner": "human"
          },
          "generated_artifacts": {
            "agent_mode": "regenerate_or_compare",
            "owner": "engine"
          },
          "maintained_code": {
            "agent_mode": "bounded_edit_only",
            "owner": "human"
          },
          "proposal_surfaces": {
            "agent_mode": "stage_map_customize_reject",
            "owner": "human"
          }
        },
        "reads": [
          "entity_content_submission"
        ],
        "reviewBoundary": {
          "automation_class": "safe",
          "reasons": [
            "read_only_surface"
          ]
        },
        "roles": [],
        "updates": []
      }
    ],
    "blocked_by": [],
    "plans": [],
    "satisfies": [
      {
        "description": "The brownfield app must add bulk approval behavior from the adopted Topogram widget and API contract without regenerating the maintained source.",
        "id": "req_maintained_bulk_approve",
        "kind": "requirement",
        "name": "Maintained Bulk Approve",
        "ownership_boundary": {
          "canonical_topogram": {
            "agent_mode": "propose_review_adopt",
            "owner": "human"
          },
          "generated_artifacts": {
            "agent_mode": "regenerate_or_compare",
            "owner": "engine"
          },
          "maintained_code": {
            "agent_mode": "bounded_edit_only",
            "owner": "human"
          },
          "proposal_surfaces": {
            "agent_mode": "stage_map_customize_reject",
            "owner": "human"
          }
        }
      }
    ],
    "verification_refs": [
      {
        "description": "Runs Topogram check, SDLC check, maintained app API behavior verification, and React build verification for the bulk approve checkpoint.",
        "id": "verification_maintained_bulk_approve",
        "kind": "verification",
        "method": "runtime",
        "name": "Maintained Bulk Approve Verification",
        "ownership_boundary": {
          "canonical_topogram": {
            "agent_mode": "propose_review_adopt",
            "owner": "human"
          },
          "generated_artifacts": {
            "agent_mode": "regenerate_or_compare",
            "owner": "engine"
          },
          "maintained_code": {
            "agent_mode": "bounded_edit_only",
            "owner": "human"
          },
          "proposal_surfaces": {
            "agent_mode": "stage_map_customize_reject",
            "owner": "human"
          }
        },
        "scenarios": [
          "brownfield_bulk_approve_api_ui_compile"
        ],
        "validates": [
          "cap_bulk_approve_submissions",
          "cap_list_submissions"
        ]
      }
    ]
  },
  "review_boundary": {
    "automation_class": "review_required",
    "reasons": [
      "task_scope"
    ]
  },
  "summary": {
    "claimed_by": [
      "actor_operator"
    ],
    "disposition": "active",
    "domain": null,
    "id": "task_maintained_bulk_approve",
    "name": "Maintained Bulk Approve",
    "priority": "medium",
    "status": "in-progress",
    "work_type": "implementation"
  },
  "type": "context_slice",
  "verification": [
    {
      "description": "Runs Topogram check, SDLC check, agent brief, focused query packets, adoption receipts, and maintained app verification for the adopted brownfield spec checkpoint.",
      "id": "verification_adopt_brownfield_spec",
      "kind": "verification",
      "method": "runtime",
      "name": "Adopt Brownfield Spec Verification",
      "ownership_boundary": {
        "canonical_topogram": {
          "agent_mode": "propose_review_adopt",
          "owner": "human"
        },
        "generated_artifacts": {
          "agent_mode": "regenerate_or_compare",
          "owner": "engine"
        },
        "maintained_code": {
          "agent_mode": "bounded_edit_only",
          "owner": "human"
        },
        "proposal_surfaces": {
          "agent_mode": "stage_map_customize_reject",
          "owner": "human"
        }
      },
      "scenarios": [
        "brownfield_adoption_topogram_check_sdlc_check_app_verify"
      ],
      "validates": [
        "cap_approve_submission",
        "cap_get_submission",
        "cap_list_submissions",
        "cap_request_changes",
        "cap_submit_content"
      ]
    },
    {
      "description": "Runs Topogram check, SDLC check, maintained app API behavior verification, and React build verification for the bulk approve checkpoint.",
      "id": "verification_maintained_bulk_approve",
      "kind": "verification",
      "method": "runtime",
      "name": "Maintained Bulk Approve Verification",
      "ownership_boundary": {
        "canonical_topogram": {
          "agent_mode": "propose_review_adopt",
          "owner": "human"
        },
        "generated_artifacts": {
          "agent_mode": "regenerate_or_compare",
          "owner": "engine"
        },
        "maintained_code": {
          "agent_mode": "bounded_edit_only",
          "owner": "human"
        },
        "proposal_surfaces": {
          "agent_mode": "stage_map_customize_reject",
          "owner": "human"
        }
      },
      "scenarios": [
        "brownfield_bulk_approve_api_ui_compile"
      ],
      "validates": [
        "cap_bulk_approve_submissions",
        "cap_list_submissions"
      ]
    }
  ],
  "verification_targets": {
    "generated_checks": [
      "compile-check",
      "runtime-check"
    ],
    "maintained_app_checks": [],
    "rationale": "Task slice points at verification covering the surfaces this task touches.",
    "verification_ids": [
      "verification_adopt_brownfield_spec",
      "verification_maintained_bulk_approve"
    ]
  },
  "version": 1,
  "write_scope": {
    "generator_owned": [
      "artifacts/**",
      "apps/**"
    ],
    "human_owned_review_required": [
      "examples/maintained/proof-app/**"
    ],
    "out_of_bounds": [
      ".git/**",
      "node_modules/**"
    ],
    "safe_to_edit": [
      "topo/**",
      "candidates/**"
    ]
  }
}

How Topogram models delivery as an SDLC graph

John Attebury — Fri, 15 May 2026 19:16:22 +0000

How Topogram models delivery as an SDLC graph

Audience: Organizations who need traceable work (requirements → proof → completion) without treating “the wiki” as the system of record.

Summary: Topogram can represent software delivery artifacts as typed records inside the same graph as your product intent. This post is a high-level tour of what that graph contains, how projects adopt it, and why declarative source and command-owned state are kept separate.

Repo: Topogram on GitHub

Dogfooding: Topogram uses its own SDLC in-tree. You can browse the adopted records under topo/sdlc/ in the repository (pitches, requirements, tasks, acceptance criteria, bugs, policy sidecars, and history the CLI maintains).

What “SDLC graph” means here

Your repository already holds many kinds of information: product concepts, contracts, tasks, tests, and process notes. When those live only in prose or scattered tickets, relationships are implicit — useful for humans, weak for automation.

Topogram’s SDLC graph is the subset of the overall Topogram model made of lifecycle records: pitches, requirements, acceptance criteria, tasks, plans, bugs, decisions, and verification hooks that tie work to observable proof. Like the rest of the model, these records live under topo/ (commonly under topo/sdlc/ paths such as pitches/, requirements/, acceptance_criteria/, tasks/, and so on — see the project docs for the recommended layout).

The parser normalizes everything under topo/ into one graph, so SDLC nodes can link to each other and to the wider model (rules, capabilities, decisions, etc.) with explicit references — not only narrative links.

The chain of proof (how records relate)

Topogram encourages the smallest record that tells the truth, with a typical reading order:

Record	Purpose (high level)
Pitch	Why a theme or investment matters.
Requirement	Durable behavior the project commits to.
Acceptance criterion	Observable proof; approved criteria use explicit given / when / then wording.
Task	Implementation-sized slice tied back to requirements and criteria.
Verification	Command, test, check, or gate that provides evidence.
Decision	A durable choice that stabilizes future work.
Bug	A violation of an accepted rule, requirement, or verified expectation.
Plan	Optional nested execution notes for a task.

Done tasks are expected to line up with the graph: valid references to what they satisfy, approved acceptance refs, and valid verification refs — so “closed” means something checkable, not only a status change in a tracker.

Adoption and enforcement (policy, not vibes)

Projects opt in with topogram.sdlc-policy.json. If the policy is missing, SDLC commands may still run, but gate behavior can report not adopted until you pass flags such as --require-adopted (see your project’s docs and policy file).

A policy can declare protected paths (areas where changes should be tied to SDLC items) and required item kinds (for example task, bug, requirement, pitch), with room for documented exemptions when reality does not fit the template. That turns “we should link work to specs” into machine-checkable expectations aligned with your repo’s rules.

How teams use it day to day (conceptual loop)

The workflow is designed so humans and agents can preview state transitions before anything mutates:

Discover available work (query sdlc-available, policy explanation).
Open a task packet (sdlc start in read-only mode) — linked requirement, criteria, blockers, decisions, verification targets, and suggested queries.
Apply transitions deliberately (sdlc start ... --write only after review) so status/state changes stay auditable.
Check proof gaps before declaring completion (query sdlc-proof-gaps, then complete with explicit verification).

Commit and integration steps can include sdlc prep commit and sdlc gate so a branch’s changes are compared against policy and the declared graph — reducing “merged without a defensible thread from spec to proof.”

For copy-paste command examples, use the repository’s SDLC concept documentation: docs/concepts/sdlc.md.

Declarative source vs. command-owned state (why writers should care)

You can edit *.tg source directly: pitches, requirements, acceptance wording, and structural links live there as declarative text.

Stateful workflow data — history, transitions, archives, trust hashes, release evidence, and similar sidecars — is intended to move through Topogram commands so drift is detectable and reviews have a clear audit trail. Hand-editing sidecar JSON to “make CI green” undermines the model; the tooling is built to expose that.

For documentation practice, the payoff is straightforward: the story and the process metadata stay aligned because the same CLI surfaces both the narrative graph and the lifecycle state.

Benefits

Stable anchors: requirements and acceptance criteria that are first-class nodes, not orphaned pages.
Traceability from intent → work → proof without maintaining a separate trace matrix by hand.
slices and packets (task-scoped context) instead of full-repo archaeology.

Bottom line

Topogram’s SDLC graph is not a separate ticketing system; it is a typed, linkable slice of your product graph where pitches, requirements, criteria, tasks, verification, and decisions form a chain of proof the CLI can query, gate, and keep honest.

Topogram on GitHub

If you are new to the project, start with topogram init --with-sdlc and read the repo’s SDLC and agent brief docs before changing protected paths.

Topogram’s structured graph: concept and implementation

John Attebury — Fri, 15 May 2026 18:55:54 +0000

Audience: Organizations who maintain product specs, API contracts, and delivery artifacts and want those to stay aligned with code and process.

Reading time: ~4 minutes.

What this post covers: What Topogram means by a structured graph, how that differs from informal documentation, and how the implementation supports validation, querying, and generation — without requiring you to adopt every workflow on day one.

Learn more in the Topogram repository
Content Approval Proof
Brownfield Content Approval Proof

Why a graph, and why “structured”?

Product knowledge naturally looks like a graph: features depend on services, screens consume APIs, requirements spawn tasks, and verification ties back to acceptance criteria. In many organizations, that graph exists only in people’s heads, or across loosely linked files and tickets. Tools cannot reliably traverse what was never declared.

Topogram’s approach is to make that graph explicit and typed.

You maintain a workspace (topo/) where you express intent using Topogram statements (.tg files) and supporting markdown. A parser normalizes everything under topo/ — regardless of folder layout — into one graph the CLI can validate, query, and hand off to generators or agents.

“Structured” here means: kinds of nodes, declared relationships, and constraints the tool can enforce. It is not the same as “we use consistent headings in Confluence.”

Concept: intent versus realization

Topogram separates two layers:

Durable intent — What the product is and must do: entities, capabilities, rules, user journeys, UI/API/DB/CLI contracts as projections, SDLC objects (for example pitches, requirements, acceptance criteria, tasks), and decisions.
Stack realization — How a specific runtime or codebase implements that intent (web app, API service, database, mobile surface, and so on), driven by project configuration and generator bindings.

Keeping intent in a single, checkable model reduces the classic failure mode where the wiki, the OpenAPI file, and the implementation each tell a slightly different story.

What goes in the graph

Common statement kinds include domain vocabulary (actor, role, term, domain), structural modeling (entity, shape, enum), behavioral and quality layers (rule, capability, orchestration, verification), UI semantics (widget), journey (ordered steps and branches), projections (contracts and surfaces), decisions, and — when SDLC is adopted — linked lifecycle artifacts.

Journeys are worth highlighting for software teams: they can represent sequences and alternatives as graph-native structure, so procedural truth is not trapped only in prose.

Projections describe surfaces such as UI contracts, web/iOS/Android surfaces, API contracts, database contracts, and CLI surfaces. That gives downstream tools a normalized contract instead of each stack inventing its own parallel spec.

Implementation from files to consumable output

At a high level, the pipeline is:

Stage	Role
Authoring	Humans and agents edit `.tg` (and markdown where appropriate) under `topo/`. `topogram.project.json` declares workspace paths, output ownership (generated vs maintained), topology runtimes, and how generators bind to projections.
Ingestion	The parser flattens the directory tree into one graph; folder structure is organizational, not semantic identity.
Validation	The CLI checks the model so errors surface before they propagate to generated artifacts or reviews.
Consumption	Teams run targeted queries (for example task slices, SDLC packets, proof-gap reports) and bind generators to normalized contracts.

Agents are guided toward read-only briefings and query packets rather than scanning the entire repository — the graph makes “just the relevant subgraph” a first-class output.

What this gives documentation and engineering teams

Traceability: Links between requirements, criteria, tasks, and verification can live in the same model you validate — not only in prose or ticket comments.
Discoverability: Queries return consistent, structured views of the graph instead of duplicating context in chat or ad-hoc exports.
Contract alignment: API, UI, data, and CLI intent share a backbone; stacks realize projections instead of re-deriving product meaning locally.
Operational honesty: Missing edges and incomplete intent show up as validation or query gaps, which is easier to prioritize than silent wiki decay.

Summary

Topogram’s structured graph is not a diagramming exercise; it is an authored, typed model of product and system intent under topo/, normalized by the tool into contracts and queries that generators and SDLC workflows can share.

If you are evaluating it, start with a small slice: one capability, one projection, and one journey — then use the CLI checks and queries to see whether your team’s implicit graph matches what you declare.

Learn more in the Topogram repository
Content Approval Proof
Brownfield Content Approval Proof

Spec Driven

John Attebury — Thu, 14 May 2026 20:10:59 +0000

Spec-driven work gets lumped in with AI-assisted coding; that’s fair overlap and agents need rails.

But the core idea is older and broader:

explicit intent
reviewable changes
less drift

AI is one consumer of good specs, not the reason to have them.

Teams that never touch an LLM still win when requirements, acceptance criteria, and system shape live in one coherent place instead of five formats that silently disagree.

Looking for a few design partners for Topogram, an early spec-and-proof layer for teams using coding agents to evolve real software

John Attebury — Wed, 22 Apr 2026 17:39:25 +0000

I’m looking for a small number of design partners to review an early project called Topogram.

Topogram is aimed at a specific problem:

how do humans and coding agents evolve real software without letting intent, generated outputs, and verification drift apart?

The core idea is simple:

keep durable software intent explicit
generate contracts and runnable artifacts from that intent
keep verification attached to the same source of truth
make it clearer what should stay generated, what should stay hand-maintained, and what should stop for human review

This is not a “prompt to product” tool and it is not a production-ready platform.

The current wedge is narrower:

brownfield recovery and reconcile/adopt workflows
maintained-app change guidance
proof-oriented generated artifacts and verification
explicit safe, guarded, and no-go boundaries for agent-assisted change

The repo already has working proof surfaces for:

generated examples across multiple domains
brownfield recovery on real stacks
a maintained proof app that shows how Topogram can guide edits to existing code
explicit single-agent and bounded multi-agent planning surfaces

If that problem space is familiar, I’d love a limited round of review from people across a real software team, especially:

developers and technical leads already using coding agents on real systems
product designers and UX people who care about where agent assistance should stop and human judgment should stay in the loop
product owners who feel the cost when workflow intent, implementation, and review drift apart
teams working on brownfield systems rather than only Greenfield demos
people who are opinionated about contracts, architecture, workflow semantics, and review boundaries

Good fit:

cross-functional software teams comfortable with early infrastructure
people willing to react to a real repo, proof docs, and evaluator path
teams with one contained workflow or subsystem they’d use to pressure-test this
teams where engineering, design, and product all have a stake in how changes are proposed, reviewed, and verified

Bad fit:

teams looking for a no-code builder
teams expecting production-ready auth or deployment hardening today
teams wanting a generic agent runtime or orchestration platform

If you want to take a look, the best starting points are:

If you’re interested, the current lightweight path is:

open a GitHub issue: attebury/topogram/issues
use the title prefix alpha interest:
include:
- what kind of codebase or system you’re working on
- whether the main pressure is brownfield recovery, maintained-app evolution, or proof/verification
- where coding agents are helping today, and where they’re drifting

What I’m looking for right now is not broad attention. I’m looking for a few sharp conversations with teams who actually feel this problem from different angles: engineering, design, UX, and product.

If that’s you, I’d really appreciate the review.

AX: A Design Discipline for the AI Agent Era

John Attebury — Sun, 15 Mar 2026 23:42:10 +0000

If you've built an MCP server, exposed tools for an AI agent, or crafted tool descriptions so the AI would call the right endpoint, you've been practicing Agent Experience — AX, a term Mathias Biilmann coined in early 2025. The current AX conversation tells you it matters. But knowing it matters and knowing how to evaluate it are different things. UX became a discipline when practitioners connected it to User-Centered Design and gave it testable principles and evaluation methods. AX needs the same grounding.

UX, DX, CX... AX

Every era of software recognizes that a particular consumer deserves intentional design. UX (end users), DX (developers), CX (customers) — each started informally, then someone named the discipline, principles emerged, and quality went up. AX — Agent Experience — follows the same arc. The new consumer is an AI agent: an LLM that reads your tool definitions, decides which to call, and orchestrates workflows. Biilmann and Netlify named it and showed why it matters. What's missing is a methodological foundation: a way to reason about why designs work and how to evaluate quality. This post grounds AX in the design traditions it inherits.

User-Centered Design

Every experience discipline rests on the same foundation: you're designing for a consumer you're not. That's User-Centered Design — refined over forty years. UX, DX, and CX are specializations of it. AX is the next one. It doesn't require a new methodology; it applies UCD to a new consumer: the agent.

In UX, you're not the user. You do research, test, iterate. In AX, you're not the agent. You can't assume the AI will "figure it out" because you know what you meant. The AI has no prior relationship with your system. It sees tool names, descriptions, and parameter schemas — and from that alone must decide what to call, when, and with what inputs. That's the entire interface. A developer has docs, tutorials, and time to learn. An AI agent has your tool signature and a few seconds of inference. The bar for clarity and self-description is dramatically higher.

Whether you use MCP, OpenAI function calling, or a custom framework, you're building an AX surface. Your tool definitions are the AI's entire interface to your system.

Four Design Pressures That Shift

AX is to API design what UX was to graphic design — not new principles, but applying them for a specific consumer under specific constraints. Four pressures shift when the consumer is an agent:

Context budget. With REST APIs, 500 endpoints cost the developer cognitive load; they find the three they need and ignore the rest. With AI tools, every definition consumes tokens from a finite context window. Too many or too verbose, and you degrade the AI's reasoning about all of them. Bloated surfaces are a performance problem, not just ergonomics.

Probabilistic selection. A developer writes fetch('/api/animals/4521') — explicit. An AI matches "check on that animal" to get_animal_info through semantic inference. Similar descriptions → wrong tool. Naming is a correctness concern.

Starts from zero every time. A developer learns your API over time. An AI has no memory. Every conversation is fresh. Rename a tool and there's no migration path. Stability and naming consistency matter far more.

Emergent composition. In APIs you design orchestration explicitly. With AI, the agent decides the sequence at runtime. You provide building blocks; the AI assembles them. Convenience endpoints that chain workflows remove the agent's ability to handle partial flows. The design pressure runs the opposite direction.

The AX Discipline Map

AX needs a structure for evaluation — like Nielsen's heuristics for UX. Six concerns we've found useful:

Orchestration Design — Can the agent assemble your tools into coherent workflows, or are there gaps?
Tool Contract Design — Can the agent figure out what a tool does, when to use it, and how to call it from the signature alone?
Context Economics — Are you spending the agent's context budget wisely, or drowning it in noise?
Domain Legibility — Does the agent understand your business after reading your tool definitions?
Safety & Trust Design — Can the agent investigate freely without accidentally breaking things?
Error & Recovery Design — When something goes wrong, can the agent figure out what to try next?

How do you know if AX is working? Test it. Run twenty representative user prompts. Measure tool selection accuracy, task completion, and recovery rate. That's the AX equivalent of a usability study.

Principles You Already Know

You don't need new principles — you need to apply existing ones with a different consumer in mind.

Single Responsibility. A tool should do one thing. A kitchen-sink tool with action: move | treat | ship | lookup forces the AI to reason combinatorially. Focused tools like get_animal_info, save_cattle_treatment, save_cattle_moves map cleanly to user intent.

Ubiquitous Language. The AI's only path to your domain is through tool and parameter names. In a feedlot system, operators say "calling feed" — so save_call_per_head with callPerHead in lbs matches naturally. Name it create_feed_record and the AI bridges a vocabulary gap that didn't need to exist. The AX surface is the documentation.

Composition over monoliths. Don't build performFullTreatmentWorkflow. Expose atomic steps: validate_treatment_tag, get_treatment_setup, save_cattle_treatment. The AI sequences them. Bury it in one tool and you lose partial workflows ("just check if 4521 is eligible") and graceful failure handling.

Safety boundaries. The AI needs to know which tools are safe to explore versus which have side effects. get_animal_info and get_open_lots — read-safe. save_cattle_treatment and save_cattle_moves — the agent should confirm before calling. Make the read/write boundary visible in the tool contract.

What AX Gets You

Netlify reports over 1,000 sites deploying daily from ChatGPT through agent-optimized infrastructure — measurable business impact from AX investment. Our experience building an POC MCP server for a feedlot system: applying AX principles (consistent get_/save_ naming, domain vocabulary, single-responsibility tools) eliminated compensatory system prompts. The AI selected the correct tool on first attempt for the vast majority of prompts — no few-shot examples, no elaborate tuning. One team's experience, not a controlled study, but the results were immediate.

Teams that treat AX as a discipline gain: better AI integrations with less prompt engineering, agent portability across Claude/GPT/Gemini, faster capability onboarding, lower token costs, and compounding returns as quality builds trust.

From Ad Hoc to Discipline

Most teams building tool servers today do it ad hoc — smart decisions without a shared framework. Start here: look at your tool definitions through the six concerns. Ask the litmus questions. The principles are the same ones you've practiced. They just have a new consumer.

AX will evolve as constraints shift — persistent memory, larger context windows. But the core challenge — making your systems legible for a reasoning consumer — persists whether the AI calls a tool, generates HTTP, or writes code. The mechanism is an implementation detail. The discipline is about the consumer.

In UX, you're not the user. In AX, you're not the agent. The craft of designing for someone else — that's the same skill it's always been.