Skip to main content
Encore has two places called “specs”. They are orthogonal, not duplicates. Pick by asking: am I changing the platform’s product, or how we build it?

​
The two paths

​
Decision matrix

  • Building or changing a product feature users touch → specs/{core}/. Start with create-spec (run eos-spec precedent first for prior art).
  • Designing how we build — a CLI command, a skill, CI, a workflow, a refactor of the tooling itself → docs/superpowers/specs/ via superpowers:brainstorming.
  • Unsure? If it ships in the app and has acceptance criteria a user could verify, it’s a product spec. If it changes the developer/agent workflow, it’s a superpowers design.

​
The bridge

A superpowers design may spawn one or more Encore product specs (e.g. a tooling design that requires a new PF feature). There is intentionally no auto-conversion. When a design spawns product specs, list their IDs in the design doc’s “Deliverables” section and, in each product spec, reference the design path under its context. Keep the governed spec as the source of truth for the shipped feature; the design doc stays as the rationale record.

​
Tooling notes (2026-05-30 dogfood)

  • eos-spec tasks <id> writes a SCAFFOLD, not finished tasks. It stamps the generic phase template (with {core}_{entity_name} and <US-1 value> placeholders) and does no spec-aware fill or migration-collision analysis. The spec-aware task breakdown is the generate-tasks skill; collision detection is the next/landscape advisory (migration-collision.ts). Don’t treat the raw tasks scaffold as final, and don’t expect collision warnings from it.
  • Fresh git worktrees need npm ci. A worktree created off development has no node_modules, so npx @encore-os/eos-spec … (or npm run spec -- …) fails with ERR_MODULE_NOT_FOUND. Run npm ci in the worktree — that installs the canonical @encore-os/eos-spec package (no build step; the in-tree fork is retired #1831). Symlinking the main checkout’s node_modules is not reliable — it produces intermittent Unknown system error -70 reads on this filesystem.