empirical-sdd 0.20.1 → 0.20.3

package/README.md

@@ -1,279 +1,76 @@
 # Empirical SDD
 
-Empirical is an agent-neutral spec-driven development engine for Codex, Claude
-Code, Cursor, Gemini CLI, Windsurf, and MCP clients. It turns a coding request
-into an exact, resumable workflow with observable contracts, evidence, review,
-living capability specifications, and safe Git worktree isolation.
+Agent-neutral, resumable spec-driven development for 73 global agent-skill
+targets, with verified runtime guidance for Codex, Claude Code, Cursor, Gemini
+CLI, Windsurf, and MCP clients.
 
-Empirical `0.20.1` is an alpha release. It uses one active feature per checkout
-and real Git worktrees for parallel work.
+> Empirical is alpha software. It supports one active feature per checkout and
+> uses Git worktrees for isolated parallel work.
 
 ## Install
 
-```bash
-npm install -g empirical-sdd
-empirical install
-```
-
-`empirical install` opens a multi-select list of every supported coding agent.
-Detected agents and existing Empirical installations are labeled and selected
-by default. Use the arrow keys to move, Space to select, `a` to toggle all, and
-Enter to install.
-
-The selection is exact: Empirical installs one global entrypoint in every
-selected agent and removes only Empirical-managed entrypoints from agents you
-deselect. Unmanaged files are never overwritten or deleted. The installer works
-from any directory and neither creates repository state nor launches an agent.
-
-For scripts and unattended setup, choose agents explicitly:
-
-```bash
-# Exact selection; repeat -a/--agent
-empirical install --agent codex --agent cursor
-
-# Every supported agent
-empirical install --all
-
-# Detected agents plus existing managed installations
-empirical install --yes
-```
-
-Then open your repository in a coding agent and use its one Empirical entrypoint:
-
-| Agent | Invocation |
+| Command | Purpose |
 | --- | --- |
-| Codex | `$empirical` |
-| Claude Code | `/empirical` |
-| Cursor Agent chat | `empirical` |
-| Gemini CLI | `empirical` |
-| Windsurf Cascade | `@empirical` |
-
-To upgrade both the package and installed entrypoints:
-
-```bash
-empirical update
-```
-
-`empirical install` and `empirical update` are the entire public terminal CLI.
-Repository setup and feature work happen inside the current coding agent; old
-terminal verbs such as `init`, `config`, `explore`, `fast`, `complex`, and
-`loop` are rejected.
-
-## One entrypoint owns the workflow
-
-Ask the installed Empirical entrypoint for repository work in ordinary language.
-It deterministically:
-
-1. initializes an uninitialized repository in the current runtime;
-2. builds or refreshes compact repository knowledge;
-3. resumes non-terminal work already owned by this checkout;
-4. uses the original five-pass Socratic interview only when the request is
-   genuinely vague;
-5. routes an approved, concrete request internally to Fast or Complex;
-6. executes exact revisions through evidence, review, and living-spec archive;
-7. offers an explicit agent handoff only after a Complex specification exists.
-
-```text
-one Empirical invocation
-          │
-          ├─ repository uninitialized ──> first-run setup + compact context
-          ├─ active feature found ──────> resume exact revision
-          └─ new request
-                ├─ genuinely vague ────> five Socratic passes ──> approval
-                └─ concrete ───────────> internal Fast / Complex routing
-                                                         │
-                                      approved Complex spec exists?
-                                                         │
-                                  Continue here | Save | Continue in agent
-```
-
-Fast is only for explicit, tiny, localized, reversible, low-risk, non-UI work.
-Everything else—including UI, architecture, public APIs, security, migrations,
-and cross-cutting changes—uses Complex.
-
-## First use and repository knowledge
-
-On first use, the agent initializes `.empirical/`. It applies safe defaults or
-asks only questions that materially change Git isolation or Complex decision
-policy. It does not install project-local workflow skills.
-
-Initialization also creates a compact, committed context set:
-
-```text
-.empirical/context/
-├── manifest.json
-├── index.md
-├── overview.md
-├── architecture.md
-├── commands.md
-└── conventions.md
-```
-
-The deterministic manifest contains bounded path, size, and content-digest
-metadata—not source contents. Dependency trees, build output, ignored files,
-secret-like paths, credentials, binary files, and large files are excluded.
-Topic pages are maintained from repository evidence and are not overwritten by
-a routine refresh. There are no embeddings, hosted services, or vector database.
-
-## Socratic discovery
-
-For a vague idea such as “make onboarding better,” Empirical asks one question
-at a time across five passes:
-
-1. primary user and observed problem;
-2. smallest observable outcome;
-3. boundaries, constraints, and explicit non-goals;
-4. failures and solution-changing risks;
-5. concrete verification.
-
-It adds only material follow-ups, saves the answers, presents the complete
-refined contract, and waits for explicit approval before creating workflow
-state. A concrete request does not pay this discovery cost.
-
-## Small feature demo
+| `npm install -g empirical-sdd` | Install the Empirical CLI globally. |
+| `empirical install` | Choose coding agents and install their five Empirical skills. |
+| `empirical update` | Upgrade Empirical and refresh the installed skills. |
 
-In your coding agent:
+Restart or reload each selected agent after installation.
 
-> `$empirical` Add a health command that prints `ok`.
+`empirical install` uses a searchable, scrollable local catalog pinned to a
+reviewed `vercel-labs/skills` release. It remembers the exact selected ids,
+deduplicates shared skill roots, and never runs `npx` or uses the network. Type
+to search by agent name, id, or destination; use arrows, Space, Enter, Escape,
+or Ctrl-C. Automation can use repeatable `--agent`/`-a`, `--all`, `--yes`, and
+`--json`; the legacy ids `claude` and `gemini` remain aliases.
 
-Empirical recognizes an explicit, localized, low-risk non-UI change and routes
-it internally to Fast. The agent inspects only relevant files, implements the
-generated observable criterion, runs one focused test, reviews the diff, and
-completes the exact revision. The durable result is:
+## Use
 
-```text
-.empirical/specs/add-a-health-command-that-prints-ok/
-├── spec.md
-├── state.json
-├── events/
-└── evidence.json
-```
+These are coding-agent skills, not shell commands:
 
-You do not choose or invoke a separate Fast command.
+| Agent | Automatic | Init | Spec | Socratic | Loop |
+| --- | --- | --- | --- | --- | --- |
+| Codex | `$empirical` | `$empirical-init` | `$empirical-spec` | `$empirical-socratic` | `$empirical-loop` |
+| Claude Code | `/empirical` | `/empirical-init` | `/empirical-spec` | `/empirical-socratic` | `/empirical-loop` |
+| Cursor | `empirical` | `empirical-init` | `empirical-spec` | `empirical-socratic` | `empirical-loop` |
+| Gemini CLI | `empirical` | `empirical-init` | `empirical-spec` | `empirical-socratic` | `empirical-loop` |
+| Windsurf | `@empirical` | `@empirical-init` | `@empirical-spec` | `@empirical-socratic` | `@empirical-loop` |
 
-## Complex feature demo
-
-In your coding agent:
-
-> `$empirical` Add team invitations with expiration, revocation, and audit
-> history. Existing members must keep access during rollout.
-
-Empirical routes the request to Complex and drives seven gates:
-
-1. Specify observable criteria, scope, risks, verification, and capability
-   deltas.
-2. Design the architecture and record accepted evidence-backed decisions.
-3. Plan an executable implementation sequence.
-4. Implement the approved contract.
-5. Verify every criterion; UI work requires real-browser evidence.
-6. Review the diff against criteria and accepted decisions.
-7. Archive reviewed deltas into living capability specifications.
-
-After Specify passes, the agent offers:
-
-- Continue here.
-- Save for later.
-- Continue in a detected agent.
-
-For an external handoff, Empirical displays the target, whether it accepts a
-prompt or only a workspace, the exact working directory, and exact argument
-array. Detection and Save launch nothing. The command is revalidated and
-authorized only after you explicitly approve that exact option.
-
-Decision records store reviewable evidence, options, the selected approach,
-trade-offs, risks, and verification—not private chain-of-thought, prompts,
-scratchpads, tokens, or credentials.
-
-## Parallel work uses Git worktrees
-
-If a different feature is active, the single entrypoint returns a read-only
-worktree proposal instead of overwriting state. It shows the base and immutable
-base commit, branch, sibling path, exact Git argument array, and approval token.
-
-After explicit approval Empirical requires a clean source checkout, revalidates
-every field, rejects collisions, creates the linked checkout without force, and
-starts the exact request there. It never stashes, commits, moves local changes,
-deletes worktrees, or deletes branches.
-
-Active selection lives in checkout-local Git metadata while portable feature
-contracts remain committed under `.empirical/specs/`. A linked checkout therefore
-does not accidentally inherit a blocked feature owned by another checkout.
-
-## Internal automation API
-
-The TypeScript API and MCP tools remain available for agent runtimes and
-programmatic integrations. They include setup, context refresh, discovery,
-Fast/Complex routing, resume, exact completion, verification, review, archive,
-status/explain, handoff, capability projection, and worktree proposal/creation.
-They are automation primitives, not additional user-facing terminal commands.
-
-The stdio MCP server exposes these groups:
-
-- setup/context: `empirical_init`, `empirical_adopt`, `empirical_configure`,
-  `empirical_context`;
-- routing/workflow: `empirical_explore`, `empirical_fast`,
-  `empirical_complex`, `empirical_loop`, `empirical_next`,
-  `empirical_complete`, `empirical_retry`, `empirical_verify`,
-  `empirical_archive`;
-- handoff/isolation: `empirical_handoff`, `empirical_worktree_propose`,
-  `empirical_worktree_create`;
-- understanding: `empirical_explain`, `empirical_status`,
-  `empirical_capabilities`, `empirical_policy`, `empirical_doctor`.
-
-Only explicitly approved worktree creation mutates Git. Agent handoff returns an
-approval-bound command but never launches it itself.
-
-## Committed layout
-
-```text
-.empirical/
-├── config.json
-├── policy.json
-├── context/
-├── capabilities/<capability>/spec.md
-├── discoveries/<discovery>/
-│   ├── interview.json
-│   └── brief.md
-└── specs/<feature>/
-    ├── spec.md
-    ├── design.md              # Complex
-    ├── decisions.md           # Complex when required
-    ├── plan.md                # Complex
-    ├── deltas/*.md            # Complex behavior changes
-    ├── state.json
-    ├── state.lock             # ephemeral
-    ├── events/*.json
-    └── evidence.json
-```
-
-Feature contracts, journals, context, capability specs, configuration, and
-policy are committed. The checkout's selected feature is stored in its own Git
-metadata and is not shared across linked worktrees.
-
-## Migration and the 0.20 alpha
+| Skill | Purpose |
+| --- | --- |
+| `empirical <request>` | Initialize if needed, select the workflow, and run the request through review. |
+| `empirical-init` | Initialize or repair repository setup without starting work. |
+| `empirical-spec <request>` | Draft a concrete specification and stop for approval. |
+| `empirical-socratic <idea>` | Refine an idea through a five-pass interview, then draft a specification. |
+| `empirical-loop` | Resume the active approved specification and drive it to completion. |
+
+On first `empirical-init`, the agent shows the complete recommended setup before
+writing anything. Apply the defaults, customize Verification, Parallel work,
+and Decisions one section at a time, or cancel. Repair shows current values and
+keeps them unless edited. Verification independently stores acceptance-test,
+UI-browser, UI-screenshot, and code-review gates; all default on. Turning off
+criterion evidence makes its UI sub-policies inactive without erasing them, and
+does not turn off code review.
+
+Broad catalog membership means an agent can read global `SKILL.md` files. MCP
+bridging and executable handoff remain separately verified capabilities; the
+installer does not infer either one.
 
-Running the installer again is the migration: it removes only marker-owned old
-global and project-local Empirical workflow artifacts, preserves unmanaged
-content and existing runtime configuration, and converges without unnecessary
-second-run changes. Existing schema-4 projects and discovery records remain
-readable.
+## Development
 
-Schema-1, schema-2, and schema-3 default root state migrates idempotently into
-the matching feature directory. Historical alternate parallel-state data is
-left untouched and unsupported.
+Requires Node.js 20+ and Bun.
 
-See [migration details](docs/migration-v1.md), the [architecture](docs/architecture.md),
-the [MCP guide](docs/mcp.md), the [security model](docs/security.md), and the
-[OpenSpec comparison](docs/openspec-comparison.md).
+| Command | Purpose |
+| --- | --- |
+| `bun install` | Install development dependencies. |
+| `bun run ci` | Run type checking, tests, build smoke tests, and package tests. |
 
-## Development
+## Documentation
 
-```bash
-bun install
-bun run ci
-```
+[Architecture](docs/architecture.md) · [Demos](docs/demo.md) ·
+[MCP](docs/mcp.md) · [Security](docs/security.md) ·
+[Migration](docs/migration-v1.md)
 
-Empirical targets Node.js 20+ at runtime. Bun is used for development, tests,
-and building the published JavaScript package.
+## License
 
-License: MIT.
+[MIT](LICENSE)