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.

Install Deliberate

You need Node.js 22.5 or later. 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’s current installer targets GitHub Copilot CLI.

npx deliberate-cli install

The default global install writes the skill to ~/.copilot/skills/deliberate. Use --here to install it into the current repository at .github/skills/deliberate, or --project <dir> for another repository.

Restart the agent harness so it discovers the skill, then verify the installation:

/deliberate help

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. Prefix the install command with SONORANCE_TELEMETRY=off to opt out before installation. See Privacy for the complete contract.

If Deliberate is not found

• Confirm that the harness scans ~/.copilot/skills/ for personal skills.
• Check the destination printed by the installer.
• Fully restart the harness; most scan for skills only at startup.
• For a project install, open the repository root and confirm .github/skills/deliberate exists.
• Re-run npx deliberate-cli install; it safely replaces the previous installation.

Ground the project

From the repository where you want to use Deliberate:

/deliberate init

Deliberate reads relevant files inside the current project folder directly as automatic context.

Initialization creates 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.

Create your first brief

/deliberate brief

On its first run, a brief covers the previous 90 days by default. Add another period to the prompt when needed—for example, /deliberate brief for June or /deliberate brief 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. 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

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.