> ## 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.
# Canonical Spec Workflow
> Version: 1.1.0 Last Updated: 2026-05-09
**Version:** 1.1.0
**Last Updated:** 2026-05-09
Canonical specification workflow: command order, decision points, and links to related commands.
**Command cheat sheet (tiers):** [SPEC\_COMMAND\_CHEATSHEET.md](SPEC_COMMAND_CHEATSHEET.md)
***
## Workflow Diagram
```mermaid theme={null}
flowchart LR
Z[/deep-module-review\] -.->|quarterly/pre-kickoff| A
Z2[/recommend-module-specs\] -.->|cross-module + optional research| A
SP[spec-pipeline] -.->|one-shot canonical flow| A
WP[wizard-spec-pipeline] -.->|one-shot wizard UX flow| W1
A[create-spec] --> B[clarify-spec]
B --> C[validate-spec]
C --> D[spec-reviewer]
D -.->|regulated cores| D2[compliance-reviewer]
D2 --> E2
D --> E2{plan needed?}
W1[create-wizard-spec] --> W2[validate-spec --type wizard]
W2 --> W3[clarify-spec]
W3 --> W4[spec-reviewer + review-ux]
W4 --> C
E2 -->|yes| F[create-plan]
F --> G[validate-plan]
G --> OPT[ready for tasks]
E2 -->|no| OPT
OPT -.->|optional| DI[discuss-implementation]
DI --> H[generate-tasks]
OPT --> H
H -.->|spec-pipeline STOPS here| STOP[ ]
H --> I[implement]
I --> I2[docs]
I2 --> J[verify-task]
J --> K[spec-complete]
I -.-> J
J -.-> K
```
**Linear sequence:**
```text theme={null}
create-spec → clarify-spec → validate-spec (--auto-fix --auto-plan) → spec-reviewer → [compliance-reviewer (regulated cores)] → [validate-plan] (when plan exists; create-plan only if plan needed but not created) → [discuss-implementation] → generate-tasks ║ [implement] → [documentation] → verify-task → spec-complete
```
> The `║` boundary marks where `spec-pipeline` stops. Implementation (`implement-spec`) 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 **`whats-next --spec {CORE-##}`** to get the single next action at any time (no need to memorize the sequence). See [whats-next](../../.cursor/commands/specs/whats-next.md).
**Before `create-spec`:** run `npm run spec -- precedent --core {core} --topic "{feature-name}"` so archived/superseded specs in `specs/{core}/archive/` and `specs/SPEC_STATUS_REGISTRY.md` are considered in scope decisions.
**Deferred features:** Use **`spec deferred --list`**, **`spec deferred --promote`**, **`spec deferred --sync`** for listing, promoting, and regenerating the deferred dashboard. See [spec-deferred](../../.cursor/commands/specs/spec-deferred.md). 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, discuss-implementation, **review-ux** (optional UI pass), **spec-review** (in-chat spec review), whats-next, spec-status, **implement-spec** (structured implementation), spec-complete, spec deferred (--list | --promote | --sync), verify-task, pre-commit-check, session-status, pause-work, resume-work. Wizard UX one-shot: **wizard-spec-pipeline**. See [SPEC\_COMMAND\_CHEATSHEET.md](SPEC_COMMAND_CHEATSHEET.md) for the full tiered list.
**Command tiers:** [SPEC\_COMMAND\_CHEATSHEET.md](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](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](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`](../../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); `--auto-fix` applies ID/section/link fixes and can insert a landscape stub; `--auto-plan` creates a plan when score ≥4. Default: use both flags. Run before spec-reviewer. |
| **spec-reviewer** | **AI chat agent** (Cursor).
• **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:** Agent must search same-core specs and integration docs per `.cursor/agents/spec-reviewer.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](AUTO_APPLY_SAFETY.md) for PHI/PII, multi-tenancy, and compliance areas to spot-check.
• **Invocation:** Run via Cursor's agent picker or use the spec-review command; provide spec path or `{CORE-##}` in chat.
• **If Task/spec-reviewer invocation fails:** Use the [spec-review](../../.cursor/commands/specs/spec-review.md) command in chat (same behavior: auto-apply by default) or check `.cursor/agents/spec-reviewer.md` for setup details. |
| **create-plan** | Use when a plan is needed but was not created by `validate-spec --auto-plan` (e.g. force-create when `score <4`, or re-create after spec changes). If score ≥4, validate-spec --auto-plan usually creates the plan in one pass. |
| **validate-plan** | Validate plan structure, "Based On" link, and required sections. Run after creating or editing a plan (or after validate-spec --auto-plan when a plan was created). |
| **discuss-implementation** | 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](../../.cursor/commands/specs/review-ux.md). Use when UI is heavy or `discuss-implementation` 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. |
| **whats-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}`. |
***
## 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](../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/](../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 --auto-fix --auto-plan` | Validate structure and constitution; apply fixes; create plan when score ≥4 |
| 4 | **spec-reviewer** (AI agent: run in Cursor chat; 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 --auto-fix → generate-tasks`
* **Optional:** Run `clarify-spec` if the spec has placeholders; run **spec-reviewer** 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 --auto-fix --auto-plan → spec-reviewer → 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-##}` | Plan is usually created by step 3 (`validate-spec --auto-plan`). Validate it. If no plan exists but score ≥4, run create-plan then validate-plan. |
| 5b | `discuss-implementation --spec {CORE-##}` (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. Default: run `validate-spec --auto-fix --auto-plan` in Phase 1 so the plan is created in one pass when needed; then run `validate-plan`. Use `create-plan` only as fallback (force-create, re-create, or when --auto-plan was not used). 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 `implement-spec` or manual implementation.
| Step | Command | Purpose |
| ---- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 7 | `implement-spec --spec {CORE-##}` (or implement per TASKS file manually) | Structured implementation: preflight, workstream proposal, gated execution. See [implement-spec](../../.cursor/commands/specs/implement-spec.md). |
| 8 | **Documentation** | Create user/admin guides per spec's [Documentation Deliverables](../../specs/_templates/SPEC_TEMPLATE.md) 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 | `verify-task --spec {CORE-##} T{N}` | Verify each task completion |
| 10 | `pre-commit-check` | Before committing |
**Decision:** Run `verify-task` 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](../../.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](../../.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. |
| 12 | **Test coverage** | Before spec-complete: ensure [spec–test matrix](../testing/SPEC_TEST_COVERAGE.md) 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. |
| 14 | `spec-complete --spec {CORE-##}` | Validate, update log, optional audit |
| (optional) | `spec-complete --spec {CORE-##} --completion-report --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 `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-reviewer agent (AI chat agent; run in Cursor; 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). |
| Create implementation plan (when score ≥4 and not using --auto-plan) | `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`, `--plan-auto-fix`) |
| 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 | `whats-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 | `discuss-implementation --spec {CORE-##}` |
| 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) | `spec-status` |
| Update status / complete feature / audit | `spec-complete` |
| Verify a single task | `verify-task` |
| 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](../../.cursor/commands/specs/deep-module-review.md). |
| 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](../../.cursor/commands/specs/recommend-module-specs.md). |
### Overlap and duplication
Use the right tool for the kind of overlap:
| Need | Use |
| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Structure, constitution, warnings for `## Spec landscape & boundary` | `validate-spec --auto-fix` |
| 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-reviewer** agent or **`spec-review`** command (after `validate-spec`) |
| 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 | **review-module-issue-sync** |
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:
1. `spec-complete --all --completion-report --update-registry`
2. `npm run spec:reconcile-tracking`
3. `npm run bootstrap:spec-issues -- --sync --active-only`
4. `npm run spec:close-stale-tracking`
5. `npm run spec:add-tracking-to-project -- --state open`
6. `npm run spec:sync-project-status`
7. `npm run spec-tracking:verify -- --scope active`
***
## Related Commands
| 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](../../.cursor/commands/specs/spec-landscape.md); optional: `npm run spec:landscape-scan -- --spec {CORE-##}` |
| spec-reviewer | agents | AI chat agent: deep implementability review (run in Cursor; 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-implementation, generate-tasks. Does NOT implement. |
| `prepare-spec` | specs | Optional one-shot: validate-spec --auto-fix --auto-plan, then validate-plan (and optionally generate-tasks) |
| `wizard-spec-pipeline` | specs | Full wizard UX one-shot pipeline: create/resolve, wizard validation, clarify, spec-reviewer, review-ux, re-validate/plan, discuss-implementation, 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.** |
| `discuss-implementation` | specs | Pre-implementation gray area discussion; creates CONTEXT.md |
| `implement-spec` | specs | Structured implementation orchestrator: 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 |
| `spec-status` | specs | Read-only status (quick or detailed) |
| `whats-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 |
| `verify-task` | development | 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](../../.cursor/commands/specs/deep-module-review.md) |
| `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](../../.cursor/commands/specs/recommend-module-specs.md) |
***
## Related Documentation
* **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`](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_DIRECTORY_STRUCTURE.md` – complete path conventions and directory layout
* **Checklists:** `specs/_templates/SPEC_CHECKLISTS.md` – pre-flight, compliance, RLS
* **Auto-apply (optional guidance):** [AUTO\_APPLY\_SAFETY.md](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
* **AI\_GUIDE.md** – Spec-first delivery, implementation log
* **Wizard workflow:** [`docs/development/WIZARD_DEVELOPMENT_GUIDE.md`](WIZARD_DEVELOPMENT_GUIDE.md), [`docs/development/WIZARD_UX_STANDARD.md`](WIZARD_UX_STANDARD.md)
* **Session state:** [.cursor/rules/session-state-patterns.md](../../.cursor/rules/session-state-patterns.md) – pause/resume and session state patterns
* **Git commit patterns:** [.cursor/rules/git-commit-patterns.md](../../.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-reviewer | 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](../../.cursor/commands/specs/deep-module-review.md) (single-module) and [recommend-module-specs](../../.cursor/commands/specs/recommend-module-specs.md) (cross-module + optional external research via --research → new + enhanced spec recommendations). |
**Commands:** validate-spec (--auto-fix --auto-plan) before spec-reviewer; validate-plan when a plan exists; verify-task 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:**
```bash theme={null}
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 --auto-fix --auto-plan
# 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-implementation --spec HR-XX # capture UI/behavior preferences before tasks
generate-tasks --spec HR-XX
# ── spec-pipeline stops here ── implementation is a separate step ──
implement-spec --spec HR-XX # structured implementation (preflight → workstreams → execute)
verify-task --spec HR-XX T1 --complete
# 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 `whats-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):**
```bash theme={null}
spec-status --spec HR-XX
spec-status --spec HR-XX --detailed
spec-status --core hr --json
```