@rpamis/comet 0.2.4 → 0.2.6

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 rpamis
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 rpamis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,8 @@
 <p align="center">
-  <a href="https://github.com/rpamis/comet">
+  <a href="https://github.com/rpamis/comet/blob/master/img/title-log.png">
     <picture>
-      <source srcset="img/title-log.png">
-      <img src="img/title-log.png" alt="Comet logo">
+      <source srcset="https://github.com/rpamis/comet/blob/master/img/title-log.png">
+      <img src="https://github.com/rpamis/comet/blob/master/img/title-log.png" alt="Comet logo">
     </picture>
   </a>
 </p>
@@ -72,7 +72,7 @@ comet init
 ## Screenshots
 
 <p align="center">
-  <img src="img/runner.png" alt="runner">
+  <img src="https://github.com/rpamis/comet/blob/master/img/runner.png" alt="runner">
 </p>
 
 <p align="center">Auto-install OpenSpec & Superpowers, one-click dev environment setup</p>
@@ -83,9 +83,9 @@ comet init
 | Command | Description |
 |---------|-------------|
 | `comet init [path]` | Initialize Comet workflow |
-| `comet status [path]` | Show active changes and workflow status |
-| `comet doctor [path]` | Diagnose Comet installation health |
-| `comet update [path]` | Update comet skills to latest version |
+| `comet status [path]` | Show active changes, task progress, and next workflow command |
+| `comet doctor [path]` | Diagnose project/global Comet installation health |
+| `comet update [path]` | Update the npm package and installed Comet skills |
 | `comet --help` | Show help |
 | `comet --version` | Show version |
 
@@ -98,13 +98,28 @@ comet init
 | `--overwrite` | Overwrite already installed components |
 | `--json` | Output structured JSON |
 
-### status / doctor / update Options
+When multiple existing components are found on the same platform, interactive init offers one bulk choice: overwrite all, skip all, or choose per component.
 
-| Option | Applies to | Description |
-|--------|-----------|-------------|
-| `--json` | `status`, `doctor` | Output structured JSON |
-| `--language <lang>` | `update` | Language for skills (`en`, `zh`) |
-| `--scope <scope>` | `update` | Install scope (`global`, `project`)|
+### status Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output active changes with `nextCommand` |
+
+### doctor Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output structured diagnostic results |
+| `--scope <scope>` | Diagnose `auto`, `project`, or `global` scope (default: `auto`) |
+
+### update Options
+
+| Option | Description |
+|--------|-------------|
+| `--json` | Output npm and skill update results as JSON |
+| `--language <lang>` | Override detected skill language (`en`, `zh`) |
+| `--scope <scope>` | Update only `global` or `project` scope |
 
 ## Supported Platforms
 
@@ -220,6 +235,8 @@ verified_at: null
 archived: false
 ```
 
+In full workflow, `build_mode` and `isolation` may temporarily be `null` at init time, but they must be resolved before `build → verify`. `direct` is allowed by default only for hotfix/tweak; full workflow requires `direct_override: true`. Projects can configure `build_command` / `verify_command` in the change or repo root, and guard will run those commands first and print failure output.
+
 All states and execution phases are updated via scripts, and **each phase verifies that tasks are truly completed before exiting — conditions are met before the phase exits and state is updated**. Compared to recording complex state management mechanisms in Skills, the script approach strongly guarantees the reliability of core state transitions, correctness of YAML files, and convenience of breakpoint recovery — Agents only need to use Comet's built-in commands to read state and know the current Spec's situation.
 
 ### Reliability Features
@@ -237,18 +254,23 @@ Comet ensures agent execution reliability through automated state transitions:
    - Guard and archive scripts use `comet-state.sh` internally for state management
 
 3. **Schema Validation** — `comet-yaml-validate.sh` ensures data integrity
-   - Validates required fields (12 fields)
-   - Validates enum values (8 enum types)
+   - Validates required and optional fields
+   - Validates enum values, including `direct_override`
    - Validates referenced file paths exist
    - Detects unknown/typos fields
 
-4. **Verification Evidence** — Guard enforces proof before phase advance
+4. **Build Decision Enforcement** — Guard and state transitions both block skipped build choices
+   - `isolation` must be `branch` or `worktree`
+   - `build_mode` must be selected before leaving build
+   - Full workflow `build_mode: direct` requires `direct_override: true`
+
+5. **Verification Evidence** — Guard enforces proof before phase advance
    - `verify-pass` transition requires `verification_report` pointing to an existing report file
    - `branch_status` must be `handled` before verify can pass
    - Guard checks `verification_report exists` and `branch_status=handled` as hard prerequisites
    - Prevents false phase advances when verification or branch handling was skipped
 
-5. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
+6. **Archive Automation** — `comet-archive.sh` handles the full archive flow in one command
    - Validates entry state, syncs delta specs to main specs
    - Annotates design doc and plan frontmatter
    - Moves change to archive directory and updates `archived: true`
@@ -297,6 +319,8 @@ Long-term Skill users know these capabilities can be freely combined, but exactl
 
 ## Development
 
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, commit conventions, PR process, and guidance for adding platforms or skills.
+
 ```bash
 # Clone
 git clone https://github.com/rpamis/comet

package/assets/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.4",
+  "version": "0.2.6",
   "skills": [
     "comet/SKILL.md",
     "comet/scripts/comet-guard.sh",

package/assets/skills/comet/SKILL.md

@@ -156,6 +156,8 @@ build_mode: subagent-driven-development
 isolation: branch
 verify_mode: light
 verify_result: pending
+verification_report: null
+branch_status: pending
 verified_at: null
 archived: false
 ```
@@ -167,12 +169,28 @@ archived: false
 | `design_doc` | Associated Superpowers Design Doc path, can be empty |
 | `plan` | Associated Superpowers Plan path, can be empty |
 | `build_mode` | Selected execution mode, can be empty |
-| `isolation` | `branch` or `worktree`, workspace isolation method, defaults to `branch` |
+| `isolation` | `branch` or `worktree`, workspace isolation method. Full workflow init may leave this as `null`, but only until `/comet-build` Step 3; hotfix/tweak default to `branch` |
 | `verify_mode` | `light` or `full`, can be empty |
 | `verify_result` | `pending`, `pass`, or `fail` |
+| `verification_report` | Verification report file path; must point to an existing file before verify can pass |
+| `branch_status` | `pending` or `handled`; set to `handled` after branch handling completes |
 | `verified_at` | Verification pass time, can be empty |
 | `archived` | Whether change is archived |
 
+Optional fields:
+
+| Field | Meaning |
+|-------|---------|
+| `direct_override` | `true`/`false`. Full workflow may use `build_mode: direct` only when this is explicitly `true` |
+| `build_command` | Project build command. Guard runs this first and prints failure output |
+| `verify_command` | Project verification command. Verify guard runs this first; if absent, it falls back to the build command |
+
+State-machine hard constraints:
+- Before `build → verify`, `isolation` must be `branch` or `worktree`
+- Before `build → verify`, `build_mode` must be selected
+- `build_mode: direct` is allowed by default only for `hotfix` / `tweak`; full workflow requires `direct_override: true`
+- These constraints are enforced by both `comet-guard.sh build --apply` and `comet-state.sh transition <name> build-complete`
+
 ### Script Location
 
 Comet scripts are distributed in `comet/scripts/`. **Do not hardcode paths** — locate once, cache in env vars: