> ## 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.

# AI Contribution Guide

> Workflow and decision support for AI-assisted contributions — spec process, implementation log protocol, decision framework.

> **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](/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](/development/SPEC_PATHWAYS) — 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`.