# ADR-0009 — Toolsmith supervisor, Skill Graphs, and specialist application agents - **Status:** Accepted architecture; Phases 0–2 implemented; application-specialist expansion and representative production qualification remain in progress - **Date:** 2026-08-06 - **Depends on:** ADR-0006 Fabric Core Intelligence; ADR-0008 Autonomous Physical Toolsmith - **Goal:** Fabric → Toolsmith → Skill Graph → Photoshop/Unity specialists completes commissioned production goals without interactive application work while retaining exact authority and proof. ## Decision Toolsmith becomes the accountable production supervisor. Photoshop and Unity become specialist execution agents. Fabric remains the only owner of durable state, policy, routing, approvals, effects, evidence, certification, publishing and commissioning. ```text Fabric runtime and event spine └─ Toolsmith supervisor ├─ Skill Graph registry and compiler ├─ Asset Intelligence ├─ Photoshop specialist → typed Fabric UXP runtime → Photoshop ├─ Unity specialist → typed Toolsmith package / MCP → Unity ├─ independent validation specialist └─ recovery and risk services ``` Specialists do not converse freely and do not receive open-ended tool access. Toolsmith issues a typed child task; the specialist returns a typed result; Fabric appends both to the shared run and deterministically decides the next graph transition. ## Meaning of autonomous The production target is **zero-touch execution for a commissioned Skill Graph inside a pre-authorized resource and effect envelope**. A normal run may inspect, plan, edit, validate, recover and finish without a person clicking Photoshop or Unity. It is not a promise that any natural-language request can safely perform any application action. An unknown operation, missing authoritative input, new project schema, destructive effect outside scope, or capability-build dead end stops safely. Toolsmith may create and qualify an isolated candidate, but the builder cannot certify, publish or commission its own authority. ## Abstraction hierarchy ```text Capability one exact registered and verified provider operation Skill a sealed DAG of capabilities with typed handoffs Expert Skill a versioned project/domain pack: skill + SOP + examples + recovery + tests Workflow a commissioned goal contract composed from Expert Skills ``` Every layer carries its own digest. Changing a child capability, graph, knowledge revision, validator, compatibility range or recovery policy invalidates downstream certification. ## Required contracts 1. `fabric.skill-graph.v1` — nodes, dependencies, joins, effects, capability bindings, input/output schemas, validators, recovery edges, compatibility and graph digest. 2. `fabric.specialist-task.v1` — parent run, child task, assigned specialist, objective, allowed capabilities, resource scope, artifacts, completion criteria, risk, budget and retry limit. 3. `fabric.specialist-result.v1` — status, observations, produced artifacts, validations, changes, warnings, confidence and one recommended transition. Prose alone has no authority. 4. `fabric.expert-pack.v1` — cited SOP sources, executable Skill Graphs, examples, failure taxonomy, tests, version compatibility, certification and project applicability. 5. `fabric.supervisor-run.v1` — append-only shared goal, graph revision, child states, artifacts, evidence, approvals, retries, checkpoints, unresolved criteria and final verdict. ## Comparison with the current implementation | Proposal | Current state | Required convergence | |---|---|---| | Toolsmith as cross-tool supervisor | Physical team assignment exists, but one plan targets one application | Add a durable supervisor run that owns multiple specialist child tasks and graph transitions | | Typed parent/child contracts | Bounded advisory children and typed physical plans exist | Add application-specialist task/result schemas and persist them on the event spine | | Shared authoritative state | Run journal, artifact manifests, approvals and event spine exist separately | Project one supervisor-run state from those canonical events | | Skill Graphs | Executable skills are flat stage lists; physical plans are primitive sequences | Add first-class certified DAGs above the capability registry | | Photoshop specialist | Governed deterministic JSX compiler and bridge are live-qualified | Add a versioned typed UXP RPC plugin and semantic document/layer model | | Unity specialist | All installed MCP handlers plus four Toolsmith semantic operations are registered | Expand versioned semantic adapters for importer, prefab, scene, ScriptableObject, build and recovery families | | Asset Intelligence | RAG, production graph and artifact lineage exist | Add one typed asset taxonomy/template/destination/dependency decision service | | Independent validation | Outcome Verifier and deterministic postconditions exist | Add graph-level blind validation over cross-tool handoffs and unexpected diffs | | Expert Knowledge Packs | SOPs can be taught to RAG; executable skill contracts are optional | Compile cited SOP revisions into reviewable Expert Pack candidates; never execute prose directly | | Cross-tool recovery | Per-plan verification and recovery advice exist | Add typed repair edges and resume checkpoints across Photoshop → Unity → Photoshop | | Zero-touch production | Live disposable pilots pass | Commission individual graphs after representative real-ticket qualification | ## Phase plan ### Phase 0 — Ephemeral application infrastructure — implemented - Keep `com.forge.fabric-toolsmith` under Fabric source control. - Deploy its exact digest into a Unity project only for a governed operation. - Store the byte-for-byte `Packages/manifest.json` recovery snapshot in Fabric-owned runtime state. - Wait for the exact extension session, execute, and restore on success or failure. - Refuse to overwrite a concurrent manifest change and retain restoration-required evidence. ### Phase 1 — Skill Graph kernel - Implement the five contracts above and canonical digests. - Validate acyclic dependencies, typed handoffs, exact capability bindings and effect closure. - Compile each application partition to the existing physical-operation IR. - Add graph certification, compatibility invalidation and Capability Center maturity. **Exit:** a static Photoshop → artifact handoff → Unity graph compiles and dry-runs with no model authority. **Implemented foundation (6 August 2026):** `fabric.skill-graph.v1` now validates semantic versions, acyclic dependencies, typed handoffs, effect closure and exact production runtime bindings. It seals canonical digests, stores only candidate lifecycle state at registration, compiles application partitions through the existing physical-operation spec/compiler, and keeps generic handoff and validator controls non-qualifying. `fabric.expert-pack.v1` binds cited source revisions, graph digests, examples, failure taxonomy, validators and compatibility. The first Offers pack completed an exact no-write qualification; it remains a candidate and is not certified, published or commissioned. ### Phase 2 — Toolsmith supervisor runtime - Durable parent/child state machine and event-spine projection. - Dynamic selection only among certified graphs and capabilities. - Bounded specialist local plans constrained by the parent graph. - Joins, checkpoints, cancellation, idempotency and uncertain-completion reconciliation. **Exit:** interruption and restart resume from the last verified handoff without replaying effects. **Implemented (6 August 2026):** `fabric.supervisor-run.v1`, `fabric.specialist-task.v1` and `fabric.specialist-result.v1` are projected from the signed Event Spine. Dry runs can inspect candidates with zero write authority. Execute mode rejects graphs that are not independently certified for their exact digest and separately commissioned for the exact resource scope; caller-supplied lifecycle fields are ignored, and execution requires an authoritative governance resolver. Results must name the assigned specialist, retain observable evidence and validation, and the run cannot complete until an independent validator task is verified. The supervisor dispatches a contiguous Photoshop mutation sequence as one sealed specialist partition, so duplicate/replace/export safety cannot be split across independent effects. Full plans are content-addressed Fabric artifacts referenced by signed events; resume verifies the bytes before dispatch because the Event Spine deliberately bounds deeply nested payloads. A no-write qualification traverses the exact partitions and controls, attaches its digest to the signed run, and grants no certification or commissioning. The registered validator control is not validation authority: qualification stops with a signed external-review request, and only a separately configured validator event store plus pinned Ed25519 trust root can issue and complete the exact corpus/result-bound receipt consumed once by certification. A commissioned run can now advance automatically through sealed application partitions, real byte-sealing handoffs and a separately supplied independent validator. Named failure codes may follow only a registered recovery edge within its attempt bound; the owning atomic partition and its dependants are reset together. Unknown completion enters a durable reconciliation-required state and cannot replay until an identified independent validator records actual-state observations. Studio exposes separate list, validate, register, no-write qualify and certify service actions. Production workload qualification remains external release evidence rather than a repository-test claim. **Implemented control-plane closure (7 August 2026):** Studio provides a guided no-write builder for the graph's exact fenced Jira input contract. It validates types, rejects unknown keys and path traversal, and proves absolute Photoshop paths remain under explicit roots before producing a copyable block. Commissioning accepts Confluence page URLs but does not trust browser-provided revision or digest claims: the backend fetches the current page, derives both values, records a signed Event Spine observation and seals that binding. The drift monitor repeats the authoritative SOP lookup and the live typed Photoshop/Unity readiness probes; missing evidence suspends. The UXP provider is now a first-class setup surface. An explicit admin action creates owner-only local token and qualification files, starts only loopback services and returns the pairing token once for Adobe UXP Developer Tool. The nine deeper Photoshop candidates bind to the exact `fabric-photoshop-uxp` provider. A durable request-identity ledger records uncertain completion; only named read-only inspection is permitted, and resolution requires an identified operator, decision and evidence. Reconciliation never invokes or replays the original mutation. Capability Center also routes a generic candidate back to the current graph digest and selected Studio node; only that exact context can enter the existing supported-family Toolsmith compiler. ## Reviewed external provider surfaces Two public MIT-licensed projects were reviewed and pinned as non-executable provider records: - **Unity-Skills** at `d8a5d487b5ad25886a389dd305da35b0a9a1ecb5` is a useful possible Unity provider because it reports a large typed REST surface, dry-run/plan metadata, per-operation risk, batch transactions, persistent rollback, audit and multi-instance discovery. Fabric will deploy only a reviewed pinned package on demand, never use Bypass mode, and import discovered operations as inert acquisition candidates. Raw C#, arbitrary scripts/reflection, unrestricted menu actions and every unbound operation remain unavailable. - **photoshop-connection** at `cae91338879a546b94cb3c699d083397ef0286de` is useful only as an optional sealed transport behind Fabric's deterministic typed compiler. Its encrypted socket and transaction dispatch do not provide Fabric governance, and its arbitrary ExtendScript execution must never be planner-visible. It does not replace the planned UXP semantic runtime. Upstream feature statements are provider claims until Fabric independently tests the exact pinned revision. Review, installation, handler registration, qualification, certification, publishing and commissioning remain distinct. The pinned Unity-Skills qualification adapter now enforces that boundary in code: only operations listed in the reviewed revision can be requested, only in Standard dry-run mode, and the response must bind the exact revision, operation, transaction plan, rollback and audit identity. Bypass, embedded code and unreviewed operations fail closed. A successful receipt is still an inert adapter candidate, not a handler registration or production capability. ### Phase 3 — Photoshop specialist and UXP runtime - Typed RPC plugin; no raw model-authored `batchPlay`, JSX or arbitrary method names. - Semantic document/layer tree, role resolution, Smart Objects, masks, text, effects, comps, profiles, checkpoints and typed export presets. - Visual QA: bounds, alpha, safe area, OCR/overflow, reference comparison and output reopening. - Failure taxonomy for fonts, links, locks, templates, profile mismatch and export recovery. **Exit:** commissioned Photoshop skills complete representative tickets with no application clicks, source corruption or unverifiable export. ### Phase 4 — Unity specialist semantic runtime - Typed importer, sprite/atlas, prefab, scene, ScriptableObject, Addressables/bundle, compilation, test and build skills. - Stable serialized/reference identity; no coordinates and no arbitrary reflection or C#. - Checkpoints and compensation for import loops, GUID/meta drift, reload, package and compile faults. **Exit:** commissioned Unity skills complete representative tickets with exact diffs, clean compile, references, tests and rollback. ### Phase 5 — Asset Intelligence and Expert Packs - Ingest exact Confluence/Jira/repository revisions as evidence, not commands. - Produce reviewable pack candidates containing taxonomy, templates, destinations, examples, validators, recovery and Skill Graphs. - Certify packs per game, application version and project schema. **Exit:** Character, Flat Art, Offers, Dialogue and Ability packs select the correct certified graph without guessing project conventions. ### Phase 6 — Cross-specialist recovery and independent validation - Route typed failures to the owning specialist without restarting completed work. - Blind validator consumes source facts and actual artifacts, not the creator's conclusion. - Adversarial tests cover unavailable tools, partial effects, timeouts, conflicting project changes, invalid references, visual mismatch and rollback failure. **Exit:** every known recoverable failure either repairs and revalidates or stops at a durable exact blocker. ### Phase 7 — Workflow qualification and commissioning Qualify separately: Offer Icon, Ability Icon, Flat Art Import, Character Pipeline, Dynamic Dialogue and other workflows. Each exact graph revision needs real-ticket coverage, application/version compatibility, zero unauthorized writes, zero fabricated completion, bounded recovery and human acceptance. Certification, publishing and commissioning remain separate actions. **Exit:** a commissioned workflow runs zero-touch in its scope; an uncommissioned graph cannot run. ## First vertical slice Build `CreateOfferIconAndIntegrate.v1`: 1. Asset Intelligence selects one approved template and destination from cited evidence. 2. Photoshop specialist inspects semantic roles, replaces the Smart Object, validates and exports. 3. Artifact handoff seals bytes, dimensions, alpha, color space, lineage and validation. 4. Unity specialist imports, applies one certified importer profile, wires one existing offer schema, compiles and validates references. 5. Independent validation checks the goal, actual bytes, Unity state and unexpected diffs. 6. Toolsmith either completes, follows one typed recovery edge, or stops safely. No commit, push, ticket transition, publish or commission is implicit in this slice. ## Non-negotiable invariants - No raw model-authored code crosses into Photoshop or Unity. - No generic control qualifies a missing semantic capability. - No specialist can widen roots, effects, tools or completion criteria. - No creator validates its own final result alone. - No provider-success response substitutes for observable postconditions. - No unknown completion is retried before reconciliation. - No graph self-certifies, self-publishes or self-commissions. - “Anything” always means anything covered by an installed, certified Expert Pack and commissioned workflow—not unrestricted desktop or repository authority.