> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# comet status — View Active Changes and Next Command

> comet status displays active OpenSpec changes, task progress, and the recommended next workflow command. Use --json for machine-readable output.

`comet status` gives you a read-only snapshot of active Comet-managed and plain OpenSpec changes, task progress, runtime evidence, and the appropriate next command.

## Usage

```bash theme={null}
comet status
```

`path` defaults to `.` (the current directory) when omitted. The command reads change state from the Classic OpenSpec root selected by `classic.artifact_layout`: `docs/openspec/changes/` for new projects or `openspec/changes/` for retained legacy layouts.

## Example Output

```
Active Changes:

  1. my-feature [Comet] [phase: build [3/7 tasks]]
     workflow: full | build_mode: subagent-driven-development
     plan:   docs/superpowers/plans/2024-06-01-my-feature.md
     next: /comet-build

  2. quick-fix [Comet] [phase: verify [5/5 tasks]]
     workflow: full | build_mode: direct
     verify_result: pending
     next: /comet-verify

  3. docs-only [OpenSpec] [plain change [2/2 tasks]]
     recommended archive: openspec archive docs-only -y
```

Each entry shows:

| Field           | Description                                                                          |
| --------------- | ------------------------------------------------------------------------------------ |
| `phase`         | Current workflow phase (`open`, `design`, `build`, `verify`, `archive`).             |
| `tasks`         | Completed / total task count from `tasks.md`, e.g. `[3/7 tasks]`.                    |
| `workflow`      | Workflow preset (`full`, `hotfix`, `tweak`).                                         |
| `build_mode`    | Build execution mode (e.g. `subagent-driven-development`, `direct`).                 |
| `design`        | Path to the Superpowers Design Doc, if generated.                                    |
| `plan`          | Path to the implementation plan, if generated.                                       |
| `verify_result` | Verification outcome (`pending`, `pass`, `fail`) — shown only in the `verify` phase. |
| `next`          | The Comet skill command to run next.                                                 |

## Mixed Comet and OpenSpec changes

One project may contain both Comet-managed changes and plain OpenSpec changes. Status labels them separately instead of forcing plain OpenSpec work into the Classic five-phase lifecycle.

| Change type    | State source                               | Archive command when ready          |
| -------------- | ------------------------------------------ | ----------------------------------- |
| Comet-managed  | `.comet.yaml` and Classic runtime evidence | `comet archive <change-name>`       |
| Plain OpenSpec | OpenSpec artifacts and task completion     | `openspec archive <change-name> -y` |

Only archive-ready entries show a recommendation. Invalid state, incomplete tasks, or failed verification continue to show recovery guidance.

## Multiple active Comet changes

With one active Comet change, source work can be attributed automatically. With multiple active changes, select the intended target first:

```bash theme={null}
comet state select <change-name>
comet state current
```

Selection is tied to the current branch/worktree. Switches and stale selections require a new `select`; the source-write guard does not guess.

Only non-archived changes appear. A directory without `.comet.yaml` appears as a plain OpenSpec change rather than being silently excluded.

## Flags

<ParamField query="--json" type="boolean">
  Output active changes as structured JSON, including a `nextCommand` field for each change. Useful
  for scripting and automation.
</ParamField>

## JSON Output

```bash theme={null}
comet status --json
```

```json theme={null}
{
  "changes": [
    {
      "name": "my-feature",
      "workflow": "full",
      "phase": "build",
      "buildMode": "subagent-driven-development",
      "isolation": "branch",
      "verifyMode": null,
      "verifyResult": "pending",
      "designDoc": null,
      "plan": "docs/superpowers/plans/2024-06-01-my-feature.md",
      "tasksCompleted": 3,
      "tasksTotal": 7,
      "nextCommand": "/comet-build"
    }
  ]
}
```

The `nextCommand` field maps each phase to its corresponding Comet entry point:

| Phase     | Next command     |
| --------- | ---------------- |
| `open`    | `/comet-open`    |
| `design`  | `/comet-design`  |
| `build`   | `/comet-build`   |
| `verify`  | `/comet-verify`  |
| `archive` | `/comet-archive` |

## Use Cases

* **Quick workflow check** — Glance at all in-flight changes and where each one stands.
* **Know what to run next** — The `next` field tells you exactly which Comet command to invoke to continue.
* **Scripting and automation** — Pipe `--json` output into CI scripts or shell tooling to conditionally trigger workflow commands based on phase or task completion.
* **Resume after interruption** — After closing an AI coding session, run `comet status` to orient yourself before typing `/comet` in your AI platform.