codebyplan 1.5.1 → 1.8.0

package/templates/rules/todo-backend.md

@@ -0,0 +1,109 @@
+---
+scope: org-shared
+paths:
+  - "apps/todo-worker/**"
+  - "apps/web/src/lib/mcp/**"
+  - "supabase/migrations/*todos*"
+  - "supabase/migrations/*worktrees*"
+---
+
+# Todo backend — queue contract, invariants, and writer obligations
+
+The todos queue is materialised by `apps/todo-worker` (CHK-122) and consumed by `/cbp-todo` + `mcp__codebyplan__get_next_action`. This rule documents what every contributor to the MCP write tools, the worker, or the SQL schema must respect.
+
+## 1. Six workflow invariants — DB-layer guards, never bypassable
+
+Defined in `supabase/migrations/20260511211900_chk111_workflow_invariants.sql`. These are `BEFORE UPDATE` triggers — they refuse invalid state transitions and produce structured `RAISE EXCEPTION` errors with `HINT` pointing at the offending row. **Do NOT port these to TS.** The DB layer is the bypass-proof contract.
+
+| # | Trigger | What it enforces |
+|---|---------|------------------|
+| 1 | `trg_enforce_checkpoint_activation_worktree` | A checkpoint cannot be activated without `worktree_id` set |
+| 2 | `enforce_standalone_task_worktree` (via task workflow) | A standalone task cannot be moved to `in_progress` without `assigned_worktree_id` |
+| 3 | `trg_enforce_task_workflow_invariants` | ≤ 1 `in_progress` task per checkpoint |
+| 4 | `trg_enforce_single_in_progress_round_per_task` | ≤ 1 `in_progress` round per task |
+| 5 | `trg_enforce_single_active_scope_per_worktree` | ≤ 1 active (checkpoint OR standalone task) per worktree |
+| 6 | `trg_enforce_standalone_task_scope_per_worktree` | ≤ 1 `in_progress` standalone task per worktree |
+
+The worker is a passive cross-checker (`apps/todo-worker/src/invariants/check.ts`) — if its check disagrees with the DB, the DB wins.
+
+## 2. Queue contract — todos_jobs lifecycle
+
+`todos_jobs` is the work queue drained by the worker.
+
+```
+MCP write → enqueueTodoJob → todos_jobs (status='pending')
+                                  ↓
+            worker claim_todos_job (SELECT … FOR UPDATE SKIP LOCKED)
+                                  ↓
+              computeTodos(repo, worktree, user) → desired rows
+                                  ↓
+            apply_todos RPC → todos table (status='current' / 'pending')
+                                  ↓
+                       todos_jobs.status='completed'
+```
+
+`status` enum: `pending → in_progress → completed | failed`. `failed` rows retry up to 3 attempts via the heartbeat cron.
+
+## 3. Priority sort_order bands
+
+The worker emits todos with these `sort_order` ranges. Lower = surfaces first in `get_next_action`.
+
+| Band | sort_order | State |
+|------|-----------|-------|
+| Active round | 10–19 | Checkpoint active, task in_progress, round in_progress |
+| Active task pending round | 20–29 | Checkpoint active, task in_progress, no round yet |
+| Pending task in active checkpoint | 30–39 | Checkpoint active, lowest-numbered pending task |
+| Pending checkpoint | 40–49 | No active checkpoint, lowest-numbered pending |
+| Standalone task | 60–69 | No checkpoint context, in_progress / pending standalone |
+| Repo-sync prompt | 90–99 | `repos.needs_refresh = true` |
+
+## 4. Command + args mapping
+
+`get_next_action` returns one row mapping to one of these slash commands. The worker stamps `command` + `metadata.context` based on workflow state:
+
+| State | Command | Required context |
+|-------|---------|------------------|
+| Round in progress | `/cbp-round-update` | `{checkpoint_id, task_id, round_id}` |
+| Round pending start | `/cbp-round-start` | `{checkpoint_id, task_id}` |
+| Task pending start | `/cbp-task-start` | `{checkpoint_id, task_id}` or `{task_id}` for standalone |
+| Checkpoint pending activation | `/cbp-checkpoint-update` | `{checkpoint_id}` |
+| Checkpoint done | `/cbp-checkpoint-check` | `{checkpoint_id}` |
+| Repo needs sync | `npx codebyplan tech-stack` | `{repo_id}` |
+
+## 5. Heartbeat policy
+
+The worker's `node-cron` heartbeat runs at `0 0 * * *` (UTC midnight). It enumerates every `(repo, worktree, user)` tuple with an active checkpoint OR in-progress standalone task and enqueues a `HEARTBEAT_SWEEP` todos_jobs row for each. This catches drift from missed `enqueueTodoJob` calls in MCP writers.
+
+Backoff: a failed job retries at `now + 2^attempts minutes` (cap 60min). After 3 attempts, the job stays `failed` and the heartbeat picks it up again at the next sweep.
+
+## 6. Writer obligations — every MCP write enqueues
+
+`apps/web/src/lib/mcp/enqueueTodoJob.ts` exposes:
+
+```ts
+enqueueTodoJob(client, { repoId, worktreeId, userId, reason }): Promise<void>
+```
+
+Every workflow mutator in `apps/web/src/lib/mcp/tools/write.ts` MUST call this after the mutation succeeds. The 11 writers as of CHK-122:
+
+`create_checkpoint, update_checkpoint, complete_checkpoint, create_task, update_task, complete_task, add_round, update_round, complete_round, create_session_log, update_session_log`
+
+Plus the 2 dedicated enqueue tools: `enqueue_todo_job`, `bind_worktree_user`.
+
+**Contract**: best-effort. The helper logs and swallows failures — the heartbeat catches anything that slips through. Atomic in-txn enqueue is NOT supported (supabase-js limitation); the worker's bounded staleness (next heartbeat ≤ 24h) is the safety net.
+
+## 7. Cutover history
+
+CHK-111 shipped the original todos queue as Postgres triggers + a 583-LOC `regenerate_todos_for_repo` PL/pgSQL function. CHK-122 ported the regen to `apps/todo-worker` (Node) for shared infrastructure with `apps/docs-ingest` (CHK-116), easier testing, and per-user fanout. The 10 `trg_*_todos` triggers and the 4 `wrap_*` wrappers were dropped in migration `20260521000000_chk122_drop_legacy_todos_regen.sql`. The 6 BEFORE-UPDATE invariant triggers stayed.
+
+## 8. Deployment — Railway
+
+`apps/todo-worker` runs as a Railway service alongside `apps/backend`. Setup:
+
+1. Dashboard → New service → Connect GitHub → pick this repo.
+2. Build command: `pnpm install && pnpm --filter @codebyplan/todo-worker build`
+3. Start command: `node apps/todo-worker/dist/main.js`
+4. Env vars (from `apps/todo-worker/.env.example`): `SUPABASE_URL`, `SUPABASE_SECRET_KEY` (an `sb_secret_...` key), `LOG_LEVEL`, `WORKER_POLL_MS`.
+5. Save the resulting `project_ref` to `.codebyplan.json` `shipment.surfaces.railway-todo-worker.project_ref`.
+
+Smoke after deploy: run `/cbp-task-complete` in any worktree → tail Railway logs → expect a `claim → apply` cycle within `WORKER_POLL_MS`.

package/templates/settings.project.base.json

@@ -0,0 +1,55 @@
+{
+  "alwaysThinkingEnabled": true,
+  "autoUpdatesChannel": "latest",
+  "awaySummaryEnabled": true,
+  "disableAgentView": false,
+  "disableRemoteControl": false,
+  "editorMode": "normal",
+  "outputStyle": "default",
+  "preferredNotifChannel": "notifications_disabled",
+  "prefersReducedMotion": false,
+  "respectGitignore": true,
+  "showTurnDuration": true,
+  "spinnerTipsEnabled": true,
+  "terminalProgressBarEnabled": true,
+  "viewMode": "default",
+  "worktree": { "baseRef": "fresh" },
+  "autoScrollEnabled": true,
+  "cleanupPeriodDays": 30,
+  "includeGitInstructions": true,
+  "showThinkingSummaries": true,
+  "disableSkillShellExecution": false,
+  "skipWebFetchPreflight": false,
+  "fastModePerSessionOptIn": false,
+  "effortLevel": "xhigh",
+  "statusLine": {
+    "type": "command",
+    "command": "bash ./.claude/hooks/cbp-statusline.sh"
+  },
+  "subagentStatusLine": {
+    "type": "command",
+    "command": "bash ./.claude/hooks/cbp-subagent-statusline.sh"
+  },
+  "permissions": {
+    "defaultMode": "bypassPermissions",
+    "deny": ["Bash(rm -rf /:*)", "Bash(rm -rf ~:*)", "Bash(rm -rf /*:*)"],
+    "ask": [
+      "Bash(git reset:*)",
+      "Bash(git clean:*)",
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git checkout -- :*)",
+      "Bash(git add .:*)",
+      "Bash(git add -A:*)",
+      "Bash(rm -rf:*)",
+      "Bash(pnpm add:*)",
+      "Bash(pnpm install:*)",
+      "Bash(npm install:*)",
+      "Bash(npm i:*)",
+      "Bash(npx add:*)"
+    ]
+  },
+  "attribution": { "commit": "", "pr": "" },
+  "showClearContextOnPlanAccept": false,
+  "syntaxHighlightingDisabled": false
+}

package/templates/settings.user.base.json

@@ -0,0 +1,25 @@
+{
+  "alwaysThinkingEnabled": true,
+  "autoUpdatesChannel": "latest",
+  "awaySummaryEnabled": true,
+  "disableAgentView": false,
+  "disableRemoteControl": false,
+  "editorMode": "normal",
+  "outputStyle": "default",
+  "preferredNotifChannel": "notifications_disabled",
+  "prefersReducedMotion": false,
+  "respectGitignore": true,
+  "showTurnDuration": true,
+  "spinnerTipsEnabled": true,
+  "terminalProgressBarEnabled": true,
+  "viewMode": "default",
+  "worktree": { "baseRef": "fresh" },
+  "autoScrollEnabled": true,
+  "cleanupPeriodDays": 30,
+  "includeGitInstructions": true,
+  "showThinkingSummaries": true,
+  "disableSkillShellExecution": false,
+  "skipWebFetchPreflight": false,
+  "fastModePerSessionOptIn": false,
+  "permissions": { "skipDangerousModePermissionPrompt": true }
+}

package/templates/skills/cbp-build-cc-agent/SKILL.md

@@ -0,0 +1,139 @@
+---
+scope: org-shared
+name: cbp-build-cc-agent
+description: Build a Claude Code subagent at .claude/agents/{name}/AGENT.md (CBP folder form) following the official sub-agents spec (frontmatter, tools, model, memory, hooks, skills preload, permission modes, isolation).
+argument-hint: "[agent-name] [--scope=project|user] [--memory=project|user|local] [--isolation=worktree]"
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(chmod *)
+effort: xhigh
+---
+
+# Build Claude Code Subagent
+
+Create a Claude Code subagent following the official Claude Code sub-agents spec. Supports every frontmatter field the runtime recognises.
+
+**CBP authoring quality** (Work-Executor vs Utility split, I/O contracts, signal density, anti-patterns, failure modes): read [reference/cbp-quality.md](reference/cbp-quality.md) before writing.
+
+## Arguments
+
+`$ARGUMENTS` — agent name (kebab-case, required). Flags: `--scope=project|user` (default `project`), `--memory=project|user|local`, `--isolation=worktree`.
+
+## When to Use
+
+- Recurring task that matches an existing worker pattern
+- Work produces verbose output you want kept out of the main conversation
+- Task has a tight tool-access or permission boundary
+- Seen the same side-task pattern 3+ times
+
+Do **not** create a subagent for one-off work — spawn `general-purpose` inline instead.
+
+## Instructions
+
+### Step 1 — Validate inputs
+
+- Name must be lowercase kebab-case (a–z, 0–9, hyphens only)
+- Reject collisions with built-in agents: `Explore`, `Plan`, `general-purpose`, `statusline-setup`, `Claude Code Guide`
+- Reject if `.claude/agents/{name}/AGENT.md` already exists unless the user asked to update
+
+### Step 2 — Pick scope
+
+CBP uses the **folder form** so an agent can bundle supporting docs/scripts next to `AGENT.md`.
+
+| Scope   | Path                               | Use when                                |
+| ------- | ---------------------------------- | --------------------------------------- |
+| project | `.claude/agents/{name}/AGENT.md`   | Repo-specific, shared with team via git |
+| user    | `~/.claude/agents/{name}/AGENT.md` | Personal, reused across all projects    |
+
+Default: `project`. Pass `--scope=user` to override. Flat form (`.claude/agents/{name}.md`) is the Claude Code native layout but CBP's structure hook expects the folder form — always use that in this repo.
+
+### Step 3 — Read the template and CBP context
+
+Read `${CLAUDE_SKILL_DIR}/templates/agent.md` for the canonical frontmatter set. Fill only fields that matter for the agent; leave the rest out (every field except `name` and `description` is optional).
+
+CBP adds a required `scope:` frontmatter marker (structural classification; not read by Claude Code). Values: `org-shared` | `project-shared` | `repo-only:<repo-name>`. Length hook warns at 400 lines, blocks at 800. Quality details in [reference/cbp-quality.md](reference/cbp-quality.md).
+
+### Step 4 — Gather required fields
+
+Ask the user only for what cannot be inferred from context:
+
+| Field                       | Source                                                                                                                                                                                                                                                                                                                               |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `name`                      | Argument                                                                                                                                                                                                                                                                                                                             |
+| `description`               | User — must describe _when_ Claude should delegate, not what the agent is                                                                                                                                                                                                                                                            |
+| `tools` / `disallowedTools` | Derive from the workflow. Prefer narrow allowlists for read-only agents                                                                                                                                                                                                                                                              |
+| `model`                     | Pinned ID (e.g. `sonnet`) for version-locked reasoning, or alias (`sonnet` / `opus` / `haiku`) for explicit lowering exceptions. `inherit` is NOT permitted in plugin authoring — every agent states its model explicitly. Default for plugin agents is `sonnet`; see [/cbp-build-cc-mode](../build-cc-mode/SKILL.md) for the matrix |
+| `effort`                    | `xhigh` by default for plugin agents; lower (`high` / `medium` / `low`) only as a documented exception in the build-cc-mode matrix. Always set explicitly — no commented-out placeholders                                                                                                                                            |
+| `permissionMode`            | `default` unless the agent must run autonomously                                                                                                                                                                                                                                                                                     |
+
+### Step 5 — Consider optional capabilities
+
+Check each against the task and include only when they add value:
+
+| Capability           | Field                                                           | When to include                                        |
+| -------------------- | --------------------------------------------------------------- | ------------------------------------------------------ |
+| Persistent memory    | `memory: project\|user\|local`                                  | Agent should accumulate learnings across conversations |
+| Preloaded skills     | `skills: [skill-a, skill-b]`                                    | Domain knowledge the agent needs every run             |
+| Scoped MCP servers   | `mcpServers: [...]`                                             | Tools the parent session shouldn't have in context     |
+| Lifecycle hooks      | `hooks: { PreToolUse: [...], PostToolUse: [...], Stop: [...] }` | Need to validate tool calls or trigger side-effects    |
+| Worktree isolation   | `isolation: worktree`                                           | Agent should mutate an isolated copy of the repo       |
+| Background execution | `background: true`                                              | Agent should always run concurrently                   |
+| Bounded turns        | `maxTurns: N`                                                   | Cap runaway loops                                      |
+| Subagent spawning    | `tools: Agent(worker, researcher)`                              | Only if run as main thread via `--agent`               |
+
+Cross-references for complex cases:
+
+- Frontmatter table: [reference/frontmatter-fields.md](reference/frontmatter-fields.md)
+- Permission modes: [reference/permission-modes.md](reference/permission-modes.md)
+- Hook patterns: [examples/with-hooks.md](examples/with-hooks.md)
+- Preloaded skills pattern: [examples/with-skills-preload.md](examples/with-skills-preload.md)
+- Read-only agent pattern: [examples/read-only-reviewer.md](examples/read-only-reviewer.md)
+
+### Step 6 — Write the agent file
+
+1. Create directory: `mkdir -p {scope-path}/{name}`
+2. Write `{scope-path}/{name}/AGENT.md`
+3. Copy the template, fill frontmatter, then write the system prompt as the markdown body. The body becomes the agent's entire system prompt — no CLAUDE.md prefix, no Claude Code defaults.
+
+System prompt guidance:
+
+- Open with a one-line role ("You are a ...")
+- Numbered workflow the agent follows when invoked
+- Output format it must return
+- Failure modes (when to return `blocked`, `failed`, `no_findings`)
+
+Supporting files (optional) live next to `AGENT.md` in the same folder: `{name}/context.md`, `{name}/examples/`, etc.
+
+### Step 7 — Validate
+
+Run the validator:
+
+```bash
+bash "${CLAUDE_SKILL_DIR}/scripts/validate-agent.sh" "{scope-path}/{name}/AGENT.md"
+```
+
+It checks: name format, frontmatter parses, required fields present (`name`, `description`, `scope`), tool names are valid, model alias is recognised.
+
+### Step 8 — Surface to the user
+
+Report:
+
+- Path written
+- Frontmatter fields used (and which optional ones were skipped and why)
+- How to invoke: `@agent-{name}`, natural language, or `claude --agent {name}`
+- Note that manual edits require `/agents` reload or a session restart (per spec)
+- Commit the new agent file to git so it propagates to other team members
+
+## Integration
+
+- **Triggered by**: user invocation
+- **Reads**: `${CLAUDE_SKILL_DIR}/templates/agent.md`, `${CLAUDE_SKILL_DIR}/reference/*.md` (including `cbp-quality.md`)
+- **Writes**: `.claude/agents/{name}/AGENT.md` or `~/.claude/agents/{name}/AGENT.md`
+- **Related skills**: `/cbp-build-cc-skill` (skill-level workflows), `/cbp-build-cc-settings` (session-level `SubagentStart`/`SubagentStop` hooks), `/cbp-build-cc-mode` (canonical model/effort matrix — audit or apply)
+
+## Key Rules
+
+- `description` is what Claude reads to decide whether to delegate. Write it for matching, not for humans
+- Subagents cannot spawn other subagents — the `Agent` tool only applies when the agent runs as the main thread
+- `bypassPermissions` and `acceptEdits` inherited from the parent cannot be weakened by the child
+- Preloaded skills inject _full content_ at startup — don't preload `disable-model-invocation: true` skills
+- Restart the session or use `/agents` to load a newly written agent file
+- CBP folder form is required — the structure hook blocks flat agent files in this repo

package/templates/skills/cbp-build-cc-agent/examples/read-only-reviewer.md

@@ -0,0 +1,32 @@
+---
+name: code-reviewer
+description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+effort: xhigh
+color: blue
+---
+
+You are a senior code reviewer ensuring high standards of code quality and security.
+
+When invoked:
+1. Run `git diff` to see recent changes
+2. Focus on modified files
+3. Begin review immediately
+
+Review checklist:
+- Code is clear and readable
+- Functions and variables are well-named
+- No duplicated code
+- Proper error handling
+- No exposed secrets or API keys
+- Input validation implemented
+- Good test coverage
+- Performance considerations addressed
+
+Provide feedback organized by priority:
+- Critical issues (must fix)
+- Warnings (should fix)
+- Suggestions (consider improving)
+
+Include specific examples of how to fix issues.

package/templates/skills/cbp-build-cc-agent/examples/with-hooks.md

@@ -0,0 +1,41 @@
+---
+name: db-reader
+description: Execute read-only database queries. Use when analyzing data or generating reports.
+tools: Bash
+model: sonnet
+effort: xhigh
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-readonly-query.sh"
+---
+
+You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.
+
+When asked to analyze data:
+1. Identify which tables contain the relevant data
+2. Write efficient SELECT queries with appropriate filters
+3. Present results clearly with context
+
+You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.
+
+---
+
+**Companion script — `./scripts/validate-readonly-query.sh`:**
+
+```bash
+#!/bin/bash
+# Exit 2 blocks the tool call and feeds stderr back to Claude.
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+[ -z "$COMMAND" ] && exit 0
+if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
+  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
+  exit 2
+fi
+exit 0
+```
+
+Make it executable: `chmod +x ./scripts/validate-readonly-query.sh`

package/templates/skills/cbp-build-cc-agent/examples/with-skills-preload.md

@@ -0,0 +1,25 @@
+---
+name: api-developer
+description: Implement API endpoints following team conventions. Use when adding, modifying, or reviewing HTTP handlers.
+tools: Read, Write, Edit, Grep, Glob, Bash
+model: sonnet
+effort: xhigh
+memory: project
+skills:
+  - api-conventions
+  - error-handling-patterns
+---
+
+You are an API developer. Follow the conventions and patterns preloaded via the `skills` field — they define the project's RESTful naming, error format, and validation rules.
+
+When invoked:
+1. Read `MEMORY.md` to recall past learnings on this codebase
+2. Locate the handler directory (`src/api/handlers/`)
+3. Implement the endpoint per the preloaded conventions
+4. Write or update tests in the matching `*.test.ts` file
+5. Append one-line learnings to `MEMORY.md` when you discover a pattern worth remembering
+
+Return:
+- Files created/modified
+- Test coverage summary
+- Any deviation from conventions and why

package/templates/skills/cbp-build-cc-agent/reference/cbp-quality.md

@@ -0,0 +1,153 @@
+---
+scope: org-shared
+---
+
+# Agent Authoring Quality
+
+Quality expectations and structure for `/.claude/agents/{name}/AGENT.md` files. This file adds CBP-specific constraints on top of the official Claude Code sub-agents spec.
+
+## CBP Folder Form
+
+CBP uses the folder form `.claude/agents/{name}/AGENT.md`, not Claude Code's native flat `.claude/agents/{name}.md`. The structure hook enforces this. Folder form lets an agent bundle supporting files (context, examples, scripts) next to `AGENT.md`.
+
+## Required CBP Frontmatter
+
+Every agent MUST have `scope:` in addition to the Claude Code native fields:
+
+```yaml
+---
+scope: org-shared # structural marker: org-shared | project-shared | repo-only:<repo-name>
+name: agent-name
+description: One sentence — used for matching. Be specific.
+tools: Read, Write, Edit, Glob, Grep, Bash
+effort: high
+---
+```
+
+`scope:` is a CBP structural marker — not read by Claude Code itself. Missing `scope:` fails validation (`validate-agent.sh` / `validate-structure-scope.sh`).
+
+## Agent Types
+
+| Type              | Phases                  | Thinking Sections       | Self-Improvement       | Max Lines |
+| ----------------- | ----------------------- | ----------------------- | ---------------------- | --------- |
+| **Work Executor** | Freeform work           | Yes (mandatory)         | Yes (mandatory)        | 400       |
+| **Utility**       | Defined phases/workflow | No (embedded in phases) | No (returns to caller) | 400       |
+
+Work Executors do arbitrary work — they need structured thinking to avoid errors.
+Utility agents have defined phases — thinking is embedded in their workflow.
+
+## Required Sections
+
+Every agent MUST have these sections:
+
+| Section                  | Purpose                                     | Skip When      |
+| ------------------------ | ------------------------------------------- | -------------- |
+| **Frontmatter**          | name, description, tools, effort            | Never          |
+| **Purpose**              | Why this agent exists, what it replaces     | Never          |
+| **Input Contract**       | YAML schema of what the agent receives      | Never          |
+| **Output Contract**      | YAML schema of what the agent returns       | Never          |
+| **Workflow**             | Numbered phases with clear steps            | Never          |
+| **Completion Criteria**  | When the agent is done                      | Never          |
+| **Failure Modes**        | What to do when blocked/failed              | Never          |
+| **Integration**          | Spawned by, returns to, input from          | Never          |
+| Thinking Requirements    | Problem understanding, source check, design | Utility agents |
+| Self-Improvement Capture | Rules/architecture/command gaps found       | Utility agents |
+
+## Frontmatter
+
+```yaml
+---
+name: agent-name
+description: One sentence — used for agent matching. Be specific.
+tools: Read, Write, Edit, Glob, Grep, Bash
+effort: high
+---
+```
+
+- `tools:` — only list tools the agent actually needs. Don't give Write/Edit to read-only agents.
+- `effort:` — `high` for agents that do complex multi-step work
+
+## Quality Expectations
+
+### Signal Density
+
+Every line must drive behavior. Test each line: "If I remove this, will the agent make a mistake?" If no, cut it.
+
+| Bad                                 | Good                                   |
+| ----------------------------------- | -------------------------------------- |
+| "Make sure to carefully analyze..." | (just write the analysis steps)        |
+| "IMPORTANT: Always check..."        | (put it in the workflow as a step)     |
+| "Note: This is critical..."         | (make it a phase gate or failure mode) |
+
+### Concrete Steps Over Vague Guidance
+
+| Bad                                | Good                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------- |
+| "Analyze the codebase thoroughly"  | "Glob `src/**/*.ts`, read files matching the pattern"                     |
+| "Fix any issues found"             | "For each lint error: read the file, apply the fix, add to fixes_applied" |
+| "When uncertain, apply fix anyway" | "When uncertain about create vs update, update the existing file"         |
+
+### Input/Output Contracts Must Be Precise
+
+Contracts define how agents communicate. Vague contracts produce vague work.
+
+```yaml
+# Bad — what does "context" mean?
+input:
+  context: object
+
+# Good — every field named and typed
+input:
+  checkpoint_goal: string
+  round_requirements: string
+  has_ui_work: boolean
+```
+
+### Merge-First for Infrastructure Changes
+
+Agents that modify `.claude/` files MUST:
+
+1. Inventory existing files in the target category before creating new ones
+2. Update existing files when topic overlap > 50%
+3. Document `checked_existing` in output when creating new files
+
+## Anti-Patterns
+
+| Pattern                                               | Problem                               | Fix                                                  |
+| ----------------------------------------------------- | ------------------------------------- | ---------------------------------------------------- |
+| Emphasis markers as fixes ("IMPORTANT:", "REQUIRED:") | Structural problem masked by shouting | Inline the content or split the agent                |
+| "Full autonomy to create anything"                    | Creates file sprawl                   | Constrain to update-first, create-with-justification |
+| Recursive self-spawning > 3 levels                    | Infinite loops, context exhaustion    | Hard cap with fallback to caller                     |
+| Agent has 10+ phases                                  | Too many responsibilities             | Split into orchestrator + specialists                |
+| Duplicate logic across agents                         | Drift, inconsistency                  | Extract to context file, both agents read it         |
+
+## When to Create vs Update an Agent
+
+| Situation                                | Action                                          |
+| ---------------------------------------- | ----------------------------------------------- |
+| Existing agent covers the domain         | Update its AGENT.md                             |
+| New domain, no existing agent covers it  | Create new agent                                |
+| Existing agent is too large (>400 lines) | Split into orchestrator + specialist            |
+| One-off task, not recurring              | Don't create an agent — use inline instructions |
+
+## Integration Section Format
+
+```markdown
+## Integration
+
+- **Spawned by**: [skill or command that spawns this agent]
+- **Returns to**: [what processes the output]
+- **Input from**: [where data comes from]
+- **Saves to**: [where results are stored]
+```
+
+## Failure Mode Defaults
+
+Every agent should handle at minimum:
+
+| Condition            | Action                                    |
+| -------------------- | ----------------------------------------- |
+| Requirements unclear | Return `blocked`, describe what's missing |
+| Dependency missing   | Return `blocked`, note what's needed      |
+| Unrecoverable error  | Return `failed`, describe error           |
+| No actionable work   | Return `skipped` or `no_findings`         |

package/templates/skills/cbp-build-cc-agent/reference/frontmatter-fields.md

@@ -0,0 +1,37 @@
+# Subagent Frontmatter Reference
+
+Source: official Claude Code sub-agents spec. Only `name` and `description` are required.
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `name` | string | Unique identifier, kebab-case |
+| `description` | string | When to delegate. Claude matches against this |
+| `tools` | list | Allowlist of tools (inherits all if omitted) |
+| `disallowedTools` | list | Denylist, applied first, then `tools` filters the remainder |
+| `model` | string | `sonnet` \| `opus` \| `haiku` \| full ID (e.g. `sonnet`) \| `inherit`. **Plugin agents authored in CBP MUST set this explicitly** — `inherit` is not permitted; see [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) for the canonical model/effort matrix |
+| `permissionMode` | string | `default` \| `acceptEdits` \| `auto` \| `dontAsk` \| `bypassPermissions` \| `plan` |
+| `maxTurns` | number | Cap on agentic turns before the agent must stop |
+| `skills` | list | Skills to preload — full content injected at startup |
+| `mcpServers` | list | String references (shared) or inline defs (scoped to this agent) |
+| `hooks` | object | Lifecycle hooks — `PreToolUse`, `PostToolUse`, `Stop` (→ `SubagentStop`) |
+| `memory` | string | `user` \| `project` \| `local` — persistent MEMORY.md directory |
+| `background` | boolean | Always run concurrent to the main thread |
+| `effort` | string | `low` \| `medium` \| `high` \| `xhigh` \| `max`. **Plugin agents authored in CBP MUST set this explicitly** (no commented-out placeholder); see [/cbp-build-cc-mode](../../build-cc-mode/SKILL.md) for the matrix |
+| `isolation` | string | `worktree` — gives the agent a temporary git worktree |
+| `color` | string | `red` \| `blue` \| `green` \| `yellow` \| `purple` \| `orange` \| `pink` \| `cyan` |
+| `initialPrompt` | string | Auto-submitted first user turn when the agent is the main session agent |
+
+## Tool-allowlist special forms
+
+| Form | Effect |
+|------|--------|
+| `Agent` | Agent may spawn any subagent (main-thread only) |
+| `Agent(worker, researcher)` | Only these subagent types may be spawned |
+| (omit `Agent`) | Cannot spawn subagents |
+
+## Resolution order for `model`
+
+1. `CLAUDE_CODE_SUBAGENT_MODEL` env var
+2. Per-invocation `model` parameter passed by Claude
+3. The `model` field in this file
+4. Main conversation's model

package/templates/skills/cbp-build-cc-agent/reference/permission-modes.md

@@ -0,0 +1,18 @@
+# Permission Modes Reference
+
+Source: official Claude Code sub-agents and permission-modes specs.
+
+| Mode | Behaviour |
+|------|-----------|
+| `default` | Standard permission prompts |
+| `acceptEdits` | Auto-accept edits and common filesystem commands in working dir |
+| `auto` | Background classifier reviews commands and protected-dir writes |
+| `dontAsk` | Auto-deny prompts; only explicit allows pass |
+| `bypassPermissions` | Skip prompts entirely (writes to `.git`, `.claude`, etc. still prompt) |
+| `plan` | Read-only exploration mode |
+
+## Inheritance rules
+
+- If parent is `bypassPermissions` or `acceptEdits`, child cannot weaken it
+- If parent is `auto`, child inherits `auto` and its `permissionMode` is ignored
+- Otherwise the child's `permissionMode` takes effect as declared