codebyplan 1.5.1 → 1.8.0

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

@@ -0,0 +1,67 @@
+#!/bin/bash
+# Validate a Claude Code subagent file (CBP folder form).
+# Usage: validate-agent.sh <path-to-AGENT.md>
+# Exit 0 = valid, exit 1 = invalid (errors printed to stderr).
+
+set -uo pipefail
+
+FILE="${1:?Usage: validate-agent.sh <path-to-AGENT.md>}"
+
+if [ ! -f "$FILE" ]; then
+  echo "ERROR: file not found: $FILE" >&2
+  exit 1
+fi
+
+errors=0
+err() { echo "  - $1" >&2; errors=$((errors + 1)); }
+
+# CBP folder form: .claude/agents/{name}/AGENT.md
+case "$FILE" in
+  */AGENT.md) ;;
+  *) err "CBP expects folder form: .claude/agents/{name}/AGENT.md (got: $FILE)";;
+esac
+
+# Frontmatter must be present
+if ! head -1 "$FILE" | grep -qE '^---[[:space:]]*$'; then
+  err "missing YAML frontmatter opener '---'"
+fi
+
+# Extract frontmatter block
+fm=$(awk '/^---[[:space:]]*$/{n++; next} n==1{print} n==2{exit}' "$FILE")
+
+# Required fields
+grep -qE '^name:[[:space:]]*' <<< "$fm" || err "missing required field: name"
+grep -qE '^description:[[:space:]]*' <<< "$fm" || err "missing required field: description"
+grep -qE '^scope:[[:space:]]*' <<< "$fm" || err "missing CBP required field: scope (org-shared|project-shared|repo-only:<repo-name>)"
+
+# Name format: kebab-case
+name=$(grep -E '^name:' <<< "$fm" | head -1 | sed -E 's/^name:[[:space:]]*//; s/[[:space:]]*$//; s/^"(.*)"$/\1/' || true)
+if [ -n "$name" ] && ! [[ "$name" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]]; then
+  err "name must be kebab-case (lowercase, hyphens): got '$name'"
+fi
+
+# Model alias check (if present)
+model=$(grep -E '^model:' <<< "$fm" | head -1 | sed -E 's/^model:[[:space:]]*//; s/[[:space:]]*$//; s/^"(.*)"$/\1/' || true)
+if [ -n "$model" ] && [[ ! "$model" =~ ^(sonnet|opus|haiku|inherit|claude-.+)$ ]]; then
+  err "model must be alias (sonnet|opus|haiku|inherit) or full ID (claude-*): got '$model'"
+fi
+
+# Permission mode check (if present)
+pm=$(grep -E '^permissionMode:' <<< "$fm" | head -1 | sed -E 's/^permissionMode:[[:space:]]*//; s/[[:space:]]*$//; s/^"(.*)"$/\1/' || true)
+if [ -n "$pm" ] && [[ ! "$pm" =~ ^(default|acceptEdits|auto|dontAsk|bypassPermissions|plan)$ ]]; then
+  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
+fi
+
+echo "validation OK: $FILE"
+exit 0

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

@@ -0,0 +1,66 @@
+---
+scope: org-shared  # CBP sync marker: org-shared | project-shared | repo-only:<repo-name>
+name: agent-name
+description: One sentence describing when Claude should delegate to this agent. Write for matching, not for humans. Include trigger phrases.
+tools: Read, Grep, Glob, Bash
+# disallowedTools: Write, Edit  # alternative to tools — inherits then removes
+# review with /cbp-build-cc-mode if defaults don't fit this agent's purpose
+model: sonnet
+# permissionMode: default  # default | acceptEdits | auto | dontAsk | bypassPermissions | plan
+# maxTurns: 20
+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
+# mcpServers:
+#   - github
+#   - playwright:
+#       type: stdio
+#       command: npx
+#       args: ["-y", "@playwright/mcp@latest"]
+# hooks:
+#   PreToolUse:
+#     - matcher: "Bash"
+#       hooks:
+#         - type: command
+#           command: "./scripts/validate-command.sh"
+#   PostToolUse:
+#     - matcher: "Edit|Write"
+#       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
+---
+
+You are a [role] specialising in [domain].
+
+## When invoked
+
+1. [First action — often: read diff, list files, query status]
+2. [Second action]
+3. [Third action]
+
+## Workflow
+
+- [Step-by-step procedure the agent follows]
+- [Keep concrete — name the tools and patterns it uses]
+
+## Output format
+
+Return:
+
+- **Summary** — one sentence
+- **Findings** — bulleted list with file:line references
+- **Recommendations** — ordered by priority (critical / warning / suggestion)
+
+## Failure modes
+
+| Condition | Action |
+|-----------|--------|
+| Requirements unclear | Return `blocked` with what's missing |
+| No matching files | Return `no_findings` |
+| Unrecoverable error | Return `failed` with the error message |

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

@@ -0,0 +1,178 @@
+---
+scope: org-shared
+name: cbp-build-cc-claude-file
+description: Create or update a CLAUDE.md file at any scope (managed, project, user, local) following the official memory spec — imports (@path), nested discovery, AGENTS.md bridge, comment stripping, and claudeMdExcludes.
+argument-hint: "[action] [--scope=managed|project|user|local]"
+allowed-tools: Read, Write, Edit, Glob, Grep
+effort: xhigh
+---
+
+# Build CLAUDE.md File
+
+Create or update a CLAUDE.md file per the official Claude Code memory spec (section _CLAUDE.md files_). CLAUDE.md is loaded in full at session start for every matching directory walked from the working directory. Nested files load on-demand when Claude reads files in subdirectories.
+
+## Arguments
+
+`$ARGUMENTS` — action: `create`, `update`, `check`, `init`. Flag: `--scope=managed|project|user|local` (default `project`).
+
+Actions:
+
+- `create` — new CLAUDE.md at the scope path
+- `update` — modify existing CLAUDE.md
+- `check` — audit for duplication with rules/context and report fixes
+- `init` — defer to Claude Code's built-in `/init` for first-time setup
+
+## When to Use
+
+- First-time project onboarding → `/init` (not this skill)
+- 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)
+
+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
+
+### Step 1 — Pick the scope
+
+| Scope            | Path                                                                                                                                               | Use for                              |
+| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
+| managed          | `/Library/Application Support/ClaudeCode/CLAUDE.md` (mac), `/etc/claude-code/CLAUDE.md` (linux/WSL), `C:\Program Files\ClaudeCode\CLAUDE.md` (win) | IT/DevOps policy, cannot be excluded |
+| project (shared) | `./CLAUDE.md` or `./.claude/CLAUDE.md`                                                                                                             | Team-shared via git                  |
+| user             | `~/.claude/CLAUDE.md`                                                                                                                              | Personal, all projects               |
+| local            | `./CLAUDE.local.md` (gitignored)                                                                                                                   | Personal, this project               |
+
+Default: project. Either `./CLAUDE.md` or `./.claude/CLAUDE.md` works; pick one and stick to it.
+
+### Step 2 — Read existing CLAUDE.md (for update/check)
+
+```bash
+cat .claude/CLAUDE.md 2>/dev/null || cat ./CLAUDE.md 2>/dev/null
+```
+
+Also list sibling rules for duplication check:
+
+```bash
+ls .claude/rules/
+```
+
+### Step 3 — Decide what belongs in CLAUDE.md
+
+Read [reference/what-belongs.md](reference/what-belongs.md) — definitive table.
+
+Quick gate: "Will Claude make a mistake without this in the context?" Every line competes for context window space — keep it high-signal.
+
+| Belongs in CLAUDE.md                   | Belongs elsewhere                            |
+| -------------------------------------- | -------------------------------------------- |
+| Project name, production URL, repo IDs | API endpoint docs → `docs/`                  |
+| Branch strategy one-liner              | Full git workflow → `rules/git-workflow.md`  |
+| Command list (name + purpose)          | Command implementation → `skills/*/SKILL.md` |
+| "DB is source of truth"                | DB schema → `docs/architecture/`             |
+| Tech stack summary                     | Framework deep-dives → `docs/stack/`         |
+
+**No duplication.** CLAUDE.md should **reference**, not **repeat**. If a rule or context file covers the topic, CLAUDE.md gets a one-liner pointing to it.
+
+**Keep it stable.** If you're updating CLAUDE.md every task, the content probably belongs in a rule or skill. CLAUDE.md changes should be: new project-level decisions (tech stack, deployment), new key references (repo ID, URL), or command table updates when a skill is added/removed. Workflow details, testing patterns, and style conventions go in rules or `.claude/docs/`.
+
+### Step 4 — Apply structure
+
+Target under 200 lines. Use markdown headers and bullets (Claude scans structure like readers).
+
+Recommended section order:
+
+1. **Project** — name, type, production URL
+2. **Tech Stack** — framework, language, DB, deployment
+3. **Structure** — key directories or monorepo packages
+4. **Key References** — repo IDs, URLs, auth method
+5. **Git** — branch strategy one-liner, attribution rules
+6. **Workflow** — entry point command + pointer to rule file
+
+See [templates/project-claude-md.md](templates/project-claude-md.md).
+
+### Step 5 — Use imports to split large files
+
+When content grows, use `@path/to/file` imports to load additional files at launch:
+
+```markdown
+See @README.md for project overview and @package.json for npm commands.
+
+# Additional Instructions
+
+- git workflow @docs/git-instructions.md
+- testing patterns @docs/testing.md
+```
+
+Rules:
+
+- Relative paths resolve relative to the file containing the import
+- Absolute paths allowed
+- Recursive imports up to 5 hops deep
+- First-time imports from outside the repo trigger an approval dialog
+
+Full reference: [reference/imports.md](reference/imports.md).
+
+### Step 6 — Bridge to AGENTS.md if the project uses it
+
+If the repo already has `AGENTS.md` for other coding agents:
+
+```markdown filename="CLAUDE.md"
+@AGENTS.md
+
+## Claude Code
+
+[Claude-specific additions below the import]
+```
+
+Claude Code reads CLAUDE.md, not AGENTS.md, so the import ensures both tools see the same instructions.
+
+### Step 7 — Use block-level HTML comments for maintainer notes
+
+Comments are stripped before Claude sees the content:
+
+```markdown
+<!-- maintainer: review this section quarterly; @alice is owner -->
+
+## Tech Stack
+```
+
+Comments inside code blocks are preserved. Use freely for context that humans need but tokens shouldn't burn.
+
+### Step 8 — For monorepos, manage excludes
+
+Other teams' CLAUDE.md files in the ancestor tree get picked up by default. Exclude them via `claudeMdExcludes` in `.claude/settings.local.json`:
+
+```json
+{
+  "claudeMdExcludes": [
+    "**/other-team/CLAUDE.md",
+    "/home/user/monorepo/platform/.claude/rules/**"
+  ]
+}
+```
+
+Managed policy CLAUDE.md cannot be excluded.
+
+### Step 9 — Verify with `/memory`
+
+Run `/memory` to confirm the file is loaded. The list shows all CLAUDE.md, CLAUDE.local.md, and rules files in effect.
+
+## Integration
+
+- **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`)
+
+## Key Rules
+
+- CLAUDE.md content enters as a user message (not system prompt) — no guarantee of strict compliance. Be specific
+- Target under 200 lines. Longer files reduce adherence
+- Project-root CLAUDE.md survives compaction. Nested files do not — they reload when Claude next reads a matching subdirectory file
+- Specific > vague: "Use 2-space indentation" beats "format code nicely"
+- Path resolution walks up from the working directory — instructions concatenate, don't override
+- CLAUDE.local.md is appended after CLAUDE.md at each level. Personal notes win on conflict at the same level
+- Block HTML comments are stripped but preserved inside code blocks

package/templates/skills/cbp-build-cc-claude-file/examples/minimal-project.md

@@ -0,0 +1,33 @@
+# CLAUDE.md
+
+## Project
+
+**Name**: acme-api
+**Type**: Python FastAPI service
+**Production**: https://api.acme.com
+
+## Stack
+
+- Python 3.12, FastAPI, Pydantic v2
+- PostgreSQL (`asyncpg`), Alembic migrations
+- Deployed on Fly.io
+
+## Commands
+
+| Task | Command |
+|------|---------|
+| Install | `uv sync` |
+| Dev server | `uv run fastapi dev` |
+| Tests | `uv run pytest` |
+| Migrations | `uv run alembic upgrade head` |
+
+## Conventions
+
+- 2-space indentation (enforced by ruff)
+- All endpoints under `src/api/v1/` with a matching test in `tests/api/v1/`
+- Errors return `{"error": {"code": str, "message": str}}` — never raw exceptions
+
+## Git
+
+- Branch: `feat/* → main`
+- Rebase, never merge. No force-pushes to `main`.

package/templates/skills/cbp-build-cc-claude-file/examples/monorepo-with-imports.md

@@ -0,0 +1,39 @@
+# CLAUDE.md
+
+<!-- Monorepo: see each package's nested CLAUDE.md for package-specific details -->
+
+## Project
+
+**Name**: acme-platform
+**Type**: pnpm + Turborepo monorepo
+**Production**: https://acme.com
+
+## Packages
+
+| Path | Package | Purpose |
+|------|---------|---------|
+| `apps/web` | `@acme/web` | Marketing + app shell |
+| `apps/api` | `@acme/api` | NestJS backend |
+| `packages/ui` | `@acme/ui` | Shared component library |
+| `packages/db` | `@acme/db` | Prisma client + migrations |
+
+Each package has its own `CLAUDE.md` loaded on-demand when Claude touches files in that directory.
+
+## Shared standards
+
+- Conventions @docs/conventions.md
+- Testing @docs/testing.md
+- Commit format @docs/commits.md
+
+## Commands
+
+- Install: `pnpm install`
+- Build all: `pnpm -r build`
+- Test: `pnpm -r test`
+- Lint: `pnpm -r lint`
+
+## Git
+
+- `feat/*` → `main`
+- PR preview reviewed before merge
+- Attribution policy: @docs/attribution.md

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

@@ -0,0 +1,72 @@
+# CLAUDE.md Imports Reference
+
+Source: official Claude Code memory spec — *Import additional files*.
+
+## Syntax
+
+```markdown
+@path/to/file
+```
+
+Imports expand and load at launch, merged into context alongside the importing CLAUDE.md.
+
+## Path resolution
+
+- **Relative**: resolves relative to the file containing the import (not the working directory)
+- **Absolute**: accepted
+- **Tilde**: `@~/.claude/my-notes.md` resolves to home
+
+## Depth
+
+Imports may recursively import. **Max depth: 5 hops.**
+
+## Common patterns
+
+### Pull in repo metadata
+
+```markdown
+See @README.md for overview and @package.json for npm commands.
+```
+
+### Sectioned additions
+
+```markdown
+## Additional Instructions
+
+- Git workflow @docs/git-instructions.md
+- Testing patterns @docs/testing.md
+```
+
+### Cross-worktree personal instructions
+
+CLAUDE.local.md is gitignored and only exists in the worktree where you created it. To share personal notes across worktrees, import from home:
+
+```markdown
+# Individual Preferences
+- @~/.claude/my-project-instructions.md
+```
+
+### AGENTS.md bridge
+
+```markdown
+@AGENTS.md
+
+## Claude Code
+
+[Claude-specific additions here]
+```
+
+## Approval dialog
+
+The first time Claude Code sees an **external** import (outside the project), it prompts for approval. Declining disables imports in that project; the dialog does not reappear.
+
+## What gets imported
+
+- Markdown files — content merged into context
+- Any readable file — the whole content is injected
+
+## Troubleshooting
+
+- Import not appearing → verify path resolves from the *file containing the import*, not the working directory
+- Dialog not showing → check if you previously declined (run `/memory` to review loaded files)
+- Exceeded depth → reduce the chain; re-flatten hierarchy

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

@@ -0,0 +1,39 @@
+# What Belongs in CLAUDE.md
+
+Source: official Claude Code memory spec — *Write effective instructions*.
+
+## Put it in CLAUDE.md when
+
+- Claude would make the same mistake a second time without it
+- A code review caught something Claude should have known
+- You find yourself retyping the same correction each session
+- A new teammate would need this context to be productive
+
+## Keep it OUT of CLAUDE.md when
+
+| Content type | Put here instead |
+|-------------|------------------|
+| 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/`) |
+| API endpoint documentation | `docs/` |
+| Architecture deep-dive | `docs/architecture/` |
+| Framework usage guide | `docs/stack/{framework}/` |
+| Ephemeral task state | Task tracker / DB / issue |
+
+## Quality gates
+
+- **Size**: under 200 lines. Longer files reduce adherence
+- **Specificity**: "Use 2-space indentation" > "format nicely"
+- **Consistency**: conflicting rules get picked arbitrarily — remove one
+- **Stability**: updating CLAUDE.md every task is a smell. Content probably belongs in a rule or context file
+
+## What CLAUDE.md is for
+
+Instructions and rules for the project. Written by humans, for Claude, to hold every session.
+
+## What it isn't
+
+- Not a style guide anyone reads — it's context, not documentation
+- Not enforced configuration — instructions shape behaviour but don't block Claude
+- Not a substitute for `settings.json` deny rules, which ARE enforced

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

@@ -0,0 +1,48 @@
+# CLAUDE.md
+
+<!-- Maintained by: @owner. Review quarterly. -->
+
+## Project
+
+**Name**: {project-name}
+**Type**: {e.g. Next.js monorepo, Python service, Go binary}
+**Production**: {url}
+
+## Tech Stack
+
+- **Framework**: {e.g. Next.js 15 App Router}
+- **Language**: {TypeScript / Python / Go}
+- **Styling**: {SCSS / Tailwind / CSS Modules}
+- **Database**: {e.g. PostgreSQL via Supabase}
+- **Deployment**: {Vercel / AWS / Fly.io}
+
+## Structure
+
+| Location | Purpose |
+|----------|---------|
+| `apps/web` | Web frontend |
+| `apps/api` | Backend API |
+| `packages/*` | Shared internal packages |
+
+## Key References
+
+| Item | Value |
+|------|-------|
+| Repo ID | {uuid} |
+| Production URL | {url} |
+| API auth | {header name + mechanism} |
+
+## Git
+
+- Branch strategy: `feat/* → main` (PR previews via Vercel)
+- Attribution: {policy — e.g. "no AI co-authorship"}
+- Details in `rules/git-workflow.md`
+
+## Workflow
+
+Start with `/{entry-command}`. Full pipeline in `rules/development-workflow.md`.
+
+## Additional instructions
+
+- Build commands @package.json
+- Testing guide @docs/testing.md

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

@@ -0,0 +1,22 @@
+# User-level CLAUDE.md
+
+<!-- Personal preferences. Loaded in every project on this machine. -->
+
+## Communication style
+
+- Terse. State results and decisions directly.
+- No trailing summaries of what you just did — the diff is self-explanatory.
+
+## Defaults
+
+- Prefer `pnpm` over `npm`, `ripgrep` over `grep`, `fd` over `find` where available.
+- Use `gh` CLI for GitHub interactions, not web fetches.
+
+## Editing
+
+- Never ask permission to format code.
+- Never introduce comments unless a reader would be confused without them.
+
+## Shared personal rules
+
+- Home-directory preferences @~/.claude/my-workflows.md