@skitterbyte/skitterspec-jira 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,220 @@
+---
+name: spec-sync
+description: Run the repo-wide spec-sync operations against Jira — what is linked, the project's statuses, read-back verification, manual stamping, and bulk apply. Run it bare for the repo-wide overview. Defers to /spec-push and /spec-status for per-spec work. Opt-in — needs specs/.core/jira.config.json. Use when the user says "/spec-sync", "run spec-sync", "what's linked to Jira", "which statuses does the project have", or "mirror the whole backlog".
+disable-model-invocation: true
+---
+
+# /spec-sync — the repo-wide Jira sync operations
+
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
+`/spec-push` and `/spec-status` cover **one spec**. This skill covers everything
+**repo-wide**, and is the answer to a bare "run spec-sync" — which is not itself
+a command.
+
+**Opt-in**: only runs when `specs/.core/jira.config.json` exists. If absent,
+tell the user how to enable Jira sync and stop.
+
+## The invocation — always state it
+
+`spec-sync` is a subcommand of a binary that is a **local devDependency**, so it
+is never on `PATH`. Typing `spec-sync` gives `command not found`, which reads as
+a broken install rather than a wrong invocation. Always run it — and always show
+the user you ran it — in full:
+
+```
+pnpm exec skitterspec-jira spec-sync <subcommand> [args]
+```
+
+In a project that installs the Jira superset the binary is
+`skitterspec-jira` (it also answers to `skitterspec`). Never print a bare
+`spec-sync …` as if the user could type it.
+
+## 1. Route the ask
+
+| The user asks | Run |
+|---------------|-----|
+| bare `/spec-sync`, "what's linked?", "how much is mirrored?" | `linked` |
+| "what statuses does the project have?" | `states` |
+| "what specs are there?", "what's in the backlog?" | `list` — or hand to `/spec-list` |
+| "did the mirror survive the push?" | `verify <spec> --stored <file>` |
+| "link this spec to PROJ-1 by hand" | `stamp <spec> --issue PROJ-1` |
+| "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
+| "what ticket am I on?", writing a commit | `ref` |
+| "what shipped in this release?", "which tickets does CI mark deployed?" | `released` — `--json` for a script; recording deploys is the project's own |
+| "is any of this wired up?", "why isn't sync working?" | `doctor` — scaffold, isolation, tracker and credentials in one |
+| "set my Jira credentials", "am I authenticated?" | `credentials <status\|set\|unset>` |
+| push one spec, or "what would push?" | **defer** — see below |
+
+The Linear provider's `retarget`, `reattach`, `stage`, `whoami`, `users`,
+`assign` and `sanitise` are **not yet shipped for the Jira provider** — say so
+when one is asked for, rather than improvising an equivalent.
+
+**With no argument, run `linked`.** It is the repo-wide overview, it is
+read-only, and it is what a bare "run spec-sync" means.
+
+**When the ask is genuinely ambiguous between a read and a write — ask.**
+"Sync the backlog" could mean `linked` (show me) or `apply --all backlog`
+(write dozens of issues). Never resolve that guess in favour of the write.
+
+## 2. Defer, don't duplicate
+
+Two front doors to one write path is worse than none:
+
+- **Push one spec** → `/spec-push`. It owns the transport choice, the
+  status-name gate, the plan, the apply, the stamping and the snapshot.
+- **Per-spec status** ("is this spec in sync?", "what would push?") →
+  `/spec-status`.
+
+Say which skill you're handing to and stop; don't reimplement either.
+
+## 3. The read-only subcommands
+
+```
+pnpm exec skitterspec-jira spec-sync linked [--json]
+pnpm exec skitterspec-jira spec-sync states [--via api|mcp] [--json]
+```
+
+- **`linked`** is offline: which specs carry a `jira_identifier`, their bucket,
+  and an `N/M linked` total. Relay it, and when specs in `in-progress` have no
+  issue, say so — those are the ones a push would mint.
+- **`states`** reaches the project. It also reports the **transport** (`api`
+  when credentials resolve, else `mcp`), which is the honest way to answer "how
+  is this talking to Jira?". Its non-JSON output ends with the **bucket map** —
+  every lifecycle bucket against the project's real statuses, a verdict per
+  row — which is the answer to relay when the user asks whether the mapping is
+  right.
+- **`list`** is the read side of the mirror: every spec issue Jira holds,
+  joined to the local spec folder that owns it. Unlike `linked`, it asks JIRA
+  what exists rather than the repo — which is the only way to see a spec started
+  on a branch this checkout has not got. Scope is the live statuses by default
+  (`--all`, or `--state <name>`). **`/spec-list` is the front door** — hand over
+  to it for anything beyond a bare listing; it carries the MCP path and the
+  offline degradation.
+
+## 4. `verify` — check what the tracker actually stored
+
+```
+pnpm exec skitterspec-jira spec-sync verify <spec> --stored <file>
+```
+
+`--stored` is **what Jira currently holds**, read back over MCP:
+
+```json
+{ "issue": "…", "subIssues": { "01-engine": "…" } }
+```
+
+**It is not a `jira-base/*.base.json` snapshot.** That file holds content
+*hashes* keyed by identifier; comparing one against a description reports
+enormous losses on a perfectly intact mirror. The engine refuses a snapshot
+outright — if you see that refusal, you passed the wrong file, not found a bug.
+
+Warns, never fails. The repo is the source of truth; a mangled mirror is fixed
+by pushing again. Jira stores descriptions as ADF and the adapter converts
+markdown at the boundary, so the comparison is words, not bytes.
+
+## 5. `stamp` — the manual escape hatch
+
+```
+pnpm exec skitterspec-jira spec-sync stamp <spec> --issue PROJ-1 [--url URL] [--sub <ref>=PROJ-2 …]
+```
+
+Writes the keys into the spec's frontmatter without touching Jira. For adopting
+an issue created by hand, or repairing a stamp — not the normal path, which is
+`/spec-push`. A wrong key here makes the next push see an **unlinked** spec and
+mint a duplicate, so read the values back to the user before writing.
+
+## 6. `apply --all <bucket>` — bulk, and the one with real blast radius
+
+```
+pnpm exec skitterspec-jira spec-sync apply --all <bucket> [--via api|mcp] [--json]
+```
+
+**Confirm before running, and state creates and updates separately.** They are
+not the same risk:
+
+- an **update** refreshes a mirror that already exists;
+- a **create** mints new issues and subtasks in someone's shared tracker.
+
+A repo adopting Jira reports "N to create" for every unlinked spec, so an
+unconsidered `--all` can mint dozens of subtasks. Get the counts first — run
+`linked` to see what is unlinked, or `spec-sync plan <spec>` per spec for exact
+numbers — then show the user something like:
+
+```
+apply --all backlog would:
+  create  12 issue(s) + 34 subtask(s)   ← new objects in Jira
+  update   3 issue(s) +  5 subtask(s)   ← refresh existing mirrors
+```
+
+Only run it on an explicit yes. It is resumable: every key is stamped the moment
+its object exists, so an interrupted run continues rather than duplicating.
+
+`--all` refuses over MCP by design — bulk goes through the API path.
+
+## 7. `ref` and `released` — tickets in commits
+
+```
+pnpm exec skitterspec-jira spec-sync ref [--json]
+pnpm exec skitterspec-jira spec-sync released [<range>] [--json]
+```
+
+`ref` prints the ticket for the branch you are on, so a commit can carry
+`Refs: <PROJ-N>` — see `.claude/rules/commit-trailers.md`.
+**Off a spec branch, or on a spec that is not linked, it prints nothing and exits non-zero.**
+That is the correct answer, not an error to work around: do not invent a ref,
+and never write `Refs: none`.
+
+`released` reports the tickets in a commit range — by default since the most
+recent tag, and it always prints the range it chose so a wrong default is
+visible. It is **read-only**: it does not move anything in Jira. Each ticket
+row names the `spec` and `url` behind it (`null` when no spec linked the ref),
+so `--json` is what a project's CI pipes into its own tooling to record a
+release or a deploy. Recording those is the project's job, not skitterspec's.
+
+Relay the **unreferenced count** even when it is zero. A chore commit
+legitimately carries no ticket and a *missed* trailer looks identical, so
+omitting the number reads as "everything is accounted for" when it may not be.
+
+**Bookkeeping commits are excluded.** A spec's `chore(spec): complete <name>`
+commit carries the same ref as the code it describes but lands *after* the tag
+that shipped it, so counting it would put the ticket in two consecutive releases.
+A commit whose changed paths are **all** under `release.ignorePaths` (default
+`specs/`) contributes nothing; one that touches an ignored path *and* a source
+file still counts. Relay the **ignored count** whenever it is non-zero — that is
+the report saying which commits it set aside.
+
+## 8. Report
+
+Relay the engine's output **above the block**, and name the subcommand you ran
+**in full**, so the user can re-run it themselves.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the subcommand did what it says.
+- `⚠️` — it ran, with something worth knowing — a partial result, a warning it
+  printed, a degradation it fell back to.
+- `❌` — it wrote some objects and failed on another. Say what exists now.
+- `⏸` — it refused: no config, an unvalidated status list, a bad argument.
+  Nothing was written.
+
+**A branch-local bucket is the normal case, never the caveat.** `linked`
+reads the checkout it runs in, and an in-flight spec's move to
+`in-progress` lives on its own unlanded branch — so from the primary
+checkout the spec still reads `backlog` while the tracker (pushed from
+the worktree) is ahead. That is worktree mode working as designed:
+report it `✅` with the fact in `Notes`. Spending `⚠️` on the normal
+case is how the verdict stops meaning anything — the same argument
+`spec-reports.md` makes for `Untouched`.
+
+**Fields:** `Tracker` · `Notes` · `Follow-ups` · `Next`
+
+`Tracker` says what changed in Jira **and that the repo is unchanged** — it is
+the source of truth either way, and a report that omits the second half reads as
+though a sync had edited the repo.

package/assets/skills/spec-to-main/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: spec-to-main
+description: Land an in-progress spec's branch onto main WITHOUT finishing it — rebase + fast-forward so the work reaches main (to run it in CI / a shared test env), while the worktree stays and the spec stays In Progress. Repeatable — land again as you commit more. Targets a spec by name (arg) or the spec in context. Use when the user says "/spec-to-main", "land this on main but keep going", "I need this on main to run tests before finishing", or "merge to main without completing the spec".
+disable-model-invocation: true
+---
+
+# /spec-to-main — land the branch on main, keep the spec open
+
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
+The **intermediate** landing. `/spec-complete` also lands the branch, but then
+verifies every phase, flips the status to Complete, `git mv`s the spec to
+`complete/`, and tears the environment down.
+**`/spec-to-main` stops after the land**: the worktree stays, the spec stays
+`In Progress`, and you can land again as you add commits.
+
+Use it when a later phase can only be done *after* the current work is on `main` —
+e.g. it needs to run in CI, a deploy pipeline, or a shared test environment that
+builds from `main`. Land what you have, run that step, then come back and finish
+the remaining phases with `/spec-next` and eventually `/spec-complete`.
+
+It reuses the **same engine** as `/spec-complete`'s landing (`spec-env integrate`
+— rebase + fast-forward), so it produces identical linear history. Because a
+fast-forward leaves `base == branch`, the operation is
+**idempotent and repeatable**: new commits put the branch ahead of base again,
+and you can run `/spec-to-main` as many times as you like.
+
+## 0. Preconditions — when this applies
+
+- **Isolation must be on** (`specs/.core/env.config.json` exists **and** the spec
+  was provisioned by `/spec-start` — a worktree, or its branch in the checkout under
+  `mode: checkout`). If isolation is absent, there is nothing to land — the spec
+  is authored directly on `main` already. Say so and stop. `spec-env integrate`
+  reads `mode` and emits the matching plan; in checkout mode it rebases in place,
+  switches to base and fast-forwards, all in the one repo.
+- **Feature / Bug specs only.** A **Hotfix** (`Type: Hotfix`) is built on a
+  release *tag* and cannot fast-forward onto `main` — refuse it and point the user
+  at `/spec-complete` (it lands a hotfix via tag + cherry-pick). Check the header
+  `> **Type:**` before proceeding.
+
+## 1. Identify the target spec
+
+- Use the name/path argument if given, else the spec **in context**. If unclear,
+  ask which spec.
+- Locate its folder under `specs/in-progress/`. Entry point is `00-overview.md`;
+  confirm `> **Status:**` is `In Progress` and `> **Type:**` is `Feature` or
+  `Bug`.
+
+## 2. Require a clean worktree
+
+The land rebases the branch — it refuses a dirty tree. If the worktree has
+uncommitted changes, offer `/commit` and **stop**; don't auto-commit.
+
+**If the spec is live** (you took the running instance with `/spec-live`):
+`integrate` is live-aware — it ends the live session first (releases the branch
+back to base, re-isolates it into its worktree, clears the receipt), then prints
+the landing plan. Commit any live fixes to the branch first; it refuses if the
+primary checkout is dirty, or if a *different* spec holds it (release that one with
+`/spec-live main`, which the user types).
+
+## 3. Tests must be green before landing
+
+Don't push red to `main`. Run the project's typecheck and test commands
+**in the worktree**; the suite must be **green**. For a **Bug** spec, confirm
+the originally-failing test now passes. If anything is red, stop and report —
+landing broken code onto `main` defeats the purpose.
+
+(Note this is the *worktree* suite. The whole point of this skill is often to run
+a *further* check that only exists on `main` / in CI — that one runs **after** the
+land, in step 5.)
+
+## 4. Land — rebase + fast-forward
+
+Run `skitterspec spec-env integrate <name>` and run the printed commands
+**in order**:
+
+- `git -C <worktree> rebase <base>` — replay the branch onto base.
+- `git -C <mainRepoPath> merge --ff-only <branch>` — fast-forward base.
+
+On a **rebase conflict** (non-zero exit), run `git -C <worktree> rebase --abort`,
+relay the conflict, and **stop** — leave the resolution to the user; change
+nothing else.
+
+On a **no-op** ("already landed on `<base>` — nothing to integrate"), just say so
+and continue — the branch has no commits base doesn't already have.
+
+**Then run the after-land commands.** Where the plan ends with a
+`then, in the primary checkout (<path>), run:` section — the project's
+`afterLand`, such as a data migration — run those commands in that directory,
+in order, after the fast-forward and **before** the re-test below, which may
+need them. Run only the lines under that heading; a
+`skipped (nothing in the land matched):` block lists conditional entries this
+land did not need, and is information, never commands. Run them on the no-op too: the engine prints them there because a
+land made elsewhere leaves them pending here.
+**Stop at the first non-zero exit**, and carry on with §5: a failure makes the run `⚠️`, naming the command
+that failed and the ones that did not run, and it **never undoes the land**.
+No section, nothing to run, and nothing to say about it.
+
+## 5. Re-test on base, then report
+
+- Run the project's test command **from the primary checkout** — base must be
+  **green** after the fast-forward.
+- Add a **Changelog** entry to `00-overview.md` recording the intermediate land
+  and *why*, e.g.
+  `- <YYYY-MM-DD> — Landed intermediate work onto <base> to <run CI / deploy to
+  test env / …>; spec stays In Progress.`
+- Do **NOT**: add a State-log row (status doesn't change), flip any phase/status
+  to Complete, `git mv` the spec, or tear down the worktree/stack.
+  **The spec stays `In Progress` and the worktree stays put.**
+- It **never pushes** — say the user can `git push` the base branch themselves to
+  trigger CI / the shared env.
+- `Next` points the way forward: `/spec-next` to continue the remaining phases
+  (you'll keep committing on the same branch and can `/spec-to-main` again), and
+  `/spec-complete` when every phase is genuinely done — it will land the final
+  commits, finalise, and tear down.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the branch is on the base and the base is green.
+- `⚠️` — landed, with something worth knowing — an after-land command that
+  failed, for one.
+- `❌` — the rebase conflicted, or the base went red after the fast-forward.
+  Quote it; the repo is mid-something and that is what the reader needs.
+- `⏸` — a dirty worktree, red tests, or no spec to land. Nothing moved.
+
+**Fields:** `Branch` · `Tests` · `Notes` · `Landed` · `Follow-ups` · `Next`
+
+`Notes` carries the after-land commands §4 ran, and where, and any it
+skipped because the land matched no `when` — or the one that failed and the ones that did not run. Nothing about it when none are
+configured.
+
+**No `Spec` field, deliberately.** This skill changes no status and moves no
+folder, and a `Spec` line here would read as though it had. The spec stays
+`In Progress` and the worktree stays standing — if that needs saying, the
+verdict clause says it.

package/bin/skitterspec-jira.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+'use strict'
+
+// The Jira superset's entry point: the base CLI plus this provider's commands.
+//
+// In the PUBLISHED distribution, bin/src/assets are composed at build time and
+// never committed — so a missing src/ means someone is running from a raw
+// checkout of the dist package, which has nothing to run. Inline rather than
+// shared: a helper would have to live in src/, which is exactly what may be
+// missing. In the workspace source package src/ always exists, so this is
+// inert there.
+const { existsSync } = require('node:fs')
+const { join } = require('node:path')
+if (!existsSync(join(__dirname, '..', 'src'))) {
+  console.error(
+    'skitterspec-jira: no build output — this package\'s bin/src/assets are composed, not committed.\n' +
+      '  run "npm run build" in the skitterspec repo, then try again.',
+  )
+  process.exit(1)
+}
+
+const { run, HELP } = require('../src/cli.js')
+
+// The provider's isolation defaults, registered beneath the project's own
+// env.config.json so `spec-env stage` claims this provider's snapshot sidecar
+// without a hand edit (see common src/env/config.js, setProviderEnvDefaults).
+require('../src/env/config.js').setProviderEnvDefaults(
+  require('../src/vendor/jira/config.js').ENV_CONFIG_DEFAULTS,
+)
+const {
+  PROVIDER_COMMANDS,
+  providerHelpSection,
+} = require('../src/vendor/jira/commands.js')
+
+async function main(argv) {
+  const [cmd, ...rest] = argv
+
+  // A source package HAS a runnable bin and src, but its assets/ is
+  // PRE-composition (seam markers still literal). Installing from it would
+  // write those markers into the user's skills — refuse before any install
+  // command runs.
+  if (cmd === 'init' || cmd === 'update') {
+    require('../src/init.js').assertComposedAssets()
+  }
+
+  // Base help + what this distribution adds. Matched on the COMMAND SLOT only,
+  // never the whole argv: `spec-sync --help` must reach that command's own
+  // help, not be swallowed by the top-level one.
+  if (!cmd || cmd === '--help' || cmd === '-h') {
+    process.stdout.write(`${HELP}\n${providerHelpSection()}`)
+    return
+  }
+
+  const provider = PROVIDER_COMMANDS[cmd]
+  if (provider) {
+    // Propagate the exit code: a refused stamp or a failed state check must
+    // not look successful to a caller checking $?.
+    process.exitCode = await provider.run(rest)
+    return
+  }
+
+  await run(argv)
+}
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(`skitterspec-jira: ${err.message}`)
+  process.exit(1)
+})

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@skitterbyte/skitterspec-jira",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.0",
+  "description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "spec-driven-development",
+    "sdd",
+    "skills",
+    "scaffold",
+    "jira"
+  ],
+  "license": "MIT",
+  "author": "Reuben Greaves",
+  "type": "commonjs",
+  "bin": {
+    "skitterspec-jira": "bin/skitterspec-jira.js",
+    "skitterspec": "bin/skitterspec-jira.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "assets",
+    "MIGRATION.md"
+  ],
+  "engines": {
+    "node": ">=22.13"
+  },
+  "dependencies": {
+    "prompts": "^2.4.2"
+  },
+  "scripts": {
+    "prepare": "node ../../scripts/build-dist.js skitterspec-jira",
+    "prepack": "node ../../scripts/build-dist.js skitterspec-jira"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SkitterByte/skitterspec.git",
+    "directory": "packages/skitterspec-jira"
+  }
+}