codebyplan 1.5.1 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. package/dist/cli.js +4462 -748
  2. package/package.json +5 -1
  3. package/templates/.gitkeep +0 -0
  4. package/templates/README.md +20 -0
  5. package/templates/agents/cbp-cc-executor.md +213 -0
  6. package/templates/agents/cbp-database-agent.md +229 -0
  7. package/templates/agents/cbp-improve-claude.md +245 -0
  8. package/templates/agents/cbp-improve-round.md +284 -0
  9. package/templates/agents/cbp-mechanical-edits.md +111 -0
  10. package/templates/agents/cbp-research.md +282 -0
  11. package/templates/agents/cbp-round-executor.md +604 -0
  12. package/templates/agents/cbp-security-agent.md +134 -0
  13. package/templates/agents/cbp-task-check.md +213 -0
  14. package/templates/agents/cbp-task-planner.md +582 -0
  15. package/templates/agents/cbp-test-e2e-agent.md +363 -0
  16. package/templates/agents/cbp-testing-qa-agent.md +400 -0
  17. package/templates/context/mcp-docs.md +139 -0
  18. package/templates/hooks/README.md +236 -0
  19. package/templates/hooks/cbp-auto-test-hooks.sh +44 -0
  20. package/templates/hooks/cbp-lint-format-on-edit.sh +159 -0
  21. package/templates/hooks/cbp-maestro-yaml-validate.sh +100 -0
  22. package/templates/hooks/cbp-mcp-migration-guard.sh +32 -0
  23. package/templates/hooks/cbp-mcp-round-sync.sh +79 -0
  24. package/templates/hooks/cbp-mcp-worktree-inject.sh +76 -0
  25. package/templates/hooks/cbp-notify.sh +68 -0
  26. package/templates/hooks/cbp-plugin-dispatch.sh +29 -0
  27. package/templates/hooks/cbp-pre-commit-quality-gate.sh +204 -0
  28. package/templates/hooks/cbp-statusline.sh +347 -0
  29. package/templates/hooks/cbp-subagent-statusline.sh +182 -0
  30. package/templates/hooks/cbp-test-coverage-gate.sh +144 -0
  31. package/templates/hooks/cbp-test-hooks.sh +320 -0
  32. package/templates/hooks/hooks.json +85 -0
  33. package/templates/hooks/validate-context-usage.sh +59 -0
  34. package/templates/hooks/validate-git-commit.sh +78 -0
  35. package/templates/hooks/validate-git-stash-deny.sh +32 -0
  36. package/templates/hooks/validate-structure-lengths.sh +57 -0
  37. package/templates/hooks/validate-structure-lib.sh +104 -0
  38. package/templates/hooks/validate-structure-patterns.sh +54 -0
  39. package/templates/hooks/validate-structure-scope.sh +33 -0
  40. package/templates/hooks/validate-structure-smoke.sh +95 -0
  41. package/templates/hooks/validate-structure-templates.sh +34 -0
  42. package/templates/hooks/validate-structure.sh +69 -0
  43. package/templates/rules/.gitkeep +0 -0
  44. package/templates/rules/README.md +47 -0
  45. package/templates/rules/context-file-loading.md +52 -0
  46. package/templates/rules/scope-vocabulary.md +64 -0
  47. package/templates/rules/todo-backend.md +109 -0
  48. package/templates/settings.project.base.json +55 -0
  49. package/templates/settings.user.base.json +25 -0
  50. package/templates/skills/cbp-build-cc-agent/SKILL.md +139 -0
  51. package/templates/skills/cbp-build-cc-agent/examples/read-only-reviewer.md +32 -0
  52. package/templates/skills/cbp-build-cc-agent/examples/with-hooks.md +41 -0
  53. package/templates/skills/cbp-build-cc-agent/examples/with-skills-preload.md +25 -0
  54. package/templates/skills/cbp-build-cc-agent/reference/cbp-quality.md +153 -0
  55. package/templates/skills/cbp-build-cc-agent/reference/frontmatter-fields.md +37 -0
  56. package/templates/skills/cbp-build-cc-agent/reference/permission-modes.md +18 -0
  57. package/templates/skills/cbp-build-cc-agent/scripts/validate-agent.sh +67 -0
  58. package/templates/skills/cbp-build-cc-agent/templates/agent.md +66 -0
  59. package/templates/skills/cbp-build-cc-claude-file/SKILL.md +178 -0
  60. package/templates/skills/cbp-build-cc-claude-file/examples/minimal-project.md +33 -0
  61. package/templates/skills/cbp-build-cc-claude-file/examples/monorepo-with-imports.md +39 -0
  62. package/templates/skills/cbp-build-cc-claude-file/reference/imports.md +72 -0
  63. package/templates/skills/cbp-build-cc-claude-file/reference/what-belongs.md +39 -0
  64. package/templates/skills/cbp-build-cc-claude-file/templates/project-claude-md.md +48 -0
  65. package/templates/skills/cbp-build-cc-claude-file/templates/user-claude-md.md +22 -0
  66. package/templates/skills/cbp-build-cc-memory/SKILL.md +201 -0
  67. package/templates/skills/cbp-build-cc-memory/examples/feedback-memory.md +11 -0
  68. package/templates/skills/cbp-build-cc-memory/examples/project-memory.md +11 -0
  69. package/templates/skills/cbp-build-cc-memory/examples/reference-memory.md +13 -0
  70. package/templates/skills/cbp-build-cc-memory/examples/user-memory.md +14 -0
  71. package/templates/skills/cbp-build-cc-memory/reference/memory-types.md +59 -0
  72. package/templates/skills/cbp-build-cc-memory/reference/when-to-save.md +62 -0
  73. package/templates/skills/cbp-build-cc-memory/templates/MEMORY-index.md +4 -0
  74. package/templates/skills/cbp-build-cc-memory/templates/memory-entry.md +15 -0
  75. package/templates/skills/cbp-build-cc-mode/SKILL.md +99 -0
  76. package/templates/skills/cbp-build-cc-rule/SKILL.md +176 -0
  77. package/templates/skills/cbp-build-cc-rule/examples/global-rule.md +19 -0
  78. package/templates/skills/cbp-build-cc-rule/examples/scoped-rule.md +41 -0
  79. package/templates/skills/cbp-build-cc-rule/reference/paths-patterns.md +48 -0
  80. package/templates/skills/cbp-build-cc-rule/templates/rule.md +32 -0
  81. package/templates/skills/cbp-build-cc-settings/SKILL.md +220 -0
  82. package/templates/skills/cbp-build-cc-settings/examples/hooks-config.json +64 -0
  83. package/templates/skills/cbp-build-cc-settings/examples/permissions-config.json +34 -0
  84. package/templates/skills/cbp-build-cc-settings/examples/sandbox-config.json +42 -0
  85. package/templates/skills/cbp-build-cc-settings/reference/cbp-conventions.md +104 -0
  86. package/templates/skills/cbp-build-cc-settings/reference/permission-rules.md +61 -0
  87. package/templates/skills/cbp-build-cc-settings/reference/scope-precedence.md +73 -0
  88. package/templates/skills/cbp-build-cc-settings/reference/settings-fields.md +166 -0
  89. package/templates/skills/cbp-build-cc-settings/templates/settings.json +23 -0
  90. package/templates/skills/cbp-build-cc-settings/templates/settings.local.json +10 -0
  91. package/templates/skills/cbp-build-cc-skill/SKILL.md +154 -0
  92. package/templates/skills/cbp-build-cc-skill/examples/dynamic-context.md +31 -0
  93. package/templates/skills/cbp-build-cc-skill/examples/fork-skill.md +22 -0
  94. package/templates/skills/cbp-build-cc-skill/examples/knowledge-skill.md +25 -0
  95. package/templates/skills/cbp-build-cc-skill/examples/task-skill.md +29 -0
  96. package/templates/skills/cbp-build-cc-skill/reference/cbp-quality.md +157 -0
  97. package/templates/skills/cbp-build-cc-skill/reference/frontmatter-fields.md +35 -0
  98. package/templates/skills/cbp-build-cc-skill/reference/string-substitutions.md +60 -0
  99. package/templates/skills/cbp-build-cc-skill/scripts/validate-skill.sh +90 -0
  100. package/templates/skills/cbp-build-cc-skill/templates/skill.md +51 -0
  101. package/templates/skills/cbp-checkpoint-check/SKILL.md +156 -0
  102. package/templates/skills/cbp-checkpoint-complete/SKILL.md +109 -0
  103. package/templates/skills/cbp-checkpoint-create/SKILL.md +287 -0
  104. package/templates/skills/cbp-checkpoint-end/SKILL.md +241 -0
  105. package/templates/skills/cbp-checkpoint-update/SKILL.md +115 -0
  106. package/templates/skills/cbp-frontend-a11y/SKILL.md +109 -0
  107. package/templates/skills/cbp-frontend-a11y/reference/aria-roles-states.md +130 -0
  108. package/templates/skills/cbp-frontend-a11y/reference/contrast-visual.md +122 -0
  109. package/templates/skills/cbp-frontend-a11y/reference/keyboard-patterns.md +154 -0
  110. package/templates/skills/cbp-frontend-a11y/reference/semantic-html.md +111 -0
  111. package/templates/skills/cbp-frontend-design/SKILL.md +145 -0
  112. package/templates/skills/cbp-frontend-design/reference/nextjs-scss.md +118 -0
  113. package/templates/skills/cbp-frontend-design/reference/rn-expo.md +101 -0
  114. package/templates/skills/cbp-frontend-design/reference/tauri-react.md +82 -0
  115. package/templates/skills/cbp-frontend-ui/SKILL.md +262 -0
  116. package/templates/skills/cbp-frontend-ui/reference/ui-label-maps.md +42 -0
  117. package/templates/skills/cbp-frontend-ui/reference/ui-layout-patterns.md +105 -0
  118. package/templates/skills/cbp-frontend-ui/reference/variant-defaults.md +149 -0
  119. package/templates/skills/cbp-frontend-ux/SKILL.md +181 -0
  120. package/templates/skills/cbp-git-branch-feat-create/SKILL.md +115 -0
  121. package/templates/skills/cbp-git-commit/SKILL.md +278 -0
  122. package/templates/skills/cbp-git-worktree-create/SKILL.md +226 -0
  123. package/templates/skills/cbp-git-worktree-remove/SKILL.md +145 -0
  124. package/templates/skills/cbp-merge-main/SKILL.md +228 -0
  125. package/templates/skills/cbp-round-check/SKILL.md +104 -0
  126. package/templates/skills/cbp-round-end/SKILL.md +183 -0
  127. package/templates/skills/cbp-round-end/reference/findings-presentation.md +44 -0
  128. package/templates/skills/cbp-round-end/reference/inline-fallback.md +35 -0
  129. package/templates/skills/cbp-round-execute/SKILL.md +211 -0
  130. package/templates/skills/cbp-round-execute/reference/inline-fallback.md +59 -0
  131. package/templates/skills/cbp-round-input/SKILL.md +165 -0
  132. package/templates/skills/cbp-round-start/SKILL.md +222 -0
  133. package/templates/skills/cbp-round-update/SKILL.md +163 -0
  134. package/templates/skills/cbp-session-end/SKILL.md +187 -0
  135. package/templates/skills/cbp-session-start/SKILL.md +155 -0
  136. package/templates/skills/cbp-ship/SKILL.md +332 -0
  137. package/templates/skills/cbp-ship/reference/changesets-overview.md +120 -0
  138. package/templates/skills/cbp-ship/reference/eas-cli-overview.md +60 -0
  139. package/templates/skills/cbp-ship/reference/gh-cli-overview.md +135 -0
  140. package/templates/skills/cbp-ship/reference/gh-cli-shipment-commands.md +283 -0
  141. package/templates/skills/cbp-ship/reference/npm-publish-monorepo.md +252 -0
  142. package/templates/skills/cbp-ship/reference/npm-publish-oidc-trusted.md +157 -0
  143. package/templates/skills/cbp-ship/reference/npm-publish-overview.md +171 -0
  144. package/templates/skills/cbp-ship/reference/preflight-checklist.md +88 -0
  145. package/templates/skills/cbp-ship/reference/railway-nestjs-deployment.md +169 -0
  146. package/templates/skills/cbp-ship/reference/railway-overview.md +120 -0
  147. package/templates/skills/cbp-ship/reference/railway-troubleshooting.md +168 -0
  148. package/templates/skills/cbp-ship/reference/release-please-overview.md +99 -0
  149. package/templates/skills/cbp-ship/reference/surface-expo-eas.md +155 -0
  150. package/templates/skills/cbp-ship/reference/surface-npm.md +180 -0
  151. package/templates/skills/cbp-ship/reference/surface-railway.md +152 -0
  152. package/templates/skills/cbp-ship/reference/surface-supabase.md +178 -0
  153. package/templates/skills/cbp-ship/reference/surface-tauri.md +138 -0
  154. package/templates/skills/cbp-ship/reference/surface-vercel.md +124 -0
  155. package/templates/skills/cbp-ship/reference/surface-vscode-ext.md +144 -0
  156. package/templates/skills/cbp-ship/reference/surfaces.md +60 -0
  157. package/templates/skills/cbp-ship/reference/testflight-automation.md +215 -0
  158. package/templates/skills/cbp-ship/reference/testflight-internal-vs-external.md +69 -0
  159. package/templates/skills/cbp-ship/reference/testflight-overview.md +98 -0
  160. package/templates/skills/cbp-ship/reference/versioning.md +116 -0
  161. package/templates/skills/cbp-ship/scripts/detect-surfaces.sh +217 -0
  162. package/templates/skills/cbp-ship/scripts/verify-expo-eas.sh +35 -0
  163. package/templates/skills/cbp-ship/scripts/verify-npm.sh +21 -0
  164. package/templates/skills/cbp-ship/scripts/verify-railway.sh +41 -0
  165. package/templates/skills/cbp-ship/scripts/verify-supabase.sh +19 -0
  166. package/templates/skills/cbp-ship/scripts/verify-tauri.sh +24 -0
  167. package/templates/skills/cbp-ship/scripts/verify-vercel.sh +32 -0
  168. package/templates/skills/cbp-ship/scripts/verify-vscode-ext.sh +25 -0
  169. package/templates/skills/cbp-ship/templates/eas.json +66 -0
  170. package/templates/skills/cbp-ship/templates/railway.toml +15 -0
  171. package/templates/skills/cbp-ship/templates/release-please-config.json +17 -0
  172. package/templates/skills/cbp-ship/templates/vercel.json +19 -0
  173. package/templates/skills/cbp-ship/templates/vscodeignore +21 -0
  174. package/templates/skills/cbp-ship/templates/workflow-changesets.yml +41 -0
  175. package/templates/skills/cbp-ship/templates/workflow-eas-submit.yml +53 -0
  176. package/templates/skills/cbp-ship/templates/workflow-npm-publish.yml +36 -0
  177. package/templates/skills/cbp-ship/templates/workflow-release-please.yml +21 -0
  178. package/templates/skills/cbp-ship/templates/workflow-tauri-release.yml +69 -0
  179. package/templates/skills/cbp-ship/templates/workflow-vsce-publish.yml +31 -0
  180. package/templates/skills/cbp-ship-configure/SKILL.md +296 -0
  181. package/templates/skills/cbp-ship-configure/reference/expo-mobile.md +204 -0
  182. package/templates/skills/cbp-ship-configure/reference/npm-package.md +165 -0
  183. package/templates/skills/cbp-ship-configure/reference/railway-backend.md +199 -0
  184. package/templates/skills/cbp-ship-configure/reference/supabase.md +200 -0
  185. package/templates/skills/cbp-ship-configure/reference/tauri-desktop.md +181 -0
  186. package/templates/skills/cbp-ship-configure/reference/vercel.md +117 -0
  187. package/templates/skills/cbp-ship-configure/reference/vscode-ext.md +155 -0
  188. package/templates/skills/cbp-ship-main/SKILL.md +65 -0
  189. package/templates/skills/cbp-supabase-branch-check/SKILL.md +337 -0
  190. package/templates/skills/cbp-supabase-branch-check/reference/dag-steps.md +29 -0
  191. package/templates/skills/cbp-supabase-migrate/SKILL.md +314 -0
  192. package/templates/skills/cbp-supabase-migrate/reference/advisor-triage.md +70 -0
  193. package/templates/skills/cbp-supabase-migrate/reference/cli-fallback.md +87 -0
  194. package/templates/skills/cbp-supabase-migrate/reference/preflight-dry-run.md +58 -0
  195. package/templates/skills/cbp-supabase-setup/SKILL.md +239 -0
  196. package/templates/skills/cbp-supabase-setup/reference/branching-setup.md +121 -0
  197. package/templates/skills/cbp-supabase-setup/reference/cli-fallback.md +109 -0
  198. package/templates/skills/cbp-task-check/SKILL.md +166 -0
  199. package/templates/skills/cbp-task-complete/SKILL.md +206 -0
  200. package/templates/skills/cbp-task-complete/reference/checkpoint-done-branching.md +48 -0
  201. package/templates/skills/cbp-task-complete/reference/next-step-heuristic.md +56 -0
  202. package/templates/skills/cbp-task-create/SKILL.md +167 -0
  203. package/templates/skills/cbp-task-start/SKILL.md +239 -0
  204. package/templates/skills/cbp-task-testing/SKILL.md +277 -0
  205. package/templates/skills/cbp-todo/SKILL.md +97 -0
@@ -0,0 +1,176 @@
1
+ ---
2
+ scope: org-shared
3
+ name: cbp-build-cc-rule
4
+ description: Build a path-scoped rule file at .claude/rules/{name}.md following the official memory/rules spec (paths globs, always-loaded vs on-demand, symlinks) plus CBP conventions (required scope field for structural classification (validate-structure-scope.sh), narrow-paths discipline; hook warns at 100 lines, blocks at 200).
5
+ argument-hint: '[name] [--scope=project|user] [--paths="glob,glob"]'
6
+ allowed-tools: Read, Write, Edit, Glob, Grep
7
+ effort: xhigh
8
+ ---
9
+
10
+ # Build Claude Code Rule
11
+
12
+ Create a rule at `.claude/rules/{name}.md` per the official Claude Code memory spec (section: _Organize rules with .claude/rules/_). Rules are auto-loaded instructions — either at session start (unconditional) or when Claude reads files matching `paths:` (scoped).
13
+
14
+ ## Arguments
15
+
16
+ `$ARGUMENTS` — rule name (kebab-case). Flags: `--scope=project|user` (default `project`), `--paths="apps/*/src/api/**/*.ts,supabase/migrations/**/*.sql"`.
17
+
18
+ ## When to Use
19
+
20
+ - Instruction applies broadly and should be loaded every session → global rule
21
+ - Instruction applies only to specific file types/directories → path-scoped rule
22
+ - Instruction is short, factual, and behavioural
23
+
24
+ **Do NOT use this skill for:**
25
+
26
+ - Step-by-step workflows → use `/cbp-build-cc-skill` (loads on invoke, doesn't burn context)
27
+ - Project-level facts always needed → CLAUDE.md (use `/cbp-build-cc-claude-file`)
28
+ - Accumulating learnings → auto memory (use `/cbp-build-cc-memory`)
29
+
30
+ ## Instructions
31
+
32
+ ### Step 1 — Decide scope and path
33
+
34
+ | Scope | Path | Loaded for |
35
+ | ------- | --------------------------- | --------------------------------- |
36
+ | project | `.claude/rules/{name}.md` | Everyone on the project (via git) |
37
+ | user | `~/.claude/rules/{name}.md` | You, across all projects |
38
+
39
+ User-level rules load _before_ project rules, so project rules override on conflict.
40
+
41
+ ### Step 2 — Decide scoping behaviour
42
+
43
+ | Pattern | Behaviour |
44
+ | ---------------------------- | ---------------------------------------------------------- |
45
+ | No `paths:` frontmatter | Rule loads at session start, unconditional — use sparingly |
46
+ | `paths: ["src/api/**/*.ts"]` | Rule loads when Claude reads a matching file |
47
+ | Multiple patterns | Comma-separated in array, supports brace expansion |
48
+
49
+ Scope every rule you reasonably can. Unscoped rules burn context for every file Claude touches.
50
+
51
+ ### Step 3 — Pick a glob pattern
52
+
53
+ Read [reference/paths-patterns.md](reference/paths-patterns.md) for the full table.
54
+
55
+ **Prefer narrow, directory-scoped patterns.** `**/*.ts` matches on every edit and burns context. Scope to the smallest directory that covers the rule's intent.
56
+
57
+ Good — narrow:
58
+
59
+ ```yaml
60
+ paths:
61
+ - "apps/*/src/app/api/**/*.ts" # API route handlers only
62
+ - "apps/*/src/components/**/*.tsx" # Component source
63
+ - "supabase/migrations/**/*.sql" # DB migrations only
64
+ - "packages/auth/src/**/*.ts" # One package's source
65
+ - "tests/e2e/**/*.test.ts" # E2E tests only
66
+ ```
67
+
68
+ Avoid — too broad:
69
+
70
+ ```yaml
71
+ paths:
72
+ - "**/*.ts" # bad — unscoped
73
+ - "src/**/*" # bad — everything under src
74
+ - "**/*.{ts,tsx}" # bad — language-wide
75
+ ```
76
+
77
+ Unscoped rules (no `paths:`) belong only on truly universal constraints: git attribution, company secrets policy, file-naming conventions.
78
+
79
+ ### Step 4 — Required CBP Frontmatter
80
+
81
+ Every rule MUST have **both** fields:
82
+
83
+ ```yaml
84
+ ---
85
+ scope: org-shared # or: project-shared | repo-only:<repo-name>
86
+ paths:
87
+ - "apps/*/src/app/api/**/*.ts"
88
+ ---
89
+ ```
90
+
91
+ | Field | Purpose |
92
+ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
93
+ | `scope:` | CBP structural marker — required by validators (`validate-structure-scope.sh`). NOT read by Claude Code. Values: `org-shared` \| `project-shared` \| `repo-only:<name>` |
94
+ | `paths:` | File globs that trigger rule loading (Claude Code native) |
95
+
96
+ When propagating rules between repos, copy only rules where `scope: org-shared` OR `scope: repo-only:<target>`.
97
+
98
+ ### Step 5 — Write the rule
99
+
100
+ Read `${CLAUDE_SKILL_DIR}/templates/rule.md` as the canonical template.
101
+
102
+ Naming:
103
+
104
+ - kebab-case: `api-validation.md`, `git-workflow.md`
105
+ - one topic per file
106
+ - filename matches the `# H1` title
107
+
108
+ Body structure — tight; bullets and tables, not prose:
109
+
110
+ ```markdown
111
+ # Rule title
112
+
113
+ One-line purpose.
114
+
115
+ ## Rule
116
+
117
+ - [Constraint 1 — specific + verifiable]
118
+ - [Constraint 2]
119
+
120
+ ## Correct / Wrong
121
+
122
+ Code examples only when the rule is non-obvious.
123
+
124
+ ## Why
125
+
126
+ Short reason — past incident, design decision, external constraint.
127
+ ```
128
+
129
+ **Recommended max 100 lines; hard limit 200** (enforced by `validate-structure-lengths.sh`). Rules load into context on every match and compete with the conversation for tokens. Split on topic as the warn threshold approaches.
130
+
131
+ ### Step 6 — Check for duplication (merge-first)
132
+
133
+ ```bash
134
+ grep -lr "topic-keyword" .claude/rules/
135
+ ```
136
+
137
+ | Situation | Action |
138
+ | ----------------------------------- | -------------------------------------- |
139
+ | Existing rule covers the topic | Update it — don't create a second file |
140
+ | Related but distinct constraints | Cross-reference, keep separate |
141
+ | Rule exists with different `paths:` | Merge the paths, keep one rule |
142
+ | Pattern seen once | Don't create yet — wait for recurrence |
143
+
144
+ ### Step 7 — (Optional) Share across projects via symlink
145
+
146
+ ```bash
147
+ # Whole rules directory shared
148
+ ln -s ~/shared-claude-rules .claude/rules/shared
149
+
150
+ # Individual file shared
151
+ ln -s ~/company-standards/security.md .claude/rules/security.md
152
+ ```
153
+
154
+ Claude Code resolves symlinks normally. Circular symlinks are detected.
155
+
156
+ ### Step 8 — Verify loading
157
+
158
+ Run `/memory` in a fresh Claude Code session to confirm the rule is listed. If path-scoped, open a file matching the glob to confirm it triggers.
159
+
160
+ Use the `InstructionsLoaded` hook if you need to debug exactly when and why a rule loads.
161
+
162
+ ## Integration
163
+
164
+ - **Triggered by**: user invocation
165
+ - **Reads**: `${CLAUDE_SKILL_DIR}/templates/rule.md`, `${CLAUDE_SKILL_DIR}/reference/paths-patterns.md`
166
+ - **Writes**: `.claude/rules/{name}.md` or `~/.claude/rules/{name}.md`
167
+ - **Related skills**: `/cbp-build-cc-claude-file` (project facts), `/cbp-build-cc-skill` (workflows), `/cbp-build-cc-memory` (auto-learnings)
168
+
169
+ ## Key Rules
170
+
171
+ - Every rule needs an intent — if removing it wouldn't change Claude's behaviour, delete it
172
+ - Prefer path-scoped over unconditional — context is a finite budget
173
+ - Missing `scope:` fails validation (validate-structure-scope.sh warns; validate-agent.sh / validate-skill.sh block); missing `paths:` loads the rule on every file read
174
+ - Rules are stored in the CBP database; the authoritative copy is in the DB — commit changes you want to keep
175
+ - Conflicting rules load in both — Claude picks arbitrarily. Remove or merge duplicates
176
+ - Rules that restate the Claude Code spec add no value — point to the official spec instead
@@ -0,0 +1,19 @@
1
+ ---
2
+ scope: org-shared
3
+ ---
4
+
5
+ # Git Commit Attribution
6
+
7
+ ## Rule
8
+
9
+ - Commit author is `<configured user>` — never add co-authors
10
+ - Commit body must not mention "Claude", "AI", or any assistant by name
11
+ - Trailers like `Co-Authored-By: Claude ...` are forbidden
12
+
13
+ ## Why
14
+
15
+ Attribution policy set by the project owner. Applies to every commit regardless of file.
16
+
17
+ ## Notes
18
+
19
+ This rule has no `paths:` and therefore loads at session start. Use unconditional rules sparingly — they consume context for every conversation.
@@ -0,0 +1,41 @@
1
+ ---
2
+ scope: org-shared
3
+ paths:
4
+ - "src/api/**/*.ts"
5
+ - "apps/*/src/app/api/**/*.ts"
6
+ ---
7
+
8
+ # API Development Rules
9
+
10
+ ## Rule
11
+
12
+ - All endpoints validate input with Zod before accessing the DB
13
+ - Return the standard error envelope: `{ error: { code, message, details? } }`
14
+ - Every handler has a matching `*.test.ts` with at least one failure case
15
+ - Never catch-and-ignore — log with structured fields and re-throw or map to a typed error
16
+
17
+ ## Correct
18
+
19
+ ```ts
20
+ import { z } from "zod";
21
+
22
+ const Body = z.object({ email: z.string().email() });
23
+
24
+ export async function POST(req: Request) {
25
+ const body = Body.parse(await req.json());
26
+ // ...
27
+ }
28
+ ```
29
+
30
+ ## Wrong
31
+
32
+ ```ts
33
+ export async function POST(req: Request) {
34
+ const body = await req.json(); // no validation
35
+ try { /* ... */ } catch (e) { /* swallow */ } // silent failure
36
+ }
37
+ ```
38
+
39
+ ## Why
40
+
41
+ Unvalidated handlers caused the 2026-Q1 data-shape incident. Standard error envelope lets the client handle failures uniformly.
@@ -0,0 +1,48 @@
1
+ # Path Glob Patterns Reference
2
+
3
+ Source: official Claude Code memory spec (section *Path-specific rules*).
4
+
5
+ ## Syntax
6
+
7
+ `paths:` accepts a YAML list of globs or a comma-separated string. Patterns match against file paths that Claude reads during the session. When any open file matches, the rule loads.
8
+
9
+ ## Common patterns
10
+
11
+ Prefer narrow patterns. Anything matching `**/*.<ext>` alone is almost always too broad — it loads the rule on every edit to that language across dependencies, build output, and unrelated packages.
12
+
13
+ | Pattern | Matches | Verdict |
14
+ |---------|---------|---------|
15
+ | `apps/*/src/app/api/**/*.ts` | Next.js API routes | good — narrow |
16
+ | `apps/*/src/components/**/*.tsx` | Component source | good — narrow |
17
+ | `supabase/migrations/**/*.sql` | DB migrations | good — narrow |
18
+ | `packages/auth/src/**/*.ts` | One package | good — narrow |
19
+ | `tests/e2e/**/*.test.ts` | E2E tests only | good — narrow |
20
+ | `.git/**/*` | Git internals | good — unique location |
21
+ | `**/*.ts` | All TS anywhere | bad — too broad |
22
+ | `src/**/*` | Everything under src | bad — any file type |
23
+ | `**/*.{ts,tsx}` | Language-wide | bad — too broad |
24
+
25
+ ## Multiple patterns
26
+
27
+ ```yaml
28
+ paths:
29
+ - "src/**/*.{ts,tsx}"
30
+ - "lib/**/*.ts"
31
+ - "tests/**/*.test.ts"
32
+ ```
33
+
34
+ A rule triggers if *any* pattern matches.
35
+
36
+ ## When rules trigger
37
+
38
+ - Rule loads when Claude reads a file matching the pattern
39
+ - Rule does NOT re-evaluate on every tool use — it's a file-open trigger
40
+ - Once loaded in a session, the rule stays until session end
41
+
42
+ ## Unscoped rules
43
+
44
+ A rule with no `paths:` loads at session start, unconditionally. Uses context for every conversation. Reserve for project-wide behavioural constraints.
45
+
46
+ ## Performance note
47
+
48
+ Narrow patterns first. Prefer `apps/*/src/api/**/*.ts` over `**/*.ts` — the latter triggers on any TypeScript file in the repo including dependencies, build output, and unrelated packages.
@@ -0,0 +1,32 @@
1
+ ---
2
+ scope: org-shared # CBP sync: org-shared | project-shared | repo-only:<repo-name>
3
+ paths:
4
+ # Narrow to the smallest directory that covers the rule's intent.
5
+ # Avoid "**/*.ts" — loads on every TS edit across the repo.
6
+ - "apps/*/src/app/api/**/*.ts"
7
+ ---
8
+
9
+ # Rule title
10
+
11
+ One-line statement of what this rule enforces.
12
+
13
+ ## Rule
14
+
15
+ - [First constraint — specific and verifiable]
16
+ - [Second constraint]
17
+
18
+ ## Correct
19
+
20
+ ```ts
21
+ // Example showing what follows the rule
22
+ ```
23
+
24
+ ## Wrong
25
+
26
+ ```ts
27
+ // Example violating the rule
28
+ ```
29
+
30
+ ## Why
31
+
32
+ [Reason — often: past incident, design decision, external constraint]
@@ -0,0 +1,220 @@
1
+ ---
2
+ scope: org-shared
3
+ name: cbp-build-cc-settings
4
+ description: Create or update Claude Code settings.json / settings.local.json / managed-settings.json following the official settings spec — scopes, permissions, hooks, sandbox, attribution, plugins, env vars, JSON schema validation.
5
+ argument-hint: "[action] [--scope=user|project|local|managed]"
6
+ allowed-tools: Read, Write, Edit, Glob, Grep, Bash(jq *)
7
+ effort: xhigh
8
+ ---
9
+
10
+ # Build Claude Code Settings File
11
+
12
+ Create or update a Claude Code settings file per the official Claude Code settings spec. Covers every scope and every documented key.
13
+
14
+ **CBP conventions** (two-file synced/local model, what goes where, policy defaults, sync behaviour): read [reference/cbp-conventions.md](reference/cbp-conventions.md) before writing.
15
+
16
+ ## Arguments
17
+
18
+ `$ARGUMENTS` — action: `create`, `add-permission`, `add-hook`, `add-env`, `audit`. Flag: `--scope=user|project|local|managed` (default `project`).
19
+
20
+ ## When to Use
21
+
22
+ - Pre-approve common read-only Bash commands → add to `permissions.allow`
23
+ - Block sensitive files → add to `permissions.deny`
24
+ - Wire hook scripts (PreToolUse, PostToolUse, InstructionsLoaded, etc.) → add to `hooks`
25
+ - Customize commit attribution → `attribution`
26
+ - Enable sandbox → `sandbox.enabled`
27
+ - Pin an auto-update channel → `autoUpdatesChannel`
28
+ - Configure MCP servers
29
+
30
+ ## Instructions
31
+
32
+ ### Step 1 — Pick the scope
33
+
34
+ Scopes stack in this precedence order (highest wins):
35
+
36
+ | # | Scope | Path | Who it affects |
37
+ | --- | --------- | -------------------------------------------------------- | --------------------------------------------- |
38
+ | 1 | Managed | `managed-settings.json` (OS-specific dir) / MDM / server | Everyone on the machine, cannot be overridden |
39
+ | 2 | CLI flags | — | This session |
40
+ | 3 | Local | `.claude/settings.local.json` | You, this project (gitignored) |
41
+ | 4 | Project | `.claude/settings.json` | Team, this project (committed) |
42
+ | 5 | User | `~/.claude/settings.json` | You, all projects |
43
+
44
+ Default scope: **project** (shared with team). Use **local** for personal prefs in a project. Use **user** for machine-wide personal prefs. Managed is IT-only.
45
+
46
+ ### Step 2 — Always include the `$schema` line
47
+
48
+ ```json
49
+ {
50
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
51
+ ...
52
+ }
53
+ ```
54
+
55
+ Enables autocomplete and validation in VS Code, Cursor, etc. The published schema lags the CLI so a warning on a new field is not always invalid.
56
+
57
+ ### Step 3 — Pick the category
58
+
59
+ Major categories (full reference: [reference/settings-fields.md](reference/settings-fields.md)):
60
+
61
+ | Category | Keys | Use for |
62
+ | ----------- | ------------------------------------------------------------------------------- | ------------------------------ |
63
+ | Permissions | `permissions.allow\|ask\|deny`, `defaultMode`, `additionalDirectories` | Tool gating |
64
+ | Hooks | `hooks`, `allowedHttpHookUrls`, `httpHookAllowedEnvVars`, `disableAllHooks` | Lifecycle scripts |
65
+ | Sandbox | `sandbox.*` (mac/linux/WSL2) | Filesystem + network isolation |
66
+ | Env | `env` | Per-session env vars |
67
+ | Attribution | `attribution.commit`, `attribution.pr` | Git commit/PR trailers |
68
+ | Plugins | `enabledPlugins`, `extraKnownMarketplaces` | Plugin control |
69
+ | MCP | `enableAllProjectMcpServers`, `enabledMcpjsonServers`, `disabledMcpjsonServers` | MCP gating |
70
+ | Memory | `autoMemoryEnabled`, `autoMemoryDirectory`, `claudeMdExcludes` | Memory control |
71
+ | Look + feel | `statusLine`, `tui`, `spinnerVerbs`, `language`, `prefersReducedMotion` | UX |
72
+
73
+ ### Step 4 — Write permissions with correct syntax
74
+
75
+ Rules follow `Tool` or `Tool(specifier)`. Evaluated in order: **deny → ask → allow**. First matching rule wins.
76
+
77
+ Full patterns: [reference/permission-rules.md](reference/permission-rules.md).
78
+
79
+ Common examples:
80
+
81
+ ```json
82
+ {
83
+ "permissions": {
84
+ "allow": [
85
+ "Bash(git diff *)",
86
+ "Bash(git status *)",
87
+ "Bash(npm run lint)",
88
+ "Bash(npm test *)"
89
+ ],
90
+ "ask": ["Bash(git push *)"],
91
+ "deny": [
92
+ "WebFetch",
93
+ "Bash(curl *)",
94
+ "Read(./.env)",
95
+ "Read(./.env.*)",
96
+ "Read(./secrets/**)"
97
+ ]
98
+ }
99
+ }
100
+ ```
101
+
102
+ See [examples/permissions-config.json](examples/permissions-config.json).
103
+
104
+ ### Step 5 — Write hooks with the right event
105
+
106
+ Full hook events and schema: see the official Claude Code hooks spec. Common entries:
107
+
108
+ ```json
109
+ {
110
+ "hooks": {
111
+ "PostToolUse": [
112
+ {
113
+ "matcher": "Edit|Write",
114
+ "hooks": [{ "type": "command", "command": "./.claude/hooks/format.sh" }]
115
+ }
116
+ ],
117
+ "SubagentStart": [
118
+ {
119
+ "matcher": "db-agent",
120
+ "hooks": [
121
+ { "type": "command", "command": "./.claude/hooks/setup-db.sh" }
122
+ ]
123
+ }
124
+ ]
125
+ }
126
+ }
127
+ ```
128
+
129
+ Matchers are regex on the tool name (or subagent name for subagent events). Full example: [examples/hooks-config.json](examples/hooks-config.json).
130
+
131
+ ### Step 6 — Sandbox (optional, advanced)
132
+
133
+ Isolates Bash commands from filesystem and network. Mac/Linux/WSL2 only. Not on by default.
134
+
135
+ ```json
136
+ {
137
+ "sandbox": {
138
+ "enabled": true,
139
+ "autoAllowBashIfSandboxed": true,
140
+ "excludedCommands": ["docker *"],
141
+ "filesystem": {
142
+ "allowWrite": ["/tmp/build", "~/.kube"],
143
+ "denyRead": ["~/.aws/credentials"]
144
+ },
145
+ "network": {
146
+ "allowedDomains": ["github.com", "*.npmjs.org"],
147
+ "allowLocalBinding": true
148
+ }
149
+ }
150
+ }
151
+ ```
152
+
153
+ Path prefix rules: `/path` = absolute, `~/path` = home, `./path` or no prefix = project root (for project settings) or `~/.claude` (for user settings). See [examples/sandbox-config.json](examples/sandbox-config.json).
154
+
155
+ ### Step 7 — Attribution (git commit/PR trailers)
156
+
157
+ ```json
158
+ {
159
+ "attribution": {
160
+ "commit": "",
161
+ "pr": ""
162
+ }
163
+ }
164
+ ```
165
+
166
+ Empty string hides the trailer. Takes precedence over the deprecated `includeCoAuthoredBy`.
167
+
168
+ ### Step 8 — Env vars
169
+
170
+ ```json
171
+ {
172
+ "env": {
173
+ "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
174
+ "OTEL_METRICS_EXPORTER": "otlp"
175
+ }
176
+ }
177
+ ```
178
+
179
+ Applied to every session. Full env-var catalogue: the official Claude Code env-vars reference.
180
+
181
+ ### Step 9 — Validate and verify
182
+
183
+ ```bash
184
+ # Pretty-print and validate JSON
185
+ jq . .claude/settings.json
186
+
187
+ # Ask Claude Code itself
188
+ # (inside a session)
189
+ /status # shows which layers are active and their origin
190
+ /doctor # deeper diagnostics
191
+ ```
192
+
193
+ The `$schema` line enables editor-level validation. For settings that arrays-merge across scopes (permissions, `allowWrite`, etc.), `/status` shows the merged result.
194
+
195
+ ### Step 10 — Precedence pitfalls
196
+
197
+ | Array setting | Merges across scopes? |
198
+ | ---------------------------------------------------------- | -------------------------- |
199
+ | `permissions.allow` / `ask` / `deny` | Yes (concatenate + dedupe) |
200
+ | `sandbox.filesystem.allowWrite` / `denyWrite` / `denyRead` | Yes |
201
+ | `allowedHttpHookUrls` | Yes |
202
+ | `httpHookAllowedEnvVars` | Yes |
203
+
204
+ Scalar settings (e.g. `model`, `defaultMode`) follow precedence, not merge. Higher-priority scope wins outright.
205
+
206
+ ## Integration
207
+
208
+ - **Triggered by**: user invocation, `update-config` bundled skill
209
+ - **Reads**: `${CLAUDE_SKILL_DIR}/templates/*.json`, `${CLAUDE_SKILL_DIR}/examples/*.json`, `${CLAUDE_SKILL_DIR}/reference/*.md` (including `cbp-conventions.md`)
210
+ - **Writes**: `.claude/settings.json`, `.claude/settings.local.json`, `~/.claude/settings.json`, or `managed-settings.json`
211
+ - **Related skills**: `/cbp-build-cc-rule` / `/cbp-build-cc-claude-file` (non-JSON configuration)
212
+
213
+ ## Key Rules
214
+
215
+ - `settings.local.json` is gitignored automatically when Claude Code creates it — never commit secrets here anyway
216
+ - Arrays merge across scopes; scalars don't. Check [reference/scope-precedence.md](reference/scope-precedence.md) before assuming
217
+ - Managed settings cannot be overridden. Don't put them in any other scope
218
+ - `permissions.deny` takes precedence over `allow` and `ask` — use it for secrets
219
+ - For path-style permission rules in `Read(...)` and `Edit(...)`: `//path` = absolute, `/path` = project-relative. Sandbox filesystem uses standard conventions (`/path` = absolute)
220
+ - The deprecated `includeCoAuthoredBy` is superseded by `attribution` — migrate rather than both
@@ -0,0 +1,64 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
+ "hooks": {
4
+ "PreToolUse": [
5
+ {
6
+ "matcher": "Bash",
7
+ "hooks": [
8
+ { "type": "command", "command": "./.claude/hooks/validate-bash.sh" }
9
+ ]
10
+ }
11
+ ],
12
+ "PostToolUse": [
13
+ {
14
+ "matcher": "Edit|Write",
15
+ "hooks": [
16
+ { "type": "command", "command": "./.claude/hooks/lint-format-on-edit.sh" }
17
+ ]
18
+ }
19
+ ],
20
+ "UserPromptSubmit": [
21
+ {
22
+ "hooks": [
23
+ { "type": "command", "command": "./.claude/hooks/record-prompt.sh" }
24
+ ]
25
+ }
26
+ ],
27
+ "SubagentStart": [
28
+ {
29
+ "matcher": "db-agent",
30
+ "hooks": [
31
+ { "type": "command", "command": "./.claude/hooks/setup-db-connection.sh" }
32
+ ]
33
+ }
34
+ ],
35
+ "SubagentStop": [
36
+ {
37
+ "hooks": [
38
+ { "type": "command", "command": "./.claude/hooks/cleanup-agent.sh" }
39
+ ]
40
+ }
41
+ ],
42
+ "Stop": [
43
+ {
44
+ "hooks": [
45
+ { "type": "command", "command": "./.claude/hooks/notify-on-stop.sh" }
46
+ ]
47
+ }
48
+ ],
49
+ "Notification": [
50
+ {
51
+ "hooks": [
52
+ { "type": "command", "command": "./.claude/hooks/terminal-bell.sh" }
53
+ ]
54
+ }
55
+ ]
56
+ },
57
+ "allowedHttpHookUrls": [
58
+ "https://hooks.example.com/*",
59
+ "http://localhost:*"
60
+ ],
61
+ "httpHookAllowedEnvVars": [
62
+ "HOOK_SECRET"
63
+ ]
64
+ }
@@ -0,0 +1,34 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
+ "permissions": {
4
+ "allow": [
5
+ "Bash(git status *)",
6
+ "Bash(git diff *)",
7
+ "Bash(git log *)",
8
+ "Bash(git show *)",
9
+ "Bash(git branch *)",
10
+ "Bash(pnpm run lint)",
11
+ "Bash(pnpm run test *)",
12
+ "Bash(pnpm -r build)",
13
+ "Read(~/.zshrc)",
14
+ "WebFetch(domain:docs.anthropic.com)",
15
+ "WebFetch(domain:code.claude.com)"
16
+ ],
17
+ "ask": [
18
+ "Bash(git push *)",
19
+ "Bash(git commit *)"
20
+ ],
21
+ "deny": [
22
+ "WebFetch",
23
+ "Bash(curl *)",
24
+ "Bash(wget *)",
25
+ "Read(./.env)",
26
+ "Read(./.env.*)",
27
+ "Read(./secrets/**)",
28
+ "Read(./**/*.pem)",
29
+ "Read(./**/credentials.json)"
30
+ ],
31
+ "additionalDirectories": [],
32
+ "defaultMode": "acceptEdits"
33
+ }
34
+ }
@@ -0,0 +1,42 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
+ "sandbox": {
4
+ "enabled": true,
5
+ "autoAllowBashIfSandboxed": true,
6
+ "failIfUnavailable": false,
7
+ "excludedCommands": ["docker *", "kubectl *"],
8
+ "filesystem": {
9
+ "allowWrite": [
10
+ "/tmp/build",
11
+ "~/.kube",
12
+ "./dist",
13
+ "./coverage"
14
+ ],
15
+ "denyWrite": [
16
+ "/etc",
17
+ "/usr/local/bin"
18
+ ],
19
+ "denyRead": [
20
+ "~/.aws/credentials",
21
+ "~/.ssh/id_*"
22
+ ],
23
+ "allowRead": ["."]
24
+ },
25
+ "network": {
26
+ "allowedDomains": [
27
+ "github.com",
28
+ "*.npmjs.org",
29
+ "registry.yarnpkg.com",
30
+ "docs.anthropic.com",
31
+ "code.claude.com"
32
+ ],
33
+ "deniedDomains": [
34
+ "uploads.github.com"
35
+ ],
36
+ "allowUnixSockets": [
37
+ "/var/run/docker.sock"
38
+ ],
39
+ "allowLocalBinding": true
40
+ }
41
+ }
42
+ }