Empirical SDD

Agent-neutral, resumable spec-driven development for coding agents. Empirical turns an ordinary change request into a deterministic workflow with durable state, reviewable evidence, and safe Git integration.

Empirical 0.27 is alpha software. It requires Node.js 22 or newer.

Install

npm install -g empirical-sdd
empirical install

Choose the agents you use, reload them, then run empirical-init once in each repository. After initialization, ask for work normally—for example, “fix the pagination bug.” Empirical activates automatically for change requests while read-only questions stay outside the workflow.

Codex uses $empirical-init, Claude Code uses /empirical-init, and Windsurf uses @empirical-init. Existing 0.22 repositories should invoke it once after upgrading; configuration, history, and evidence are preserved.

Doctor verifies that completed repositories still have every required local instruction, skill, and MCP bridge. If it reports missing or drifted project integrations, invoke empirical-init explicitly to reconcile Empirical-owned artifacts; unmanaged or unsafe conflicts are preserved and remain visible.

What it provides

• Deterministic Fast or Complex routing based on the request's risk.
• Resumable Specify, Design, Plan, Implement, Verify, Review, and Integrate phases.
• Immutable evidence tied to criteria, source state, and provenance.
• Isolated parallel work through linked Git worktrees.
• Guided Linear, GitHub Issues + Projects, or Jira ticket mirrors with automatic binding, milestone comments, and safe evidence projection.
• Selectable concise or detailed agent questions and runtime summaries.
• Explicit, guarded delivery and npm publication boundaries.

Completion is reported only at the highest proven level: implemented, verified, integrated, delivered, or published.

Tracker setup

empirical-init always shows Interaction and Tracker sections. New recommended setup selects concise questions: agents ask only when an answer changes scope, architecture, authorization, or a safety gate. Detailed preserves the expanded guidance used by existing Schema-5 repositories. Automation can set the same value with --questions concise|detailed or the MCP questions field.

When no tracker choice exists, Init recommends Track work by type and requires choosing that or No tracking before setup can be saved. Track work selects Linear, GitHub Projects, or Jira; No tracking persists a provider-free choice and makes no provider requests.

Authentication starts with OAuth when a trusted host supplies a connection. MCP clients may open that connection only through explicitly negotiated URL-mode elicitation; Empirical never requests a credential through a form, tool argument, tool result, assistant message, or repository file. The default standalone CLI has no hosted OAuth broker and truthfully proceeds to the host-only fallback.

Never paste credentials into chat. If OAuth is unavailable, edit the secrets file directly on the host: ${XDG_CONFIG_HOME:-$HOME/.config}/empirical/secrets.env on POSIX or %APPDATA%\Empirical\secrets.env on Windows. Do not put a credential value in a shell command, process argument, tool call, or repository .env file.

New setup uses LINEAR_SECRET_KEY for Linear, GITHUB_TOKEN for GitHub, and both JIRA_EMAIL and JIRA_API_TOKEN for Jira. The file must be a regular, non-symbolic-link file outside the repository and, on POSIX, owner-only (for example mode 0600). Runtime precedence is connected host OAuth, then a complete injected environment set, then the checked host file. Existing Tracker Policy v1/v2 names—including LINEAR_API_KEY and custom names—remain valid and are never rewritten automatically.

After authentication, Empirical discovers accessible targets and workflow states, proposes all seven semantic mappings, and shows the complete secret-free policy before saving. Ambiguous state suggestions require an explicit choice; simple boards may intentionally reuse one provider state for several phases. Repair preserves an existing tracker policy or explicit No tracking choice unless you change it.

Tracker Policy v2 supports off, manual, and ensure ticket behavior plus blockers/final, phase-milestone, or every-revision progress comments. ensure validates a referenced ticket, reconciles the feature marker, and creates only when neither identifies one unique ticket. Local workflow state commits first; provider outages leave exact retry state and never rewind local work. Comments preserve user-authored descriptions, and receipt-approved evidence is uploaded or linked only after repository containment, media, size, and digest checks. Existing Tracker Policy v1 files remain valid with manual binding and legacy projection until deliberately upgraded.

An optional strict ticketRules matrix refines ensure by change type and workflow size. The recommended features+large-fixes preset is:

| Work | Fast | Quick | Complex | | --- | --- | --- | --- | | Feature | required | required | required | | Fix | optional | required | required | | Chore | optional | optional | optional |

Optional work with no referenced ticket stays local without OAuth, provider access, ticket creation, or a redundant question. One explicit reference is attached; multiple references fail closed. See the demo for a provider-independent new-feature run and MCP documentation for the complete custom JSON form.

CLI

| Command | Purpose | | --- | --- | | empirical install | Select agents and install or repair Empirical integrations. | | empirical update | Upgrade the package and refresh installed integrations. | | empirical uninstall | Remove Empirical-managed global files and the package. | | empirical --help | Show commands and automation options. |

empirical uninstall preserves project .empirical history, evidence, and repository configuration. Automation must confirm removal with --yes.

Safety

Empirical asks when a material product choice or permission is missing. It does not bypass host permissions or branch protection, extract credentials, force-write Git history, delete real worktrees, or infer publication. Releases remain bound to an exact version, commit, tag, and npm dist-tag.

Documentation

Protocol · Architecture · MCP and tracking · Demo · Security · Migration · Versioning · Changelog

Development

Development requires Node.js 22+ and Bun. CI covers Node 22, 24, and 26.

bun install
bun run ci

The package exports ., ./protocol, ./mcp, and ./integrations.

License

MIT