.cursor/commands/specs/). Full narrative: SPEC_WORKFLOW.md. Navigate without memorizing: eos-spec next --spec {CORE-##}.
Pipeline stages — canonical invocation
Machine-generated stage → invocation map (source:tools/eos-spec/src/lib/pipeline-map.ts):
| Stage | Canonical invocation |
|---|---|
clarified | clarify-spec —spec <SPEC-ID> |
validated | the /validate-spec command on <SPEC-ID> (writes the <!— validated: —> marker; alt: eos-spec signoff --type validated --spec <SPEC-ID>) |
regulatory_grounded | the encore-spec-research skill on <SPEC-ID> |
reviewed | the spec-review skill on <SPEC-ID> |
research-before-review | the encore-spec-research skill on <SPEC-ID> (research must precede review on the non-regulated path) |
revalidate-after-review | re-run the /validate-spec command on <SPEC-ID> after spec-review’s auto-applied edits, then eos-spec signoff --type revalidated-after-review --spec <SPEC-ID> |
compliance-for-sensitive | the compliance-reviewer agent on <SPEC-ID> (PHI/PII/billing/credentialing), then eos-spec signoff --type compliance --spec <SPEC-ID> |
compliance_reviewed | the compliance-reviewer agent on <SPEC-ID>, then merge its review PR |
draft-acs | the encore-spec-ac-draft skill on <SPEC-ID> |
generate-tests | the encore-spec-to-test skill on <SPEC-ID> |
ux_reviewed | the encore-a11y-audit skill on <SPEC-ID> (UI-bearing specs) |
planned | validate-spec —spec <SPEC-ID> —auto-plan (or create-plan), then validate-plan —spec <SPEC-ID> |
tasks_generated | eos-spec tasks <SPEC-ID> |
Tier 1 — Core workflow (use every feature)
| I want to… | Run | Notes |
|---|---|---|
| Check prior art before creating specs | npm run spec -- precedent --core {core} --topic "{feature}" | Searches active + archived specs, registry, deferred dashboard |
| Check migration-table collisions for a drafted spec | npm run spec -- precedent --spec {CORE-##} --check-migrations | Reports any table the spec defines that already exists in supabase/migrations/. STOP and rework as an enhancement if it trips. |
| Seed citation classes (early pipeline, no MCP) | npm run spec:research:seed -- --seed <seed-or-spec-path> --core {core} | LLM-free classifier that lists which regulatory surfaces apply, before the full MCP-backed research run. Add --mock in CI/offline. |
| Start a new spec | create-spec --core {core} --name {slug} | Output: specs/{core}/specs/{CORE}-##-{slug}.md. Hard-stop before assigning an ID if precedent finds an active overlap or if any intended {core}_* table already exists in supabase/migrations/. |
| Fix placeholders / ambiguities | clarify-spec --spec {CORE-##} | Before planning if TODOs remain |
| Structure + constitution + optional plan | validate-spec --file specs/{core}/specs/{CORE}-##-….md --auto-fix --auto-plan | Run before spec-reviewer |
| Know the single next step | eos-spec next --spec {CORE-##} | Uses artifacts + session state. Skips terminal-status specs (deferred / archived / blocked / superseded). For UX/wizard specs under specs/{core}/ux/, routes from the spec’s own TASKS.md. Surfaces a verification-debt warning + spec:check-debt / spec:verify-acs --enforce pointer when the spec is claimed-complete but unverified. |
| Pick the next core spec and reserve it atomically | eos-spec next --core {core} --claim | Skips specs already claimed by other worktrees and takes a TTL lease on the chosen spec inside the same lock. Add --include-claimed to bypass the lease filter (read-only inspection). |
| Break work into tasks | generate-tasks --spec {CORE-##} | After review; reads *-CONTEXT.md if present |
| Finish the feature | spec-complete --spec {CORE-##} | Registry, logs, deferred checks — see command doc |
Tier 2 — Quality gates (use when workflow or risk demands)
| I want to… | Run | Notes |
|---|---|---|
| Deep implementability + overlap | spec-reviewer agent or spec-review | Required before tasks for regulated cores (CL, PM, HR, RH, GR, FA, IT, CE) |
| UX/spec UI checklist only | review-ux --spec {CORE-##} or spec-reviewer UX focus | Optional; see review-ux command |
| Heuristic overlap scan (tables/paths) | spec-landscape --spec {CORE-##} or npm run spec:landscape-scan -- --spec {CORE-##} | Read-only. spec-review preflight runs this together with precedent --spec {ID} --check-migrations and HALTS on any reported overlap or migration collision. |
| Lock UI/API choices before tasks | run the superpowers:brainstorming skill (--spec {CORE-##}) | Captures decisions into specs/{core}/specs/{CORE}-##-CONTEXT.md |
| Validate / create plan | validate-plan --spec {CORE-##} / create-plan --spec {CORE-##} | When plan exists or score ≥ 4 |
| Full canonical one-shot pipeline (resolve/create → validate → clarify → review → tasks) | spec-pipeline {CORE-##} or spec-pipeline --spec {CORE-##} (or --create --core {core} --name {slug}) | Bare IDs normalize, e.g. /spec-pipeline hr-42 → --spec HR-42; includes optional UX and implementation discussion steps |
| One-shot validate + plan (+ optional tasks) | prepare-spec --spec {CORE-##} | Does not replace clarify-spec or spec-reviewer |
| Verify a task | verify (superpowers:verification-before-completion) + run-tests | After implementation (--spec {CORE-##} T{N}) |
Tier 3 — Specialized (domain or artifact type)
| I want to… | Run | Notes |
|---|---|---|
| Wizard UX spec | create-wizard-spec / create-spec --type wizard | Under specs/{core}/ux/ |
| Full wizard pipeline (create → validate → review → tasks) | wizard-spec-pipeline --spec {CORE-UX-##} | End-to-end autonomous; see command doc |
| Validate wizard spec | validate-spec --file … --type wizard | Not validate-wizard-spec |
| Score specs for wizard candidacy | recommend-wizards | Prioritization |
| Audit wizard specs vs template | audit-wizard-specs | Quality band |
| Deferred enhancements | spec deferred --list / --sync / --promote | specs/DEFERRED_DASHBOARD.md |
| Promote deferred phase | create-expansion | Expansion markdown |
| CL/PM research bundle | research-ehr-pm-requirements, plan-ehr-pm-module | EHR/PM planning |
| Module strategy | deep-module-review --core {core} | Quarterly / pre-kickoff |
| Cross-module spec recommendations | recommend-module-specs --core {core} --cross-module all [--research] | Full module review + peer-core comparative scan + external research → new + enhanced spec recommendations |
| Integration gap report | research-module-integration-gaps --core {core} | Events/APIs vs code |
| Tests from spec | generate-test-suite | Scaffolds per command doc |
| UAT cases | generate-uat-test-cases | User-story based |
| Archive completed spec files | eos-spec archive | Moves spec/plan/tasks to specs/{core}/archive/; --status complete also matches Implemented |
| Record a stage sign-off marker | eos-spec signoff --spec {CORE-##} --type validated|spec-reviewed|ux-reviewed|heal-verified|docshots|ui-gate-waived|submit-e2e-waived|compliance | Stamps the load-bearing marker (e.g. <!-- validated: YYYY-MM-DD -->) in the spec body using your local date. Run reconcile --write afterward to materialize the derived pipeline_status. Use submit-e2e-waived only when a create-wizard genuinely has no submit path. |
| Scaffold a compliance sign-off file | eos-spec signoff --spec {CORE-##} --type compliance --reviewer <name> | Writes specs/{core}/reviews/{CORE-##}-COMPLIANCE-SIGNOFF.md with parseable YAML frontmatter (spec_id, reviewer, date, determinations[]). Idempotent — no-op if the file already exists. Edit the determinations[] block (one row per applicable regime: 42-cfr-part-2, hipaa-164, onc-170.315, fcra, tcpa, ahcccs, carf, samhsa, dhs-licensure, can-spam) with status: reviewed | not-applicable | deferred, then commit. The spec:compliance:check CI gate parses this file. |
Recompute pipeline_status from artifacts (report only) | eos-spec reconcile | Read-only; lists specs whose written status diverges from the artifact-derived stage. Add --core {core} or --spec {CORE-##} to scope. |
Materialize pipeline_status for one spec | eos-spec reconcile --spec {CORE-##} --write | Preferred for routine sign-offs on a shared tree — scopes the write to one ID instead of the whole corpus. |
Materialize pipeline_status for an entire core | eos-spec reconcile --core {core} --write | Use after batch artifact changes; review the divergence report before writing. |
Safety guard:eos-spec reconcile --writewith no scope (no--spec,--core, or--changed) is rejected withSCOPE_REQUIREDand writes nothing. This prevents accidental corpus-widepipeline_statusrewrites; dry-run (reconcilewithout--write) stays unscoped.
Tier 4 — Operational / inventory
| I want to… | Run | Notes |
|---|---|---|
| List specs | eos-spec list --core {core} | Optional --json |
| Reserve a spec across parallel worktrees | eos-spec claim {CORE-##} [--by {who}] [--ttl {min}] | Writes a TTL lease to the shared claim store so other agents skip the spec. Default claimant is $EOS_SPEC_CLAIMED_BY or the worktree basename; default TTL is 90 minutes. |
| Release a claim | eos-spec claim {CORE-##} --release | Frees the lease immediately. Stalled claims also expire when their TTL elapses. |
| Dispatch a core’s ready queue across parallel agents | /spec-fleet --core {core} [--k N] [--execute] | Reads eos-spec ready --core {core} --json, drops claimed and human-gated specs (regulated cores CL/PM/HR/RH/GR and any RLS/PHI-touching spec are surfaced, never auto-dispatched), claims each remaining spec, and emits per-spec packets through the existing multi-engine harness. Opens PRs, never auto-merges. |
| Include archived specs in CLI list/status | npm run spec -- list --core {core} --include-archived / npm run spec -- status --core {core} --include-archived | Adds 🗄️ rows from specs/{core}/archive/ |
| Read-only status | eos-spec status --spec {CORE-##} | No writes. Flags claimed-complete-but-unverified specs and points at spec:check-debt / spec:verify-acs --enforce. |
| Per-core completion scorecard | npm run spec:scorecard -- --core {core} (alias for eos-spec scorecard) | Per-spec stage, frontmatter accuracy, AC/US/FR validation, docshots. Add --json for clean JSON output. |
| Platform readiness rollup | npm run spec:rollup (alias for eos-spec readiness-rollup) | Ranked platform view across all cores. Headline metric is claimed-complete-but-unverified. |
| List specs ready for the next stage | npm run spec:ready -- --core {core} (alias for eos-spec ready) | Use with --json to feed /spec-fleet or your own dispatcher. |
| Backfill canonical issue line | backfill-core-canonical-issues --core {core} | Spec file metadata |
| Issue / project sync | deep-module-review --sync-issues | See command + SPEC_TRACKING_TRIAGE.md |
Deprecated / do not use
promote-deferred,sync-deferred-summary— legacy aliases removed; usespec deferredaudit-spec-completion— legacy alias removed; usespec-complete(see SPEC_COMPLETION_TRACKING.md)
Last Updated: 2026-06-13