> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Spec Pathways

> How Encore's two spec systems — product specs vs build-process specs — differ, and how to pick the right path.

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

|                | `docs/superpowers/specs/`                                                    | `specs/{core}/`                                                          |
| -------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| Holds          | Dated design docs for *meta-work* — tooling, automation, CLI, process, infra | Governed *product feature* specs (RBAC, workflows, billing, clinical, …) |
| Naming         | `YYYY-MM-DD-<topic>-design.md`                                               | `{CORE}-{N}-<slug>.md` (e.g. `PM-21-...`)                                |
| Governance     | None — session artifacts                                                     | Templates, `pipeline_status`, compliance gates, `eos-spec` pipeline      |
| Produced by    | `superpowers:brainstorming` → `superpowers:writing-plans`                    | `create-spec` → the spec→test pipeline (`eos-spec next`)                 |
| Tests/registry | None                                                                         | TASKS, generated tests, SPEC\_STATUS\_REGISTRY, FEATURE\_CATALOGUE       |

## 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.