codebyplan 1.13.38 → 1.13.39

package/package.json

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

package/templates/agents/cbp-map-architecture.md

@@ -0,0 +1,90 @@
+---
+scope: org-shared
+name: cbp-map-architecture
+description: Read-only agent that analyzes a repository module and produces a structured architecture map following the canonical spec. Invoke when generating or refreshing a module's .claude/architecture/<module>.md map file. Returns the full map content as text for the caller to write.
+tools: Read, Glob, Grep
+model: sonnet
+effort: high
+---
+
+# Architecture Map Agent
+
+You are a read-only code analyst that produces architecture map content for a single repository module.
+
+## Purpose
+
+Analyze a module's source files and produce the complete content of a `.claude/architecture/<module>.md` map file, following the canonical format defined in `.claude/context/architecture/arch-map-spec.md`. The caller writes the returned content to disk — this agent does NOT write files.
+
+## Input Contract
+
+```yaml
+input:
+  module_path: string   # Module root path relative to repo root (e.g. "apps/web", "packages/codebyplan-package")
+  depth: skeleton|deep  # Map fidelity level — skeleton omits Data-Flow Traces (section 5)
+```
+
+## Output Contract
+
+Returns the complete `.claude/architecture/<module>.md` file content as a text block — starting with `---` (YAML frontmatter) and ending after section 7. The caller writes this text to the appropriate path and then runs `codebyplan arch-map stamp` to update `architecture.json`.
+
+## Workflow
+
+### Phase 1 — Load the canonical spec
+
+1. Read `.claude/context/architecture/arch-map-spec.md`.
+2. Confirm the 7 canonical section names, frontmatter fields, and depth rules.
+
+### Phase 2 — Discover module files
+
+1. Derive `source_globs` from `module_path`:
+   - For `apps/<name>`: `["apps/<name>/src/**/*.ts", "apps/<name>/src/**/*.tsx", "apps/<name>/**/*.ts", "apps/<name>/**/*.tsx"]` (deduplicated to what actually exists)
+   - For `packages/<name>`: `["packages/<name>/src/**/*.ts"]`
+   - For cross-cutting paths (`supabase/`, root config dirs): glob the directory directly
+2. Run Glob for each pattern. Record the file list.
+3. Read the module's `package.json` (if present) for name, dependencies, scripts.
+4. Read the primary entry file (e.g. `src/index.ts`, `src/index.tsx`, `app/layout.tsx`, `main.ts`) if it exists.
+
+### Phase 3 — Analyze the module
+
+Use Read and Grep to gather the signal for each section:
+
+| Section | Analysis action |
+|---------|----------------|
+| 1 — Boundaries | Read README or top-level comments; grep for `// @module`, `@description`, or doc headers |
+| 2 — Public surface | Grep for `export (function\|class\|const\|type\|interface\|default)` in entry files |
+| 3 — Internal structure | List top-level directories; read key non-entry files to understand their role |
+| 4 — Dependencies | Parse `package.json` dependencies; grep `from '../'` patterns for cross-module imports |
+| 5 — Data-flow [deep only] | Trace 2–5 representative flows by reading route handlers, service methods, or CLI entry points end-to-end |
+| 6 — Conventions | Note naming patterns, linting config files, test file locations, framework idioms |
+| 7 — Landmarks | Record the most commonly-needed paths (config file, main entry, types, tests) |
+
+### Phase 4 — Produce the map content
+
+Assemble the output following the spec exactly:
+
+1. YAML frontmatter block with all 5 fields (`module`, `generated_from_sha: null`, `depth`, `generated_at: null`, `source_globs`).
+2. Sections 1–4 and 6–7 (always).
+3. Section 5 (only when `depth: deep`).
+4. Each section must have substantive content — no empty sections, no "N/A" placeholders. If information is genuinely unavailable, write a one-line note explaining why.
+
+## Completion Criteria
+
+- All 7 sections present (or section 5 explicitly omitted for `depth: skeleton`).
+- Frontmatter matches the spec schema exactly.
+- `generated_from_sha` and `generated_at` are `null` (the caller sets these via `stamp`).
+- Output is returned as text, not written to disk.
+
+## Failure Modes
+
+| Condition | Action |
+|-----------|--------|
+| `module_path` does not exist in the repo | Return `blocked`: "Module path {path} not found — verify the path and retry" |
+| Spec file `.claude/context/architecture/arch-map-spec.md` missing | Return `failed`: "Required spec file not found" |
+| Glob finds zero files for all patterns | Return `blocked`: "No source files found under {module_path} — check source_globs" |
+
+## Integration
+
+- **Spawned by**: `cbp-map-architecture` skill or direct agent invocation
+- **Returns to**: caller writes output text to `.claude/architecture/<module-slug>.md`, then runs `codebyplan arch-map stamp`
+- **Input from**: caller provides `module_path` and `depth`
+- **Reads**: `.claude/context/architecture/arch-map-spec.md`, module source files

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

@@ -212,6 +212,16 @@ If modifying managed files (`.claude/*`, `.claude/docs/architecture/*`, etc.):
 
 **Why:** Routing commands do this automatically. If you bypass routing, you MUST do source consultation manually. Skills contain coding patterns and conventions that must be followed.
 
+### Step 2.4: Architecture Map Consultation
+
+For ANY module you are about to edit (app code or managed files), check for a pre-computed architecture map:
+
+1. For each path in `files_to_modify`, derive its module and Glob `.claude/architecture/<module-slug>.md`.
+2. If a map exists, read it BEFORE Step 3 — it surfaces the module's boundaries, internal structure, dependencies, and where-things-live landmarks, reducing broad file-system scans.
+3. If `.claude/architecture/` is absent or the module has no map, proceed without it (not a blocker).
+
+See `.claude/context/architecture-map.md` for the full consultation contract. Unlike Step 2 (managed files only), this step fires for every round regardless of file type.
+
 ### Step 2.5: Search Before Creating
 
 For each file with action `create` in `files_to_modify`:

package/templates/agents/cbp-task-planner.md

@@ -376,6 +376,11 @@ delegation_hint:
 
 Read `.claude/rules/*.md` and relevant architecture docs.
 
+If `.claude/architecture/` contains map file(s) for the target module(s), read them before
+finalizing scope — they provide pre-computed structural context (boundaries, dependencies,
+landmarks) that reduces the need for broad file-system scans. See
+`.claude/context/architecture-map.md` for the consultation contract.
+
 ### Phase 4: Clarify Requirements (Context-First)
 
 Before any AskUserQuestion call, check (1) `checkpoint.context`, (2) `task.context`, (3) codebase via Grep/Glob/Read. Only ask if all three fail. When asking, prefix with `Checked: [sources]. Not found. Asking: [question]`. If a question IS answered in context, use that answer directly — do not re-ask.

package/templates/context/architecture/arch-map-spec.md

@@ -0,0 +1,204 @@
+---
+scope: org-shared
+---
+
+# Architecture Map Spec
+
+Canonical format specification for the `codebyplan arch-map` engine. Both the
+`cbp-map-architecture` agent and the `arch-map` CLI reference this file as the
+authoritative definition of all artifact formats.
+
+---
+
+## Per-Module Map File
+
+Location: `.claude/architecture/<module>.md`
+
+Where `<module>` is a slug derived from the module path, e.g.:
+- `apps/web` → `apps-web.md`
+- `packages/codebyplan-package` → `packages-codebyplan-package.md`
+- `backend` → `backend.md`
+- `.github` → `dot-github.md` (a leading dot in the module path is normalized to `dot-` so the map file is never hidden; the manifest `path` keeps the leading dot for git drift)
+
+### YAML Frontmatter
+
+Every map file MUST open with a YAML block containing these exact fields:
+
+```yaml
+---
+module: <path>                  # Module root path relative to repo root (e.g. "apps/web")
+generated_from_sha: <sha>|null  # Full git commit SHA the map was produced from, or null if never stamped
+depth: skeleton|deep            # Map fidelity level (see Depth Levels below)
+generated_at: <iso>|null        # ISO 8601 UTC timestamp of last generation, or null
+source_globs:                   # Glob patterns used to discover files for this map
+  - <glob>
+  - <glob>
+---
+```
+
+**Field rules:**
+- `module` is the canonical path — used as the key in `architecture.json` and INDEX.md rows.
+- `generated_from_sha` is `null` until `codebyplan arch-map stamp` is run for the first time.
+- `depth` must be exactly `skeleton` or `deep` — no other values are valid.
+- `generated_at` is `null` until first generation; set to an ISO 8601 UTC string on each regeneration.
+- `source_globs` lists the patterns actually used; empty array is valid for cross-cutting modules.
+
+### Depth Levels
+
+**`skeleton`** — structural overview only. Covers sections 1–4 and 6–7 (excludes Data-flow traces).
+Fast to generate; useful for unfamiliar or rarely-changed modules.
+
+**`deep`** — full analysis including Data-flow traces (section 5). Costs more tokens; used when
+the agent or developer needs end-to-end data-flow understanding.
+
+### The 7 Canonical Sections
+
+Every map file MUST include all applicable sections in this order. Sections marked `[deep only]`
+are omitted for `depth: skeleton` maps.
+
+```
+## 1. Boundaries & Responsibility
+## 2. Public Surface / Entry Points
+## 3. Internal Structure
+## 4. Dependencies (In / Out)
+## 5. Data-Flow Traces [deep only]
+## 6. Conventions
+## 7. Where-Things-Live Landmarks
+```
+
+**Section guidance:**
+
+**1. Boundaries & Responsibility**
+One-paragraph statement of what this module owns and does NOT own. Include the decision
+boundary (which concerns belong here vs. adjacent modules).
+
+**2. Public Surface / Entry Points**
+Exported functions, classes, components, API routes, CLI entry points, or RPC endpoints
+that other modules may depend on. For each: name, type, brief purpose.
+
+**3. Internal Structure**
+Key directories and their roles. Package sub-folders, layers, major files that are not
+part of the public surface. Use a flat list or nested bullets.
+
+**4. Dependencies (In / Out)**
+- **Consumes**: modules, packages, or services this module imports/calls.
+- **Consumed by**: modules that import from this module's public surface.
+Cross-module edges only — internal sub-folder imports are not listed here.
+
+**5. Data-Flow Traces [deep only]**
+2–5 named traces showing data end-to-end through this module. Format per trace:
+```
+### <trace name>
+Source → [step] → [step] → Sink
+```
+Include key transforms, async boundaries, and error paths.
+
+**6. Conventions**
+Patterns specific to this module: naming rules, file layout expectations, linting configs,
+framework conventions, testing approach.
+
+**7. Where-Things-Live Landmarks**
+Quick-lookup table or list for "where is X?" questions. List landmark paths and one-line
+descriptions. Aimed at a developer who has never opened this module.
+
+---
+
+## INDEX.md
+
+Location: `.claude/architecture/INDEX.md`
+
+The INDEX.md is the grep-native registry of all module maps in this repo. Format mirrors
+`vendor/INDEX.md` — one pipe-delimited row per module, designed so `grep <term> INDEX.md`
+produces a readable hit.
+
+### Row Format
+
+```
+| <module> | <depth> | <generated_from_sha_short> | <generated_at_date> | <map_file> |
+```
+
+- `<module>` — the `module` frontmatter value (e.g. `apps/web`)
+- `<depth>` — `skeleton` or `deep`
+- `<generated_from_sha_short>` — first 8 chars of `generated_from_sha`, or `unset` if null
+- `<generated_at_date>` — `YYYY-MM-DD` portion of `generated_at`, or `unset` if null
+- `<map_file>` — relative path from `.claude/architecture/` (e.g. `apps-web.md`)
+
+### Header
+
+```markdown
+# Architecture Map Index
+
+Grep-friendly registry of per-module architecture maps. Layout convention in `context/architecture/arch-map-spec.md`.
+
+| Module | Depth | SHA | Generated | Map File |
+|--------|-------|-----|-----------|----------|
+```
+
+Each module map added or updated MUST have a corresponding row upserted in INDEX.md.
+
+---
+
+## graph.md
+
+Location: `.claude/architecture/graph.md`
+
+Adjacency-list representation of cross-module dependency edges. Used for dependency impact
+analysis ("if I change module X, what else might be affected?").
+
+### Format
+
+```markdown
+# Architecture Dependency Graph
+
+Adjacency list of cross-module edges. Each entry: `<from> -> <to>`.
+Generated from the `Dependencies (In / Out)` sections of individual map files
+(first-party `@codebyplan/*` workspace imports, verified against each module's `package.json`).
+
+Scope: edges are TypeScript workspace package imports only. Runtime/service dependencies
+(shared schema directories, HTTP calls between apps) are documented per-map in
+`## 4. Dependencies (In / Out)` and are intentionally NOT graphed here — a module with
+no edge is not necessarily isolated; consult its map file for runtime coupling.
+
+## Edges
+
+<module-A> -> <module-B>
+<module-A> -> <module-C>
+<module-B> -> <module-D>
+```
+
+**Rules:**
+- One edge per line: `<from> -> <to>` (exact module path values from frontmatter).
+- Edges are directed (A depends on B = A -> B).
+- Edges ARE deduplicated at write time by `/cbp-map-architecture` — each unique `<from> -> <to>` pair appears exactly once in graph.md, regardless of how many map files declare the same dependency.
+- The file is regenerated wholesale by both `/cbp-map-architecture` (full generation) and `/cbp-refresh-arch-map` (drift-scoped refresh) — it is not appended incrementally by the CLI (`arch-map status`/`drift` are read-only).
+- Edges represent first-party `@codebyplan/*` TypeScript workspace package imports only, verified against each module's `package.json`. Runtime/service dependencies (shared schema directories, HTTP calls between apps) are intentionally NOT graphed — consult each module's `## 4. Dependencies (In / Out)` section for runtime coupling.
+
+---
+
+## architecture.json
+
+Location: `.codebyplan/architecture.json`
+
+The committed manifest tracking which modules have been mapped and their freshness state.
+Written by `setup` (empty stub) and `config` (create-if-absent). Updated by
+`codebyplan arch-map stamp`.
+
+### Schema
+
+```json
+{
+  "version": 1,
+  "modules": [
+    {
+      "path": "apps/web",
+      "map_file": ".claude/architecture/apps-web.md",
+      "generated_from_sha": "abc12345def...",
+      "depth": "skeleton",
+      "generated_at": "2026-06-02T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+The TypeScript types for this schema are `ArchitectureConfig` and `ArchitectureModuleEntry`
+in `packages/codebyplan-package/src/lib/types.ts`.

package/templates/context/architecture-map.md

@@ -0,0 +1,117 @@
+---
+scope: org-shared
+---
+
+# Architecture Map Consultation Contract
+
+This file is the **consumer contract** for the `.claude/architecture/` per-module map
+files: what the artifacts are, when to read them, how to parse them, and what to do when
+they are absent. Artifact format spec is in `context/architecture/arch-map-spec.md`.
+
+## What the Architecture Map Is
+
+A committed set of per-module `.md` files under `.claude/architecture/` that record the
+structure, public surface, internal layout, dependencies, conventions, and landmarks of
+each repository module. They are authored by the `cbp-map-architecture` agent and stamped
+by the `codebyplan arch-map stamp` CLI.
+
+| Artifact | Location | Purpose |
+|----------|----------|---------|
+| Per-module map | `.claude/architecture/<module-slug>.md` | Full analysis of one module |
+| Index | `.claude/architecture/INDEX.md` | Grep-friendly registry of all mapped modules |
+| Dependency graph | `.claude/architecture/graph.md` | Cross-module dependency edges (adjacency list) |
+
+**Depth levels** (from the module's `depth:` frontmatter field):
+
+| Level | Sections included | When used |
+|-------|-------------------|-----------|
+| `skeleton` | 1–4, 6–7 (no data-flow traces) | Structural overview, unfamiliar or rarely-changed modules |
+| `deep` | 1–7 including data-flow traces | End-to-end understanding of active modules |
+
+**Slug derivation**: `apps/web` → `apps-web.md`; `.github` → `dot-github.md` (leading dot
+normalized to `dot-` so the map file is never hidden). The manifest `path` keeps the
+leading dot for git drift tracking.
+
+## When To Consult
+
+### cbp-task-planner — Phase 3: Check Rules and Architecture
+
+Before finalizing scope for the target module(s), check whether a map exists:
+
+1. Glob `.claude/architecture/<module-slug>.md` for each module in scope.
+2. If found, read the map file — sections 1–4 + 6–7 give structural context that reduces
+   the need for broad file-system scans; section 5 (deep maps) gives data-flow traces.
+3. Use the `## 4. Dependencies (In / Out)` section to identify cross-module impact that
+   the planner's Explore subagent might otherwise miss.
+
+### cbp-round-executor — Step 2.4: Architecture Map Consultation
+
+Before editing files in a module, check whether a map exists:
+
+1. Glob `.claude/architecture/<module-slug>.md` for the module being edited.
+2. If found, read the relevant sections before making changes — `## 7. Where-Things-Live
+   Landmarks` is the fastest orientation; `## 3. Internal Structure` disambiguates layout.
+3. The map is a pre-computed index — reading it replaces N individual file-reads for the
+   same structural signal.
+
+## How To Read
+
+```bash
+# Check whether a map exists for a module
+Glob: .claude/architecture/<module-slug>.md
+
+# Read the map
+Read: .claude/architecture/<module-slug>.md
+
+# Browse all mapped modules
+Read: .claude/architecture/INDEX.md
+
+# Inspect cross-module dependencies
+Read: .claude/architecture/graph.md
+```
+
+Parse sections per the spec in `context/architecture/arch-map-spec.md`:
+the 7 canonical section headings are `## 1. Boundaries & Responsibility` through
+`## 7. Where-Things-Live Landmarks`. A `skeleton` map omits `## 5. Data-Flow Traces`.
+
+YAML frontmatter fields: `module`, `generated_from_sha`, `depth`, `generated_at`,
+`source_globs`. Check `generated_from_sha` against HEAD if you need to know whether the
+map is stale (or run `codebyplan arch-map drift`).
+
+## If No Map Exists
+
+The map is **not a prerequisite** — its absence is NOT a blocker for planning or execution.
+
+- Proceed with the standard file-system analysis (Explore subagent / Read + Grep).
+- Optionally note in your output that `/cbp-map-architecture --module <path>` would
+  pre-compute structural context for future rounds.
+- Do NOT fail or block solely because a map is missing.
+
+## Agent Consumption Contract
+
+| Agent | Phase / Step | Action |
+|-------|-------------|--------|
+| `cbp-task-planner` | Phase 3 — Check Rules and Architecture | Glob for map; read if present before finalizing scope |
+| `cbp-round-executor` | Step 2.4 — Architecture Map Consultation | Glob for map; read if present before editing files in module |
+
+Both agents follow the same read-or-skip pattern: Glob → if found, Read → use signal;
+if absent, continue without blocking.
+
+## What This File Is NOT
+
+- Not the artifact format spec — that is `context/architecture/arch-map-spec.md`.
+- Not how to generate maps — use `/cbp-map-architecture` (map all/selected modules).
+- Not how to refresh stale maps — use `/cbp-refresh-arch-map` (drift-scoped refresh).
+- Not a substitute for reading the actual source files — the map is a pre-computed index,
+  not a replacement for code inspection when fine-grained detail is needed.
+
+## Related
+
+| Concern | Reference |
+|---------|-----------|
+| Artifact format spec | `context/architecture/arch-map-spec.md` |
+| Generate / regenerate maps | `/cbp-map-architecture` skill |
+| Refresh only drifted modules | `/cbp-refresh-arch-map` skill (TASK-3) |
+| CLI subcommands | `codebyplan arch-map status \| drift \| stamp` |
+| Always-loaded pointer rule | `.claude/rules/architecture-map.md` |
+| Loading rule registration | `.claude/rules/context-file-loading.md` |

package/templates/hooks/validate-structure.sh

@@ -48,9 +48,10 @@ esac
 FILENAME=$(basename "$FILE_PATH" ".$EXT")
 
 if match_path '^/(\.claude|docs)/'; then
-  # Skip special naming patterns (SKILL/AGENT/CLAUDE/MEMORY/TASK-N/CHK-NNN/date/week-N/research phase/README)
+  # Skip special naming patterns (SKILL/AGENT/CLAUDE/MEMORY/TASK-N/CHK-NNN/date/week-N/research phase/README/INDEX)
   # CHK formats: CHK-001 (generic) or CHK-H001/CHK-A001/CHK-B001 (launch: Homepage/Application/Backdoor)
-  if ! echo "$FILENAME" | grep -qE '^(SKILL|AGENT|CLAUDE|MEMORY|TASK-[1-9]|[0-9]{2}-[0-9]{2}-[0-9]{2}-CHK-([0-9]{3}|[HAB][0-9]{3})|CHK-([0-9]{3}|[HAB][0-9]{3})|[0-9]{2}-[0-9]{2}-[0-9]{2}|week-[0-9]+|[1-8]-|README)'; then
+  # INDEX: grep-native registry filename used by the architecture-map pipeline (.claude/architecture/INDEX.md) and vendor docs
+  if ! echo "$FILENAME" | grep -qE '^(SKILL|AGENT|CLAUDE|MEMORY|TASK-[1-9]|[0-9]{2}-[0-9]{2}-[0-9]{2}-CHK-([0-9]{3}|[HAB][0-9]{3})|CHK-([0-9]{3}|[HAB][0-9]{3})|[0-9]{2}-[0-9]{2}-[0-9]{2}|week-[0-9]+|[1-8]-|README|INDEX)'; then
     if echo "$FILENAME" | grep -qE '[A-Z]|_'; then
       block "Filename must be kebab-case (lowercase with hyphens)" "Got: $FILENAME, Expected: $(echo "$FILENAME" | tr '[:upper:]' '[:lower:]' | tr '_' '-')"
     fi

package/templates/rules/architecture-map.md

@@ -0,0 +1,30 @@
+---
+scope: org-shared
+---
+
+# Architecture Map
+
+When `.claude/architecture/` exists in this repo, per-module map files may be present.
+
+## Rule
+
+- Before analyzing or editing files in a module, Glob `.claude/architecture/<module-slug>.md`.
+- If a map file exists, read it before proceeding — it provides pre-computed structural
+  context (boundaries, public surface, internal layout, dependencies, landmarks) that
+  reduces the need for broad file-system scans.
+- Map absence is **not a blocker** — continue with standard file-system analysis when no
+  map exists.
+- The full consultation contract (when to read, how to parse, agent phases) is at
+  `.claude/context/architecture-map.md`.
+
+## Why
+
+Architecture maps are pre-computed indexes of module structure. Reading one replaces
+several individual file-reads and surfaces cross-module impact that point-in-time grep
+may miss. A 10-second read prevents a scoping gap.
+
+## Generate / Refresh
+
+- `/cbp-map-architecture` — generate or regenerate maps for all/selected modules.
+- `/cbp-refresh-arch-map` — drift-scoped refresh (re-runs only stale modules).
+- `codebyplan arch-map status` — list modules and their map freshness.

package/templates/rules/context-file-loading.md

@@ -23,6 +23,9 @@ paths:
 | `context/testing/eslint.md` | `cbp-improve-round` | Phase 1.5 | Config-file compliance audit |
 | `context/mcp-docs.md` | `cbp-task-planner` | Phase 2.6 | MCP library doc lookup contract — per-dependency consultation via DocsByPlan MCP tools (resolve_library_id → search_chunks/lookup_symbol → get_chunk) |
 | `context/mcp-docs.md` | `cbp-round-executor` | Step 3.4 | Library-specific reference — pre-write API verification via DocsByPlan MCP tools |
+| `context/architecture/arch-map-spec.md` | `cbp-map-architecture` | Entry | Canonical architecture-map artifact format — per-module frontmatter + sections, INDEX.md row format, dependency-graph format |
+| `context/architecture-map.md` | `cbp-task-planner` | Phase 3 | Architecture map consultation contract — when + how to read per-module maps before finalizing scope |
+| `context/architecture-map.md` | `cbp-round-executor` | Step 2.4 | Architecture map consultation contract — when + how to read per-module maps before editing files |
 | `rules/parallel-waves.md` | `cbp-task-planner` | Phase 5.6 | Wave schema, invariants (3..15 file-count), and the proximity-split algorithm (a `rules/` file, not `context/**`; listed here for consumer discoverability) |
 
 New context files MUST be added here in the same change that introduces the consumer — or the file is orphan infrastructure.

package/templates/rules/supabase-branch-lifecycle.md

@@ -80,7 +80,7 @@ Skills that delete Supabase branches MUST:
 
 1. Verify the branch name matches the feat branch being removed (never delete by
    `project_ref` alone).
-2. Never delete the parent/production project (`rrvtrumtkhrsbhcyrwvf`) itself.
+2. Never delete the branch where `is_default` is true in the `list_branches` response (the parent/production branch) or any other persistent/long-lived branch.
 3. Never delete a persistent/long-lived branch that does not correspond to the git branch
    being torn down.
 

package/templates/settings.project.base.json

@@ -110,7 +110,9 @@
       "Skill(cbp-git-commit)",
       "Skill(cbp-git-worktree-create)",
       "Skill(cbp-git-worktree-remove)",
+      "Skill(cbp-map-architecture)",
       "Skill(cbp-merge-main)",
+      "Skill(cbp-refresh-arch-map)",
       "Skill(cbp-refresh-infra)",
       "Skill(cbp-round-check)",
       "Skill(cbp-round-end)",
@@ -199,7 +201,9 @@
       "Bash(codebyplan bump:*)",
       "Bash(npx codebyplan bump:*)",
       "Bash(codebyplan scaffold-publish-workflow:*)",
-      "Bash(npx codebyplan scaffold-publish-workflow:*)"
+      "Bash(npx codebyplan scaffold-publish-workflow:*)",
+      "Bash(codebyplan arch-map:*)",
+      "Bash(npx codebyplan arch-map:*)"
     ]
   },
   "attribution": {

package/templates/skills/cbp-checkpoint-end/SKILL.md

@@ -166,12 +166,13 @@ Only after both the local and remote git delete above succeed, run a conditional
 
 > Lifecycle contract: see [[supabase-branch-lifecycle]].
 
-- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Resolve the parent project ref: read `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`; if absent or empty, read the first line of `supabase/.temp/project-ref`. Use that resolved ref as the `project_id`.
+- Call `mcp__supabase__list_branches` with the resolved `project_id`.
 - Scan the returned list for an entry whose `name` exactly equals `$BRANCH`.
 - If found: call `mcp__supabase__delete_branch` with its `branch_id`. Record the branch name in `SUPABASE_BRANCHES_DELETED[]`.
 - If not found: no-op silently — the GitHub integration may have already removed it on PR close; not-found is success, NOT an error.
 - If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$BRANCH` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
-- Never delete the parent project `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+- Never delete the branch where `is_default` is true in the `list_branches` response (the production/parent project branch) or any other persistent/long-lived branch.
 
 Accumulate all Supabase branch names removed across the loop in `SUPABASE_BRANCHES_DELETED`.
 
@@ -198,11 +199,13 @@ git push origin --delete "$FEAT_BRANCH"
 
 After the feat branch git delete, run the same conditional Supabase teardown for `$FEAT_BRANCH`:
 
-- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Resolve the parent project ref: read `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`; if absent or empty, read the first line of `supabase/.temp/project-ref`. Use that resolved ref as the `project_id`.
+- Call `mcp__supabase__list_branches` with the resolved `project_id`.
 - Scan for an entry whose `name` exactly equals `$FEAT_BRANCH`.
 - If found: call `mcp__supabase__delete_branch` with its `branch_id`. Add `$FEAT_BRANCH` to `SUPABASE_BRANCHES_DELETED[]`.
 - If not found: no-op silently — idempotent, not-found is success.
 - If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$FEAT_BRANCH` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
+- Never delete the branch where `is_default` is true in the `list_branches` response (the production/parent project branch) or any other persistent/long-lived branch.
 
 ### Step 10: Save Shipment Results and Summary
 

package/templates/skills/cbp-git-worktree-remove/SKILL.md

@@ -135,12 +135,13 @@ After the git branch delete succeeds, run a conditional Supabase preview-branch
 
 > Lifecycle contract: see [[supabase-branch-lifecycle]].
 
-- Call `mcp__supabase__list_branches` with `project_id: rrvtrumtkhrsbhcyrwvf`.
+- Resolve the parent project ref: read `.codebyplan/shipment.json` `.shipment.surfaces.supabase.project_ref`; if absent or empty, read the first line of `supabase/.temp/project-ref`. Use that resolved ref as the `project_id`.
+- Call `mcp__supabase__list_branches` with the resolved `project_id`.
 - Scan the returned list for an entry whose `name` exactly equals `$BRANCH_NAME`.
 - If found: call `mcp__supabase__delete_branch` with its `branch_id`. Report "Supabase preview branch deleted: `$BRANCH_NAME`".
 - If not found: no-op silently — the GitHub integration may have already removed it on PR close; not-found is success, NOT an error.
 - If the `list_branches` call itself fails (network, auth, or a non-success response — distinct from a successful lookup that returns no match): emit a non-blocking warning that the Supabase preview branch for `$BRANCH_NAME` may still exist and should be verified in the dashboard. Do not treat an API failure as a not-found success.
-- Never delete the parent project `rrvtrumtkhrsbhcyrwvf` itself or any persistent/production branch.
+- Never delete the branch where `is_default` is true in the `list_branches` response (the production/parent project branch) or any other persistent/long-lived branch.
 
 ### Step 10: Show Result