# Sphere — public knowledge corpus

Sphere Desktop is a chat-first architect/orchestrator (Windows/macOS) for checked delivery against Architecture as Code - differentiated autonomy, equal-outcome ROI (tokens / scope / human interactions), a BA/Dev/Architect/QA control plane (Chat, Plans, Runs, Diagram), and a living SCAN blueprint. app.spherescan.io is the free SCAN whiteboard only - not the main product.

# What is Sphere

# What is Sphere

**Sphere is an architecture-guided platform for autonomous software delivery.** It turns an approved goal into a checked, working change to a real system — with much less human supervision than driving AI coding tools by hand.

Tagline: *Complex software changes, delivered with less human supervision.*

## The story in four beats

When someone asks what Sphere is, how it helps, why it is better, or how it achieves that, answer with this narrative:

1. **Differentiated autonomy.** Coding harnesses (IDE chat, CLI coding agents) are autonomous at writing and editing code. Sphere is autonomous at **delivering a checked change to a real system**: plan, build, verify, and fix against a persistent architecture model. People approve the goal and the plan and review the result; they do not babysit every step. Proof point: **Sphere builds Sphere** — the team uses the same loop on its own multi-component product (including the desktop client). Do **not** claim “we are autonomous and other tools are not.”
2. **Better ROI for the same outcome.** For the **same production-ready platform / same target outcome**, compare AI capacity (tokens) consumed, scope delivered, and **human interactions** (re-prompting, re-contexting, chasing failures) against driving a coding harness alone. Do **not** invent numeric benchmarks; explain *why* supervision drops and invite a scoped pilot. See `roi-and-evaluation.md` and `vs-coding-harness.md`.
3. **A control plane for BA, Dev, Architect, and QA.** Sphere is shared collaboration surface for changes — board, plans, runs, verification — not only an IDE chat for developers. Business, architecture, build, and quality meet on one reality. The primary product UI is **Sphere Desktop**: chat-first architect/orchestrator (Chat home; Plans, Runs, and Diagram beside it) — not the free SCAN whiteboard at app.spherescan.io. See `sphere-desktop.md`.
4. **How: Architecture as Code.** SCAN + the Sphere board are a living **blueprint** (like a house plan). Agents and human control layers stay anchored in the same ground truth. Context is **not rebuilt from scratch** on every change; the model, plans, and verification history accumulate.

One-sentence introductions:

- General: “Sphere Desktop is a chat-first app that turns an idea into planned, implemented, and verified software against a living architecture model.”
- Business: “Sphere connects what the business wants with the work needed to deliver it, so teams spend less time translating and coordinating across separate tools.”
- Technical: “Sphere connects system context, delivery plans, implementation work, and verification so coding tasks stay tied to the wider goal.”

## The problem

AI can write code quickly. The delivery process around the code still sits on people: giving the AI context again and again, re-prompting when it drifts, working out which parts of the system a change touches, running tests, fixing broken builds, reviewing results, and remembering why things were done across sessions.

The bottleneck has moved from *writing code* to *supervising delivery*. For simple changes this is manageable. For changes that cross several services, repositories or teams, it isn't.

## The core idea

Sphere keeps a **living model of the whole system**: components, how they connect, technology, and decisions. That model is shared context for everything Sphere does — Architecture as Code, not a throwaway prompt.

From an approved goal, Sphere uses the model to **plan** the change, **build** it, **verify** it against acceptance criteria, and **fix** what fails, looping until the result is checked.

Because the model persists, Sphere remembers what it built and why. The next change starts from that knowledge instead of a blank prompt.

## In one sentence, by audience

- **Engineering leaders:** an architecture that stays true to the code, and a delivery engine reliable enough to trust with multi-component changes.
- **Architects:** your architecture becomes the working input to delivery, not documentation that drifts.
- **Developers:** describe the change, approve the plan, and get back a verified result, instead of steering an AI tool line by line.
- **Business analysts / product:** state needs in plain language and collaborate on the same plans and board as engineering.
- **QA:** verification and acceptance criteria are part of the plan, not an afterthought bolted onto a chat transcript.
- **Founders and small teams:** deliver like a larger team — Sphere carries the delivery process around the code.

## What Sphere is not

- Not just another code autocomplete or chat-in-the-editor tool.
- Not “merely an autonomous coding harness” — autonomy of *typing code* is not the same as autonomy of *checked delivery*.
- Not the free SCAN whiteboard at app.spherescan.io (diagram-only). Sphere Desktop is the chat-led product.
- Not a product where you are expected to live inside the diagram builder; Chat is home.
- It does not replace your coding agents; it directs them with the right context and checks their work.
- It does not remove people from decisions; it removes repetitive supervision around them.
- It does not make every project automatic, remove technical judgment, or guarantee that generated software is correct, secure, or production-ready.

# How Sphere works

# 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.

# Sphere Desktop

# Sphere Desktop

**Sphere Desktop is the primary product experience.** It is a Windows and macOS app where you architect and orchestrate software delivery through a **chat-first control plane** — not a diagram-only builder, and not the free SCAN whiteboard at app.spherescan.io.

Invitations roll out in waves via **Get started** / **Download** on spherescan.io. Treat Desktop as what Sphere *is* when you talk about using the product day to day; the marketing site and free SCAN tool are how people discover and try the notation.

## What kind of product it is

Sphere Desktop is an **architect and orchestrator**:

- You describe goals in plain language.
- Sphere plans against a living Architecture-as-Code model of your system.
- You approve goals and plans; Sphere builds, verifies, and fixes with coding agents.
- Plans, runs, and architecture stay with the workspace so the next change starts informed.

People stay in control of intent and review. Sphere carries the delivery loop between those decisions. See `how-sphere-works.md` and `what-is-sphere.md`.

## Chat is home

After you open a workspace, you land in **Chat**. That is where most work happens.

In Chat you:

- Brainstorm the product or change with Sphere.
- Shape architecture and delivery intent conversationally.
- Review proposals and approve human-in-the-loop actions (goals, plans, architecture updates).
- Kick off builds and come back when Sphere needs a decision or a result is ready.

You do **not** need to stay parked in the diagram editor. Diagram, Plans, and Runs are supporting views of the same project — open them when you want the board, the roadmap, or build progress; return to Chat to continue directing work.

## Main areas of the app

Left-rail navigation (order reflects how the product is used):

| Area | Role |
|---|---|
| **Chat** | Primary surface. Conversation with Sphere as architect/orchestrator; approvals and hand-offs live here. |
| **Plans** | Delivery packs and roadmaps produced from your conversations — what will change, phased work, acceptance intent. Review, revise, and start builds from here. |
| **Runs** | Build and verification activity: progress of plan → build → verify → fix, grouped with the plans they belong to. Watch status when you want; you do not have to babysit every step. |
| **Diagram** | Visual board of the living system model (SCAN). Inspect components and connections; approve architecture updates Sphere proposes. Supporting view — not the whole product. |
| **Connectors** | Links to tools and services the workspace uses (availability varies; see `capabilities.md`). |
| **Settings** | Account, preferences, and workspace-related configuration. |

Entry flow at a high level: sign in → pick or open a **workspace** (local project folder Sphere works against) → **Chat**.

## How a typical day feels

1. Open the workspace and stay in Chat.
2. State what you want functionally (“build…”, “add…”, “turn this prototype into…”).
3. Sphere drafts architecture and a plan against the system model; you review and approve.
4. Open **Plans** when you want the roadmap or pack detail; open **Diagram** when you want the board; open **Runs** when you care about build/verify progress.
5. Approve merges and decisions when Sphere pauses; otherwise let the loop run.
6. Context accumulates — model, plans, and run history — so the next chat turn is not a blank prompt.

BA, Dev, Architect, and QA share that same control plane. See `ways-of-working.md`.

## Sphere Desktop vs the SCAN whiteboard

| | **Sphere Desktop** (product) | **app.spherescan.io** (free SCAN whiteboard) |
|---|---|---|
| Purpose | Architect + orchestrate delivery: chat, plans, runs, living model | Draw and edit SCAN diagrams in the browser |
| Primary UI | **Chat**, with Plans / Runs / Diagram beside it | Diagram canvas only |
| Plans, builds, verification | Yes (product loop) | No |
| Persistent delivery memory | Yes, with the workspace | No product delivery memory |
| Access | Invited Desktop preview / paid Sphere | Free, open notation tools |

**Do not** describe Sphere as “the app at app.spherescan.io” or as “mainly a diagram builder.” That site is for trying **SCAN**. Sphere Desktop is the chat-led product that uses SCAN as its Architecture-as-Code blueprint.

The marketing site (spherescan.io) introduces Sphere with guided Desktop-shaped examples (Chat → roadmap/plans → architecture → runs). Use those as the mental model for visitors and assistants.

## Availability and getting in

- Desktop for Windows and macOS is rolling out in **invitation waves**.
- Visitors join via **Get started** / **Download** on this site; the marketing chat cannot send invitations itself.
- Until someone has Desktop, they can explore SCAN at app.spherescan.io, read `/learn`, and book time with the team.

Never claim Desktop is generally available to everyone, and never invent ship dates. Never claim a local install means “all data stays on your machine” — see `trust-and-governance.md`.

## What not to invent

When describing Desktop UX, stick to the surfaces and roles above. Do **not** invent menus, keyboard shortcuts, internal agent names, protocols, file formats beyond SCAN as public Architecture as Code, pricing, or implementation details. For those asks, load `sensitive-questions.md`.

# SCAN open notation

# SCAN: the open notation

**SCAN (System and Component Architecture Notation) is an open, human-readable notation for describing software systems.** Sphere is built on it. SCAN itself is free and open.

SCAN is the **Architecture-as-Code** substrate: the blueprint language for the living system model. Sphere turns that blueprint into plans, builds, verification, and memory. Without a shared notation, agents and people rebuild context from prose and file dumps every session.

## What SCAN describes

- **Components:** services, apps, data stores, agents, external systems.
- **Connections:** what talks to what, and how.
- **Ports and interfaces:** where components connect.
- **Technology:** what each component is built with.
- **Boundaries:** groupings such as domains, teams or deployment zones.
- **Layout and views:** how the model is drawn on a board.

A SCAN model is plain text (YAML), so it can live in a repository, be reviewed like code, and be read by both people and AI agents — the same ground truth for BA, Dev, Architect, QA, and coding agents.

## Why an open notation matters

- No lock-in for your architecture — the model is yours, in an open format.
- Toolable — anyone can read, render or generate SCAN.
- Shared language for people and AI agents.
- Structured context that is far more useful to agents than prose alone or a pile of source files.
- Context that **persists** across changes instead of being rebuilt each time.

## SCAN vs Sphere

| | SCAN (free, open) | Sphere Desktop (product) |
|---|---|---|
| Notation and specification | Yes | Yes |
| Browser whiteboard at app.spherescan.io | Yes (diagram canvas) | — |
| Chat-first architect / orchestrator | — | Yes |
| Plans, runs, builds, verification | — | Yes |
| Private workspace with a live, reconciled model | — | Yes |
| Persistent memory of plans, runs and verification | — | Yes |
| Collaboration, governance, connected systems | — | Yes |

**app.spherescan.io** is the free SCAN whiteboard — useful for trying the notation, not a substitute for Sphere Desktop. For how Desktop works (Chat, Plans, Runs, Diagram), see `sphere-desktop.md`. Learn more at https://spherescan.io.

# Sphere vs a coding harness

# Sphere vs a coding harness on its own

A **coding harness** is an AI coding agent and the tooling that drives it: chat-in-editor assistants, CLI coding agents and similar tools. They are very good at writing and editing code. Sphere uses them; it doesn't compete with them.

## The short answer

A coding harness answers *"write this code"*. Sphere answers *"deliver this change to my system, correctly, and remember it"*.

Many harnesses look “autonomous” because they loop on edits. Sphere’s autonomy is different: it continues through **plan → build → verify → fix** against a **persistent architecture model**, with people at goal/plan approval and result review — not at every re-prompt.

## Side by side

| | Coding harness alone | Sphere (with coding agents) |
|---|---|---|
| **Autonomy** | Writes/edits code in a session | Delivers a checked change across the system model |
| **Context** | Current session: open files, a prompt, maybe rules | A persistent model of the whole system (Architecture as Code) |
| **Scope** | Usually one repository or one task | Changes that span several components and repositories |
| **Planning** | Implicit, inside the conversation | Explicit plan with acceptance criteria, approved before building |
| **Verification** | Left to the developer, or ad hoc | Built into every plan; failures diagnosed and fixed in a loop |
| **Who supervises** | A person steering and checking each step | People approve goal and plan and review the checked result |
| **Memory** | Mostly lost between sessions | Plans, runs and verification kept with the system model |
| **Collaboration** | Primarily developers in an IDE | Control plane for BA, Dev, Architect, and QA |
| **Status** | "Done" when the agent says so | "Done" when the checks pass |

## ROI: compare equal outcomes

Do not claim a magic savings percentage. Use a fair comparison:

For the **same target platform / same production-ready outcome**, look at:

- **Tokens / AI capacity** consumed to get there
- **Production-ready scope** actually delivered (Y)
- **Human interactions** required (Z): re-prompting, re-pasting context, chasing failed builds, translating between roles

A coding harness alone often burns more Z because context and verification sit on people. Sphere lowers Z by anchoring agents in the living blueprint and folding verify/fix into the loop. Exact X/Y/Z numbers come from a **scoped pilot** on your system — not from invented benchmarks. See `roi-and-evaluation.md`.

## Why that matters

Less supervision, fewer surprises across components, trustworthy status, knowledge that compounds, and you keep the coding agents you like.

## When a coding harness alone is enough

For small, self-contained edits in one place, a coding assistant alone is often the right tool. Sphere earns its place when changes are larger, cross boundaries, need verification, need multi-role collaboration, or need to be understood later by someone else.

Do not criticise named competitor products — compare approaches.

# ROI and evaluation

# ROI and how to evaluate Sphere

## The fair comparison

Ask: for the **same production-ready outcome** (same platform or change set you would ship), how do these compare?

| KPI | What to count |
|-----|----------------|
| **X — AI capacity** | Tokens or subscription AI usage consumed to reach the outcome |
| **Y — Scope delivered** | Production-ready work completed (features/services/checks that ship) |
| **Z — Human interactions** | Prompts, re-contexting, babysitting failed runs, hand-offs between BA/Dev/Architect/QA |

Compare **Sphere (with coding agents)** against **driving a coding harness alone** (for example Cursor- or Claude-style IDE/CLI agents) on that equal outcome. Do **not** invent numeric X/Y/Z values in chat or marketing copy unless a published measurement exists.

## Why Sphere tends to improve Z (and often X)

- **Persistent Architecture as Code** — the SCAN/Sphere model is not rebuilt from a blank prompt each turn.
- **Approvals at goal and plan** — people decide once; agents execute against the approved plan.
- **Built-in verify and fix** — failures are diagnosed in the loop instead of becoming new human tickets.
- **One control plane** — BA, Dev, Architect, and QA share board, plans, and runs instead of translating across tools.

## How to run a pilot

1. Pick a bounded, production-relevant change (multi-component preferred).
2. Deliver it once with the team’s current harness-only practice; note capacity used and human touchpoints.
3. Deliver a comparable change with Sphere; note the same KPIs.
4. Compare X, Y, and Z — and qualitative collaboration (who had to watch the tools).

## What not to say

- Guaranteed percentages of time or money saved
- “Always cheaper than [named product]” without a measured pilot
- Inflated case studies or customer counts you cannot share (see sensitive-questions for internal deflection rules — do not quote that file publicly)

For pricing structure (not dollar amounts), see `plans-and-pricing.md`. For approach comparison, see `vs-coding-harness.md`.

# Ways of working

# Ways of working with Sphere

Sphere changes the shape of a delivery team's day: less steering of tools, more deciding and reviewing. **Sphere Desktop** is that **control plane**: BA, Dev, Architect, and QA meet in a **chat-first** app — Chat is home; Plans, Runs, and Diagram support the same workspace. See `sphere-desktop.md`. Do not picture the day as living inside a diagram builder or the free SCAN whiteboard.

## Roles on one control plane

- **Business analyst / product owner (a person)** states the goal functionally: *what* is needed and why.
- **The architect (a person)** owns the system's direction: architecture, important decisions and what "good" looks like.
- **Developers (people)** review plans and verified results; coding agents execute under Sphere’s direction.
- **QA (people)** rely on acceptance criteria and verification records that travel with the plan.
- **Sphere** works out *how*: plans against the architecture, builds through coding agents, verifies and fixes.

People decide intent and accept outcomes; Sphere handles the mechanics in between — all anchored in the same Architecture-as-Code blueprint.

## The rhythm

1. **Describe the goal functionally.** Say what should change and why, not which files to edit.
2. **Review the plan.** Check intent and which parts of the system it touches; ask Sphere to revise if needed.
3. **Approve and let it run.** Builds don't need watching. Sphere reports when done or when it needs a decision.
4. **Review the checked result.** Look at what changed, what was verified and why. Merge when satisfied.
5. **Let the model learn.** Plan, run and verification records stay with the system model — context for the next change.

## Habits that work well

- Plan, revise, then build — the cheapest place to catch a misunderstanding.
- Write acceptance criteria in plain language; they become the checks.
- Keep the architecture honest when Sphere proposes model updates.
- Start from a prototype: turn an existing app into a production version while cleaning structure.
- Let notifications pull you in rather than watching progress.
- Evaluate ROI with equal-outcome KPIs (tokens, scope, human interactions) — see `roi-and-evaluation.md`.

## A proof point

Sphere is used to build Sphere. The team plans, builds and verifies parts of the platform — including the desktop client — through the same loop customers use.

# Benefits by role

# Benefits by role

Describe benefits as *how* Sphere helps. Don't quote numbers unless a published benchmark has been provided. Sphere is a **shared control plane** for change — not only an IDE chat for developers.

## Business analysts and product

- State needs in plain language and see plans that map to the real system.
- Collaborate on the same board and plan record as engineering and QA.
- Less translation loss between “what the business asked” and “what got built.”

## Engineering leaders

- Larger, multi-component changes become deliverable with less senior supervision.
- Status you can trust: done means verified, not "the agent said so".
- A consistent way of working across teams and AI tools.
- Knowledge stays in the system model when people move on.
- Fair ROI evaluation against harness-only practice (tokens, scope, human interactions) — see `roi-and-evaluation.md`.

## Architects

- Architecture becomes the working input to delivery, not a stale diagram.
- Cross-component impact is visible in the plan before anything is built.
- Model updates are proposed for review — nothing rewrites architecture silently.
- Open SCAN notation keeps the model portable and readable (Architecture as Code).

## Developers

- Less time feeding context, re-prompting and chasing failing builds.
- A clear plan with acceptance criteria before work starts.
- Verified results to review, with a record of what was done and why.
- Keep using the coding agents you already like — Sphere directs them.

## QA

- Acceptance criteria and checks are part of the plan, not bolted on afterward.
- Visibility into what was verified and what failed in the fix loop.
- Same control plane as BA, Dev, and Architect — one reality for “done.”

## Product managers and operators

- State needs in plain language and see a plan you can understand.
- Visibility of where each change is and what has been checked.
- People involved where judgment matters, not for routine follow-up.

## Founders and small teams

- Deliver like a larger team: Sphere carries the delivery process around the code.
- Grow a prototype into a production system with cleaner structure.
- Begin with one connected system and grow from there.

## Enterprises

- Governance in the workflow: approvals, audit trails and human review points.
- Deployment choices from managed cloud to private environments.
- Portfolio-level visibility across many systems and teams.

# Capabilities

# Capabilities

Use this list to describe what Sphere does. **Never present an "In development" or "Planned" item as available, and never give dates.**

## Living architecture

| Capability | What it means | Status |
|---|---|---|
| Open SCAN notation | Describe your system in an open, readable format | Available |
| Visual board | See and edit the architecture as a diagram | Available |
| Architecture and code reconciliation | Keep the model in line with real repositories | Available |
| Multi-repository awareness | Systems across many repos understood as one | Available |
| Continuous drift detection | Mismatches flagged as proposed fixes | Planned |

## Planning and delivery

| Capability | What it means | Status |
|---|---|---|
| Architecture-grounded assistant | Brainstorm and plan against your system | Available |
| Plan, revise, build workflow | Reviewed and approved before building | Available |
| Isolated builds | Away from the main line until checked | Available |
| Built-in verification | Acceptance criteria and checks on every build | Available |
| Fix-and-reverify loop | Failures diagnosed and rebuilt | Available |
| Recorded test paths | Human paths recorded and replayed as checks | Available |
| Deployment pipeline integration | Pre-prod to prod with rollback | In development |

## Memory and context

| Capability | What it means | Status |
|---|---|---|
| Plan record | Intent kept with the system | Available |
| Run and verification history | What was built and checked | Available, being extended |
| Assistant memory across sessions | Decisions remembered between conversations | In development |

## Autonomy

| Capability | What it means | Status |
|---|---|---|
| Autoplay (continued progress) | Less repeated prompting across related plans | Available (depends on edition/setup — confirm with team when exact availability matters) |
| Notifications instead of watching | Sphere tells you when a result or question waits | In development |
| Escalation to a person | Pause affected work and ask | Planned |
| Many plans delivered together | Related changes in order after one approval | Planned |

## Platform

| Capability | What it means | Status |
|---|---|---|
| Sphere Desktop (Windows and macOS) | Primary product: chat-first architect/orchestrator with Chat, Plans, Runs, Diagram | In development — invitation waves via the marketing site form |
| Free SCAN whiteboard (app.spherescan.io) | Browser diagram canvas for open SCAN notation only | Available |
| Git integration | Connect repositories for planning and building | Available |
| Connections to external tools | Bring in other systems the team uses | In development |
| Organisations and projects | Multiple teams and projects with access control | Available |

Desktop invitations: **Sphere Desktop** is the product Sphere presents first — chat-led control plane, not the SCAN whiteboard. It is rolling out in waves. Visitors leave email via **Get started** / **Download** on this site; this chat cannot send invitations itself. UX overview: `sphere-desktop.md`.

# Autonomy and Autoplay

# Autonomy and Autoplay

## What autonomy means here

Sphere's autonomy is **continuing delivery toward an intended outcome** with less repeated manual prompting: planning, revision, implementation, and verification connected together — not only an agent looping on code edits in a chat.

Coding harnesses can feel autonomous because they keep writing code. Sphere’s autonomy is different: it keeps working the **delivery loop** against a **persistent architecture model**, pausing for people where judgment is required (goal, plan, merge decisions).

**Autoplay** supports that more continuous way of working. A broader feature may involve multiple related plans rather than one coding request.

## Proof point: Sphere builds Sphere

The Sphere team develops parts of Sphere — including the desktop client — through the same plan / build / verify / fix loop customers use. Treat this as evidence the delivery loop works on a real multi-component product, not as a claim that every customer project will run unattended.

## What the user gains

- Less repetitive effort moving between planning and implementation.
- Progress on a broader feature while its purpose stays visible.
- More focus on direction, decisions, and evaluation.
- A connected view for reviewing activity and results.

These are functional benefits, not measured guarantees of time saved or uninterrupted operation. For ROI comparison shape, see `roi-and-evaluation.md`.

## Human responsibility

People remain responsible for deciding what should be built, resolving ambiguous requirements, assessing tradeoffs, and determining whether results are acceptable — including scope, sensitive data, security expectations, and release readiness.

## How to discuss “fully autonomous” / “aren’t all tools autonomous?”

Prefer: “Sphere continues through connected planning, implementation, and verification with less repeated prompting — anchored in a living system model.”

Prefer when comparing: “Harnesses are strong at writing code; Sphere is strong at delivering a checked change and remembering it.”

Do **not** say: never needs people, always makes the right decision, runs forever, can access everything, automatically deploys any change, or “other tools are not autonomous.”

If asked about continuous operation: Autoplay supports continuous progression; actual operation depends on resources, access, external services, and decisions. Do not offer a 24/7 SLA.

## Verification and drift

Verification asks whether the result meets the expectations being checked. Drift is divergence between intended direction and what is being built. Sphere connects these concerns to the delivery workflow — it does not claim to detect all drift or prove complete correctness.

# Illustrative use cases

# Illustrative use cases

These scenarios explain potential use. They are **not** customer references, measured results, integration commitments, or delivery-time guarantees. Identify them as examples when you use them.

## Turn a product idea into a first usable version

Situation: A founder has an idea for a portal but needs to define the first meaningful version.

With Sphere: Discuss users and outcomes, make system context understandable, organize work into plans, and review implementation and verification as the product takes shape.

Limit: No fixed delivery time; scope and quality decisions remain.

## Add a feature that spans several components

Situation: Customers should track request status; the change may touch UI, services, and storage.

With Sphere: Treat the feature as one outcome, use the blueprint for relationships, connect work to plans, and evaluate combined behavior.

Limit: Exact systems and connections must be assessed for the project.

## Improve an existing internal tool

Situation: Staff struggle with a fragmented workflow.

With Sphere: Clarify friction and desired behavior, discuss affected areas, plan improvements, and review against staff needs.

Limit: Access and constraints influence what is practical.

## Carry a solution blueprint into implementation

Situation: An architect outlined a solution; handoffs keep losing context.

With Sphere: Shared blueprint and plans keep the relationship between the proposed solution and delivery work.

Limit: Not a promise that arbitrary diagrams import automatically.

## Continue work on a broader feature

Situation: Multiple related plans and revisions; the owner spends time prompting each next step.

With Sphere: Autoplay supports continued planning, implementation, and verification while reviewing progress and decisions that need attention.

Limit: Unresolved decisions, access limits, or unclear requirements can still stop progress.

# Trust and governance

# Trust, governance and deployment (high level)

Answer at this level only. For detailed security, compliance or architecture questions, offer a conversation with the team (via spherescan.io).

## Human control

- People approve the goal, approve the plan before it is built, and review the verified result before it is merged.
- No silent changes to the architecture — updates are proposed for review.
- When Sphere needs a decision, it asks instead of guessing.
- Work is reported as finished only after verification.

## Safety by design

- Builds happen in isolation from the main line until checked.
- Credentials and secrets are not stored in the architecture model or in plans.
- Actions by agents and approvals by people are recorded for traceability.
- Organisations and their data are kept separate.

## Deployment options

| Option | In plain terms |
|---|---|
| Sphere Cloud with a local workspace | Sphere runs the service; work on your code can happen on your machine |
| Sphere Cloud with managed workers | Sphere runs the service and the build capacity |
| Private cloud | Sphere in your own cloud (Enterprise) |
| On-premises or restricted network | Sphere in your own infrastructure (Enterprise) |

**Important wording.** A local or desktop setup does **not** by itself mean all data stays on your machine. Where code, prompts, model calls, logs and run records go depends on the deployment option and whose model credentials are used.

## Using your own AI model credentials

Customers can use their own model provider credentials where the plan allows. They pay the provider for model usage; Sphere charges for the platform. Private deployments use customer-controlled credentials.

## What not to say

- Don't name infrastructure providers, regions, encryption methods, identity providers or certifications unless given an approved public statement.
- Don't claim compliance certifications (SOC 2, ISO, etc.) here.

# Plans and pricing structure

# Plans and pricing (structure only)

**Prices are not published in this knowledge base.** Describe the structure and direct people to https://spherescan.io or **hello@spherescan.io** for current pricing.

## The structure

- **SCAN Community: free.** Open notation, specification and static renderer — no managed AI delivery.
- **Sphere subscriptions: paid.** Individuals, teams and teams delivering routinely. Private workspace, live system model, Flows, planning, and a defined amount of AI and delivery capacity.
- **Sphere Enterprise: annual contract.** Multiple teams: portfolio governance, security controls, support, contracted capacity and deployment choices including private deployment.

## Principles you can explain

- Priced around connected systems, not per diagram or per Flow. Viewers are not charged.
- Usage is included, with visible limits. Usage beyond it is visible and controllable; never billed without consent.
- Customers can see expected usage before work runs and can set limits.
- Bring-your-own model credentials where the plan allows.
- Enterprise pilots around a real multi-component change are available, scoped with the team.

## What not to say

- No prices, discounts, allowances, overage rates or "starting from" figures.
- No claim that Sphere is cheaper than other approaches.
- No promise of "unlimited" AI usage.

# FAQ

# Frequently asked questions

## The basics

**What is Sphere?**  
Sphere is an architecture-guided platform for autonomous software delivery. It keeps a living Architecture-as-Code model of your system and uses it to plan, build, verify and fix changes — a control plane for BA, Dev, Architect, and QA — so complex changes get delivered with less human supervision. See the four-beat story in `what-is-sphere.md`.

**Who is it for?**  
Engineering teams, architects, BAs/product, QA, and founders working on systems with several components or repositories, where changes need to be planned, checked and understood later.

**What does "architecture-guided" mean?**  
Every plan starts from a model of your whole system: components, connections and decisions. That model guides what Sphere changes and how it checks the result. Context is not rebuilt from a blank prompt each time.

**What is SCAN?**  
SCAN is the open, free notation Sphere uses to describe systems in readable YAML — the blueprint language. You can use SCAN without Sphere — try the free whiteboard at app.spherescan.io. That site is diagram-only; it is not Sphere Desktop.

**Is Sphere mainly a diagram builder?**  
No. Sphere Desktop is chat-first: you architect and orchestrate in Chat, with Plans, Runs, and Diagram as supporting views. See `sphere-desktop.md`.

## Autonomy and coding tools

**Aren’t all AI coding tools autonomous?**  
Harnesses are strong at writing and editing code in a session. Sphere’s autonomy is delivering a **checked change** through plan, build, verify, and fix against a **persistent system model**, with people at goal/plan approval and result review. Different job, not “they aren’t autonomous.”

**Is Sphere a coding assistant?**  
Not on its own. Sphere directs coding agents and checks their work — context, planning, verification, fixing and memory.

**Do I have to stop using my current AI coding tools?**  
No. Sphere works alongside coding agents.

**Why not just use a coding agent directly?**  
For small edits in one place, that's often fine. For multi-component changes, a coding agent alone needs a person to supply context, steer and check at every step. Sphere carries that work and keeps a record.

**How do you measure ROI vs Cursor / Claude / similar harnesses?**  
Compare equal production-ready outcomes using tokens (or AI capacity), scope delivered, and human interactions — then run a scoped pilot. We don’t invent benchmark numbers. See `roi-and-evaluation.md`.

**Which AI models does Sphere use?**  
Sphere chooses suitable models for each kind of work; customers can use their own credentials where the plan allows. We don't share specific models or selection rules.

## How it works in practice

**How is context not rebuilt each time?**  
The SCAN/Sphere model, plans, and verification history persist with the workspace. Agents and people stay anchored in that blueprint instead of re-pasting the system into every prompt. See `how-sphere-works.md` and `scan.md`.

**Do I need to describe exactly what code to write?**  
No. Describe the goal functionally. You review the plan before anything is built.

**What happens if the build fails a check?**  
Sphere diagnoses, rebuilds and verifies again. If it can't resolve the problem, it pauses and asks a person.

**Will Sphere change my architecture without asking?**  
No. Model updates are proposed for review.

**Do I have to watch builds?**  
No. Approve the plan; Sphere reports when ready or when it needs a decision.

**Can I start from a prototype?**  
Yes — a common pattern is turning a prototype into a production version while cleaning structure.

**Is Sphere used to build Sphere?**  
Yes. The team develops parts of Sphere, including the desktop client, through the same loop — evidence the delivery loop works on a real multi-component product.

## Product and access

**Is there a desktop app?**  
Yes — **Sphere Desktop** (Windows and macOS) is the primary product: chat-first control plane for plans, architecture, and builds. It is rolling out in invitation waves; join via **Get started** / **Download** on this site. The free tool at app.spherescan.io is the SCAN whiteboard, not Desktop.

**Where do I spend my time in Sphere?**  
In **Chat**. Diagram, Plans, and Runs support the same workspace; you visit them for the board, roadmap, or build progress, then return to Chat to keep directing work.

**Does a local setup mean my code never leaves my machine?**  
Not automatically. It depends on deployment option and whose model credentials are used.

**Can we deploy Sphere privately?**  
Enterprise options include your own cloud or on-premises. Talk to the team.

**How much does it cost?**  
SCAN is free. Sphere has paid subscriptions and Enterprise contracts. For current pricing, see spherescan.io or email **hello@spherescan.io**.

**How do I contact Sphere?**  
Email **hello@spherescan.io** (also linked in the site footer). For Desktop access, use **Get started** / **Download** on this page.

**How do I get started?**  
Join the Sphere Desktop invitation list via **Get started** / **Download** on this page, explore the guided Desktop-shaped examples on the site, try free SCAN at app.spherescan.io, or email **hello@spherescan.io** for a demo.

# Glossary

# Glossary

**Acceptance criteria.** Plain-language statements of what must be true for a change to count as done. Sphere turns them into checks.

**Approved goal.** A change someone wants, stated functionally and approved before Sphere starts work.

**Architecture-guided delivery.** Planning and building from a model of the whole system rather than a single prompt or file.

**Autoplay.** Continued planning, implementation and verification across related work with less repeated prompting.

**Board / Diagram.** The visual view of the system model in Sphere Desktop. Supporting surface — not where you are expected to spend most of your time.

**Chat.** Home screen of Sphere Desktop: conversational architect/orchestrator surface where goals, proposals, and approvals happen.

**Checked result.** A change that has passed verification and is ready for human review and merge.

**Coding agent / coding harness.** An AI tool that writes and edits code, plus the tooling that drives it. Sphere works with these.

**Component.** A part of a system: service, app, data store, agent or external system.

**Connected system.** One managed application or platform in Sphere, possibly spanning several services and repositories.

**Connection.** A link between components showing what talks to what.

**Drift.** When the architecture model, plans and real code no longer match.

**Flow.** A structured piece of work or process captured in Sphere that uses the system model.

**Living model.** The system model kept up to date as changes land, rather than a one-off diagram.

**Plan.** Sphere's description of a change: what will change, where, and how it will be verified. In Desktop, plans and roadmaps live under **Plans**.

**Revise.** Refining a plan against the architecture and review feedback before it is built.

**Runs.** Desktop view of build and verification activity for plans.

**SCAN.** System and Component Architecture Notation — the open, free notation Sphere is built on. The free browser whiteboard at app.spherescan.io is SCAN-only, not Sphere Desktop.

**Sphere Desktop.** Primary Sphere product (Windows and macOS): chat-first architect and orchestrator. See `sphere-desktop.md`.

**Verification.** Running a plan's checks against the built change.

**Viewer.** A person who can see a workspace without running delivery work. Viewers are not charged.