@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 +21 -21
- package/README.md +270 -270
- package/assets/manifest.json +21 -21
- package/assets/skills/comet/scripts/comet-archive.sh +258 -258
- package/assets/skills/comet/scripts/comet-guard.sh +7 -5
- package/assets/skills/comet/scripts/comet-state.sh +497 -496
- package/assets/skills/comet/scripts/comet-yaml-validate.sh +132 -132
- package/assets/skills/comet-archive/SKILL.md +63 -63
- package/assets/skills/comet-build/SKILL.md +153 -153
- package/assets/skills/comet-design/SKILL.md +91 -91
- package/assets/skills/comet-open/SKILL.md +70 -70
- package/assets/skills/comet-verify/SKILL.md +114 -114
- package/assets/skills-zh/comet-archive/SKILL.md +63 -63
- package/assets/skills-zh/comet-build/SKILL.md +153 -153
- package/assets/skills-zh/comet-design/SKILL.md +91 -91
- package/assets/skills-zh/comet-open/SKILL.md +70 -70
- package/assets/skills-zh/comet-verify/SKILL.md +114 -114
- package/bin/comet.js +3 -3
- package/dist/cli/index.js +10 -1
- package/dist/cli/index.js.map +1 -1
- package/dist/core/detect.d.ts +6 -1
- package/dist/core/detect.d.ts.map +1 -1
- package/dist/core/detect.js +29 -1
- package/dist/core/detect.js.map +1 -1
- package/package.json +62 -61
- package/scripts/postinstall.js +44 -44
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
|
package/assets/manifest.json
CHANGED
|
@@ -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
|
+
}
|