@skitterbyte/skitterspec 2.0.1 → 3.0.0

package/assets/skills/spec-env/SKILL.md

@@ -1,63 +0,0 @@
----
-name: spec-env
-description: Provision an isolated environment for a spec — a git worktree on its own branch + a namespaced Docker stack (isolated containers/networks/volumes + a reserved port block), plus an optional editor/terminal opener. Runs `skitterspec spec-env up` and executes the printed git/docker/open commands. Opt-in — needs specs/.core/env.config.json. Use when the user says "/spec-env", "spin up an environment for <spec>", "give this spec its own worktree/stack", or "isolate <spec>".
----
-
-# /spec-env — provision an isolated environment for a spec
-
-Give an in-progress spec its own **git worktree** (a sibling directory on its own
-branch, no stashing) + a **namespaced Docker stack** (`COMPOSE_PROJECT_NAME`
-isolates containers/networks/volumes; `PORT_OFFSET` reserves a port block), so N
-specs run side by side and `main` stays clean. An optional `open.command` then
-opens the worktree however you like.
-
-This skill is **opt-in**: it only works when `specs/.core/env.config.json` exists
-(copy `env.config.json.example` to adopt it). If it's absent, tell the user how
-to enable it and stop.
-
-## 1. Identify the target spec
-
-- Use the spec named as an argument, else the spec **currently in context**. If
-  neither is clear, ask which spec.
-
-## 2. Plan the environment
-
-Run the engine — it allocates the slot (idempotent), persists the registry, and
-**prints** the plan (worktree path, branch, project name, port block, the exact
-commands, the `.env` contents, and the opener):
-
-```
-skitterspec spec-env up <spec>
-```
-
-If it reports the feature isn't enabled, relay that and stop — do not hand-roll a
-worktree/stack.
-
-## 3. Execute the printed side effects
-
-Run the printed commands **in order**, exactly as printed:
-
-1. **`git worktree add …`** — creates the sibling worktree on its branch. It is a
-   **sibling** of this checkout, **never nested** inside it. If the worktree
-   already exists, the engine prints the *attach* form (no `-b`) — do not clobber
-   an existing worktree/branch.
-2. **Write the `.env`** — write the printed `.env` contents into the new
-   worktree's env file (default `.env`). Do this *after* the worktree exists.
-3. **`docker compose … up -d`** — only printed when Docker is enabled. Brings the
-   namespaced stack up in the spec's reserved port block.
-4. **Opener** — if an `open.command` line was printed, run it (e.g. opens the
-   worktree in your editor/terminal). Skipped silently when unset.
-5. **Trust the worktree root for this session** — the engine already wrote the
-   printed `trusted:` root into `.claude/settings.local.json` (gitignored, so it
-   persists for future sessions). That file likely won't hot-reload mid-session,
-   so also run `/add-dir <trusted root>` now to lift `Edit`/`Write` prompts for
-   the **current** session. (If the engine printed a `trusted: ! …` warning,
-   `settings.local.json` isn't valid JSON — fix it, then re-run.)
-
-## 4. Report
-
-Echo the summary: worktree path, branch, project name, the allocated slot + port
-block, and whether the stack was brought up. **Idempotent** — re-running attaches
-to the existing slot/worktree and never reallocates.
-
-Tear down later with `/spec-env-down <spec>`.

package/assets/skills/spec-env-down/SKILL.md

@@ -1,64 +0,0 @@
----
-name: spec-env-down
-description: Tear down a spec's isolated environment — stop and remove its namespaced Docker stack (optionally backing up + dropping volumes), remove its git worktree, and free its slot. Guards refuse teardown on a dirty or unpushed worktree unless --force. Runs `skitterspec spec-env down` and executes the printed commands. Opt-in — needs specs/.core/env.config.json. Use when the user says "/spec-env-down", "tear down <spec>'s environment", "clean up the worktree/stack for <spec>", or "reclaim <spec>'s slot".
----
-
-# /spec-env-down — tear down a spec's isolated environment
-
-Reverse `/spec-env`: stop + remove the spec's Docker stack, remove its git
-worktree, and free its slot so the ports/slot are reclaimed. **Volumes are the
-only destructive part** — dropped by default (to reclaim disk) unless
-`--keep-volumes`, and always backed up first when `docker.backupCommand` is set.
-
-Opt-in: only works when `specs/.core/env.config.json` exists. If absent, say so
-and stop.
-
-## 1. Identify the target spec
-
-- Use the spec named as an argument, else the spec **currently in context**. If
-  neither is clear, ask which spec.
-
-## 2. Plan the teardown
-
-Run the engine — it checks the guards, frees the slot, and **prints** the plan:
-
-```
-skitterspec spec-env down <spec> [--keep-volumes] [--force]
-```
-
-- **`--keep-volumes`** — keep the stack's data (plain `down`, no backup, no drop).
-- **`--force`** — override the guards below.
-
-## 3. Handle a guard block
-
-If the CLI reports **blocked** (the worktree has uncommitted changes, or unpushed
-commits that aren't yet merged into the base branch), **relay the reason and
-stop** — do not destroy unreviewed work. Offer the user `--force` (and suggest
-committing/pushing first). Only re-run with `--force` when the user explicitly
-asks. **A branch already merged into the base needs no `--force`** — the unpushed
-guard treats "landed on base" as safe, so a completed spec (post-`/spec-complete`
-integrate) tears down cleanly even with no remote.
-
-## 4. Execute the printed side effects
-
-When not blocked, run the printed commands **in order**, exactly as printed:
-
-1. **Backup** (only when a `docker.backupCommand` is configured and volumes are
-   being dropped) — writes a dump under `.spec-env/backups/` before anything is
-   destroyed.
-2. **`docker compose … down`** — with `--volumes` unless `--keep-volumes`.
-3. **`git worktree remove …`** — removes the sibling worktree.
-4. **`git branch -d <branch>`** — deletes the spec's branch (freed by the worktree
-   removal above). It's `-d` (merged-only), never `-D`: if it reports the branch
-   isn't fully merged, **relay that and stop** — don't `-D` it. That only happens
-   on a `--force` teardown of unmerged work; the user can delete it by hand if
-   they're sure.
-
-The slot is already freed by the CLI.
-
-## 5. Report
-
-Confirm what happened: worktree removed, branch deleted, containers down, volumes
-**dropped|kept**, slot freed, and the backup path (if any). If a `git branch -d`
-was refused (unmerged), say so. If the spec wasn't provisioned / was already torn
-down, the CLI reports a clean **no-op** — relay that; it's not an error.

package/assets/skills/spec-ready/SKILL.md

@@ -1,50 +0,0 @@
----
-name: spec-ready
-description: Mark a Draft spec as Ready — confirm it's groomed (no unresolved open questions, phases and per-phase tests defined, decisions captured) and flip its status to Ready so it's a candidate for /spec-go. Stays in specs/backlog/. Targets a spec by name (arg) or the spec in context. Use when the user says "/spec-ready", "this spec is ready", or "mark <spec> ready to start".
----
-
-# /spec-ready — promote a Draft spec to Ready
-
-A grooming gate between authoring (`/spec`, status `Draft`) and implementation
-(`/spec-go`, status `In Progress`). It does **not** move the spec — it stays in
-`specs/backlog/`; it only confirms quality and flips the status to `Ready` so
-you can see at a glance which backlog specs are good to start.
-
-## 1. Identify the target spec
-
-- Use the name/path argument if given, else the spec **in context**. If unclear,
-  ask which spec.
-- Locate the spec folder under `specs/backlog/`. Entry point is its
-  `00-overview.md`; phases are separate files (`01-<slug>.md`, `02-…`) listed in
-  its phase index (legacy specs may be a bare `<name>.md`).
-
-## 2. Check it's actually ready — don't rubber-stamp
-
-Review the spec against the readiness bar. If any of these fail, **stop and tell
-the user what's missing** rather than marking it Ready:
-
-- **Open questions resolved** — the `## Open questions` section is empty or
-  reads "None". Unresolved branches mean it isn't ready.
-- **Decisions captured** — the chosen solution and key trade-offs are recorded.
-- **Phased with clear tasks** — work is broken into phases, and **every phase in
-  the `00-overview.md` index has a matching phase file** (`0N-<slug>.md`) with
-  verb-first `- [ ]` tasks granular enough for one session. No index row without
-  a file, no orphan file without an index row.
-- **Tests baked into every phase** — each phase file ends with a
-  create-and-run-tests task (a phase isn't done until green).
-- **Concise and current** — no stale/contradictory sections.
-
-Offer to fix small gaps inline if the user wants; otherwise leave it `Draft`.
-
-## 3. Mark Ready
-
-- Set the **Status** header in the entry point:
-  `> **Status:** Ready (<YYYY-MM-DD>)`.
-- Append a **State log** row: `| <YYYY-MM-DD> | Ready | backlog | <git user.name> |`
-  (no folder change — Ready stays in `backlog`).
-- Optionally add a **Changelog** note if grooming changed anything substantive.
-
-## 4. Report
-
-Confirm it's Ready and note it stays in `backlog` until `/spec-go` picks it up.
-If you blocked it, list exactly what needs resolving first.