@zenuml/core 3.47.9 → 3.48.1

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/zenuml.mjs +13529 -0
  2. package/dist/cli/zenuml.mjs.map +1 -0
  3. package/dist/cloud-icons-eHuugVSv.js.map +1 -0
  4. package/dist/zenuml.esm.mjs +2153 -2156
  5. package/dist/zenuml.esm.mjs.map +1 -0
  6. package/dist/zenuml.js +82 -82
  7. package/dist/zenuml.js.map +1 -0
  8. package/package.json +18 -5
  9. package/.agents/skills/babysit-pr/SKILL.md +0 -223
  10. package/.agents/skills/babysit-pr/agents/openai.yaml +0 -7
  11. package/.agents/skills/dia-scoring/SKILL.md +0 -139
  12. package/.agents/skills/dia-scoring/agents/openai.yaml +0 -7
  13. package/.agents/skills/dia-scoring/references/selectors-and-keys.md +0 -253
  14. package/.agents/skills/land-pr/SKILL.md +0 -120
  15. package/.agents/skills/propagate-core-release/SKILL.md +0 -205
  16. package/.agents/skills/propagate-core-release/agents/openai.yaml +0 -7
  17. package/.agents/skills/propagate-core-release/references/downstreams.md +0 -42
  18. package/.agents/skills/ship-branch/SKILL.md +0 -105
  19. package/.agents/skills/submit-branch/SKILL.md +0 -76
  20. package/.agents/skills/validate-branch/SKILL.md +0 -72
  21. package/.claude/commands/README.md +0 -162
  22. package/.claude/commands/analyze.md +0 -101
  23. package/.claude/commands/clarify.md +0 -158
  24. package/.claude/commands/code-review.md +0 -322
  25. package/.claude/commands/constitution.md +0 -73
  26. package/.claude/commands/create-docs.md +0 -309
  27. package/.claude/commands/full-context.md +0 -121
  28. package/.claude/commands/gemini-consult.md +0 -164
  29. package/.claude/commands/handoff.md +0 -146
  30. package/.claude/commands/implement.md +0 -56
  31. package/.claude/commands/plan.md +0 -43
  32. package/.claude/commands/refactor.md +0 -188
  33. package/.claude/commands/specify.md +0 -21
  34. package/.claude/commands/tasks.md +0 -62
  35. package/.claude/commands/update-docs.md +0 -314
  36. package/.claude/hooks/README.md +0 -270
  37. package/.claude/hooks/config/sensitive-patterns.json +0 -86
  38. package/.claude/hooks/gemini-context-injector.sh +0 -129
  39. package/.claude/hooks/mcp-security-scan.sh +0 -147
  40. package/.claude/hooks/notify.sh +0 -103
  41. package/.claude/hooks/setup/hook-setup.md +0 -96
  42. package/.claude/hooks/setup/settings.json.template +0 -63
  43. package/.claude/hooks/sounds/complete.wav +0 -0
  44. package/.claude/hooks/sounds/input-needed.wav +0 -0
  45. package/.claude/hooks/subagent-context-injector.sh +0 -65
  46. package/.claude/skills/babysit-pr/SKILL.md +0 -223
  47. package/.claude/skills/babysit-pr/agents/openai.yaml +0 -7
  48. package/.claude/skills/dia-scoring/SKILL.md +0 -139
  49. package/.claude/skills/dia-scoring/agents/openai.yaml +0 -7
  50. package/.claude/skills/dia-scoring/references/selectors-and-keys.md +0 -253
  51. package/.claude/skills/emoji-eval/SKILL.md +0 -187
  52. package/.claude/skills/land-pr/SKILL.md +0 -120
  53. package/.claude/skills/propagate-core-release/SKILL.md +0 -205
  54. package/.claude/skills/propagate-core-release/agents/openai.yaml +0 -7
  55. package/.claude/skills/propagate-core-release/references/downstreams.md +0 -42
  56. package/.claude/skills/ship-branch/SKILL.md +0 -105
  57. package/.claude/skills/submit-branch/SKILL.md +0 -76
  58. package/.claude/skills/validate-branch/SKILL.md +0 -72
  59. package/.claude/skills/zenuml-ux-research/SKILL.md +0 -183
  60. package/.claude/skills/zenuml-ux-research/references/assertion-catalog.md +0 -261
  61. package/.claude/skills/zenuml-ux-research/references/best-practices-overview.md +0 -56
  62. package/.claude/skills/zenuml-ux-research/references/report-template.md +0 -89
  63. package/.claude/skills/zenuml-ux-research/references/scenarios/edit-message-label.md +0 -37
  64. package/.claude/skills/zenuml-ux-research/references/scenarios/insert-message.md +0 -36
  65. package/.claude/skills/zenuml-ux-research/references/scenarios/insert-participant.md +0 -31
  66. package/.claude/skills/zenuml-ux-research/references/scenarios/rename-participant.md +0 -33
  67. package/.claude/skills/zenuml-ux-research/references/scenarios/undo-insert.md +0 -35
  68. package/.devcontainer/devcontainer.json +0 -21
  69. package/.dockerignore +0 -19
  70. package/.eslintrc.js +0 -39
  71. package/.git-blame-ignore-revs +0 -6
  72. package/.kiro/hooks/README.md +0 -38
  73. package/.kiro/hooks/session-sound-notification.js +0 -44
  74. package/.kiro/hooks/session-sound-notification.json +0 -23
  75. package/.mcp.json.example +0 -17
  76. package/.nvmrc +0 -1
  77. package/.prettierignore +0 -4
  78. package/.prettierrc +0 -1
  79. package/.specify/memory/constitution.md +0 -33
  80. package/.specify/scripts/bash/check-prerequisites.sh +0 -166
  81. package/.specify/scripts/bash/common.sh +0 -113
  82. package/.specify/scripts/bash/create-new-feature.sh +0 -97
  83. package/.specify/scripts/bash/setup-plan.sh +0 -60
  84. package/.specify/scripts/bash/update-agent-context.sh +0 -728
  85. package/.specify/templates/agent-file-template.md +0 -23
  86. package/.specify/templates/plan-template.md +0 -219
  87. package/.specify/templates/spec-template.md +0 -116
  88. package/.specify/templates/tasks-template.md +0 -127
  89. package/.storybook/main.ts +0 -25
  90. package/.storybook/preview.ts +0 -29
  91. package/.watchmanconfig +0 -3
  92. package/AGENTS.md +0 -26
  93. package/CLAUDE.md +0 -124
  94. package/DEPLOYMENT.md +0 -62
  95. package/Dockerfile +0 -36
  96. package/IMPLEMENTATION_PLAN.md +0 -163
  97. package/Integration/vanilla-js/index.html +0 -42
  98. package/MCP-ASSISTANT-RULES.md +0 -85
  99. package/README_CN.md +0 -15
  100. package/TUTORIAL.md +0 -116
  101. package/antlr/antlr-4.11.1-complete.jar +0 -0
  102. package/bun.lock +0 -1544
  103. package/bunfig.toml +0 -52
  104. package/docs/UNICODE_SUPPORT.md +0 -179
  105. package/docs/ai-context/deployment-infrastructure.md +0 -21
  106. package/docs/ai-context/docs-overview.md +0 -89
  107. package/docs/ai-context/handoff.md +0 -174
  108. package/docs/ai-context/project-structure.md +0 -160
  109. package/docs/ai-context/system-integration.md +0 -21
  110. package/docs/asciidoc/contributor.adoc +0 -54
  111. package/docs/asciidoc/create-my-own-theme.adoc +0 -149
  112. package/docs/asciidoc/images/creation-component.png +0 -0
  113. package/docs/asciidoc/images/creation-rtl.png +0 -0
  114. package/docs/asciidoc/images/message-arrow-rtl.png +0 -0
  115. package/docs/asciidoc/images/occurrence.png +0 -0
  116. package/docs/asciidoc/images/return-message-conflict.png +0 -0
  117. package/docs/asciidoc/images/shift-up-half-the-height.png +0 -0
  118. package/docs/asciidoc/images/three-layer-info-arch.png +0 -0
  119. package/docs/asciidoc/images/vertical-alignment.svg +0 -1
  120. package/docs/asciidoc/images/vertically-aligning.png +0 -0
  121. package/docs/asciidoc/index.adoc +0 -277
  122. package/docs/asciidoc/theme-debug-web-app.png +0 -0
  123. package/docs/asciidoc/tutorial.adoc +0 -22
  124. package/docs/asciidoc/user-css.png +0 -0
  125. package/docs/async-vs-sync-parser-rules.md +0 -81
  126. package/docs/divider-parser-allow-spaces.md +0 -38
  127. package/docs/highlighting-messages.md +0 -52
  128. package/docs/images/editor-sample.png +0 -0
  129. package/docs/inherited-vs-provided-from.md +0 -64
  130. package/docs/parser/Assignment.md +0 -8
  131. package/docs/parser/PARSER_IMPROVEMENTS_CC.md +0 -425
  132. package/docs/parser/grammar_review_gemini.md +0 -116
  133. package/docs/participants-function.md +0 -25
  134. package/docs/responsive-participant-margin.md +0 -52
  135. package/docs/starter.md +0 -9
  136. package/docs/superpowers/plans/2026-03-27-e2e-test-reorg.md +0 -698
  137. package/docs/superpowers/plans/2026-03-30-emoji-support.md +0 -1220
  138. package/docs/superpowers/plans/2026-03-30-self-correcting-scoring.md +0 -206
  139. package/docs/superpowers/plans/2026-04-15-keyboard-editing-on-diagram.md +0 -1992
  140. package/docs/superpowers/plans/2026-04-15-zenuml-ux-research-skill.md +0 -1452
  141. package/docs/ux-research/.gitkeep +0 -0
  142. package/docs/ux-research/2026-04-15-rename-participant.md +0 -156
  143. package/docs/ux-research/2026-04-18-insert-participant.md +0 -151
  144. package/docs/width-translate-and-offsets.md +0 -62
  145. package/docs/xss.md +0 -59
  146. package/e2e/data/compare-cases.js +0 -1090
  147. package/e2e/data/diff-algorithm.js +0 -199
  148. package/e2e/fixtures/create-message.html +0 -26
  149. package/e2e/fixtures/editable-label.html +0 -35
  150. package/e2e/fixtures/editable-span.html +0 -122
  151. package/e2e/fixtures/empty-diagram.html +0 -23
  152. package/e2e/fixtures/fixture.html +0 -31
  153. package/e2e/fixtures/insert-participant.html +0 -23
  154. package/e2e/fixtures/reorder-cross-fragment.html +0 -31
  155. package/e2e/fixtures/reorder-fragment.html +0 -29
  156. package/e2e/fixtures/reorder-message.html +0 -27
  157. package/e2e/fixtures/svg-test.html +0 -21
  158. package/e2e/fixtures/type-switch.html +0 -29
  159. package/e2e/tools/canonical-history.html +0 -908
  160. package/e2e/tools/compare-case.html +0 -371
  161. package/e2e/tools/compare.html +0 -35
  162. package/e2e/tools/native-diff-ext/background.js +0 -60
  163. package/e2e/tools/native-diff-ext/bridge.js +0 -26
  164. package/e2e/tools/native-diff-ext/content.js +0 -194
  165. package/e2e/tools/svg-preview.html +0 -56
  166. package/embed.html +0 -193
  167. package/eslint.config.mjs +0 -35
  168. package/firebase-debug.log +0 -108
  169. package/iframe-container-demo/diagram.html +0 -124
  170. package/iframe-container-demo/host.html +0 -817
  171. package/index.html +0 -771
  172. package/mermaid-zenuml-async-spa-auth.png +0 -0
  173. package/mermaid-zenuml-async-spa-auth.snapshot.md +0 -96
  174. package/newsletter/unicode-support-announcement.md +0 -134
  175. package/playground/creation.html +0 -53
  176. package/playground/message.html +0 -63
  177. package/playwright.config.ts +0 -40
  178. package/renderer.html +0 -366
  179. package/scripts/analyze-compare-case/collect-data.mjs +0 -1134
  180. package/scripts/analyze-compare-case/config.mjs +0 -102
  181. package/scripts/analyze-compare-case/geometry.mjs +0 -101
  182. package/scripts/analyze-compare-case/native-diff.mjs +0 -224
  183. package/scripts/analyze-compare-case/output.mjs +0 -74
  184. package/scripts/analyze-compare-case/panel-diff.mjs +0 -114
  185. package/scripts/analyze-compare-case/report.mjs +0 -162
  186. package/scripts/analyze-compare-case/residual-scopes.mjs +0 -347
  187. package/scripts/analyze-compare-case/scoring.mjs +0 -829
  188. package/scripts/analyze-compare-case.mjs +0 -149
  189. package/scripts/bump-version.js +0 -117
  190. package/scripts/snapshot-dual.js +0 -173
  191. package/scripts/update-snapshots.js +0 -70
  192. package/skills/dia-scoring/SKILL.md +0 -129
  193. package/skills/dia-scoring/agents/openai.yaml +0 -7
  194. package/skills/dia-scoring/references/selectors-and-keys.md +0 -253
  195. package/tailwind.config.js +0 -126
  196. package/test-compression.html +0 -274
  197. package/test-mermaid-zenuml.html +0 -57
  198. package/test-setup.ts +0 -124
  199. package/test-url-params.html +0 -192
  200. package/tsconfig.app.json +0 -31
  201. package/tsconfig.node.json +0 -24
  202. package/tsconfig.test.json +0 -9
  203. package/vite.config.lib.ts +0 -93
  204. package/vite.config.ts +0 -84
  205. package/wrangler.toml +0 -18
package/bunfig.toml DELETED
@@ -1,52 +0,0 @@
1
- # Bun configuration file
2
-
3
- [test]
4
- # Preload setup file for test environment
5
- preload = ["./test-setup.ts"]
6
-
7
- # Project root directory
8
- root = "./"
9
-
10
- # Note: To exclude /tests folder (Playwright tests), use the npm script:
11
- # bun run test:bun
12
- # Or run directly: bun test 'src/**/*.{spec,test}.{ts,tsx}' 'test/**/*.{spec,test}.{ts,tsx}'
13
-
14
- # Coverage configuration
15
- # Disabled by default due to resource issues with large asset files
16
- # Enable with: bun test --coverage
17
- coverage = false
18
- coverageReporter = ["text"]
19
- coverageDirectory = "./coverage"
20
-
21
- # Timeout for tests (in milliseconds)
22
- timeout = 5000
23
-
24
- # Run tests in watch mode by default
25
- # watch = false
26
-
27
- [install]
28
- # Package manager settings
29
- peer = true
30
- dev = true
31
- optional = true
32
-
33
- # Auto install dependencies
34
- auto = "auto"
35
-
36
- # Disable cache if needed
37
- # disable = false
38
-
39
- [install.lockfile]
40
- # Save exact versions
41
- save = true
42
-
43
- # Print changes to lockfile
44
- print = "bun"
45
-
46
- [run]
47
- # Bun runtime settings for scripts
48
- # Silent mode for cleaner output
49
- # silent = false
50
-
51
- # Automatically install missing packages when running scripts
52
- autoInstall = true
@@ -1,179 +0,0 @@
1
- # Unicode 字符支持
2
-
3
- ZenUML 现在完全支持 Unicode 字符,包括中文、日文、韩文、阿拉伯文、俄文等多种语言的标识符。
4
-
5
- ## 功能特性
6
-
7
- ### 1. 直接使用 Unicode 字符作为标识符
8
-
9
- 您可以直接使用任何 Unicode 字母字符作为:
10
- - 参与者名称
11
- - 方法名称
12
- - 变量名称
13
- - 参数名称
14
-
15
- **示例:**
16
-
17
- ```zenuml
18
- // 中文标识符
19
- 用户 订单服务 数据库
20
-
21
- 用户.登录()
22
- 订单服务.创建订单()
23
- 数据库.保存数据()
24
- return 成功
25
- ```
26
-
27
- ### 2. 包含空格的文本使用引号
28
-
29
- 如果标识符中需要包含空格或特殊字符,请使用双引号:
30
-
31
- ```zenuml
32
- // 使用引号处理包含空格的名称
33
- "用户 服务" "订单 管理系统"
34
-
35
- "用户 服务"."获取 用户信息"()
36
- "订单 管理系统"."创建 新订单"()
37
- return "操作 成功"
38
- ```
39
-
40
- ### 3. 中英文混合支持
41
-
42
- 您可以自由混合使用中文和英文:
43
-
44
- ```zenuml
45
- UserService 数据库 CacheManager
46
-
47
- UserService.获取用户()
48
- 数据库.query("SELECT * FROM users")
49
- CacheManager.缓存结果()
50
- ```
51
-
52
- ## 支持的 Unicode 范围
53
-
54
- 当前实现支持所有 Unicode 字母字符,包括但不限于:
55
-
56
- - **中文**:汉字字符
57
- - **日文**:平假名、片假名、汉字
58
- - **韩文**:韩文字母
59
- - **阿拉伯文**:阿拉伯字母
60
- - **俄文**:西里尔字母
61
- - **其他**:所有 Unicode 定义的字母字符
62
-
63
- ## 使用规则
64
-
65
- 1. **标识符规则**:
66
- - 必须以 Unicode 字母或下划线 `_` 开头
67
- - 可以包含 Unicode 字母、数字和下划线
68
- - 不能包含空格(需要空格请使用引号)
69
-
70
- 2. **引号字符串**:
71
- - 可以包含任何字符(除了换行符)
72
- - 适用于包含空格或特殊字符的文本
73
-
74
- 3. **保留关键字**:
75
- - 英文关键字(如 `if`, `while`, `return` 等)保持不变
76
- - 不能使用保留关键字作为标识符
77
-
78
- ## 实际应用示例
79
-
80
- ### 示例 1:订单处理流程
81
-
82
- ```zenuml
83
- title "订单处理流程"
84
-
85
- @Actor 用户
86
- @Service 订单服务
87
- @Database 数据库
88
-
89
- 用户->订单服务: 创建订单
90
- 订单服务.验证订单() {
91
- if (库存充足) {
92
- 数据库.保存订单()
93
- return "订单创建成功"
94
- } else {
95
- return "库存不足"
96
- }
97
- }
98
- ```
99
-
100
- ### 示例 2:用户认证流程
101
-
102
- ```zenuml
103
- 用户 认证服务 令牌管理器
104
-
105
- 用户.登录(用户名, 密码)
106
- 认证服务.验证凭据(用户名, 密码) {
107
- if (验证成功) {
108
- 令牌 = 令牌管理器.生成令牌()
109
- return 令牌
110
- } else {
111
- return "认证失败"
112
- }
113
- }
114
- ```
115
-
116
- ### 示例 3:多语言混合
117
-
118
- ```zenuml
119
- // 混合多种语言的示例
120
- ユーザー // 日文
121
- 사용자 // 韩文
122
- 用户 // 中文
123
- User // 英文
124
-
125
- ユーザー.ログイン()
126
- 사용자.로그인()
127
- 用户.登录()
128
- User.login()
129
- ```
130
-
131
- ## 技术实现
132
-
133
- ### 词法分析器更改
134
-
135
- 在 `SequenceLexer.g4` 中,ID token 定义已更新为:
136
-
137
- ```antlr
138
- ID
139
- : [\p{L}_] [\p{L}\p{Nd}_]*
140
- ;
141
- ```
142
-
143
- - `\p{L}` 匹配任何 Unicode 字母
144
- - `\p{Nd}` 匹配任何 Unicode 十进制数字
145
- - 保持了对下划线 `_` 的支持
146
-
147
- ### 向后兼容性
148
-
149
- 所有现有的 ASCII 标识符仍然完全支持:
150
- - 英文字母 (a-z, A-Z)
151
- - 数字 (0-9)
152
- - 下划线 (_)
153
-
154
- 现有的 ZenUML 代码无需任何修改即可继续工作。
155
-
156
- ## 测试
157
-
158
- 您可以通过以下方式测试 Unicode 支持:
159
-
160
- 1. **开发服务器测试**:
161
- ```bash
162
- pnpm dev
163
- ```
164
- 然后访问 http://localhost:8080/test-chinese.html
165
-
166
- 2. **单元测试**:
167
- ```bash
168
- pnpm test src/parser/ChineseSupport.spec.ts
169
- ```
170
-
171
- ## 注意事项
172
-
173
- 1. **编码**:确保您的文件使用 UTF-8 编码保存
174
- 2. **字体支持**:渲染时需要系统或浏览器支持相应的字体
175
- 3. **方向性**:某些语言(如阿拉伯文)是从右到左书写,但在 ZenUML 中仍按从左到右的顺序处理
176
-
177
- ## 贡献
178
-
179
- 如果您发现任何 Unicode 相关的问题或有改进建议,欢迎提交 issue 或 pull request。
@@ -1,21 +0,0 @@
1
- # Deployment & Infrastructure Documentation
2
-
3
- This document contains deployment and infrastructure-related documentation for the project.
4
-
5
- ## Purpose
6
-
7
- This template serves as a placeholder for documenting:
8
- - Deployment strategies and procedures
9
- - Infrastructure architecture and configuration
10
- - CI/CD pipelines and automation
11
- - Environment management
12
- - Monitoring and observability setup
13
- - Scaling strategies and considerations
14
-
15
- ## Implementation Note
16
-
17
- Replace this template with your actual deployment and infrastructure documentation as your project develops. Focus on patterns and decisions that AI agents need to understand when working with infrastructure-related code or making architectural recommendations.
18
-
19
- ---
20
-
21
- *Customize this template based on your specific deployment and infrastructure requirements.*
@@ -1,89 +0,0 @@
1
- # Documentation Architecture
2
-
3
- This project uses a **3-tier documentation system** that organizes knowledge by stability and scope, enabling efficient AI context loading and scalable development.
4
-
5
- ## How the 3-Tier System Works
6
-
7
- **Tier 1 (Foundation)**: Stable, system-wide documentation that rarely changes - architectural principles, technology decisions, cross-component patterns, and core development protocols.
8
-
9
- **Tier 2 (Component)**: Architectural charters for major components - high-level design principles, integration patterns, and component-wide conventions without feature-specific details.
10
-
11
- **Tier 3 (Feature-Specific)**: Granular documentation co-located with code - specific implementation patterns, technical details, and local architectural decisions that evolve with features.
12
-
13
- This hierarchy allows AI agents to load targeted context efficiently while maintaining a stable foundation of core knowledge.
14
-
15
- ## Documentation Principles
16
- - **Co-location**: Documentation lives near relevant code
17
- - **Smart Extension**: New documentation files created automatically when warranted
18
- - **AI-First**: Optimized for efficient AI context loading and machine-readable patterns
19
-
20
- ## Tier 1: Foundational Documentation (System-Wide)
21
-
22
- - **[Master Context](/CLAUDE.md)** - *Essential for every session.* Coding standards, security requirements, MCP server integration patterns, and development protocols
23
- - **[Project Structure](/docs/ai-context/project-structure.md)** - *REQUIRED reading.* Complete technology stack, file tree, and system architecture. Must be attached to Gemini consultations
24
- - **[System Integration](/docs/ai-context/system-integration.md)** - *For cross-component work.* Communication patterns, data flow, testing strategies, and performance optimization
25
- - **[Deployment Infrastructure](/docs/ai-context/deployment-infrastructure.md)** - *Infrastructure patterns.* Containerization, monitoring, CI/CD workflows, and scaling strategies
26
- - **[Task Management](/docs/ai-context/handoff.md)** - *Session continuity.* Current tasks, documentation system progress, and next session goals
27
-
28
- ## Tier 2: Component-Level Documentation
29
-
30
- ### Backend Components
31
- - **[Backend Context](/backend/CONTEXT.md)** - *Server implementation.* API patterns, database integration, service architecture, and performance considerations
32
- - **[Worker Services](/workers/CONTEXT.md)** - *Background processing.* Job queue patterns, scheduling, and async task management
33
- - **[Shared Libraries](/shared/CONTEXT.md)** - *Reusable code.* Common utilities, shared types, and cross-component functionality
34
-
35
- ### Frontend Components
36
- - **[Web Application](/frontend/CONTEXT.md)** - *Client implementation.* UI patterns, state management, routing, and user interaction patterns
37
- - **[Mobile Application](/mobile/CONTEXT.md)** - *Mobile implementation.* Platform-specific patterns, native integrations, and mobile optimizations
38
- - **[Admin Dashboard](/admin/CONTEXT.md)** - *Administrative interface.* Permission patterns, admin workflows, and management tools
39
-
40
- ### Infrastructure Components
41
- - **[Infrastructure Code](/infrastructure/CONTEXT.md)** - *IaC patterns.* Terraform/CloudFormation templates, resource definitions, and deployment automation
42
- - **[Monitoring Setup](/monitoring/CONTEXT.md)** - *Observability patterns.* Metrics collection, alerting rules, and dashboard configurations
43
-
44
- ## Tier 3: Feature-Specific Documentation
45
-
46
- Granular CONTEXT.md files co-located with code for minimal cascade effects:
47
-
48
- ### Backend Feature Documentation
49
- - **[Core Services](/backend/src/core/services/CONTEXT.md)** - *Business logic patterns.* Service architecture, data processing, integration patterns, and error handling
50
- - **[API Layer](/backend/src/api/CONTEXT.md)** - *API patterns.* Endpoint design, validation, middleware, and request/response handling
51
- - **[Data Layer](/backend/src/data/CONTEXT.md)** - *Data patterns.* Database models, queries, migrations, and data access patterns
52
- - **[Authentication](/backend/src/auth/CONTEXT.md)** - *Auth patterns.* Authentication flows, authorization rules, session management, and security
53
- - **[Integrations](/backend/src/integrations/CONTEXT.md)** - *External services.* Third-party API clients, webhook handlers, and service adapters
54
-
55
- ### Frontend Feature Documentation
56
- - **[UI Components](/frontend/src/components/CONTEXT.md)** - *Component patterns.* Reusable components, styling patterns, accessibility, and composition strategies
57
- - **[State Management](/frontend/src/store/CONTEXT.md)** - *State patterns.* Global state, local state, data flow, and persistence strategies
58
- - **[API Client](/frontend/src/api/CONTEXT.md)** - *Client patterns.* HTTP clients, error handling, caching, and data synchronization
59
- - **[Routing](/frontend/src/routes/CONTEXT.md)** - *Navigation patterns.* Route definitions, guards, lazy loading, and deep linking
60
- - **[Utilities](/frontend/src/utils/CONTEXT.md)** - *Helper functions.* Formatters, validators, transformers, and common utilities
61
-
62
- ### Shared Feature Documentation
63
- - **[Common Types](/shared/src/types/CONTEXT.md)** - *Type definitions.* Shared interfaces, enums, and type utilities
64
- - **[Validation Rules](/shared/src/validation/CONTEXT.md)** - *Validation patterns.* Schema definitions, custom validators, and error messages
65
- - **[Constants](/shared/src/constants/CONTEXT.md)** - *Shared constants.* Configuration values, enums, and magic numbers
66
- - **[Utilities](/shared/src/utils/CONTEXT.md)** - *Shared utilities.* Cross-platform helpers, formatters, and common functions
67
-
68
-
69
-
70
- ## Adding New Documentation
71
-
72
- ### New Component
73
- 1. Create `/new-component/CONTEXT.md` (Tier 2)
74
- 2. Add entry to this file under appropriate section
75
- 3. Create feature-specific Tier 3 docs as features develop
76
-
77
- ### New Feature
78
- 1. Create `/component/src/feature/CONTEXT.md` (Tier 3)
79
- 2. Reference parent component patterns
80
- 3. Add entry to this file under component's features
81
-
82
- ### Deprecating Documentation
83
- 1. Remove obsolete CONTEXT.md files
84
- 2. Update this mapping document
85
- 3. Check for broken references in other docs
86
-
87
- ---
88
-
89
- *This documentation architecture template should be customized to match your project's actual structure and components. Add or remove sections based on your architecture.*
@@ -1,174 +0,0 @@
1
- # Task Management & Handoff Template
2
-
3
- This file manages task continuity, session transitions, and knowledge transfer for AI-assisted development sessions.
4
-
5
- ## Purpose
6
-
7
- This template helps maintain:
8
- - **Session continuity** between AI development sessions
9
- - **Task status tracking** for complex, multi-session work
10
- - **Context preservation** when switching between team members
11
- - **Knowledge transfer** for project handoffs
12
- - **Progress documentation** for ongoing development efforts
13
-
14
- ## Current Session Status
15
-
16
- ### Active Tasks
17
- Document currently in-progress work:
18
-
19
- ```markdown
20
- ## In Progress
21
- - [ ] Task 1: [Brief description]
22
- - Status: [Started/Blocked/Awaiting review]
23
- - Context: [Relevant files, decisions made]
24
- - Next steps: [What needs to be done next]
25
- - Dependencies: [What this task depends on]
26
-
27
- - [ ] Task 2: [Brief description]
28
- - Status: [Current status]
29
- - Files modified: [List of files changed]
30
- - Challenges: [Any issues encountered]
31
- - Notes: [Important context for continuation]
32
- ```
33
-
34
- ### Pending Tasks
35
- Document queued work:
36
-
37
- ```markdown
38
- ## Pending
39
- - [ ] Task A: [Description]
40
- - Priority: [High/Medium/Low]
41
- - Dependencies: [What must be completed first]
42
- - Estimated effort: [Time estimate]
43
- - Context: [Background information]
44
-
45
- - [ ] Task B: [Description]
46
- - Priority: [Priority level]
47
- - Requirements: [Specific requirements or constraints]
48
- - Resources needed: [Tools, access, information needed]
49
- ```
50
-
51
- ### Completed Tasks
52
- Track completed work for context:
53
-
54
- ```markdown
55
- ## Completed This Session
56
- - [x] Task X: [Description]
57
- - Completed: [Date]
58
- - Outcome: [What was accomplished]
59
- - Files changed: [Modified files]
60
- - Notes: [Important decisions or lessons learned]
61
-
62
- - [x] Task Y: [Description]
63
- - Completed: [Date]
64
- - Impact: [How this affects other tasks]
65
- - Follow-up needed: [Any follow-up actions required]
66
- ```
67
-
68
- ## Architecture & Design Decisions
69
-
70
- ### Recent Decisions
71
- Document architectural decisions made during development:
72
-
73
- ```markdown
74
- ## Design Decisions Made
75
- - **Decision**: [What was decided]
76
- - Date: [When decision was made]
77
- - Rationale: [Why this approach was chosen]
78
- - Alternatives considered: [Other options evaluated]
79
- - Impact: [How this affects the system]
80
- - Validation: [How to verify this was the right choice]
81
-
82
- - **Decision**: [Another decision]
83
- - Context: [Situation that led to this decision]
84
- - Trade-offs: [What was gained/lost with this choice]
85
- - Dependencies: [What this decision depends on]
86
- ```
87
-
88
- ### Technical Debt & Issues
89
- Track technical debt and known issues:
90
-
91
- ```markdown
92
- ## Technical Debt Identified
93
- - **Issue**: [Description of technical debt]
94
- - Location: [Where in codebase]
95
- - Impact: [How it affects development/performance]
96
- - Proposed solution: [How to address it]
97
- - Priority: [When should this be addressed]
98
-
99
- - **Issue**: [Another issue]
100
- - Root cause: [Why this debt exists]
101
- - Workaround: [Current mitigation strategy]
102
- - Long-term fix: [Proper solution approach]
103
- ```
104
-
105
- ## Next Session Goals
106
-
107
- ### Immediate Priorities
108
- Define what should be tackled next:
109
-
110
- ```markdown
111
- ## Next Session Priorities
112
- 1. **Primary Goal**: [Main objective for next session]
113
- - Success criteria: [How to know this is complete]
114
- - Prerequisites: [What must be ready beforehand]
115
- - Estimated effort: [Time estimate]
116
-
117
- 2. **Secondary Goal**: [Secondary objective]
118
- - Dependencies: [What this depends on]
119
- - Resources needed: [Tools, information, access required]
120
-
121
- 3. **If Time Permits**: [Optional tasks]
122
- - Context: [Background on why these are valuable]
123
- - Preparation: [What needs to be done to start these]
124
- ```
125
-
126
- ### Knowledge Gaps
127
- Document areas needing research or clarification:
128
-
129
- ```markdown
130
- ## Knowledge Gaps to Address
131
- - **Question**: [What needs to be clarified]
132
- - Impact: [How this affects current work]
133
- - Research needed: [What investigation is required]
134
- - Decision maker: [Who can answer this]
135
-
136
- - **Unknown**: [Technical uncertainty]
137
- - Options: [Possible approaches to explore]
138
- - Experiments: [What should be tested]
139
- - Timeline: [When this needs to be resolved]
140
- ```
141
-
142
- ## Context for Continuation
143
-
144
- ### Key Files & Components
145
- Document important files for session continuity:
146
-
147
- ```markdown
148
- ## Files Currently Being Modified
149
- - `[file-path]`: [Purpose and current changes]
150
- - `[file-path]`: [What's being implemented here]
151
- - `[file-path]`: [Status and next steps]
152
-
153
- ## Important Context Files
154
- - `[context-file]`: [Why this is relevant]
155
- - `[documentation]`: [What information this contains]
156
- - `[reference]`: [How this relates to current work]
157
- ```
158
-
159
- ### Development Environment
160
- Document environment and setup considerations:
161
-
162
- ```markdown
163
- ## Environment Status
164
- - **Development setup**: [Current state of dev environment]
165
- - **Database**: [Schema changes, migrations, data state]
166
- - **External services**: [API keys, service configurations]
167
- - **Testing**: [Test suite status, coverage, failing tests]
168
- - **Build/Deploy**: [Build status, deployment considerations]
169
- ```
170
-
171
-
172
- ---
173
-
174
- *This template provides a comprehensive framework for managing task continuity and knowledge transfer. Customize it based on your team's workflow, project complexity, and communication needs.*
@@ -1,160 +0,0 @@
1
- # Project Structure Template
2
-
3
- This document provides a template for documenting the complete technology stack and file tree structure for your project. **AI agents MUST read this file to understand the project organization before making any changes.**
4
-
5
- ## Technology Stack Template
6
-
7
- ### Backend Technologies
8
- Document your backend technology choices:
9
- - **[Language] [Version]** with **[Package Manager]** - Dependency management and packaging
10
- - **[Web Framework] [Version]** - Web framework with specific features (async, type hints, etc.)
11
- - **[Server] [Version]** - Application server configuration
12
- - **[Configuration] [Version]** - Configuration management approach
13
-
14
- Example:
15
- ```
16
- - Python 3.11+ with Poetry - Dependency management and packaging
17
- - FastAPI 0.115.0+ - Web framework with type hints and async support
18
- - Uvicorn 0.32.0+ - ASGI server with standard extras
19
- - Pydantic Settings 2.5.2+ - Configuration management with type validation
20
- ```
21
-
22
- ### Integration Services & APIs
23
- Document external services and integrations:
24
- - **[Service Name] [API/SDK Version]** - Purpose and usage pattern
25
- - **[AI Service] [Version]** - AI/ML service integration details
26
- - **[Database] [Version]** - Data storage and management
27
- - **[Monitoring] [Version]** - Observability and logging
28
-
29
- ### Real-time Communication
30
- Document real-time features:
31
- - **[WebSocket Library]** - Real-time communication patterns
32
- - **[HTTP Client]** - Async HTTP communication
33
- - **[Message Queue]** - Event processing (if applicable)
34
-
35
- ### Development & Quality Tools
36
- Document development toolchain:
37
- - **[Formatter] [Version]** - Code formatting
38
- - **[Linter] [Version]** - Code quality and linting
39
- - **[Type Checker] [Version]** - Static type checking
40
- - **[Testing Framework] [Version]** - Testing approach
41
- - **[Task Runner]** - Build automation and task orchestration
42
-
43
- ### Frontend Technologies (if applicable)
44
- Document frontend technology stack:
45
- - **[Language] [Version]** - Frontend development language
46
- - **[Framework] [Version]** - UI framework
47
- - **[Build Tool] [Version]** - Development and build tooling
48
- - **[Deployment] [Version]** - Deployment and hosting approach
49
-
50
- ### Future Technologies
51
- Document planned technology additions:
52
- - **[Planned Technology]** - Future integration plans
53
- - **[Platform]** - Target platform expansion
54
- - **[Service]** - Planned service integrations
55
-
56
- ## Complete Project Structure Template
57
-
58
- ```
59
- [PROJECT-NAME]/
60
- ├── README.md # Project overview and setup
61
- ├── CLAUDE.md # Master AI context file
62
- ├── [BUILD-FILE] # Build configuration (Makefile, package.json, etc.)
63
- ├── .gitignore # Git ignore patterns
64
- ├── .[IDE-CONFIG]/ # IDE workspace configuration
65
- │ ├── settings.[ext] # IDE settings
66
- │ ├── extensions.[ext] # Recommended extensions
67
- │ └── launch.[ext] # Debug configurations
68
- ├── [BACKEND-DIR]/ # Backend application
69
- │ ├── CONTEXT.md # Backend-specific AI context
70
- │ ├── src/ # Source code
71
- │ │ ├── config/ # Configuration management
72
- │ │ │ └── settings.[ext] # Application settings
73
- │ │ ├── core/ # Core business logic
74
- │ │ │ ├── CONTEXT.md # Core logic patterns
75
- │ │ │ ├── services/ # Business services
76
- │ │ │ │ ├── [service1].[ext] # Service implementations
77
- │ │ │ │ └── [service2].[ext]
78
- │ │ │ ├── models/ # Data models
79
- │ │ │ │ ├── [model1].[ext] # Model definitions
80
- │ │ │ │ └── [model2].[ext]
81
- │ │ │ └── utils/ # Utility functions
82
- │ │ │ ├── logging.[ext] # Structured logging
83
- │ │ │ ├── validation.[ext] # Input validation
84
- │ │ │ └── helpers.[ext] # Helper functions
85
- │ │ ├── api/ # API layer
86
- │ │ │ ├── CONTEXT.md # API patterns and conventions
87
- │ │ │ ├── routes/ # API route definitions
88
- │ │ │ │ ├── [resource1].[ext] # Resource-specific routes
89
- │ │ │ │ └── [resource2].[ext]
90
- │ │ │ ├── middleware/ # API middleware
91
- │ │ │ │ ├── auth.[ext] # Authentication middleware
92
- │ │ │ │ ├── logging.[ext] # Request logging
93
- │ │ │ │ └── validation.[ext] # Request validation
94
- │ │ │ └── schemas/ # Request/response schemas
95
- │ │ │ ├── [schema1].[ext] # Data schemas
96
- │ │ │ └── [schema2].[ext]
97
- │ │ └── integrations/ # External service integrations
98
- │ │ ├── CONTEXT.md # Integration patterns
99
- │ │ ├── [service1]/ # Service-specific integration
100
- │ │ │ ├── client.[ext] # API client
101
- │ │ │ ├── models.[ext] # Integration models
102
- │ │ │ └── handlers.[ext] # Response handlers
103
- │ │ └── [service2]/
104
- │ ├── tests/ # Test suite
105
- │ │ ├── unit/ # Unit tests
106
- │ │ ├── integration/ # Integration tests
107
- │ │ └── fixtures/ # Test fixtures and data
108
- │ ├── [PACKAGE-FILE] # Package configuration
109
- │ └── [ENV-FILE] # Environment configuration
110
- ├── [FRONTEND-DIR]/ # Frontend application (if applicable)
111
- │ ├── CONTEXT.md # Frontend-specific AI context
112
- │ ├── src/ # Source code
113
- │ │ ├── components/ # UI components
114
- │ │ │ ├── CONTEXT.md # Component patterns
115
- │ │ │ ├── common/ # Shared components
116
- │ │ │ └── [feature]/ # Feature-specific components
117
- │ │ ├── pages/ # Page components/routes
118
- │ │ │ ├── [page1].[ext] # Page implementations
119
- │ │ │ └── [page2].[ext]
120
- │ │ ├── stores/ # State management
121
- │ │ │ ├── CONTEXT.md # State management patterns
122
- │ │ │ ├── [store1].[ext] # Store implementations
123
- │ │ │ └── [store2].[ext]
124
- │ │ ├── api/ # API client layer
125
- │ │ │ ├── CONTEXT.md # Client patterns
126
- │ │ │ ├── client.[ext] # HTTP client setup
127
- │ │ │ └── endpoints/ # API endpoint definitions
128
- │ │ ├── utils/ # Utility functions
129
- │ │ │ ├── logging.[ext] # Client-side logging
130
- │ │ │ ├── validation.[ext] # Form validation
131
- │ │ │ └── helpers.[ext] # Helper functions
132
- │ │ └── assets/ # Static assets
133
- │ ├── tests/ # Frontend tests
134
- │ ├── [BUILD-CONFIG] # Build configuration
135
- │ └── [PACKAGE-FILE] # Package configuration
136
- ├── docs/ # Documentation
137
- │ ├── ai-context/ # AI-specific documentation
138
- │ │ ├── project-structure.md # This file
139
- │ │ ├── docs-overview.md # Documentation architecture
140
- │ │ ├── system-integration.md # Integration patterns
141
- │ │ ├── deployment-infrastructure.md # Infrastructure docs
142
- │ │ └── handoff.md # Task management
143
- │ ├── api/ # API documentation
144
- │ ├── deployment/ # Deployment guides
145
- │ └── development/ # Development guides
146
- ├── scripts/ # Automation scripts
147
- │ ├── setup.[ext] # Environment setup
148
- │ ├── deploy.[ext] # Deployment scripts
149
- │ └── maintenance/ # Maintenance scripts
150
- ├── [INFRASTRUCTURE-DIR]/ # Infrastructure as code (if applicable)
151
- │ ├── [PROVIDER]/ # Cloud provider configurations
152
- │ ├── docker/ # Container configurations
153
- │ └── monitoring/ # Monitoring and alerting
154
- └── [CONFIG-FILES] # Root-level configuration files
155
- ```
156
-
157
-
158
- ---
159
-
160
- *This template provides a comprehensive foundation for documenting project structure. Adapt it based on your specific technology stack, architecture decisions, and organizational requirements.*