Skip to main content
This page is synced from /AI_GUIDE.md at the repository root. Edit the source file — this published copy is regenerated by npm run docs:sync-canonical. See the governance index for related documents.

​
AI_GUIDE.md - AI Contribution Guide for Encore OS

Version: 2.12.0 Last Updated: 2026-05-13
Document hierarchy: constitution.md -> AI_GUIDE.md -> AGENTS.md -> .cursor/rules/* constitution.md is the source of truth for guardrails. This guide defines implementation workflow and decision support. AGENTS.md is the always-loaded quick reference.

​
Purpose

Use this file for process decisions that are not obvious from code:
  • Spec and planning decisions
  • Integration contract requirements
  • Implementation log workflow
  • Spec review and delivery checklists
Do not duplicate quick patterns that already live in AGENTS.md or constitutional rules that already live in constitution.md.

​
When To Read This File

Read this guide when you are:
  • creating/updating specs
  • validating implementation readiness
  • updating integration contracts
  • completing implementation logs
  • deciding whether to create plan docs
For routine coding tasks, rely on AGENTS.md plus scoped rule files under .cursor/rules/.

​
Decision Trees

Use these decision trees before writing implementation tasks or generating plan artifacts.

​
Workflow Entry Points

​
1) Should I create a spec?

Two spec locations? See docs/development/SPEC_PATHWAYS.md — product features go in specs/{core}/; tooling/process designs go in docs/superpowers/specs/.
Before creating a new spec:
  1. npm run spec -- precedent --core {core} --topic "{feature}"
  2. Check specs/{core}/archive/
  3. Check specs/SPEC_STATUS_REGISTRY.md
  4. Decide whether to enhance an existing spec instead of creating a new one

​
2) Should this become a setting, picklist, or feature flag?

Apply the full decision tree from .cursor/rules/tenant-configurability.md:
  1. Same for every tenant forever and not regulatory? → OK to hardcode (system constant).
  2. Different orgs need different values? (thresholds, intervals, defaults, limits) → {core}_module_settings per constitution §5.2.3.
  3. Value varies by state Medicaid program? (deadlines, timed-code thresholds, assessment counts) → PF-96 jurisdiction profiles, not org settings.
  4. User/admin-maintained list of options? (status reasons, categories, types, dropdown choices) → PF-15 picklists, not string literals or CHECK constraints.
  5. Boolean product experiment or slow rollout? → PF-45 feature flags.
  6. Org-specific schema extensions on entities? → custom_fields JSONB + PF-16 definitions.
When writing a spec, complete the Settings Considerations table in SPEC_TEMPLATE.md and the Enums and Source Types section — evaluate every new enum/status field against the picklist-vs-enum decision table in §5.2.4. Run audit-tenant-configurability --core {core} for existing code.

​
3) PLAN_TEMPLATE vs plan-in-spec

Use canonical matrices in specs/_templates/SPEC_GUIDE.md:
  • Full spec vs lite: #factor-score-full-spec-vs-lite
  • Separate plan doc: #decision-matrix-for-plan-document

​
4) Ask vs proceed

Ask when security/PHI handling, cross-core boundaries, breaking changes, or migration rollback paths are ambiguous.

​
Integration Documentation Requirements

All cross-core interactions require contract documentation.
  • Platform layers: docs/architecture/integrations/PLATFORM_INTEGRATION_LAYERS.md
  • Event contracts: docs/architecture/integrations/EVENT_CONTRACTS.md
  • API contracts: docs/architecture/integrations/API_CONTRACTS.md
  • Integration matrix: docs/architecture/integrations/CROSS_CORE_INTEGRATIONS.md

​
Spec Review Checklist

  • RLS enabled and UPDATE policies include both USING and WITH CHECK
  • SECURITY DEFINER helpers used where required
  • No recursive RLS policy patterns
  • PHI/PII handling and access controls documented
  • Dependencies, contracts, and fallback paths documented
  • Tenant configurability reviewed: Settings Considerations table completed; hard-coded values justified; enums evaluated for PF-15 picklist eligibility; jurisdiction-scoped values routed to PF-96 (constitution §5.2.3–§5.2.4)

​
Implementation Log Protocol

After shipping meaningful work, update specs/{core}/IMPLEMENTATION_LOG.md with status, completion date, changed surfaces, test evidence, and deferred work.

​
Scope Notes

  • Canonical “What AI Must NEVER Do” list lives in AGENTS.md.
  • Quick pattern rules live in AGENTS.md and .cursor/rules/quick-reference.mdc.
  • Constitutional policy and regulatory guardrails remain in constitution.md.