Your objective is to initialize the CocoPlus project bundle in the current working directory.
Pre-flight Check
- Check if
.cocoplus/already exists in the current directory.- If it does: output "CocoPlus is already initialized in this directory. Use
$pod statusto check current state or$pod resumeto restore context." Then stop.
- If it does: output "CocoPlus is already initialized in this directory. Use
- Check that a git repository exists using a shell-safe argument call equivalent to
git rev-parse --git-dir.- Prefer
spawnSync('git', ['rev-parse', '--git-dir'])or the host tool's native argument array. - Do not wrap this in PowerShell-specific parsing or string interpolation.
- If not: offer "Git not detected. Initialize? (yes/no)"
- If yes: run
git initand continue. - If no: stop.
- Prefer
Create Directory Structure
Create the following directories (create them even if empty — they are required by other skills):
.cocoplus/
.cocoplus/lifecycle/
.cocoplus/memory/
.cocoplus/prompts/
.cocoplus/monitors/
.cocoplus/brew/
.cocoplus/grove/
.cocoplus/grove/patterns/
.cocoplus/meter/
.cocoplus/snapshots/
.cocoplus/modes/
.cocoplus/config/
.cocoplus/fleet/
.cocoplus/pull/
.cocoplus/harvest/
.cocoplus/seeds/
.cocoplus/map/
.cocoplus/map/intermediate/
.cocoplus/map/archive/
.cocoplus/flow/
.cocoplus/flow/artifacts/
.cocoplus/flows/
.cocoplus/flows/templates/
.cocoplus/flows/templates/archive/
.cocoplus/proposals/
.cocoplus/proposals/archive/
.cocoplus/routines/
.cocoplus/session/
.cocoplus/personas/
.cocoplus/personas/archive/
.cocoplus/skills/
.cocoplus/cupper/
.cocoplus/recall/
.cocoplus/governance/
.cocoplus/sentinel/
Copy Template Files
Copy template files from the plugin templates directory to .cocoplus/:
-
Copy
templates/AGENTS.md.template→.cocoplus/AGENTS.md- Replace
{{TIMESTAMP}}with current ISO 8601 timestamp - Replace
{{SESSION_ID}}with a generated session ID (format:sess-YYYYMMDD-HHMMSS)
- Replace
-
Copy
templates/project.md.template→.cocoplus/project.md- Replace
{{TIMESTAMP}}with current ISO 8601 timestamp - Prompt the developer: "What is this project called?" Replace
{{PROJECT_NAME}}. - Prompt: "Briefly describe the project (one sentence):" Replace
{{PROJECT_DESCRIPTION}}. - Prompt: "What is the primary goal?" Replace
{{PROJECT_GOAL}}. - Replace
{{OWNER}}with git user name (git config user.name).
- Replace
-
Copy
templates/flow.json.template→.cocoplus/flow.json- Replace
{{TIMESTAMP}}with current ISO 8601 timestamp
- Replace
-
Copy
templates/notifications.json.template→.cocoplus/notifications.json -
Copy
templates/safety-config.json.template→.cocoplus/safety-config.json -
Copy
templates/cocoplus.toml.template→cocoplus.tomlat the project root- Replace the
[project]namefield with the collected project name - Leave empty Snowflake database/schema fields unless the developer provides them
- This file is committed and becomes the source of truth for operator-configurable settings
- Replace the
-
Copy
templates/monitors/narrator.monitor.json→.cocoplus/monitors/narrator.monitor.json -
Copy
templates/monitors/cost-tracker.monitor.json→.cocoplus/monitors/cost-tracker.monitor.json -
Copy
templates/monitors/quality-advisor.monitor.json→.cocoplus/monitors/quality-advisor.monitor.json -
Copy
templates/monitors/memory-capture.monitor.json→.cocoplus/monitors/memory-capture.monitor.json
Non-console feature behavior is implemented by V2-native skills; do not copy script files into .cocoplus/.
Initialize Mode Flags
Create the following empty flag files using the Write tool (cross-platform — do not use touch):
.cocoplus/modes/safety.normal— empty file (default safety mode).cocoplus/modes/memory.on— empty file (memory enabled by default)
Do NOT create other mode flags (inspector, context-mode, quality, cocometer, etc.) unless the developer enables them explicitly later.
Initialize Lifecycle Meta
Create .cocoplus/lifecycle/meta.json:
{
"current_phase": "not_started",
"phases_completed": [],
"created_at": "{{TIMESTAMP}}",
"flow_type": null,
"bloom_waived": false,
"phase_history": []
}
Create Constitutional Context
Create .cocoplus/lifecycle/cocoplus-context.md from the project answers:
# CocoPlus Project Context
## Project
[Project name and one-sentence description]
## Snowflake Stack
Unknown until captured by `$inspect` or project-specific context.
## Architectural Constraints
Use CocoPlus lifecycle artifacts as source of truth. Prefer deterministic scripts for classification and validation before agent reasoning.
## Security Requirements
Safety Gate defaults to normal. Production and PII-adjacent changes require explicit review.
Create Project Gitignore
Create .cocoplus/.gitignore to exclude transient runtime files from version control:
# Transient session data
state.json
meter/current-session.json
hook-errors.log
hook-log.jsonl
lifecycle/cocowatch-session.md
# Regenerable environment snapshots
snapshots/
# Fleet runtime logs
fleet/*/output.log
# SecondEye staging temp files
lifecycle/.secondeye-staging/
# Generated visualizations
flow-view.html
meter-view.html
# CocoScout session context files
scout-context-*.json
# Scratch and archive data
map/intermediate/
map/archive/
harvest/intermediate/
harvest/archive/
harvest/*-progress.txt
harvest/*-tasks.json
harvest/*-tasks.json.tmp
harvest/*-tasks.json.bak
# Pull artifacts are derived unless explicitly promoted
*.pull.md
# CocoContract working state (outcomes/ archive itself is committed)
contract-evidence.json
# CocoRefine learning-cycle queue
refine/pending.jsonl
# CocoRecall local session index (rebuilt via $recall import)
recall.db
# SecondEye shadow rule findings (do not affect verdict; regenerable)
secondeye/shadow-findings.json
# CocoCupper auto-captured corrections (silent capture, regenerable)
cupper/auto-captured.json
# CocoPivot machine-readable convergence state (FINDINGS.md itself is committed)
lifecycle/findings-state.json
pod-status.json
# CocoPlus 2.0 runtime queues and local indexes
v2-runtime-requests.jsonl
subagent-spawn-requests.jsonl
ui-notifications.jsonl
lifecycle/pilot-session.json
lifecycle/forge-state.json
lifecycle/forge-activity.jsonl
lifecycle/leviathan-state.json
lifecycle/consolidation-log.json
lifecycle/governance-log.json
lifecycle/retrospective-ledger.jsonl
brew/distribution-gate-*.json
session/PROGRESS.md
session/CONTEXT.md
session/task-queue.jsonl
session/stage-evidence.json
session/iteration-budget.json
session/budget-state.json
session/status.json
session/discoveries.jsonl
proposals/proposal-log.jsonl
routines/registry.json.tmp
sentinel/coach-requests.jsonl
sentinel/coach-requests.processed.jsonl
sentinel/known-gaps.jsonl
.last-consolidation
.last-retrospective
AGENT_STOP
STEER.md
# Execution plan templates are committed when promoted; archives are local by default
flows/templates/archive/
# Dynamic persona scratch state
personas/dynamic-registry.json.tmp
Create Root AGENTS.md Shim
Create AGENTS.md in the project root (not inside .cocoplus/). This thin shim tells Coco where to find the live session context:
# [Project Name] — CocoPlus Active
This project uses CocoPlus. Session state, active phase, and persona context
are maintained in `.cocoplus/AGENTS.md`.
<!-- cocoplus-agents-redirect: .cocoplus/AGENTS.md -->
Replace [Project Name] with the project name collected in the Copy Template Files step.
Initialize Persona and Subagent Registries
Create .cocoplus/personas.json with the default shorthand map:
{
"$de": "data-engineer",
"$ae": "analytics-engineer",
"$ds": "data-scientist",
"$da": "data-analyst",
"$bi": "bi-analyst",
"$dpm": "data-product-manager",
"$dst": "data-steward",
"$cdo": "chief-data-officer"
}
Create .cocoplus/subagents.json as an empty registry:
{}
Create .cocoplus/personas/dynamic-registry.json:
{
"version": 1,
"active": [],
"candidates": [],
"dissolved": []
}
Create .cocoplus/v2-runtime-requests.jsonl as an empty queue file. Hooks append V2 feature work requests here rather than invoking legacy scripts directly.
Create .cocoplus/.last-consolidation with the current epoch milliseconds so the CocoRecall Dream Cycle starts on the normal 24-hour cadence.
Create .cocoplus/.last-retrospective with the current epoch milliseconds so CocoRetro starts on the normal monthly cadence.
Create .cocoplus/session/PROGRESS.md:
# CocoSession Progress
## Done
## In Progress
## Next
## Notes
Create .cocoplus/session/CONTEXT.md with predicate state:
SESSION.status=initialized
SESSION.skill_surface_budget=standard
Create empty .cocoplus/session/task-queue.jsonl, .cocoplus/session/stage-evidence.json, .cocoplus/session/discoveries.jsonl, and .cocoplus/proposals/proposal-log.jsonl.
Create .cocoplus/session/iteration-budget.json:
{
"cap": 200,
"warn_at": 160,
"consumed": 0,
"warned": false,
"stopped": false
}
Create .cocoplus/session/budget-state.json:
{
"budget_limit": 0,
"reserve_fraction": 0.1,
"reserve_amount": 0,
"spent": 0,
"remaining": 0,
"budget_state": "normal",
"execution_cost": 0,
"coordination_cost": 0,
"landing_cost": 0,
"landing_incomplete": false
}
Create .cocoplus/session/status.json:
{
"status": "idle",
"updated_at": "{{TIMESTAMP}}"
}
Create .cocoplus/pod-state.json:
{
"status": "idle",
"updated_at": "{{TIMESTAMP}}"
}
Create .cocoplus/routines/registry.json:
{
"version": 1,
"routines": []
}
CocoAudit Setup (Feature 40)
Ask the developer:
Enable session audit trail? (recommended for regulated environments) [y/N]
If yes:
- Create
.cocoplus/modes/cocoaudit.on(empty file) - Create
.cocoplus/lifecycle/audit.mdwith the following header:
# CocoAudit — Session Audit Trail
**Project**: {{PROJECT_NAME}}
**Initialized**: {{TIMESTAMP}}
**Team**: {{OWNER}}
> This file is append-only. Records are verbatim developer inputs.
> Do not edit manually. This is a compliance artifact.
---
- Add
audit.mdnote to success output
If no: Skip silently. CocoAudit can be enabled later by creating modes/cocoaudit.on.
Validate Pod Scope Declarations (Feature 47 Enhancement)
If this project intends to register any pod for use in a CocoFlow parallel: step, check that pod's .agent.md frontmatter for an excludes: field. If a pod is registered for parallel use without one, warn:
⚠️ Pod "[name]" is registered for parallel execution but has no
excludes:field declared. Without an explicit exclusion boundary, this pod's scope cannot be validated by CocoPivot's scope anomaly detection, and it may produce overlapping findings with other pods running in the sameparallel:step. Add anexcludes:field to[path].agent.mdbefore using this pod in parallel workflows.
This check is advisory, not blocking — solo-pod workflows never require excludes:.
Create Initial Git Commit
Stage all new files and create commit:
git add .cocoplus/ AGENTS.md cocoplus.toml
git commit -m "chore(cocopod): initialize CocoPlus project structure"
Success Output
Output the following confirmation:
CocoPlus initialized successfully.
.cocoplus/
├── AGENTS.md ← hot context (auto-loaded each session)
├── .gitignore ← excludes transient runtime files
├── personas.json ← shorthand persona map ($de, $ae, etc.)
├── subagents.json ← active subagent registry
├── project.md ← project charter
├── flow.json ← pipeline definition (empty)
├── lifecycle/ ← phase artifacts (spec, plan, build, test, review, ship)
├── memory/ ← cross-session decisions and patterns
├── grove/ ← CocoGrove pattern library
├── meter/ ← CocoMeter token tracking
├── config/ ← generated config from cocoplus.toml sync
├── brew/ ← CocoBrew distribution quality gate reports
├── flow/artifacts/ ← named artifact protocol handoff files
├── flows/templates/ ← reusable execution plan templates
├── proposals/ ← retained CocoFlow stage proposals pending settlement
├── routines/ ← CocoRoutine registry
├── session/ ← CocoSession handoff, predicate state, evidence, and task queue
├── personas/ ← dynamic persona registry and history files
├── pull/ ← CocoPull manifest and distillation registry
├── harvest/ ← pipeline recovery scratch state
├── snapshots/ ← Environment Inspector results
└── modes/ ← feature flags (safety.normal active)
AGENTS.md ← project root shim → .cocoplus/AGENTS.md
cocoplus.toml ← committed plugin configuration source of truth
Next steps:
$spec — capture project requirements (start here)
$pod status — check project state at any time
$cocoplus on — activate all features at once
Anti-Rationalization
| Temptation | Why Not |
|---|---|
| Skip template copy, create files inline | Templates are the user's customization point — always copy from source |
| Initialize all mode flags | Modes are opt-in. Only safety.normal is default. |
| Skip git commit | Every pod init must create a commit for rollback traceability |
Exit Criteria
-
.cocoplus/directory exists with all required subdirectories (lifecycle/,memory/,prompts/,monitors/,brew/,grove/,grove/patterns/,meter/,snapshots/,modes/,config/,fleet/,pull/,harvest/,seeds/,map/,flow/artifacts/,routines/,sentinel/) -
.cocoplus/modes/safety.normalflag file exists; no other safety flags exist -
.cocoplus/modes/memory.onflag file exists -
.cocoplus/AGENTS.md,.cocoplus/project.md,.cocoplus/flow.json, and all four monitor JSON files exist -
.cocoplus/lifecycle/meta.jsonexists with"current_phase": "not_started"and emptyphases_completed -
.cocoplus/lifecycle/cocoplus-context.mdexists -
.cocoplus/.gitignoreexists excluding transient session files - Root
AGENTS.mdshim exists at project root withcocoplus-agents-redirectdirective - Root
cocoplus.tomlexists and includes the current 2.0 sections -
.cocoplus/personas.jsonexists with 8 default shorthand entries ($dethrough$cdo) -
.cocoplus/subagents.jsonexists as empty{} -
.cocoplus/personas/dynamic-registry.json,.cocoplus/flows/templates/,.cocoplus/proposals/,.cocoplus/session/,.cocoplus/session/iteration-budget.json,.cocoplus/session/budget-state.json,.cocoplus/session/status.json,.cocoplus/pod-state.json,.cocoplus/routines/registry.json,.cocoplus/v2-runtime-requests.jsonl,.cocoplus/.last-consolidation, and.cocoplus/.last-retrospectiveexist - Git commit with message
chore(cocopod): initialize CocoPlus project structureexists in log