DEV Community

Cover image for Intent first, stacks second: why Topogram centers contracts
John Attebury
John Attebury

Posted on

Intent first, stacks second: why Topogram centers contracts

#ai #softwareengineering #topogram #agents

Topogram chains three layers:

  1. Spec — durable intent in topo/ (.tg statements, projections, widgets, SDLC records, and supporting docs).
  2. 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).
  3. 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]
}
Enter fullscreen mode Exit fullscreen mode

Ask for a bounded packet:

topogram query slice ./topo --widget widget_data_grid --json
Enter fullscreen mode Exit fullscreen mode

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"
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)