@zenuml/core 3.47.8 → 3.48.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 (204) hide show
  1. package/dist/cloud-icons-eHuugVSv.js.map +1 -0
  2. package/dist/zenuml.esm.mjs +2153 -2156
  3. package/dist/zenuml.esm.mjs.map +1 -0
  4. package/dist/zenuml.js +82 -82
  5. package/dist/zenuml.js.map +1 -0
  6. package/package.json +11 -1
  7. package/src/cli/zenuml.ts +1164 -0
  8. package/.agents/skills/babysit-pr/SKILL.md +0 -223
  9. package/.agents/skills/babysit-pr/agents/openai.yaml +0 -7
  10. package/.agents/skills/dia-scoring/SKILL.md +0 -139
  11. package/.agents/skills/dia-scoring/agents/openai.yaml +0 -7
  12. package/.agents/skills/dia-scoring/references/selectors-and-keys.md +0 -253
  13. package/.agents/skills/land-pr/SKILL.md +0 -120
  14. package/.agents/skills/propagate-core-release/SKILL.md +0 -205
  15. package/.agents/skills/propagate-core-release/agents/openai.yaml +0 -7
  16. package/.agents/skills/propagate-core-release/references/downstreams.md +0 -42
  17. package/.agents/skills/ship-branch/SKILL.md +0 -105
  18. package/.agents/skills/submit-branch/SKILL.md +0 -76
  19. package/.agents/skills/validate-branch/SKILL.md +0 -72
  20. package/.claude/commands/README.md +0 -162
  21. package/.claude/commands/analyze.md +0 -101
  22. package/.claude/commands/clarify.md +0 -158
  23. package/.claude/commands/code-review.md +0 -322
  24. package/.claude/commands/constitution.md +0 -73
  25. package/.claude/commands/create-docs.md +0 -309
  26. package/.claude/commands/full-context.md +0 -121
  27. package/.claude/commands/gemini-consult.md +0 -164
  28. package/.claude/commands/handoff.md +0 -146
  29. package/.claude/commands/implement.md +0 -56
  30. package/.claude/commands/plan.md +0 -43
  31. package/.claude/commands/refactor.md +0 -188
  32. package/.claude/commands/specify.md +0 -21
  33. package/.claude/commands/tasks.md +0 -62
  34. package/.claude/commands/update-docs.md +0 -314
  35. package/.claude/hooks/README.md +0 -270
  36. package/.claude/hooks/config/sensitive-patterns.json +0 -86
  37. package/.claude/hooks/gemini-context-injector.sh +0 -129
  38. package/.claude/hooks/mcp-security-scan.sh +0 -147
  39. package/.claude/hooks/notify.sh +0 -103
  40. package/.claude/hooks/setup/hook-setup.md +0 -96
  41. package/.claude/hooks/setup/settings.json.template +0 -63
  42. package/.claude/hooks/sounds/complete.wav +0 -0
  43. package/.claude/hooks/sounds/input-needed.wav +0 -0
  44. package/.claude/hooks/subagent-context-injector.sh +0 -65
  45. package/.claude/skills/babysit-pr/SKILL.md +0 -223
  46. package/.claude/skills/babysit-pr/agents/openai.yaml +0 -7
  47. package/.claude/skills/dia-scoring/SKILL.md +0 -139
  48. package/.claude/skills/dia-scoring/agents/openai.yaml +0 -7
  49. package/.claude/skills/dia-scoring/references/selectors-and-keys.md +0 -253
  50. package/.claude/skills/emoji-eval/SKILL.md +0 -187
  51. package/.claude/skills/land-pr/SKILL.md +0 -120
  52. package/.claude/skills/propagate-core-release/SKILL.md +0 -205
  53. package/.claude/skills/propagate-core-release/agents/openai.yaml +0 -7
  54. package/.claude/skills/propagate-core-release/references/downstreams.md +0 -42
  55. package/.claude/skills/ship-branch/SKILL.md +0 -105
  56. package/.claude/skills/submit-branch/SKILL.md +0 -76
  57. package/.claude/skills/validate-branch/SKILL.md +0 -72
  58. package/.claude/skills/zenuml-ux-research/SKILL.md +0 -183
  59. package/.claude/skills/zenuml-ux-research/references/assertion-catalog.md +0 -261
  60. package/.claude/skills/zenuml-ux-research/references/best-practices-overview.md +0 -56
  61. package/.claude/skills/zenuml-ux-research/references/report-template.md +0 -89
  62. package/.claude/skills/zenuml-ux-research/references/scenarios/edit-message-label.md +0 -37
  63. package/.claude/skills/zenuml-ux-research/references/scenarios/insert-message.md +0 -36
  64. package/.claude/skills/zenuml-ux-research/references/scenarios/insert-participant.md +0 -31
  65. package/.claude/skills/zenuml-ux-research/references/scenarios/rename-participant.md +0 -33
  66. package/.claude/skills/zenuml-ux-research/references/scenarios/undo-insert.md +0 -35
  67. package/.devcontainer/devcontainer.json +0 -21
  68. package/.dockerignore +0 -19
  69. package/.eslintrc.js +0 -39
  70. package/.git-blame-ignore-revs +0 -6
  71. package/.kiro/hooks/README.md +0 -38
  72. package/.kiro/hooks/session-sound-notification.js +0 -44
  73. package/.kiro/hooks/session-sound-notification.json +0 -23
  74. package/.mcp.json.example +0 -17
  75. package/.nvmrc +0 -1
  76. package/.prettierignore +0 -4
  77. package/.prettierrc +0 -1
  78. package/.specify/memory/constitution.md +0 -33
  79. package/.specify/scripts/bash/check-prerequisites.sh +0 -166
  80. package/.specify/scripts/bash/common.sh +0 -113
  81. package/.specify/scripts/bash/create-new-feature.sh +0 -97
  82. package/.specify/scripts/bash/setup-plan.sh +0 -60
  83. package/.specify/scripts/bash/update-agent-context.sh +0 -728
  84. package/.specify/templates/agent-file-template.md +0 -23
  85. package/.specify/templates/plan-template.md +0 -219
  86. package/.specify/templates/spec-template.md +0 -116
  87. package/.specify/templates/tasks-template.md +0 -127
  88. package/.storybook/main.ts +0 -25
  89. package/.storybook/preview.ts +0 -29
  90. package/.watchmanconfig +0 -3
  91. package/AGENTS.md +0 -26
  92. package/CLAUDE.md +0 -124
  93. package/DEPLOYMENT.md +0 -62
  94. package/Dockerfile +0 -36
  95. package/IMPLEMENTATION_PLAN.md +0 -163
  96. package/Integration/vanilla-js/index.html +0 -42
  97. package/MCP-ASSISTANT-RULES.md +0 -85
  98. package/README_CN.md +0 -15
  99. package/TUTORIAL.md +0 -116
  100. package/antlr/antlr-4.11.1-complete.jar +0 -0
  101. package/bun.lock +0 -1544
  102. package/bunfig.toml +0 -52
  103. package/docs/UNICODE_SUPPORT.md +0 -179
  104. package/docs/ai-context/deployment-infrastructure.md +0 -21
  105. package/docs/ai-context/docs-overview.md +0 -89
  106. package/docs/ai-context/handoff.md +0 -174
  107. package/docs/ai-context/project-structure.md +0 -160
  108. package/docs/ai-context/system-integration.md +0 -21
  109. package/docs/asciidoc/contributor.adoc +0 -54
  110. package/docs/asciidoc/create-my-own-theme.adoc +0 -149
  111. package/docs/asciidoc/images/creation-component.png +0 -0
  112. package/docs/asciidoc/images/creation-rtl.png +0 -0
  113. package/docs/asciidoc/images/message-arrow-rtl.png +0 -0
  114. package/docs/asciidoc/images/occurrence.png +0 -0
  115. package/docs/asciidoc/images/return-message-conflict.png +0 -0
  116. package/docs/asciidoc/images/shift-up-half-the-height.png +0 -0
  117. package/docs/asciidoc/images/three-layer-info-arch.png +0 -0
  118. package/docs/asciidoc/images/vertical-alignment.svg +0 -1
  119. package/docs/asciidoc/images/vertically-aligning.png +0 -0
  120. package/docs/asciidoc/index.adoc +0 -277
  121. package/docs/asciidoc/theme-debug-web-app.png +0 -0
  122. package/docs/asciidoc/tutorial.adoc +0 -22
  123. package/docs/asciidoc/user-css.png +0 -0
  124. package/docs/async-vs-sync-parser-rules.md +0 -81
  125. package/docs/divider-parser-allow-spaces.md +0 -38
  126. package/docs/highlighting-messages.md +0 -52
  127. package/docs/images/editor-sample.png +0 -0
  128. package/docs/inherited-vs-provided-from.md +0 -64
  129. package/docs/parser/Assignment.md +0 -8
  130. package/docs/parser/PARSER_IMPROVEMENTS_CC.md +0 -425
  131. package/docs/parser/grammar_review_gemini.md +0 -116
  132. package/docs/participants-function.md +0 -25
  133. package/docs/responsive-participant-margin.md +0 -52
  134. package/docs/starter.md +0 -9
  135. package/docs/superpowers/plans/2026-03-27-e2e-test-reorg.md +0 -698
  136. package/docs/superpowers/plans/2026-03-30-emoji-support.md +0 -1220
  137. package/docs/superpowers/plans/2026-03-30-self-correcting-scoring.md +0 -206
  138. package/docs/superpowers/plans/2026-04-15-keyboard-editing-on-diagram.md +0 -1992
  139. package/docs/superpowers/plans/2026-04-15-zenuml-ux-research-skill.md +0 -1452
  140. package/docs/ux-research/.gitkeep +0 -0
  141. package/docs/ux-research/2026-04-15-rename-participant.md +0 -156
  142. package/docs/ux-research/2026-04-18-insert-participant.md +0 -151
  143. package/docs/width-translate-and-offsets.md +0 -62
  144. package/docs/xss.md +0 -59
  145. package/e2e/data/compare-cases.js +0 -1090
  146. package/e2e/data/diff-algorithm.js +0 -199
  147. package/e2e/fixtures/create-message.html +0 -26
  148. package/e2e/fixtures/editable-label.html +0 -35
  149. package/e2e/fixtures/editable-span.html +0 -122
  150. package/e2e/fixtures/empty-diagram.html +0 -23
  151. package/e2e/fixtures/fixture.html +0 -31
  152. package/e2e/fixtures/insert-participant.html +0 -23
  153. package/e2e/fixtures/reorder-cross-fragment.html +0 -31
  154. package/e2e/fixtures/reorder-fragment.html +0 -29
  155. package/e2e/fixtures/reorder-message.html +0 -27
  156. package/e2e/fixtures/svg-test.html +0 -21
  157. package/e2e/fixtures/type-switch.html +0 -29
  158. package/e2e/tools/canonical-history.html +0 -908
  159. package/e2e/tools/compare-case.html +0 -371
  160. package/e2e/tools/compare.html +0 -35
  161. package/e2e/tools/native-diff-ext/background.js +0 -60
  162. package/e2e/tools/native-diff-ext/bridge.js +0 -26
  163. package/e2e/tools/native-diff-ext/content.js +0 -194
  164. package/e2e/tools/svg-preview.html +0 -56
  165. package/embed.html +0 -193
  166. package/eslint.config.mjs +0 -35
  167. package/firebase-debug.log +0 -108
  168. package/iframe-container-demo/diagram.html +0 -124
  169. package/iframe-container-demo/host.html +0 -817
  170. package/index.html +0 -771
  171. package/mermaid-zenuml-async-spa-auth.png +0 -0
  172. package/mermaid-zenuml-async-spa-auth.snapshot.md +0 -96
  173. package/newsletter/unicode-support-announcement.md +0 -134
  174. package/playground/creation.html +0 -53
  175. package/playground/message.html +0 -63
  176. package/playwright.config.ts +0 -40
  177. package/renderer.html +0 -366
  178. package/scripts/analyze-compare-case/collect-data.mjs +0 -1134
  179. package/scripts/analyze-compare-case/config.mjs +0 -102
  180. package/scripts/analyze-compare-case/geometry.mjs +0 -101
  181. package/scripts/analyze-compare-case/native-diff.mjs +0 -224
  182. package/scripts/analyze-compare-case/output.mjs +0 -74
  183. package/scripts/analyze-compare-case/panel-diff.mjs +0 -114
  184. package/scripts/analyze-compare-case/report.mjs +0 -162
  185. package/scripts/analyze-compare-case/residual-scopes.mjs +0 -347
  186. package/scripts/analyze-compare-case/scoring.mjs +0 -829
  187. package/scripts/analyze-compare-case.mjs +0 -149
  188. package/scripts/bump-version.js +0 -117
  189. package/scripts/snapshot-dual.js +0 -173
  190. package/scripts/update-snapshots.js +0 -70
  191. package/skills/dia-scoring/SKILL.md +0 -129
  192. package/skills/dia-scoring/agents/openai.yaml +0 -7
  193. package/skills/dia-scoring/references/selectors-and-keys.md +0 -253
  194. package/tailwind.config.js +0 -126
  195. package/test-compression.html +0 -274
  196. package/test-mermaid-zenuml.html +0 -57
  197. package/test-setup.ts +0 -124
  198. package/test-url-params.html +0 -192
  199. package/tsconfig.app.json +0 -31
  200. package/tsconfig.node.json +0 -24
  201. package/tsconfig.test.json +0 -9
  202. package/vite.config.lib.ts +0 -93
  203. package/vite.config.ts +0 -84
  204. package/wrangler.toml +0 -18
@@ -1,314 +0,0 @@
1
- You have just completed work on the VR Language Learning App project. Analyze changes based on the provided context and automatically update relevant documentation.
2
-
3
- ## Auto-Loaded Project Context:
4
- @/CLAUDE.md
5
- @/docs/ai-context/project-structure.md
6
- @/docs/ai-context/docs-overview.md
7
-
8
- ## Core Documentation Principle: Document Current State Only
9
-
10
- **CRITICAL: Always document the current "is" state of the system. Never reference legacy implementations, describe improvements made, or explain what changed. Documentation should read as if the current implementation has always existed.**
11
-
12
- ### Documentation Anti-Patterns to Avoid:
13
- - ❌ "Refactored the voice pipeline to use streaming instead of batch processing"
14
- - ❌ "Improved performance by implementing caching"
15
- - ❌ "Previously used X, now uses Y for better results"
16
- - ❌ "Legacy implementation has been replaced with..."
17
-
18
- ### Documentation Best Practices:
19
- - ✅ "The voice pipeline uses streaming for real-time processing"
20
- - ✅ "Implements caching for frequently accessed data"
21
- - ✅ "Uses Y for optimal results"
22
- - ✅ "The system architecture follows..."
23
-
24
- ## Step 1: Analyze Changes Based on Input
25
-
26
- ### Determine Analysis Mode:
27
- - **No input (default)**: Analyze recent conversation context
28
- - **Git commit ID** (e.g., "3b8d24e" or full hash): Analyze specific commit
29
- - **"uncommitted"/"staged"/"working"**: Analyze uncommitted changes
30
- - **"last N commits"** (e.g., "last 3 commits"): Analyze recent commits
31
-
32
- ### Execute Analysis:
33
- Based on the input parameter:
34
-
35
- #### For Git Commit Analysis:
36
- ```bash
37
- # Get commit details
38
- git show --name-status [COMMIT_ID]
39
- git diff [COMMIT_ID]^ [COMMIT_ID]
40
- ```
41
-
42
- #### For Uncommitted Changes:
43
- ```bash
44
- # Get staged and unstaged changes
45
- git status --porcelain
46
- git diff HEAD
47
- git diff --cached
48
- ```
49
-
50
- #### For Recent Commits:
51
- ```bash
52
- # Get recent commit history
53
- git log --oneline -n [N]
54
- git diff HEAD~[N] HEAD
55
- ```
56
-
57
- #### For Session Context (default):
58
- Review your recent conversation and tool usage for significant changes.
59
-
60
- **Look for Evidence of Documentation-Relevant Changes:**
61
- - **New features or components** (functionality that needs documenting)
62
- - **Architecture decisions** (new patterns, structural changes, design decisions)
63
- - **Technology stack changes** (new dependencies, framework additions, integration changes)
64
- - **API changes** (new endpoints, modified interfaces, breaking changes)
65
- - **Configuration changes** (new environment variables, settings, deployment requirements)
66
- - **File structure changes** (new directories, moved components, reorganized code)
67
-
68
- **Exclude from Documentation Updates:**
69
- - Performance optimizations without architectural impact
70
- - Bug fixes that don't change interfaces or patterns
71
- - Code cleanup, refactoring that doesn't affect usage
72
- - Logging improvements, debugging enhancements
73
- - Test additions without new functionality
74
-
75
- **Generate a brief summary** of what was accomplished:
76
- ```
77
- Analysis source: [session context/commit ID/uncommitted changes]
78
- Detected changes: [1-2 sentence summary of main work done]
79
- ```
80
-
81
- ## Step 2: Understand Project Context and Documentation Structure
82
-
83
- Analyze the auto-loaded foundational files:
84
- 1. `/CLAUDE.md` - **CRITICAL:** Understand AI instructions, coding standards, and development protocols that govern the project
85
- 2. `/docs/ai-context/project-structure.md` - **FOUNDATION:** Technology stack, complete file tree and architecture overview
86
- 3. `/docs/ai-context/docs-overview.md` - Understand:
87
- - What documentation files exist and their purposes
88
- - How the documentation is organized
89
- - Which types of changes map to which documentation
90
-
91
- **AI-First Documentation Principle**: Remember that documentation is primarily for AI consumption - optimize for file path references, clear structure markers, and machine-readable patterns that enable efficient context loading.
92
-
93
- ## Step 3: Intelligent Update Strategy Decision
94
-
95
- Think deeply about the documentation updates needed based on the auto-loaded project context and detected changes. Based on the detected changes from Step 1 AND the auto-loaded project context, intelligently decide the optimal approach:
96
-
97
- ### Strategy Options:
98
-
99
- **Direct Update** (0-1 sub-agents):
100
- - Simple file modifications with clear documentation mapping
101
- - Bug fixes or minor enhancements that don't affect architecture
102
- - Changes confined to a single component or feature area
103
- - Standard patterns already well-documented in the project
104
-
105
- **Focused Analysis** (2-3 sub-agents):
106
- - Moderate complexity changes affecting multiple files
107
- - New features that introduce novel patterns
108
- - Changes that span 2-3 components or documentation tiers
109
- - Technology stack updates requiring validation across docs
110
-
111
- **Comprehensive Analysis** (3+ sub-agents):
112
- - Complex architectural changes affecting multiple system areas
113
- - Major refactoring that restructures component relationships
114
- - New integrations that create cross-system dependencies
115
- - Changes that require extensive documentation cascade updates
116
-
117
- ## Step 4: Execute Chosen Strategy
118
-
119
- ### For Direct Update:
120
- Proceed with straightforward documentation updates using the detected changes and auto-loaded foundational context. Continue with Step 5 (Final Decision Making).
121
-
122
- ### For Sub-Agent Approaches:
123
- You have complete autonomy to design sub-agents based on the specific changes detected. Consider these investigation areas and design custom agents to cover what's most relevant:
124
-
125
- **Core Investigation Areas to Consider:**
126
- - **Change Impact Analysis**: Map file modifications to affected documentation across all tiers
127
- - **Architecture Validation**: Verify existing architectural docs still reflect current implementation
128
- - **Cross-Component Dependency Mapping**: Identify documentation updates needed due to integration changes
129
- - **Documentation Accuracy Assessment**: Validate current docs against modified code patterns
130
- - **Tier Cascade Requirements**: Determine which documentation levels need updates based on change scope
131
- - **Technology Stack Verification**: Ensure tech stack changes are reflected across relevant documentation
132
-
133
- **Autonomous Sub-Agent Design Principles:**
134
- - **Custom Specialization**: Define agents based on the specific change complexity and documentation impact
135
- - **Flexible Agent Count**: Use as many agents as needed - scale based on actual change scope
136
- - **Adaptive Coverage**: Ensure all affected documentation areas are covered without unnecessary overlap
137
- - **Update-Focused Analysis**: Prioritize investigation that directly supports accurate documentation updates
138
-
139
- **Sub-Agent Task Template:**
140
- ```
141
- Task: "Analyze [SPECIFIC_INVESTIGATION_AREA] for documentation updates based on changes from [SOURCE]: [DETECTED_CHANGES]"
142
-
143
- Standard Investigation Workflow:
144
- 1. Review auto-loaded project context (CLAUDE.md, project-structure.md, docs-overview.md)
145
- 2. [CUSTOM_ANALYSIS_STEPS] - Investigate the specific area thoroughly
146
- 3. Return actionable findings that identify required documentation updates
147
-
148
- Return comprehensive findings addressing this investigation area for documentation updates.
149
- ```
150
-
151
- **CRITICAL: When using sub-agents, always launch them in parallel using a single message with multiple Task tool invocations.**
152
-
153
- ## Step 5: Synthesize Analysis and Plan Updates
154
-
155
- ### For Sub-Agent Approaches:
156
- Think deeply about integrating findings from all sub-agent investigations for optimal documentation updates. Combine findings from all agents to create optimal documentation update strategy:
157
-
158
- **Integration Analysis:**
159
- - **Change Impact**: Use Change Impact Agent's mapping of modifications to documentation
160
- - **Architecture Validation**: Apply Architecture Validation Agent's findings on outdated information
161
- - **Dependency Updates**: Implement Cross-Component Agent's integration change requirements
162
- - **Accuracy Corrections**: Address Documentation Accuracy Agent's identified inconsistencies
163
- - **Cascade Planning**: Execute Tier Cascade Agent's multi-level update requirements
164
-
165
- **Update Strategy Decision:**
166
- Based on synthesized analysis, determine:
167
- - **Documentation scope**: Which files need updates and at what detail level
168
- - **Update priority**: Critical architectural changes vs. minor pattern updates
169
- - **Cascade requirements**: Which tier levels need coordinated updates
170
- - **New file creation**: Whether new documentation files are warranted
171
-
172
- ## Step 6: Final Decision Making
173
-
174
- Based on your context analysis and the auto-loaded documentation structure (either direct or synthesized from sub-agents), decide:
175
- - **Which documents need updates** (match changes to appropriate documentation)
176
- - **What type of updates** (component changes, architecture decisions, new patterns, etc.)
177
- - **Update scope** (major changes get more detail, minor changes get brief updates)
178
- - **Whether new documentation files are needed** (see Smart File Creation guidelines below)
179
-
180
- ## Step 7: Smart File Creation (If Needed)
181
-
182
- Before updating existing documentation, assess if new documentation files should be created based on the 3-tier system:
183
-
184
- ### Guidelines for Creating New Documentation Files
185
-
186
- **Create new Component CONTEXT.md when:**
187
- - You detect an entirely new top-level component (new directory under `agents/`, `unity-client/`, `supabase-functions/`, etc.)
188
- - The component has significant functionality (5+ meaningful files)
189
- - Example: Adding `agents/lesson-generator/` → Create `agents/lesson-generator/CONTEXT.md`
190
-
191
- **Create new Feature-Specific CONTEXT.md when:**
192
- - You detect a new complex subsystem within an existing component
193
- - The subsystem has 3+ files and represents a distinct functional area
194
- - No existing granular CONTEXT.md file covers this area
195
- - Example: Adding `agents/tutor-server/src/features/translation/` with multiple files → Create `agents/tutor-server/src/features/CONTEXT.md`
196
-
197
- **When NOT to create new files:**
198
- - Small additions (1-2 files) that fit existing documentation scope
199
- - Bug fixes or minor modifications
200
- - Temporary or experimental code
201
-
202
- **File Creation Process:**
203
- 1. **Create the new CONTEXT.md file** with placeholder content following the pattern of existing granular docs
204
- 2. **Update `/docs/ai-context/docs-overview.md`** to include the new file in the appropriate tier
205
- 3. **Document the addition** in the current update process
206
-
207
- ### File Content Template for New Granular CONTEXT.md:
208
- ```markdown
209
- # [Feature Area] Documentation
210
-
211
- *This file documents [specific area] patterns and implementations within [component].*
212
-
213
- ## [Area] Architecture
214
- - [Key architectural elements]
215
-
216
- ## Implementation Patterns
217
- - [Key patterns used]
218
-
219
- ## Integration Points
220
- - [How this integrates with other parts]
221
-
222
- ---
223
-
224
- *This file was created as part of the 3-tier documentation system to document [brief reason].*
225
- ```
226
-
227
- ## Step 8: Tier-First Documentation Updates
228
-
229
- **CRITICAL: Always start with Tier 3 (feature-specific) documentation and work upward through the tiers. Never skip tiers.**
230
-
231
- ### Tier 3 (Feature-Specific) - START HERE
232
- **Always begin with the most granular documentation closest to your changes:**
233
- - **Identify affected Tier 3 files** (feature-specific CONTEXT.md files in subdirectories)
234
- - **Update these granular files first** with specific implementation details, patterns, and integration points
235
- - **Examples**: `agents/tutor-server/src/core/pipelines/CONTEXT.md`, `web-dashboard/src/lib/api/CONTEXT.md`, `agents/tutor-server/src/features/*/CONTEXT.md`
236
- - **Update guidelines**: Be specific about file names, technologies, implementation patterns
237
-
238
- ### Tier 2 (Component-Level) - CASCADE UP
239
- **After completing Tier 3 updates, evaluate if component-level changes are needed:**
240
- - **Check parent component CONTEXT.md files** (e.g., `agents/tutor-server/CONTEXT.md` for changes in `agents/tutor-server/src/*/`)
241
- - **Update if changes represent significant architectural shifts** affecting the overall component
242
- - **Focus on**: How granular changes affect component architecture, new integration patterns, major feature additions
243
- - **Examples**: `agents/tutor-server/CONTEXT.md`, `web-dashboard/CONTEXT.md`, `unity-client/CONTEXT.md`
244
-
245
- ### Tier 1 (Foundational) - CASCADE UP
246
- **Finally, check if foundational documentation needs updates for system-wide impacts:**
247
-
248
- #### Project Structure Updates (`/docs/ai-context/project-structure.md`)
249
- Update for any of these changes:
250
- - **File tree changes**: Created, moved, deleted files/directories; renamed components; restructured organization
251
- - **Technology stack updates**: New dependencies (check pyproject.toml, package.json), major version updates, new frameworks, AI service changes, development tool modifications
252
-
253
- #### Other Foundational Documentation
254
- Update other `/docs/ai-context/` files if changes affect:
255
- - **System-wide architectural patterns**
256
- - **Cross-component integration approaches**
257
- - **Development workflow or standards**
258
-
259
- ### Cascade Decision Logic
260
- **What Constitutes "Significant Updates" Requiring Cascade:**
261
- - **New major feature areas** (not just bug fixes or minor enhancements)
262
- - **Architectural pattern changes** that affect how components integrate with others
263
- - **New technologies or frameworks** introduced to a component
264
- - **Major refactoring** that changes component structure or responsibilities
265
- - **New integration points** between components or external systems
266
-
267
- ### Update Quality Guidelines (All Tiers)
268
- - **Be concise** (max 3 sentences unless major architectural change)
269
- - **Be specific** (include file names, technologies, key benefits)
270
- - **Follow existing patterns** in each document
271
- - **Avoid redundancy** (don't repeat what's already documented)
272
- - **Co-locate knowledge** (keep documentation near relevant code)
273
-
274
- ## Step 9: Update Documentation Overview
275
-
276
- **IMPORTANT:** After updating any documentation files in steps 1-8, check if the documentation overview needs updates:
277
- - Reference the auto-loaded `/docs/ai-context/docs-overview.md`
278
- - If you added new documentation files (especially new CONTEXT.md files), update the overview to include them in the appropriate tier
279
- - If you significantly changed the structure/purpose of existing documentation, update the overview to reflect these changes
280
- - Keep the overview accurate and current so it serves as a reliable guide to the documentation architecture
281
-
282
- ### Special Note for New CONTEXT.md Files:
283
- When you create new granular CONTEXT.md files, you MUST add them to the appropriate section in docs-overview.md:
284
- - **Tier 2 (Component-Level)**: For new top-level components
285
- - **Tier 3 (Feature-Specific)**: For new subsystem documentation within existing components
286
-
287
- ## Quality Guidelines
288
-
289
- - **Concise:** Keep updates brief and focused
290
- - **Specific:** Include file names, technologies, key benefits
291
- - **Accurate:** Based on actual changes made, not assumptions
292
- - **Helpful:** Information that would be useful to another developer
293
- - **Current:** Ensure file tree reflects actual project structure
294
- - **Organized:** Follow the 3-tier documentation system principles
295
-
296
- ## When Not to Update or Create Documentation
297
-
298
- Skip documentation updates/creation for:
299
- - Bug fixes (unless they change architecture)
300
- - Minor tweaks or cleanup
301
- - Debugging or temporary changes
302
- - Code formatting or comments
303
- - Trivial modifications
304
- - Single-file additions that fit existing documentation scope
305
-
306
- ## 3-Tier System Benefits
307
-
308
- This enhanced approach leverages the 3-tier documentation system to:
309
- - **Minimize cascade effects**: Most changes update 1-2 granular files
310
- - **Scale intelligently**: New documentation created only when warranted
311
- - **Co-locate knowledge**: Documentation lives near relevant code
312
- - **Maintain consistency**: Clear guidelines for when and how to extend documentation
313
-
314
- Now analyze the specified changes and update the relevant documentation accordingly.
@@ -1,270 +0,0 @@
1
- # Claude Code Hooks
2
-
3
- This directory contains battle-tested hooks that enhance your Claude Code development experience with automated security scanning, intelligent context injection, and pleasant audio feedback.
4
-
5
- ## Architecture
6
-
7
- ```
8
- Claude Code Lifecycle
9
-
10
- ├── PreToolUse ──────► Security Scanner
11
- │ ├── Context Injector (Gemini)
12
- │ └── Context Injector (Subagents)
13
-
14
- ├── Tool Execution
15
-
16
- ├── PostToolUse
17
-
18
- ├── Notification ────────► Audio Feedback
19
-
20
- └── Stop/SubagentStop ───► Completion Sound
21
- ```
22
-
23
- These hooks execute at specific points in Claude Code's lifecycle, providing deterministic control over AI behavior.
24
-
25
- ## Available Hooks
26
-
27
- ### 1. Gemini Context Injector (`gemini-context-injector.sh`)
28
-
29
- **Purpose**: Automatically includes your project documentation and assistant rules when starting new Gemini consultation sessions, ensuring the AI has complete context about your codebase and project standards.
30
-
31
- **Trigger**: `PreToolUse` for `mcp__gemini__consult_gemini`
32
-
33
- **Features**:
34
- - Detects new Gemini consultation sessions (no session_id)
35
- - Automatically attaches two key files:
36
- - `docs/ai-context/project-structure.md` - Complete project structure and tech stack
37
- - `MCP-ASSISTANT-RULES.md` - Project-specific coding standards and guidelines
38
- - Preserves existing file attachments
39
- - Session-aware (only injects on new sessions)
40
- - Logs all injection events for debugging
41
- - Fails gracefully if either file is missing
42
- - Handles partial availability (will attach whichever files exist)
43
-
44
- **Customization**:
45
- - Copy `docs/MCP-ASSISTANT-RULES.md` template to your project root
46
- - Customize it with your project-specific standards, principles, and constraints
47
- - The hook will automatically include it in Gemini consultations
48
-
49
- ### 2. MCP Security Scanner (`mcp-security-scan.sh`)
50
-
51
- **Purpose**: Prevents accidental exposure of secrets, API keys, and sensitive data when using MCP servers like Gemini or Context7.
52
-
53
- **Trigger**: `PreToolUse` for all MCP tools (`mcp__.*`)
54
-
55
- **Features**:
56
- - Pattern-based detection for API keys, passwords, and secrets
57
- - Scans code context, problem descriptions, and attached files
58
- - File content scanning with size limits
59
- - Configurable pattern matching via `config/sensitive-patterns.json`
60
- - Whitelisting for placeholder values
61
- - Command injection protection for Context7
62
- - Comprehensive logging of security events to `.claude/logs/`
63
-
64
- **Customization**: Edit `config/sensitive-patterns.json` to:
65
- - Add custom API key patterns
66
- - Modify credential detection rules
67
- - Update sensitive file patterns
68
- - Extend the whitelist for your placeholders
69
-
70
- ### 3. Subagent Context Injector (`subagent-context-injector.sh`)
71
-
72
- **Purpose**: Automatically includes core project documentation in all sub-agent Task prompts, ensuring consistent context across multi-agent workflows.
73
-
74
- **Trigger**: `PreToolUse` for `Task` tool
75
-
76
- **Features**:
77
- - Intercepts all Task tool calls before execution
78
- - Prepends references to three core documentation files:
79
- - `docs/CLAUDE.md` - Project overview, coding standards, AI instructions
80
- - `docs/ai-context/project-structure.md` - Complete file tree and tech stack
81
- - `docs/ai-context/docs-overview.md` - Documentation architecture
82
- - Passes through non-Task tools unchanged
83
- - Preserves original task prompt by prepending context
84
- - Enables consistent knowledge across all sub-agents
85
- - Eliminates need for manual context inclusion in Task prompts
86
-
87
- **Benefits**:
88
- - Every sub-agent starts with the same foundational knowledge
89
- - No manual context specification needed in each Task prompt
90
- - Token-efficient through @ references instead of content duplication
91
- - Update context in one place, affects all sub-agents
92
- - Clean operation with simple pass-through for non-Task tools
93
-
94
- ### 4. Notification System (`notify.sh`)
95
-
96
- **Purpose**: Provides pleasant audio feedback when Claude Code needs your attention or completes tasks.
97
-
98
- **Triggers**:
99
- - `Notification` events (all notifications including input needed)
100
- - `Stop` events (main task completion)
101
-
102
- **Features**:
103
- - Cross-platform audio support (macOS, Linux, Windows)
104
- - Non-blocking audio playback (runs in background)
105
- - Multiple audio playback fallbacks
106
- - Pleasant notification sounds
107
- - Two notification types:
108
- - `input`: When Claude needs user input
109
- - `complete`: When Claude completes tasks
110
-
111
- ## Installation
112
-
113
- 1. **Copy the hooks to your project**:
114
- ```bash
115
- cp -r hooks your-project/.claude/
116
- ```
117
-
118
- 2. **Configure hooks in your project**:
119
- ```bash
120
- cp hooks/setup/settings.json.template your-project/.claude/settings.json
121
- ```
122
- Then edit the WORKSPACE path in the settings file.
123
-
124
- 3. **Test the hooks**:
125
- ```bash
126
- # Test notification
127
- .claude/hooks/notify.sh input
128
- .claude/hooks/notify.sh complete
129
-
130
- # View logs
131
- tail -f .claude/logs/context-injection.log
132
- tail -f .claude/logs/security-scan.log
133
- ```
134
-
135
- ## Hook Configuration
136
-
137
- Add to your Claude Code `settings.json`:
138
-
139
- ```json
140
- {
141
- "hooks": {
142
- "PreToolUse": [
143
- {
144
- "matcher": "mcp__gemini__consult_gemini",
145
- "hooks": [
146
- {
147
- "type": "command",
148
- "command": "${WORKSPACE}/.claude/hooks/gemini-context-injector.sh"
149
- }
150
- ]
151
- },
152
- {
153
- "matcher": "mcp__.*",
154
- "hooks": [
155
- {
156
- "type": "command",
157
- "command": "${WORKSPACE}/.claude/hooks/mcp-security-scan.sh"
158
- }
159
- ]
160
- },
161
- {
162
- "matcher": "Task",
163
- "hooks": [
164
- {
165
- "type": "command",
166
- "command": "${WORKSPACE}/.claude/hooks/subagent-context-injector.sh"
167
- }
168
- ]
169
- }
170
- ],
171
- "Notification": [
172
- {
173
- "matcher": ".*",
174
- "hooks": [
175
- {
176
- "type": "command",
177
- "command": "${WORKSPACE}/.claude/hooks/notify.sh input"
178
- }
179
- ]
180
- }
181
- ],
182
- "Stop": [
183
- {
184
- "matcher": ".*",
185
- "hooks": [
186
- {
187
- "type": "command",
188
- "command": "${WORKSPACE}/.claude/hooks/notify.sh complete"
189
- }
190
- ]
191
- }
192
- ]
193
- }
194
- }
195
- ```
196
-
197
- See `hooks/setup/settings.json.template` for the complete configuration including all hooks and MCP servers.
198
-
199
- ## Security Model
200
-
201
- 1. **Execution Context**: Hooks run with full user permissions
202
- 2. **Blocking Behavior**: Exit code 2 blocks tool execution
203
- 3. **Data Flow**: Hooks can modify tool inputs via JSON transformation
204
- 4. **Isolation**: Each hook runs in its own process
205
- 5. **Logging**: All security events logged to `.claude/logs/`
206
-
207
- ## Integration with MCP Servers
208
-
209
- The hooks system complements MCP server integrations:
210
-
211
- - **Gemini Consultation**: Context injector ensures both project structure and MCP assistant rules are included
212
- - **Context7 Documentation**: Security scanner protects library ID inputs
213
- - **All MCP Tools**: Universal security scanning before external calls
214
-
215
- ## Best Practices
216
-
217
- 1. **Hook Design**:
218
- - Fail gracefully - never break the main workflow
219
- - Log important events for debugging
220
- - Use exit codes appropriately (0=success, 2=block)
221
- - Keep execution time minimal
222
-
223
- 2. **Security**:
224
- - Regularly update sensitive patterns
225
- - Review security logs periodically
226
- - Test hooks in safe environments first
227
- - Never log sensitive data in hooks
228
-
229
- 3. **Configuration**:
230
- - Use `${WORKSPACE}` variable for portability
231
- - Keep hooks executable (`chmod +x`)
232
- - Version control hook configurations
233
- - Document custom modifications
234
-
235
- ## Troubleshooting
236
-
237
- ### Hooks not executing
238
- - Check file permissions: `chmod +x *.sh`
239
- - Verify paths in settings.json
240
- - Check Claude Code logs for errors
241
-
242
- ### Security scanner too restrictive
243
- - Review patterns in `config/sensitive-patterns.json`
244
- - Add legitimate patterns to the whitelist
245
- - Check logs for what triggered the block
246
-
247
- ### No sound playing
248
- - Verify sound files exist in `sounds/` directory
249
- - Test audio playback: `.claude/hooks/notify.sh input`
250
- - Check system audio settings
251
- - Ensure you have an audio player installed (afplay, paplay, aplay, pw-play, play, ffplay, or PowerShell on Windows)
252
-
253
- ## Hook Setup Command
254
-
255
- For comprehensive setup verification and testing, use:
256
-
257
- ```
258
- /hook-setup
259
- ```
260
-
261
- This command uses multi-agent orchestration to verify installation, check configuration, and run comprehensive tests. See [hook-setup.md](setup/hook-setup.md) for details.
262
-
263
- ## Extension Points
264
-
265
- The kit is designed for extensibility:
266
-
267
- 1. **Custom Hooks**: Add new scripts following the existing patterns
268
- 2. **Event Handlers**: Configure hooks for any Claude Code event
269
- 3. **Pattern Updates**: Modify security patterns for your needs
270
- 4. **Sound Customization**: Replace audio files with your preferences
@@ -1,86 +0,0 @@
1
- {
2
- "patterns": {
3
- "api_keys": [],
4
- "credentials": [
5
- "password\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
6
- "passwd\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
7
- "secret\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
8
- "private[_-]?key\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
9
- "access[_-]?key\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
10
- "auth[_-]?token\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
11
- "api[_-]?key\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?",
12
- "client[_-]?secret\\s*[:=]\\s*[\"']?[^\\s\"']+[\"']?"
13
- ],
14
- "sensitive_files": [
15
- ".env",
16
- ".env.local",
17
- ".env.production",
18
- ".env.development",
19
- ".env.staging",
20
- "credentials.json",
21
- "google-credentials.json",
22
- "service-account.json",
23
- "private.key",
24
- "id_rsa",
25
- "id_ed25519",
26
- "id_dsa",
27
- "id_ecdsa",
28
- ".pem",
29
- ".key",
30
- ".p12",
31
- ".pfx",
32
- "keystore",
33
- ".jks"
34
- ],
35
- "regex_patterns": [
36
- "sk-[a-zA-Z0-9]{32,}",
37
- "sk-proj-[a-zA-Z0-9]{32,}",
38
- "AIza[0-9A-Za-z\\-_]{35}",
39
- "gsk_[a-zA-Z0-9]{32,}",
40
- "AKIA[0-9A-Z]{16}",
41
- "aws_secret_access_key\\s*=\\s*[a-zA-Z0-9/+=]{40}",
42
- "(postgres|postgresql|mysql|mongodb|redis)://[^:]+:[^@]+@[^/]+",
43
- "-----BEGIN.*(RSA|DSA|EC|OPENSSH|PGP).*PRIVATE KEY-----",
44
- "Bearer\\s+[a-zA-Z0-9\\-_]+\\.[a-zA-Z0-9\\-_]+\\.[a-zA-Z0-9\\-_]+",
45
- "[A-Z_]+(KEY|TOKEN|SECRET|PASSWORD|PASSWD)\\s*=\\s*[\"']?[^\\s\"']+[\"']?",
46
- "(api[_-]?key|access[_-]?token|auth[_-]?token)\\s*[:=]\\s*[\"']?[a-zA-Z0-9_\\-]{20,}[\"']?",
47
- "(password|secret|key)\\s*[:=]\\s*[\"']?[A-Za-z0-9+/]{40,}={0,2}[\"']?",
48
- "ghp_[a-zA-Z0-9]{36}",
49
- "gho_[a-zA-Z0-9]{36}",
50
- "github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}",
51
- "glpat-[a-zA-Z0-9\\-_]{20}",
52
- "xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}",
53
- "sq0atp-[0-9A-Za-z\\-_]{22}",
54
- "sq0csp-[0-9A-Za-z\\-_]{43}",
55
- "SK[a-z0-9]{32}"
56
- ]
57
- },
58
- "whitelist": {
59
- "allowed_mentions": [
60
- "GOOGLE_API_KEY=your_google_api_key_here",
61
- "GROQ_API_KEY=your_groq_api_key_here",
62
- "OPENAI_API_KEY=your_openai_api_key_here",
63
- "GEMINI_API_KEY=your_gemini_api_key_here",
64
- "AWS_ACCESS_KEY_ID=your_access_key_here",
65
- "api_key=settings.api_key",
66
- "api_key=process.env.API_KEY",
67
- "api_key=YOUR_API_KEY",
68
- "password=your_password_here",
69
- "password=<your_password>",
70
- "password=${PASSWORD}",
71
- "token=your_token_here",
72
- "token=<auth_token>",
73
- "secret=your_secret_here",
74
- "Bearer YOUR_TOKEN_HERE",
75
- "Bearer <token>",
76
- "postgres://user:password@localhost",
77
- "mysql://root:password@localhost",
78
- "mongodb://user:password@localhost",
79
- "redis://user:password@localhost",
80
- "connection_string = \"your_connection_string_here\"",
81
- "API_KEY=<your_api_key>",
82
- "SECRET_KEY=<your_secret_key>",
83
- "DATABASE_URL=<your_database_url>"
84
- ]
85
- }
86
- }