From Code to Shared Understanding

August 15, 2026 · View on GitHub

Workspai gives everyone the same understanding of your software, without asking you to replace your frameworks or move existing source code.

flowchart TB
    Sources["Projects · APIs · packages<br/>infrastructure · docs · CI"]

    Connect["Create · Adopt in place · Import"]

    Model["Canonical Workspace Model<br/>identity · inventory · boundaries"]

    Graph["Derived Knowledge Graph<br/>relationships · facts · canonical proof"]

    Decide["Diff · Impact · Evidence gates<br/>Readiness · Verify"]

    Ground["Reports · bounded context<br/>Agent sync · Explain"]

    Sources --> Connect
    Connect --> Model
    Model -->|derives, revision-bound| Graph
    Model --> Decide
    Graph --> Decide
    Decide --> Ground

    Ground --> Humans["Developers"]
    Ground --> Automation["CI · releases"]
    Ground --> Tools["IDEs · MCP · AI agents"]

What This Means

  1. Connect your software. Create something new, adopt an existing project without moving it, or import a repository.
  2. Understand the workspace. Workspai builds one model of the projects and how they relate. That Workspace Model is canonical. Workspai then derives a proof-backed Knowledge Graph from the model-owned project inventory so tools can query files, APIs, packages, infrastructure, tests, ownership, and decisions without creating a second source of truth.
  3. Understand change and verify it. Workspai shows affected areas and checks the evidence needed for a safe decision.
  4. Share the result. Developers, CI, IDEs, AI agents, and MCP clients consume the same workspace truth instead of building separate assumptions. The current CLI exposes the governed evidence through its reports, agent context, graph queries, and read-mostly workspace mcp serve bridge.

This is the user-facing view. The implementation uses a versioned chain of model, change, evidence, verification, context, grounding, and explanation steps. Contributors and integrations can inspect the complete contracts:

The unified runner also has a deterministic execution envelope: sync runs before Model and baseline resolution runs after Model/before Diff. These appear as two preflight entries, not as extra chain stages. The 11 canonical stages, baseline lifecycle, exit codes, and failure propagation are specified in Unified Workspace Intelligence Runner.

The npm README uses a PNG rendering because npm package pages do not reliably render Mermaid. npm also does not provide a dependable embedded-video player for package READMEs. Keep the full MP4 outside the published package. For inline motion, use a bounded, silent GIF hosted as a public asset; retain a linked MP4 for full-resolution playback and audio. When this source changes, regenerate From Code to Shared Understanding.png before publishing.

Execute the Contract

Run the complete canonical chain in its versioned order:

npx workspai workspace intelligence run --for-agent generic --json

For enterprise CI and release enforcement, add --strict. A warning or needs-attention verdict then produces a blocked report and exit code 2:

npx workspai workspace intelligence run --for-agent generic --strict --json

pipeline is the broader governance/release orchestrator. It does not replace or reorder the canonical Workspace Intelligence chain.