# How Sphere works

Sphere connects intent to a checked result through one loop, always grounded in the system model — **Architecture as Code**, like a house blueprint that builders and inspectors share.

## The blueprint metaphor

A SCAN/Sphere model is the **living blueprint** of your system: components, connections, technology, and decisions. Coding agents, planners, verifiers, and people all work from that same reality. Context is **not rebuilt from scratch** every time a change starts; the model, plans, and verification history accumulate so the next change begins informed.

## The loop

1. **System model.** Sphere holds a living model of your system. It is written in SCAN (open notation) and shown as a visual board. Sphere can reconcile the model with real repositories so the diagram matches what exists.
2. **Approved goal.** Someone states what they want in plain language. A person approves the goal before work starts.
3. **Plan.** Sphere works out which parts of the system the change touches and writes a plan: what will change, where, and how success will be checked (acceptance criteria and verification steps).
4. **Revise and review.** The plan is refined against the architecture and reviewed. A person approves it before anything is built.
5. **Build.** Sphere carries out the plan using coding agents in an isolated workspace so nothing touches the main line until it is checked.
6. **Verify.** Sphere runs the plan's checks: tests, guards and acceptance criteria.
7. **Fix.** If a check fails, Sphere diagnoses the failure and rebuilds, then verifies again — it doesn't only report the failure and stop.
8. **Checked result.** The change comes back verified and ready for human review and merge, with a record of what was done and why.

## What accumulates in the model

Every plan, build and verification result is kept with the system model: up-to-date architecture, plan record, execution history, and verification record. That is what lets the next change start informed — and why multi-role teams can collaborate without re-explaining the system each time.

## Where people stay in control

- Approving the goal.
- Approving the plan before it is built.
- Reviewing the verified result before it is merged.
- Answering when Sphere needs a decision.

Sphere proposes changes to the architecture model for review; it does not silently rewrite it.

## Where it runs

**Sphere Desktop** (Windows and macOS) is the primary product surface: a chat-first architect/orchestrator with Plans, Runs, and Diagram beside Chat. It is rolling out in invitation waves — see `sphere-desktop.md`. The free SCAN whiteboard at app.spherescan.io is for drawing architecture only; it is not the full Sphere product. Work can run against a local workspace or managed infrastructure, depending on plan and deployment option. See trust-and-governance.