WorkSpec Studio

Design an application with your agent, derive its infrastructure needs, compare Azure and AWS, record the ADR, and export the complete .workspec workspace.

Comment

Inspiration

Architecture decisions usually fragment across diagramming tools, spreadsheets, cloud pricing tabs, chat transcripts, and ADR documents. The diagram stops matching the estimate; the rationale disappears; and the final artifacts are trapped in somebody else's database.

We built WorkSpec Studio to make architecture a shared, inspectable workflow between a person and an AI agent, with portable files as the durable result.

What it does

WorkSpec Studio takes a project through one connected journey:

  1. Design the application as an interactive C4 model.
  2. Derive an editable, provider-neutral infrastructure shopping list from its deployable elements.
  3. Map the same requirements to Azure and AWS and compare deterministic monthly planning estimates.
  4. Prepare and review the cloud-platform decision.
  5. Record the approved choice as an architecture decision record.
  6. Download the complete .workspec workspace as a ZIP.

A user can start blank, load an example, or import an existing .workspec bundle. The C4 canvas supports context, logical-container, and deployment views. People can create, move, connect, and edit elements directly; the agent can propose or arrange the same model through WebMCP.

The resulting workspace is schema-validated YAML that can be reviewed in the browser, committed to Git, used by WorkSpec command-line tools, or consumed by a hosted WorkSpec Enterprise installation.

Why WebMCP

Architecture work combines two different strengths. Agents are good at turning intent into a coherent first draft and tracing consequences across many artifacts. People are responsible for understanding the system, correcting assumptions, weighing trade-offs, and approving durable decisions.

Without WebMCP, an agent must manipulate a complex infinite canvas with fragile pointer automation or edit files somewhere outside the UI the person is reviewing. WorkSpec's WebMCP tools connect both participants to the same live browser-local workspace.

The agent can create a structured C4 proposal in one operation while the person immediately sees a real diagram they can drag and edit. The infrastructure list is derived from that same model, the provider comparison uses that same list, and the ADR is generated only from the visible draft the person has approved. Every successful agent operation appears in a collapsible Agent activity history.

How we built it

The workbench is a TypeScript and React monorepo composed from reusable WorkSpec packages for C4 schemas and rendering, infinite-canvas interaction, topology planning, provider mapping, decisions, ZIP workspaces, and the shared Studio shell.

The page registers eleven bounded tools with document.modelContext.registerTool(). They let an agent inspect the workspace, navigate the gated workflow, control relevant sidebars, create a complete C4 architecture, inspect and pin diagram layout, update infrastructure requirements, compare providers, prepare an unsaved decision, record a reviewed decision, and export the workspace ZIP.

All tool inputs use closed JSON schemas. Handlers resolve the current application state through stable action references, and registrations share an AbortController so React Strict Mode cannot leave duplicate tools behind. Human UI actions and agent tools operate on the same canonical MemoryWorkspace.

The cloud estimates are deterministic planning figures rather than live quotes, keeping the comparison reproducible. Provider-specific choices do not leak into the source architecture or neutral requirements.

Human review is part of the protocol

The decision flow is intentionally split into two tools. prepare_cloud_decision opens the Decision page and fills a visible, editable provider and rationale draft. record_cloud_decision rejects calls until that draft exists and is used only after explicit human approval. This makes review a real product boundary, not a sentence in an agent prompt.

The export tool returns the exact current workspace as a bounded base64 ZIP. That gives agents a reliable handoff even in browser environments where clicking a download button is awkward, while people retain the ordinary visible download control.

Challenges we faced

The biggest challenge was making an infinite visual canvas genuinely agent-operable without taking control away from the person. We added semantic architecture and layout tools rather than exposing cursor coordinates, while keeping every generated node editable and draggable.

We also had to keep one canonical state across four routed stages, preserve unknown files during ZIP round trips, prevent stale React closures in registered tools, and make irreversible decision recording impossible before a visible draft exists.

Accomplishments we're proud of

  • One continuous Design → Infrastructure → Compare → Decision story.
  • A real C4 canvas that supports both semantic WebMCP operations and direct human editing.
  • Provider-neutral requirements with traceability back to architecture elements.
  • Like-for-like Azure and AWS mappings and monthly estimates.
  • A visible approval gate before ADR generation.
  • Complete .workspec ZIP import and export.
  • Eleven WebMCP tools plus a clear Agent activity history.
  • More than two thousand automated tests across the WorkSpec packages and applications.

What we learned

The best WebMCP tools describe meaningful product operations, not DOM gestures. A tool such as "prepare a decision for review" is more robust and more understandable than a sequence of clicks, and it lets the UI enforce the same rules for both humans and agents.

We also learned that shared visibility matters as much as capability. The strongest moments are not when the agent finishes everything invisibly; they are the pauses where a proposal appears in the real UI, the person edits or approves it, and both continue from the same state.

What's next

Azure and AWS are the first provider adapters. The provider-neutral model is designed for additional clouds, on-premises targets, live pricing catalogs, policy checks, and organization-specific mapping rules. We also plan to reuse the extracted Studio packages directly inside WorkSpec Enterprise.

Try it

Live app: https://studio.workspec.io/

Source: https://github.com/FieldstateNZ/workspec-studio

Suggested prompt:

Help me design Orderlight, an online ordering system that takes payment through an external gateway and fulfils accepted orders asynchronously. Build the C4 architecture, derive and review the infrastructure plan, compare Azure and AWS, and prepare a recommendation. Stop for my review at every stage and do not record the decision until I explicitly approve it.

Built With

Share this project:

Updates

Submission history