Skip to main content

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.

Purpose: Verify that governance docs (AGENTS.md, constitution, AI_GUIDE), Cursor agents, process commands, specs, and templates are present, consistent, and accurate. Use this runbook after governance or .cursor/spec changes, and before releases. Version source of truth: docs/VERSIONS.md. All audit scripts that check document versions read from this file. Do not hardcode versions in scripts.

​
Governance & Lovable Upkeep (Quick Reference)

WhenDo this
After editing constitution or AGENTSUpdate docs/VERSIONS.md, run npm run validate:governance, then re-paste docs/tools/lovable/LOVABLE_CUSTOM_KNOWLEDGE.md into Lovable Project Settings → Custom Knowledge.
After adding/removing an agent or commandUpdate .cursor/README.md, run npm run validate-agents-content and npm run validate-commands.
After changing a spec templateRun npm run validate-specs-templates; update TEMPLATE_INDEX.md if you added/renamed/deprecated a template; if the template references constitution, use (current: see docs/VERSIONS.md) or ensure the version matches VERSIONS.md.
Periodic (e.g. pre-release)Full runbook sequence below (automated commands + manual checklists).

​
When governance docs change

When you update constitution.md, AGENTS.md, or docs/tools/lovable/LOVABLE_CUSTOM_KNOWLEDGE.md:
  1. Update LOVABLE_CUSTOM_KNOWLEDGE.md if the change affects platform guardrails (e.g. new architecture rule, new “must never”).
  2. Update version/last-updated in that file and in docs/VERSIONS.md for the Core Documentation row.
  3. Re-paste docs/tools/lovable/LOVABLE_CUSTOM_KNOWLEDGE.md into Lovable: Project Settings → Custom Knowledge. This keeps Lovable sessions aligned with the latest rules.
After running npm run validate:governance successfully following a change to constitution or AGENTS, if constitution or AGENTS changed, re-paste docs/tools/lovable/LOVABLE_CUSTOM_KNOWLEDGE.md into Lovable Custom Knowledge.

​
1. Automated Commands (Run in Order)

Run these from the repository root. Fix any failures before proceeding to manual checks.
StepCommandPurpose
0npm run validate-version-syncEnsure docs/VERSIONS.md exists and Core Documentation table has all governance docs (run first; included in validate:governance)
1npm run validateFull pipeline: format check, typecheck, lint, build
2npm run validate-agentsAGENTS.md structural validation, version refs, size
3npm run audit-ai-docs -- --governance-onlyGovernance doc cross-reference sync (AGENTS, AI_GUIDE, constitution)
4npm run docs:validateDoc link validation and version checks against VERSIONS.md
5npm run test:audit:completenessSpec/test matrix coverage, RLS rollup, env consistency (generates report)
6npm run test:audit:enforceEnforce audit gates (run after test:audit:completeness)
7npm run validate-agents-contentAGENTS.md link validity, quick-reference locations, nested AGENTS, Cursor agents inventory/links, Context-to-load path validation
8npm run validate-constitutionConstitution sections 1–7, version vs VERSIONS.md, hierarchy statements, section refs
9npm run validate-commandsCommand/agent counts vs .cursor/README, npm script refs, script paths
10npm run validate-specs-templatesSpec required sections (incl. Objectives), constitution ref, spec-vs-README inventory, implementation log consistency, plan linkage, template inventory vs TEMPLATE_INDEX, deprecated templates, SPEC_TEMPLATE.md internal links
The script in step 10 also checks: spec inventory vs each core README, implementation log consistency (Complete entries vs spec files; optional warning for specs with no log entry), plan linkage for specs that suggest multi-phase or cross-core work, and that all internal links in SPEC_TEMPLATE.md resolve. Steps 9 and 7 cover command/agent counts vs .cursor/README and Context-to-load path validation respectively. One-shot governance run:
  • npm run validate:governance — Runs validate-version-sync, validate-agents, audit-ai-docs —governance-only, validate-agents-content, validate-constitution, validate-commands, and validate-specs-templates in sequence.
CI: The .github/workflows/build.yml workflow runs npm run validate:governance after install (format check, typecheck, lint, tests, build). Governance scripts report warnings by default; use --strict in scripts to fail on errors. Pre-commit: The .husky/pre-commit hook runs lint-staged, typecheck, validate-staged-docs, RLS migration lint, and (when AGENTS.md is staged) validate-agents. Use a test commit to confirm all steps run as expected.

​
2. Manual Verification Checklists

Use these after automated checks pass. Run the listed commands and spot-check as indicated.

​
2.1 AGENTS.md (Root + Nested)

  • Run: npm run validate-agents — all pass, no version drift, no size violations (or document accepted exceptions).
  • Run: npm run audit-ai-docs -- --governance-only — governance docs synced.
  • Inventory: Compare actual AGENTS.md files on disk to the list in scripts/audit/validate-agents.ts and root AGENTS.md “Module-Specific Instructions.” Confirm no files are missing (e.g. cl, pm, ce).
  • Root content: Open root AGENTS.md. Spot-check 5 “Document Map” links — do they resolve? Spot-check 3 entries in the “Top 10 Common Mistakes” table — are the quick fixes still accurate?
  • Quick-reference table: Open .cursor/rules/quick-reference.mdc. Spot-check 5 “Location” links — do they resolve to the correct pattern file and anchor?
  • Nested AGENTS.md: Pick 2–3 nested files (e.g. HR, FA, CL). Confirm:
    • References root AGENTS.md version or “see docs/VERSIONS.md”.
    • Spec list (e.g. “HR-01 through HR-07”) matches files in specs/{core}/specs/.
    • Implementation status claims match the implementation log.
    • “What AI Must NEVER Do” section is present and module-specific.

​
2.2 Constitution

  • Version: constitution.md version header matches docs/VERSIONS.md.
  • Section structure: Sections 1–7 exist and are in order. Referenced subsections (e.g. §5.2.4, §5.7, §7.2, §7.3) exist as headings or anchors.
  • Cross-references: Search specs for “constitution §” — spot-check 5 references. Verify each points to a real section with matching content.
  • Hierarchy statement: AGENTS.md, AI_GUIDE.md, CLAUDE.md each state “constitution wins” or equivalent.
  • Audit script versions: Versions used by audit scripts come from VERSIONS.md (via scripts/audit/utils/read-versions.ts). No hardcoded CURRENT_VERSIONS in validate-agents or audit-ai-docs.

​
2.3 Cursor Agents

  • Inventory: List .cursor/agents/*.md. Verify count matches the Agents table in .cursor/README.md (canonical count; exclude agents/README.md and any non-agent stubs).
  • Frontmatter: Spot-check 3 agents — each has name and description in YAML frontmatter.
  • Governance: Pick 3 agents (e.g. verifier, spec-reviewer, code-reviewer). Confirm they reference AGENTS.md and/or constitution.md in “Context to load” section.
  • Links: In those 3 agents, check that relative links (e.g. ../../AGENTS.md, ../rules/quick-reference.mdc) resolve to existing files.
Agent & command upkeep: When adding an agent, create .cursor/agents/<name>.md with required frontmatter (name, description), add it to the README inventory, and run npm run validate-agents-content so “Context to load” and links are validated. When retiring an agent, remove the file, update README and any commands that reference it, then run validate-agents-content and validate-commands.

​
2.4 Process Commands

  • Run: npm run validate — format:check, typecheck, lint, build all pass.
  • Pre-commit: Trigger pre-commit on a test commit; confirm lint-staged, typecheck, validate-staged-docs, and (if applicable) validate-agents run.
  • Command count: Count .cursor/commands/**/*.md files. Compare to .cursor/README.md claim (e.g. “48 commands”).
  • npm script spot-check: Pick 5 commands (e.g. create-spec, validate-spec, spec-complete, pre-commit-check, audit-ai-docs). Confirm each referenced npm run X exists in package.json.
  • Run sample commands: Execute npm run docs:validate, npm run check-architecture, and npm run test:audit:completeness. Confirm they run without errors and produce expected output.

​
2.5 Specs

  • Spec inventory: For each core (HR, FA, RH, GR, FW, FM, LO, IT, PF, CL, PM, CE), confirm the core README lists all spec files in specs/{core}/specs/.
  • Constitution reference: Spot-check 5 specs across cores. Confirm the > **Constitution Reference:** ... line exists and references the current version (see VERSIONS.md).
  • Required sections: In those 5 specs, confirm presence of: Business Context, Scope, User Stories, Data Model, Integration Points, Testing Strategy.
  • Completion tracking: For 2–3 completed specs, verify status in the implementation log matches the spec header status.
  • Run validate-spec: Use the Cursor command validate-spec --core hr (or --all) on at least one core. Review output for unexpected failures.

​
2.6 Templates

  • Template count: Count files in specs/_templates/ (and subdirs as appropriate). Verify against TEMPLATE_INDEX claim (e.g. 30 templates).
  • TEMPLATE_INDEX accuracy: Open specs/_templates/TEMPLATE_INDEX.md. Compare each listed template to actual files. No phantom entries (listed but missing file) and no unlisted files.
  • Deprecated cleanup: TEMPLATE_INDEX lists deprecated templates. Confirm those old files do not exist on disk.
  • Constitution version in template: In specs/_templates/SPEC_TEMPLATE.md, check the constitution reference matches current docs/VERSIONS.md or uses (current: see docs/VERSIONS.md).
  • Internal links: In SPEC_TEMPLATE.md, spot-check 3 links (e.g. to SPEC_CHECKLISTS.md, db-preflight.md, SPEC_GUIDE.md). Confirm they resolve.
After changing any spec template (e.g. SPEC_TEMPLATE, TASKS_TEMPLATE): run npm run validate-specs-templates and update TEMPLATE_INDEX.md if you added, renamed, or deprecated a template.
  • After changing constitution, AGENTS.md, AI_GUIDE.md, or AGENTS.md: Run automated commands 1–4 and manual checklists 2.1 and 2.2. Re-paste docs/tools/lovable/LOVABLE_CUSTOM_KNOWLEDGE.md into Lovable Custom Knowledge so Lovable sessions stay aligned.
  • After adding or changing .cursor/agents or .cursor/commands: Run automated commands 1–4 and manual checklists 2.3 and 2.4.
  • After adding or changing specs or specs/_templates: Run automated commands 1–5 (and 6 if enforcing gates) and manual checklists 2.5 and 2.6.
  • Before a release or major merge: Run all automated commands and complete all manual checklists.
  • Accuracy testing plan — Full plan and implementation phases (see .cursor/plans/ or plan file agent_constitution_process_accuracy_testing_95a8e4e7.plan.md if present in repo).
  • docs/VERSIONS.md — Single source of truth for document versions.
  • AGENTS.md — Root AI quick reference.
  • constitution.md — Engineering guardrails.
  • .cursor/README.md — Cursor commands and agents index.