Enable and operate the Context Awareness feature (docs/context contracts + environment registry) so LLMs can work from a verified context layer instead of ad-hoc repo scans.
Provide a stable, verifiable, LLM-readable context layer under docs/context/.
The context-awareness feature standardizes how the project exposes:
The main outcome is that the LLM can load a small number of canonical entry points and avoid fragile whole-repo discovery.
When enabled, the feature materializes these paths in the repo root:
docs/context/** (contracts + registry)docs/context/AGENTS.md (LLM routing entrypoint with progressive loading protocol)docs/context/knowledge/glossary.json (domain glossary — structured term definitions)docs/context/knowledge/glossary.schema.json (glossary JSON Schema for verification)docs/context/knowledge/architecture-principles.md (cross-cutting constraints and rejected alternatives)config/environments/** (environment config templates; no secrets)And it assumes these controller scripts exist (they are part of the template SSOT under .ai/):
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs — context artifacts + registry + environments + glossarynode .ai/scripts/ctl-project-state.mjs — project state (.ai/project/state.json)node .ai/scripts/ctl-openapi-quality.mjs — OpenAPI semantic quality gatenode .ai/skills/_meta/ctl-skillpacks.mjs — skill pack switching + wrapper syncdocs/context/AGENTS.md (authoritative LLM routing — progressive loading protocol)docs/context/INDEX.mddocs/context/registry.jsondocs/context/api/api-index.json (API overview — read before per-module openapi.yaml)docs/context/knowledge/glossary.json (domain term definitions)docs/context/config/environment-registry.jsonIf a DB schema exists, the canonical DB contract is:
docs/context/db/schema.jsonThat DB contract is produced by the DB SSOT workflow (see ctl-db-ssot, and the database workflow skills).
.ai/skills/features/context-awareness/templates/
into the repo root.node .ai/scripts/ctl-project-state.mjs init
node .ai/scripts/ctl-project-state.mjs set context.enabled true
node .ai/scripts/ctl-project-state.mjs set-context-mode contract
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs init
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs touch
docs/context/knowledge/glossary.json)Structured JSON for project-specific term definitions. Manage via CLI:
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs add-term --term "tenant" --definition "An isolated customer organization" --scope global --aliases "organization,org"
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs remove-term --term "tenant"
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs list-terms
Verification: ctl-context verify --strict validates glossary structure when the file exists.
docs/context/knowledge/architecture-principles.md)Markdown file for cross-cutting rules and rejected alternatives. Edit directly, then run ctl-context touch.
Validates per-module and project-level OpenAPI files for semantic completeness:
node .ai/scripts/ctl-openapi-quality.mjs verify --source modules/<id>/interact/openapi.yaml --strict
node .ai/scripts/ctl-openapi-quality.mjs verify --discover-modules --strict
Checks: required fields (operationId/summary/tags/2xx), unique operationId, security scheme refs, path param declarations, $ref resolution. Optional enhancement: install @apidevtools/swagger-parser for full OpenAPI spec compliance.
Use ctl-project-state to maintain .ai/project/state.json:
node .ai/scripts/ctl-project-state.mjs init
node .ai/scripts/ctl-project-state.mjs set custom.stage <prototype|mvp|production|maintenance|archived>
node .ai/scripts/ctl-project-state.mjs set-context-mode <contract|snapshot>
node .ai/scripts/ctl-project-state.mjs verify
After editing any file under docs/context/**:
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs touch
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs list-envs
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs add-env --id qa --description "QA environment"
node .ai/skills/features/context-awareness/scripts/ctl-context.mjs verify-config
For module-level context slices, follow the standard workflow below:
docs/context/db/schema.jsonenv/contract.yamldocs/context/observability/*.json# modules/<module_id>/MANIFEST.yaml