Command Reference

Command Reference

Every CocoPlus command, organized by the feature that owns it. Each command includes its flags, what it does, and what output to expect.

Every CocoPlus command, organized by the feature that owns it. Each command includes its flags, what it does, and what output to expect.

Commands marked [auto] do not require explicit invocation — they are triggered by hooks. They are documented here for awareness, not for manual use.

Setup and State — CocoPod

CocoPod is the prerequisite. No other CocoPlus command functions in a directory without an initialized CocoPod.

$pod init — Initialize a new CocoPlus project


$pod init
$pod init --name "Data Platform v2"

Prompts for project name and description if not provided. Creates .cocoplus/ directory structure, writes initial AGENTS.md, project.md, flow.json, cocoplus.toml, and notifications.json. Creates the initial git commit. Also generates lifecycle/cocoplus-context.md — the constitutional document that every CocoPlus agent reads first to understand the project's durable context, organizational standards, and active decision record. Fails if .cocoplus/ already exists.

cocoplus.toml is the single source of truth for all operator-configurable plugin settings: security rules, cost thresholds, warehouse access, model tier defaults, demo mode flags, and sprint configuration. All downstream artifacts (agent frontmatter, hook rule tables) are generated from it and must not be edited directly.

--refresh-context — Regenerates lifecycle/cocoplus-context.md through a guided dialogue without reinitializing the full pod. Archives the prior version to lifecycle/cocoplus-context-[timestamp].md before regeneration. Use when project scope, organizational standards, or key decisions have shifted significantly since the last initialization.

Output: Directory structure confirmation and next-steps guidance.

$pod status — Project state dashboard


$pod status

Reads all state from .cocoplus/ and reports: current CocoBrew phase, active feature modes, CocoFlow pipeline status, recent CocoMeter session summary, latest CocoCupper findings (last 3), and Environment Inspector snapshot age. Also performs a self-heal check: compares flag files in .cocoplus/modes/ against the ## Active Modes section in AGENTS.md. If diverged, shows a warning and offers a one-step sync.

Output: Structured report. No state changes unless sync is accepted.

$pod resume — Context reconstruction for returning developers


$pod resume

Produces a focused narrative of where you left off: last phase completed, what blocking items remain, the three most recent key decisions, and the recommended immediate next action. Updates AGENTS.md with the resume timestamp.

Output: Narrative summary. Use at the start of any session after time away.

$pod kb — View the project knowledge base


$pod kb

Displays lifecycle/kb.md — the session-spanning project knowledge base populated by CocoCupper. Contains durable insights that have survived the curation gate: patterns observed repeatedly, key decisions and their rationale, anomalies with confirmed root causes, evaluation baselines established across prior sessions.

Output: Knowledge base contents. No state changes.

$pod checkpoint — Write a structured recovery snapshot


$pod checkpoint

Writes lifecycle/checkpoint.md with: current CocoBrew phase and phase ID, in-progress CocoFlow stage (if any), last five decisions from memory/decisions.md, pending must-fix items from review.md, active CocoHarvest harvest status, and context utilization at checkpoint time. Also invoked automatically by CocoHealth when context utilization crosses the 70% critical threshold.

Confirms: "Checkpoint saved. Run $clear to reset context, then $pod resume to continue from this point."

Output: Committed lifecycle/checkpoint.md. Run before $clear to enable clean recovery.

$cocoplus sync — Propagate cocoplus.toml changes to all generated artifacts


$cocoplus sync

Reads cocoplus.toml and propagates its values into all downstream plugin artifacts: agent frontmatter files, hook rule tables, environment settings, and generated configuration. Commits all generated files as a single change with message chore(config): $cocoplus sync — cocoplus.toml applied. If a generated file was manually edited since the last sync, the manual edit is overwritten and a warning is shown — cocoplus.toml is the source of truth, not its outputs.

Run after any change to cocoplus.toml to ensure all plugin components reflect the current configuration intent.

Output: Generated file changes + git commit.

$cocoplus migrate-config — Convert a legacy safety-config.json to cocoplus.toml


$cocoplus migrate-config

Detects an existing safety-config.json in the project, reads its security rules, populates the [security] section of a new cocoplus.toml, and runs $cocoplus sync to regenerate downstream artifacts. The original safety-config.json is archived (not deleted) after migration. For projects upgrading from an earlier plugin version.

Output: cocoplus.toml creation + sync commit + archive of safety-config.json.

Master Toggle — Assist Mode

$cocoplus on — Activate all features simultaneously


$cocoplus on

Creates mode flag files for Memory Engine, Environment Inspector (auto), Safety Gate (normal), Code Quality Advisor, Context Mode, and CocoMeter. Immediately triggers an Environment Inspector background scan. Updates AGENTS.md to show "FULL ASSIST MODE: ACTIVE". Creates git commit. Idempotent — running when already active confirms state only.

Does not activate: CocoBrew lifecycle phases, CocoSpark, CocoFleet.

Output: Confirmation listing every feature and its activation state.

$cocoplus off — Deactivate all features


$cocoplus off

Removes all mode flag files. Does not delete any data files — memory content, meter history, grove patterns, and lifecycle artifacts are preserved. Creates git commit. Shows what was deactivated and what state was preserved.

Output: Deactivation summary with preserved-state list.

Lifecycle — CocoBrew

The six phases run sequentially. Each phase requires the previous phase to be committed before it can begin.

$spec — Enter the Spec phase


$spec
$spec --force
$spec --full
$spec --quick

Before opening the requirements dialogue, a deterministic classifier (scope-classify.sh) analyzes the initial description and routes to one of two tracks: Quick Flow (single-function, clear requirements — produces lifecycle/quick-build.md via a Clarify → Implement → Verify sequence, no plan.md or flow.json) or Full Flow (everything else — the complete six-phase CocoBrew lifecycle). --full forces Full Flow regardless of classification. --quick forces Quick Flow with a warning if the classifier disagrees. If no bloom document exists, a one-line advisory recommends running $bloom first.

In Full Flow, opens a structured requirements dialogue: goal, success criteria, explicit out-of-scope, involved Snowflake objects, constraints. Output written to .cocoplus/lifecycle/spec.md. Git commit: feat(spec): initial project specification captured.

Re-running during the plan phase prompts for confirmation. Re-running during build, test, review, or shipped phases requires --force — the skill warns that active CocoHarvest worktrees (agent/stage-*) will become stale and must be pruned manually before accepting the flag.

Output: Completed spec.md (Full Flow) or quick-build.md (Quick Flow) + commit confirmation.

$cocoplus plan — Enter the Plan phase


$cocoplus plan

Reads spec.md, invokes CocoHarvest to decompose work, generates flow.json, and enters Coco's native plan mode as a hard approval gate. No Build phase begins without plan approval. Output: .cocoplus/lifecycle/plan.md, .cocoplus/flow.json, prompt stubs in .cocoplus/prompts/. Git commit: feat(plan): approved execution plan v<version>.

Output: Approved plan document + flow.json + commit confirmation.

$cocoplus build — Enter the Build phase


$cocoplus build
$cocoplus build --model <haiku|sonnet|opus>

Reads plan.md and flow.json. For complex multi-workstream plans, invokes CocoHarvest to spawn parallel persona subagents in isolated git worktrees. For simple single-workstream plans, delegates directly to the appropriate persona. --model sets the pipeline-level default model (Tier 2) applied to any stage without a stage-level model assignment. Checks for open unacknowledged SecondEye Critical findings before proceeding.

Output: Per-stage build commits + updated flow.json.

$cocoplus test — Enter the Test phase


$cocoplus test

Runs validation against spec success criteria using SQL execution, notebook execution, or file-existence checks depending on what was built. Results recorded in .cocoplus/lifecycle/test.md. Can be re-run without rebuilding. Git commit: test: test execution and validation.

Output: Test results document with pass/fail per spec criterion.

$cocoplus review — Enter the Review phase


$cocoplus review

Aggregates Code Quality Advisor findings, CocoCupper session intelligence, and spec compliance check into .cocoplus/lifecycle/review.md. Findings classified as: must-fix (blocks Ship), should-fix (recommended), consider (informational). Git commit: docs(review): code review and quality analysis complete.

Output: Review document with classified findings.

$cocoplus ship — Enter the Ship phase


$cocoplus ship

Gated on review completion with no open must-fix items. Cross-checks that spec.md, plan.md, and review.md physically exist on disk before proceeding — meta.json alone is not sufficient. Creates final structured commit with full lifecycle summary in the commit message. Applies a semantic version tag (validated as v<major>.<minor>.<patch>; the highest existing tag is found programmatically, filtering only well-formed version tags). Prunes stale CocoHarvest worktrees (agent/stage-*) after the release commit. Writes .cocoplus/lifecycle/deployment.md with version, SHA, and timestamp. Optionally creates a pull request via gh pr create if gh CLI is configured.

Output: Deployment summary document + tagged commit.

$rewind [step-id] — Roll back to a previous lifecycle state


$rewind plan-v1
$rewind build-stage-003
$rewind --tag cocoplus/harvest/hr-20260511-4a2f/task-007
$rewind --tag task-007

Identifies CocoBrew phase commits in git log, shows the target state and what would be discarded, then resets to the target after confirmation. Uses soft reset — history is preserved. After reset, automatically prunes stale CocoHarvest worktrees (agent/stage-*) to prevent naming collisions on future builds. Updates AGENTS.md and flow.json to reflect rolled-back state.

--tag <tag-name> — Rolls back to a specific git tag created by CocoHarvest at task completion. Two tag series exist: harvest task tags (cocoplus/harvest/[run-id]/task-[N] — e.g. cocoplus/harvest/hr-20260511-4a2f/task-007) created at every CocoHarvest task completion; and function version tags (cocoplus/fn/[function-name]/v[N] — e.g. cocoplus/fn/sentiment_classifier/v3) created when a Cortex function reaches a named deployment stage. Harvest tags can be abbreviated to their last segment (task-007). This gives sub-phase granularity: recovery to any task completion boundary in any prior harvest run is a single command rather than git log archaeology.

Output: Rollback confirmation with state summary.

$fork [branch-name] — Create an exploration worktree


$fork alternative-schema

Creates a git worktree on a fork/<branch-name> branch at the current phase. Experiment freely. If the fork produces something useful, bring it back. If not, discard it. Main branch is untouched.

Output: New worktree path and branch confirmation.

Pipeline Execution — CocoFlow

CocoFlow commands manage the execution of the pipeline defined in flow.json. Most developers interact with these during and after the Build phase.

$flow run [stage-id] — Execute the pipeline or a specific stage


$flow run
$flow run stage-003
$flow run --model <haiku|sonnet|opus>
$flow run --model <value> --stage <stage-id>
$flow run --concurrency <normal|caution|single-track>

Reads flow.json, spawns stage subagents, monitors completion via SubagentStop hook integration. Stage status written back to flow.json in real time. --model without --stage applies a Tier 2 pipeline default. --model with --stage applies a Tier 3 stage-level override. Neither form modifies flow.json on disk.

--concurrency controls CocoHarvest's adaptive parallelism mode. In normal operation, the mode is managed automatically: the pipeline starts in Normal mode (full parallelism), steps down to Caution (reduced parallelism) on any stage failure, and drops to Single-track (serial execution) if more than 50% of stages have failed. Pass --concurrency normal to override back to full parallelism when you have investigated failures and want to retry at full speed. The current concurrency mode is visible in $flow status.

Stages with "isolated": true in their flow.json definition receive only checkpoint-validated deliverables from prior stages — not the full execution context. Use this field for deployment stages, post-evaluation steps, or any stage that should operate on declared outputs rather than ambient session state.

Output: Stage execution progress. Final status in flow.json.

$flow status — Live pipeline status


$flow status

Renders the pipeline state as a structured report: each stage with status indicator, runtime duration, checkpoint validation results, failure reason (if applicable).

Output: Formatted pipeline report. No state changes.

$flow pause — Pause after current stage completes


$flow pause

Halts execution after the currently-running stage completes. Running stages are never killed mid-execution. Pipeline enters "paused" state.

Output: Pause confirmation with current stage status.

$flow resume [stage-id] — Resume a paused or failed pipeline


$flow resume
$flow resume stage-003

Validates that all prior stages' checkpoints are satisfied before resuming. If checkpoints are missing, resume is blocked with a clear explanation of what's missing and why.

Output: Resume confirmation or checkpoint failure report.

$flow view — Render the pipeline as an interactive visual graph


$flow view
$flow view --output <path>

Reads .cocoplus/flow.json, injects the data into a self-contained HTML template, writes the result to .cocoplus/flow-view.html, and opens it in the OS default browser. The rendered view shows task cards arranged left-to-right by topological level, group bounding boxes, dependency edges as bezier curves, and colour-coded status badges (running, pending, success, failed). Click any node to highlight its connections and open a metadata panel. Pan, zoom, and load a different flow.json for comparison — all in-browser.

--output <path> writes to a custom path without opening the browser. Useful for sharing a pipeline snapshot or attaching to documentation.

The output file is ephemeral — excluded from git, overwritten on every invocation, and never committed. CocoView makes no state changes.

Requires: A valid flow.json. If none exists, run $cocoplus plan first.

Output: .cocoplus/flow-view.html opened in browser + status summary ([N] nodes, [M] groups).

Pipeline Templates — CocoRecipe

CocoRecipe provides pre-built parameterized CocoFlow pipeline templates. Templates live in the CocoPlus profile folder (~/.coco/plugins/cocoplus/recipes/) — they are not project-specific. They are tools you carry with you and apply across projects.

$recipe list — Browse available templates


$recipe list

Lists the standard recipe library alongside any custom recipes you have created. Shows recipe name, description, parameter count, and last-used date (if applicable).

Standard library:

Output: Recipe list. No state changes.

$recipe use <name> — Instantiate a recipe as a flow.json


$recipe use data-product-build
$recipe use schema-migration --param target_schema=ANALYTICS

Prompts for any required parameters not supplied via --param. Generates a populated flow.json from the template in the current project's .cocoplus/ directory. Offers to open in CocoView ($flow view) before Build begins so you can inspect the resulting pipeline graph. Fails if a flow.json already exists unless you pass --overwrite.

Output: Populated flow.json + optional CocoView render.

$recipe new — Create a custom recipe from the current flow.json


$recipe new

Reads the current flow.json and parameterizes it by identifying environment-specific values — schema names, table names, model assignments, warehouse targets — and replacing them with named parameter placeholders. Prompts for recipe name and description. Saves the resulting template to ~/.coco/plugins/cocoplus/recipes/ for reuse across all future projects.

Output: New recipe template file in profile folder.

Personas

Personas are invoked with the $ prefix. All persona invocations route through the UserPromptSubmit hook.

$personas — List all available personas


$personas

Lists all eight personas with their trigger, default model, invocation mode, and core tools.

Output: Formatted persona table. No state changes.

$de — Data Engineer


$de Review this stored procedure for performance issues
$de --continue Fix the issues you identified
$de --model haiku Generate a quick schema summary

Domain: schema design, SQL optimization, stored procedures, pipelines. Model: Sonnet. Mode: auto (executes).

$ae — Analytics Engineer


$ae Design a semantic model for this fact table
$ae --continue Add the revenue metric definition

Domain: semantic models, dbt-style transformations, metric definitions. Model: Sonnet. Mode: auto (executes).

$ds — Data Scientist


$ds Build a feature engineering pipeline for this dataset
$ds --model opus Design an ML architecture strategy

Domain: notebooks, ML pipelines, feature engineering, Cortex ML functions. Model: Sonnet. Mode: auto (executes).

$da — Data Analyst


$da Write a query for daily active users by region
$da --model sonnet Write a multi-CTE attribution analysis

Domain: query writing, exploration, Cortex Analyst integration. Default model: Haiku (escalates to Sonnet for complex queries). Mode: auto (executes).

$bi — BI Analyst


$bi Refine the semantic layer for the sales dashboard

Domain: dashboards, semantic layer refinement, presentation-ready outputs. Default model: Haiku (escalates to Sonnet). Mode: auto (executes).

$dpm — Data Product Manager


$dpm Document the requirements for the churn model output table
$dpm Write a stakeholder summary of this pipeline's capabilities

Domain: requirements, documentation, stakeholder communication. Model: Sonnet. Mode: plan only — never executes tools autonomously.

$dst — Data Steward


$dst Review this schema design for PII tagging compliance
$dst Validate row access policy coverage for this table

Domain: governance, data quality, access policy review. Model: Sonnet. Mode: plan only — validates and recommends but does not execute production changes.

$cdo — Chief Data Officer


$cdo What are the long-term architectural implications of this data model?
$cdo --model sonnet Quick trade-off summary between these two approaches

Domain: strategic architecture, system-level decisions, trade-off analysis. Model: Opus (the only persona defaulting to Opus). Mode: plan only. Downgrading CDO's model triggers a logged advisory.

Flags common to all persona invocations:

--continue — Pass the full current conversation context to the persona for seamless continuation without re-explaining the problem.

--model <haiku|sonnet|opus> — Override the persona's default model for this invocation only. Does not affect the persona definition or future invocations. Cannot override CocoCupper (which is always Haiku and not user-invokable).

Memory Engine

$memory on — Enable memory capture


$memory on

Creates modes/memory.on flag file. PostToolUse hook begins capturing significant tool use events — schema changes, plan updates, explicit decisions — to the warm memory layer.

$memory off — Disable memory capture


$memory off

Removes modes/memory.on flag. Existing memory content is preserved. Capture stops until re-enabled.

Organizational Standards — CocoContext

CocoContext stores durable organizational standards that every persona and subagent reads before generating output. These files are committed to git — they travel with the project and evolve with the team. There are six standard types, each capped at 200 lines by the same discipline that governs AGENTS.md.

$context add <type> — Capture or update an organizational standard


$context add approved-models
$context add quality-thresholds
$context add pii-policy
$context add warehouse-policy
$context add naming-conventions
$context add governance-gates

Opens a guided capture workflow for the specified standard type. If the target file already exists, its current contents are shown first — you're adding to a living document, not replacing it. Output written to .cocoplus/context/<type>.md. Creates a git commit on completion.

Output: Updated context file + commit confirmation.

$context view <type> — Display a stored standard


$context view pii-policy
$context view naming-conventions

Shows the current contents of the specified context file in readable form.

Output: File contents. No state changes.

$context list — List all configured standards


$context list

Shows which of the six standard types have been populated and their approximate word counts. Types not yet configured are listed as "not configured."

Output: Status table. No state changes.

Environment Inspector

$cocoplus inspect — Run an environment scan


$cocoplus inspect
$cocoplus inspect --schema ANALYTICS
$cocoplus inspect --full

Scans connected Snowflake environment: schemas, tables, views, stored procedures, functions, Cortex Search endpoints, Cortex Analyst semantic models, access grants, resource monitors. --schema limits scan to one schema. --full includes column-level statistics and access policy details. Output written to .cocoplus/snapshots/[timestamp]-env.md. Session context receives a summary of key findings.

Output: Snapshot file + session summary.

$inspector on — Enable auto-scan on session start


$inspector on

Creates modes/inspector.on flag. SessionStart hook triggers inspector as a non-blocking background subagent at the start of every session.

$inspector off — Disable auto-scan


$inspector off

Removes modes/inspector.on flag. Manual $cocoplus inspect invocation still works.

Safety Gate

$safety strict — Maximum protection mode


$safety strict

Creates modes/safety.strict flag. Hard blocks any SQL containing DROP TABLE, DROP SCHEMA, DROP DATABASE, DROP PROCEDURE, DROP FUNCTION, DROP VIEW, TRUNCATE TABLE, DELETE without WHERE, or ALTER TABLE on production-pattern schemas. Use in environments where even warnings are too close to the edge.

$safety normal — Standard protection mode (default)


$safety normal

Creates modes/safety.normal flag. Same pattern set as strict, but triggers warnings instead of hard blocks. The soft gate for batch operations is active in both strict and normal modes.

$safety off — Disable Safety Gate


$safety off

Removes safety mode flags. No hard blocks, no warnings from the pattern gate. Only use in development environments with no production data. Using this in a production-adjacent environment is a manual override of a deliberate safety system — the decision and its consequences are yours.

Note: $safety off does not disable the phase gate. SnowflakeSqlExecute remains unconditionally blocked during the spec and plan lifecycle phases regardless of this setting.

Code Quality Advisor

$quality on — Enable background quality review


$quality on

Creates modes/quality.on flag. PostToolUse hook triggers a lightweight background review after every .sql file write. Findings surfaced via the Notification system when complete (non-blocking).

$quality off — Disable background quality review


$quality off

Removes modes/quality.on flag.

$quality run [file-path] — Immediate full quality review


$quality run
$quality run path/to/procedure.sql

Runs a complete review immediately and blocks until complete. Without a file path, reviews all SQL files modified in the current session. Produces a comprehensive findings report covering performance, correctness, governance, and cost.

Output: Full findings report in session context.

CocoMeter — Token and Cost Tracking

$meter on — Enable token tracking


$meter on

Creates modes/cocometer.on flag. PostToolUse hook begins recording token consumption keyed by tool, feature, and timestamp to meter/current-session.json.

$meter off — Disable token tracking


$meter off

Removes modes/cocometer.on flag.

$meter — Current session summary


$meter

Shows token consumption and estimated Snowflake credit cost for the current session, broken down by feature and operation.

Output: Session cost summary. No state changes.

$meter estimate [description] — Pre-flight cost estimation


$meter estimate "Run a CocoHarvest build with four parallel stages"
$meter estimate "SecondEye critique on a 200-line plan"

Uses Haiku to analyze the described operation against known cost profiles and returns an estimated token consumption and credit cost before you run it. Useful before expensive multi-agent operations.

Output: Estimated cost breakdown. No state changes.

$meter history [n] — Historical session summaries


$meter history
$meter history 5

Shows per-session cost summaries for the last N sessions (default 10) from meter/history.jsonl. Includes trends and identification of most expensive features and operations.

Output: Historical cost report. No state changes.

$meter view — Generate the token attribution dashboard (CocoMeter Enhanced)


$meter view

Reads all captured request_id values from .cocoplus/meter/request-map.jsonl, queries SNOWFLAKE.ACCOUNT_USAGE.CORTEX_CODE_CLI_USAGE_HISTORY through Coco's existing Snowflake connection, joins the result with stage attribution data, and generates an interactive HTML dashboard at .cocoplus/meter-view.html. Opens in the OS default browser.

Dashboard sections: Summary cards (total tokens, total credits, cache efficiency, output tokens), Stage Attribution table (per-stage token bars, cache hit %, model indicator, click-to-filter), Model Distribution (token consumption by Haiku/Sonnet/Opus), Token Composition (cache-read / cache-write / fresh-input / output proportions), and a full Request Log with REQUEST_ID, parent relationship, stage, time, token breakdown, credits, and model badge.

The dashboard is a self-contained local HTML file — no network requests, no external dependencies, excluded from git. Data is authoritative: sourced from Snowflake's billing record, attributed per-request, per-stage.

Requires: At least one completed session with CocoMeter active (so request-map.jsonl has entries).

Output: .cocoplus/meter-view.html opened in browser.

$meter sync — Refresh usage data without regenerating the full dashboard (CocoMeter Enhanced)


$meter sync

Re-queries Snowflake for the most recent usage data for all request_id values in request-map.jsonl and updates the injected HTML without a full $meter view regeneration. Useful for refreshing the dashboard after a long pipeline run completes.

Output: Updated meter-view.html + sync summary (records updated, new tokens found).

$meter accuracy — Estimation accuracy learning dashboard (CocoMeter Enhanced)


$meter accuracy

Displays the estimation accuracy history accumulated via the Accuracy Learning Feedback Loop. CocoMeter compares pre-flight estimates against actual session consumption (drawn from request-map.jsonl) and stores session ratios in meter/accuracy-history.jsonl. The current calibration adjustment factor — the rolling median of the last 10 session ratios — is stored in meter/adjustment-factor.json and automatically applied to future pre-flight estimates.

$meter accuracy shows: the current adjustment factor and its sample size, the trend over the last five sessions (stable / rising / falling), and the raw per-session history (estimated tokens, actual tokens, ratio). When the adjustment factor is active, $meter estimate output includes a calibration note: "Estimated 45,000 tokens (baseline: 30,000, calibration factor: 1.5x from 8 prior sessions)."

Output: Accuracy history table + current calibration factor + trend indicator.

CocoCupper — Post-Execution Intelligence

CocoCupper runs automatically via hooks. The manual commands below are for on-demand analysis and review.

$cup — Manually trigger CocoCupper analysis


$cup

Triggers CocoCupper (Haiku, read-only) to analyze the current session's completed output. Findings written to .cocoplus/grove/cupper-findings.md. CocoCupper cannot modify any code, SQL, or configuration file.

Output: Findings written to grove. Session notification when complete.

$cup history [n] — Review past findings


$cup history
$cup history 3

Shows findings from the last N sessions (default all available). Useful before starting a new session to see what patterns have been accumulating.

Output: Historical findings report. No state changes.

CocoGrove — Pattern Library

$patterns view [tag] — Browse promoted patterns


$patterns view
$patterns view pagination
$patterns view snowflake-optimization

Lists patterns in the grove, optionally filtered by tag. Shows pattern name, description, and context.

Output: Pattern list. No state changes.

$patterns promote [finding-id] — Promote a CocoCupper finding to a permanent pattern


$patterns promote FINDING-047

Elevates a CocoCupper finding to a permanent pattern in .cocoplus/grove/patterns/. Prompts for name, description, context (when to apply), anti-context (when not to apply), and tags. Promoted patterns are markdown files in git — editable and versionable.

Output: New pattern file + confirmation.

$grove glossary — Propose domain terms from recent artifacts


$grove glossary

Scans recent lifecycle artifacts (spec.md, plan.md, review.md, cupper findings) for candidate domain terms and proposes additions to grove/language/glossary.md. Each candidate is presented with its source context and proposed definition. Developer reviews and approves or rejects each proposal. Approved terms are written to the glossary and become available for CocoScout's domain vocabulary.

Output: Candidate term proposals awaiting developer review.

$grove glossary view — View the current glossary


$grove glossary view

Displays the project's ubiquitous language glossary from grove/language/glossary.md. Lists all approved domain terms, their definitions, and the artifacts they appear in.

Output: Current glossary. No state changes.

Pattern Distillation — CocoDream

CocoDream surfaces prompt patterns that have proven reliable across sessions and refines them into tested, reusable prompts through a supervised iteration process. The developer reviews and approves every candidate. Nothing is promoted automatically — the intelligence is CocoPlus's, but the judgment is yours.

$dream — Initiate a pattern distillation session


$dream

Triggers CocoCupper (Haiku) to scan CocoGrove cupper-findings and session history for prompt patterns that have produced consistently good results across multiple invocations. Candidate patterns are written to .cocoplus/grove/dream-[timestamp].md with a draft optimized prompt, the evidence that surfaced it, and the rationale for why it is worth formalizing. The developer reviews each candidate, edits freely, then either promotes to CocoGrove as a permanent pattern or discards. The session file records the decision for each candidate.

Output: Dream candidates file in grove. Awaits developer review.

$dream history — Review past distillation sessions


$dream history

Lists all dream session files with creation date, candidate count, and how many were promoted versus discarded. Use to understand how the pattern library has grown over time.

Output: Distillation session history. No state changes.

Context Mode

$context on — Enable narration overlay


$context on

Creates modes/context-mode.on flag. Every significant CocoPlus action includes a brief context header: what is happening, why, what to expect next. Adds token cost but no computation overhead. Recommended during learning phases.

$context off — Disable narration overlay


$context off

Removes modes/context-mode.on flag. Turn off when you're comfortable with the workflow.

Brainstorm Mode — CocoSpark

$cocoplus spark [topic] — Activate divergent thinking mode


$cocoplus spark
$cocoplus spark schema design approaches
$cocoplus spark cost optimization strategies

Activates brainstorm mode for a topic. Generates three to five distinct approaches, articulates trade-offs, identifies hidden assumptions, raises questions. All output marked explicitly as exploration. Written to .cocoplus/spark-[timestamp].md. Does not modify any lifecycle artifact.

Output: Exploration document. Never flows automatically into spec or plan.

$cocoplus spark-off — Exit brainstorm mode


$cocoplus spark-off

Deactivates CocoSpark. Offers option to capture insights into spec.md — developer decides what, if anything, to carry forward.

Plan Critique — SecondEye

$secondeye — Run three-model parallel plan critique


$secondeye

Default target: .cocoplus/lifecycle/plan.md. Spawns five SecondEye Critic subagents in parallel — Haiku (Efficiency Lens), Sonnet (Completeness Lens), Opus (Risk Lens), Sonnet (Devil's Advocate), Haiku (Edge Case Hunter). Each writes to a temporary staging file; results are aggregated into .cocoplus/lifecycle/secondeye-[timestamp].md. Staging files deleted after aggregation.

If Critical findings exist, a soft gate activates on the Build phase. This is always on-demand — never automatic.

Each finding in the aggregated report is tagged on two orthogonal dimensions:

The report header includes an action_summary YAML field with hitl_count, afk_count, blocking_count, minor_count, da_finding_count, and edge_case_count — giving the developer a complete decision burden assessment before reading the full findings.

Devil's Advocate section [Devil's Advocate]: The fourth critic's findings appear separately, sorted to the top of the report. All DA findings are BLOCKING by default. Concession from the DA requires the developer's rebuttal to score ≥4 on a 1–5 scale; a score of 3 or below means the DA re-asserts the concern and explains the insufficiency.

Edge Case Hunter section [Edge Case Hunter]: The fifth critic's findings appear in a separate section. It does not assess plan validity — it assesses evaluation coverage: what the evaluation plan would miss if implemented exactly as written. Findings are Advisory by default, escalated to BLOCKING only when the blind spot is fundamental to evaluation validity.

Individual findings within each section carry a six-severity label shared with CocoReview: blocking (must resolve before proceeding), important (should resolve; context-dependent), nit (minor style or preference), suggestion (optional improvement), learning (educational context without improvement intent), praise (explicitly highlight a well-constructed pattern — at least one required per review). These labels describe the nature of the finding; HITL/AFK and BLOCKING/MINOR describe the intervention required. A [Devil's Advocate] finding can carry a blocking severity label and be BLOCKING+HITL simultaneously — the labels operate on different axes.

Output: Aggregated critique report with findings classified as Critical, Advisory, or Observation, plus HITL/AFK and BLOCKING/MINOR tags, plus six-severity finding labels, plus [Devil's Advocate] and [Edge Case Hunter] sections.

$secondeye --artifact <target> — Critique a specific artifact


$secondeye --artifact spec
$secondeye --artifact review
$secondeye --artifact path/to/custom-file.md

Valid named targets: spec (→ lifecycle/spec.md), plan (→ lifecycle/plan.md), review (→ lifecycle/review.md). File paths reference arbitrary artifacts.

$secondeye --model <model> — Single-model critique


$secondeye --model haiku
$secondeye --model opus

Spawns one critic instead of three. No aggregation step. Report is a single-model critique. Soft gate logic still applies — Critical findings still block Build.

$secondeye acknowledge — Clear the Build soft gate


$secondeye acknowledge
$secondeye acknowledge --hitl-only
$secondeye acknowledge --blocking-only

Finds the most recent SecondEye report with critical_open: true and acknowledged: false. Presents Critical findings. On confirmation, updates report metadata with acknowledgment timestamp. Build phase soft gate is cleared.

--hitl-only — Acknowledges only HITL-classified findings (required before $cocoplus build proceeds); AFK findings are separately queued for autonomous resolution in the next build pass.

--blocking-only — Acknowledges only BLOCKING-classified findings; MINOR findings remain queued for autonomous resolution. Can be combined with --hitl-only to acknowledge the highest-priority finding category only.

$secondeye history — List all SecondEye reports


$secondeye history

Lists all reports in .cocoplus/lifecycle/ with finding counts by tier and acknowledgment status.

Output: Report index. No state changes.

Doc Engine

$doc run [target] — Generate documentation from code artifacts


$doc run
$doc run path/to/procedure.sql
$doc run ANALYTICS.CUSTOMER_SCHEMA

Reads source files or Snowflake object definitions and generates: column-level descriptions for tables and views, function and procedure docstrings, schema lineage notes, data dictionary entries. Does not overwrite existing documentation — proposes additions and updates for developer review.

Output: Documentation files co-located with source files or in project docs/ directory per project.md configuration.

Prompt Studio

$prompt new — Create a new Cortex AI prompt


$prompt new

Guided workflow: define task goal, select target model, collect optional few-shot examples, draft initial prompt, review for common anti-patterns (excessive hedging, ambiguous output format, missing context injection points). Produces a versioned prompt file with metadata.

Output: Versioned prompt file.

$prompt compare [prompt-a] [prompt-b] — Compare two prompt variants


$prompt compare prompts/v1.md prompts/v2.md

Runs both prompts against a provided or auto-generated sample dataset. Compares on: accuracy against expected results, output format compliance, verbosity, and token consumption. Produces a structured comparison report with a recommendation.

Output: Comparison report.

Multi-Process Orchestration — CocoFleet

CocoFleet spawns independent Coco CLI processes at the OS level. Requires coco to be available in PATH.

$fleet init [name] — Create a fleet manifest template


$fleet init data-platform

Creates .cocoplus/fleet/[name]-manifest.json as a template. Edit this file to define instances — each with task file path, persona, output directory, dependency IDs, and checkpoint file paths.

Output: Manifest template file.

$fleet run [manifest-path] — Execute a fleet


$fleet run .cocoplus/fleet/data-platform-manifest.json

Resolves dependency graph, creates instance directories, writes task files, spawns Coco processes in dependency order. Process IDs recorded in state file. Polls for completion by checking checkpoint file existence and process exit codes. When an instance completes, dependent instances are spawned.

Output: Fleet state file at .cocoplus/fleet/[fleet-id]-state.json.

$fleet status [fleet-id] — Live fleet execution status


$fleet status fleet-001

Reads state file and renders: all instances, their status, runtime duration, checkpoint states. Failed instances show their last log lines.

Output: Formatted status table. No state changes.

$fleet logs [instance-id] — Stream instance logs


$fleet logs instance-003

Reads .cocoplus/fleet/[instance-id]/output.log. If the instance is still running, tails the log.

Output: Log stream. No state changes.

$fleet stop [fleet-id] — Gracefully stop a running fleet


$fleet stop fleet-001

Sends SIGTERM to all running processes. Waits up to 10 seconds for graceful shutdown. Sends SIGKILL to any still-running processes. Updates state file to "stopped". Records which instances were stopped and their last checkpoint states.

Output: Stop confirmation with instance state summary.

Context Health — CocoHealth

CocoHealth monitors context utilization automatically via the PostToolUse hook. Its primary command, $pod checkpoint, is documented in the CocoPod section above. The monitoring behavior itself is automatic and requires no invocation.

CocoHealth fires advisory warnings at 60% context utilization and critical warnings with a structured recovery decision matrix at 70%. Thresholds are configurable in plugin.json under cocoHealth.warnThreshold and cocoHealth.criticalThreshold.

Function Knowledge Graph — CocoMap

$map — Build the Cortex function knowledge graph


$map

Triggers a parallel five-agent analysis: Function Scanner (discovers all Cortex AI functions), Dependency Mapper (traces call chains and shared infrastructure), Domain Analyzer (maps functions to business capabilities), Evaluation Mapper (discovers evaluation configurations and accuracy baselines), and Gap Detector (surfaces isolation risks and undocumented functions). Agents write to .cocoplus/map/intermediate/ without returning to orchestrator context. Results merge into .cocoplus/map/coco-map.json — committed as a team artifact.

Requires at least 2 Cortex AI functions in the project to generate a map.

Output: coco-map.json + summary: function count, dependency edges, identified gaps, capabilities detected.

$map diff — Impact analysis for staged changes


$map diff

Reads coco-map.json and staged git changes (via git diff --staged). For each modified function, traces all downstream dependents through the dependency graph. Reports: which downstream functions are affected, whether shared evaluation sets are touched, and whether any capability definitions change.

Output: Impact report. No state changes. Run before committing changes that touch shared functions.

$map explain <target> — Natural language explanation of a function or capability


$map explain customer_sentiment_classifier
$map explain ANALYTICS.CUSTOMER_EVENTS

Reads coco-map.json and produces a natural language explanation of the target: what it does in domain terms, direct and transitive dependents, what it depends on, nearest business capability, and analysis recency.

Output: Explanation narrative. No state changes.

Deferred Ideas — CocoSeed

$seed add "<idea>" --trigger "<condition>" — Capture a deferred idea with a trigger


$seed add "Add batch evaluation mode" --trigger "when evaluation accuracy baseline exceeds 90%"
$seed add "Refactor into shared UDF" --trigger "when CocoMap is committed"

Stores the idea in .cocoplus/seeds/ with a trigger condition, the active CocoBrew phase, and creation timestamp. The trigger is plain language: filesystem presence checks, phase completion checks, and mode flag checks are evaluated automatically; manual conditions are shown as pending manual confirmation.

Output: Confirmation with the stored trigger condition.

$seed list — Review all seeds and their trigger status


$seed list

Evaluates all trigger conditions against current project state. Output in two sections: "Ready to Promote" (triggered seeds, with the trigger that fired) and "Waiting" (pending seeds with current trigger evaluation).

Output: Two-section seed status report. No state changes.

$seed promote <id> — Move a triggered seed into the planning cycle


$seed promote seed-20260112-001

Writes the seed idea as a new item in lifecycle/spec.md under a "Backlog Items" section. Marks the seed file as status: promoted. Confirms: "Seed promoted to spec backlog. Run $spec to incorporate it into the next spec cycle."

Output: Updated spec.md + seed status update.

Decision Locking — CocoDiscuss

$discuss — Launch the pre-plan decision-capture dialogue


$discuss

Opens a structured multi-turn wizard tailored to the current spec.md. Asks focused implementation decision questions: model selection, evaluation methodology, accuracy threshold, warehouse assignment, production safety requirements, and explicit scope boundaries. Adapts to spec type — AI function builds get model and accuracy questions; Cortex Search configurations get indexing and latency questions. CocoContext organizational standards that definitively answer a question are applied automatically; those questions are skipped and their source is attributed.

All answers are written to lifecycle/discuss.md. When $cocoplus plan subsequently runs, the planning agent reads discuss.md as a constraint document and a plan-checker validation step flags any Pre-Approval Conflicts before plan approval.

After completing (or immediately after $spec if $discuss was not invoked), the CocoSpec quality gate evaluates specification completeness on five dimensions: Value, Scope, Acceptance, Boundaries, and Risk (0–2 points each, maximum 10, required ≥9). Scores below 9 hold the gate with an Uncertainty Declaration that names implicit assumptions explicitly.

When all three conditions hold — spec score ≥9, scope ≤3 files, no EHRB indicators — Quick Mode bypass is recommended: skip Plan phase and proceed directly to Build.

Output: lifecycle/discuss.md + CocoSpec score in lifecycle/spec-score.md.

Developer Engagement Observer — CocoWatch

CocoWatch is always on. It has no user-invocable commands. Its session summary surfaces automatically at $cocoplus ship and at FULL checkpoints. Consult it before shipping; there is nothing to invoke.

The summary shows the Engagement Zone (1 = over-delegation, 2 = healthy collaboration, 3 = under-utilization), Delegation Intensity (ratio of accepted-without-modification to total outputs), and Review Depth (engagement quality signals including timing and reasoning presence). Zone 1 sessions include a list of specific findings that received less than threshold engagement time, by filename and finding number.

CocoWatch signals are written to lifecycle/cocowatch-session.md — ephemeral, not committed, overwritten at each new session start. They are never used as input by any other feature.

Working Backwards Gate — CocoBloom

$bloom — Open the pre-commitment working backwards dialogue


$bloom

Runs a structured four-question dialogue before $spec begins. The four questions: who benefits and what changes for them? What is the core capability in one sentence? What are the three constraints that bound the solution? Write the press release paragraph — a one-paragraph announcement written as if the feature is already shipped. The developer writes the press release; the agent provides examples. Output is committed to lifecycle/bloom.md.

When $spec subsequently runs, it reads bloom.md as its first context. CocoDiscuss, when active, includes bloom.md in its pre-plan validation and surfaces a Concern (not a block) if the plan diverges from the original beneficiary or constraint set. At $cocoplus ship, CocoWatch notes whether the bloom commitment was met.

Output: lifecycle/bloom.md + git commit feat(bloom): pre-commitment working backwards document.

$bloom --skip — Waive the bloom requirement for this session


$bloom --skip

Writes "bloom_waived": true to lifecycle/meta.json. Suppresses the $spec advisory permanently for this session. Use when the scope is too small to warrant the dialogue or when the outcome is already clearly defined and documented elsewhere.

Output: Meta.json update + suppression confirmation.

$bloom crystallize — Preserve a completed build pattern as a reusable skill


$bloom crystallize

Available immediately after a successful CocoPod pipeline completion — specifically, when the last $cocoplus ship completed without any BLOCKED CocoSentinel or FAIL SecondEye verdict. Extracts the bloom commitment from lifecycle/bloom.md, the CocoDiscuss decision record from lifecycle/discuss.md (if present), and the execution pattern from flow.json, and writes a structured skill entry to the CocoGrove catalog. The skill carries the original intent from the bloom document alongside the implementation pattern — not just what was done, but why.

If invoked outside the post-ship window, the command explains that crystallization requires a recently completed and approved execution.

Crystallized skills may be promoted to parameterized CocoRecipe templates via $recipe from-skill <skill-slug> — converting hard-coded values to template variables.

Output: New skill file in .cocoplus/grove/patterns/ + grove catalog update.

Multi-Agent Roundtable — CocoKlatch

$klatch <topic> — Spawn a genuine multi-perspective subagent roundtable


$klatch "Should we use Cortex LLM Complete or fine-tuning for this classifier?"
$klatch "Architecture decision: single function vs. pipeline of functions"
$klatch --participants=5 "Evaluation methodology for this RAG system"

Prepares a structured topic brief from the free-text topic, then spawns N participant subagents simultaneously — each receives only the brief. Default is 3 participants (Skeptic, Optimist, Pragmatist). With 4: adds Domain Expert (always included at ≥ 3). With 5: adds Contrarian.

Each participant produces an independent analysis. When all complete, a synthesis subagent reads all outputs and produces a synthesis document covering: points of agreement (across ≥ 2 participants), points of divergence (each position stated), open questions (unresolved across all participants), and a recommended decision path with the primary remaining uncertainty named.

All artifacts are committed to git under lifecycle/klatch/: the brief, each participant's analysis, and the synthesis document.

--participants=N — Sets participant count (2–5). Minimum: Skeptic + Optimist. Maximum: all five roles.

Output: lifecycle/klatch/<timestamp>-<topic-slug>-synthesis.md surfaced in session + all participant files committed.

Context Distillation — CocoPull

$pull <target> — Distill a large artifact into a token-efficient form


$pull lifecycle/evaluation-results.md
$pull lifecycle/schema-analysis/
$pull lifecycle/stage-005-output.md

Runs a two-stage distillation. A structure analysis agent (Haiku) identifies the information architecture of the target: what sections exist, what type of content each contains, and which sections carry decision-relevant facts versus background context. A distillation agent (Sonnet) produces the pull file, preserving verbatim any decision-relevant values (thresholds, schema names, constraint values), compressing narrative explanations to their conclusions, deduplicating repeated content, and representing large tabular data as a representative sample with a statistical summary.

The pull file is written alongside the source as <source-name>.pull.md. Its header records the source path, distillation timestamp, original and distilled token count estimates, and compression ratio. Pull files are gitignored by default.

For a directory target, each eligible file is distilled independently and a manifest is produced.

Output: <source>.pull.md + compression ratio summary.

$pull --validate — Run a round-trip reconstruction test after distillation


$pull lifecycle/evaluation-results.md --validate

After producing the pull file, spawns a verification subagent that reads only the pull file and answers a set of probe questions generated from the source. Answers are compared against ground-truth answers drawn from the original by a separate agent. A pull file scoring below 85% match rate is flagged reliability: low in its header — CocoHarvest will not automatically use it as a stage input. Use --validate the first time you pull a new document type to assess whether the compression pattern is reliable for that type.

Output: Pull file + validation summary appended to pull file header with reliability classification.

$pull search "<query>" — Full-text search across session archives


$pull search "accuracy threshold evaluation"
$pull search "PII masking" --archetype build-intensive
$pull search "schema migration decision" --since 2026-01-01

Searches across all committed session artifacts — spec files, discuss records, review summaries, bloom documents, klatch syntheses — using the SQLite index maintained by the background wisdom-writer script. Results are ranked by relevance and display the artifact path, session date, session archetype, and a matched excerpt. Optional filters: --archetype <type> (spec-heavy, build-intensive, review-dominated, exploratory, maintenance), --since <date>, --gate <secondeye|sentinel|da_critic> (to filter for gate-related records only).

Use when you need to retrieve a prior decision, constraint, or evaluation methodology without knowing which session it lives in. Searching by decision is faster and more reliable than reading committed files sequentially.

Output: Ranked match list with excerpts and artifact paths.

Artifact Quality Gate — CocoSentinel

$sentinel [file] — Run a seven-dimension parallel quality evaluation on an artifact


$sentinel
$sentinel lifecycle/spec.md
$sentinel queries/sentiment_classifier.sql

Without a file argument, evaluates the most recently modified committed artifact. With a file argument, evaluates the specified file. Before spawning dimension sub-agents, runs sentinel-pregate.js (Dimension G — deterministic, <50ms): validates that the submission includes concrete execution evidence, non-trivial test coverage, no success claims without attached output, and no single-agent self-evaluation. If Dimension G fails, returns BLOCKED immediately — the seven dimension agents do not run.

If Dimension G passes, spawns seven dimension sub-agents simultaneously, each in an independent context window:

Each dimension produces a verdict (PASS / CONCERN (ADVISORY) / CONCERN (BLOCKING) / FAIL) with evidence citing the specific line or pattern, and a recommendation. The synthesis agent produces the overall outcome: APPROVED, CONDITIONAL, or BLOCKED.

Full report written to .cocoplus/sentinel/<artifact-sha>.json.

Output: Console summary with dimension verdicts + overall outcome + report path.

$sentinel --report — Display the most recent evaluation report


$sentinel --report
$sentinel --report queries/sentiment_classifier.sql

Reads the most recent sentinel report for the current directory or the specified file and renders it as a formatted summary with dimension verdicts, evidence lines, and recommendations.

Output: Formatted report. No state changes.

$sentinel --approve — Record a SHA-bound approval after resolving findings


$sentinel --approve
$sentinel --approve --rationale "CONCERN A2 accepted: internal function only"

After the developer resolves all BLOCKING concerns (or provides written rationale for accepting CONDITIONAL terms), writes an approval record to .cocoplus/sentinel/approvals.jsonl binding the approval to the artifact's SHA-256 hash. If the artifact is subsequently modified, the PostToolUse hook recomputes the SHA and voids the approval automatically — a warning is surfaced before the next lifecycle gate.

Output: Approval record committed to approvals.jsonl.

Institutional Rejection Memory — CocoWisdom

$wisdom — Show a summary of the project's quality rejection history


$wisdom

Displays a brief status: total rejection records, most frequent gate (secondeye / sentinel / da_critic), most blocked dimension, last rejection date, and a quality trend indicator (improving if recent sessions had fewer rejections than the project average).

Output: Status summary. No state changes.

$wisdom list — List rejection records with optional filters


$wisdom list
$wisdom list --gate secondeye
$wisdom list --since 2026-04-01
$wisdom list --dimension acceptance_criteria

Lists records with record ID, date, gate, dimension, and the first 80 characters of the rejection reason. Filters may be combined.

Output: Filtered record list.

$wisdom search "<pattern>" — Full-text search across rejection reasons


$wisdom search "acceptance criteria"
$wisdom search "PII masking"

Searches rejections.jsonl using the SQLite index maintained by the wisdom-writer script. Returns matching records with excerpts and record IDs.

Output: Ranked match list with excerpts.

$wisdom insights — Generate a structured quality pattern synthesis report


$wisdom insights

Invokes a Haiku sub-agent to read rejections.jsonl and produce a structured synthesis: most frequently blocked dimension, quality trend over time (improving/stable/degrading), dimension health table (total blocks, last 30 days, trend direction). Written to .cocoplus/wisdom/insights-<date>.md — committed to git as a project artifact.

Output: insights-<date>.md + git commit.

$wisdom export — Export all rejection records as a formatted Markdown report


$wisdom export

Generates a complete formatted Markdown report of all rejection records for retrospective review or external sharing. Does not modify the store.

Output: Formatted report. No state changes.

Structured Code Review — CocoReview

$cocoplus review — Run a structured holistic code review on the current change


$cocoplus review
$cocoplus review path/to/artifact.sql

Without a target, reviews the current staged git diff. With a target, reviews the specified file. Runs pr-complexity.js (deterministic) to compute a complexity score, size bucket, non-test ratio, schema layer diversity, estimated review time, and risk flags. If size bucket is XL (≥800 lines of change), surfaces a split recommendation before proceeding with the review.

Proceeds through four phases: Context Gathering (PR description, linked issue, CI status), High-Level Review (architecture and strategy — structural problems are surfaced here before line-by-line work), Line-by-Line Review (logic, security, performance, maintainability, reuse — with explicit reuse check before accepting new code), Summary and Verdict.

Applies nine universal anti-patterns before any language-specific guide: Parameter Sprawl, Leaky Abstractions, Stringly-Typed Code, Nested Conditionals, Copy-Paste Variants, No-Op Updates, TOCTOU Race Conditions (specifically flagging Snowflake IF EXISTS THEN INSERT patterns), Over-Broad Reads, Redundant State.

Finding labels: blocking · important · nit · suggestion · learning · praise (mandatory — at least one per review). Verdict: APPROVE / COMMENT / REQUEST_CHANGES.

Review output written to .cocoplus/review/cocoreview-<timestamp>.md — committed to git.

Output: Structured review report with findings and verdict.

$cocoplus review --complexity — Run only the PR complexity analysis


$cocoplus review --complexity
$cocoplus review --complexity path/to/diff.patch

Runs pr-complexity.js and returns the complexity score, size bucket, file count, non-test ratio, schema layer diversity, estimated review minutes, and risk flags. No LLM invoked.

Output: Complexity JSON + summary. Written to .cocoplus/review/complexity-cache.json (gitignored).

$cocoplus review --security — Run a security-focused review


$cocoplus review --security
$cocoplus review --security path/to/artifact.sql

Loads both the project's language guide and the security review guide before proceeding. Applies a five-tier security severity scale: Critical (blocks merge — immediate exploitation possible), High (blocks merge — significant vulnerability requiring specific conditions), Medium (should fix, can merge with tracking), Low (best-practice violation, non-blocking), Info (optional enhancement). In Snowflake deployments handling PII or regulated data, Critical triggers for hardcoded credentials, missing data masking policies on PII-classified columns, or unprotected references to regulated column sets.

Output: Review report with security-tier findings.

$cocoplus review --architecture — Run an architecture-focused review


$cocoplus review --architecture

Loads the architecture review guide and the universal quality guide. Evaluates SOLID principles, Clean Architecture layer separation, and dependency direction. Architectural problems found in Phase 2 (high-level review) are surfaced before line-by-line work begins.

Output: Review report with architecture-focused findings.

$cocoplus review --language <lang> — Override automatic language detection


$cocoplus review --language sql
$cocoplus review --language python
$cocoplus review --language javascript

Explicit language guide selection. Use when file extensions are ambiguous or when a non-standard extension is used.

Output: Review report with specified language guide applied.

Delivery Intelligence — CocoOps

$ops — Show a brief CocoOps status summary


$ops

Displays the most recently computed DORA metric values (from dora-snapshot.json if available), current sprint health summary (from sprint-health.json if available), and a time-aware suggestion for the current hour of day. If no snapshot exists, prompts to run $ops dora.

Output: Status summary. No state changes.

$ops dora — Compute and display full DORA metrics report


$ops dora

Runs dora-metrics.js (deterministic — no LLM) to compute four DORA-adapted metrics from Snowflake task execution history and git log: Pipeline Run Frequency, Data Availability Lead Time, Failure Recovery Time, and Data Quality Failure Rate. Each metric is classified against standard DORA tier thresholds (Elite / High / Medium / Low). A Haiku sub-agent then generates a narrative synthesis citing specific pipeline names, dates, and quantities — no vague generalities.

Report written to .cocoplus/ops/dora-snapshot.json and committed to git after each run.

Output: DORA report with tier classifications + notable signals + git commit.

$ops sprint — Compute current sprint health


$ops sprint

Reads git commits from the current sprint window (start date from cocoplus.toml [sprint] start_date) and computes story velocity (pipeline features completed), burndown (completed vs. remaining pipeline tasks), and a velocity-based completion projection. Written to .cocoplus/ops/sprint-health.json — committed to git.

Output: Sprint health summary + git commit.

$ops suggest — Show time-aware operational guidance


$ops suggest

Returns contextually appropriate actions based on the current time of day — morning pipeline status, mid-morning PR health, afternoon stale PR alerts, end-of-day velocity, Friday weekly summary. Time classification is determined by ops-suggest.js (deterministic, no LLM inference).

Output: Time-appropriate action list. No state changes.

$ops demo — Activate demo mode with realistic mock data


$ops demo

Populates .cocoplus/ops/demo/ with realistic mock Snowflake task history and git log data, enabling full CocoOps functionality without production access. Activates [demo] enabled = true in cocoplus.toml. Demo dataset includes representative failure patterns, a 30-day DORA metric improvement progression, and sprint timing data. Demo data is gitignored.

Output: Demo dataset written + cocoplus.toml updated.

$ops refresh — Re-query Snowflake for latest operational data


$ops refresh

Re-runs dora-metrics.js against current Snowflake task history and updates dora-snapshot.json. Useful for refreshing the metrics view after a long pipeline run completes without regenerating the full narrative report.

Output: Updated dora-snapshot.json + git commit.

Hooks (Automatic — Reference Only)

These hooks fire on Coco lifecycle events. They are documented here for understanding the system, not for manual invocation.

Hook Fires When What It Does
SessionStart Coco session begins Reads state, initializes CocoMeter, triggers inspector background scan if auto-mode active, evaluates CocoSeed trigger conditions and surfaces newly-ready seeds
SessionEnd Coco session ends Writes CocoMeter data, updates AGENTS.md with session summary, queues CocoCupper if needed, writes final CocoHealth checkpoint
PreToolUse Before any tool call Safety Gate — two layers: (1) unconditionally blocks SnowflakeSqlExecute during spec/plan phases regardless of safety mode; (2) blocks or warns on destructive SQL patterns from build phase onward per strict/normal setting
PostToolUse After any tool call Memory Engine capture layer — records significant tool use events to warm memory layer; CocoHealth samples context utilization and fires threshold warnings when applicable
UserPromptSubmit Developer submits a prompt Intercepts $<persona> shorthand for persona routing; intercepts `$cocoplus on off`
SubagentStop A subagent completes Validates checkpoints, updates flow.json stage status, triggers next stage if dependencies met
Stop Main session ends Final state capture
PreCompact Before context window compaction Flushes important state from context to warm memory layer before it's lost
Notification CocoPlus raises an event Routes notification to Coco UI or log file per notifications.json configuration

Quick Reference Card

Group Commands
Setup $pod init · $pod init --refresh-context · $pod status · $pod resume · $pod kb · $pod checkpoint · $cocoplus sync · $cocoplus migrate-config
Assist Mode $cocoplus on · $cocoplus off
Lifecycle $bloom · $bloom --skip · $bloom crystallize · `$spec [--quick\ --full] · $discuss · $cocoplus plan · $cocoplus build · $cocoplus test · $cocoplus review · $cocoplus ship · $rewind [--tag] · $fork`
Pipeline $flow run [--concurrency] · $flow status · $flow pause · $flow resume · $flow view
Recipes $recipe list · $recipe use · $recipe new · $recipe from-skill <slug>
Personas $de · $ae · $ds · $da · $bi · $dpm · $dst · $cdo · $personas
Memory $memory on · $memory off
Org Standards $context add · $context view · $context list
Inspector $cocoplus inspect · $inspector on · $inspector off
Safety $safety strict · $safety normal · $safety off
Quality $quality on · $quality off · $quality run
Meter $meter on · $meter off · $meter · $meter estimate · $meter history · $meter accuracy · $meter view · $meter sync
Cupper $cup · $cup history
Grove $patterns view · $patterns promote · $grove glossary · $grove glossary view
Dream $dream · $dream history
Context Mode $context on · $context off
Spark $cocoplus spark · $cocoplus spark-off
SecondEye $secondeye · $secondeye --artifact · $secondeye --model · $secondeye acknowledge [--hitl-only] [--blocking-only] · $secondeye history
Sentinel $sentinel [file] · $sentinel --report · $sentinel --approve
Wisdom $wisdom · $wisdom list [--gate] [--since] [--dimension] · $wisdom search "<pattern>" · $wisdom insights · $wisdom export
Code Review $cocoplus review · $cocoplus review --complexity · $cocoplus review --security · $cocoplus review --architecture · $cocoplus review --language <lang>
Ops $ops · $ops dora · $ops sprint · $ops suggest · $ops demo · $ops refresh
Klatch $klatch <topic> · $klatch --participants=N
Pull $pull <target> · $pull --validate · $pull search "<query>"
Docs $doc run
Prompts $prompt new · $prompt compare
Fleet $fleet init · $fleet run · $fleet status · $fleet logs · $fleet stop
Map $map · $map diff · $map explain <target>
Seeds $seed add "<idea>" --trigger "<condition>" · $seed list · $seed promote <id>
CocoWatch (automatic — summary at $cocoplus ship and FULL checkpoints)

A reference document is a map, not a destination. Use it to find the right path, then put it down and walk.