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 |
| 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.
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, supported source imports (currently bounded JavaScript and TypeScript scanning) | 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-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.
Evidence principle
Evidence is the source of understanding; documentation is an output, not the authority.