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.
Date: 2026-05-09
Scope: .cursor/rules/, .cursor/skills/, .cursor/commands/, .claude/, .agents/, AGENTS.md, AI_GUIDE.md, constitution.md, .github/instructions/, package.json scripts
Executive Summary
The Encore Health OS agent infrastructure is mature and well-structured. Document hierarchy is clear, core AGENTS.md files are complete (14/14), and rule activation patterns are sound. This audit identifies 26 actionable improvements across 6 categories to increase efficiency, reduce context waste, and improve accuracy for AI agents.
Inventory Snapshot
| Area | Count | Status |
|---|
.cursor/rules/ files | 45 | Active (README says 35 — stale) |
.cursor/skills/ | 23 | All have SKILL.md |
.cursor/commands/ | 78 | Well-organized by domain |
.claude/agents/ | 6 | Code-reviewer, compliance, docs, structure, writer, test-gen |
.claude/commands/ | 5 | commit, fix-issue, pr-summary, security-audit, recommender |
.claude/skills/ | 5 | spec-review, doc-update, code-review, api-integration, file-organizer |
.agents/skills/ | 4 | cloud-runbook, autofix, code-review, turborepo |
src/**/AGENTS.md | 14 | All cores + platform + shared + integrations |
.github/instructions/ | 10 | Copilot-scoped instructions |
package.json scripts | 218 | Categorized; CLAUDE.md says 206 (stale) |
These are factual inconsistencies that can mislead agents into wrong behavior or stale assumptions.
| # | Issue | Location | Fix |
|---|
| 1 | constitution.md header says v1.17.0 but footer block says v1.16.1 | constitution.md footer (~line 2190) | Update footer to 1.17.0 |
| 2 | docs/VERSIONS.md lists copilot-instructions.md as v1.23.0; actual file is v1.23.1 | docs/VERSIONS.md | Sync to 1.23.1 |
| 3 | .cursor/README.md says 35 rule files; actual count is 45 | .cursor/README.md | Update to 45 |
| 4 | CLAUDE.md says 206 scripts; actual count is 218 | CLAUDE.md | Update to 218 |
| 5 | constitution.md TOC omits §12.3–12.5 (Testing, Audit, Rate Limiting) | constitution.md TOC | Add subsections to TOC |
| 6 | AI_GUIDE.md See Also has broken note: “AGENTS.md consolidated into AGENTS.md” | AI_GUIDE.md footer | Fix copy-paste error |
Category 2: Context Efficiency (Medium-High Priority)
These changes reduce token waste for AI agents while preserving information.
| # | Recommendation | Rationale |
|---|
| 7 | Delete the 4 split-stub files (performance-patterns.md, security-patterns.md, form-libraries.md, and any other pure-redirect files) and update cross-references to point directly to the targets. | Each stub wastes ~200 tokens of context when accidentally loaded. A glob match can still pull them in. Alternatively, if keeping stubs for discoverability, make them 2-line files (no YAML frontmatter globs: that could trigger loading). |
| 8 | Consolidate query-patterns.md and perf-query-caching.md into a single file. | Both cover React Query caching with overlapping content. Having two glob-matched files for src/**/*.{ts,tsx} means agents may load both (~450 lines) for the same task. |
| 9 | Add a max_lines: N or size_budget metadata field to each core AGENTS.md header as a soft governance signal. | Several core AGENTS.md files exceed their own stated size goals (e.g., platform at 800+ lines vs “keep small”). A metadata field makes drift visible during governance audits. |
| 10 | Create a lightweight .cursor/rules/index.md (decision-tree replacement or supplement) that maps “I’m editing file X” → “load rules Y, Z”. | pattern-decision-tree.md exists but is 150 lines of prose. A flat table (file-glob → rule-files) would be more scannable for agents and enable tooling to auto-inject only relevant rules. |
Category 3: Missing Skills & Commands (Medium Priority)
Gaps where a new skill or command would materially improve agent performance.
| # | Proposed Addition | Justification |
|---|
| 11 | Skill: migration-authoring (.cursor/skills/migration-authoring/SKILL.md) | Currently agents must read database-patterns.mdc + database-migrations.md + constitution.md §5 + the DB dev guide. A single skill that sequences these reads and provides a preflight checklist would reduce missed steps and token churn. |
| 12 | Skill: rls-testing (.cursor/skills/rls-testing/SKILL.md) | RLS tests have specific setup (service-role keys, test isolation, SKIP_SUPABASE_TESTS). The info is scattered across .github/instructions/rls-tests.instructions.md, testing.md rule, and the test setup doc. A unified skill chains them. |
| 13 | Command: validate-quick (.cursor/commands/development/validate-quick.md) | Many tasks only need typecheck + lint + build (not full governance). A command that runs the minimal CI gate (npm run validate) and reports pass/fail would be faster than agents guessing which checks to run. |
| 14 | Skill: ui-component-creation | Agents creating new components must synthesize dialog-size-standards, tab-patterns, semantic colors, mobile/gesture patterns, and breadcrumb rules. A single skill that triggers on “creating a new page/component” would orchestrate the reads. |
| 15 | Command: sync-versions (.cursor/commands/documentation/sync-versions.md) | Automates the version drift fixes from Category 1. Reads all doc headers, compares to VERSIONS.md, and proposes corrections. Could be run monthly per governance cadence. |
Category 4: Rule Activation & Glob Refinement (Medium Priority)
| # | Recommendation | Rationale |
|---|
| 16 | Narrow database-patterns.mdc glob from src/**/*.{ts,tsx} to src/**/hooks/use*Query*.{ts,tsx}, src/**/hooks/use*Mutation*.{ts,tsx}, src/**/api/** or similar. | A 431-line rule currently loads for ANY .ts/.tsx edit. Most of its content (RLS, SECURITY DEFINER, naming) is irrelevant when editing a UI component. |
| 17 | Add alwaysApply: false explicitly to all rules that lack it (currently only constitution.mdc and quick-reference.mdc have alwaysApply fields). | Explicit is better than implicit for governance audits and tooling. |
| 18 | Remove or refine the glob on ai-slop-avoidance.mdc (**/*.{ts,tsx,js,jsx}). | This 30-line rule is lightweight but loads for every TS/JS edit. Consider making it always-apply (it’s short) or removing the glob and relying on the check:slop command for enforcement. |
| 19 | Create a .cursor/rules/mobile-patterns.md scoped to src/cores/*/components/mobile/** and src/platform/gestures/**. | Mobile/gesture guidance is currently embedded in AGENTS.md point #15 (a paragraph) and a separate dev guide. A scoped rule file would auto-inject when agents edit mobile components. |
| # | Issue | Fix |
|---|
| 20 | .claude/skills/code-review/ and .agents/skills/code-review/ overlap but serve different purposes (local Claude review vs CodeRabbit PR integration). | Rename .agents/skills/code-review/ to .agents/skills/coderabbit-review/ to eliminate ambiguity. Update SKILL.md trigger descriptions. |
| 21 | .cursor/mcp.json only defines shadcn; AGENTS.md references “baseline: shadcn, fallow” for MCP. | Either add a fallow MCP config (if it supports MCP protocol) or correct AGENTS.md to say “baseline MCP: shadcn; fallow via npm scripts.” |
| 22 | .github/instructions/ has no mention in .cursor/README.md or AGENTS.md Document Map. | Add a row to the AGENTS.md Document Map table for .github/instructions/ files and their purpose (Copilot-scoped instruction injection). |
| 23 | No .agents/README.md exists to explain the .agents/ directory purpose vs .claude/ vs .cursor/. | Add a short README explaining: .agents/ = cross-tool skills (Cloud agents, CI); .claude/ = Claude Code; .cursor/ = Cursor IDE. |
Category 6: Operational & Governance Improvements (Low Priority)
| # | Recommendation | Rationale |
|---|
| 24 | Add a docs/VERSIONS.md “Debugging & Troubleshooting” section or remove the empty heading. | Empty headings waste tokens and signal incomplete work to agents. |
| 25 | Add governance audit for skill versions to the monthly cadence in RULES_GOVERNANCE.md. | Skills have version fields (v1.0.0) but no process to review/bump them. As skills evolve, stale version numbers reduce trust. |
| 26 | Create a script npm run audit:agent-config that validates: rule count matches README, VERSIONS.md matches file headers, no empty doc sections, skill frontmatter is complete. | Automates Category 1 fixes and prevents future drift. Could be added to validate:governance. |
Priority Matrix
HIGH IMPACT
│
┌───────────────────┼───────────────────┐
│ Cat 1 (#1-6) │ Cat 2 (#7-10) │
│ Version drift │ Context savings │
│ │ │
LOW ├───────────────────┼───────────────────┤ HIGH
EFF │ Cat 5 (#20-23) │ Cat 3 (#11-15) │ EFFORT
ORT │ Consistency │ New skills │
│ │ │
│ Cat 6 (#24-26) │ Cat 4 (#16-19) │
│ Governance │ Glob tuning │
└───────────────────┼───────────────────┘
│
LOW IMPACT
- Category 1 (version fixes) — immediate, low effort, high trust impact
- Category 2 items 7-8 (stub deletion, query consolidation) — quick wins
- Category 3 item 11 (migration skill) — highest-value new skill
- Category 4 item 16 (database-patterns glob) — largest context savings
- Remaining items by priority band
Appendix: Unused/Redundant Configuration
| Item | Status | Recommendation |
|---|
form-libraries.md | Pure redirect stub | Delete or reduce to 2 lines without glob |
performance-patterns.md | Pure redirect stub | Delete or reduce to 2 lines without glob |
security-patterns.md | Pure redirect stub | Delete or reduce to 2 lines without glob |
file-organizer skill (.claude/skills/) | Generic, not Encore-specific | Consider removing — adds noise to skill list |
turborepo skill (.agents/skills/) | 950+ lines; project is not a monorepo yet | Keep but mark as “future/aspirational” in its description |
constitution.md “Annual Review” heading | Duplicate of §10.3 | Merge into §10.3 or remove standalone heading |
Next Steps
- Immediate: Fix the 6 version drift items (Category 1) — these can be done in a single commit.
- This sprint: Delete stubs, consolidate query patterns, narrow database-patterns glob.
- Next sprint: Author the
migration-authoring and rls-testing skills.
- Monthly governance: Add
audit:agent-config script to validate:governance chain.
Generated by agent audit on 2026-05-09. All 26 recommendations implemented in this PR.
