@encore-os/eos-spec

A portable, config-driven spec-pipeline engine + quality harness. It ships two faces from one package: an agent-friendly CLI (eos-spec) and a library (with a browser-safe /pure subpath). The package carries no corpus data — it drives any repo's specs/ tree as described by that repo's specs/config.yaml.

Specs move through a pipeline (stub → clarified → validated → … → tasks_generated); the engine derives each spec's stage from signals in its markdown, recommends the next action (blocker-aware), and gates completion claims against on-disk evidence.

Quickstart — with a coding agent (recommended)

npm install -D @encore-os/eos-spec   # or run everything via npx
npx @encore-os/eos-spec setup        # prints the onboarding plan
npx @encore-os/eos-spec setup --yes  # scaffold layout + AI_GUIDE.md + install spec-pipeline-skills (Claude Code)

Then prompt your agent — e.g. "Read AI_GUIDE.md and use eos-spec to create and drive a spec for ." The generated AI_GUIDE.md teaches the agent the loop: profile --json first, then next / run, always --json, switching on machine error codes.

Quickstart — manual

npx @encore-os/eos-spec init --scaffold      # specs/config.yaml + templates + per-core dirs
npx @encore-os/eos-spec create APP-01 "First feature"   # `app` is the scaffolded default core
npx @encore-os/eos-spec validate --core app
npx @encore-os/eos-spec next --spec APP-01   # the one recommended next action

eos-spec --help lists a worked example for every command.

Machine contract

Every command accepts --json and emits one stable envelope:

{ "ok": true, "data": { "…": "…" } }
{ "ok": false, "data": null, "error": { "code": "SPEC_NOT_FOUND", "message": "…" } }

Error codes are a frozen, append-only enum (SPEC_NOT_FOUND, UNKNOWN_CORE, INVALID_ARGUMENT, SCOPE_REQUIRED, VALIDATION_FAILED, DUPLICATE_SPEC_ID, SUBPROCESS_ERROR, IO_ERROR, ENGINE_VERSION_MISMATCH, INTERNAL) — switch on error.code, never regex the text. Skills that wrap this CLI pin their supported engine range with the global --require-engine ">=0.23 <1" flag; a mismatch fails fast with ENGINE_VERSION_MISMATCH.

Entry points

• @encore-os/eos-spec — fs-bound main entry: the CLI program plus the corpus API (listSpecs, findSpec, loadConfig, …).
• @encore-os/eos-spec/pure — fs-free re-exports only; safe to bundle in a browser app. Enforced by a purity test on transitive value imports.
• @encore-os/eos-spec/embeddings — narrow fs-bound subpath for a corpus-local embeddings build + recall, without dragging in the CLI graph.

Precedent & semantic search

The precedent command searches active + archived specs, registry, and deferred dashboard for prior art:

• precedent --spec <id> — Lookup precedent for one spec (identifier overlap). Returns specs sharing backtick-quoted table identifiers, ranked by document frequency (distinctive shared tables rank higher).

• precedent --topic <text> — Lookup precedent for a topic keyword (ranked search). Ranks results semantically when vectors + embedder are available (via live query embedding with Ollama); lexical fallback when either is absent. The output carries a rankMode field ('semantic' or 'lexical') to signal which method ranked the hits. When ranking semantically, archived specs are not in the embedding corpus; status metadata may show 'unknown' for semantic hits.

Both modes support --core <core> to scope search to one core. The --all flag lifts the default cap (15 top matches).

Create gates: precedent block mode

Repos can declare a create_gates block in specs/config.yaml to opt into block mode for the create command's Tier-2 precedent auto-check:

create_gates:
  precedent: block            # 'warn' (default) | 'block'
  precedent_block_min_score: 12

• precedent: 'warn' (default) — Surfaces prior art but never blocks. Shows top lexical hits when a spec ID or title has a near-duplicate precedent.

• precedent: 'block' — Halts create (non-zero exit, no scaffold) when the top lexical hit's score clears precedent_block_min_score. The --force flag overrides (logged). Fail-open on config/search errors.

• precedent_block_min_score — Lexical score floor (searchSpecs' score field); default is 12. A bare title match never reaches 12 alone — the floor requires genuine two-signal corroboration (title AND body). Pass create <id> --force to force-create despite a high precedent hit.

Exactly one create-precedent gate event is logged per invocation, regardless of whether the check warns or blocks.

Companion skills

The encore-plugins marketplace ships spec-pipeline-skills — nine Claude Code skills that drive this engine (setup --yes installs them):

claude plugin marketplace add Encore-OS/encore-plugins
claude plugin install spec-pipeline-skills@encore-plugins --scope user

Versioning & release

SemVer. Releases are cut by release-please and published to the public npm registry on tag; the CHANGELOG is generated — behavior changes ride Conventional Commit PR titles. Node ≥ 22, ESM only.