Start here

Deliberate adds opinionated product workflows to the agent you already use. The agent supplies the model and execution; Deliberate supplies the method, durable files, and review loop.

Set up Deliberate

An agent harness is the app or CLI where an agent runs, uses tools, and loads skills—for example, OpenAI Codex or GitHub Copilot. Deliberate supports GitHub Copilot, Claude Code, Codex, Gemini CLI, Cursor, OpenCode, and Windsurf. Use Node.js 22.20 or later across these installation paths.

Setup is two commands: install the plugin, then initialize a project. Pick your harness below—every command in these docs then follows it. Gemini CLI and OpenCode have no slash grammar, so their commands are expressed to the agent in natural language.

GitHub Copilot

1. Install$ copilot plugin marketplace add Sonorance/deliberate$ copilot plugin install deliberate@deliberate
2. Initialize a project/deliberate init

Claude Code

1. Install/plugin marketplace add Sonorance/deliberate/plugin install deliberate@deliberate/reload-plugins
2. Initialize a project/deliberate:deliberate init

Codex

1. Install$ codex plugin marketplace add Sonorance/deliberate
2. Initialize a project$deliberate init

Gemini CLI

1. Install$ gemini extensions install https://github.com/Sonorance/deliberate
2. Initialize a projectdeliberate init

Cursor

1. InstallCustomize > Marketplace > Deliberate > Install
2. Initialize a project/deliberate init

OpenCode

1. Install$ npx skills add Sonorance/deliberate --skill deliberate --global --agent opencode
2. Initialize a projectdeliberate init

Windsurf

1. Install$ npx skills add Sonorance/deliberate --skill deliberate --global --agent windsurf
2. Initialize a project@deliberate init

Restart the agent harness so it discovers the skill, then confirm it with /deliberate help/deliberate:deliberate help$deliberate helpdeliberate help/deliberate helpdeliberate help@deliberate help. For the full per-harness reference—including the Copilot app and cloud agent, managed/offline archives, and troubleshooting—see Install Deliberate.

Deliberate includes the Sonorance runtime. Privacy-first, anonymous usage telemetry is on by default and records only allow-listed feature usage, performance measurements, and redacted error classes—never project, file, or folder names; file contents; paths; prompts; completions; error messages; or stack traces. Installation runs no Deliberate code. Set SONORANCE_TELEMETRY=off before starting the harness to opt out before first use. See Privacy for the complete contract.

What grounding creates

Run from the repository where you want to use Deliberate. Deliberate reads relevant files inside the current project folder directly as automatic context, then writes three context files with clear ownership:

• product.md captures the product, users, market, evidence, and operating context.
• competitors.md tracks the qualified alternatives customers could choose instead, with current evidence and monitoring sources.
• ecosystem.md tracks the complements and adjacent products that shape the end-to-end customer workflow.

The agent drafts these files from available evidence. Review and edit them as your product or market changes; every later workflow reuses them. Rerun /deliberate init/deliberate:deliberate init$deliberate initdeliberate init/deliberate initdeliberate init@deliberate init after a meaningful product change or Deliberate update: it preserves the current files as source material, rereads the project and configured sources, and refreshes all three through the latest installed context method instead of resetting them.

Create your first brief

Run /deliberate brief/deliberate:deliberate brief$deliberate briefdeliberate brief/deliberate briefdeliberate brief@deliberate brief.

On its first run, a brief covers the previous 90 days by default. Add another period to the request when needed—for example, ask for June or for the last 30 days. Later briefs normally continue from the previous brief, capped at a 90-day lookback.

The agent reads the project context, researches the bounded landscape window, and writes a source-backed brief to deliberate/briefs/<date>/brief.md, where <date> is the last day of the reported period. It separates routine direct action from each consequential unresolved decision worth deeper case analysis.

After saving the brief, the agent explains the triggering evidence, why analysis is useful now, and the decision each recommended case would unlock. It then offers Open for review + run cases (default), Open for review only, and Other.

Review and keep the record

Sonorance is the local review workbench included with Deliberate. It opens the saved Markdown in an Explorer over your deliberate/ files, where you read and edit the document, search across the project, and inspect what the agent changed against git in diff mode. Review stays tied to the durable file instead of a chat transcript.

To respond, select the exact text that needs clarification or revision and leave a comment. Each comment carries the file and text anchor the agent needs to understand what you mean. Comments stay on your machine in .sonorance/local/comments.jsonl; they are not committed or shared automatically.

Keep Sonorance running, return to the agent in the same project, and run /deliberate address/deliberate:deliberate address$deliberate addressdeliberate address/deliberate addressdeliberate address@deliberate address.

The agent reads every open comment, answers the question or edits the referenced file where warranted, and marks the comment resolved only after addressing it. Resolutions appear live in Sonorance. Review the revision in diff mode, repeat the loop if needed, then commit the accepted context and artifacts to the repository’s git history.

Choose the next workflow

• Track external changes with briefs.
• Read a completed reporting period with readouts.
• Compare one rival with matchups.
• Analyze any consequential idea or signal with cases.
• Test an eligible product journey or market touchpoint with prototypes.
• Put recurring briefs and readouts on a harness-owned schedule with automation.

Read How Deliberate works for the files-first model, product boundary, and trust contract.