@sk8metal/michi-cli 0.10.1 → 0.12.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 (139) hide show
  1. package/README.md +71 -848
  2. package/dist/scripts/constants/environments.d.ts +1 -1
  3. package/dist/scripts/constants/environments.d.ts.map +1 -1
  4. package/dist/scripts/constants/environments.js +0 -20
  5. package/dist/scripts/constants/environments.js.map +1 -1
  6. package/dist/scripts/phase-runner.js +1 -1
  7. package/dist/scripts/phase-runner.js.map +1 -1
  8. package/dist/scripts/utils/multi-repo-validator.d.ts +18 -0
  9. package/dist/scripts/utils/multi-repo-validator.d.ts.map +1 -1
  10. package/dist/scripts/utils/multi-repo-validator.js +42 -0
  11. package/dist/scripts/utils/multi-repo-validator.js.map +1 -1
  12. package/dist/scripts/utils/tasks-format-validator.js +3 -3
  13. package/dist/scripts/utils/tasks-format-validator.js.map +1 -1
  14. package/dist/scripts/utils/template-finder.d.ts +2 -2
  15. package/dist/scripts/utils/template-finder.d.ts.map +1 -1
  16. package/dist/scripts/utils/template-finder.js +3 -8
  17. package/dist/scripts/utils/template-finder.js.map +1 -1
  18. package/dist/src/cli.d.ts.map +1 -1
  19. package/dist/src/cli.js +0 -8
  20. package/dist/src/cli.js.map +1 -1
  21. package/dist/src/commands/init.d.ts +0 -4
  22. package/dist/src/commands/init.d.ts.map +1 -1
  23. package/dist/src/commands/init.js +6 -30
  24. package/dist/src/commands/init.js.map +1 -1
  25. package/dist/src/commands/setup-existing.d.ts +2 -6
  26. package/dist/src/commands/setup-existing.d.ts.map +1 -1
  27. package/dist/src/commands/setup-existing.js +8 -142
  28. package/dist/src/commands/setup-existing.js.map +1 -1
  29. package/docs/README.md +20 -83
  30. package/docs/getting-started/configuration.md +350 -0
  31. package/docs/getting-started/installation.md +59 -0
  32. package/docs/getting-started/quick-start.md +76 -0
  33. package/docs/guides/atlassian-integration.md +116 -0
  34. package/docs/guides/claude-code.md +155 -0
  35. package/docs/guides/multi-repo.md +117 -0
  36. package/docs/guides/workflow.md +382 -0
  37. package/docs/reference/ai-commands.md +92 -0
  38. package/docs/reference/cli.md +752 -0
  39. package/docs/reference/environment-variables.md +192 -0
  40. package/docs/troubleshooting.md +498 -0
  41. package/package.json +1 -3
  42. package/scripts/__tests__/create-project.test.ts +12 -12
  43. package/scripts/__tests__/setup-existing-project.test.ts +22 -22
  44. package/scripts/constants/__tests__/environments.test.ts +7 -50
  45. package/scripts/constants/environments.ts +1 -27
  46. package/scripts/phase-runner.ts +1 -1
  47. package/scripts/template/__tests__/renderer.test.ts +21 -21
  48. package/scripts/utils/__tests__/multi-repo-validator.test.ts +159 -1
  49. package/scripts/utils/multi-repo-validator.ts +50 -0
  50. package/scripts/utils/tasks-format-validator.ts +3 -3
  51. package/scripts/utils/template-finder.ts +5 -11
  52. package/templates/claude/agents/e2e-first-planner/AGENT.md +1 -1
  53. package/templates/claude/agents/pr-resolver/AGENT.md +15 -3
  54. package/templates/claude/commands/michi/e2e-plan.md +1 -1
  55. package/templates/claude/commands/michi/spec-design.md +2 -2
  56. package/templates/claude/commands/michi/spec-tasks.md +156 -0
  57. package/templates/claude/commands/michi/test-planning.md +1 -1
  58. package/templates/claude/commands/michi/validate-design.md +3 -3
  59. package/templates/claude/commands/michi-multi-repo/impl-all.md +30 -1
  60. package/templates/claude/commands/michi-multi-repo/propagate-specs.md +14 -1
  61. package/templates/claude/commands/michi-multi-repo/spec-review.md +16 -2
  62. package/templates/claude-agent/agents/repo-spec-executor.md +1 -1
  63. package/templates/claude-agent/commands/michi/spec-tasks.md +117 -0
  64. package/templates/claude-agent/rules/code-size-monitor.md +26 -0
  65. package/templates/claude-agent/rules/code-size-rules.md +32 -0
  66. package/templates/michi/cc-sdd-overrides/settings/rules/design-review-michi.md +1 -1
  67. package/docs/context.md +0 -59
  68. package/docs/michi-development/contributing/development.md +0 -341
  69. package/docs/michi-development/contributing/release.md +0 -365
  70. package/docs/michi-development/design/config-unification.md +0 -733
  71. package/docs/michi-development/design/design-config-current-state.md +0 -330
  72. package/docs/michi-development/design/design-config-implementation.md +0 -628
  73. package/docs/michi-development/design/design-config-migration.md +0 -952
  74. package/docs/michi-development/design/design-config-security.md +0 -771
  75. package/docs/michi-development/design/design-config-solution.md +0 -583
  76. package/docs/michi-development/design/design-config-testing.md +0 -892
  77. package/docs/michi-development/testing/manual-verification-flow.md +0 -871
  78. package/docs/michi-development/testing/manual-verification-other-tools.md +0 -1279
  79. package/docs/michi-development/testing/manual-verification-troubleshooting.md +0 -122
  80. package/docs/michi-development/testing/pre-publish-checklist.md +0 -560
  81. package/docs/michi-development/testing-strategy.md +0 -87
  82. package/docs/plan.md +0 -275
  83. package/docs/user-guide/getting-started/github-token-setup.md +0 -510
  84. package/docs/user-guide/getting-started/new-repository-setup.md +0 -704
  85. package/docs/user-guide/getting-started/quick-start.md +0 -212
  86. package/docs/user-guide/getting-started/setup.md +0 -819
  87. package/docs/user-guide/guides/agent-skills-integration.md +0 -222
  88. package/docs/user-guide/guides/customization.md +0 -537
  89. package/docs/user-guide/guides/internationalization.md +0 -540
  90. package/docs/user-guide/guides/migration-guide.md +0 -138
  91. package/docs/user-guide/guides/multi-project.md +0 -368
  92. package/docs/user-guide/guides/multi-repo-guide.md +0 -1590
  93. package/docs/user-guide/guides/phase-automation.md +0 -419
  94. package/docs/user-guide/guides/workflow.md +0 -574
  95. package/docs/user-guide/hands-on/README.md +0 -142
  96. package/docs/user-guide/hands-on/claude-agent-setup.md +0 -597
  97. package/docs/user-guide/hands-on/claude-setup.md +0 -452
  98. package/docs/user-guide/hands-on/cursor-setup.md +0 -353
  99. package/docs/user-guide/hands-on/troubleshooting.md +0 -964
  100. package/docs/user-guide/hands-on/verification-checklist.md +0 -439
  101. package/docs/user-guide/hands-on/workflow-walkthrough.md +0 -1078
  102. package/docs/user-guide/reference/config.md +0 -589
  103. package/docs/user-guide/reference/multi-repo-api.md +0 -771
  104. package/docs/user-guide/reference/quick-reference.md +0 -297
  105. package/docs/user-guide/reference/security-test-payloads.md +0 -50
  106. package/docs/user-guide/reference/tasks-template.md +0 -550
  107. package/docs/user-guide/release/ci-setup-java.md +0 -114
  108. package/docs/user-guide/release/ci-setup-nodejs.md +0 -94
  109. package/docs/user-guide/release/ci-setup-php.md +0 -102
  110. package/docs/user-guide/release/ci-setup-troubleshooting.md +0 -94
  111. package/docs/user-guide/release/ci-setup.md +0 -188
  112. package/docs/user-guide/release/release-flow.md +0 -476
  113. package/docs/user-guide/templates/test-specs/README.md +0 -173
  114. package/docs/user-guide/templates/test-specs/e2e-test-spec-template.md +0 -553
  115. package/docs/user-guide/templates/test-specs/integration-test-spec-template.md +0 -435
  116. package/docs/user-guide/templates/test-specs/performance-test-spec-template.md +0 -454
  117. package/docs/user-guide/templates/test-specs/security-test-spec-template.md +0 -625
  118. package/docs/user-guide/templates/test-specs/unit-test-spec-template.md +0 -328
  119. package/docs/user-guide/testing/integration-tests.md +0 -312
  120. package/docs/user-guide/testing/tdd-cycle.md +0 -349
  121. package/docs/user-guide/testing/test-execution-flow.md +0 -396
  122. package/docs/user-guide/testing/test-failure-handling.md +0 -521
  123. package/docs/user-guide/testing/test-planning-flow.md +0 -185
  124. package/docs/user-guide/testing-strategy.md +0 -185
  125. package/docs/verification-guide.md +0 -518
  126. package/templates/cline/rules/atlassian-integration.md +0 -36
  127. package/templates/cline/rules/michi-core.md +0 -56
  128. package/templates/codex/AGENTS.override.md +0 -277
  129. package/templates/codex/prompts/confluence-sync.md +0 -177
  130. package/templates/codex/rules/README.md +0 -210
  131. package/templates/cursor/commands/kiro/kiro-spec-impl.md +0 -244
  132. package/templates/cursor/commands/kiro/kiro-spec-tasks.md +0 -354
  133. package/templates/cursor/commands/michi/confluence-sync.md +0 -76
  134. package/templates/cursor/commands/michi/project-switch.md +0 -69
  135. package/templates/cursor/rules/atlassian-mcp.mdc +0 -188
  136. package/templates/cursor/rules/github-ssot.mdc +0 -151
  137. package/templates/cursor/rules/multi-project.mdc +0 -81
  138. package/templates/gemini/commands/README.md +0 -41
  139. package/templates/gemini/rules/GEMINI.md +0 -80
@@ -1,36 +0,0 @@
1
- # Atlassian Integration Rules
2
-
3
- ## Confluence Integration
4
-
5
- ### Page Creation Format
6
- - Title: `[{{PROJECT_ID}}] {document_type}`
7
- - Labels: Use {{KIRO_DIR}}/project.json `confluenceLabels`
8
- - Space: Reference environment variables (CONFLUENCE_PRD_SPACE, etc.)
9
-
10
- ### Content Sync
11
- - Source: GitHub {{KIRO_DIR}}/specs/
12
- - Destination: Confluence pages
13
- - Sync tool: `npm run confluence:sync`
14
-
15
- ## JIRA Integration
16
-
17
- ### Issue Creation Format
18
- - Summary: `[{{JIRA_KEY}}] {title}`
19
- - Project Key: Use {{KIRO_DIR}}/project.json `jiraProjectKey`
20
- - Labels: Derived from Confluence labels
21
-
22
- ### Workflow
23
- 1. Generate specs in GitHub
24
- 2. Create JIRA epics/stories
25
- 3. Link Confluence pages to JIRA issues
26
-
27
- ## Environment Variables
28
-
29
- Required variables (from .env):
30
- - `ATLASSIAN_URL`
31
- - `ATLASSIAN_EMAIL`
32
- - `ATLASSIAN_API_TOKEN`
33
- - `JIRA_PROJECT_KEYS`
34
- - `CONFLUENCE_PRD_SPACE`
35
- - `CONFLUENCE_QA_SPACE`
36
- - `CONFLUENCE_RELEASE_SPACE`
@@ -1,56 +0,0 @@
1
- # Michi Core Principles
2
-
3
- ## Development Guidelines
4
- {{DEV_GUIDELINES}}
5
-
6
- ## Language
7
- All generated documents should be in: **{{LANG_CODE}}**
8
-
9
- Reference the language field in {{KIRO_DIR}}/project.json.
10
-
11
- ## Single Source of Truth (SSoT)
12
-
13
- ### GitHub as SSoT
14
- - **All specifications are managed in GitHub** ({{KIRO_DIR}}/specs/)
15
- - Confluence is **reference and approval only** (editing is GitHub only)
16
- - Avoid duplicate management
17
-
18
- ### Data Flow
19
- ```
20
- GitHub ({{KIRO_DIR}}/specs/) ← Source of truth (editable)
21
- ↓ sync
22
- Confluence ← Display and approval (read-only)
23
- ```
24
-
25
- ## Multi-Project Management
26
-
27
- ### Project Identification
28
- - All operations reference {{KIRO_DIR}}/project.json
29
- - Dynamically use project ID, JIRA key, Confluence labels
30
- - Project ID: {{PROJECT_ID}}
31
-
32
- ### Naming Conventions
33
-
34
- #### Confluence Pages
35
- - Format: `[{projectName}] {document_type}`
36
- - Example: `[{{PROJECT_ID}}] Requirements`
37
-
38
- #### JIRA Epic/Story
39
- - Format: `[{JIRA_KEY}] {title}`
40
- - Use project metadata from {{KIRO_DIR}}/project.json
41
-
42
- ## Project Structure
43
-
44
- - Project metadata: {{KIRO_DIR}}/project.json
45
- - Specifications: {{KIRO_DIR}}/specs/
46
- - Templates: {{KIRO_DIR}}/settings/templates/
47
- - Steering: {{KIRO_DIR}}/steering/
48
- - Rules: {{AGENT_DIR}}/rules/
49
-
50
- ## Best Practices
51
-
52
- 1. **Always reference project.json** for project-specific metadata
53
- 2. **Use SSoT principle** - Edit in GitHub, reference in Confluence
54
- 3. **Follow naming conventions** for consistency
55
- 4. **Generate specs incrementally** - Requirements → Design → Tasks
56
- 5. **Commit frequently** to GitHub
@@ -1,277 +0,0 @@
1
- # AGENTS.override.md - Michi Project Extensions
2
-
3
- このファイルはcc-sddのAGENTS.mdを拡張し、Michi固有のワークフローとルールを追加します。
4
-
5
- ## Michi Overview
6
-
7
- **Michi**は、AI駆動開発を支援するプロジェクト管理・ドキュメント管理フレームワークです。Claude Code、Cursor、Codex CLI、Claude Agent SDKと統合し、効率的な開発フローを実現します。
8
-
9
- - **Repository**: https://github.com/sk8metalme/michi
10
- - **Documentation**: `docs/user-guide/`
11
- - **License**: MIT
12
-
13
- ---
14
-
15
- ## Michi-Specific Workflows
16
-
17
- ### 1. Confluence Integration
18
-
19
- #### Confluence同期コマンド
20
- ```bash
21
- /prompts:confluence-sync FEATURE=<機能名>
22
- ```
23
-
24
- #### 必要な環境変数
25
- ```bash
26
- ATLASSIAN_URL=https://your-domain.atlassian.net
27
- ATLASSIAN_EMAIL=your-email@example.com
28
- ATLASSIAN_API_TOKEN=your-api-token
29
- ```
30
-
31
- #### プロジェクト設定
32
- `.kiro/project.json`に以下を設定:
33
- ```json
34
- {
35
- "confluenceSpaceKey": "YOUR_SPACE",
36
- "confluenceLabels": ["ai-development", "michi"]
37
- }
38
- ```
39
-
40
- #### 同期対象
41
- - 要件定義書(requirements.md)→ Confluenceページ
42
- - 設計書(design.md)→ Confluenceページ
43
- - タスク一覧(tasks.md)→ Confluenceページ(オプション)
44
-
45
- ---
46
-
47
- ### 2. JIRA Integration
48
-
49
- #### プロジェクトキー設定
50
- `.kiro/project.json`の`jiraProjectKey`を使用してJIRAチケットを管理:
51
- ```json
52
- {
53
- "jiraProjectKey": "MYPROJ"
54
- }
55
- ```
56
-
57
- #### リリース管理
58
- - JIRAでリリースバージョンを作成
59
- - Confluenceでリリース手順書を管理
60
- - GitHub Releasesと連携
61
-
62
- ---
63
-
64
- ### 3. Multi-Language Support
65
-
66
- Michiは以下の言語とビルドツールをサポート:
67
-
68
- | 言語 | ビルドツール | テストコマンド |
69
- |------|------------|---------------|
70
- | Node.js/TypeScript | npm | `npm test` |
71
- | Java | **Gradle のみ** | `./gradlew test` |
72
- | PHP | Composer | `composer test` |
73
-
74
- **重要:** Javaプロジェクトでは**Gradleのみ**を使用してください。Mavenは使用しません。
75
-
76
- ---
77
-
78
- ### 4. Test Strategy - Master Test Approach
79
-
80
- Michiは**マスタテスト方式**を採用しています:
81
-
82
- #### 基本原則
83
- - テストは常に最新の仕様を反映(phase-0、phase-1のような履歴管理はしない)
84
- - 仕様変更時は既存のテストファイルを更新
85
- - テスト実行時間を一定に保つ
86
-
87
- #### Phase構成
88
- - **Phase A**: PR時に自動実行
89
- - Unit tests
90
- - Lint
91
- - Build
92
- - **Phase B**: リリース前に手動実行
93
- - Integration tests
94
- - E2E tests
95
- - Performance tests
96
- - Security tests
97
-
98
- #### テストカバレッジ
99
- - 目標: **95%以上**
100
- - テストは仕様として扱う
101
- - 実装に合わせてテストを変更しない(仕様通りでない場合のみ修正)
102
-
103
- ---
104
-
105
- ### 5. CI/CD Integration
106
-
107
- #### サポート対象
108
- - **GitHub Actions**
109
- - **Screwdriver**
110
-
111
- #### 推奨ワークフロー
112
- ```yaml
113
- # .github/workflows/ci.yml
114
- name: CI
115
- on: [pull_request]
116
- jobs:
117
- test:
118
- runs-on: ubuntu-latest
119
- steps:
120
- - uses: actions/checkout@v3
121
- - name: Run Phase A Tests
122
- run: |
123
- npm install
124
- npm run test:unit
125
- npm run lint
126
- npm run build
127
- ```
128
-
129
- ---
130
-
131
- ### 6. Release Flow
132
-
133
- #### セマンティックバージョニング
134
- ```
135
- v<major>.<minor>.<patch>
136
- 例: v1.2.3
137
- ```
138
-
139
- #### リリース手順
140
- 1. **Confluenceでリリース手順書作成**
141
- - テンプレート: `.kiro/templates/release-procedure.md`
142
- 2. **JIRAでリリースチケット起票**
143
- - チケットタイプ: Release
144
- - バージョン: 自動生成
145
- 3. **GitHub Releaseの作成**
146
- - リリースノート自動生成
147
- - タグ付け
148
-
149
- ---
150
-
151
- ## Coding Standards
152
-
153
- ### TypeScript/Node.js
154
- - **Style Guide**: Airbnb JavaScript Style Guide準拠
155
- - **Linter**: ESLint
156
- - **Formatter**: Prettier
157
- - **Type Checking**: `tsc --noEmit`
158
-
159
- ### Java (Gradle)
160
- - **Style Guide**: Google Java Style Guide
161
- - **Build Tool**: Gradle 8.x
162
- - **Test Framework**: JUnit 5
163
- - **Coverage**: JaCoCo
164
-
165
- ### PHP
166
- - **Style Guide**: PSR-12
167
- - **Build Tool**: Composer
168
- - **Test Framework**: PHPUnit
169
- - **Static Analysis**: PHPStan
170
-
171
- ---
172
-
173
- ## File Structure Standards
174
-
175
- ### .kiro/ Directory
176
- ```
177
- .kiro/
178
- ├── project.json # プロジェクトメタデータ
179
- ├── specs/ # 機能仕様(cc-sdd管理)
180
- │ └── {feature}/
181
- │ ├── requirements.md
182
- │ ├── design.md
183
- │ ├── tasks.md
184
- │ └── spec.json
185
- ├── steering/ # AI指導ルール(cc-sdd管理)
186
- │ ├── structure.md
187
- │ ├── tech.md
188
- │ └── product.md
189
- └── settings/ # 共通ルール(cc-sdd管理)
190
- ```
191
-
192
- ### Michi Extensions
193
- ```
194
- .kiro/
195
- ├── project.json # ⭐ Michi固有
196
- └── templates/ # ⭐ Michi固有
197
- ├── confluence-page.md
198
- ├── jira-ticket.md
199
- └── release-procedure.md
200
- ```
201
-
202
- ---
203
-
204
- ## Security Policy
205
-
206
- ### 環境変数管理
207
- - **絶対禁止**: APIキー、トークンのハードコード
208
- - **推奨**: `.env`ファイル + `.gitignore`
209
- - **CI/CD**: GitHub Secrets / Screwdriver Secrets
210
-
211
- ### 依存関係管理
212
- - 定期的な脆弱性スキャン(`npm audit`, `snyk`)
213
- - 依存ライブラリの最小化
214
- - 信頼できるソースからのみダウンロード
215
-
216
- ---
217
-
218
- ## Workflow Integration
219
-
220
- ### cc-sdd + Michi 連携フロー
221
-
222
- 1. **プロジェクト初期化**
223
- ```bash
224
- # cc-sddインストール
225
- npx cc-sdd@latest --codex --lang ja
226
-
227
- # Michi拡張インストール
228
- npx michi setup --codex
229
- ```
230
-
231
- 2. **仕様作成(cc-sdd)**
232
- ```bash
233
- /kiro:spec-init FEATURE=user-auth
234
- /kiro:spec-requirements FEATURE=user-auth
235
- /kiro:spec-design FEATURE=user-auth
236
- ```
237
-
238
- 3. **Confluence同期(Michi)**
239
- ```bash
240
- /prompts:confluence-sync FEATURE=user-auth
241
- ```
242
-
243
- 4. **実装とテスト(cc-sdd + TDD)**
244
- ```bash
245
- /kiro:spec-tasks FEATURE=user-auth
246
- /kiro:spec-impl FEATURE=user-auth
247
- ```
248
-
249
- 5. **検証(cc-sdd)**
250
- ```bash
251
- /kiro:validate-impl FEATURE=user-auth
252
- ```
253
-
254
- ---
255
-
256
- ## Communication Guidelines
257
-
258
- ### 日本語優先
259
- - コミュニケーションは日本語を基本とする
260
- - 技術用語は適切に英語/日本語を使い分ける
261
-
262
- ### 質問と確認
263
- - 不明な点は必ず質問し精度を高めることを最優先する
264
- - AskUserQuestionツールを積極的に活用
265
-
266
- ---
267
-
268
- ## Reference Links
269
-
270
- - [Michi Documentation](https://github.com/sk8metalme/michi/tree/main/docs)
271
- - [cc-sdd Documentation](https://github.com/gotalab/cc-sdd)
272
- - [Confluence API](https://developer.atlassian.com/cloud/confluence/rest/v2/)
273
- - [JIRA API](https://developer.atlassian.com/cloud/jira/platform/rest/v3/)
274
-
275
- ---
276
-
277
- **Note**: このファイルはCodex CLIの`AGENTS.md`を上書き(override)するものではなく、cc-sddの基本ルールに**追加**される形で適用されます。
@@ -1,177 +0,0 @@
1
- ---
2
- description: Confluenceへのドキュメント同期 - Michi仕様書をConfluenceに連携
3
- argument-hint: [FEATURE=<機能名>]
4
- ---
5
- # Michi Confluence Sync
6
-
7
- 機能「$1」の仕様ドキュメントをConfluenceに同期します。
8
-
9
- ## 前提条件
10
-
11
- ### 環境変数の設定
12
- 以下の環境変数が必要です:
13
- ```bash
14
- ATLASSIAN_URL=https://your-domain.atlassian.net
15
- ATLASSIAN_EMAIL=your-email@example.com
16
- ATLASSIAN_API_TOKEN=your-api-token
17
- ```
18
-
19
- ### プロジェクトメタデータ
20
- `.kiro/project.json`に以下が設定されていること:
21
- - `confluenceSpaceKey`: Confluenceスペースキー
22
- - `confluenceLabels`: 自動付与するラベル
23
-
24
- ## 同期対象ファイル
25
-
26
- 以下のファイルをConfluenceページに変換して同期します:
27
-
28
- 1. **要件定義書**
29
- - ソース: `.kiro/specs/$1/requirements.md`
30
- - タイトル: `[$1] 要件定義`
31
-
32
- 2. **設計ドキュメント**
33
- - ソース: `.kiro/specs/$1/design.md`
34
- - タイトル: `[$1] 設計書`
35
-
36
- 3. **タスク一覧**(オプション)
37
- - ソース: `.kiro/specs/$1/tasks.md`
38
- - タイトル: `[$1] タスク管理`
39
-
40
- ## 実行手順
41
-
42
- ### 1. 環境変数の確認
43
- ```typescript
44
- // 必要な環境変数をチェック
45
- const requiredEnvVars = [
46
- 'ATLASSIAN_URL',
47
- 'ATLASSIAN_EMAIL',
48
- 'ATLASSIAN_API_TOKEN'
49
- ];
50
-
51
- for (const envVar of requiredEnvVars) {
52
- if (!process.env[envVar]) {
53
- console.error(`❌ ${envVar} が設定されていません`);
54
- process.exit(1);
55
- }
56
- }
57
- ```
58
-
59
- ### 2. プロジェクトメタデータの読み込み
60
- ```typescript
61
- import { readFileSync } from 'fs';
62
-
63
- const projectMeta = JSON.parse(
64
- readFileSync('.kiro/project.json', 'utf-8')
65
- );
66
-
67
- const spaceKey = projectMeta.confluenceSpaceKey;
68
- const labels = projectMeta.confluenceLabels || [];
69
- ```
70
-
71
- ### 3. Confluence APIクライアントの初期化
72
- ```typescript
73
- import { ConfluenceClient } from '../path/to/confluence-client';
74
-
75
- const confluence = new ConfluenceClient({
76
- url: process.env.ATLASSIAN_URL!,
77
- email: process.env.ATLASSIAN_EMAIL!,
78
- apiToken: process.env.ATLASSIAN_API_TOKEN!
79
- });
80
- ```
81
-
82
- ### 4. Markdownファイルの読み込みと変換
83
- ```typescript
84
- const requirements = readFileSync(
85
- `.kiro/specs/$1/requirements.md`,
86
- 'utf-8'
87
- );
88
-
89
- // Markdown → Confluence Storage Format変換
90
- const confluenceHtml = convertMarkdownToConfluence(requirements);
91
- ```
92
-
93
- ### 5. ページの作成または更新
94
- ```typescript
95
- // 既存ページの検索
96
- const existingPage = await confluence.findPageByTitle(
97
- spaceKey,
98
- `[$1] 要件定義`
99
- );
100
-
101
- if (existingPage) {
102
- // 更新
103
- await confluence.updatePage(existingPage.id, {
104
- title: `[$1] 要件定義`,
105
- body: confluenceHtml,
106
- version: existingPage.version + 1
107
- });
108
- console.log('✅ ページを更新しました');
109
- } else {
110
- // 新規作成
111
- const newPage = await confluence.createPage({
112
- spaceKey,
113
- title: `[$1] 要件定義`,
114
- body: confluenceHtml,
115
- labels
116
- });
117
- console.log('✅ ページを作成しました:', newPage.url);
118
- }
119
- ```
120
-
121
- ### 6. 同期結果の報告
122
- ```typescript
123
- console.log('\n📊 Confluence同期結果:');
124
- console.log(` 機能: $1`);
125
- console.log(` スペース: ${spaceKey}`);
126
- console.log(` 同期ファイル数: 2`);
127
- console.log(` ラベル: ${labels.join(', ')}`);
128
- ```
129
-
130
- ## エラーハンドリング
131
-
132
- ### 認証エラー
133
- ```
134
- ❌ Confluence API認証失敗
135
- - ATLASSIAN_URLが正しいか確認
136
- - API Tokenが有効か確認
137
- - メールアドレスが正しいか確認
138
- ```
139
-
140
- ### スペースが見つからない
141
- ```
142
- ❌ Confluenceスペースが見つかりません
143
- - .kiro/project.jsonのconfluenceSpaceKeyを確認
144
- - スペースへのアクセス権限を確認
145
- ```
146
-
147
- ### ページ作成失敗
148
- ```
149
- ❌ ページ作成に失敗しました
150
- - スペースへの書き込み権限を確認
151
- - タイトルの重複がないか確認
152
- ```
153
-
154
- ## Markdown変換の注意点
155
-
156
- Confluenceは独自のStorage Format(XHTML)を使用するため、以下に注意:
157
-
158
- - **コードブロック**: \`\`\`言語 → `<ac:structured-macro ac:name="code">`
159
- - **表**: GitHub Markdown → Confluence Table
160
- - **画像**: 相対パス → Confluence添付ファイル
161
- - **リンク**: 他の.mdファイル → Confluenceページリンク
162
-
163
- ## 参考リソース
164
-
165
- - [Confluence REST API ドキュメント](https://developer.atlassian.com/cloud/confluence/rest/v2/intro/)
166
- - [Storage Format仕様](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html)
167
- - Michiの`scripts/utils/confluence-client.ts`実装を参照
168
-
169
- ## 使用例
170
-
171
- ```bash
172
- # Codex CLIから実行
173
- /prompts:confluence-sync FEATURE=user-authentication
174
-
175
- # 複数ファイルを一括同期(カスタムスクリプト)
176
- node scripts/sync-all-specs-to-confluence.js
177
- ```