# Commands

All spec commands are available in the CLI REPL via `/spec` (or `/specs` as an alias for `/spec list`).

## /spec list

List all specs with per-phase status badges.

**Usage:**

```
/spec list
/specs
```

**Example output:**

```text
  @myapp/spec/api-design  requirements:approved design:approved tasks:draft
  @myapp/spec/auth-flow   requirements:approved design:stale tasks:draft
```

Phase statuses are color-coded:

- **Green** — `approved`
- **Amber** — `stale`
- **Gray** — `draft`

---

## /spec show

Show a spec with phase statuses, content, and task list.

**Usage:**

```
/spec show <fqn>
```

**Example:**

```
/spec show @myapp/spec/api-design
```

**Output:**

```text
Spec: @myapp/spec/api-design

  requirements: approved
  design:       approved
  tasks:        draft

Requirements:
  Users must be able to create, read, update, and delete
  API resources via REST endpoints.

Design:
  FastAPI router with Pydantic models. SQLite storage
  via parameterized queries. Auth via session middleware.

Tasks:
  setup-router: Create FastAPI router skeleton
  add-models: Define Pydantic request/response models
  implement-crud: Implement CRUD endpoints [depends on: setup-router, add-models]
  add-tests: Write endpoint tests [depends on: implement-crud]
```

---

## /spec create

Create a new spec by opening your editor with a YAML template, or generate one from a natural-language prompt or GitHub issue.

**Usage:**

```
/spec create <namespace> <name>
/spec create --design-first <namespace> <name>
/spec create --bugfix <namespace> <name>
/spec create --prompt <text> <namespace> <name>
/spec create --from-issue <N> <namespace> <name>
```

**Examples:**

```
/spec create myapp api-design
/spec create --bugfix myapp login-fix
/spec create --prompt "Add retry logic to the API client" myapp retry-logic
/spec create --from-issue 42 myapp issue-fix
```

Without `--prompt` or `--from-issue`, this opens `$EDITOR` (falls back to `$VISUAL`, then `vi`) with a pre-populated YAML template. Fill in the `requirements`, `design`, and `tasks` sections, then save and close the editor.

The resulting spec has the FQN `@myapp/spec/api-design`. All three phases start in `draft` status.

If you close the editor without changing the template, the create is cancelled.

### LLM-assisted generation

The `--prompt` flag generates a spec from a natural-language description. The LLM drafts `requirements`, `design`, and `tasks` sections, then opens the result in your editor for review before saving.

```
/spec create --prompt "Add caching to the search endpoint with TTL config" myapp search-cache
```

The `--from-issue` flag fetches a GitHub issue (title, body, labels) and uses it as the generation prompt:

```
/spec create --from-issue 106 myapp replay-hardening
```

Both flows:

1. Call the LLM to generate a structured spec (JSON, converted to YAML)
2. Display the generated YAML with syntax highlighting
3. Open `$EDITOR` for review and editing
4. Save via `create_spec()` with `creation_flow: prompt` or `creation_flow: from_issue`

If the LLM output cannot be parsed as valid JSON, the raw output is returned with a warning header for manual editing.

### Design-first template

The `--design-first` flag starts from the design phase with requirements deferred. Use when the architecture drives the requirements — for example, when exploring a technical approach before defining acceptance criteria. The template sets `creation_flow: design_first` and pre-populates design and tasks sections.

### Bugfix template

The `--bugfix` flag uses a specialized template with `mode: bugfix` that includes:

- **current_behavior** — description of the observed bug
- **expected_behavior** — description of the correct behavior
- **reproduction_steps** — steps to reproduce the issue

The bugfix template pre-populates tasks for investigation, fix implementation, and regression testing.

!!! info
    Unlike other `/spec` commands, `create` takes a bare namespace and name — the FQN is built automatically. All other commands require the full FQN.

---

## /spec approve

Approve a specific phase of a spec.

**Usage:**

```
/spec approve <fqn> <phase>
```

**Example:**

```
/spec approve @myapp/spec/api-design requirements
```

Valid phase names: `requirements`, `design`, `tasks`.

Approval records the current timestamp, the approving user, and the current content version number. This metadata is used to derive stale reasons if the content later changes.

---

## /spec unapprove

Reset a phase back to `draft` status, clearing its approval metadata.

**Usage:**

```
/spec unapprove <fqn> <phase>
```

**Example:**

```
/spec unapprove @myapp/spec/api-design design
```

This is useful for:

- Withdrawing an approval after discovering an issue
- Resetting a `stale` phase before re-approving it

---

## /spec diff

Show a colorized content diff between the two most recent spec versions.

**Usage:**

```
/spec diff <fqn>
```

**Example:**

```
/spec diff @myapp/spec/api-design
```

Diff output shows per-phase changes in unified diff format.

!!! warning
    Diffing requires at least 2 content versions. If the spec has only been created (version 1) with no subsequent content changes, the command reports: "Only one version — nothing to diff."

    Use `/spec edit` to update content and create a new version, then diff to see what changed.

---

## /spec launch

Launch a workflow run from a spec task.

**Usage:**

```
/spec launch <fqn> <task_id> <workflow_id>
```

**Example:**

```
/spec launch @myapp/spec/api-design implement-crud my-workflow
```

This starts a workflow run targeting the specified spec task. The workflow receives the spec FQN and task metadata as inputs.

**Prerequisites:**

- The spec must exist and the task_id must be defined in the spec's tasks list
- The workflow must be resolvable by ID
- The tasks phase does not need to be approved to launch (approval gates are checked within the workflow itself)

**Output:**

```text
Launched workflow my-workflow for task implement-crud
  Run ID: abc123def456
  Status: running
```

---

## /spec edit

Open your editor with the spec's YAML content for editing. Optionally edit a single phase.

**Usage:**

```
/spec edit <fqn>
/spec edit <fqn> requirements
/spec edit <fqn> design
```

**Example:**

```
/spec edit @myapp/spec/api-design
/spec edit @myapp/spec/api-design design
```

If a phase is specified (`requirements` or `design`), only that phase's content is loaded into the editor. Otherwise, the full spec YAML is opened.

Saving and closing the editor triggers a content update. If the content hash changes, a new version is created and invalidation rules apply. If you close without changes, the edit is cancelled.

---

## /spec queue

Show the review inbox: specs needing review, stale specs, and blocked workflow runs.

**Usage:**

```
/spec queue
```

**Example output:**

```text
Review Queue:

  Needs review (2):
    @myapp/spec/api-design    design:draft
    @myapp/spec/auth-flow     tasks:draft

  Stale (1):
    @myapp/spec/auth-flow     requirements:stale

  Blocked runs (1):
    @myapp/spec/api-design    run abc123 waiting on spec_design_approved
```

---

## /spec link

Link a spec to a git branch or pull request for traceability.

**Usage:**

```
/spec link <fqn>
/spec link <fqn> branch <name>
/spec link <fqn> pr <number> [url]
```

**Examples:**

```
/spec link @myapp/spec/api-design
/spec link @myapp/spec/api-design branch issue-42-api-design
/spec link @myapp/spec/api-design pr 42 https://github.com/org/repo/pull/42
```

With no arguments beyond the FQN, the current git branch is auto-detected and linked. The optional `url` on PR links is stored for display purposes.

---

## /spec unlink

Remove a git link from a spec.

**Usage:**

```
/spec unlink <fqn> <link_id>
```

**Example:**

```
/spec unlink @myapp/spec/api-design abc123
```

Use `/spec links` to find link IDs.

---

## /spec links

List all git links for a spec.

**Usage:**

```
/spec links <fqn>
```

**Example:**

```
/spec links @myapp/spec/api-design
```

**Example output:**

```text
Links for @myapp/spec/api-design:

  abc123  branch  issue-42-api-design
  def456  pr      #42  https://github.com/org/repo/pull/42
```

---

## `/spec dashboard`

Portfolio view of all specs with lifecycle state, phase statuses, and workflow execution status.

### Usage

```
/spec dashboard
/spec dashboard --status stale
/spec dashboard --namespace myteam
/spec dashboard --phase design --phase-status draft
```

### Flags

| Flag | Description |
|------|-------------|
| `--status <status>` | Filter by overall status: `draft`, `in_progress`, `stale`, `blocked`, `all_approved` |
| `--namespace <ns>` | Filter by namespace |
| `--phase <phase>` | Filter by specific phase (requires `--phase-status`) |
| `--phase-status <status>` | Filter by phase status: `draft`, `approved`, `stale` |

### Output

Renders a Rich table with columns: FQN, Mode, Status, Req, Des, Tasks, Runs, Updated. Footer shows totals by status category.

The dashboard complements `/spec queue` — the queue shows what needs attention, the dashboard shows the state of everything.

---

## /spec conformance

Run deterministic conformance checks on a spec: task coverage, run health, phase status, and temporal validity.

**Usage:**

```
/spec conformance <fqn>
```

**Example:**

```
/spec conformance @myapp/spec/api-design
```

**Example output:**

```text
Conformance: @myapp/spec/api-design (v3)

  Task coverage:     4/4 tasks have runs
  Run health:        3 completed, 1 failed
  Phase status:      requirements:approved design:approved tasks:stale
  Temporal validity: design approved before requirements changed

  Result: NON-CONFORMANT (2 findings)
    - tasks phase is stale
    - task implement-crud has a failed run
```
