Spec Studio

The agent front door is one evaluation sink over the exported reader

spec:decisions.agent-front-doorDecision Record · featureready floor ready

Packs: pack:self-hosting-v1

Design: no design entries · no pinned declarations · no decisions

Findings: no errors, no warnings

specs/decisions/agent-front-door.sdp.md

No open questions and no blocking questions; implementation binding none, verifier binding none, and expected-outcome oracle none.

Intent
outcome
Let an agent read the typed graph in a single invocation without authoring a module for each question and without minting query verbs.
Decision
context
Agents arrive holding a question rather than a project, and the exported reader answers only after a TypeScript module is authored, compiled, and run.
decision
The front door is two entrances over one seam: the package exports the reader constructor, and the CLI carries a single evaluation sink that derives the graph in process, injects that same reader, and prints the body's pre-shaped return.
rationale
  • One evaluation sink adds no query vocabulary, so it is the opposite of a verb wall, while a scripting-only entrance taxes every question with a module, a sink with its own query language would rebuild the wall, and reading a committed graph artifact would answer from a snapshot a just-authored Spec is missing from.
consequences
  • The graph is derived through the extractor on every invocation, so a just-authored Spec is queryable immediately and no stale artifact answers in the graph's name.
  • The sink reads only — it consumes the extractor's derived output in memory, never re-parses carriers, and writes no artifact.
  • The sink evaluates operator-supplied code with the trust stance of a local developer tool rather than a sandbox, and supplied roots resolve to canonical validated identities at the boundary.
  • The injected binding names are a scripted contract that recipes and skills depend on, so renaming one breaks every body written against the surface.
Verification

Verifier bindings

No verifier binding recorded.

Design view

Requirement drawing

  • Declared verifying examples: no declared verifying example.
  • Satisfying or referencing units: no recorded binding.
  • Test or oracle bindings: no recorded binding.
Requirement drawing for spec:decisions.agent-front-door

Arrows: refines (declared).

The diagram as text
  • spec:decisions.agent-front-door: The agent front door is one evaluation sink over the exported reader · declared Spec
  • spec:consumers.agent-surface: Agents script a visible typed graph · declared Spec
  • spec:decisions.agent-front-door refines spec:consumers.agent-surface · declared
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred and chosen syntax: requirementDiagram; exact refines, satisfies and verifies, with claim words in nodes and per-edge comments.

Decisions

No decision record named.

Runtime

No implementation neighborhood recorded.

Runtime observation: not tracked.

Evidence

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.

Impact
Relations of spec:decisions.agent-front-door
The diagram as text
  • spec:consumers.agent-surface: Agents script a visible typed graph
  • spec:consumers.agent-surface.evaluation-sink: The evaluation sink runs one body and prints its return
  • spec:consumers.agent-surface.recipe-parameters: Recipes take parameters as data and ship as runnable files
  • spec:consumers.context-bundle: A context bundle is composed per invocation within a stated budget
  • spec:consumers.reader: The reader bridges agent entry points to composable graph context
  • spec:consumers.reading-on-ramp: The reading skill teaches agents to query the graph
  • spec:decisions.agent-front-door: The agent front door is one evaluation sink over the exported reader
  • spec:decisions.agent-surface-scripts-graph: Agents script the visible graph
  • spec:decisions.agent-front-door dependsOn spec:decisions.agent-surface-scripts-graph · declared
  • spec:decisions.agent-front-door refines spec:consumers.agent-surface · declared
  • spec:consumers.agent-surface decidedBy spec:decisions.agent-front-door · declared
  • spec:consumers.agent-surface.evaluation-sink decidedBy spec:decisions.agent-front-door · declared
  • spec:consumers.agent-surface.recipe-parameters decidedBy spec:decisions.agent-front-door · declared
  • spec:consumers.context-bundle decidedBy spec:decisions.agent-front-door · declared
  • spec:consumers.reader decidedBy spec:decisions.agent-front-door · declared
  • spec:consumers.reading-on-ramp decidedBy spec:decisions.agent-front-door · declared
Mermaid source

Copyable source; the Studio draws static SVG.

Preferred syntax: flowchart. Chosen syntax: labelled flowchart, preserving exact relations, claims and folds.

Rests on

Rested on by

Distance 1

Distance 2

Distance 3

Distance 4

Distance 5

Relations

Relation and directionOther endClaimReasonExercised keys
dependsOn · outgoingAgents script the visible graph
spec:decisions.agent-surface-scripts-graph · resolves		declaredNoneNone
refines · outgoingAgents script a visible typed graph
spec:consumers.agent-surface · resolves		declaredNoneNone
decidedBy · incomingAgents script a visible typed graph
spec:consumers.agent-surface · resolves		declaredNoneNone
decidedBy · incomingThe evaluation sink runs one body and prints its return
spec:consumers.agent-surface.evaluation-sink · resolves		declaredNoneNone
decidedBy · incomingRecipes take parameters as data and ship as runnable files
spec:consumers.agent-surface.recipe-parameters · resolves		declaredNoneNone
decidedBy · incomingA context bundle is composed per invocation within a stated budget
spec:consumers.context-bundle · resolves		declaredNoneNone
decidedBy · incomingThe reader bridges agent entry points to composable graph context
spec:consumers.reader · resolves		declaredNoneNone
decidedBy · incomingThe reading skill teaches agents to query the graph
spec:consumers.reading-on-ramp · resolves		declaredNoneNone

Bindings

Implementation binding: none

Design reference: none

Verifier binding: none

Expected-outcome oracle: none

Runtime observation: not tracked.

Run results: not recorded in the graph.

Findings

None.

Composing (0)

Composing needs the script.