spec-kitty.specify

## Startup Upgrade Check

Run this at most once per active agent session before the first Spec Kitty command workflow.
If you already ran `spec-kitty upgrade --agent-check --json` in this session, reuse that result and skip this block.
Do not run or announce an upgrade check again for later Spec Kitty commands in the same session.
Otherwise, before continuing, run:

```bash
spec-kitty upgrade --agent-check --json
```

If JSON `action` is `none`, continue.
If `action` is `auto_upgrade`, run `upgrade_command` before continuing. If it fails, tell the user and continue with the current Spec Kitty version.
If `action` is `guidance`, show `upgrade_note` briefly, then continue.
If `action` is `prompt`, ask the user with the host-native question UI when available:

`Spec Kitty {latest_version} is available. You are on {installed_version}. Upgrade now?`

Use these choices:

1. Upgrade now (recommended) - record `upgrade_now`, run `upgrade_command`, then continue.
2. Always keep me up to date - record `always`, run `upgrade_command`, then continue.
3. Not now - record `not_now`, then continue.
4. Never ask again - record `never_ask`, then continue.

Record the selected choice before continuing:

```bash
spec-kitty upgrade --agent-choice <upgrade_now|always|not_now|never_ask> --agent-latest <latest_version> --json
```

If no host-native question UI is available, present the same four choices in plain text and wait for the user.
In non-interactive hosts, choose `not_now` and continue.


# /spec-kitty.specify - Create Mission Specification

**Version**: 0.11.0+

## 📍 WORKING DIRECTORY: Stay in the repository root checkout

**IMPORTANT**: Specify works in the repository root checkout. NO worktrees are created.

```bash
# Run from the repository root checkout:
cd /path/to/project/root  # Your repository root checkout

# All planning artifacts are created in the project root and committed:
# - kitty-specs/<mission_slug>/spec.md → Created in project root
#   (use the mission_slug returned by `mission create`; the numeric NNN- prefix
#    is display-only and is assigned at merge time)
# - Committed to target branch (from create JSON: target_branch/base_branch)
# - NO worktrees created
```

**Worktrees are created later** during `/spec-kitty.implement`, after task finalization computes execution lanes.

## Mission Handle Rule

Before `mission create`, there is no mission handle yet.

- Do **not** pass `--mission` to `spec-kitty agent mission branch-context`.
- Do **not** pass `--mission` to `spec-kitty agent mission create`.
- After `create` succeeds, use `--mission <handle>` for commands that operate on
  the created mission.
- `<handle>` can be the mission's `mission_id` (ULID), `mid8` (first 8 chars of
  the ULID), or `mission_slug`.
- The resolver disambiguates by `mission_id` and returns a structured
  `MISSION_AMBIGUOUS_SELECTOR` error on ambiguity — there is no silent fallback.

## User Input

The content of the user's message that invoked this skill (everything after the skill invocation token, e.g. after `/spec-kitty.<command>` or `$spec-kitty.<command>`) is the User Input referenced elsewhere in these instructions.

You **MUST** consider this user input before proceeding (if not empty).

## Primary Invariant: What Are We Building?

This workflow answers "What are we building?" before it creates artifacts. The
raw invocation text is only a starting point for discovery, not the final truth.

Before `mission create`, before writing `spec.md`, and before committing
anything, you **MUST** have one of these:

- A completed discovery interview with an acknowledged Intent Summary.
- A brief-intake summary and extracted requirement set explicitly confirmed by
  the user.
- An explicit user instruction to minimize or skip discovery; even then, record
  the minimal confirmed scenario and assumptions in the Intent Summary.

For non-trivial work, the confirmed Intent Summary must cover the primary actor,
trigger, desired outcome, one rule or invariant, and any canonical domain term
or boundary that materially affects the work.

## Branch Strategy Confirmation (MANDATORY)

Before discovery, resolve branch intent through the Python helper, not by probing git directly:

```bash
spec-kitty agent mission branch-context --json
```

If the user already told you the intended landing branch, pass it explicitly:

```bash
spec-kitty agent mission branch-context --json --target-branch <intended-branch>
```

Parse the JSON and, in your next reply, explicitly tell the user:

- Current branch at workflow start: `current_branch`
- Default planning/base branch if you create the mission right now: `planning_base_branch`
- Final merge target for completed changes: `merge_target_branch`
- Whether `branch_matches_target` is true or false
- If that is not the intended landing branch, stop and ask which branch should receive this feature before you run `create`

Never talk generically about `main` or "the default branch". Name the actual branch values from the helper JSON. Do not shell out to git for this prompt.

## Commit Boundary (issue #846)

`spec-kitty agent mission create` no longer auto-commits `spec.md`. The empty
template is written to disk untracked at create time; **you** are responsible
for committing it after writing substantive content.

"Substantive content" for `spec.md` means **at least one Functional
Requirements row** (`FR-###`) whose description is real (not a template
placeholder like `[NEEDS CLARIFICATION …]`, `[e.g., …]`, or a bare user-story
scaffold). Section presence is the only signal — adding 300 bytes of arbitrary
prose without an FR row does **not** count as substantive.

Workflow:

1. Run `spec-kitty agent mission create …`. Note that `spec.md` is left
   untracked.
2. Populate `spec.md` with real Functional / Non-Functional / Constraint rows.
3. Commit `spec.md` yourself: `spec-kitty safe-commit --message "Add spec for <slug>" <feature_dir>/spec.md`.
4. Only then will `spec-kitty agent mission setu