codebyplan 1.13.29 → 1.13.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.29",
+  "version": "1.13.30",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/README.md

@@ -1,20 +1,23 @@
-# Templates
+# .claude/
 
-This directory holds the installed content that the `codebyplan claude install` subcommand places into a consuming project's `./.claude/` directory. Skills, agents, and hooks live here.
+This directory is **managed by the `codebyplan` package** and refreshed by:
 
-## Authoring source
+```sh
+npx codebyplan claude update
+```
 
-`packages/codebyplan-package/templates/` is the single source of truth for all `.claude/` content. The sibling-identity gate (CHK-134) requires that every edit to `templates/` is mirrored to `.claude/` in the same commit — there is no special "canonical worktree". Every worktree running this repo consumes updates via `npx codebyplan claude install|update`; release-please publishes the `codebyplan` npm package on merge to main, which propagates changes to consuming repos.
+## Do not hand-edit managed files
 
-## Layout
+Files installed here (skills, agents, hooks, rules) are owned by the `codebyplan` package. Running `codebyplan claude update` will overwrite any local changes to managed files.
 
-| Path      | Count                                | Shape                                                                                           |
-| --------- | ------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| `skills/` | 41 folders                           | each is a `SKILL.md` plus optional `templates/`, `reference/`, `examples/`, `scripts/` siblings |
-| `agents/` | 16 files                             | flat `.md` agent prompts (NOT `AGENT.md` subdirs)                                               |
-| `hooks/`  | 20 `.sh` + `hooks.json` + `README.md` | event hooks and manifest                                                                        |
-| `rules/`  | 1+ files                             | flat `<name>.md` rule files; see `rules/README.md` for bar and format                           |
+To change managed behaviour, make the change upstream in the `codebyplan` package and publish a new version.
 
-## This directory IS the source of truth
+## Repo-specific additions
 
-Edit files in this directory directly. There is no upstream tree — CHK-111 TASK-10 retired the prior in-monorepo plugin distribution path and replaced rsync-based distribution with an npm publish lifecycle. CHK-132 then consolidated that lifecycle into the merged `codebyplan` package; the assets now ship as the `claude` subcommand group (`install` / `update` / `uninstall`).
+Additions that belong only to this repo go in repo-scoped files that `codebyplan` does not touch:
+
+- **Root `CLAUDE.md`** — repo-level context and instructions always loaded by Claude Code.
+- **`rules/` files with `scope: repo-only:<repo-name>`** — behavioral constraints specific to this repo.
+- **`context/` and `docs/`** — repo-specific reference material referenced by your own agents or skills.
+
+Repo-scoped files coexist with managed files and are never overwritten by `codebyplan claude update`.

package/templates/agents/cbp-cc-executor.md

@@ -1,7 +1,7 @@
 ---
 scope: org-shared
 name: cbp-cc-executor
-description: Authoring executor for `.claude/` infrastructure. Applies approved changes across rules, skills, agents, context, CLAUDE.md, settings, hooks, and auto-memory — with update-first discipline, scope-marker enforcement, and length-limit awareness. Callable by the main conversation, `/cbp-checkpoint-end`, and `round-executor` (for in-scope `.claude/` infra deliverables).
+description: Authoring executor for `.claude/` infrastructure. Applies approved changes across rules, skills, agents, context, CLAUDE.md, settings, and hooks — with update-first discipline, scope-marker enforcement, and length-limit awareness. Callable by the main conversation, `/cbp-checkpoint-end`, and `round-executor` (for in-scope `.claude/` infra deliverables).
 tools: Read, Write, Edit, Glob, Grep, Skill, Task, AskUserQuestion, mcp__codebyplan__create_task
 model: sonnet
 effort: xhigh
@@ -40,7 +40,7 @@ input:
   source: 'main' | 'checkpoint-end' | 'round-executor'  # additional internal sources may exist in your CBP setup; extend as needed
   changes:
     - id: string | number
-      type: 'rule' | 'skill' | 'agent' | 'context' | 'architecture' | 'CLAUDE.md' | 'settings' | 'hook' | 'memory'
+      type: 'rule' | 'skill' | 'agent' | 'context' | 'architecture' | 'CLAUDE.md' | 'settings' | 'hook'
       target: string                 # Path under .claude/ (or CLAUDE.md)
       action: 'create' | 'update' | 'delete'
       description: string            # What the change is
@@ -121,13 +121,12 @@ Per validated change, route to the correct authoring path:
 | CLAUDE.md    | `/cbp-build-cc-claude-file` (only for a non-root CLAUDE.md — root exists) | Direct Edit                                                      |
 | settings     | `/cbp-build-cc-settings`                                                  | `/cbp-build-cc-settings` (schema-critical — always route) |
 | hook         | Direct Write with `# @scope:` header                                             | Direct Edit                                                      |
-| memory       | `/cbp-build-cc-memory`                                                    | `/cbp-build-cc-memory` (MEMORY.md index must update)      |
 
 Routing rules:
 
 - **Creates always go through the build-cc skill** when one exists — the skill embeds the signature (`scope:` / `$schema:` / `type:`) the build-cc skills require.
 - **Updates use direct Edit** on already-signed files. The signature travels with the file; editing preserves it.
-- **Settings and memory always route** — their schema/index semantics are non-trivial.
+- **Settings always route** — their schema semantics are non-trivial.
 
 Record every applied change with `authored_via` and `status`.
 
@@ -143,9 +142,8 @@ Record every applied change with `authored_via` and `status`.
 After all changes applied:
 
 1. For every touched file, re-check: still within length limit? scope marker still present?
-2. If `MEMORY.md` touched: index lines ≤200 chars? No duplicate names?
-3. If `settings.json` touched: valid JSON? Re-read the file and validate syntax — matched braces/brackets, quoted keys, no trailing commas. Reject the change if invalid.
-4. Report any drift as `status: 'partial'` and list in `applied_changes[].note`.
+2. If `settings.json` touched: valid JSON? Re-read the file and validate syntax — matched braces/brackets, quoted keys, no trailing commas. Reject the change if invalid.
+3. Report any drift as `status: 'partial'` and list in `applied_changes[].note`.
 
 ### Phase 6: Return
 
@@ -164,7 +162,6 @@ Every managed file must carry its scope marker — checked by `validate-structur
 | agent        | `scope: {value}`                               | YAML frontmatter |
 | hook         | `# @scope: {value}`                            | Header comment   |
 | settings     | `$schema: {url}` (implicit scope via filename) | JSON field       |
-| memory       | `type: {user\|feedback\|project\|reference}`   | YAML frontmatter |
 | context      | _(signatureless)_                              | n/a              |
 | architecture | _(signatureless)_                              | n/a              |
 | CLAUDE.md    | _(plain markdown)_                             | n/a              |
@@ -208,6 +205,6 @@ Block-limit violations are non-negotiable — split before applying.
 - **Spawned by**: main conversation (ad-hoc), `/cbp-checkpoint-end` (future), `round-executor` (in-scope `.claude/` infra deliverables, `source: 'round-executor'`)
 - **Reads**: `.claude/` inventory, `validate-structure-lengths.sh`, target files
 - **Writes**: `.claude/` files (via `/cbp-build-cc-*` skills for creates, direct Edit for updates)
-- **Calls skills**: `/cbp-build-cc-rule`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`, `/cbp-build-cc-memory`
+- **Calls skills**: `/cbp-build-cc-rule`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`
 - **Creates tasks**: via MCP `create_task` when a change exceeds invocation scope
 - **Enforced by**: `validate-structure-lengths.sh` (length), `validate-structure-scope.sh` (scope marker), `validate-structure-patterns.sh` (path layout)

package/templates/agents/cbp-round-executor.md

@@ -98,7 +98,7 @@ output:
 
 **Key Principle:** If something is unclear or you're blocked, ASK the user. Don't make assumptions.
 
-**Routing Principle:** For managed files requiring routing commands (`/cbp-build-cc-rule`, `/cbp-build-cc-agent`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`, `/cbp-build-cc-memory`), use Skill tool. For other managed files (templates, architecture, research, stack docs), use direct Write/Edit.
+**Routing Principle:** For managed files requiring routing commands (`/cbp-build-cc-rule`, `/cbp-build-cc-agent`, `/cbp-build-cc-skill`, `/cbp-build-cc-claude-file`, `/cbp-build-cc-settings`), use Skill tool. For other managed files (templates, architecture, research, stack docs), use direct Write/Edit.
 
 ## Execution Workflow
 
@@ -124,7 +124,6 @@ Skill tool: skill="cbp-build-cc-agent"        # for .claude/agents/
 Skill tool: skill="cbp-build-cc-skill"        # for .claude/skills/
 Skill tool: skill="cbp-build-cc-claude-file"  # for .claude/CLAUDE.md
 Skill tool: skill="cbp-build-cc-settings"     # for .claude/settings*.json
-Skill tool: skill="cbp-build-cc-memory"       # for ~/.claude/projects/<project>/memory/
 Direct Write/Edit                          # for templates, docs/
 ```
 

package/templates/rules/README.md

@@ -34,14 +34,19 @@ The `install`/`update`/`uninstall` flow handles these files identically to how i
 
 ## Current status
 
-Four rules are shipped:
-
-| Rule file | Summary |
-|---|---|
-| `scope-vocabulary.md` | Canonical scope-marker enum (`org-shared` / `project-shared` / `repo-only:<name>`) enforced by three validators |
-| `context-file-loading.md` | Context-file load contract — who loads what, when, and how missing files are handled |
-| `todo-backend.md` | Todos queue contract, six DB-layer workflow invariants, and writer obligations for MCP mutators |
-| `supabase-branch-lifecycle.md` | Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle — lazy create on first DB change, delete wherever the git branch is removed |
+Nine rules are shipped:
+
+| Rule file | Scope | Summary |
+|---|---|---|
+| `scope-vocabulary.md` | `org-shared` | Canonical scope-marker enum (`org-shared` / `project-shared` / `repo-only:<name>`) enforced by three validators |
+| `context-file-loading.md` | `org-shared` | Context-file load contract — who loads what, when, and how missing files are handled |
+| `todo-backend.md` | `org-shared` | Todos queue contract, six DB-layer workflow invariants, and writer obligations for MCP mutators |
+| `supabase-branch-lifecycle.md` | `org-shared` | Supabase preview-branch lifecycle mirrors the git feat-branch lifecycle — lazy create on first DB change, delete wherever the git branch is removed |
+| `agent-claim-verification.md` | `org-shared` | Verify an agent's claimed outcomes against ground truth (git, filesystem, tool results) before trusting them |
+| `e2e-mandatory.md` | `org-shared` | E2E is opt-out: an eligible framework whose source changed in a round must run its specialist or record a valid skip |
+| `parallel-waves.md` | `org-shared` | Wave-dispatch contract for parallel round execution — topological ordering and per-wave testing |
+| `task-routing-recommendation.md` | `repo-only:codebyplan` | Two-family command surface (checkpoint-bound vs standalone) and identifier-format routing — installed only in codebyplan-family repos |
+| `cbp-operating-gotchas.md` | `org-shared` | Cross-repo CBP-tooling traps (ship/timeout/MCP-replace/worktree/lint-baseline/approval-reconcile) + behavioral prefs, inherited once by all consumers |
 
 ## Contributing a rule
 

package/templates/rules/cbp-operating-gotchas.md

@@ -0,0 +1,64 @@
+---
+scope: org-shared
+---
+
+# CBP Operating Gotchas
+
+Cross-repo traps in the CodeByPlan tooling surface (CLI, MCP, git, host platform) that
+recur in every consuming repo. They are recorded **once** here so consumers inherit them via
+`npx codebyplan claude update` instead of re-learning each one per repo. This file is for
+SHARED tooling behavior only — repo-specific gotchas belong in that repo's own `CLAUDE.md`
+(root or nested), never here.
+
+## Tooling Traps
+
+- **`codebyplan ship` can report a false `checks_failed`.** The CLI polls
+  `gh pr checks --json name,state,conclusion` and treats a check as failed when its `state` is
+  `COMPLETED` and its `conclusion` is non-null and not a success value — but `gh` does not always
+  populate `conclusion` for every check type, so a green PR can be misread as failed. Do not trust
+  the CLI verdict alone: confirm with `gh pr checks <pr> --watch`, then merge manually with
+  `gh pr merge <pr> --merge`.
+
+- **macOS has no `timeout` binary.** Wrapping a build/lint/test in `timeout …` fails with
+  `command not found: timeout` — meaning the wrapped command **never ran** (a misleading
+  "exit 127", not a real result). Never shell-wrap with `timeout`; use the Bash tool's own
+  `timeout` parameter to bound a command.
+
+- **MCP `update_checkpoint` / `update_task` / `update_round` are REPLACE, not merge.** The
+  `context` JSONB and `files_changed[]` array overwrite wholesale — a partial write silently
+  clobbers existing `decisions` / `discoveries` / `check_results`. Always read the current row,
+  merge your change into the full object/array, then write the whole thing back.
+
+- **`resolve-worktree` empty output = a NULL `(device, path, branch)` tuple, not a broken
+  resolver.** When identity is unresolved the server can collapse the caller to the repo's main
+  worktree, so feat-locked writes get rejected. Pass `caller_worktree_id` on every MCP mutation,
+  and confirm ownership by matching the row's repo path + branch to the current directory before
+  mutating.
+
+- **Full-repo lint/type baselines are often pre-existing red.** A round must gate on the files
+  it changed, not the whole-repo baseline — scope lint/tsc checks to the round's changed set so a
+  pre-existing baseline error outside that set never fails the round.
+
+- **`complete_task` checks file approval on the round's `files_changed`, not the task's.**
+  Reconcile approvals via `update_round` (set each entry `user_approved: true`), not
+  `update_task` alone — updating only the task leaves the round entries unapproved and
+  `complete_task` rejects with "files are not approved".
+
+- **CLI transport uses REST (reads) and OAuth+MCP (writes) — a 502 from `codebyplan round sync-approvals` is transient MCP churn, not an outage.** The CLI exits 0 with a warning and MCP tools still work. A missing `CODEBYPLAN_API_KEY` surfaces as an `ApiError`, not a 502. `sync-approvals` can also drag untracked per-device dirs into `files_changed` — run it from the repo root or pass `--caller-worktree-id`.
+
+- **`codebyplan claude update` requires a TTY.** On non-TTY stdin (CI, piped) it half-applies then errors. Re-run with `--yes` to accept defaults non-interactively.
+
+- **Checkpoint locks are invisible until a mutation they block.** `get_checkpoints` / `get_tasks` succeed even when another worktree holds the lock; the 403 fires only on `update_*` / `complete_*`. Verify the row's `worktree_id` matches the caller before mutating. A null-`worktree_id` checkpoint can still be actively shipped by whichever worktree physically holds its feat branch — check `git worktree list` first.
+
+- **`update_task` accepts `caller_worktree_id` for lock-verify only — it does NOT assign ownership.** Ownership assignment goes through the web UI or the dedicated assignment path. Don't conflate `caller_worktree_id` with `assigned_worktree_id`.
+
+- **Re-run config-driven gates after merging main into a feat branch.** A merge can add or change `.codebyplan/shipment.json`, ports, branch config, `e2e.json`, and `eslint.json` — treat the post-merge state as a fresh baseline before continuing.
+
+## Behavioral Preferences
+
+- **Never `git stash`** — for any reason. To inspect or compare other state use
+  `git diff <ref>`, `git show <ref>:<path>`, or `git worktree add`.
+
+- **During MCP instability, verify tool results over narration.** When responses lag, servers
+  cycle, or calls 502, never state an expected output as fact — confirm against git and the
+  filesystem, which are the source of truth.

package/templates/settings.project.base.json

@@ -96,7 +96,6 @@
     "allow": [
       "Skill(cbp-build-cc-agent)",
       "Skill(cbp-build-cc-claude-file)",
-      "Skill(cbp-build-cc-memory)",
       "Skill(cbp-build-cc-mode)",
       "Skill(cbp-build-cc-rule)",
       "Skill(cbp-build-cc-settings)",

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

@@ -1,8 +1,8 @@
 ---
 scope: org-shared
 name: cbp-build-cc-agent
-description: Build a Claude Code subagent at .claude/agents/{name}.md (flat form, per the official sub-agents spec) 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]"
+description: Build a Claude Code subagent at .claude/agents/{name}.md (flat form, per the official sub-agents spec) following the official sub-agents spec (frontmatter, tools, model, hooks, skills preload, permission modes, isolation).
+argument-hint: "[agent-name] [--scope=project|user] [--isolation=worktree]"
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(chmod *)
 effort: xhigh
 ---
@@ -15,7 +15,7 @@ Create a Claude Code subagent following the official Claude Code sub-agents spec
 
 ## Arguments
 
-`$ARGUMENTS` — agent name (kebab-case, required). Flags: `--scope=project|user` (default `project`), `--memory=project|user|local`, `--isolation=worktree`.
+`$ARGUMENTS` — agent name (kebab-case, required). Flags: `--scope=project|user` (default `project`), `--isolation=worktree`.
 
 ## When to Use
 
@@ -70,7 +70,6 @@ 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    |

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

@@ -4,7 +4,6 @@ description: Implement API endpoints following team conventions. Use when adding
 tools: Read, Write, Edit, Grep, Glob, Bash
 model: sonnet
 effort: xhigh
-memory: project
 skills:
   - api-conventions
   - error-handling-patterns
@@ -13,11 +12,11 @@ skills:
 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
+1. Read the nearest folder-local `CLAUDE.md` (e.g. `src/api/CLAUDE.md`) for conventions specific to this area
 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
+5. When you discover a durable pattern worth remembering, record it in the folder-local `CLAUDE.md` via `/cbp-build-cc-claude-file`
 
 Return:
 - Files created/modified

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

@@ -14,7 +14,6 @@ Source: official Claude Code sub-agents spec. Only `name` and `description` are
 | `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 |

package/templates/skills/cbp-build-cc-agent/scripts/validate-agent.sh

@@ -54,12 +54,6 @@ if [ -n "$pm" ] && [[ ! "$pm" =~ ^(default|acceptEdits|auto|dontAsk|bypassPermis
   err "permissionMode invalid: got '$pm'"
 fi
 
-# Memory scope check
-mem=$(grep -E '^memory:' <<< "$fm" | head -1 | sed -E 's/^memory:[[:space:]]*//; s/[[:space:]]*$//; s/^"(.*)"$/\1/' || true)
-if [ -n "$mem" ] && [[ ! "$mem" =~ ^(user|project|local)$ ]]; then
-  err "memory must be user|project|local: got '$mem'"
-fi
-
 if [ "$errors" -gt 0 ]; then
   echo "validation FAILED ($errors issue(s)) for $FILE" >&2
   exit 1

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

@@ -12,7 +12,6 @@ effort: xhigh
 # color: blue  # red | blue | green | yellow | purple | orange | pink | cyan
 # background: false
 # isolation: worktree  # only if the agent should work in an isolated git worktree
-# memory: project  # project | user | local — enables persistent MEMORY.md
 # skills:
 #   - api-conventions
 #   - error-handling-patterns
@@ -33,7 +32,7 @@ effort: xhigh
 #       hooks:
 #         - type: command
 #           command: "./scripts/run-linter.sh"
-# initialPrompt: "Start by reading MEMORY.md, then wait for instructions."  # only used when run as main thread via --agent
+# initialPrompt: "Start by reading the project CLAUDE.md, then wait for instructions."  # only used when run as main thread via --agent
 ---
 
 You are a [role] specialising in [domain].

package/templates/skills/cbp-build-cc-claude-file/SKILL.md

@@ -28,12 +28,12 @@ Actions:
 - Adding a new project-level fact (build command, architecture decision)
 - Restructuring when CLAUDE.md grows past ~200 lines
 - Migrating from AGENTS.md to CLAUDE.md (or bridging them)
+- Capturing a folder-local learning (a `project`/`feedback` insight tied to one area of the tree) → author a **nested CLAUDE.md** next to that code (see "Authoring a nested CLAUDE.md" below). This is the home for durable learnings that previously went to auto-memory.
 
 Do NOT use this skill for:
 
 - Workflow details or behavioural rules → `/cbp-build-cc-rule`
 - Reusable step-by-step procedures → `/cbp-build-cc-skill`
-- Personal learnings across projects → `/cbp-build-cc-memory`
 
 ## Instructions
 
@@ -48,6 +48,20 @@ Do NOT use this skill for:
 
 Default: project. Either `./CLAUDE.md` or `./.claude/CLAUDE.md` works; pick one and stick to it.
 
+### Step 1.5 — Authoring a nested CLAUDE.md
+
+A **nested** CLAUDE.md lives in a subdirectory (e.g. `apps/web/src/lib/CLAUDE.md`) rather than the repo root. It is the home for a folder-local learning — a `project`/`feedback` insight that only matters when working in that part of the tree (what previously went to auto-memory). Prefer a nested CLAUDE.md over the root file whenever the fact is scoped to one area: it keeps the root high-signal and loads the detail only when relevant.
+
+**Discovery (how nested files load).** At session start Claude Code loads every `CLAUDE.md` on the path from the working directory **up** to the repo root. Files in subdirectories **below** the working directory load **on-demand** — the moment Claude reads any file inside that subdirectory. Unlike the root file, nested CLAUDE.md content does **not** survive compaction — it reloads when Claude next touches a matching subdirectory file. So a nested file is self-contained context for its folder, not a place for repo-wide rules.
+
+**Placement.** Put the file in the shallowest directory that fully contains the concern:
+
+- A gotcha about one package's build → that package root (`packages/foo/CLAUDE.md`)
+- A convention for a feature area → that feature dir (`apps/web/src/lib/CLAUDE.md`)
+- A repo-wide fact → the root CLAUDE.md, not a nested file
+
+**Authoring.** Same quality gates as the root file (specific > vague, no duplication, keep it stable), but scope every line to the folder. Open with one line naming the area the file governs. Cross-link the root file or a rule with `@path` imports instead of repeating their content. To create one, run this skill with `create --scope=project` and write to the nested path.
+
 ### Step 2 — Read existing CLAUDE.md (for update/check)
 
 ```bash
@@ -165,7 +179,7 @@ Run `/memory` to confirm the file is loaded. The list shows all CLAUDE.md, CLAUD
 - **Triggered by**: user invocation
 - **Reads**: `${CLAUDE_SKILL_DIR}/templates/*.md`, `${CLAUDE_SKILL_DIR}/reference/*.md`, current CLAUDE.md, `.claude/rules/*.md`
 - **Writes**: CLAUDE.md at the chosen scope
-- **Related skills**: `/cbp-build-cc-rule` (behavioural constraints), `/cbp-build-cc-memory` (personal learnings), `/cbp-build-cc-settings` (for `claudeMdExcludes`)
+- **Related skills**: `/cbp-build-cc-rule` (behavioural constraints), `/cbp-build-cc-settings` (for `claudeMdExcludes`)
 
 ## Key Rules
 

package/templates/skills/cbp-build-cc-claude-file/reference/what-belongs.md

@@ -15,7 +15,7 @@ Source: official Claude Code memory spec — *Write effective instructions*.
 |-------------|------------------|
 | Multi-step procedure | Skill (`.claude/skills/{name}/SKILL.md`) |
 | File-specific constraint | Path-scoped rule (`.claude/rules/{name}.md` with `paths:`) |
-| Personal learning | Auto memory (`~/.claude/projects/<project>/memory/`) |
+| Folder-local learning (project/feedback) | Nested CLAUDE.md placed next to the code it concerns (see SKILL.md "Authoring a nested CLAUDE.md") |
 | API endpoint documentation | `docs/` |
 | Architecture deep-dive | `docs/architecture/` |
 | Framework usage guide | `docs/stack/{framework}/` |

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

@@ -23,7 +23,7 @@ Audit or apply the canonical `model:` + `effort:` frontmatter convention across
 
 `model: sonnet` + `effort: xhigh`
 
-Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 27 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-memory, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
+Fifteen of the 16 authoring agents take the default (`cbp-cc-executor`, `cbp-database-agent`, `cbp-improve-claude`, `cbp-improve-round`, `cbp-research`, `cbp-round-executor`, `cbp-security-agent`, `cbp-task-check`, `cbp-task-planner`, `cbp-testing-qa-agent`, `cbp-e2e-playwright`, `cbp-e2e-maestro`, `cbp-e2e-tauri`, `cbp-e2e-vscode`, `cbp-e2e-xcuitest`). The 16th — `cbp-mechanical-edits` — is an explicit haiku-low exception (see below). 26 skills take the default: cbp-round-start, cbp-round-input, cbp-round-execute, cbp-task-create, cbp-task-start, cbp-task-complete, cbp-task-testing, cbp-checkpoint-create, cbp-checkpoint-check, cbp-checkpoint-end, cbp-build-cc-mode, cbp-build-cc-agent, cbp-build-cc-skill, cbp-build-cc-rule, cbp-build-cc-claude-file, cbp-build-cc-settings, cbp-frontend-a11y, cbp-frontend-design, cbp-frontend-ui, cbp-frontend-ux, cbp-session-end, cbp-ship, cbp-ship-configure, cbp-supabase-setup, cbp-supabase-migrate, cbp-supabase-branch-check.
 
 ### Effort-lowered skills (5)
 

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

@@ -25,7 +25,7 @@ Create a rule at `.claude/rules/{name}.md` per the official Claude Code memory s
 
 - Step-by-step workflows → use `/cbp-build-cc-skill` (loads on invoke, doesn't burn context)
 - Project-level facts always needed → CLAUDE.md (use `/cbp-build-cc-claude-file`)
-- Accumulating learnings → auto memory (use `/cbp-build-cc-memory`)
+- Accumulating learnings → nested CLAUDE.md (use `/cbp-build-cc-claude-file`)
 
 ## Instructions
 
@@ -164,7 +164,7 @@ Use the `InstructionsLoaded` hook if you need to debug exactly when and why a ru
 - **Triggered by**: user invocation
 - **Reads**: `${CLAUDE_SKILL_DIR}/templates/rule.md`, `${CLAUDE_SKILL_DIR}/reference/paths-patterns.md`
 - **Writes**: `.claude/rules/{name}.md` or `~/.claude/rules/{name}.md`
-- **Related skills**: `/cbp-build-cc-claude-file` (project facts), `/cbp-build-cc-skill` (workflows), `/cbp-build-cc-memory` (auto-learnings)
+- **Related skills**: `/cbp-build-cc-claude-file` (project facts + nested-folder learnings), `/cbp-build-cc-skill` (workflows)
 
 ## Key Rules
 

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

@@ -1,201 +0,0 @@
----
-scope: org-shared
-name: cbp-build-cc-memory
-description: Create or update an auto-memory entry under the Claude Code auto-memory directory per the official spec. Handles path-slug encoding, per-repo redirection via autoMemoryDirectory, MEMORY.md index, and per-entry typing (user/feedback/project/reference).
-argument-hint: "[entry-name] [--type=user|feedback|project|reference] [--repo-local]"
-allowed-tools: Read, Write, Edit, Glob, Grep, Bash(mkdir *), Bash(cat *), Bash(ls *), Bash(jq *)
-effort: xhigh
----
-
-# Build Claude Code Auto-Memory Entry
-
-Create or update an entry in Claude Code's auto-memory directory per the official Claude Code memory spec (section _Auto memory_).
-
-Auto memory is machine-local knowledge Claude accumulates across sessions. Only the first 200 lines or 25KB of `MEMORY.md` load at session start.
-
-## Arguments
-
-`$ARGUMENTS` — entry name (kebab-case, used as filename). Flags: `--type=user|feedback|project|reference` (see [reference/memory-types.md](reference/memory-types.md)), `--repo-local` (store at `.claude/memory/` via user-scope `autoMemoryDirectory` override; see Step 1).
-
-## When to Use
-
-| Situation                                                    | Action                                 |
-| ------------------------------------------------------------ | -------------------------------------- |
-| User tells you something about themselves                    | Save as `user` memory                  |
-| User corrects you, or confirms a non-obvious approach worked | Save as `feedback` memory              |
-| User shares project info (deadline, stakeholder, WHY)        | Save as `project` memory               |
-| User points to external system (Linear, Slack, dashboard)    | Save as `reference` memory             |
-| User says "remember this" / "save this"                      | Save immediately, pick type by content |
-| User says "forget X"                                         | Find and delete the entry              |
-
-Do **NOT** save:
-
-- Things derivable from `git log`, `git blame`, or reading the current code
-- Debugging fixes (they're already in the commit)
-- CLAUDE.md content (different mechanism)
-- Ephemeral task/conversation state
-
-## Instructions
-
-### Step 1 — Locate the memory directory
-
-**Default (global auto-memory):** `~/.claude/projects/<project-slug>/memory/`.
-
-The `<project-slug>` is the **absolute git repo path with `/` replaced by `-`**, e.g. repo at `/Users/alice/my-app` → slug `-Users-alice-my-app`. The `<project>` placeholder in the docs is not a friendly name — it's this slug.
-
-Resolve it deterministically:
-
-```bash
-REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
-SLUG="$(echo "$REPO_ROOT" | sed 's|/|-|g')"
-DEFAULT_DIR="$HOME/.claude/projects/$SLUG/memory"
-```
-
-Worktrees get a separate slug (the spec says all worktrees share one dir, but the runtime slugs by path — verify with `ls ~/.claude/projects/ | grep "$SLUG"`).
-
-**Override (`autoMemoryDirectory`):** the runtime reads this key only from **user, local, or managed-policy** settings — never from project settings. Resolve in that priority order, then fall back to the default path.
-
-```bash
-# Check overrides in priority order
-for f in "$HOME/.claude/settings.json" ".claude/settings.local.json"; do
-  override=$(jq -r '.autoMemoryDirectory // empty' "$f" 2>/dev/null)
-  [ -n "$override" ] && MEMORY_DIR="${override/#\~/$HOME}" && break
-done
-MEMORY_DIR="${MEMORY_DIR:-$DEFAULT_DIR}"
-mkdir -p "$MEMORY_DIR"
-```
-
-### Step 2 — Pick scope: global vs repo-local vs user-global
-
-Three valid configurations (decide before writing):
-
-| Scope                        | Where it lives                      | How to enable                                                                    | When to use                                          |
-| ---------------------------- | ----------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------- |
-| Global auto-memory (default) | `~/.claude/projects/<slug>/memory/` | No config — works by default                                                     | Personal learnings specific to this repo             |
-| Repo-local                   | `<repo>/.claude/memory/`            | Set `autoMemoryDirectory` in `.claude/settings.local.json` (NOT `settings.json`) | Team-shared repo memory; also gitignore if sensitive |
-| User-global                  | `~/my-notes/` or similar            | Set `autoMemoryDirectory` in `~/.claude/settings.json`                           | One memory pool across all your projects             |
-
-**CBP default: global.** Switch to repo-local only when (a) the memory would help a teammate on the same repo, (b) isn't already in CLAUDE.md, and (c) you're comfortable committing it (or gitignoring deliberately). Prefer global for automatic feedback-type memories.
-
-**Never save credentials, secrets, or PII** to any memory scope. Memory is loaded into every session.
-
-**Memory vs CLAUDE.md vs rules:**
-
-| Destination              | What belongs                                                                           |
-| ------------------------ | -------------------------------------------------------------------------------------- |
-| CLAUDE.md                | Stable, team-shared facts needed every session (tech stack, branch strategy, repo IDs) |
-| `.claude/rules/`         | Behavioural constraints enforced on specific files (paths-scoped)                      |
-| Auto-memory (global)     | Personal learnings, user's working style, past corrections                             |
-| Auto-memory (repo-local) | Team facts not yet stable enough for CLAUDE.md                                         |
-
-Don't duplicate across destinations.
-
-**Repo-local setup** (if `--repo-local` or user asks):
-
-1. Invoke `/cbp-build-cc-settings` to add `"autoMemoryDirectory": "./.claude/memory"` to `.claude/settings.local.json` (user-scope is also accepted). Project-scope `settings.json` is **rejected** by the runtime.
-2. Create the directory: `mkdir -p .claude/memory`
-3. Decide: commit to git (team-shared) or add to `.gitignore` (personal in-repo).
-
-### Step 3 — Read the existing MEMORY.md
-
-```bash
-cat "$MEMORY_DIR/MEMORY.md" 2>/dev/null || echo "(no MEMORY.md yet)"
-```
-
-MEMORY.md is the **index**, not a store. One-line pointer per entry, under ~150 chars. It's loaded every session (first 200 lines / 25KB). Keep it tight.
-
-### Step 4 — Check for an existing entry
-
-```bash
-ls "$MEMORY_DIR" | grep -i "{topic-keyword}"
-```
-
-If a related entry exists:
-
-- Updating an existing fact → edit that file
-- Same topic, different angle → edit or merge
-- New but adjacent → create new file, cross-link from MEMORY.md
-
-Never duplicate.
-
-### Step 5 — Classify the entry
-
-Pick the right type. Details: [reference/memory-types.md](reference/memory-types.md).
-
-| Type        | Saves                         | Example trigger                           |
-| ----------- | ----------------------------- | ----------------------------------------- |
-| `user`      | Who they are, how they work   | "I've been writing Go for 10 years"       |
-| `feedback`  | Corrections AND confirmations | "stop summarizing", "yeah that was right" |
-| `project`   | Work context, deadlines, WHY  | "we're freezing after Thursday"           |
-| `reference` | Pointers to external systems  | "bugs live in Linear project INGEST"      |
-
-### Step 6 — Write the entry file
-
-Read `${CLAUDE_SKILL_DIR}/templates/memory-entry.md` for the canonical format.
-
-Filename convention: `{type}_{topic}.md` (e.g. `feedback_testing.md`, `user_role.md`, `project_q1_freeze.md`).
-
-Frontmatter:
-
-```yaml
----
-name: Human-readable entry name
-description: One-line relevance hint — used to judge if this memory matters in a new conversation
-type: user | feedback | project | reference
----
-```
-
-For `feedback` and `project` types, structure the body as:
-
-1. Lead line — the rule or fact itself
-2. **Why:** — reason the user gave (incident, preference, deadline)
-3. **How to apply:** — when this guidance kicks in
-
-See [examples/feedback-memory.md](examples/feedback-memory.md) and [examples/project-memory.md](examples/project-memory.md).
-
-### Step 7 — Update MEMORY.md
-
-MEMORY.md is an index, not a memory. No frontmatter. One line per entry:
-
-```markdown
-# Memory
-
-- [Title](file.md) — one-line hook
-- [Another title](another.md) — one-line hook
-```
-
-Keep each line under ~150 characters. Organize by topic, not chronology.
-
-### Step 8 — Handle absolute dates
-
-Convert relative dates to absolute when saving:
-
-| User said      | Save as                     |
-| -------------- | --------------------------- |
-| "by Thursday"  | `2026-04-23` (today + days) |
-| "next week"    | `2026-04-29 to 2026-05-05`  |
-| "last quarter" | `2026-Q1`                   |
-
-Memories persist — relative dates rot.
-
-### Step 9 — Verify with `/memory`
-
-Run `/memory` in Claude Code to browse the directory. New entries appear immediately in the index load (on next session).
-
-## Integration
-
-- **Triggered by**: user asking to remember, feedback during work
-- **Reads**: `${CLAUDE_SKILL_DIR}/templates/*.md`, `${CLAUDE_SKILL_DIR}/reference/*.md`
-- **Writes**: resolved `$MEMORY_DIR` (default `~/.claude/projects/<slug>/memory/`, or `autoMemoryDirectory` override)
-- **Related skills**: `/cbp-build-cc-settings` (configure `autoMemoryDirectory`), `/cbp-build-cc-claude-file` (team-shared facts → CLAUDE.md, not memory), `/cbp-build-cc-rule` (behavioural constraints → rules)
-
-## Key Rules
-
-- `<project>` in the docs is a **slug** (`/` → `-`), not a friendly name
-- `autoMemoryDirectory` is **rejected** from project `settings.json` — only user / local / managed-policy accept it
-- MEMORY.md is an **index** — pointer lines only, no frontmatter, no long content
-- Lines after 200 (or 25KB) are not loaded at session start — keep MEMORY.md concise
-- Global auto memory is machine-local; for team-shared use repo-local and commit to git
-- Verify facts before recommending — memory can go stale; re-read the code when acting
-- When the user says "don't use memory," do not cite or act on it for this session
-- For a memory that names a file/function/flag — grep before relying on it

package/templates/skills/cbp-build-cc-memory/examples/feedback-memory.md

@@ -1,11 +0,0 @@
----
-name: Integration tests hit a real database
-description: Never mock the DB in integration tests — prior incident taught the team this
-type: feedback
----
-
-Integration tests must hit a real database, not mocks.
-
-**Why:** Prior incident (2025-Q4) — mocked tests passed but a prod migration failed because the mock diverged from the real schema. Team agreed to never mock the DB in integration tests afterwards.
-
-**How to apply:** Whenever writing or reviewing tests under `tests/integration/`, `apps/*/tests/integration/`, or anything tagged `@integration`. Unit tests may still mock. If you see a mock in an integration test, flag it.