Architecture

CocoPlus does not introduce any new runtime infrastructure. No additional processes, no sidecar services, no external APIs. Every capability it provides is expressed through the constructs that Coco already understands: configuration files, subagent definitions, skill scripts, and hooks.

This is a choice about reliability. When something breaks, you should be able to understand why by reading files, not by debugging a service mesh.

---

The Four Pillars

Pillar 1 — Rules: The Ambient Context

Every CocoPlus-initialized project contains a file at .cocoplus/AGENTS.md. Coco loads this file automatically at the start of every session. Every agent, every skill, every hook — they all operate within the constraints this file establishes.

AGENTS.md contains the current CocoBrew phase, the active feature modes, the most recent key decisions, and the Git state summary. It is capped at 200 lines — enforced, not suggested. When a session ends, the hook that updates AGENTS.md compresses older entries if adding new ones would breach the limit.

Why the hard limit? Because everything in AGENTS.md is loaded into every session, whether or not it's needed. Space here is shared with everything else the developer is doing. 200 lines is enough to orient any agent at the start of a session. More than that is noise.

AGENTS.md is never written by hand. Hooks update it automatically. The ambient context is authoritative and current because the system maintains it, not because developers remember to update it.

Pillar 2 — Agents: The Domain Specialists

The .cortex/agents/ directory holds subagent definition files — one for each specialist persona in CocoPlus, plus CocoCupper.

Each definition specifies four things: identity (who this agent is and what domain it owns), model (locked, not a suggestion), tools (which native Coco tools it can access, also locked), and mode (auto = executes, plan = advises only).

These definitions are contracts. The Data Steward operates in plan mode because autonomous execution defeats the purpose of governance review. The CDO uses Opus because strategic architectural decisions warrant the reasoning depth.

CocoCupper is also a subagent. It runs in the background, triggered by the Stop and SubagentStop hooks. It uses Haiku. It is read-only — it cannot write code or modify files outside its designated output path. Its only job is observation and categorization.

Pillar 3 — Skills: The User-Facing Capabilities

Skills are SKILL.md files in .cortex/skills/. Each skill implements one user-facing capability — one slash command, or one group of closely related commands.

Skills are loaded on demand. They are not in the context window by default. When a developer runs /plan, the plan skill is loaded, executes its workflow, and exits. The context window returns to baseline.

Each skill is self-contained. It reads from .cocoplus/ (the current state store), executes its workflow, and writes its outputs back to .cocoplus/. Skills don't share state through the session context — they share state through files. This makes skills independently testable and independently auditable.

Pillar 4 — Hooks: The Nervous System

Hooks are shell scripts that fire when Coco lifecycle events occur. They are invisible to the developer during normal operation. They are what keeps CocoPlus coherent across time.

CocoPlus registers nine hooks:

---

How the Pillars Talk to Each Other

The four pillars interact through a shared state store: the .cocoplus/ directory. Rules are updated by Hooks. Skills read from AGENTS.md. Agents write their outputs to paths specified in their definitions. Hooks validate those outputs against checkpoints.

Here is a complete lifecycle walkthrough — from /spec to /ship:

1. Developer runs /spec. The spec skill loads and opens a guided dialogue.
2. Developer runs /plan. The plan skill reads spec.md, triggers CocoHarvest to generate flow.json, and enters Coco's native plan mode for human approval.
3. Developer approves. The skill commits plan.md and updates AGENTS.md to reflect Build phase.
4. Developer runs /build. The build skill reads flow.json and begins execution.
5. As each subagent completes a stage, the SubagentStop hook fires, validates checkpoints, and updates flow.json stage status.
6. The PostToolUse hook captures significant decisions into warm memory throughout execution.
7. Developer runs /secondeye if they want independent multi-model critique of the plan before proceeding. Three critic instances run in parallel; findings are aggregated.
8. Developer runs /test. Tests run against spec success criteria; results recorded.
9. Developer runs /review. Code Quality Advisor reviews SQL; CocoCupper findings are surfaced; spec compliance checked.
10. Developer runs /ship. Gated on review. Creates structured commit, version tag, optional PR.
11. Session ends. Stop and SessionEnd hooks write CocoMeter data, update AGENTS.md, and queue CocoCupper.
12. Next session starts. AGENTS.md is loaded. Developer sees exactly where they left off.

This sequence is the ordinary experience of working with CocoPlus. Every session is a conversation between the pillars, mediated by files.

---

The CocoPod Directory

The .cocoplus/ directory is the physical manifestation of a CocoPlus project. It contains everything the system needs to be stateful.

.cocoplus/
├── AGENTS.md              ← hot memory, auto-loaded every session (≤200 lines)
├── project.md             ← project identity and initialization metadata
├── flow.json              ← CocoFlow pipeline definition + execution log
├── lifecycle/             ← spec, plan, test, review, deployment artifacts
│   └── .secondeye-staging/ ← temp directory for SecondEye critic outputs
├── memory/                ← decisions.md, patterns.md, errors.md
├── prompts/               ← per-stage prompt files (generated at Plan phase)
├── monitors/              ← four standard monitor configs
├── grove/                 ← CocoGrove: curated patterns + cupper findings
├── meter/                 ← session tracking and cost history
├── snapshots/             ← Environment Inspector scan results
├── modes/                 ← mode flag files (inspector.on, memory.on, etc.)
├── safety-config.json     ← protected schema patterns
└── notifications.json     ← notification routing configuration

This directory goes into version control. The entire project state — decisions, patterns, lifecycle artifacts, pipeline definitions — is versionable, diffable, and recoverable.

File-based persistence was chosen because it aligns with how developers already think about project state. You can read any of these files with a text editor. You can diff them with git. You can restore a previous state with git checkout. The system's intelligence lives in legible files, not in opaque service state.

---

The Four-Tier Model Hierarchy

Model selection across the system follows a four-tier precedence hierarchy, resolved from lowest to highest:

CocoCupper's model is not in this hierarchy. It cannot be overridden. This is an intentional exception — CocoCupper's cost architecture is a design requirement, not a preference.

---

CocoFleet — A Different Kind of Parallelism

CocoHarvest runs parallel subagents within a single Coco session — these are Coco's native subagents, coordinated by the parent session.

CocoFleet is different. It spawns independent Coco CLI processes at the operating system level. Separate processes, separate sessions, separate context windows. Coordinated through shared file state, PID tracking, and dependency resolution logic.

This distinction matters for very large workstreams. When the work is too large for a single Coco session's context budget, you need multiple sessions, not multiple subagents. CocoFleet manages that orchestration. It is not for everyday use. It is for the projects where scale genuinely demands it.

A well-designed system is one where the complexity is in the right place — not eliminated, but located where it can be reasoned about.