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
Four constructs, working together, compose the entire CocoPlus system.
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. Not by convention — by enforcement. 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. This is important: the ambient context is authoritative and current because the system maintains it, not because developers remember to update it.
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 — which model it uses (locked, not a suggestion)
- Tools — which native Coco tools it can access (also locked)
- Mode — whether it operates in auto mode (executes) or plan mode (advises, never executes autonomously)
These definitions are contracts. The Data Steward's definition says it operates in plan mode, because the Data Steward's job is governance review, not autonomous execution. The CDO's definition says it uses Opus, because strategic architectural decisions warrant the reasoning depth. These choices were made deliberately and documented in the definition files.
When CocoHarvest decomposes a task, it reads these definitions and assigns workstreams accordingly. When a developer types $de, Coco routes directly to the Data Engineer definition. The routing is deterministic — not probabilistic, not inferred.
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.
CocoScout is a third background subagent — also Haiku, also non-invocable. It fires before every Build stage and every persona invocation. Where CocoCupper looks backward (what just happened), CocoScout looks sideways (what context is most relevant right now). It scans warm memory, CocoGrove patterns, CocoContext organizational standards, and Environment Inspector snapshots, ranks them by relevance to the current task, and surfaces the top results to the executing agent. The result is that each persona begins its work with a context window shaped to the task, not the full project history.
Beyond the agent definitions, there is a behavioral layer that applies to all agents simultaneously: CocoBehavior. This is a user-invocable: false SKILL.md file preloaded into every persona at invocation. It establishes four constraints that govern how all CocoPlus agents reason — think before coding (understand before implementing), simplicity first (solve the current problem, not the anticipated one), surgical changes (touch only what the task requires), and evaluation first (validate the approach against available context before executing). CocoBehavior is not a set of reminders — it is a structural definition of what it means for a CocoPlus agent to reason well in a data engineering context.
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 $cocoplus plan, the plan skill is loaded, executes its workflow, and exits. The context window returns to baseline.
This is not a technical limitation — it's a design decision. Loading all skills all the time would consume context window space whether the developer needed them or not. On-demand loading means the context window reflects the current task, not the entire CocoPlus surface area.
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.
The complete skill catalog covers the full lifecycle: $spec, $cocoplus plan, $cocoplus build, $cocoplus test, $cocoplus review, $cocoplus ship, plus the feature-specific commands for every CocoPlus capability.
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:
- SessionStart — reads current state, initializes CocoMeter tracking, triggers the Environment Inspector if auto-mode is active, evaluates all CocoSeed trigger conditions and surfaces any newly-triggered seeds in the session startup summary
- SessionEnd — writes CocoMeter session data, updates AGENTS.md with session summary, optionally triggers CocoCupper, writes a final CocoHealth checkpoint to
lifecycle/checkpoint.md - PreToolUse — the Safety Gate, two layers: (1) phase gate — unconditionally blocks SnowflakeSqlExecute during the
specandplanlifecycle phases regardless of safety mode; (2) pattern gate — intercepts SnowflakeSqlExecute from the build phase onward and blocks or warns on destructive SQL (DROP, TRUNCATE, DELETE without WHERE, ALTER on production schemas) per strict/normal mode setting. - PostToolUse — the Memory Engine capture layer. Records significant tool use events into the warm memory layer. Also runs the CocoHealth utilization sample — checking context window fill level against configured thresholds and surfacing advisory or critical warnings when thresholds are crossed.
- UserPromptSubmit — intercepts
$<persona>shorthand and routes to the appropriate subagent. Also intercepts$cocoplus onand$cocoplus offfor Assist Mode toggling. - SubagentStop — fires when a subagent completes. Validates checkpoints, updates flow.json stage status, triggers the next stage if dependencies are satisfied.
- Stop — fires when the main session ends. Final state capture.
- PreCompact — fires before Coco compacts the context window. Flushes important state from the context to the warm memory layer before it's lost to compaction.
- Notification — fires when the notification system wants to surface something to the developer. Routes to the configured notification channel.
The hooks are the reason CocoPlus can maintain state across sessions without requiring the developer to do anything. They are the background machinery that keeps the system coherent.
How the Pillars Talk to Each Other
The four pillars interact through a shared state store: the .cocoplus/ directory.
Rules (AGENTS.md) are updated by Hooks (SessionEnd, PreCompact, PostToolUse). Skills read from AGENTS.md to understand current phase and modes. Agents write their outputs to .cocoplus/ paths specified in their definitions. Hooks validate those outputs against checkpoints before updating flow status.
The flow looks like this in practice:
- Optionally, the developer runs
$discussbefore$cocoplus plan. The discuss skill captures implementation decisions (model selection, evaluation methodology, accuracy thresholds, scope boundaries) intolifecycle/discuss.md. The CocoSpec quality gate then scores the specification on five dimensions — if the score is below nine, the gate names implicit assumptions and holds until addressed. - Developer runs
$cocoplus plan. The plan skill loads. - The skill reads
spec.mdanddiscuss.md(if it exists) from the warm layer, and the current AGENTS.md from the hot layer. Ifdiscuss.mdexists, the planning agent uses it as a constraint document; a plan-checker step validates the generated plan against its decisions and flags any contradictions before approval. - CocoHarvest decomposes the plan, generates
flow.json, and produces prompt files. CocoLens classifies every task as HITL or AFK during this decomposition step — the developer reviews the Type column and can flip any classification before spawning begins. - The plan enters Coco's native
$cocoplus planmode as the human approval gate. - Optionally, the developer runs
$secondeye. Three subagents fire in parallel — Haiku critiques for efficiency, Sonnet for completeness, Opus for strategic risk. Their findings are classified (Critical / Advisory / Observation) with HITL/AFK and BLOCKING/MINOR tags. Critical findings trigger a soft gate:$secondeye acknowledgeis required before Build can proceed. - Developer approves. The skill writes
plan.md, commits via Git, and updates AGENTS.md to reflect the Build phase. - The developer runs
$cocoplus build. The build skill readsflow.jsonand begins execution. - As each subagent completes a stage, the SubagentStop hook fires, validates checkpoints, and updates
flow.jsonstage status. At any point during build, the developer can run$flow viewto open a live browser visualization of the pipeline — which stages are running, which are pending, which are blocked. - The PostToolUse hook captures significant decisions into the warm memory layer throughout.
- The session ends. The Stop and SessionEnd hooks write CocoMeter data, update AGENTS.md, and queue CocoCupper if needed.
- Next session starts. AGENTS.md is loaded. The developer sees exactly where they left off.
This sequence is not exceptional — it 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
├── project.md ← project identity and initialization metadata
├── flow.json ← the current CocoFlow pipeline definition
├── lifecycle/ ← phase artifacts: spec, plan, review, deployment
│ ├── cocoplus-context.md ← constitutional document — every agent reads this first
│ ├── bloom.md ← CocoBloom working backwards commitment (optional, committed)
│ ├── spec.md ← current specification
│ ├── discuss.md ← CocoDiscuss decision-lock document (optional)
│ ├── spec-score.md ← CocoSpec quality gate score and rationale
│ ├── plan.md ← approved execution plan
│ ├── kb.md ← project knowledge base (populated by CocoCupper)
│ ├── checkpoint.md ← CocoHealth recovery snapshot (overwritten per $pod checkpoint)
│ ├── review.md ← Review phase findings and must-fix items
│ ├── cocowatch-session.md ← CocoWatch engagement signals (ephemeral — not committed)
│ └── klatch/ ← CocoKlatch roundtable artifacts (committed)
│ ├── [timestamp]-[slug]-brief.md ← topic brief
│ ├── [timestamp]-[slug]-[role].md ← participant analysis (one per role)
│ └── [timestamp]-[slug]-synthesis.md ← synthesis document
├── memory/ ← warm memory: decisions, patterns, errors
├── context/ ← CocoContext: six organizational standards files
├── prompts/ ← per-stage prompt files generated at Plan phase
├── monitors/ ← four standard monitor configurations
├── grove/ ← CocoGrove: curated pattern library + cupper findings
│ ├── patterns/ ← promoted patterns (individual markdown files)
│ ├── language/ ← ubiquitous language glossary
│ │ └── glossary.md ← approved domain terms
│ └── anchors/ ← CocoScout Anchor Lens catalog
│ └── catalog.md ← pre-compiled methodology vocabulary lookup table
├── map/ ← CocoMap knowledge graph
│ ├── coco-map.json ← committed knowledge graph (structural + domain views)
│ └── intermediate/ ← gitignored scratch files from analysis agents
├── seeds/ ← CocoSeed deferred idea files
├── pull/ ← CocoPull distillation manifest and pull artifacts
│ └── manifest.json ← records all pull files, compression ratios, validation scores
├── harvest/ ← CocoHarvest execution state
│ ├── [run-id]-progress.txt ← append-only progress log
│ ├── [run-id]-tasks.json ← atomic task state file
│ └── intermediate/ ← CocoFlow parallel evaluation intermediate results
├── meter/ ← CocoMeter: session tracking and history
│ ├── accuracy-history.jsonl ← per-session estimation accuracy records
│ └── adjustment-factor.json ← rolling calibration factor for pre-flight estimates
├── sentinel/ ← CocoSentinel artifact quality gate results
│ ├── <artifact-sha>.json ← evaluation result per artifact (SHA-bound)
│ └── approvals.jsonl ← SHA-bound approval records (append-only)
├── wisdom/ ← CocoWisdom institutional rejection memory
│ ├── rejections.jsonl ← append-only structured rejection records (committed)
│ ├── wisdom-index.db ← SQLite full-text search index
│ └── insights-<date>.md ← periodic synthesis reports (committed)
├── review/ ← CocoReview structured code review outputs
│ ├── cocoreview-<timestamp>.md ← review reports (committed)
│ └── complexity-cache.json ← PR complexity analyzer output (gitignored)
├── ops/ ← CocoOps delivery intelligence data
│ ├── dora-snapshot.json ← latest DORA metric computation (committed)
│ ├── sprint-health.json ← current sprint computation (committed)
│ └── demo/ ← demo mode mock dataset (gitignored)
├── index/ ← CocoPull session archive search index
│ └── sessions.db ← SQLite FTS index of session pull archives (gitignored)
├── snapshots/ ← Environment Inspector scan results
├── modes/ ← mode flag files (inspector.on, memory.on, etc.)
└── notifications.json ← notification routing configuration
cocoplus.toml ← single source of truth for all plugin configuration (committed)
This directory goes into version control. The entire project state — decisions, patterns, lifecycle artifacts, pipeline definitions — is versionable, diffable, and recoverable.
This is not an accident. File-based persistence was chosen specifically 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
One of CocoPlus's more precise decisions is how model selection works across the system. There are four tiers, resolved from lowest to highest precedence:
Tier 1 — Persona Default. Each .agent.md file specifies a default model. This is the baseline. Data Engineer uses Sonnet. CDO uses Opus. CocoCupper uses Haiku, always.
Tier 2 — Pipeline Default. The defaults.model field in flow.json overrides persona defaults for all stages in a pipeline. Useful when you want a consistent model choice across a multi-stage execution.
Tier 3 — Stage-Level Override. Individual stages in flow.json can specify their own model, overriding both the persona default and the pipeline default.
Tier 4 — Runtime Flag. The --model flag on any persona invocation or flow command overrides everything else for that specific call. It does not persist to flow.json.
This hierarchy exists because model selection is a meaningful engineering decision. The CDO's model choice was made for a reason. Overriding it at the pipeline level for a specific execution context is a legitimate decision. Overriding it at runtime for a single call is also legitimate. The hierarchy makes these decisions explicit and traceable.
CocoCupper's model is not in this hierarchy. It cannot be overridden. This is an intentional exception, not an oversight.
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 — tracking which processes are running, handling their completion, sequencing dependent processes, surfacing logs.
CocoFleet 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.