SuperAPI AI Directory

pod-init

Coding & development

View repository

Updated 10-23 23:07

About this skill

Your objective is to initialize the CocoPlus project bundle in the current working directory.

Pre-flight Check

  1. Check if .cocoplus/ already exists in the current directory.
    • If it does: output "CocoPlus is already initialized in this directory. Use $pod status to check current state or $pod resume to restore context." Then stop.
  2. 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 init and continue.
    • If no: stop.

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/:

  1. 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)
  2. 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).
  3. Copy templates/flow.json.template → .cocoplus/flow.json

    • Replace {{TIMESTAMP}} with current ISO 8601 timestamp
  4. Copy templates/notifications.json.template → .cocoplus/notifications.json

  5. Copy templates/safety-config.json.template → .cocoplus/safety-config.json

  6. Copy templates/cocoplus.toml.template → cocoplus.toml at the project root

    • Replace the [project] name field 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
  7. Copy templates/monitors/narrator.monitor.json → .cocoplus/monitors/narrator.monitor.json

  8. Copy templates/monitors/cost-tracker.monitor.json → .cocoplus/monitors/cost-tracker.monitor.json

  9. Copy templates/monitors/quality-advisor.monitor.json → .cocoplus/monitors/quality-advisor.monitor.json

  10. 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:

  1. Create .cocoplus/modes/cocoaudit.on (empty file)
  2. Create .cocoplus/lifecycle/audit.md with 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.

---
  1. Add audit.md note 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 same parallel: step. Add an excludes: field to [path].agent.md before 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.normal flag file exists; no other safety flags exist
  • .cocoplus/modes/memory.on flag file exists
  • .cocoplus/AGENTS.md, .cocoplus/project.md, .cocoplus/flow.json, and all four monitor JSON files exist
  • .cocoplus/lifecycle/meta.json exists with "current_phase": "not_started" and empty phases_completed
  • .cocoplus/lifecycle/cocoplus-context.md exists
  • .cocoplus/.gitignore exists excluding transient session files
  • Root AGENTS.md shim exists at project root with cocoplus-agents-redirect directive
  • Root cocoplus.toml exists and includes the current 2.0 sections
  • .cocoplus/personas.json exists with 8 default shorthand entries ($de through $cdo)
  • .cocoplus/subagents.json exists 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-retrospective exist
  • Git commit with message chore(cocopod): initialize CocoPlus project structure exists in log