@rpamis/comet 0.2.0 → 0.2.2

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.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 rpamis
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 rpamis
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,270 +1,270 @@
1
- # @rpamis/comet
2
-
3
- ```
4
- ██████╗ ██████╗ ███╗ ███╗███████╗████████╗
5
- ██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
6
- ██║ ██║ ██║██╔████╔██║█████╗ ██║
7
- ██║ ██║ ██║██║╚██╔╝██║██╔══╝ ██║
8
- ╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗ ██║
9
- ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝ ╚═╝
10
- ```
11
-
12
- > 中文版:[README-zh.md](README-zh.md)
13
-
14
- **OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
15
-
16
- OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). Superpowers handles **HOW** (technical design, planning, execution, wrap-up). Comet chains both into a five-phase automated pipeline.
17
-
18
- ## Install
19
-
20
- ```bash
21
- npm install -g @rpamis/comet
22
- ```
23
-
24
- ## Quick Start
25
-
26
- ```bash
27
- cd your-project
28
- comet init
29
- ```
30
-
31
- `comet init` will:
32
-
33
- 1. Prompt you to select AI platforms (auto-detects existing configs)
34
- 2. Choose install scope: project-level (current directory) or global (home directory)
35
- 3. Select language for Comet skills: English or 中文
36
- 4. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
37
- 5. Install [Superpowers](https://github.com/obra/superpowers) skills
38
- 6. Deploy Comet skills (in your chosen language) to selected platforms
39
- 7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
40
-
41
- ## Commands
42
-
43
- | Command | Description |
44
- |---------|-------------|
45
- | `comet init [path]` | Initialize Comet workflow |
46
- | `comet status [path]` | Show active changes and workflow status |
47
- | `comet doctor [path]` | Diagnose Comet installation health |
48
- | `comet update [path]` | Update comet skills to latest version |
49
- | `comet --help` | Show help |
50
- | `comet --version` | Show version |
51
-
52
- ### init Options
53
-
54
- | Option | Description |
55
- |--------|-------------|
56
- | `--yes` | Non-interactive mode, auto-select detected platforms |
57
- | `--skip-existing` | Skip already installed components |
58
- | `--overwrite` | Overwrite already installed components |
59
- | `--json` | Output structured JSON |
60
-
61
- ### status / doctor / update Options
62
-
63
- | Option | Applies to | Description |
64
- |--------|-----------|-------------|
65
- | `--json` | `status`, `doctor` | Output structured JSON |
66
- | `--language <lang>` | `update` | Language for skills (`en`, `zh`) |
67
- | `--scope <scope>` | `update` | Install scope (`global`, `project`)|
68
-
69
- ## Supported Platforms
70
-
71
- `comet init` supports 28 AI coding platforms:
72
-
73
- | Platform | Skills Dir | Platform | Skills Dir |
74
- |----------|-----------|----------|-----------|
75
- | Claude Code | `.claude/` | Cursor | `.cursor/` |
76
- | Codex | `.codex/` | OpenCode | `.opencode/` |
77
- | Windsurf | `.windsurf/` | Cline | `.cline/` |
78
- | RooCode | `.roo/` | Continue | `.continue/` |
79
- | GitHub Copilot | `.github/` | Gemini CLI | `.gemini/` |
80
- | Amazon Q Developer | `.amazonq/` | Qwen Code | `.qwen/` |
81
- | Kilo Code | `.kilocode/` | Auggie | `.augment/` |
82
- | Kiro | `.kiro/` | Lingma | `.lingma/` |
83
- | Junie | `.junie/` | CodeBuddy | `.codebuddy/` |
84
- | CoStrict | `.cospec/` | Crush | `.crush/` |
85
- | Factory Droid | `.factory/` | iFlow | `.iflow/` |
86
- | Pi | `.pi/` | Qoder | `.qoder/` |
87
- | Antigravity | `.agent/` | Bob Shell | `.bob/` |
88
- | ForgeCode | `.forge/` | Trae | `.trae/` |
89
-
90
- ## Skills
91
-
92
- After `comet init`, three groups of skills are installed to the selected platform's `skills/` directory:
93
-
94
- ### Comet Skills
95
-
96
- | Skill | Description |
97
- |-------|-------------|
98
- | `/comet` | Main entry — auto-detects phase and dispatches to sub-commands |
99
- | `/comet-open` | Phase 1: Open a change (proposal, design, task breakdown) |
100
- | `/comet-design` | Phase 2: Deep design (brainstorming, Design Doc) |
101
- | `/comet-build` | Phase 3: Plan and build (implementation plan, code commits) |
102
- | `/comet-verify` | Phase 4: Verify and finish (testing, verification report) |
103
- | `/comet-archive` | Phase 5: Archive (delta spec sync, status annotation) |
104
- | `/comet-hotfix` | Preset: Quick bug fix (skips brainstorming) |
105
- | `/comet-tweak` | Preset: Small change (skips brainstorming and full plan) |
106
-
107
- ### Guard & Automation Scripts
108
-
109
- | Script | Purpose |
110
- |--------|---------|
111
- | `comet-guard.sh` | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml` |
112
- | `comet-archive.sh` | One-command archive — validates state, syncs specs, moves to archive, updates status |
113
- | `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values |
114
- | `comet-state.sh` | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface |
115
-
116
- ### OpenSpec Skills
117
-
118
- Spec lifecycle management: propose, explore, sync, verify, archive, and more.
119
-
120
- ### Superpowers Skills
121
-
122
- Development methodology: brainstorming, TDD, subagent-driven development, code review, plan writing, and more.
123
-
124
- ## Workflow
125
-
126
- ```
127
- /comet
128
- ↓ auto-detect
129
- /comet-open --> /comet-design --> /comet-build --> /comet-verify --> /comet-archive
130
- (OpenSpec) (Superpowers) (Superpowers) (Both) (OpenSpec)
131
-
132
- /comet-hotfix (preset path, skips brainstorming)
133
- open --> build --> verify --> archive
134
-
135
- /comet-tweak (preset path, skips brainstorming and full plan)
136
- open --> lightweight build --> light verify --> archive
137
- ```
138
-
139
- ### Five Phases
140
-
141
- | Phase | Command | Owner | Artifacts |
142
- |-------|---------|-------|-----------|
143
- | 1. Open | `/comet-open` | OpenSpec | proposal.md, design.md, tasks.md |
144
- | 2. Deep Design | `/comet-design` | Superpowers | Design Doc, delta spec |
145
- | 3. Plan & Build | `/comet-build` | Superpowers | Implementation plan, code commits |
146
- | 4. Verify & Finish | `/comet-verify` | Both | Verification report, branch handling |
147
- | 5. Archive | `/comet-archive` | OpenSpec | delta→main spec sync, archive |
148
-
149
- ### Core Principles
150
-
151
- - **Brainstorming is non-skippable** — every change must go through deep design (except hotfix/tweak)
152
- - **Delta specs are living documents** — freely editable during Phase 3, synced at archive
153
- - **Keep tasks.md in sync** — check off each task as completed
154
- - **Commit frequently** — one commit per task, message reflects design intent
155
- - **Verify before archive** — `/comet-verify` must pass before `/comet-archive`
156
-
157
- ### State Management
158
-
159
- Comet uses a decoupled state architecture with separate YAML files:
160
-
161
- | File | Owner | Purpose |
162
- |------|-------|---------|
163
- | `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata |
164
- | `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
165
-
166
- **Key Fields in `.comet.yaml`:**
167
- - `workflow`: `full`, `hotfix`, or `tweak`
168
- - `phase`: `design`, `build`, `verify`, `archive`
169
- - `design_doc`: Path to Superpowers Design Doc
170
- - `plan`: Path to implementation plan
171
- - `build_mode`: `subagent-driven-development`, `executing-plans`, or `direct`
172
- - `isolation`: `branch` or `worktree`, workspace isolation method
173
- - `verify_mode`: `light` or `full`
174
- - `verify_result`: `pending`, `pass`, or `fail`
175
- - `archived`: Boolean indicating if change is archived
176
-
177
- ### Reliability Features
178
-
179
- Comet ensures agent execution reliability through automated state transitions:
180
-
181
- 1. **Entry Verification** — Each phase validates preconditions before execution
182
- - Checks file existence, state consistency, and phase transitions
183
- - Outputs `[HARD STOP]` with actionable suggestions if validation fails
184
-
185
- 2. **Automated State Transitions** — `comet-guard.sh --apply` updates `.comet.yaml` automatically
186
- - All phase transitions (design → build → verify → archive) use `guard --apply`
187
- - No manual state editing required — eliminates write-verification errors
188
- - `comet-state.sh` is the agents' exclusive interface for state operations
189
- - Guard and archive scripts use `comet-state.sh` internally for state management
190
-
191
- 3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
192
- - Validates required fields (10 fields)
193
- - Validates enum values (7 enum types)
194
- - Validates referenced file paths exist
195
- - Detects unknown/typos fields
196
-
197
- 4. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
198
- - Validates entry state, syncs delta specs to main specs
199
- - Annotates design doc and plan frontmatter
200
- - Moves change to archive directory and updates `archived: true`
201
- - Supports `--dry-run` for preview
202
-
203
- **Security**: Path traversal protection on all change name inputs
204
-
205
- ## Project Structure
206
-
207
- ```
208
- your-project/
209
- ├── .claude/skills/ # Platform skills dir (Comet + OpenSpec + Superpowers)
210
- │ ├── comet/SKILL.md
211
- │ │ └── scripts/
212
- │ │ ├── comet-guard.sh # Phase transition guard (--apply auto-updates state)
213
- │ │ ├── comet-archive.sh # One-command archive automation
214
- │ │ ├── comet-yaml-validate.sh # Schema validator
215
- │ │ └── comet-state.sh # Unified state management (init/set/get/check/scale)
216
- │ ├── comet-*/SKILL.md
217
- │ ├── openspec-*/SKILL.md
218
- │ └── brainstorming/SKILL.md
219
- ├── openspec/ # OpenSpec — WHAT
220
- │ ├── config.yaml
221
- │ └── changes/
222
- │ └── <name>/
223
- │ ├── .openspec.yaml # OpenSpec state
224
- │ ├── .comet.yaml # Comet workflow state (decoupled)
225
- │ ├── proposal.md
226
- │ ├── design.md
227
- │ ├── specs/<capability>/spec.md
228
- │ └── tasks.md
229
- └── docs/superpowers/ # Superpowers — HOW
230
- ├── specs/ # Design documents
231
- └── plans/ # Implementation plans
232
- ```
233
-
234
- ## Development
235
-
236
- ```bash
237
- # Clone
238
- git clone https://github.com/rpamis/comet
239
- cd comet
240
-
241
- # Install dependencies
242
- pnpm install
243
-
244
- # Dev mode (watch)
245
- pnpm dev
246
-
247
- # Build
248
- pnpm build
249
-
250
- # Test (unit + coverage)
251
- pnpm test
252
- pnpm test:coverage
253
- pnpm test:shell # bats shell tests
254
-
255
- # Lint & format
256
- pnpm lint
257
- pnpm format
258
- ```
259
-
260
- See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
261
-
262
- ## Security
263
-
264
- - Pre-publish scan for API keys, secrets, tokens, and private keys
265
- - `.npmignore` prevents source code and config files from entering the npm package
266
- - `.gitignore` covers secrets, credentials, IDE configs, and more
267
-
268
- ## License
269
-
270
- MIT
1
+ # @rpamis/comet
2
+
3
+ ```
4
+ ██████╗ ██████╗ ███╗ ███╗███████╗████████╗
5
+ ██╔════╝██╔═══██╗████╗ ████║██╔════╝╚══██╔══╝
6
+ ██║ ██║ ██║██╔████╔██║█████╗ ██║
7
+ ██║ ██║ ██║██║╚██╔╝██║██╔══╝ ██║
8
+ ╚██████╗╚██████╔╝██║ ╚═╝ ██║███████╗ ██║
9
+ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝╚══════╝ ╚═╝
10
+ ```
11
+
12
+ > 中文版:[README-zh.md](README-zh.md)
13
+
14
+ **OpenSpec + Superpowers dual-star development workflow** — one command from idea to archive.
15
+
16
+ OpenSpec handles **WHAT** (outlines, proposals, spec lifecycle, archiving). Superpowers handles **HOW** (technical design, planning, execution, wrap-up). Comet chains both into a five-phase automated pipeline.
17
+
18
+ ## Install
19
+
20
+ ```bash
21
+ npm install -g @rpamis/comet
22
+ ```
23
+
24
+ ## Quick Start
25
+
26
+ ```bash
27
+ cd your-project
28
+ comet init
29
+ ```
30
+
31
+ `comet init` will:
32
+
33
+ 1. Prompt you to select AI platforms (auto-detects existing configs)
34
+ 2. Choose install scope: project-level (current directory) or global (home directory)
35
+ 3. Select language for Comet skills: English or 中文
36
+ 4. Install [OpenSpec](https://github.com/Fission-AI/OpenSpec) skills
37
+ 5. Install [Superpowers](https://github.com/obra/superpowers) skills
38
+ 6. Deploy Comet skills (in your chosen language) to selected platforms
39
+ 7. Create `docs/superpowers/specs/` and `docs/superpowers/plans/` working directories
40
+
41
+ ## Commands
42
+
43
+ | Command | Description |
44
+ |---------|-------------|
45
+ | `comet init [path]` | Initialize Comet workflow |
46
+ | `comet status [path]` | Show active changes and workflow status |
47
+ | `comet doctor [path]` | Diagnose Comet installation health |
48
+ | `comet update [path]` | Update comet skills to latest version |
49
+ | `comet --help` | Show help |
50
+ | `comet --version` | Show version |
51
+
52
+ ### init Options
53
+
54
+ | Option | Description |
55
+ |--------|-------------|
56
+ | `--yes` | Non-interactive mode, auto-select detected platforms |
57
+ | `--skip-existing` | Skip already installed components |
58
+ | `--overwrite` | Overwrite already installed components |
59
+ | `--json` | Output structured JSON |
60
+
61
+ ### status / doctor / update Options
62
+
63
+ | Option | Applies to | Description |
64
+ |--------|-----------|-------------|
65
+ | `--json` | `status`, `doctor` | Output structured JSON |
66
+ | `--language <lang>` | `update` | Language for skills (`en`, `zh`) |
67
+ | `--scope <scope>` | `update` | Install scope (`global`, `project`)|
68
+
69
+ ## Supported Platforms
70
+
71
+ `comet init` supports 28 AI coding platforms:
72
+
73
+ | Platform | Skills Dir | Platform | Skills Dir |
74
+ |----------|-----------|----------|-----------|
75
+ | Claude Code | `.claude/` | Cursor | `.cursor/` |
76
+ | Codex | `.codex/` | OpenCode | `.opencode/` |
77
+ | Windsurf | `.windsurf/` | Cline | `.cline/` |
78
+ | RooCode | `.roo/` | Continue | `.continue/` |
79
+ | GitHub Copilot | `.github/` | Gemini CLI | `.gemini/` |
80
+ | Amazon Q Developer | `.amazonq/` | Qwen Code | `.qwen/` |
81
+ | Kilo Code | `.kilocode/` | Auggie | `.augment/` |
82
+ | Kiro | `.kiro/` | Lingma | `.lingma/` |
83
+ | Junie | `.junie/` | CodeBuddy | `.codebuddy/` |
84
+ | CoStrict | `.cospec/` | Crush | `.crush/` |
85
+ | Factory Droid | `.factory/` | iFlow | `.iflow/` |
86
+ | Pi | `.pi/` | Qoder | `.qoder/` |
87
+ | Antigravity | `.agent/` | Bob Shell | `.bob/` |
88
+ | ForgeCode | `.forge/` | Trae | `.trae/` |
89
+
90
+ ## Skills
91
+
92
+ After `comet init`, three groups of skills are installed to the selected platform's `skills/` directory:
93
+
94
+ ### Comet Skills
95
+
96
+ | Skill | Description |
97
+ |-------|-------------|
98
+ | `/comet` | Main entry — auto-detects phase and dispatches to sub-commands |
99
+ | `/comet-open` | Phase 1: Open a change (proposal, design, task breakdown) |
100
+ | `/comet-design` | Phase 2: Deep design (brainstorming, Design Doc) |
101
+ | `/comet-build` | Phase 3: Plan and build (implementation plan, code commits) |
102
+ | `/comet-verify` | Phase 4: Verify and finish (testing, verification report) |
103
+ | `/comet-archive` | Phase 5: Archive (delta spec sync, status annotation) |
104
+ | `/comet-hotfix` | Preset: Quick bug fix (skips brainstorming) |
105
+ | `/comet-tweak` | Preset: Small change (skips brainstorming and full plan) |
106
+
107
+ ### Guard & Automation Scripts
108
+
109
+ | Script | Purpose |
110
+ |--------|---------|
111
+ | `comet-guard.sh` | Phase transition guard — validates exit conditions, `--apply` auto-updates `.comet.yaml` |
112
+ | `comet-archive.sh` | One-command archive — validates state, syncs specs, moves to archive, updates status |
113
+ | `comet-yaml-validate.sh` | Schema validator — validates `.comet.yaml` structure and field values |
114
+ | `comet-state.sh` | Unified state management — init/set/get/check/scale, agents' exclusive YAML interface |
115
+
116
+ ### OpenSpec Skills
117
+
118
+ Spec lifecycle management: propose, explore, sync, verify, archive, and more.
119
+
120
+ ### Superpowers Skills
121
+
122
+ Development methodology: brainstorming, TDD, subagent-driven development, code review, plan writing, and more.
123
+
124
+ ## Workflow
125
+
126
+ ```
127
+ /comet
128
+ ↓ auto-detect
129
+ /comet-open --> /comet-design --> /comet-build --> /comet-verify --> /comet-archive
130
+ (OpenSpec) (Superpowers) (Superpowers) (Both) (OpenSpec)
131
+
132
+ /comet-hotfix (preset path, skips brainstorming)
133
+ open --> build --> verify --> archive
134
+
135
+ /comet-tweak (preset path, skips brainstorming and full plan)
136
+ open --> lightweight build --> light verify --> archive
137
+ ```
138
+
139
+ ### Five Phases
140
+
141
+ | Phase | Command | Owner | Artifacts |
142
+ |-------|---------|-------|-----------|
143
+ | 1. Open | `/comet-open` | OpenSpec | proposal.md, design.md, tasks.md |
144
+ | 2. Deep Design | `/comet-design` | Superpowers | Design Doc, delta spec |
145
+ | 3. Plan & Build | `/comet-build` | Superpowers | Implementation plan, code commits |
146
+ | 4. Verify & Finish | `/comet-verify` | Both | Verification report, branch handling |
147
+ | 5. Archive | `/comet-archive` | OpenSpec | delta→main spec sync, archive |
148
+
149
+ ### Core Principles
150
+
151
+ - **Brainstorming is non-skippable** — every change must go through deep design (except hotfix/tweak)
152
+ - **Delta specs are living documents** — freely editable during Phase 3, synced at archive
153
+ - **Keep tasks.md in sync** — check off each task as completed
154
+ - **Commit frequently** — one commit per task, message reflects design intent
155
+ - **Verify before archive** — `/comet-verify` must pass before `/comet-archive`
156
+
157
+ ### State Management
158
+
159
+ Comet uses a decoupled state architecture with separate YAML files:
160
+
161
+ | File | Owner | Purpose |
162
+ |------|-------|---------|
163
+ | `.openspec.yaml` | OpenSpec | Spec lifecycle, change metadata |
164
+ | `.comet.yaml` | Comet | Workflow phase, execution mode, verification status |
165
+
166
+ **Key Fields in `.comet.yaml`:**
167
+ - `workflow`: `full`, `hotfix`, or `tweak`
168
+ - `phase`: `design`, `build`, `verify`, `archive`
169
+ - `design_doc`: Path to Superpowers Design Doc
170
+ - `plan`: Path to implementation plan
171
+ - `build_mode`: `subagent-driven-development`, `executing-plans`, or `direct`
172
+ - `isolation`: `branch` or `worktree`, workspace isolation method
173
+ - `verify_mode`: `light` or `full`
174
+ - `verify_result`: `pending`, `pass`, or `fail`
175
+ - `archived`: Boolean indicating if change is archived
176
+
177
+ ### Reliability Features
178
+
179
+ Comet ensures agent execution reliability through automated state transitions:
180
+
181
+ 1. **Entry Verification** — Each phase validates preconditions before execution
182
+ - Checks file existence, state consistency, and phase transitions
183
+ - Outputs `[HARD STOP]` with actionable suggestions if validation fails
184
+
185
+ 2. **Automated State Transitions** — `comet-guard.sh --apply` updates `.comet.yaml` automatically
186
+ - All phase transitions (design → build → verify → archive) use `guard --apply`
187
+ - No manual state editing required — eliminates write-verification errors
188
+ - `comet-state.sh` is the agents' exclusive interface for state operations
189
+ - Guard and archive scripts use `comet-state.sh` internally for state management
190
+
191
+ 3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
192
+ - Validates required fields (10 fields)
193
+ - Validates enum values (7 enum types)
194
+ - Validates referenced file paths exist
195
+ - Detects unknown/typos fields
196
+
197
+ 4. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
198
+ - Validates entry state, syncs delta specs to main specs
199
+ - Annotates design doc and plan frontmatter
200
+ - Moves change to archive directory and updates `archived: true`
201
+ - Supports `--dry-run` for preview
202
+
203
+ **Security**: Path traversal protection on all change name inputs
204
+
205
+ ## Project Structure
206
+
207
+ ```
208
+ your-project/
209
+ ├── .claude/skills/ # Platform skills dir (Comet + OpenSpec + Superpowers)
210
+ │ ├── comet/SKILL.md
211
+ │ │ └── scripts/
212
+ │ │ ├── comet-guard.sh # Phase transition guard (--apply auto-updates state)
213
+ │ │ ├── comet-archive.sh # One-command archive automation
214
+ │ │ ├── comet-yaml-validate.sh # Schema validator
215
+ │ │ └── comet-state.sh # Unified state management (init/set/get/check/scale)
216
+ │ ├── comet-*/SKILL.md
217
+ │ ├── openspec-*/SKILL.md
218
+ │ └── brainstorming/SKILL.md
219
+ ├── openspec/ # OpenSpec — WHAT
220
+ │ ├── config.yaml
221
+ │ └── changes/
222
+ │ └── <name>/
223
+ │ ├── .openspec.yaml # OpenSpec state
224
+ │ ├── .comet.yaml # Comet workflow state (decoupled)
225
+ │ ├── proposal.md
226
+ │ ├── design.md
227
+ │ ├── specs/<capability>/spec.md
228
+ │ └── tasks.md
229
+ └── docs/superpowers/ # Superpowers — HOW
230
+ ├── specs/ # Design documents
231
+ └── plans/ # Implementation plans
232
+ ```
233
+
234
+ ## Development
235
+
236
+ ```bash
237
+ # Clone
238
+ git clone https://github.com/rpamis/comet
239
+ cd comet
240
+
241
+ # Install dependencies
242
+ pnpm install
243
+
244
+ # Dev mode (watch)
245
+ pnpm dev
246
+
247
+ # Build
248
+ pnpm build
249
+
250
+ # Test (unit + coverage)
251
+ pnpm test
252
+ pnpm test:coverage
253
+ pnpm test:shell # bats shell tests
254
+
255
+ # Lint & format
256
+ pnpm lint
257
+ pnpm format
258
+ ```
259
+
260
+ See [CHANGELOG.md](CHANGELOG.md) for version history and updates.
261
+
262
+ ## Security
263
+
264
+ - Pre-publish scan for API keys, secrets, tokens, and private keys
265
+ - `.npmignore` prevents source code and config files from entering the npm package
266
+ - `.gitignore` covers secrets, credentials, IDE configs, and more
267
+
268
+ ## License
269
+
270
+ MIT
@@ -1,21 +1,21 @@
1
- {
2
- "version": "0.1.0",
3
- "skills": [
4
- "comet/SKILL.md",
5
- "comet/scripts/comet-guard.sh",
6
- "comet/scripts/comet-state.sh",
7
- "comet/scripts/comet-archive.sh",
8
- "comet/scripts/comet-yaml-validate.sh",
9
- "comet-open/SKILL.md",
10
- "comet-design/SKILL.md",
11
- "comet-build/SKILL.md",
12
- "comet-verify/SKILL.md",
13
- "comet-archive/SKILL.md",
14
- "comet-hotfix/SKILL.md",
15
- "comet-tweak/SKILL.md"
16
- ],
17
- "languages": [
18
- { "id": "en", "name": "English", "skillsDir": "skills" },
19
- { "id": "zh", "name": "中文", "skillsDir": "skills-zh" }
20
- ]
21
- }
1
+ {
2
+ "version": "0.1.0",
3
+ "skills": [
4
+ "comet/SKILL.md",
5
+ "comet/scripts/comet-guard.sh",
6
+ "comet/scripts/comet-state.sh",
7
+ "comet/scripts/comet-archive.sh",
8
+ "comet/scripts/comet-yaml-validate.sh",
9
+ "comet-open/SKILL.md",
10
+ "comet-design/SKILL.md",
11
+ "comet-build/SKILL.md",
12
+ "comet-verify/SKILL.md",
13
+ "comet-archive/SKILL.md",
14
+ "comet-hotfix/SKILL.md",
15
+ "comet-tweak/SKILL.md"
16
+ ],
17
+ "languages": [
18
+ { "id": "en", "name": "English", "skillsDir": "skills" },
19
+ { "id": "zh", "name": "中文", "skillsDir": "skills-zh" }
20
+ ]
21
+ }