Intent first, stacks second: why Topogram centers contracts

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]

}

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.