Ticket to Branch: A Claude Code Skill Pipeline from Jira Ticket to Squash-Merged PR

---
name: ticket-intake
description: Turn a Jira ticket into an understanding brief for an unfamiliar codebase. Use when starting work on a Jira key like PROJ-123.
disable-model-invocation: true
argument-hint: "<JIRA-KEY>"
allowed-tools: Bash(bash *fetch-ticket.sh*)
---
# Ticket intake

Ticket key: $0. It must look like PROJ-123. If it is missing or malformed, stop and ask.

## Ticket (fetched before you started)
!`bash "${CLAUDE_SKILL_DIR}/fetch-ticket.sh" "$0"`

If the block above starts with NO_TICKET or BAD_KEY, ask the user to paste the
ticket (summary, description, acceptance criteria, important comments). Never guess it.

## Steps
1. Size it. XS: one-line fix. S: 1-3 files, under a day, no open decisions.
   M: several files or at least one real decision. L: crosses modules, changes
   a schema or public API, or will be over ~400 changed lines.
2. Branch: git fetch origin, then git switch -c feat/$0-<short-slug> origin/main
   (use the team's prefix if CLAUDE.md names one). If a branch for $0 already
   exists, switch to it instead. Never work on main or master.
3. Notes folder: docs/tickets/$0-<short-slug>/. Add the line docs/tickets/ to
   .git/info/exclude if it is not there. Save the ticket text as ticket.md.
   Never edit the Jira issue in this skill.
4. Fast check: find the quickest command that typechecks, lints and runs the
   tests for one area (package.json scripts, Makefile, CI config, README).
   Write it as one line to fastcheck in the notes folder and run it once.
   Note whether the baseline is green.
5. XS or S: write brief.md with Task, Files, Existing tests (names and how to
   run them) and Done when, in about 10 lines. STOP and suggest /build-slice.
6. M or L: read CLAUDE.md, CONTEXT.md and docs/adr/ if they exist.
7. Write 5-10 research questions about the code ("where is X computed?",
   "what calls Y?", "which tests cover Z?"). Launch 2-3 Explore subagents in
   parallel and give them ONLY the questions, not the ticket. They return facts
   with file:line and no proposals.
8. Run git log --oneline -15 on the 3-5 main files. Summarise how the area
   changed recently and which commits matter.
9. If the fetch above printed JIRA_OK, run
   bash "${CLAUDE_SKILL_DIR}/fetch-ticket.sh" --search "<2-3 keywords>"
   and look for duplicates or earlier rejected attempts.
10. Write brief.md:
    - Task in plain words (2-4 lines). Acceptance criteria exactly as Jira states them.
    - Code map: entry points, files likely touched, patterns to copy (file:line).
    - Current behaviour, and the EXISTING TESTS that cover it (names + run command).
    - Fast check command and whether the baseline is green.
    - Risks and unknowns. Size (XS/S/M/L) and why.
    - Open questions, in three groups:
      FACTS: answered by the research, each with file:line.
      DECISIONS: need the user; each with 2-3 options and your recommendation.
      PO QUESTIONS: only the ticket author can answer.
11. STOP. Show a summary of at most 15 lines and ask: "Is this the task?" (G1)

#!/usr/bin/env bash
# Prints a Jira ticket for /ticket-intake. Always exits 0 so the skill still loads.
#
# Usage: fetch-ticket.sh PROJ-123
#        fetch-ticket.sh --search "two or three keywords"
#
# Optional setup, once: put these lines in ~/.jira-env and run chmod 600 ~/.jira-env
#   JIRA_BASE_URL=https://yourcompany.atlassian.net
#   JIRA_EMAIL=you@company.com          # Jira Cloud
#   JIRA_API_TOKEN=...                  # Cloud: id.atlassian.com > Security > API tokens
#   JIRA_PAT=...                        # Jira Server / Data Center, instead of the two above
#   JIRA_AC_FIELD=customfield_10042     # only if acceptance criteria live in a custom field
# Without it, paste the ticket into docs/tickets/<KEY>-<slug>/ticket.md and this script prints that.

[ -f "$HOME/.jira-env" ] && . "$HOME/.jira-env"

# The token goes to curl on stdin (-H @-), so it never shows up in the process list.
auth_header() {
  if [ -n "${JIRA_PAT:-}" ]; then
    printf 'Authorization: Bearer %s\n' "$JIRA_PAT"
  else
    printf 'Authorization: Basic %s\n' "$(printf '%s:%s' "${JIRA_EMAIL:-}" "${JIRA_API_TOKEN:-}" | base64 | tr -d '\n')"
  fi
}

if [ "${1:-}" = "--search" ]; then
  [ -n "${JIRA_BASE_URL:-}" ] || { echo "NO_JIRA: no ~/.jira-env, so search Jira by hand for duplicates."; exit 0; }
  # Jira Cloud removed /rest/api/2/search; Server/Data Center still uses it.
  if [ -n "${JIRA_PAT:-}" ]; then path=/rest/api/2/search; else path=/rest/api/3/search/jql; fi
  auth_header | curl -sfG --max-time 20 -H @- -H 'Accept: application/json' "$JIRA_BASE_URL$path" \
    --data-urlencode "jql=text ~ \"${2:-}\" ORDER BY updated DESC" \
    --data-urlencode "fields=summary,status,resolution,updated" \
    --data-urlencode "maxResults=15" || echo "JIRA_SEARCH_FAILED"
  exit 0
fi

key="${1:-}"
if ! printf '%s' "$key" | grep -Eq '^[A-Z][A-Z0-9]+-[0-9]+$'; then
  echo "BAD_KEY: '$key' does not look like PROJ-123. Ask the user for the key."
  exit 0
fi

pasted=$(ls docs/tickets/"$key"-*/ticket.md 2>/dev/null | head -1)
if [ -n "$pasted" ]; then
  echo "PASTED_TICKET from $pasted:"
  cat "$pasted"
  exit 0
fi

if [ -z "${JIRA_BASE_URL:-}" ]; then
  echo "NO_TICKET: no ~/.jira-env and no pasted ticket.md. Ask the user to paste the ticket."
  exit 0
fi

fields=summary,description,comment,issuelinks,status,labels,priority,parent,subtasks,issuetype,components
[ -n "${JIRA_AC_FIELD:-}" ] && fields="$fields,$JIRA_AC_FIELD"
# API v2 returns the description as plain wiki text, which is much shorter than v3's JSON document format.
if out=$(auth_header | curl -sf --max-time 20 -H @- -H 'Accept: application/json' \
         "$JIRA_BASE_URL/rest/api/2/issue/$key?fields=$fields"); then
  echo "JIRA_OK"
  printf '%s\n' "$out"
else
  echo "NO_TICKET: the Jira request failed (check ~/.jira-env, VPN and token). Ask the user to paste the ticket."
fi
exit 0

---
name: decide
description: Settle the open design decisions for the current ticket by asking the user one question at a time. Use after ticket-intake on M or L tickets, or when the user says "grill me" about a ticket.
disable-model-invocation: true
---
# Decide

Find KEY in the branch name (git branch --show-current). Read
docs/tickets/<KEY>-*/brief.md, mainly its DECISIONS and PO QUESTIONS.

## Rules
- Facts are your job. If the code, tests, docs or git history can answer a
  question, send an Explore subagent and record the answer as a FACT.
  Never ask the user something you could look up.
- Ask ONE question at a time with AskUserQuestion, 2-4 options. The first
  option is your recommendation, labelled "(Recommended)".
- Before the options, write two lines: what you found (with file:line) and
  what goes wrong if the choice is wrong.
- Order the queue by impact x uncertainty. Ask a question only when every
  decision it depends on is settled. New decisions found along the way join
  the queue.
- Aim for 5-10 questions. If you need more, the ticket is probably too big:
  say so and propose a split.
- Check vague words against CONTEXT.md. If the user's answer contradicts the
  code, say so before recording it.
- Questions only the PO can answer go to questions-for-po.md. Offer to post
  them as one Jira comment, and post only after an explicit yes.
- Anything you chose yourself is recorded as "agent default", never as
  something the user agreed to.

## After each answer, append to decisions.md
### D-<n> . <short title>
- Question:
- Choice:
- Rejected: <alternatives, one line each with why>
- Evidence: <file:line or doc>
- Decided by: user | agent default | PO
- Affects: <acceptance criteria or files> . Reversible: yes | no

## ADRs
Draft docs/adr/NNNN-<slug>.md only when a decision passes all three tests:
hard to reverse, surprising without context, and a real trade-off. Sections:
Status (proposed), Context, Decision, Consequences, Alternatives. It will be
committed with the slice it belongs to. Add new domain terms to CONTEXT.md.

## Done when
No open decisions remain. Show the full scope in one list and ask
"Anything missing?" Do not /clear: /ticket-spec runs in this same session.

---
name: ticket-spec
description: Write the PRD/spec for the current ticket from the brief and the decisions made in this session. Use right after /decide on M or L tickets.
disable-model-invocation: true
---
# Ticket spec

Do NOT interview the user again. Use brief.md, decisions.md and this conversation.
KEY comes from the branch name. Refuse to run on main or master.

1. Propose the test seams: where tests will touch the code. Prefer existing
   seams and existing test files, ideally one seam. Confirm them with the
   user in a single AskUserQuestion.
2. Write docs/tickets/<KEY>-*/spec.md with exactly these sections:
   ## Problem             2-4 lines, in the user's words
   ## Goals / Non-goals
   ## User stories        numbered
   ## Acceptance criteria
   AC-1  WHEN <trigger> THE SYSTEM SHALL <response>
         -> test: <test file> "<test name>"
   (EARS forms: WHEN / WHILE / IF ... THEN / WHERE; one behaviour per AC)
   ## Implementation decisions   modules, interfaces, schema; cite D-n
   ## Code map            from brief.md, file:line
   ## Testing decisions   seams, existing tests to copy, fast check command
   ## Out of scope
   ## Verification        one end-to-end check a human can run before pushing
   ## Open risks
3. Every acceptance criterion in the Jira ticket maps to at least one AC-n.
   List any that don't, and ask about them.
4. Every AC names one test. An AC that can't be tested gets a manual check
   under Verification, marked MANUAL.
5. Keep it under ~150 lines. The user must be able to review it in 5 minutes.
6. STOP and ask for approval (G2). The spec is not committed. It stays in the
   untracked notes folder, and /ship copies its summary into the PR body.

---
name: slice
description: Split the approved spec into vertical slices, one slice per future commit. Use after /ticket-spec is approved, on M or L tickets.
disable-model-invocation: true
---
# Slice

Read spec.md and brief.md from docs/tickets/<KEY>-*/ (KEY from the branch).
Write tasks.md in the same folder. Each slice becomes exactly one commit.

## Rules
- Preparatory refactors come first, as their own slices, with no behaviour change.
- Each feature slice is a thin path through every layer it needs
  (schema -> API -> UI -> test). It can be shown working on its own and
  fits in one fresh session.
- Aim for about 100 changed lines per slice; 300 is fine; more means split it.
- Whole ticket over ~400 changed lines? Propose 2-3 PRs titled
  "<KEY> (1/3) ...", each squash-merged on its own.
- Wide refactors: expand -> migrate in batches -> contract.
- Every AC in spec.md belongs to at least one slice.

## Per slice
- [ ] S-<n>  <title>
  ACs: AC-?          Depends on: S-? | none
  Files: <paths>
  Existing tests to run first: <names or command>
  First failing test: <file> "<name>"
  Verify: <fast check, plus anything slice-specific>
  Commit: "<KEY> <type>(<scope>): <summary>"
  PR: 1 (or 2, 3 if split)

End the file with an empty section:
## NOTICED BUT NOT TOUCHING

## Check, then stop
Launch one subagent with only spec.md and tasks.md. It reports any AC with
no slice, any slice that contradicts the spec, and any slice that depends on
a later one. Fix what it finds.
STOP and ask: right size? right order? should any part be its own PR? (G3)

---
name: build-slice
description: Build the next unchecked slice of the current ticket test-first and commit it. Use once per slice, ideally in a fresh session.
disable-model-invocation: true
hooks:
  Stop:
    - hooks:
        - type: command
          command: bash "$HOME/.claude/hooks/fast-check-on-stop.sh"
          timeout: 300
---
# Build one slice

1. Refuse to run on main or master. KEY comes from the branch name.
   git status --porcelain must show no changes to TRACKED files
   (the untracked notes folder is fine). If it does, stop and ask.
2. Read docs/tickets/<KEY>-*/: spec.md and tasks.md, and pick the first
   unchecked slice. XS/S tickets have no tasks.md: brief.md is the one slice.
3. Run the existing tests for this area first. If they already fail, STOP and
   tell the user. Never build on a red baseline.
4. Write ONE failing test at the agreed seam, in the style of the tests next
   to it. Run it and confirm it fails for the expected reason, not a typo or
   import error.
5. Write the smallest code that makes it pass. Rerun. Repeat steps 4-5 for
   the slice's other ACs, one test at a time.
6. Run the fast check (the fastcheck file in the notes folder). Then read
   your own diff once, looking for debug output, dead code and secrets.
7. Never edit, skip or delete an existing test without asking. Never change a
   new test just to make it pass. Never write all the tests up front.
   Don't fix anything outside this slice: add it under
   "NOTICED BUT NOT TOUCHING" in tasks.md.
8. Stage only this slice's files, by path (never git add -A or git add .),
   including any ADR or CONTEXT.md change that belongs to it.
9. Commit with the message planned in tasks.md. Tick the slice.
10. STOP and report:
    - what changed, in 3-5 lines
    - the new test names and the command output proving they pass
    - anything surprising, and anything you were unsure about
    - one sentence the user could say to a reviewer about this slice
    Then suggest /clear before the next /build-slice.

---
name: ticket-review
description: Review the current ticket branch with fresh-context subagents against the spec and the repo's standards. Use after all slices are built, before /ship.
disable-model-invocation: true
---
# Ticket review

You coordinate. The reviewing is done by subagents, which start with an empty
context, so they never see how the code was written.

1. git fetch origin. KEY from the branch. Notes folder: docs/tickets/<KEY>-*/.
   Collect the paths only: spec.md, tasks.md, CLAUDE.md, and
   CODING_STANDARDS.md or CONTRIBUTING.md if they exist.
2. Launch two subagents IN PARALLEL. Tell each: "Read-only. Do not edit files
   or run tests. Run git diff origin/main...HEAD yourself and read the files
   listed. Report findings as: problem . file:line . severity
   (Critical / Required / Optional) . suggested fix. At most 10."
   A) SPEC: for every AC, where is it implemented and which test proves it?
      Report missing ACs, behaviour that differs from the spec, and scope
      creep (changes no AC asks for). Check the tests really assert the AC
      and are not hard-coded to pass.
   B) STANDARDS: repo conventions (copy what nearby code does), error
      handling, security (input, auth, secrets, injection), performance traps,
      and code smells. No style preferences that a linter would not enforce.
   Keep the two reports separate. Don't merge or re-rank them.
3. Then ONE subagent, not in parallel with anything: "Pick the 3 most
   important conditions in the diff. For each: change it to its opposite,
   run its tests, record whether a test failed, and revert it. At the end
   git status --porcelain must show no tracked changes; prove it."
   Any change that no test catches is a Required finding.
4. Launch one more subagent with the combined findings and the diff. It tries
   to disprove each finding and drops the ones it cannot confirm.
5. Write review.md in the notes folder: confirmed findings grouped by
   severity, the mutation results, and a short "dropped findings" list.
6. Show the user the Critical and Required findings and ask which to fix.
   Each agreed fix becomes its own commit:
   git commit --fixup=<sha of the slice it belongs to>
   Optional findings are listed, not fixed, unless the user asks.

This does not replace the user's own reading of the diff before /ship.

---
name: ship
description: Tidy the slice commits, push the ticket branch, open the PR (squash-merged later into one commit on main) and comment on Jira. Use when review.md has no open Critical or Required findings.
disable-model-invocation: true
---
# Ship

The model: one commit per slice on the branch. The platform squash-merges the
PR into ONE commit on main. Never squash to one commit locally.

1. Preconditions: on feat/<KEY>-* (never main or master); git status
   --porcelain shows no tracked changes; every slice is ticked; review.md has
   no open Critical or Required finding. If any fails, stop and say which.
2. git fetch origin
   BRANCH=$(git branch --show-current)
   If git ls-remote --exit-code --heads origin "$BRANCH" succeeds, the branch
   was already pushed: DO NOT rewrite history. Skip to step 6. To pick up new
   commits from main, use git merge origin/main, never rebase.
3. BACKUP="backup/$(echo "$BRANCH" | tr / -)-$(date +%s)"; git branch "$BACKUP"
   OLD_BASE=$(git merge-base origin/main HEAD)
4. Fold the fixups into their slices and rebase onto main, running the fast
   check (fastcheck in the notes folder) on every commit:
   GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash -x "<fast check>" origin/main
   If a check fails or a conflict stops the rebase, STOP and show the user.
   Offer git rebase --abort, which restores the branch. Never continue silently.
5. Prove nothing was lost or added:
   git range-diff "$OLD_BASE..$BACKUP" "origin/main..HEAD"
   Expect only the fixups folded into their slices. Show it to the user.
   If the commits don't match the slices, RECOMPUTE the base first:
   BASE=$(git merge-base origin/main HEAD); git reset --soft "$BASE"
   then recommit slice by slice (stage by path, or git apply --cached for
   single hunks) and rerun the check from step 4.
6. Every commit message starts with <KEY>. No Jira smart-commit commands
   (#time #comment #transition) in any message.
7. Write pr.md in the notes folder.
   Line 1 = PR title = the future squash subject, in the team's format, e.g.
   "<KEY> <type>(<scope>): <summary>".
   The rest = PR body = the future squash body:
   - Summary (3-5 lines)
   - Slices: one line each
   - Acceptance criteria -> evidence: table of AC-n, test name, result
   - Decisions: the key D-n lines
   - Risk: one-way or two-way door, blast radius, how to roll back
   - Refs: <KEY>
   - Co-authored-by: Claude <noreply@anthropic.com>
   Also write jira-comment.txt: the PR link placeholder plus the summary.
8. SHOW the user: git log --oneline origin/main..HEAD, the PR title and body,
   and the Jira comment. Wait for an explicit yes. (G4)
9. git push -u origin HEAD
   If gh is available: gh pr create --title "<line 1>" --body-file <body file>
   Otherwise give the user the compare URL git printed and the title and body
   to paste.
10. Jira, only after a yes: put the PR URL into jira-comment.txt, then run
    bash "${CLAUDE_SKILL_DIR}/jira-comment.sh" <KEY> <path to jira-comment.txt>
    If it prints NO_JIRA, show the text for the user to paste. Change the
    ticket status only if the user asks.

During review: every fix is a NEW commit (git commit --fixup=<sha>, then
git push). Never force-push a branch under review. Never merge the PR
yourself; a human or the merge queue squash-merges it.
After merge: git switch main && git pull --prune, then
git branch -D "$BRANCH" and the backup branch (-D because a squash leaves
no ancestry for git to see).

#!/usr/bin/env bash
# Posts a text file as a comment on a Jira ticket. Used by /ship after the user says yes.
# Usage: jira-comment.sh PROJ-123 path/to/comment.txt
# Uses the same ~/.jira-env as /ticket-intake. Without it, prints NO_JIRA and you paste by hand.
set -u
[ -f "$HOME/.jira-env" ] && . "$HOME/.jira-env"

key="${1:-}"; file="${2:-}"
printf '%s' "$key" | grep -Eq '^[A-Z][A-Z0-9]+-[0-9]+$' || { echo "BAD_KEY: $key"; exit 1; }
[ -f "$file" ] || { echo "NO_FILE: $file"; exit 1; }
[ -n "${JIRA_BASE_URL:-}" ] || { echo "NO_JIRA: no ~/.jira-env. Paste the comment into Jira by hand."; exit 1; }

auth_header() {
  if [ -n "${JIRA_PAT:-}" ]; then
    printf 'Authorization: Bearer %s\n' "$JIRA_PAT"
  else
    printf 'Authorization: Basic %s\n' "$(printf '%s:%s' "${JIRA_EMAIL:-}" "${JIRA_API_TOKEN:-}" | base64 | tr -d '\n')"
  fi
}

# Escape the text for JSON: backslashes, quotes, tabs, carriage returns, then newlines.
body=$(sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e "s/$(printf '\t')/\\\\t/g" -e "s/$(printf '\r')//g" "$file" \
       | awk '{ printf "%s\\n", $0 }')

# API v2 takes plain wiki text; v3 would need Atlassian's JSON document format.
if auth_header | curl -sf --max-time 20 -X POST -H @- \
     -H 'Content-Type: application/json' -H 'Accept: application/json' \
     --data-binary "{\"body\":\"$body\"}" \
     "$JIRA_BASE_URL/rest/api/2/issue/$key/comment" >/dev/null; then
  echo "POSTED comment on $key"
else
  echo "JIRA_POST_FAILED: paste the comment into Jira by hand."
  exit 1
fi

---
name: ticket-retro
description: Log how a finished ticket went, compare against the baseline, and turn a repeated agent mistake into one rule. Use after the PR is opened or merged.
disable-model-invocation: true
argument-hint: "[JIRA-KEY]"
---
# Ticket retro

KEY is $0, or comes from the branch name. Notes folder: docs/tickets/<KEY>-*/.

1. Gather facts without asking: size and track from brief.md; number of
   decisions in decisions.md; slices in tasks.md; findings per severity in
   review.md; time of the first slice commit and of the push (git log);
   PR created time and review rounds (gh pr view --json createdAt,reviews,
   if gh is available).
2. Ask the user in ONE AskUserQuestion round: hands-on hours (their own
   time, not wall-clock), whether they had to rework anything after review,
   and the biggest agent mistake, if any.
3. Append ONE row to ~/ticket-log.md, outside every repo. Create the file
   with this header only if it does not exist. Never rewrite earlier rows.
   | date | key | size | track | start->PR (h) | hands-on (h) | slices | review C/R/O | rework | agent mistake | note |
   The first row in the file is the baseline: the user's typical numbers
   from before using this pipeline.
4. Read the last 5 rows. If the same kind of agent mistake appears twice,
   propose ONE fix: a line for CLAUDE.md, a check in a hook, or a change to
   one skill. Show the exact text and add it only after a yes.
5. Every 5th row: compare the median start->PR and hands-on hours per size
   with the baseline. Say plainly if it is slower or the same. Suggest
   dropping stages that didn't pay off for that size.

#!/usr/bin/env bash
# PreToolUse hook for Bash: blocks risky git/gh commands and asks before destructive ones.
# Applies in every session and every skill, because a hook can't tell which skill is running.
input=$(cat)
if command -v jq >/dev/null 2>&1; then
  cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
else
  cmd=$input   # no jq: match against the raw JSON, which still contains the command text
fi
[ -n "$cmd" ] || exit 0

block() { echo "Blocked by git-guard: $1" >&2; exit 2; }
ask() {
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"git-guard: %s"}}\n' "$1"
  exit 0
}
has() { printf '%s' "$cmd" | grep -Eq -- "$1"; }

S='[[:space:]]'
END='([[:space:];&|"]|$)'
branch=$(git branch --show-current 2>/dev/null)

if has "git$S.*push"; then
  has "push[^;&|]*($S|:|refs/heads/)(main|master)$END" && block "never push to main/master. Push the ticket branch and open a PR."
  case "$branch" in main|master) block "you are on $branch. Push from the ticket branch." ;; esac
  has "push[^;&|]*(--force$END|--force=|$S-f$END|$S\+[^[:space:]])" && block "no force-push. Push fixes as new fixup! commits."
  has "push[^;&|]*--force-with-lease" && ask "force-push with lease. Only OK if this branch has never been reviewed."
fi
has "--no-verify" && block "don't skip the repo's git hooks."
has "git$S+add$S+(-A|--all|\.)$END" && block "stage files by path, never all at once."
has "git$S+commit($S[^;&|]*)?$S-[a-zA-Z]*a[a-zA-Z]*$END" && block "no commit -a. Stage by path, then commit."
has "git$S+commit($S|$)" && case "$branch" in main|master) block "don't commit on $branch. Create the ticket branch first." ;; esac
has "gh$S+pr$S+merge" && block "the agent never merges PRs. A human or the merge queue does."
has "git$S+reset$S[^;&|]*--hard" && ask "reset --hard discards uncommitted work."
has "git$S+clean$S+-[a-zA-Z]*f" && ask "git clean deletes untracked files (including the ticket notes)."
has "git$S+branch$S[^;&|]*-D$END" && ask "deleting a branch with -D."
has "git$S+(checkout|restore)$S[^;&|]*$S\.$END" && ask "this throws away local changes."
has "git$S+stash$S+(drop|clear)" && ask "dropping stashed work."
exit 0

#!/usr/bin/env bash
# Stop hook, used only by /build-slice (declared in its frontmatter).
# Refuses to let the agent finish while the ticket's fast check fails.
input=$(cat)
# Second stop in a row: let it finish, so a baseline that can't go green never loops.
printf '%s' "$input" | grep -Eq '"stop_hook_active"[[:space:]]*:[[:space:]]*true' && exit 0

cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null || exit 0
key=$(git branch --show-current 2>/dev/null | grep -oE '[A-Z][A-Z0-9]+-[0-9]+' | head -1)
[ -n "$key" ] || exit 0
check=$(cat docs/tickets/"$key"-*/fastcheck 2>/dev/null | head -1)
[ -n "$check" ] || exit 0

if ! out=$(bash -c "$check" 2>&1); then
  {
    echo "Fast check failed: $check"
    printf '%s\n' "$out" | tail -40
    echo "Fix it, or tell the user exactly why it can't pass. Don't report the slice as done."
  } >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "bash \"$HOME/.claude/hooks/git-guard.sh\"" }
        ]
      }
    ]
  }
}

## Ticket workflow (personal rules)
- Work happens on a ticket branch: feat/<KEY>-<slug>. Never commit or push on main/master.
- Every commit message and PR title starts with the Jira key.
- Notes for a ticket live in docs/tickets/<KEY>-<slug>/. The folder is untracked
  (listed in .git/info/exclude) and never committed, except ADR or CONTEXT.md
  changes that belong to a slice.
- One slice = one commit. Stage files by path; never git add -A, git add . or commit -a.
- Never force-push, never merge a PR, never skip git hooks with --no-verify.
- No Jira smart-commit commands (#time, #comment, #transition) in commit messages.
- Never edit, skip or delete an existing test without asking.
- Facts: look them up in the code yourself. Decisions: ask me, recommendation first.
- Problems outside the current slice go under NOTICED BUT NOT TOUCHING in tasks.md.
- Before saying something works, show the command and its output.

# ~/.jira-env  (chmod 600 ~/.jira-env). Optional: without it you paste tickets by hand.
JIRA_BASE_URL=https://yourcompany.atlassian.net
# Jira Cloud: your login email + an API token (id.atlassian.com > Security > API tokens)
JIRA_EMAIL=you@company.com
JIRA_API_TOKEN=paste-token-here
# Jira Server / Data Center instead: a personal access token, and delete the two lines above
# JIRA_PAT=paste-token-here
# Only if acceptance criteria live in a custom field (ask your Jira admin for the id)
# JIRA_AC_FIELD=customfield_10042

#!/usr/bin/env bash
# Writes the ticket-to-branch kit into ~/.claude. Never overwrites: existing files are skipped.
set -eu
put() { if [ -e "$1" ]; then echo "skip (exists): $1"; cat >/dev/null; else mkdir -p "$(dirname "$1")"; cat >"$1"; echo "wrote: $1"; fi; }

put "$HOME/.claude/skills/ticket-intake/SKILL.md" <<'KIT_EOF_0'
---
name: ticket-intake
description: Turn a Jira ticket into an understanding brief for an unfamiliar codebase. Use when starting work on a Jira key like PROJ-123.
disable-model-invocation: true
argument-hint: "<JIRA-KEY>"
allowed-tools: Bash(bash *fetch-ticket.sh*)
---
# Ticket intake

Ticket key: $0. It must look like PROJ-123. If it is missing or malformed, stop and ask.

## Ticket (fetched before you started)
!`bash "${CLAUDE_SKILL_DIR}/fetch-ticket.sh" "$0"`

If the block above starts with NO_TICKET or BAD_KEY, ask the user to paste the
ticket (summary, description, acceptance criteria, important comments). Never guess it.

## Steps
1. Size it. XS: one-line fix. S: 1-3 files, under a day, no open decisions.
   M: several files or at least one real decision. L: crosses modules, changes
   a schema or public API, or will be over ~400 changed lines.
2. Branch: git fetch origin, then git switch -c feat/$0-<short-slug> origin/main
   (use the team's prefix if CLAUDE.md names one). If a branch for $0 already
   exists, switch to it instead. Never work on main or master.
3. Notes folder: docs/tickets/$0-<short-slug>/. Add the line docs/tickets/ to
   .git/info/exclude if it is not there. Save the ticket text as ticket.md.
   Never edit the Jira issue in this skill.
4. Fast check: find the quickest command that typechecks, lints and runs the
   tests for one area (package.json scripts, Makefile, CI config, README).
   Write it as one line to fastcheck in the notes folder and run it once.
   Note whether the baseline is green.
5. XS or S: write brief.md with Task, Files, Existing tests (names and how to
   run them) and Done when, in about 10 lines. STOP and suggest /build-slice.
6. M or L: read CLAUDE.md, CONTEXT.md and docs/adr/ if they exist.
7. Write 5-10 research questions about the code ("where is X computed?",
   "what calls Y?", "which tests cover Z?"). Launch 2-3 Explore subagents in
   parallel and give them ONLY the questions, not the ticket. They return facts
   with file:line and no proposals.
8. Run git log --oneline -15 on the 3-5 main files. Summarise how the area
   changed recently and which commits matter.
9. If the fetch above printed JIRA_OK, run
   bash "${CLAUDE_SKILL_DIR}/fetch-ticket.sh" --search "<2-3 keywords>"
   and look for duplicates or earlier rejected attempts.
10. Write brief.md:
    - Task in plain words (2-4 lines). Acceptance criteria exactly as Jira states them.
    - Code map: entry points, files likely touched, patterns to copy (file:line).
    - Current behaviour, and the EXISTING TESTS that cover it (names + run command).
    - Fast check command and whether the baseline is green.
    - Risks and unknowns. Size (XS/S/M/L) and why.
    - Open questions, in three groups:
      FACTS: answered by the research, each with file:line.
      DECISIONS: need the user; each with 2-3 options and your recommendation.
      PO QUESTIONS: only the ticket author can answer.
11. STOP. Show a summary of at most 15 lines and ask: "Is this the task?" (G1)
KIT_EOF_0
put "$HOME/.claude/skills/ticket-intake/fetch-ticket.sh" <<'KIT_EOF_1'
#!/usr/bin/env bash
# Prints a Jira ticket for /ticket-intake. Always exits 0 so the skill still loads.
#
# Usage: fetch-ticket.sh PROJ-123
#        fetch-ticket.sh --search "two or three keywords"
#
# Optional setup, once: put these lines in ~/.jira-env and run chmod 600 ~/.jira-env
#   JIRA_BASE_URL=https://yourcompany.atlassian.net
#   JIRA_EMAIL=you@company.com          # Jira Cloud
#   JIRA_API_TOKEN=...                  # Cloud: id.atlassian.com > Security > API tokens
#   JIRA_PAT=...                        # Jira Server / Data Center, instead of the two above
#   JIRA_AC_FIELD=customfield_10042     # only if acceptance criteria live in a custom field
# Without it, paste the ticket into docs/tickets/<KEY>-<slug>/ticket.md and this script prints that.

[ -f "$HOME/.jira-env" ] && . "$HOME/.jira-env"

# The token goes to curl on stdin (-H @-), so it never shows up in the process list.
auth_header() {
  if [ -n "${JIRA_PAT:-}" ]; then
    printf 'Authorization: Bearer %s\n' "$JIRA_PAT"
  else
    printf 'Authorization: Basic %s\n' "$(printf '%s:%s' "${JIRA_EMAIL:-}" "${JIRA_API_TOKEN:-}" | base64 | tr -d '\n')"
  fi
}

if [ "${1:-}" = "--search" ]; then
  [ -n "${JIRA_BASE_URL:-}" ] || { echo "NO_JIRA: no ~/.jira-env, so search Jira by hand for duplicates."; exit 0; }
  # Jira Cloud removed /rest/api/2/search; Server/Data Center still uses it.
  if [ -n "${JIRA_PAT:-}" ]; then path=/rest/api/2/search; else path=/rest/api/3/search/jql; fi
  auth_header | curl -sfG --max-time 20 -H @- -H 'Accept: application/json' "$JIRA_BASE_URL$path" \
    --data-urlencode "jql=text ~ \"${2:-}\" ORDER BY updated DESC" \
    --data-urlencode "fields=summary,status,resolution,updated" \
    --data-urlencode "maxResults=15" || echo "JIRA_SEARCH_FAILED"
  exit 0
fi

key="${1:-}"
if ! printf '%s' "$key" | grep -Eq '^[A-Z][A-Z0-9]+-[0-9]+$'; then
  echo "BAD_KEY: '$key' does not look like PROJ-123. Ask the user for the key."
  exit 0
fi

pasted=$(ls docs/tickets/"$key"-*/ticket.md 2>/dev/null | head -1)
if [ -n "$pasted" ]; then
  echo "PASTED_TICKET from $pasted:"
  cat "$pasted"
  exit 0
fi

if [ -z "${JIRA_BASE_URL:-}" ]; then
  echo "NO_TICKET: no ~/.jira-env and no pasted ticket.md. Ask the user to paste the ticket."
  exit 0
fi

fields=summary,description,comment,issuelinks,status,labels,priority,parent,subtasks,issuetype,components
[ -n "${JIRA_AC_FIELD:-}" ] && fields="$fields,$JIRA_AC_FIELD"
# API v2 returns the description as plain wiki text, which is much shorter than v3's JSON document format.
if out=$(auth_header | curl -sf --max-time 20 -H @- -H 'Accept: application/json' \
         "$JIRA_BASE_URL/rest/api/2/issue/$key?fields=$fields"); then
  echo "JIRA_OK"
  printf '%s\n' "$out"
else
  echo "NO_TICKET: the Jira request failed (check ~/.jira-env, VPN and token). Ask the user to paste the ticket."
fi
exit 0
KIT_EOF_1
put "$HOME/.claude/skills/decide/SKILL.md" <<'KIT_EOF_2'
---
name: decide
description: Settle the open design decisions for the current ticket by asking the user one question at a time. Use after ticket-intake on M or L tickets, or when the user says "grill me" about a ticket.
disable-model-invocation: true
---
# Decide

Find KEY in the branch name (git branch --show-current). Read
docs/tickets/<KEY>-*/brief.md, mainly its DECISIONS and PO QUESTIONS.

## Rules
- Facts are your job. If the code, tests, docs or git history can answer a
  question, send an Explore subagent and record the answer as a FACT.
  Never ask the user something you could look up.
- Ask ONE question at a time with AskUserQuestion, 2-4 options. The first
  option is your recommendation, labelled "(Recommended)".
- Before the options, write two lines: what you found (with file:line) and
  what goes wrong if the choice is wrong.
- Order the queue by impact x uncertainty. Ask a question only when every
  decision it depends on is settled. New decisions found along the way join
  the queue.
- Aim for 5-10 questions. If you need more, the ticket is probably too big:
  say so and propose a split.
- Check vague words against CONTEXT.md. If the user's answer contradicts the
  code, say so before recording it.
- Questions only the PO can answer go to questions-for-po.md. Offer to post
  them as one Jira comment, and post only after an explicit yes.
- Anything you chose yourself is recorded as "agent default", never as
  something the user agreed to.

## After each answer, append to decisions.md
### D-<n> . <short title>
- Question:
- Choice:
- Rejected: <alternatives, one line each with why>
- Evidence: <file:line or doc>
- Decided by: user | agent default | PO
- Affects: <acceptance criteria or files> . Reversible: yes | no

## ADRs
Draft docs/adr/NNNN-<slug>.md only when a decision passes all three tests:
hard to reverse, surprising without context, and a real trade-off. Sections:
Status (proposed), Context, Decision, Consequences, Alternatives. It will be
committed with the slice it belongs to. Add new domain terms to CONTEXT.md.

## Done when
No open decisions remain. Show the full scope in one list and ask
"Anything missing?" Do not /clear: /ticket-spec runs in this same session.
KIT_EOF_2
put "$HOME/.claude/skills/ticket-spec/SKILL.md" <<'KIT_EOF_3'
---
name: ticket-spec
description: Write the PRD/spec for the current ticket from the brief and the decisions made in this session. Use right after /decide on M or L tickets.
disable-model-invocation: true
---
# Ticket spec

Do NOT interview the user again. Use brief.md, decisions.md and this conversation.
KEY comes from the branch name. Refuse to run on main or master.

1. Propose the test seams: where tests will touch the code. Prefer existing
   seams and existing test files, ideally one seam. Confirm them with the
   user in a single AskUserQuestion.
2. Write docs/tickets/<KEY>-*/spec.md with exactly these sections:
   ## Problem             2-4 lines, in the user's words
   ## Goals / Non-goals
   ## User stories        numbered
   ## Acceptance criteria
   AC-1  WHEN <trigger> THE SYSTEM SHALL <response>
         -> test: <test file> "<test name>"
   (EARS forms: WHEN / WHILE / IF ... THEN / WHERE; one behaviour per AC)
   ## Implementation decisions   modules, interfaces, schema; cite D-n
   ## Code map            from brief.md, file:line
   ## Testing decisions   seams, existing tests to copy, fast check command
   ## Out of scope
   ## Verification        one end-to-end check a human can run before pushing
   ## Open risks
3. Every acceptance criterion in the Jira ticket maps to at least one AC-n.
   List any that don't, and ask about them.
4. Every AC names one test. An AC that can't be tested gets a manual check
   under Verification, marked MANUAL.
5. Keep it under ~150 lines. The user must be able to review it in 5 minutes.
6. STOP and ask for approval (G2). The spec is not committed. It stays in the
   untracked notes folder, and /ship copies its summary into the PR body.
KIT_EOF_3
put "$HOME/.claude/skills/slice/SKILL.md" <<'KIT_EOF_4'
---
name: slice
description: Split the approved spec into vertical slices, one slice per future commit. Use after /ticket-spec is approved, on M or L tickets.
disable-model-invocation: true
---
# Slice

Read spec.md and brief.md from docs/tickets/<KEY>-*/ (KEY from the branch).
Write tasks.md in the same folder. Each slice becomes exactly one commit.

## Rules
- Preparatory refactors come first, as their own slices, with no behaviour change.
- Each feature slice is a thin path through every layer it needs
  (schema -> API -> UI -> test). It can be shown working on its own and
  fits in one fresh session.
- Aim for about 100 changed lines per slice; 300 is fine; more means split it.
- Whole ticket over ~400 changed lines? Propose 2-3 PRs titled
  "<KEY> (1/3) ...", each squash-merged on its own.
- Wide refactors: expand -> migrate in batches -> contract.
- Every AC in spec.md belongs to at least one slice.

## Per slice
- [ ] S-<n>  <title>
  ACs: AC-?          Depends on: S-? | none
  Files: <paths>
  Existing tests to run first: <names or command>
  First failing test: <file> "<name>"
  Verify: <fast check, plus anything slice-specific>
  Commit: "<KEY> <type>(<scope>): <summary>"
  PR: 1 (or 2, 3 if split)

End the file with an empty section:
## NOTICED BUT NOT TOUCHING

## Check, then stop
Launch one subagent with only spec.md and tasks.md. It reports any AC with
no slice, any slice that contradicts the spec, and any slice that depends on
a later one. Fix what it finds.
STOP and ask: right size? right order? should any part be its own PR? (G3)
KIT_EOF_4
put "$HOME/.claude/skills/build-slice/SKILL.md" <<'KIT_EOF_5'
---
name: build-slice
description: Build the next unchecked slice of the current ticket test-first and commit it. Use once per slice, ideally in a fresh session.
disable-model-invocation: true
hooks:
  Stop:
    - hooks:
        - type: command
          command: bash "$HOME/.claude/hooks/fast-check-on-stop.sh"
          timeout: 300
---
# Build one slice

1. Refuse to run on main or master. KEY comes from the branch name.
   git status --porcelain must show no changes to TRACKED files
   (the untracked notes folder is fine). If it does, stop and ask.
2. Read docs/tickets/<KEY>-*/: spec.md and tasks.md, and pick the first
   unchecked slice. XS/S tickets have no tasks.md: brief.md is the one slice.
3. Run the existing tests for this area first. If they already fail, STOP and
   tell the user. Never build on a red baseline.
4. Write ONE failing test at the agreed seam, in the style of the tests next
   to it. Run it and confirm it fails for the expected reason, not a typo or
   import error.
5. Write the smallest code that makes it pass. Rerun. Repeat steps 4-5 for
   the slice's other ACs, one test at a time.
6. Run the fast check (the fastcheck file in the notes folder). Then read
   your own diff once, looking for debug output, dead code and secrets.
7. Never edit, skip or delete an existing test without asking. Never change a
   new test just to make it pass. Never write all the tests up front.
   Don't fix anything outside this slice: add it under
   "NOTICED BUT NOT TOUCHING" in tasks.md.
8. Stage only this slice's files, by path (never git add -A or git add .),
   including any ADR or CONTEXT.md change that belongs to it.
9. Commit with the message planned in tasks.md. Tick the slice.
10. STOP and report:
    - what changed, in 3-5 lines
    - the new test names and the command output proving they pass
    - anything surprising, and anything you were unsure about
    - one sentence the user could say to a reviewer about this slice
    Then suggest /clear before the next /build-slice.
KIT_EOF_5
put "$HOME/.claude/skills/ticket-review/SKILL.md" <<'KIT_EOF_6'
---
name: ticket-review
description: Review the current ticket branch with fresh-context subagents against the spec and the repo's standards. Use after all slices are built, before /ship.
disable-model-invocation: true
---
# Ticket review

You coordinate. The reviewing is done by subagents, which start with an empty
context, so they never see how the code was written.

1. git fetch origin. KEY from the branch. Notes folder: docs/tickets/<KEY>-*/.
   Collect the paths only: spec.md, tasks.md, CLAUDE.md, and
   CODING_STANDARDS.md or CONTRIBUTING.md if they exist.
2. Launch two subagents IN PARALLEL. Tell each: "Read-only. Do not edit files
   or run tests. Run git diff origin/main...HEAD yourself and read the files
   listed. Report findings as: problem . file:line . severity
   (Critical / Required / Optional) . suggested fix. At most 10."
   A) SPEC: for every AC, where is it implemented and which test proves it?
      Report missing ACs, behaviour that differs from the spec, and scope
      creep (changes no AC asks for). Check the tests really assert the AC
      and are not hard-coded to pass.
   B) STANDARDS: repo conventions (copy what nearby code does), error
      handling, security (input, auth, secrets, injection), performance traps,
      and code smells. No style preferences that a linter would not enforce.
   Keep the two reports separate. Don't merge or re-rank them.
3. Then ONE subagent, not in parallel with anything: "Pick the 3 most
   important conditions in the diff. For each: change it to its opposite,
   run its tests, record whether a test failed, and revert it. At the end
   git status --porcelain must show no tracked changes; prove it."
   Any change that no test catches is a Required finding.
4. Launch one more subagent with the combined findings and the diff. It tries
   to disprove each finding and drops the ones it cannot confirm.
5. Write review.md in the notes folder: confirmed findings grouped by
   severity, the mutation results, and a short "dropped findings" list.
6. Show the user the Critical and Required findings and ask which to fix.
   Each agreed fix becomes its own commit:
   git commit --fixup=<sha of the slice it belongs to>
   Optional findings are listed, not fixed, unless the user asks.

This does not replace the user's own reading of the diff before /ship.
KIT_EOF_6
put "$HOME/.claude/skills/ship/SKILL.md" <<'KIT_EOF_7'
---
name: ship
description: Tidy the slice commits, push the ticket branch, open the PR (squash-merged later into one commit on main) and comment on Jira. Use when review.md has no open Critical or Required findings.
disable-model-invocation: true
---
# Ship

The model: one commit per slice on the branch. The platform squash-merges the
PR into ONE commit on main. Never squash to one commit locally.

1. Preconditions: on feat/<KEY>-* (never main or master); git status
   --porcelain shows no tracked changes; every slice is ticked; review.md has
   no open Critical or Required finding. If any fails, stop and say which.
2. git fetch origin
   BRANCH=$(git branch --show-current)
   If git ls-remote --exit-code --heads origin "$BRANCH" succeeds, the branch
   was already pushed: DO NOT rewrite history. Skip to step 6. To pick up new
   commits from main, use git merge origin/main, never rebase.
3. BACKUP="backup/$(echo "$BRANCH" | tr / -)-$(date +%s)"; git branch "$BACKUP"
   OLD_BASE=$(git merge-base origin/main HEAD)
4. Fold the fixups into their slices and rebase onto main, running the fast
   check (fastcheck in the notes folder) on every commit:
   GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash -x "<fast check>" origin/main
   If a check fails or a conflict stops the rebase, STOP and show the user.
   Offer git rebase --abort, which restores the branch. Never continue silently.
5. Prove nothing was lost or added:
   git range-diff "$OLD_BASE..$BACKUP" "origin/main..HEAD"
   Expect only the fixups folded into their slices. Show it to the user.
   If the commits don't match the slices, RECOMPUTE the base first:
   BASE=$(git merge-base origin/main HEAD); git reset --soft "$BASE"
   then recommit slice by slice (stage by path, or git apply --cached for
   single hunks) and rerun the check from step 4.
6. Every commit message starts with <KEY>. No Jira smart-commit commands
   (#time #comment #transition) in any message.
7. Write pr.md in the notes folder.
   Line 1 = PR title = the future squash subject, in the team's format, e.g.
   "<KEY> <type>(<scope>): <summary>".
   The rest = PR body = the future squash body:
   - Summary (3-5 lines)
   - Slices: one line each
   - Acceptance criteria -> evidence: table of AC-n, test name, result
   - Decisions: the key D-n lines
   - Risk: one-way or two-way door, blast radius, how to roll back
   - Refs: <KEY>
   - Co-authored-by: Claude <noreply@anthropic.com>
   Also write jira-comment.txt: the PR link placeholder plus the summary.
8. SHOW the user: git log --oneline origin/main..HEAD, the PR title and body,
   and the Jira comment. Wait for an explicit yes. (G4)
9. git push -u origin HEAD
   If gh is available: gh pr create --title "<line 1>" --body-file <body file>
   Otherwise give the user the compare URL git printed and the title and body
   to paste.
10. Jira, only after a yes: put the PR URL into jira-comment.txt, then run
    bash "${CLAUDE_SKILL_DIR}/jira-comment.sh" <KEY> <path to jira-comment.txt>
    If it prints NO_JIRA, show the text for the user to paste. Change the
    ticket status only if the user asks.

During review: every fix is a NEW commit (git commit --fixup=<sha>, then
git push). Never force-push a branch under review. Never merge the PR
yourself; a human or the merge queue squash-merges it.
After merge: git switch main && git pull --prune, then
git branch -D "$BRANCH" and the backup branch (-D because a squash leaves
no ancestry for git to see).
KIT_EOF_7
put "$HOME/.claude/skills/ship/jira-comment.sh" <<'KIT_EOF_8'
#!/usr/bin/env bash
# Posts a text file as a comment on a Jira ticket. Used by /ship after the user says yes.
# Usage: jira-comment.sh PROJ-123 path/to/comment.txt
# Uses the same ~/.jira-env as /ticket-intake. Without it, prints NO_JIRA and you paste by hand.
set -u
[ -f "$HOME/.jira-env" ] && . "$HOME/.jira-env"

key="${1:-}"; file="${2:-}"
printf '%s' "$key" | grep -Eq '^[A-Z][A-Z0-9]+-[0-9]+$' || { echo "BAD_KEY: $key"; exit 1; }
[ -f "$file" ] || { echo "NO_FILE: $file"; exit 1; }
[ -n "${JIRA_BASE_URL:-}" ] || { echo "NO_JIRA: no ~/.jira-env. Paste the comment into Jira by hand."; exit 1; }

auth_header() {
  if [ -n "${JIRA_PAT:-}" ]; then
    printf 'Authorization: Bearer %s\n' "$JIRA_PAT"
  else
    printf 'Authorization: Basic %s\n' "$(printf '%s:%s' "${JIRA_EMAIL:-}" "${JIRA_API_TOKEN:-}" | base64 | tr -d '\n')"
  fi
}

# Escape the text for JSON: backslashes, quotes, tabs, carriage returns, then newlines.
body=$(sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e "s/$(printf '\t')/\\\\t/g" -e "s/$(printf '\r')//g" "$file" \
       | awk '{ printf "%s\\n", $0 }')

# API v2 takes plain wiki text; v3 would need Atlassian's JSON document format.
if auth_header | curl -sf --max-time 20 -X POST -H @- \
     -H 'Content-Type: application/json' -H 'Accept: application/json' \
     --data-binary "{\"body\":\"$body\"}" \
     "$JIRA_BASE_URL/rest/api/2/issue/$key/comment" >/dev/null; then
  echo "POSTED comment on $key"
else
  echo "JIRA_POST_FAILED: paste the comment into Jira by hand."
  exit 1
fi
KIT_EOF_8
put "$HOME/.claude/skills/ticket-retro/SKILL.md" <<'KIT_EOF_9'
---
name: ticket-retro
description: Log how a finished ticket went, compare against the baseline, and turn a repeated agent mistake into one rule. Use after the PR is opened or merged.
disable-model-invocation: true
argument-hint: "[JIRA-KEY]"
---
# Ticket retro

KEY is $0, or comes from the branch name. Notes folder: docs/tickets/<KEY>-*/.

1. Gather facts without asking: size and track from brief.md; number of
   decisions in decisions.md; slices in tasks.md; findings per severity in
   review.md; time of the first slice commit and of the push (git log);
   PR created time and review rounds (gh pr view --json createdAt,reviews,
   if gh is available).
2. Ask the user in ONE AskUserQuestion round: hands-on hours (their own
   time, not wall-clock), whether they had to rework anything after review,
   and the biggest agent mistake, if any.
3. Append ONE row to ~/ticket-log.md, outside every repo. Create the file
   with this header only if it does not exist. Never rewrite earlier rows.
   | date | key | size | track | start->PR (h) | hands-on (h) | slices | review C/R/O | rework | agent mistake | note |
   The first row in the file is the baseline: the user's typical numbers
   from before using this pipeline.
4. Read the last 5 rows. If the same kind of agent mistake appears twice,
   propose ONE fix: a line for CLAUDE.md, a check in a hook, or a change to
   one skill. Show the exact text and add it only after a yes.
5. Every 5th row: compare the median start->PR and hands-on hours per size
   with the baseline. Say plainly if it is slower or the same. Suggest
   dropping stages that didn't pay off for that size.
KIT_EOF_9
put "$HOME/.claude/hooks/git-guard.sh" <<'KIT_EOF_10'
#!/usr/bin/env bash
# PreToolUse hook for Bash: blocks risky git/gh commands and asks before destructive ones.
# Applies in every session and every skill, because a hook can't tell which skill is running.
input=$(cat)
if command -v jq >/dev/null 2>&1; then
  cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
else
  cmd=$input   # no jq: match against the raw JSON, which still contains the command text
fi
[ -n "$cmd" ] || exit 0

block() { echo "Blocked by git-guard: $1" >&2; exit 2; }
ask() {
  printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"ask","permissionDecisionReason":"git-guard: %s"}}\n' "$1"
  exit 0
}
has() { printf '%s' "$cmd" | grep -Eq -- "$1"; }

S='[[:space:]]'
END='([[:space:];&|"]|$)'
branch=$(git branch --show-current 2>/dev/null)

if has "git$S.*push"; then
  has "push[^;&|]*($S|:|refs/heads/)(main|master)$END" && block "never push to main/master. Push the ticket branch and open a PR."
  case "$branch" in main|master) block "you are on $branch. Push from the ticket branch." ;; esac
  has "push[^;&|]*(--force$END|--force=|$S-f$END|$S\+[^[:space:]])" && block "no force-push. Push fixes as new fixup! commits."
  has "push[^;&|]*--force-with-lease" && ask "force-push with lease. Only OK if this branch has never been reviewed."
fi
has "--no-verify" && block "don't skip the repo's git hooks."
has "git$S+add$S+(-A|--all|\.)$END" && block "stage files by path, never all at once."
has "git$S+commit($S[^;&|]*)?$S-[a-zA-Z]*a[a-zA-Z]*$END" && block "no commit -a. Stage by path, then commit."
has "git$S+commit($S|$)" && case "$branch" in main|master) block "don't commit on $branch. Create the ticket branch first." ;; esac
has "gh$S+pr$S+merge" && block "the agent never merges PRs. A human or the merge queue does."
has "git$S+reset$S[^;&|]*--hard" && ask "reset --hard discards uncommitted work."
has "git$S+clean$S+-[a-zA-Z]*f" && ask "git clean deletes untracked files (including the ticket notes)."
has "git$S+branch$S[^;&|]*-D$END" && ask "deleting a branch with -D."
has "git$S+(checkout|restore)$S[^;&|]*$S\.$END" && ask "this throws away local changes."
has "git$S+stash$S+(drop|clear)" && ask "dropping stashed work."
exit 0
KIT_EOF_10
put "$HOME/.claude/hooks/fast-check-on-stop.sh" <<'KIT_EOF_11'
#!/usr/bin/env bash
# Stop hook, used only by /build-slice (declared in its frontmatter).
# Refuses to let the agent finish while the ticket's fast check fails.
input=$(cat)
# Second stop in a row: let it finish, so a baseline that can't go green never loops.
printf '%s' "$input" | grep -Eq '"stop_hook_active"[[:space:]]*:[[:space:]]*true' && exit 0

cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null || exit 0
key=$(git branch --show-current 2>/dev/null | grep -oE '[A-Z][A-Z0-9]+-[0-9]+' | head -1)
[ -n "$key" ] || exit 0
check=$(cat docs/tickets/"$key"-*/fastcheck 2>/dev/null | head -1)
[ -n "$check" ] || exit 0

if ! out=$(bash -c "$check" 2>&1); then
  {
    echo "Fast check failed: $check"
    printf '%s\n' "$out" | tail -40
    echo "Fix it, or tell the user exactly why it can't pass. Don't report the slice as done."
  } >&2
  exit 2
fi
exit 0
KIT_EOF_11
chmod +x "$HOME/.claude/hooks/"*.sh "$HOME/.claude/skills/"*/*.sh
echo
echo "Next, by hand: merge settings.json into ~/.claude/settings.json and append the CLAUDE.md block (see the page)."