Memory
## Map Definition Tools for External LLM (Work Engineering MCP Surface) **Date:** 2026-09-08 **Status:** Design addition **Related:** Work Engineering in the Workspace DO, Work Engineering Map v0, GlassAgent workspace agent, MCP tool portals ### Problem The external LLM (e.g. Claude, GPT, Perplexity) needs to **define the work** — i.e. create the Work Engineering map (Work Objects, Routings, Workstations, Contracts) — but should not need to understand the internal storage model (Artifacts tree structure, SQLite schema, etc.). The workspace DO must expose a **simple, easy-to-follow MCP tool surface** that allows an external LLM to: 1. **Discover** what work definitions already exist. 2. **Define** new work (Work Objects, Routings, Workstations, Contracts). 3. **Validate** that the definition is coherent (no cycles, all references exist, etc.). 4. **Activate** the map (make it the current working definition). This is the "probabilistic shell proposes" part of the GlassAgent model — the external LLM defines the work, the DO enforces it deterministically. [mikesecondbrain:2][mikesecondbrain:3] ### Design principles 1. **Map-as-code, but LLM-friendly** — The map is stored as JSON/Markdown in Artifacts, but the LLM interacts via high-level MCP tools, not raw file writes. 2. **Contract-first** — Every definition must reference or imply a contract (even if minimal). 3. **Incremental** — The LLM can define work in small pieces (one Work Object, one Routing, etc.), not all at once. 4. **Validated** — The DO validates coherence before activation (no dangling references, no cycles in routings, etc.). 5. **Versioned** — Each map definition is versioned; activation creates a new "working version". 6. **Reversible** — Definitions can be superseded or deprecated, not just overwritten. ### Proposed MCP tool surface #### Discovery tools ```typescript // Get a high-level summary of the current work map getWorkMapBrief(): { workObjects: count, routings: count, workstations: count, contracts: count, activeVersion: string, lastModified: timestamp } // List work objects (optionally filtered) listWorkObjects(filter?: { kind?: string, parentId?: string }): WorkObjectSummary[] // List routings listRoutings(): RoutingSummary[] // List workstations listWorkstations(): WorkstationSummary[] // List contracts listContracts(): ContractSummary[] // Get full definition of a work object getWorkObject(id: string): WorkObjectDefinition // Get full definition of a routing getRouting(id: string): RoutingDefinition // Get full definition of a workstation getWorkstation(id: string): WorkstationDefinition // Get full definition of a contract getContract(id: string): ContractDefinition // Search the work map (FTS5-backed) searchWorkMap(query: string): SearchResult[] ``` #### Definition tools ```typescript // Define a new work object defineWorkObject(input: { id?: string, // optional, DO generates if not provided name: string, description?: string, parentId?: string, // optional, for hierarchical work objects metadata?: Record<string, any> }): { id: string, ok: true } // Define a new workstation defineWorkstation(input: { id?: string, name: string, description?: string, kind: 'production' | 'quality', capabilities?: string[], // e.g. ['read_file', 'write_file', 'call_model'] workingAreas?: string[], // e.g. ['documents/', 'evidence/'] contractId?: string, // optional, can be added later metadata?: Record<string, any> }): { id: string, ok: true } // Define a new contract defineContract(input: { id?: string, name: string, description?: string, inputs: string[], // work object IDs outputs: string[], // work object IDs rules?: string[], // human-readable rules evidenceRequirements?: string[], metadata?: Record<string, any> }): { id: string, ok: true } // Define a new routing defineRouting(input: { id?: string, name: string, description?: string, workObjectId: string, // the work object this routing produces stationIds: string[], // ordered list of workstation IDs variant?: string, // e.g. 'standard', 'fast-track' metadata?: Record<string, any> }): { id: string, ok: true } // Link a workstation to a contract (if not done at definition time) linkWorkstationToContract(workstationId: string, contractId: string): { ok: true } // Validate a routing (check coherence, no cycles, all stations exist) validateRouting(routingId: string): { ok: true, errors: string[], warnings: string[] } // Validate entire work map validateWorkMap(): { ok: true, errors: string[], warnings: string[] } ``` #### Activation tools ```typescript // Activate a routing as the current working definition activateRouting(routingId: string): { ok: true, activeVersion: string, activatedAt: timestamp } // Deactivate current routing (return to no active routing) deactivateRouting(): { ok: true } // Get current active routing getActiveRouting(): RoutingDefinition | null ``` #### Revision tools ```typescript // Supersede a definition (create new version, mark old as superseded) supersedeWorkObject(id: string, patch: Partial<WorkObjectDefinition>, reason: string): { newId: string, oldId: string } // Deprecate a definition (mark as deprecated, do not use for new lots) deprecateWorkObject(id: string, reason: string): { ok: true } // Similar for workstations, contracts, routings ``` ### Example flow (external LLM defining work) 1. **Discover current state** ```typescript const brief = await getWorkMapBrief() // => { workObjects: 0, routings: 0, workstations: 0, contracts: 0, activeVersion: null } ``` 2. **Define work objects** ```typescript const meetingAudio = await defineWorkObject({ name: 'Meeting Audio', description: 'Raw meeting recording file' }) const transcript = await defineWorkObject({ name: 'Transcript', description: 'Transcribed text from meeting audio', parentId: meetingAudio.id }) const approvedNotes = await defineWorkObject({ name: 'Approved Notes', description: 'Human-reviewed notes from meeting' }) ``` 3. **Define contract** ```typescript const notesContract = await defineContract({ name: 'Notes Approved Contract', description: 'Notes must capture all decisions and action items from the meeting', inputs: [transcript.id], outputs: [approvedNotes.id], rules: [ 'Notes must capture every decision from the transcript', 'Notes must capture every action item from the transcript' ], evidenceRequirements: [ 'Human reviewer must cite transcript evidence', 'Reviewer must confirm completeness against transcript' ] }) ``` 4. **Define workstations** ```typescript const ingestStation = await defineWorkstation({ name: 'Ingest Audio', kind: 'production', capabilities: ['read_file', 'write_artifact'], workingAreas: ['documents/', 'evidence/'] }) const transcribeStation = await defineWorkstation({ name: 'Transcribe', kind: 'production', capabilities: ['call_model', 'write_artifact'], workingAreas: ['documents/', 'evidence/'], contractId: notesContract.id }) const reviewStation = await defineWorkstation({ name: 'Review Notes', kind: 'quality', capabilities: ['read_artifact', 'search_fts', 'record_evidence', 'submit_quality_decision'], workingAreas: ['documents/', 'evidence/'], contractId: notesContract.id }) ``` 5. **Define routing** ```typescript const routing = await defineRouting({ name: 'Meeting Audio to Notes', description: 'Standard workflow for transcribing and approving meeting notes', workObjectId: meetingAudio.id, stationIds: [ingestStation.id, transcribeStation.id, reviewStation.id], variant: 'standard' }) ``` 6. **Validate** ```typescript const validation = await validateRouting(routing.id) // => { ok: true, errors: [], warnings: [] } ``` 7. **Activate** ```typescript const activation = await activateRouting(routing.id) // => { ok: true, activeVersion: 'v1', activatedAt: '2026-09-08T23:00:00Z' } ``` Now the external LLM has defined a complete work map, and the DO can execute it. ### Implementation notes #### Storage - Definitions stored in Artifacts tree (`/work/objects/`, `/work/routings/`, etc.) as JSON. - SQLite tables for fast queries (derived from Artifacts). - FTS5 index for `searchWorkMap()`. #### Validation rules - All referenced IDs must exist (workstations in routing, inputs/outputs in contract, etc.). - No cycles in routing (station A → station B → station A). - At least one production station before any quality station (can't start with quality). - Quality stations must have a contract linked. - No orphaned work objects (every work object should be referenced by at least one routing or contract). #### Versioning - Each definition has `version`, `supersededBy`, `supersedes` fields. - Activation creates a new "map version" record. - Lots reference the map version they were created under. #### Security - External LLM can only define work, not execute it (execution requires operator callsign). - Definitions are validated before activation. - Activation may require human approval (configurable). ### Relationship to existing patterns - **Work Engineering Map v0** — This is a higher-level abstraction on top of the v0 RPC surface. The v0 methods (`createWorkObject`, `defineRouting`, etc.) are used internally, but the external LLM sees a simpler, more guided surface. [mikesecondbrain:1] - **GlassAgent workspace agent** — The external LLM plays the "probabilistic shell proposes" role; the DO enforces deterministically. [mikesecondbrain:2][mikesecondbrain:3] - **MCP Portal** — These tools would be exposed via the gatekeeper-MCP portal, with appropriate scopes (e.g. `work-map:write`, `work-map:read`). [mikesecondbrain:1] ### Open questions 1. **Template support** — Should there be pre-defined templates (e.g. "Meeting notes workflow", "PR review workflow") that the LLM can instantiate? 2. **Human approval** — Should map activation require human approval, or can the LLM activate directly? 3. **Multi-map support** — Can multiple routings be active at once (for different work types), or only one at a time? 4. **Migration** — If a routing is updated, what happens to in-flight lots? (Probably: they continue under the old version; new lots use the new version.) ### Next steps 1. **Define minimal JSON schema** for Work Object, Workstation, Contract, Routing. 2. **Implement MCP tools** in the workspace DO (or as a wrapper around the v0 surface). 3. **Test with external LLM** — Have Claude/GPT define a simple workflow via these tools. 4. **Document the pattern** — Example flows, validation rules, error messages. --- **Note:** This is a design addition to the Work Engineering in the Workspace DO model. It focuses on making map definition accessible to external LLMs without exposing internal complexity.
Tags: work-engineering, mcp-tools, map-definition, external-llm, glassagent, workspace-do, design-addition, volatility:state, kind:episodic — Source: mcp — 2026-09-08 22:59:40 UTC