Encore OS — Documentation

Version: 1.2.0 Last Updated: 2026-05-27 Canonical specification workflow: command order, decision points, and links to related commands. Command cheat sheet (tiers): SPEC_COMMAND_CHEATSHEET.md

Pipeline stages

The canonical stage → actor mapping, generated from tools/eos-spec/src/lib/pipeline-map.ts:

Stage (`pipeline_status`)	Canonical actor	Layer	Flags
`clarified`	clarify-spec command	Encore	optional
`validated`	validate-spec command	Encore	—
`regulatory_grounded`	encore-spec-research skill	Encore	regulated-only
`reviewed`	spec-review skill	Encore	—
`—`	encore-spec-research skill	Encore	—
`—`	validate-spec command	Encore	—
`—`	compliance-reviewer agent	Encore	—
`compliance_reviewed`	compliance-reviewer agent	Encore	—
`—`	encore-spec-ac-draft skill	Encore	—
`—`	encore-spec-to-test skill	Encore	—
`ux_reviewed`	encore-a11y-audit skill	Encore	optional
`planned`	create-plan / validate-plan command	Encore	—
`tasks_generated`	generate-tasks command	Encore	—

Workflow Diagram

Linear sequence:

create-spec → clarify-spec → validate-spec → spec-review → [compliance-reviewer (regulated cores)] → [validate-plan] (when plan exists; create-plan only if plan needed but not created) → [discuss/CONTEXT] → generate-tasks  ║  [implement] → [documentation] → verify → spec-complete

The ║ boundary marks where spec-pipeline stops. Implementation (via the superpowers:executing-plans skill) is a separate step initiated by the user.

Post-completion archive step (optional but recommended for done specs):

Run eos-spec archive --spec {CORE-##} (or bulk with --core --status complete) to move completed artifacts into specs/{core}/archive/.
Archive filtering treats both Complete and Implemented as done-state statuses.
After archive, manually update discovery docs (SPEC_STATUS_REGISTRY.md and DEFERRED_DASHBOARD.md when relevant).

Navigate the workflow: Use eos-spec next --spec {CORE-##} to get the single next action at any time (no need to memorize the sequence).

Full-pipeline navigation: eos-spec next --spec {CORE-##} now covers the Claude-skill stages too (research → spec-review → AC draft → test generation → a11y), names the actor + exact invocation, and flags [human-gate] stops. The using-encore skill is the session gateway; every Encore spec/test skill ends with a ▶ Next: line pointing back to eos-spec next.

Before create-spec (hard stops — do not assign a new ID until both pass):

Active-spec overlap. Run npm run spec -- precedent --core {core} --topic "{feature-name}" so archived and superseded specs in specs/{core}/archive/ and specs/SPEC_STATUS_REGISTRY.md factor into scope decisions. If an active (non-archived) spec at the same conceptual scope exists, STOP. Author the work as an enhancement of that spec, or document explicit non-overlap.
Migration-table collision. For each intended table, confirm it does not already exist in supabase/migrations/:
grep -riIl "create table[^;]*\b{core}_{name}\b" supabase/migrations/
If any intended {core}_* table is already defined, STOP. Never re-define a table that already lives in supabase/migrations/.

Once a draft spec exists, spec-review enforces both gates via npm run spec -- precedent --spec {ID} --check-migrations and npm run spec:landscape-scan -- --spec {ID} and HALTS the review if either trips. Early research seeding (optional, before the full MCP-backed run): Use npm run spec:research:seed -- --seed <seed-or-spec-path> --core {core} to get the applicable citation classes (which regulatory surfaces apply) without invoking an LLM or MCP. Pass --mock in CI/offline. This decouples cheap “which regs apply” classification from the more expensive citation-verification pass that runs after validated. Deferred features: Use spec deferred --list, spec deferred --promote, spec deferred --sync for listing, promoting, and regenerating the deferred dashboard. See spec-deferred. The dashboard file specs/DEFERRED_DASHBOARD.md is auto-generated by spec deferred --sync (run the command to create/update it). The commands promote-deferred and sync-deferred-summary are deprecated (sunset: 2026-06-01); use spec deferred instead. Canonical spec commands (use these): create-spec, clarify-spec, validate-spec, spec-pipeline, prepare-spec, create-plan, validate-plan, generate-tasks, review-ux (optional UI pass), spec-review (in-chat spec review), spec-complete, spec deferred (—list | —promote | —sync), pre-commit-check, session-status, pause-work, resume-work. Wizard UX one-shot: wizard-spec-pipeline. Navigation/status via the eos-spec CLI (next / status / list); the discuss/CONTEXT, implement, and verify steps are owned by superpowers skills (brainstorming, writing-plans/executing-plans, verification-before-completion). See SPEC_COMMAND_CHEATSHEET.md for the full tiered list. Command tiers: SPEC_COMMAND_CHEATSHEET.md Deprecated / do not use: promote-deferred, sync-deferred-summary → use spec deferred. audit-spec-completion, update-spec-status, complete-feature → use spec-complete with flags (see SPEC_COMPLETION_TRACKING.md). Board and assignment tracking: For GitHub Project setup and when to update the board, see GITHUB_PROJECT_SPEC_TRACKING_PLAN.md. Implementation in Lovable: Tasks are often implemented in Lovable AI (which does not have Cursor rules). Each TASKS file includes an “Implementation rules for Lovable / external AI” section so implementers have the necessary patterns. See AGENTS.md and specs/_templates/TASKS_TEMPLATE.md.

GitHub issues vs formal specs

Use GitHub issues (see .github/ISSUE_TEMPLATE/) for bugs, small enhancements, and feature ideas that are not yet spec-backed. Use the spec pipeline below when work is non-trivial per constitution and AI_GUIDE.md. Escalate from an issue to a formal spec when any of the following is true:

Signal	Action
Database schema, migration, or RLS change	Run `create-spec` (or promote from enhancement catalog); follow full pipeline.
Cross-core behavior or new integration contracts	Spec required; document boundaries in `## Spec landscape & boundary`.
New reusable UI primitives or multi-module patterns	Spec required (or SPEC_TEMPLATE_LITE if truly UI-only and low risk).
Complex business rules, compliance/regulatory scope, or ambiguous security	Spec required; use spec-reviewer and regulated-core checklists in `AI_GUIDE.md`.
CodeRabbit / triage plan shows multi-phase work or unclear ownership	Create or extend a spec; attach plan notes to the spec’s pre-planning section.
Simple bug fix, copy change, or single-file UI tweak with no schema impact	Issue + PR is enough; link `Closes` / `Refs` in the PR body (see `.github/pull_request_template.md`).

Decision tree (canonical): See “Should I Create a Spec?” in AI_GUIDE.md (Decision Trees). CodeRabbit Issue Planner: Optional coding plans from GitHub issues (@coderabbitai plan or labels configured in .coderabbit.yaml) can inform implementation; they do not replace validate-spec, constitution checks, or regulatory sections in specs.

What Each Step Does

Step	Purpose
create-spec	Create spec from template; pre-fill core, ID, dates. For CL/PM, load docs/ehr_pm/ai-context (see README) and research-20260216.md when drafting.
clarify-spec	Resolve ambiguities (placeholders, TODOs); optional `--auto-accept` records AI-recommended answers. Review the Clarifications section before generate-tasks.
validate-spec	Fast structural and constitution check; `## Spec landscape & boundary` required (warn if missing/incomplete per validate-spec command). Validates only — `--auto-fix` and `--auto-plan` are not implemented in `scripts/specs/validate.ts` and are silently ignored. When validation reports issues, apply fixes manually and re-run; when a plan is indicated (complexity score ≥4), create one via the `create-plan` command. Run before spec-reviewer.
spec-review	spec-review skill. • Default: Auto-applies recommendations (required spec-landscape research for overlap/conflict, then Stage 1–3, then safe and contextual edits with review-and-understand). Output is short summary + Duplication & boundary bullets + Applied + Manual follow-up; no full report unless user asks to save. • Opt-out: Say “report only”, “review only”, or “do not apply” to get the full report without applying edits. • Research: Skill must search same-core specs and integration docs per `automation/skills/spec-review/references/spec-review-process.md` Required research (spec landscape); for CL/PM also loads docs/ehr_pm/ai-context and research-20260216.md. • Before reviewing auto-applied changes: See AUTO_APPLY_SAFETY.md for PHI/PII, multi-tenancy, and compliance areas to spot-check. • Invocation: Invoke the `spec-review` skill; provide spec path or `{CORE-##}` in chat. • Process reference: See automation/skills/spec-review/references/spec-review-process.md for the authoritative review process (Stages 1–3, auto-apply default, completion marker).
create-plan	Use when a plan is needed and `validate-spec` reported a score ≥4 (or force-create when score <4, or re-create after spec changes).
validate-plan	Validate plan structure, “Based On” link, and required sections. Run after creating or editing a plan.
discuss/CONTEXT (`superpowers:brainstorming`)	Capture implementation preferences (UI layout, behavior choices, error handling) before task generation. Creates `{CORE}-##-CONTEXT.md`; referenced by `generate-tasks` and implementers. Optional but recommended for specs with UI or multi-valid approaches. Run before generate-tasks.
review-ux	Optional focused UI/UX checklist (spec UI section, dialog tiers, primitives). See .cursor/commands/specs/review-ux.md. Use when UI is heavy or the discuss/CONTEXT step was skipped; does not replace spec-reviewer.
generate-tasks	Task breakdown with execution steps; includes “Implementation rules for Lovable” block. Reads CONTEXT.md if present.
eos-spec next	Infer current spec state and output the single next command; use to drive the pipeline without memorizing order. Run with `--spec {CORE-##}` or `--core {core}`. Skips terminal-status specs (`deferred` / `archived` / `blocked` / `superseded`) so they never resurface as a core’s next pick. For UX/wizard specs under `specs/{core}/ux/`, routes from the spec’s own `TASKS.md` instead of the spec body. When a spec is claimed-complete but unverified, surfaces a debt warning and points at `npm run spec:check-debt` / `npm run spec:verify-acs -- --enforce`.

Context for CL/PM specs

When creating or reviewing a CL or PM spec, load EHR/PM context so requirements align with domain and implementation guidance. Load (1) docs/ehr_pm/ai-context/README.md and the domain file(s) that match the spec ID from the “Load when working on” table, and (2) docs/ehr_pm/research-20260216.md. This applies to create-spec (author should have this context when drafting) and spec-reviewer (agent loads it before review). Chunks (docs/ehr_pm/_artifacts/ai_ingest_ehr_pm_chunks/) are optional for migration or incumbent-system mapping only.

Command Order by Phase

Phase 1: Spec Creation and Clarification

Step	Command	Purpose
1	`create-spec --core {core} --name {name}`	Create spec from template
2	`clarify-spec --spec {CORE-##}` (optionally `--auto-accept`)	Resolve ambiguities before planning
3	`validate-spec --file specs/{core}/specs/{CORE}-##-{name}.md`	Validate structure and constitution; apply any reported fixes manually and re-run; if score ≥4, run `create-plan`
4	spec-review skill (provide spec path or `{CORE-##}`; recommendations are applied by default; say “report only” to get full report without applying)	Deep implementability review; run after validate-spec
4b	compliance-reviewer (Cursor agent or Claude Code agent; recommended for regulated cores)	Regulatory compliance review for CL/PM/HR/RH/GR specs; run after spec-reviewer. Included in `spec-pipeline` for regulated cores by default.

Decision: Use SPEC_TEMPLATE.md for complex features (DB, multi-phase); use SPEC_TEMPLATE_LITE.md for simple UI-only features. See specs/_templates/TEMPLATE_INDEX.md and SPEC_GUIDE.md.

Simple spec (fast) path

For low-complexity specs (SPEC_TEMPLATE_LITE, or single-phase UI-only, no DB changes):

When: Spec uses SPEC_TEMPLATE_LITE or is known to be low-complexity (no database, single phase, UI-only).
Path: create-spec → validate-spec → generate-tasks
Optional: Run clarify-spec if the spec has placeholders; run the spec-review skill for critical or cross-cutting features. Skip create-plan / validate-plan when score <4 (validate-spec will report “plan not needed”).
Effect: Fewer steps for small features; use the full pipeline (clarify → validate-spec → spec-reviewer → create-plan → validate-plan → generate-tasks) for complex or multi-phase specs.

Phase 2: Planning and Task Generation

Step	Command	Purpose
5	`validate-plan --spec {CORE-##}` when plan exists; else `create-plan --spec {CORE-##}` then `validate-plan --spec {CORE-##}`	If validate-spec in step 3 reported score ≥4, run create-plan then validate-plan. If a plan already exists, run validate-plan directly.
5b	`superpowers:brainstorming` skill (recommended)	Capture UI/behavior preferences before task generation; creates CONTEXT.md. Critical for specs with UI, multiple valid approaches, or regulated compliance details.
6	`generate-tasks --spec {CORE-##}`	Task breakdown from spec/plan (reads CONTEXT.md if present). `spec-pipeline` stops here.

Decision: Use a separate plan when complexity score ≥4 or multi-phase. Run validate-spec in Phase 1; when it reports score ≥4, run create-plan then validate-plan. See specs/_templates/SPEC_GUIDE.md (“When to Use a Separate Plan Document”).

Phase 3: Implementation

Note: spec-pipeline ends at Phase 2 (generate-tasks). Phase 3 is a separate step initiated by the user via the superpowers:executing-plans skill or manual implementation.

Step	Command	Purpose
7	`superpowers:executing-plans` skill (or implement per TASKS file manually)	Structured implementation: preflight, workstream proposal, gated execution.
8	Documentation	Create user/admin guides per spec’s Documentation Deliverables section. Use `docs/templates/USER_GUIDE_TEMPLATE.md` and `docs/templates/ADMIN_GUIDE_TEMPLATE.md`. Documentation tasks (T14/T15 or T-DOC-*) are generated by `generate-tasks` when required.
9	`superpowers:verification-before-completion` skill	Verify each task completion
10	`pre-commit-check`	Before committing

Decision: Run the verification step (superpowers:verification-before-completion) after each task (or batch); run pre-commit-check before every commit. Complete documentation during implementation (documentation-as-you-go). Atomic commits: One commit per task using conventional format feat(CORE-##-TN): description. See .cursor/rules/git-commit-patterns.md. Session management: Use pause-work when stopping mid-task and resume-work to restore context. Use session-status to check current position. See .cursor/rules/session-state-patterns.md. Long features (Document-and-Clear): After every 3–4 tasks, optionally write specs/{core}/specs/{CORE-##}-PROGRESS.md with: completed work, decisions made, blockers, next task. Clear context and resume with CLAUDE.md + spec + PROGRESS.md to preserve architectural decisions across long sessions.

Phase 4: Completion

Step	Command	Purpose
11	Documentation	Verify user/admin guides exist if required by spec’s Documentation Deliverables. `spec-complete` reports missing guides as warnings.
11a	Docshots (UI specs)	`eos-spec next` blocks completion until docshot evidence exists: a `docs/images/<area>/<spec-id>-.png` (captured via a `-docs-shots.spec.ts` in the local lane, verified by `npm run docs:shots:check`), or a `docshots` sign-off when no surface is worth documenting. `/docs-shots <area> --signoff-spec {CORE-##}` auto-emits `eos-spec signoff --type docshots` after the drift check passes — you no longer hand-emit it. CI runs the drift check enforcing (`docs:shots:check:enforce`); capture stays local.
11b	Browser auto-heal (UI specs)	`eos-spec next` blocks completion until a green auto-heal verdict is recorded: run `/heal-e2e {CORE-##}` (console/pageerror/network>=400 capture, fix to `HEAL_VERDICT=green`). On green the loop auto-emits `eos-spec signoff --type heal-verified` when the target is a resolvable spec id (look for `HEAL_SIGNOFF=ok`); a bare-core/path target prints `HEAL_SIGNOFF=skipped`, so sign that spec off yourself.
11c	Submit→DB E2E (create-wizards)	For wizard specs that create a record, `eos-spec next` blocks completion until a submit→DB E2E proves the wizard persists a row. Add `tests/e2e/<core>/<spec-id>-<slug>-local.spec.ts` driving the wizard → submit → asserting the persisted row (exemplar: `tests/e2e/gr/gr-ux-13-training-course-local.spec.ts`); run `npm run test:e2e:local`. If the wizard has no submit path, record `eos-spec signoff --type submit-e2e-waived --spec {CORE-##}`. Config and non-wizard specs are exempt.
12	Test coverage	Before spec-complete: ensure spec–test matrix is updated; required tests exist (RLS for tables, E2E for critical flows). Run `generate-test-suite {CORE-##}` (dry-run first) to scaffold missing RLS/unit/integration tests. Add `@spec CORE-##` in test file headers.
13	`npm run check-rls-coverage` (if DB/RLS)	Verify RLS coverage; fix or document gaps.
13a	Dogfood result (UI / dogfooded specs)	When a spec is dogfooded (a run record under `evals/dogfood/{CORE-##}-run.md`), record a `dogfood-result:` frontmatter field (see Dogfood result below). `spec-complete` warns when a UI/dogfooded spec lacks it. The corpus is rolled up by `npm run dogfood:metrics`.
14	`spec-complete --spec {CORE-##}`	Validate, update log, optional audit. Routes through the engine gate (`npm run spec -- complete --enforce --spec {CORE-##}`) so the slash command and bare CLI converge on one done-ness decision; the UI-evidence gate (docshots + heal-verified) decides. Or `/spec-ship {CORE-##}` to drive the whole tail (verify-acs → heal → docshots → `complete --enforce`) in one pass.
(optional)	`spec-complete --spec {CORE-##} --update-registry`	Full audit and registry update

Event registry sync (when spec adds new events): Keep three sources in sync: (1) KnownEventName in src/platform/events/types.ts, (2) event contract sections in docs/architecture/integrations/EVENT_CONTRACTS.md, (3) fw_workflow_events seed/migration data. When completing a spec that introduced new events, verify all three are updated. A future check-event-registry-sync script may automate this. Decision: Use eos-spec status --spec {CORE-##} --detailed for read-only status; use spec-complete for all completion and status-update operations.

Decision Points

When you need to…	Use
Create a new spec	`create-spec`
Check for ambiguities before planning	`clarify-spec`
Validate spec structure/completeness	`validate-spec`
Read-only overlap triage (same-core identifiers, integration paths)	`spec-landscape` or `npm run spec:landscape-scan -- --spec {CORE-##}`
Validate wizard spec	`validate-spec --file specs/{core}/ux/….md --type wizard`
Deep implementability review (after validate-spec)	`spec-review` skill (provide spec path or `{CORE-##}`). Recommendations are applied by default; output is short summary + Duplication & boundary + Applied + Manual follow-up. Say “report only” or “do not apply” to get the full report without applying. Required: spec landscape research (adjacent specs, integration docs, regulated-core trackers as applicable). See spec-review-process.md.
Create implementation plan (when score ≥4)	`create-plan`
Validate plan structure and spec linkage	`validate-plan`
Run the full canonical one-shot pipeline (create/resolve → validate → clarify → review → compliance → plan check → context → tasks; does NOT implement)	`spec-pipeline {CORE-##}` or `spec-pipeline --spec {CORE-##}` (or `--create --core {core} --name {slug}`); slash form `/spec-pipeline hr-42` normalizes to `--spec HR-42`
Run validation + plan validation + optional generate-tasks in one go	`prepare-spec --spec {CORE-##}` (optional `--generate-tasks`)
Run the full wizard UX one-shot pipeline	`wizard-spec-pipeline --spec {CORE-UX-##}` (or `--create --core {core} --name {slug}`)
Get the single next action for a spec	`eos-spec next --spec {CORE-##}`
List or manage deferred features	`spec deferred --list`, `spec deferred --core {core}`, `spec deferred --promote`, `spec deferred --sync`
Generate task breakdown	`generate-tasks`
Capture UI/behavior preferences before implementing	`superpowers:brainstorming` skill
Check current session position (mid-implementation)	`session-status`
Stop mid-task and save state for later	`pause-work` (optionally `--commit`)
Resume after pausing	`resume-work`
Generate tests from spec	`generate-test-suite`
Check workflow status (read-only)	`eos-spec status`
Update status / complete feature / audit	`spec-complete`
Verify a single task	`superpowers:verification-before-completion`
Run quality checks before commit	`pre-commit-check`
Holistic module gap analysis and planning (quarterly, pre-kickoff)	deep-module-review (module-strategic-reviewer agent). See deep-module-review.
Full module review + cross-module comparative scan with optional external research (—research) → prioritized new and enhanced spec recommendations	recommend-module-specs (module-strategic-reviewer agent). See recommend-module-specs.

Overlap and duplication

Use the right tool for the kind of overlap:

Need	Use
Structure, constitution, warnings for `## Spec landscape & boundary`	`validate-spec` (fix issues manually and re-run)
Fast read-only heuristics (same-core table-style identifiers, integration path signals)	`spec-landscape` command or `npm run spec:landscape-scan -- --spec {CORE-##}`
Judgment, adjacent-spec research, Duplication & boundary, safe edits	`spec-review` skill (after `validate-spec`) — see spec-review-process.md
Quarterly module-wide strategy, gaps, new spec ideas	deep-module-review
Cross-module comparative pattern scan with optional external research (—research) → prioritized new + enhanced specs	recommend-module-specs
Registry / tracking / Bucket C–E reconciliation (not semantic spec overlap)	`npm run spec:reconcile-tracking` (see specs/README.md)
Full issue-sync loop after registry updates	See Full Issue-Sync Loop below.
Duplicate GitHub issues vs registry	deep-module-review —sync-issues

Do not run validate-spec again when you meant an overlap scan—use spec-landscape (or the npm script) first, then spec-review if ambiguity remains.

Full Issue-Sync Loop

Run this sequence after registry updates:

spec-complete --all --update-registry
npm run spec:reconcile-tracking
npm run bootstrap:spec-issues -- --sync --active-only
npm run spec:close-stale-tracking
npm run spec:add-tracking-to-project -- --state open
npm run spec:sync-project-status
npm run spec-tracking:verify -- --scope active

Command	Category	Purpose
`create-spec`	specs	Create spec from template
`clarify-spec`	specs	Resolve ambiguities
`validate-spec`	specs	Validate structure and completeness
`spec-landscape`	specs	Read-only overlap triage (same-core collisions, integration signals); see spec-landscape; optional: `npm run spec:landscape-scan -- --spec {CORE-##}`
`spec-review`	skills	spec-review skill: deep implementability review (provide spec path or `{CORE-##}`; recommendations applied by default; say “report only” to get full report without applying; run after validate-spec)
`spec-pipeline`	specs	Full canonical one-shot pipeline: resolve/create, validate, clarify, spec-reviewer, compliance-reviewer (regulated cores), optional review-ux, re-validate/plan, discuss/CONTEXT, generate-tasks. Does NOT implement.
`prepare-spec`	specs	Optional one-shot: validate-spec, then validate-plan when a plan exists (and optionally generate-tasks). Fixes are applied manually.
`wizard-spec-pipeline`	specs	Full wizard UX one-shot pipeline: create/resolve, wizard validation, clarify, spec-reviewer, review-ux, re-validate/plan, discuss/CONTEXT, generate-tasks
`create-plan`	specs	Create implementation plan when needed (constitution-aligned)
`validate-plan`	specs	Validate plan structure and spec linkage
`generate-tasks`	specs	Generate task file. `spec-pipeline` stops here.
`superpowers:brainstorming`	skills	Pre-implementation gray-area discussion (discuss/CONTEXT step); creates CONTEXT.md
`superpowers:executing-plans`	skills	Structured implementation: preflight, workstreams, gated execution. Run after `generate-tasks`.
`spec-review`	specs	In-chat spec review (alternative to spec-reviewer agent when agent invocation fails)
`generate-test-suite`	specs	Generate RLS/unit/integration/E2E tests
`eos-spec status`	specs	Read-only status (quick or detailed)
`eos-spec next`	specs	Next action for spec (infer state, output next command)
`spec-complete`	specs	Completion workflow, audit, registry
`spec deferred`	specs	Deferred features: list, promote, sync dashboard
`superpowers:verification-before-completion`	skills	Verify task completion
`session-status`	development	Show current session state (spec, task, decisions)
`pause-work`	development	Save state and create handoff for resuming later
`resume-work`	development	Restore from handoff and continue
`pre-commit-check`	development	Pre-commit validation
`check-rls-coverage`	database	RLS test coverage
`deep-module-review`	specs	Holistic module gap analysis and planning (quarterly, pre-kickoff); see deep-module-review
`recommend-module-specs`	specs	Full module review + cross-module comparative scan with optional external research (—research) → prioritized new spec proposals AND enhancement recommendations; see recommend-module-specs

AC-coverage drift (shipped-but-unverified)

npm run spec:ac-drift reports specs whose code shipped (they have @verifies tests) but whose ACs are still planned, bucketed by how cheap the fix is:

promotable-now — an @verifies AC-N tag exists; run npm run spec:verify-acs -- --spec <ID> --write.
backlink-recoverable — an FR-tagged test covers the AC; run npm run spec:ac-backlink -- --spec <ID> to scaffold the AC tag (review it — an FR proof is not automatically an AC proof), then verify-acs —write.
needs-work — no test covers the AC’s FRs; author one.

The nightly ac-drift-sweep.yml upserts an “AC-coverage drift burndown” issue. Nothing auto-promotes.

Dogfood result

When a spec is exercised through a dogfood pass (its run record lives at evals/dogfood/{CORE-##}-run.md), record the outcome on the spec’s frontmatter as a dogfood-result: field. This turns an anecdotal run record into a structured, checkable signal that the completion audit reads and npm run dogfood:metrics rolls up (scripts/dogfood/collect-dogfood-metrics.ts).

dogfood-result:
  run: evals/dogfood/CL-02-run.md   # path to the run record
  date: 2026-05-28
  human-touches: 3                  # total human touches in the pass
  defects: 4                        # T-tag count (P0+P1+P2)
  rubric-avg: 4.8                   # mean rubric score (out of 5)
  stages-cleared: "4/4"             # stages advanced / attempted

spec-complete (step 1c / 13a) warns — never blocks — when a UI-bearing or dogfooded spec is missing this field. It is optional for backend/data-only specs that were not dogfooded. The fields mirror what the metrics collector parses from the run record, so a spec author can copy them straight from the record’s Summary block.

Constitution: constitution.md – engineering guardrails; spec and plan validation align with §1–§6
Templates: specs/_templates/TEMPLATE_INDEX.md – template decision tree and list
Template design rationale: docs/development/SPEC_TEMPLATE_DESIGN_RATIONALE.md – why each template constraint exists (failure modes + mitigations); read once before authoring your first spec
Spec process review (Spec Kit comparison): SPEC_TEMPLATE_DESIGN_RATIONALE.md – contains the adopted recommendations (R1–R8) informed by the GitHub Spec Kit comparison
Spec usage: specs/_templates/SPEC_GUIDE.md – when to use plan, data model decisions
Directory structure: specs/_templates/SPEC_GUIDE.md – complete path conventions and directory layout
Checklists: specs/_templates/SPEC_GUIDE.md – pre-flight, compliance, RLS
Auto-apply (optional guidance): AUTO_APPLY_SAFETY.md – optional: categories to consider for human review after auto-apply
Lovable handoff: AGENTS.md § Lovable Cloud Integration – making specs/tasks self-contained for Lovable
Regulatory compliance: docs/compliance/REGULATORY_COMPLIANCE_TRACKER.md – regulatory deadlines and interim procedures
AGENTS.md – Specification Protocol, completion tracking
Regulatory Compliance Decision Tree – .cursor/rules/regulatory-compliance.md
AI_GUIDE.md – Spec-first delivery, implementation log
Wizard workflow: docs/development/WIZARD_DEVELOPMENT_GUIDE.md, docs/development/WIZARD_UX_STANDARD.md
Session state: .cursor/rules/session-state-patterns.md – pause/resume and session state patterns
Git commit patterns: .cursor/rules/git-commit-patterns.md – atomic commits per task
EHR/PM context (CL/PM): docs/ehr_pm/ai-context/README.md, docs/ehr_pm/research-20260216.md – load when creating or reviewing CL/PM specs

Recommended agents and skills

After implementation: Run verifier (run commands, show output) and code-reviewer (spec compliance then code quality) before PR/commit. For specs that touch RLS, PHI, multi-tenancy, or new migrations, run security-auditor pre-deploy or before merge. For architecture or refactors, architecture-validator can validate rules and patterns. Specs with external APIs or integrations (PDMP, FHIR, etc.): Before or during spec, use technical-researcher to gather API docs, SDKs, and best practices; use integration-contract-author when adding or changing event/API contracts. During implementation, use the api-integration-specialist skill (auth, retries, rate limits, error handling, no secrets in code).

Agent	When to use
spec-review skill	After validate-spec; deep implementability review; recommendations applied by default; say “report only” to get full report without applying
technical-researcher	Integration research, library/API evaluation, external API docs (integration-heavy specs)
code-reviewer	Before PR/commit; two-stage: spec compliance then code quality
verifier	After tasks marked done; run commands and report pass/gaps
security-auditor	Pre-deploy or new migrations; RLS, PHI, multi-tenant isolation, secrets
architecture-validator	Before commit or after refactors; architecture rules and patterns
integration-contract-author	When adding or changing event/API contracts or integration catalog
compliance-reviewer	After validate-spec (regulated cores CL/PM/HR/RH/GR); verify regulatory requirements before generate-tasks; Claude Code agent alternative to spec-reviewer Stage 3
module-strategic-reviewer	Quarterly holistic module gap analysis and planning (pre-kickoff); complements spec-reviewer for module-level strategy. Implements both deep-module-review (single-module) and recommend-module-specs (cross-module + optional external research via —research → new + enhanced spec recommendations).

Commands: validate-spec before spec-reviewer (fix issues manually, create plan via create-plan when score ≥4); validate-plan when a plan exists; verification (superpowers:verification-before-completion) after each task or batch; pre-commit-check before commit; spec-complete for completion; generate-test-suite for test scaffolding; npm run check-rls-coverage when DB/RLS changed. Skills: api-integration-specialist (third-party APIs), supabase-postgres-best-practices (Postgres/RLS), verification-before-completion (before claiming work complete), systematic-debugging (bugs/test failures), tdd-workflow (implementation when appropriate).

Quick Reference

Canonical order:

create-spec --core hr --name my-feature
clarify-spec --spec HR-XX --auto-accept
validate-spec --file specs/hr/specs/HR-XX-my-feature.md
# Run spec-reviewer agent (recommendations applied by default; save *-SPEC-REVIEW.md only when needed)
# Run compliance-reviewer for regulated cores (CL, PM, HR, RH, GR)
# If plan was created (score ≥4), validate it. If not and plan needed, run create-plan first.
validate-plan --spec HR-XX
# discuss/CONTEXT: run the superpowers:brainstorming skill to capture UI/behavior preferences (writes HR-XX-CONTEXT.md)
generate-tasks --spec HR-XX
# ── spec-pipeline stops here ── implementation is a separate step ──
# implement per the TASKS file via superpowers:executing-plans (preflight → workstreams → execute)
# verify each task via superpowers:verification-before-completion
# if stopping mid-session:
pause-work --spec HR-XX --task T2
# next session:
resume-work
# or check position:
session-status
pre-commit-check
spec-complete --spec HR-XX

One-shot pipelines: Use spec-pipeline {CORE-##} or spec-pipeline --spec {CORE-##} for the full canonical one-shot flow (including clarify/spec-reviewer, compliance-reviewer for regulated cores, optional UX/discussion, and generate-tasks). Slash invocations with bare spec IDs are normalized first, so /spec-pipeline hr-42 is equivalent to spec-pipeline --spec HR-42. The pipeline does not implement — it stops at generate-tasks. Use prepare-spec --spec {CORE-##} for the narrower validate+plan(+tasks) shortcut. For wizard UX specs, use wizard-spec-pipeline --spec {CORE-UX-##}. See .cursor/commands/specs/spec-pipeline.md, .cursor/commands/specs/prepare-spec.md, and .cursor/commands/specs/wizard-spec-pipeline.md. What’s next: Run eos-spec next --spec {CORE-##} anytime to get the next command. Deferred work: spec deferred --list, spec deferred --sync; dashboard: specs/DEFERRED_DASHBOARD.md. Status only (no writes):

eos-spec status --spec HR-XX
eos-spec status --spec HR-XX --detailed
eos-spec status --core hr --json

Start Here

Module Engineering Snapshots

Canonical AI Governance

Architecture

Integrations

Development

Decision Guides

Database

Module Reference

Testing

Migration

Operations

Governance & Security

Platform Internals

Canonical Spec Workflow

Pipeline stages

Workflow Diagram

GitHub issues vs formal specs

What Each Step Does

Context for CL/PM specs

Command Order by Phase

Phase 1: Spec Creation and Clarification

Simple spec (fast) path

Phase 2: Planning and Task Generation

Phase 3: Implementation

Phase 4: Completion

Decision Points

Overlap and duplication

Full Issue-Sync Loop

AC-coverage drift (shipped-but-unverified)

Dogfood result

Recommended agents and skills

Quick Reference

​Pipeline stages

​Workflow Diagram

​GitHub issues vs formal specs

​What Each Step Does

​Context for CL/PM specs

​Command Order by Phase

​Phase 1: Spec Creation and Clarification

​Simple spec (fast) path

​Phase 2: Planning and Task Generation

​Phase 3: Implementation

​Phase 4: Completion

​Decision Points

​Overlap and duplication

​Full Issue-Sync Loop

​Related Commands

​AC-coverage drift (shipped-but-unverified)

​Dogfood result

​Related Documentation

​Recommended agents and skills

​Quick Reference

Pipeline stages

Workflow Diagram

GitHub issues vs formal specs

What Each Step Does

Context for CL/PM specs

Command Order by Phase

Phase 1: Spec Creation and Clarification

Simple spec (fast) path

Phase 2: Planning and Task Generation

Phase 3: Implementation

Phase 4: Completion

Decision Points

Overlap and duplication

Full Issue-Sync Loop

Related Commands

AC-coverage drift (shipped-but-unverified)

Dogfood result

Related Documentation

Recommended agents and skills

Quick Reference