MagWorksManaged Intelligence

The product

Studio — how Solutions are made

In plain language

Studio is the workshop. It is where Matter & Gas turns a client's need into a working Capability: write the instructions (a Prompt), attach the material it should draw on (Knowledge), bind those into a single action (a Skill), connect actions into a flow (a Capability), prove it behaves (an Evaluation Suite), publish it, and then watch it run. Nothing reaches a client without passing through publication, and publication is a gate with evidence.

The mechanism

The objects, in operator vocabulary

Object What it is
Prompt reusable instruction text with declared inputs and a runtime version pointer
Knowledge a named corpus of documents the platform retrieves from at run time
Skill one reusable AI action, bound to exactly one primitive, binding a Prompt + Model + optional Knowledge
Recipe a reusable workflow composed of Skills
Capability the customer-facing unit: one or more Skill steps connected by next / onError
Evaluation Case one input plus expected outcomes
Evaluation Suite a bundle of cases run together to certify a Capability version

A Skill's primitive is chosen at creation and cannot be changed; Knowledge must be published before a Skill can bind it; a Capability is invocable only after publication flips its pointer — saving is not publishing.

The authoring lineage

   Prompt ──────┐
   Knowledge ───┤
                ▼
              Skill ──────┐
                          ▼
                       Capability ── activate ──► Workflow Pointer ──► Workflow Definition
                                                                              │
                                                                              ▼
                                                                     Capability Resolution
   Evaluation Case ──┐
                     ▼
              Evaluation Suite ── run ──► eval-run linkage + S3 archive
                                                   │
                                                   └── Evidence ──► gates publication

The primitive registry

Skill primitives are a closed enumeration owned by the platform (I-8). The registry today admits identities in the families llm.* (generate, classify, extract, summarize, judge, embed), context.* (assemble, project), human.* (acknowledge), tool.* (invoke, fetch, publish) and flow.* (terminal). Primitive identity is persisted explicitly on the authored definition and reaches the runtime only through compilation — the resolver — never by the runtime reading Studio's tables (ADR-0008).

Publication is a transaction with evidence

Publication compiles the composition into a workflow definition (idempotent on content hash), writes the Capability Resolution row (idempotent on capability + version + hash), flips the Workflow Pointer with a conditional write — the atomic commit — and appends a CapabilityPublishCompleted ledger entry that carries the evalRunRef of the evidence that backed it. Failure before the flip leaves the version in evaluated with idempotent partial substrate; retry resumes from the failed step.

The capability's evaluation namespace governs the gate: primarySuiteId names the suite, freshnessDays how old a passing run may be, and mode whether evidence is advisory or required. Under required, activation verifies the cited evidence against the substrate's archive before the pointer moves.

Operating

Every run appears with its cost attributed; reviews appear in a queue; Capability Intelligence synthesises usage, cost, reliability and quality per Capability. Runs can be inspected down to each action's input snapshot, output and timing. Operator surfaces use operator vocabulary throughout — substrate identifiers appear only in Expert mode (I-28) — and never synthesise a value to fill a screen (I-29).

The screens

Studio is 40 routes under /admin/studio: capabilities (index, new, composition, edit, history, operate, intelligence, runs), skills, recipes, prompts, knowledge, library, models, test (cases, suites, runs), operate (inquiries, reviews, runs), solutions, platform (primitives, limits), the build workspace and the copilot.

The copilot

Studio has a grounded copilot — itself a published Capability on the platform, granted a platform-owned corpus of Studio documentation — that can draft definitions for the operator to validate and save. It runs through the same publication, grant and ledger machinery as any client Solution.

Design notes

  • Why publication carries evidence (Layer 3 ADR-0007). A published version previously carried no durable record of the evaluation that backed it; the question "what evidence supported publishing version N?" had no answer beyond logs. The publication ledger entry became the canonical provenance record so the answer is one row.
  • Why the resolver is the only bridge (ADR-0008). If Studio owned compilation it would acquire substrate knowledge and leak it into operator vocabulary; if the substrate owned compilation it would have to read Studio's authoring format. Neither placement is correct, so compilation lives in one place that knows both and is owned by neither.
  • Why one AppSync API with a shared data source per host Lambda (ADR-0011). The generated resolver pattern cost six CloudFormation resources per operation and hit the hard 500-resource limit at 83 operations. The standard pattern now costs two, with budgets that warn at 350 and refuse at 425.

Sources

  • matterandgas-com/docs/user-guide/compendium.md — objects, lineage, rules.
  • matterandgas-com/docs/architecture/object-specifications.md (OBJ-1.7) — publication atomicity, invariants INV-CAP-, INV-CFG-, INV-DOC-*.
  • matterandgas-com/docs/adr/0007, 0008, 0009, 0011.
  • matterandgas-com/amplify/functions/studio-publication/orchestrator.ts.
  • matterandgas-com/app/admin/studio/ — the routes.