The Lifecycle
The oldest insight in software engineering is that code produced without process is code produced twice. Once when you write it wrong, and once when you fix it.
CocoPlus calls its lifecycle CocoBrew. Six phases: Spec, Plan, Build, Test, Review, Ship. The naming is intentional — brewing takes time, has stages, and you can't rush fermentation without ruining the batch.
Each phase has a specific job:
- Spec gets you to write down what you're actually building before you build it. The spec file is not a contract — it is a mirror. You see your own assumptions, written down, and immediately notice the gaps.
- Plan decomposes the spec into work. CocoHarvest does this automatically. Plan ends with a human approval gate. No Build phase begins without it.
- Build executes the plan in isolated stages. Parallel where possible. Sequential where dependencies demand it. Every stage commits its artifacts before the next stage begins.
- Test validates against the spec's success criteria — not the developer's mental model of what success looks like.
- Review is a structured quality pass. Checklist, not opinion. Anti-patterns, spec compliance, CocoCupper findings.
- Ship is gated on Review. Open must-fix items — Ship refuses. This is not negotiable.
The phases are not bureaucracy. They are the difference between developing in straight lines and developing in spirals.
CocoFlow
A CocoFlow is a pipeline definition — a JSON file that describes stages, their dependencies, their assigned personas, their checkpoints, and what constitutes completion.
Think of it like a directed graph of work. Stage B cannot start until Stage A's checkpoint files exist. Stage C can run in parallel with Stage D if neither depends on the other. Each stage knows which persona executes it, which model to use, and what files to produce.
CocoFlow is generated by CocoHarvest at the end of the Plan phase. The developer can read it, understand it, and edit it if needed. It is a transparent artifact — not a black box orchestration layer.
The flow file lives at .cocoplus/flow.json and is updated in real time as execution proceeds. /flow status reads this file and renders a human-readable report. If a stage fails, the failure reason is recorded in the file. If you need to resume from a specific stage, /flow resume [stage-id] validates that all prior stages' checkpoints are intact before proceeding.
CocoFlow is not required for simple tasks. A single-developer, single-persona task goes straight to execution without creating a formal pipeline. The complexity of the tooling should match the complexity of the work.
The Persona System
The deepest design decision in CocoPlus is the one that looks the most obvious: use specialists, not generalists.
A generalist AI model will write you a Snowflake stored procedure. It will write a semantic model. It will write a notebook. It will review governance. It will do all of these things adequately. CocoPlus takes the position that "adequately" is not what you want from an AI assistant — you want depth, and depth requires specialization.
| Persona | Trigger | Model | Mode | Domain |
|---|---|---|---|---|
| Data Engineer | $de | Sonnet | Auto | Schema, SQL, pipelines, performance |
| Analytics Engineer | $ae | Sonnet | Auto | Semantic models, transformations, metrics |
| Data Scientist | $ds | Sonnet | Auto | Notebooks, ML, Cortex ML functions |
| Data Analyst | $da | Haiku→Sonnet | Auto | Queries, exploration, Cortex Analyst |
| BI Analyst | $bi | Haiku→Sonnet | Auto | Dashboards, semantic layer refinement |
| Data Product Manager | $dpm | Sonnet | Plan only | Requirements, documentation, scope |
| Data Steward | $dst | Sonnet | Plan only | Governance, data quality, access policy |
| Chief Data Officer | $cdo | Opus | Plan only | Strategic architecture, data estate decisions |
Each persona has a locked tool set. The Data Steward cannot run arbitrary SQL against production. The Data Scientist can use NotebookExecute; the Data Engineer cannot. These locks are not limitations — they are the persona's identity.
Memory
Three layers. Each layer serves a different time horizon.
The hot layer is AGENTS.md. 200 lines, always loaded, always current. This is what Coco sees at the start of every session. It knows the current phase, the active modes, the three most recent key decisions. It is a summary, not an archive.
The warm layer is three files: decisions, patterns, errors. Richer than AGENTS.md. Consulted when a skill needs more context than the hot layer provides. Updated by hooks throughout the session.
The cold layer is CocoGrove — the curated pattern library. Not everything that happens in a session is worth keeping forever. CocoGrove contains only what has been promoted: patterns that worked, anti-patterns that burned you, reusable templates that earned their place.
These layers are a design about forgetting. Not everything deserves to be remembered. The hot layer forgets by compressing. The warm layer retains selectively. The cold layer requires deliberate promotion. This is how human institutional memory works in high-functioning teams, and it is how CocoPlus models it.
The benefit of this structure compounds. By session thirty, your CocoGrove has thirty sessions of project-specific wisdom. The AI assistant is not starting fresh — it is operating in an environment that knows your schemas, your patterns, your anti-patterns, your decisions.
The Safety Gate
There are two kinds of mistakes: recoverable and unrecoverable.
Recoverable mistakes are fine. They are how you learn. Write the wrong SQL, catch the error, fix it. No problem.
Unrecoverable mistakes are a different category. Drop the wrong production table. Truncate the wrong schema. Delete without a WHERE clause on a table with three million rows. These mistakes are expensive. Sometimes very expensive.
CocoPlus treats these two categories differently. For recoverable mistakes, the system offers guidance — suggestions, warnings, quality checks. Advisory. For unrecoverable mistakes, the system offers a hard gate — an interceptor that fires before the tool call executes and blocks it entirely.
This distinction matters because language model behavior is probabilistic. A strongly-worded prompt that says "never drop production tables" will be followed most of the time. Most of the time is not good enough for irreversible operations. The hard gate cannot be prompted around. It fires at the infrastructure level, before any reasoning happens.
CocoCupper and CocoGrove
After every session, something happens quietly in the background.
CocoCupper — a lightweight analyst agent — reads what just happened. The SQL that was executed. The files that were created. The decisions that were made. It identifies patterns: things that worked consistently, things that failed in consistent ways, approaches that were reinvented unnecessarily. It writes its findings to a file.
Those findings are raw material for CocoGrove. CocoGrove is the pattern library. It is not automatically populated by CocoCupper — that would create noise. Instead, developers promote findings they consider durable.
CocoCupper runs on Haiku. It doesn't need to reason deeply — it needs to recognize and categorize. CocoGrove holds the results of that recognition, curated by a human who decided something was worth keeping.
The combination is institutional memory with a quality filter. The AI captures. The developer curates. The library compounds.
Token Economics
Every tool invocation, every loaded file, every active monitor, every character in AGENTS.md — it all costs context window space.
CocoPlus takes this seriously in a way most AI plugins don't. The AGENTS.md hard limit of 200 lines is not a convention — it is enforced. Skills are loaded on demand, not always active. Monitors run per-stage, not globally. The background analyst uses Haiku. The CDO uses Opus. These choices are made deliberately and documented explicitly.
Why does this matter? Because context explosion is a slow, invisible failure mode. A system that works perfectly at session five begins to degrade at session twenty as accumulated context starts crowding out useful reasoning. CocoPlus is designed to remain useful at session two hundred.
The principle it embodies: the right model for the right task, with the minimum context required to do that task well. Surgical, not comprehensive.
CocoPod
CocoPod is the container that holds everything together.
Before any CocoPlus feature can run, you initialize a CocoPod: /pod init. This creates the .cocoplus/ directory with the complete file structure that all features read from and write to. Memory files, lifecycle artifacts, flow definitions, monitor configurations, the pattern library — all of it lives here.
CocoPod is project-scoped. It lives next to your code. It goes into version control. It is the persistent state that transforms a stateless AI session into a stateful development environment.
When you come back after a week away, /pod resume reads the current state and tells you exactly where you left off. It is not summarizing from the AI's memory — it is reading from files that were written during your last session. The state is durable because files are durable.
This is a choice about trust. CocoPlus doesn't trust the AI's session memory to persist important state. It trusts files. Files are readable, diffable, committable, inspectable. A file-based state store is a state store you can audit.
A system is only as good as what it remembers and what it refuses to forget.