@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @skitterbyte/skitterspec-jira
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Spec-driven development for Claude Code, with **one-way Jira Cloud sync** — a
+superset of [`@skitterbyte/skitterspec`](https://www.npmjs.com/package/@skitterbyte/skitterspec):
+the base filesystem workflow plus `/spec-push` · `/spec-status` and the
+`spec-sync` CLI. The repo is canonical; Jira is a generated mirror.
+
+Install exactly one distribution — this, the base, or
+`@skitterbyte/skitterspec-linear` — never two:
+
+```
+npx @skitterbyte/skitterspec-jira init
+```
+
+## What the sync is
+
+- A spec is a Jira **issue**; each phase a **subtask**; tasks ride along as a
+  live ADF checklist (still a read-only mirror — the repo wins on every push).
+- **One-way**: nothing is read back into the repo. A description edited on Jira
+  is reported (`spec-sync status`) and replaced on the next push, loudly.
+- Descriptions are stored as ADF; the engine converts markdown at the adapter
+  boundary and verifies round-trips **by words, not bytes**.
+- Workflow moves happen by **transition** — an unreachable status refuses
+  loudly and names what is available; the engine never path-finds a workflow.
+
+## Setup
+
+`/spec-jira-setup` interviews you and writes `specs/.core/jira.config.json`
+(site URL, project key, issue/subtask types, bucket→status names). Credentials
+are an email + API token pair, kept out of the repo:
+
+```
+skitterspec-jira spec-sync credentials set
+```
+
+`skitterspec-jira spec-sync doctor --check-remote` reports readiness across
+every layer.
+
+Not yet shipped for Jira (the Linear superset has them): assignment/`/spec-claim`,
+`retarget`, `reattach`, `spec-sanitise`. Releases and deploys are the host
+project's to record on every provider: `spec-sync released <range> --json`
+lists a range's tickets for its CI to act on.
+
+This package's `bin/`, `src/` and `assets/` are composed at build time from the
+skitterspec monorepo — see the repo for sources and development.

package/assets/claude-md-section.md

@@ -0,0 +1,85 @@
+## Spec workflow
+
+Spec-driven development runs through the lifecycle **skills** — use them so
+structure and lifecycle stay consistent. The everyday loop is
+**`spec → start → next → commit → complete`**, with **`/spec-diff`** to read what
+a phase changed and `/spec-connect` when you want to test the spec in a browser.
+
+**Skills vs commands.** The lifecycle skills are read by Claude, which exercises
+judgment. `/spec-connect` and `/spec-live` are **slash commands** instead — each
+pre-executes one `spec-env` verb and relays it, so only you can run them; a
+skill that wants one will tell you to type it.
+
+**Seeing the work.** A phase is built in its own worktree, so `git diff` in your
+terminal answers about the base branch. **`/spec-diff`** renders that worktree's
+diff as a self-contained HTML page you open locally — or publish, and read on a
+phone. The diff never passes through the model, so the page costs no context
+tokens however large it is; the optional written review is the part that costs,
+and it is offered rather than assumed. `/spec-next` writes the page at the end of
+every phase.
+
+**Handing the review back.** The page takes marks: tick `✓ accept` per file as
+you read, note anything against a line or a whole file, answer the questions a
+written review asked — then **end it in a decision**. At the end of a phase the
+buttons are `✓ Commit`, `✓ Commit & Continue` (commit, then build the next
+phase), `↺ Request changes` and `… Discuss first`. A spec that has just been
+written gets `✓ Commit & Start` instead — the `commit-start` verdict, which is
+the `commit && /spec-start` you would otherwise type. A **served** page hands
+the pass to the engine, which **holds** it and shows a six-digit code. Committing
+is unavailable while a note is open — you asked for something, so it cannot also
+be fine — and it hands off to your own commit skill (`review.commitWith`,
+`/commit` by default) rather than a copy living here. Fixes come back as
+resolutions, so the next render shows each note struck through with what changed.
+An accept remembers the file's content, so it lapses by itself when that file
+changes again. The marks are information — nothing gates on them; the verdict is
+the one thing you choose, once.
+
+**A second opinion, when you want one** (`review.reviewers`, empty by default).
+Point it at a code reviewer that runs from your terminal — CodeRabbit's CLI has
+a free tier and `{ "use": "coderabbit" }` is the whole setup; anything printing
+[rdjsonl](https://github.com/reviewdog/reviewdog) works too — and its findings
+land on the page beside your own notes, each badged with the tool that found it
+and linked to the line it is about. `/spec-next` runs them once per phase;
+`/spec-diff --reviewers` is the mid-phase ask. **They never block a commit** —
+reply to one and your reply does, because then a person has asked for something.
+A reviewer that could not run says `did not run — <why>` rather than passing as
+clean, because on the page you commit from those two must not look alike.
+Adding one sends your diff to whatever the command talks to, which is why the
+list starts empty and `init` never writes one.
+
+**Above the verdicts sits one line that is not a verdict.** `▶ Put it live`
+commits the phase, checks the branch out where your dev server can see it, and
+hands you back the same page with the same options — so you can judge the change
+by *using* it, not only by reading it. It clears no gate: you have looked at it
+running and concluded nothing, so the phase still owes an answer.
+
+**Every render lists where the page can be read**, labelled, in a fixed order —
+`local`, `network`, `remote` — each either a URL or the one command that turns it
+on, plus a `live:` line saying whether the change is also running. `local` and
+`network` are two doors into one room: the same server and the same waiting
+verdict, so one wait covers both. `remote` is a published page, a second store —
+a verdict there needs `/spec-reviewed`, and it stays off until someone types
+**`/spec-remote-review`**, which toggles it. Publishing is permitted by that
+command, never performed by it: a published page is one this tooling cannot
+remove.
+
+**One ending.** Every spec skill finishes with the same block — a verdict
+(`✅` · `⚠️` · `❌` · `⏸`), then a table of the fields that skill declares,
+ending on the one thing to do next. A refusal emits it too, so "nothing
+happened" is reported rather than absent, and `Follow-ups` is always there
+because a recorded `none` is a decision. Skills stay quiet while they run. The
+shape lives in **`.claude/rules/spec-reports.md`**.
+
+The skill table, the spec type/folder conventions and the per-spec isolation
+model all live in **`.claude/rules/spec-planning.md`**, the canonical reference
+every spec skill points at. Tailor its per-phase test commands to this stack.
+
+**Release gating** *(only when `specs/.core/gating.config.json` exists)* — each
+spec records whether it ships behind a feature flag, as
+`> **Gating:** <flag name>` or `> **Gating:** none: <one-line reason>`. `/spec`,
+`/spec-bug` and `/spec-hotfix` ask; `/spec-review`, `/spec-start` and
+`/spec-complete` report a spec that has no answer, and never block over it.
+`skitterspec gating check` lists them and always exits 0. The point is that the
+question is **on the record**: a missing line is an oversight, a reason is a
+decision. Skitterspec never reads your flag system — it asks and cites the doc
+you point it at. Without that config, none of this appears.

package/assets/commands/allow-main.md

@@ -0,0 +1,33 @@
+---
+description: Allow writes on the base branch for this session — bare allows it with no reason, a reason records why, `off` clears it
+argument-hint: "[<reason> | off]"
+allowed-tools: Bash({{exec}} skitterspec spec-env main allow:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env main allow $ARGUMENTS`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+**Only you can run this, and that is the whole guard.** The main-guard hook
+refuses an `Edit` or a `Write` in the primary checkout while it sits on the base
+branch, and it names two exits: move the work with `/no-spec` or `/spec-start`,
+or have you lift the guard. Claude can take the first exit on its own and can
+never take the second — a guard the model can lift is decoration, which is the
+same line `/spec-reviewed` draws.
+
+**Give it a reason.** `/allow-main fixing the lockfile by hand` records why; bare
+records `none given`. The reason is the part a reviewer can argue with, exactly
+as with a `Gating:` header — and it is what you will read when you wonder later
+why the base branch has an uncommitted file on it.
+
+**It lapses with the session where it can.** The allow is recorded against this
+session, so it ends when the session does. Where the harness exposes no session
+id it degrades to a repo-wide allow that outlives the session and is cleared only
+by `/allow-main off`; the engine says which kind you got, so do not read a bare
+"allowed" as temporary.
+
+**It is machine-local and gitignored.** Unlike `/spec-remote-review`, this writes
+nothing anyone else pulls: it is your decision about your checkout, not the
+project's policy. The project-wide switch is `guards.mainIsLandingZone` in
+`specs/.core/env.config.json`, and turning that off is a different, committed
+decision.

package/assets/commands/spec-connect.md

@@ -0,0 +1,13 @@
+---
+description: Expose one spec's dev servers on the canonical localhost ports — bare uses the spec you are on, `main` hands them back
+argument-hint: "[<spec> | main]"
+allowed-tools: Bash({{exec}} skitterspec spec-env connect:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env connect $ARGUMENTS`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+Only if it reports a **canonical port is in use**: say that the main checkout's
+dev server still holds that port, and that stopping it and re-running is the fix
+(the proxy cannot share a port main is bound to).

package/assets/commands/spec-live.md

@@ -0,0 +1,14 @@
+---
+description: Put one spec live on the already-running dev server — bare takes the spec you are on, `<spec>` takes that one, `main` hands the instance back
+argument-hint: "[<spec> | main | status | release | abort]"
+allowed-tools: Bash({{exec}} skitterspec spec-env live:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env live $ARGUMENTS`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+The engine enforces every refusal itself and prints why — a hotfix, a stateful
+spec (`Stack: worktree + docker`), a branch touching migrations, a dirty tree, a
+rebase conflict, or another spec already holding the instance. Do not re-explain
+or work around any of them.

package/assets/commands/spec-remote-review.md

@@ -0,0 +1,37 @@
+---
+description: Permit or forbid publishing this spec's review for a reader off your network — bare toggles it, `on`/`off` set it explicitly
+argument-hint: "[on | off]"
+allowed-tools: Bash({{exec}} skitterspec spec-env review allow remote:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env review allow remote --set "$ARGUMENTS"`
+
+Relay the engine output above verbatim. Add nothing to it.
+
+**Then one thing, and only when the engine asked for it.** Where the output
+carries a `review:` and a `publish:` line, typing this command **is** the ask
+to publish that page: the banner named this command beside a review the reader
+could not reach, so the link is what they are waiting for. Publish it exactly
+as `/spec-diff` §6 describes (run the `publish:` command, publish the copy it
+names with a store, write the URL file), then re-emit the review banner with
+all three tiers, `remote` now carrying the URL. A wait already running keeps
+running; do not restart it or the server. If the harness refuses the publish,
+say so in one line and keep the banner as it was, because local and network
+still work.
+
+With no `publish:` line, run nothing else. Nothing has a page to publish, or
+the tier was turned off.
+
+**Bare toggles.** That is the common case: you are looking at a render whose
+`remote:` line says which way it currently is, and what you want is the other
+one. `on` and `off` are there for when you are not looking at it.
+
+**It is per spec.** The engine resolves the spec from the worktree you are
+standing in and records the permission in the gitignored review store, so
+the base branch is untouched and no other spec may publish because of it.
+`skitterspec spec-env review allow remote --project` is the committed,
+every-spec form, for a team that wants it.
+
+**A published page is one skitterspec cannot delete**, and a verdict pressed
+on one needs `/spec-reviewed`, because nothing pushes from an artifact's store
+into a conversation.

package/assets/commands/spec-skip.md

@@ -0,0 +1,24 @@
+---
+description: Move on from a phase without a verdict, with the reason on the record — clears the review gate
+argument-hint: "\"<reason>\""
+allowed-tools: Bash({{exec}} skitterspec spec-env review skip:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env review skip "$ARGUMENTS"`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+**It refuses with no reason, and that refusal is the feature.** A skip with no
+reason is indistinguishable from nobody having looked — where
+`none: additive, nothing to revert` is a decision a reviewer can argue with. If
+the engine asked for a reason, relay that and stop; do not supply one on the
+operator's behalf.
+
+**It is one of exactly two exits**, and the other is a committing verdict on the
+page. Nothing else discharges a phase's obligation — not a mid-run `Continue`,
+not an action, not a render.
+
+**Only you can run it.** Like `/allow-main`, this lifts a guard aimed at Claude,
+so Claude must not be able to lift it. `/spec-connect` and `/spec-live` are
+user-only for the milder reason that there is no judgement to apply; this one is
+user-only because of who the guard is for.

package/assets/core/SETUP.md

@@ -0,0 +1,192 @@
+# Setting up Jira sync (one-way)
+
+A start-to-finish guide to getting `/spec-status` and `/spec-push` working
+against a real Jira Cloud site. Sync is **one-way**: the repo is the source of
+truth and the linked Jira **issue** is a **generated mirror** — content is
+pushed up, never read back or merged. A spec is a Jira issue and each phase a
+**subtask**, with the phase's tasks mirrored into that subtask's description as
+a live (but read-only — the repo wins) ADF checklist. Covers the **Jira side**
+(credentials, finding your project) that the config reference
+(`jira.config.md`) assumes you already have.
+
+> The whole feature is **opt-in**: until `specs/.core/jira.config.json` exists,
+> everything below is inert and the package behaves exactly like the base
+> `@skitterbyte/skitterspec`.
+
+Two things about Jira Cloud shape everything below:
+
+- **Descriptions are ADF** (Atlassian Document Format), not markdown. The
+  adapter converts markdown at the boundary in both directions, and every
+  verification compares **words, not bytes**.
+- **Statuses move by workflow transition** — there is no "set status". The
+  engine resolves the transition that lands on the configured status and
+  refuses loudly (naming what IS available) when none does. It never
+  path-finds a workflow.
+
+---
+
+## 1. Install the package
+
+Install the Jira superset (or, if you already run the base or the Linear
+superset, switch — every distribution contains the entire base, so install
+exactly one):
+
+```sh
+npx @skitterbyte/skitterspec-jira init
+```
+
+## 2. Credentials — an email + API-token pair
+
+Jira Cloud authenticates REST calls with basic auth: your Atlassian account
+email plus an API token. Create the token at
+<https://id.atlassian.com/manage-profile/security/api-tokens>.
+
+Store the pair in the user-level credentials store (outside every repo,
+`0600`), **in your own terminal — not through an assistant**:
+
+```sh
+pnpm exec skitterspec-jira spec-sync credentials set --site-url https://<site>.atlassian.net
+# Jira account email for https://<site>.atlassian.net: you@example.com
+# Jira API token for you@example.com (hidden): ●●●●●●●●
+```
+
+(`--site-url` keys the store entry before the repo has a config; once
+`jira.config.json` exists it can be omitted.)
+
+Or export `JIRA_EMAIL` and `JIRA_API_TOKEN` (both — an email without a token
+authenticates nothing). The environment wins over the store.
+
+> **MCP alternative:** with no credentials at all, the sync skills fall back to
+> Atlassian's official remote MCP server — `claude mcp add --transport http
+> atlassian https://mcp.atlassian.com/v1/sse`, then authenticate via `/mcp`.
+> The engine itself never calls MCP tools; the skills fetch and hand results to
+> the engine as files (`--workspace-states`, `--stored`, `--text`).
+
+## 3. Configure — run `/spec-jira-setup`
+
+With credentials in place, let the skill interview you:
+
+```
+/spec-jira-setup
+```
+
+It asks for the site URL, the project key, the issue and subtask type names,
+and the four bucket→status names — validating them against the project's real
+statuses (`spec-sync states`) — then writes `specs/.core/jira.config.json`
+via `spec-sync init-config`. By hand instead:
+
+```sh
+pnpm exec skitterspec-jira spec-sync init-config \
+  --site-url https://your-site.atlassian.net \
+  --project-key PROJ \
+  --state complete=Done
+```
+
+**Commit the file it writes.** Spec worktrees fork from commits, so an
+uncommitted `jira.config.json` is invisible inside every worktree — which is
+where the sync skills actually run — and sync reports itself off there.
+
+`jira.config.md` (installed beside this file) is the full field reference.
+Two defaults worth knowing: the issue type is `Task` and the subtask type
+`Subtask` — site admins rename these, so check yours; and `cancelled` maps to
+`Done` because default Jira workflows carry no Cancelled status.
+
+**Map buckets to work statuses, not deployment stages.** The buckets mirror
+the repo's work lifecycle, so To Do / In Progress / Done translate honestly —
+On Test / On Live do not: a finished phase would show as deployed before
+anything was released. A workflow that encodes a pipeline has standard outs
+(a separate subtask workflow, fix versions, the deployments panel) —
+`jira.config.md` → **Choosing your status map** carries the reasoning.
+
+## 4. Check — `spec-sync doctor`
+
+```sh
+pnpm exec skitterspec-jira spec-sync doctor --check-remote
+```
+
+Every row reports `ok`, or names the exact command that fixes it. `missing`
+is an opt-in not taken (fine); `broken` is configured-but-wrong (exit 1).
+`--check-remote` additionally proves the credentials reach the site and that
+every configured status exists in the project's workflows.
+
+## 5. Push a spec
+
+`/spec-push <spec>` computes the plan, applies it, stamps the returned keys
+into the spec's frontmatter (`jira_identifier` / `jira_url` /
+`jira_issue_id`), verifies the round-trip by words, and records the snapshot
+later pushes diff against. From then on the lifecycle skills keep the
+mirror fresh on their own.
+
+---
+
+## Release smoke checklist
+
+Re-runnable, against a real Jira Cloud site — a throwaway project is ideal.
+Run before cutting a release that touches the adapter, the ADF layer or the
+apply path. `states.json` below is the project's status names.
+
+1. **Doctor** — every row ok:
+
+   ```sh
+   pnpm exec skitterspec-jira spec-sync doctor --check-remote
+   ```
+
+2. **States** — the project's statuses list:
+
+   ```sh
+   pnpm exec skitterspec-jira spec-sync states --json > states.json
+   ```
+
+3. **Mint** — on a test spec with at least one phase and a task checklist:
+
+   ```sh
+   pnpm exec skitterspec-jira spec-sync plan <spec> --workspace-states states.json --json > plan.json
+   pnpm exec skitterspec-jira spec-sync apply <spec> --plan plan.json
+   ```
+
+   In Jira: the issue and its subtasks exist, statuses match the buckets, and
+   the task checklist renders as live checkboxes. (If a surface renders the
+   task list as plain text, the renderer has a `taskLists: false` fallback —
+   file it.)
+
+4. **Update** — edit the spec's prose and a phase's status, then plan + apply
+   again: the description is replaced and the subtask's status transitions.
+
+5. **Adopt + preserve** — hand-create an issue with a description, stamp it
+   onto a spec, and preserve before the linking push:
+
+   ```sh
+   pnpm exec skitterspec-jira spec-sync stamp <spec> --issue PROJ-123
+   pnpm exec skitterspec-jira spec-sync preserve <spec>
+   ```
+
+   The original description appears as a comment headed **Original report**;
+   a second `preserve` reports "already preserved".
+
+6. **Verify** — save a read-back (`{ "issue": "<description text>",
+   "subIssues": { "<ref>": "<text>" } }`; a ref is the phase file's basename
+   without `.md`, e.g. `01-date-logic` — keyed with the extension it reports
+   every sub-issue as a stale ref) and:
+
+   ```sh
+   pnpm exec skitterspec-jira spec-sync verify <spec> --stored readback.json
+   ```
+
+   "round-tripped intact", exit 0.
+
+7. **Released** — over a range with `Refs:` trailers:
+
+   ```sh
+   pnpm exec skitterspec-jira spec-sync released <tag>..HEAD
+   ```
+
+   Tickets counted, unreferenced commits reported, bookkeeping ignored.
+
+8. **Drift** — edit the issue's description **in Jira**, fetch the issue JSON,
+   and:
+
+   ```sh
+   pnpm exec skitterspec-jira spec-sync status <spec> --remote issue.json
+   ```
+
+   The edit is reported; the next apply replaces it and says so loudly.

package/assets/core/env.config.json.example

@@ -0,0 +1,56 @@
+{
+  "mode": "worktree",
+  "worktree": {
+    "root": "../{repo}-wt",
+    "folderPattern": "{slug}"
+  },
+  "docker": {
+    "enabled": true,
+    "composeFile": "docker-compose.yml",
+    "projectNamePattern": "{repoSlug}_{slug}",
+    "portBase": 3000,
+    "portsPerSpec": 10,
+    "envFile": ".env",
+    "backupCommand": ""
+  },
+  "seedFiles": {
+    "mode": "symlink",
+    "files": [
+      ".env"
+    ]
+  },
+  "setup": [],
+  "dev": [],
+  "proxy": {
+    "enabled": true,
+    "host": "127.0.0.1"
+  },
+  "registry": ".spec-env/registry.json",
+  "branch": {
+    "pattern": "{type}/{slug}",
+    "identifierField": "jira_identifier"
+  },
+  "spec": {
+    "companionPaths": [
+      "specs/.core/jira-base/{identifier}.base.json"
+    ]
+  },
+  "baseBranch": "",
+  "guards": {
+    "refuseTeardownIfDirty": true,
+    "refuseTeardownIfUnpushed": true
+  },
+  "review": {
+    "reader": "detect",
+    "servePort": "auto",
+    "serve": "always",
+    "allowNetwork": true,
+    "allowRemote": false,
+    "commitWith": "/commit",
+    "required": true,
+    "reviewers": []
+  },
+  "live": {
+    "migrations": []
+  }
+}