How Deliberate works

Deliberate is a files-first product toolkit that runs through an agent harness: the app or CLI where an agent runs, uses tools, and loads skills, such as OpenAI Codex or GitHub Copilot. Deliberate does not run a model, schedule jobs, or operate a hosted worker. Its root manifest follows Agent Plugins 1.0.0, while generated native adapters and portable skill installation carry the same canonical Agent Skill across GitHub Copilot, Claude Code, Codex, Gemini CLI, Cursor, OpenCode, and Windsurf. Harness-specific manifests remain because plugin marketplaces and installation are outside the portable specification.

The three responsibilities

Layer	Responsibility
Agent harness	Runs the model, executes tools, handles authentication, and owns scheduling.
Deliberate	Grounds the agent, supplies product-work methods, and defines durable artifact contracts and commands.
Sonorance	Renders local Markdown and HTML, shows diffs, anchors review comments, and makes unresolved feedback available to /deliberate address/deliberate:deliberate address$deliberate addressdeliberate address/deliberate addressdeliberate address@deliberate address.

Deliberate is the product toolkit. Sonorance is its included local viewing and review feature. Sonorance does not replace the agent harness or run Deliberate’s methods.

When a workflow needs a private source, Deliberate tells the harness how to establish access without becoming a credential store: prefer the underlying API or saved query, reuse approved connectors or provider credential chains, verify account context, ask before login or switching identities, retry, then offer an official export. Only exhausted paths become evidence limitations. The same policy applies across init, cases, briefs, readouts, matchups, prototypes, and source-dependent review work; readouts add a stricter all-source preflight because their configured evidence is the report’s core input.

The Sonorance review workbench

Sonorance is the local app Deliberate runs on. It stays product-agnostic—Deliberate contributes document types and workflows without rebranding or replacing it. When you open a saved artifact, Sonorance gives you:

• an Explorer over the Markdown files in your project, so you can move between context and generated artifacts;
• reading and editing of each document, with frontmatter preserved and edits autosaved to disk;
• search across the project;
• diff mode, which compares the working document against git and highlights what the agent changed;
• inline comments anchored to a specific file and text selection; and
• a comment bridge that hands your open comments to /deliberate address/deliberate:deliberate address$deliberate addressdeliberate address/deliberate addressdeliberate address@deliberate address and shows resolutions live.

This is the review loop: read the agent’s work, comment on the exact claim or section, run /deliberate address/deliberate:deliberate address$deliberate addressdeliberate address/deliberate addressdeliberate address@deliberate address, and confirm the revision in diff mode.

Files are the system of record

Project context, external sources, generated artifacts, and review history stay in ordinary files rather than a vendor dashboard or chat transcript.

• Context is inspectable. A later run can read the same product grounding and source inventory.
• Methods are repeatable. The model may change, but the workflow and artifact contract remain visible.
• Artifacts are durable. Briefs, readouts, matchups, cases, and prototypes can be versioned, reviewed, and linked.
• Review closes the loop. Comments attach to the artifact, and /deliberate address/deliberate:deliberate address$deliberate addressdeliberate address/deliberate addressdeliberate address@deliberate address carries them back into the agent workflow.

This keeps the work portable across capable agent harnesses and lets the team decide what enters git history.

Provenance makes trust inspectable

A durable artifact should preserve enough context for a later reader to understand how it was produced:

• the sources available to the agent;
• the command and workflow used;
• material assumptions and missing evidence;
• the resulting artifact and its version history;
• human review and how it was addressed;
• evaluator identity when a score or assessment depends on a particular model or person.

Provenance does not make an artifact objectively correct. It makes the conditions of production visible so another person can interpret, challenge, or reproduce the work.

See Filesystem for the complete on-disk contract, Privacy for processing and telemetry boundaries, and Start here for the human feedback loop.