Architecture
Three contract-backed views of the Workspace Intelligence architecture, from its purpose to its complete evidence chain.
Workspace Intelligence turns observed software-system facts into evidence-backed understanding that developers, CI, IDEs, and AI agents can share. The same architecture is presented at three levels below. The detail changes; the meaning and boundaries do not.
Simple view
Use this view to understand the product in seconds.
This is a four-layer architecture:
- Inputs are facts and prior evidence observed from the software system.
- Workspace Intelligence evaluates those facts through one ordered chain.
- Evidence-backed outputs are durable artifacts, verdicts, context, and explanations.
- Consumers use the outputs without creating a second source of truth.
Standard view
Use this view to understand the complete intelligence loop without command-level detail.
| Phase | Human question | Contract steps |
|---|---|---|
| Understand | What exists in the current workspace? | Model |
| Change | What changed, and what can it affect? | Diff, Impact |
| Evidence | What health, contract, and readiness facts were observed? | Doctor Evidence, Contract Evidence, Analyze Evidence, Readiness Evidence |
| Gate | Is the current state acceptable and trustworthy? | Verify |
| Ground | What should an agent know before acting? | Agent Context |
| Distribute | Which durable agent and IDE surfaces receive that context? | Agent Grounding |
| Explain | Why did the system reach this result or verdict? | Explain |
The arrows are artifact flow, not a promise that every command must always run interactively. A consumer may execute a valid subset, but it must preserve step identity, dependencies, freshness, and verdict semantics from the contract.
Advanced view
Use this view when implementing a CLI, extension, CI workflow, documentation surface, or adapter.
| # | Step | Consumes | Produces |
|---|---|---|---|
| 1 | Model | workspace markers, project metadata, registry, contract, policies | .workspai/reports/workspace-model.json, .workspai/reports/workspace-knowledge-graph.json |
| 2 | Diff | .workspai/reports/workspace-model.json, .workspai/reports/workspace-model-snapshot.json | .workspai/reports/workspace-model-diff-last-run.json |
| 3 | Impact | .workspai/reports/workspace-model.json, .workspai/reports/workspace-model-diff-last-run.json | .workspai/reports/workspace-impact-last-run.json |
| 4 | Doctor Evidence | workspace runtime and project health signals | .workspai/reports/doctor-last-run.json |
| 5 | Contract Evidence | .workspai/workspace.contract.json | .workspai/reports/workspace-contract-verify-last-run.json |
| 6 | Analyze Evidence | .workspai/reports/workspace-model.json, workspace runtime and dependency signals | .workspai/reports/analyze-last-run.json |
| 7 | Readiness Evidence | doctor, analysis, runtime, and release signals | .workspai/reports/release-readiness-last-run.json |
| 8 | Verify | .workspai/reports/workspace-impact-last-run.json, .workspai/reports/doctor-last-run.json, .workspai/reports/workspace-contract-verify-last-run.json, .workspai/reports/release-readiness-last-run.json | .workspai/reports/workspace-verify-last-run.json, .workspai/reports/workspace-intelligence-history.json |
| 9 | Agent Context | .workspai/reports/workspace-model.json, .workspai/reports/workspace-impact-last-run.json, .workspai/reports/workspace-verify-last-run.json | .workspai/reports/workspace-context-agent.json |
| 10 | Agent Grounding | .workspai/reports/workspace-context-agent.json | .workspai/reports/INDEX.json, .workspai/reports/agent-customization-pack.json, .workspai/reports/workspace-skills-index.json, AGENTS.md |
| 11 | Explain | .workspai/reports/workspace-verify-last-run.json, .workspai/reports/workspace-impact-last-run.json | .workspai/reports/workspace-explain-last-run.json |
The canonical machine-readable definition is
contracts/workspace-intelligence-chain.v1.json. It defines ordering,
dependencies, commands, consumed and produced artifacts, exit policy, input and
output boundaries, and consumer rules. Prose and diagrams explain that contract;
they do not replace it.
The CLI executes that definition through one contract-backed entry point:
workspai workspace intelligence run --for-agent generic --strict --jsonEvery run publishes
.workspai/reports/workspace-intelligence-run-last-run.json, validated by
workspace-intelligence/workspace-intelligence-run.v1.json. The report records
each stage, status, duration, artifacts, exit code, and whether the overall run
passed, was blocked by a structured verdict, or failed operationally.
Contract boundaries
Inputs are observations, not marketing promises that every fact is always available.
Observed inputs
| Boundary | Observed sources | Enters at |
|---|---|---|
| Projects and repositories | projects, repositories, services, modules, imported paths | Model |
| Runtime and dependencies | runtime manifests, lockfiles, scripts, framework markers, package dependencies, bounded multi-language source observations for supported file extensions | Model |
| Workspace rules | workspace markers, registry, project metadata, contracts, policies, ownership, graph overrides | Model |
| Changes | repository state, git state, model baseline, workspace diff | Diff |
| Explicit model baseline | .workspai/reports/workspace-model-snapshot.json | Diff |
| Existing evidence | doctor reports, analysis reports, contract verification, release readiness, pipeline results, tests and runtime evidence, previous intelligence artifacts | Doctor Evidence |
Evidence-backed outputs
| Output family | Artifacts | Produced by |
|---|---|---|
| System understanding | .workspai/reports/workspace-model.json, .workspai/reports/workspace-knowledge-graph.json, .workspai/reports/workspace-model-diff-last-run.json, .workspai/reports/workspace-impact-last-run.json | model, diff, impact |
| Governance evidence | .workspai/reports/doctor-last-run.json, .workspai/reports/workspace-contract-verify-last-run.json, .workspai/reports/analyze-last-run.json, .workspai/reports/release-readiness-last-run.json, .workspai/reports/workspace-verify-last-run.json, .workspai/reports/workspace-intelligence-history.json | doctor-evidence, contract-evidence, analyze-evidence, readiness-evidence, verify |
| Agent grounding | .workspai/reports/workspace-context-agent.json, .workspai/reports/INDEX.json, .workspai/reports/agent-customization-pack.json, .workspai/reports/workspace-skills-index.json, AGENTS.md | context, agent-sync |
| Explainable decisions | .workspai/reports/workspace-explain-last-run.json | explain |
Existing evidence appears at the input boundary because previous reports and live checks are observations consumed by the current run. It is not the same as the normalized Governance evidence produced by the chain.
A report records a command result. An artifact is any durable output that another consumer can read. A gate turns current evidence into a structured pass, warning, or blocking verdict.
Workspace identity boundary
The architecture also includes a workspace identity boundary. Workspace Intelligence depends on the same workspace being discoverable from terminals, CI, IDEs, and agents.
That boundary is what lets workspace list, workspace sync, create, adopt,
import, and agent grounding refer to the same software system instead of
creating parallel views of it.
Consumer boundary
Developers, CI, IDEs, and AI agents consume the same structured outputs through different channels. They may render the information differently, but must not rename steps, omit dependencies, infer freshness, or reinterpret a failed gate as success.
Graph inspection, watch mode, MCP serving, and future cloud surfaces are capabilities around this architecture. They expose or accelerate the same model and evidence; they are not additional mandatory steps in the canonical chain.
Three operational protocols also sit beside the chain:
- Doctor diagnosis classifies causal findings, capabilities, unknowns, and repair posture consumed by Readiness and Verify.
- Workspace Run plans and executes polyglot lifecycle units, then publishes
.workspai/reports/workspace-run-last.jsonfor verification. - Repair Engine owns the transaction from immutable plan and approval to checkpoint, mutation, exact-producer refresh, verification, and closure or rollback.
These protocols can produce evidence consumed by the chain, but they do not rename its stages or become hidden extra stages. See Polyglot Lifecycle Orchestration and Verified AI Repair.
Evidence principle
Evidence is the source of understanding; documentation is an output, not the authority.
Agent Skills and Grounded Context
Learn how Workspai gives coding agents shared instructions, focused graph evidence, and current workspace context without turning prompts into a second source of truth.
Workspace Model
The canonical representation of projects, runtimes, commands, policies, contracts, and evidence.