AOCI Cognition — governed repository knowledge for AI agent

Onboarding a new developer to a complex codebase usually takes days of manual exploration. This skill implements the AOCI-CODE collaboration protocol, enabling an agent to maintain a persistent, Git-versioned cognition map of both source code and database schemas. It replaces guesswork with a governed system of responsibilities, contracts, and constraints.

What it does

• Governed Cognition maintains a version-controlled map of code responsibilities (FRAS) and system boundaries.
• Database Mapping integrates table-level cognition using read-only environment variable DSNs for schema analysis.
• Semantic Tracking triggers maintenance only when machine-computed semantic change thresholds are crossed.
• Protocol Adherence enforces a strict session lifecycle including overview loading, attestation, and task-end maintenance.
• Evidence Reporting generates headers and reports to prove alignment between the cognition map and the actual source.

How it works

1. Initialize the session by calling aoci_rules to confirm the behavior contract and protocol constraints.
2. Load Overview by consuming the architecture and module boundary map, following cursors if transport limits are hit.
3. Execute & Maintain by performing business edits followed by the aoci_maintain command to identify semantic drift.
4. Update & Verify by batch-submitting semantic candidates via aoci_update_entry and proving alignment with aoci_verify.

Frameworks & tools

Requires the aoci CLI binary (versioned and checksum-verified) and a Git repository. Works with any MCP-capable agent host like Claude Code, Cursor, or OpenCode. Supports database schema cognition via AOCI_DB_*_DSN environment variables.

Why this beats prompting it yourself

Manual prompts lack persistence and struggle with context window limits in large repos. This skill uses a formal protocol to ensure the agent's "understanding" is stored in Git, preventing hallucinations about system boundaries and ensuring every architectural claim is bound to a source SHA256.

Use cases

• Codebase Takeover quickly building a mental model of an unfamiliar repository's architecture and contracts.
• System Impact Analysis determining which code objects or database tables are affected by a proposed change.
• Consistency Enforcement maintaining strict FRAS (Function/Responsibility/Authority/Sign-off) discipline across large teams.

Known limitations

Requires pre-installation of the aoci binary on a stable path. Does not handle business data or network egress; it focuses exclusively on source and schema metadata.