@jeiemgi/cckit 0.1.6

package/skills/kit-effort-close/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: kit-effort-close
+description: Close an effort in ONE op — snapshot each sub-issue's diff BEFORE squash (work record), squash-merge the effort PR, close the parent + ALL native sub-issues, set the board Status=Done for the parent and every sub, then garbage-collect (switch to the base branch, pull, remove the effort worktree, delete local+remote branch, prune). Finally, flag any kit-managed files the effort touched for upstream contribution.
+when_to_use: When the effort PR has been reviewed and is ready to land. This is the single close op for the effort lifecycle (effort-model.md) — board + record state are correct by construction. Replaces the separate merge / close / mark-done / gc steps.
+---
+
+# kit-effort-close
+
+Plugin-direct skill — runs straight from `${CLAUDE_PLUGIN_ROOT}` (no per-project `scripts/` checkout
+needed). The verb logic (`effort_branch_num`, `effort_snapshot_subs`) lives in
+`scripts/lib/effort.sh`, never re-authored inline (kit-engine-boundary #1/#2). Respects
+`KIT_BASE_BRANCH` (default `main`) and the `KIT_PROJECTS_V2` board toggle.
+
+The effort lifecycle's terminal op. Board state, issue state, and the work record are correct
+**by construction** — this op owns them. Order matters: **snapshot before squash** (squash destroys
+the per-sub-issue commit pairs that ARE the per-unit work record — effort-model.md "Trace hard rules").
+
+## Preconditions
+
+1. The effort PR exists, is reviewed, not in draft, and is mergeable (or rebaseable).
+2. You are on the `effort/<N>-<slug>` branch (its worktree), working tree clean.
+
+If not, abort and route to `/kit-effort-pr` first.
+
+## Inputs
+
+| Field        | Required | Notes                                                   |
+| ------------ | -------- | ------------------------------------------------------- |
+| Issue number | optional | Parent #N — derived from `effort/<N>-<slug>` if omitted |
+| PR number    | optional | Defaults to the open PR for the effort branch           |
+
+## Execution
+
+```bash
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/kit-config.sh" && load_kit_config
+[[ "$KIT_PROJECTS_V2" == "true" ]] && { source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/gh-project.sh"; load_project_ids; }
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/effort.sh"
+BASE="${KIT_BASE_BRANCH:-main}"
+
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# 0. Resolve parent #N + the effort PR.
+NUM="${INPUT_NUM:-}"
+[[ -z "$NUM" ]] && NUM=$(effort_branch_num "$BRANCH")
+[[ -z "$NUM" ]] && { echo "✗ Not on an effort branch (effort/<N>-<slug>) and no #N passed"; exit 1; }
+
+if [[ -n "$(git status --porcelain)" ]]; then
+  echo "✗ Working tree dirty — commit via /kit-effort-pr first"; exit 1
+fi
+
+PR_NUM="${INPUT_PR:-}"
+[[ -z "$PR_NUM" ]] && PR_NUM=$(gh pr list --repo "$KIT_REPO" --head "$BRANCH" --state open --json number --jq '.[0].number // empty')
+[[ -z "$PR_NUM" ]] && { echo "✗ No open PR for $BRANCH — run /kit-effort-pr $NUM"; exit 1; }
+echo "→ effort #$NUM · PR #$PR_NUM · branch $BRANCH"
+
+# ── (a) SNAPSHOT SUB-DIFFS *BEFORE* SQUASH ───────────────────────────────────────────────
+# Squash collapses the per-sub-issue commits; capture each commit's diff + its sub-issue pairing
+# NOW, to a durable trace dir under the shared git-common-dir (survives the worktree prune below).
+TRACE_DIR=$(effort_snapshot_subs "$NUM" "origin/$BASE")
+echo "  trace: ${TRACE_DIR:-<none>}"
+
+# ── (b) SQUASH-MERGE THE EFFORT PR ───────────────────────────────────────────────────────
+MERGE_INFO=$(gh pr view "$PR_NUM" --repo "$KIT_REPO" --json mergeable,isDraft --jq '{m:.mergeable,d:.isDraft}')
+[[ "$(echo "$MERGE_INFO" | jq -r .d)" == "true" ]] && { echo "✗ PR #$PR_NUM is a draft — undraft first"; exit 1; }
+if [[ "$(echo "$MERGE_INFO" | jq -r .m)" == "CONFLICTING" ]]; then
+  echo "→ Conflicts — rebasing onto $BASE..."
+  git fetch origin "$BASE" && git rebase "origin/$BASE" \
+    && git push --force-with-lease origin "$BRANCH" \
+    || { echo "✗ Rebase conflicts need manual resolution"; git rebase --abort 2>/dev/null; exit 1; }
+  sleep 3
+fi
+gh pr merge "$PR_NUM" --repo "$KIT_REPO" --squash || { echo "✗ Merge failed — see https://github.com/$KIT_REPO/pull/$PR_NUM"; exit 1; }
+echo "✓ PR #$PR_NUM squash-merged"
+
+# ── (c) CLOSE PARENT + ALL NATIVE SUB-ISSUES ─────────────────────────────────────────────
+# Native sub-issues (GitHub parent/child). Collect them via GraphQL subIssues.
+SUBS=$(gh api graphql -f query='
+  query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){
+    subIssues(first:50){nodes{number state}}}}}' \
+  -F o="${KIT_REPO%/*}" -F r="${KIT_REPO#*/}" -F n="$NUM" \
+  --jq '.data.repository.issue.subIssues.nodes[]?.number' 2>/dev/null)
+
+# The parent auto-closes on merge to the default branch via `Closes #N`; ensure it, plus close every sub.
+for N in $NUM $SUBS; do
+  STATE=$(gh issue view "$N" --repo "$KIT_REPO" --json state --jq .state 2>/dev/null)
+  if [[ "$STATE" == "OPEN" ]]; then
+    gh issue close "$N" --repo "$KIT_REPO" \
+      --comment "Closed on merge of effort PR #$PR_NUM (parent #$NUM) — /kit-effort-close." \
+      && echo "✓ closed #$N"
+  else
+    echo "  #$N already ${STATE:-unknown} — skipped"
+  fi
+done
+
+# ── (d) BOARD: STATUS=DONE FOR PARENT + ALL SUBS ─────────────────────────────────────────
+# project_find_item_by_issue paginates the WHOLE board and fails loudly instead of returning empty.
+if [[ "$KIT_PROJECTS_V2" == "true" ]]; then
+  for N in $NUM $SUBS; do
+    ITEM=$(project_find_item_by_issue "$N") || { echo "  ⚠ board lookup failed for #$N (see stderr)"; continue; }
+    if [[ -n "$ITEM" ]]; then
+      project_set_single_select "$ITEM" "$STATUS_FIELD_ID" "$STATUS_OPT_DONE" && echo "✓ board Done: #$N"
+    else
+      echo "  ⚠ #$N not on board — skipped"
+    fi
+  done
+fi
+
+# ── (e) GC: trunk + prune the effort worktree/branch ─────────────────────────────────────
+WT=$(git worktree list --porcelain | awk -v b="refs/heads/$BRANCH" '/^worktree /{p=$2} /^branch /{if($2==b) print p}')
+MAIN_WT=$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')
+git -C "$MAIN_WT" checkout "$BASE" 2>/dev/null || git checkout "$BASE"
+git -C "$MAIN_WT" pull origin "$BASE" 2>/dev/null || git pull origin "$BASE"
+if [[ -n "$WT" && "$WT" != "$MAIN_WT" ]]; then
+  git worktree remove "$WT" --force && echo "✓ removed worktree $WT"
+fi
+git branch -D "$BRANCH" 2>/dev/null && echo "✓ deleted local branch $BRANCH"
+git push origin --delete "$BRANCH" 2>/dev/null && echo "✓ deleted remote branch $BRANCH" || echo "  (remote branch already gone)"
+git worktree prune
+
+# ── (f) KIT-SYNC DRIFT CHECK — kit ⇄ project stay in sync ─────────────────────────────────
+# If this effort changed kit-managed files, they likely belong upstream (/kit-contribute) — a
+# future /kit-update could otherwise clobber un-upstreamed fixes. Advisory; never blocks the close.
+KIT_TOUCHED=$(git -C "$MAIN_WT" show --name-only --pretty=format: HEAD 2>/dev/null \
+  | grep -E '^(scripts/(lib/|kit$|kit-)|\.claude/(skills|rules|hooks|lib|agents)/)' | sort -u || true)
+if [[ -n "$KIT_TOUCHED" ]]; then
+  echo ""
+  echo "⚠ kit-sync: this effort changed kit-managed files — review for upstream (/kit-contribute):"
+  printf '   %s\n' $KIT_TOUCHED
+  echo "   kit ⇄ project must stay in sync; an un-upstreamed change can be clobbered by /kit-update."
+fi
+
+echo "✓ effort #$NUM closed — merged, parent+subs Done, trace at ${TRACE_DIR:-<none>}, worktree pruned"
+```
+
+## Output
+
+- Pre-squash trace dir (`<git-common-dir>/traces/effort-<N>/` + `index.jsonl`)
+- PR squash-merged; parent + all native sub-issues closed
+- Board Status=Done for parent + every sub (if Projects v2 is on)
+- On the base branch, up to date; effort worktree + local/remote branch removed and pruned
+- A kit-sync warning if the effort touched kit-managed files
+
+## Rules
+
+- **Snapshot BEFORE squash — absolute** (step a). Squash destroys the per-sub-issue commit pairs
+  that ARE the per-unit work record. Never reorder a/b. The trace lives under the **shared
+  git-common-dir** so it survives the worktree prune in step e.
+- **One op owns board + issue + record state** — never rely on a separate, skippable "mark done"
+  (effort-model.md). All subs go Done here.
+- Never merge a draft PR — abort with instructions to undraft.
+- recover-before-prune (branch-naming.md): never remove a worktree with a staged-but-uncommitted
+  delta — the working tree must be clean (precondition) before this op proceeds.
+- Scrub secrets from the trace if any commit diff could contain them (trace hygiene).
+- Never force-push to trunk; never delete the default branch.
+- **Heed step (f):** a kit-managed change that isn't contributed upstream is a latent regression
+  the next `/kit-update` can revert. Treat the warning as a to-do.

package/skills/kit-effort-new/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: kit-effort-new
+description: Create an effort — a parent GitHub issue using the effort-model template (Goal / Scope / For agents / Verification) plus N native GitHub sub-issues linked via the sub-issues REST API, all added to the project board. The parent issue IS the plan.
+when_to_use: When starting a new unit of work (a "plan"/effort) that decomposes into several sub-tasks. Replaces ad-hoc `gh issue create` for multi-part work. The effort splits into native sub-issues at scoping time; sequential subs commit on the effort branch, parallel subs use file-disjoint worktrees and merge in. See rules/effort-model.md.
+---
+
+# kit-effort-new
+
+Plugin-direct skill — runs straight from `${CLAUDE_PLUGIN_ROOT}` (no per-project `scripts/` checkout
+needed). Helpers are sourced from the plugin; the verb logic lives in `scripts/lib/effort.sh`
+(`effort_link_sub`), never re-authored inline (kit-engine-boundary #1/#2). Repo + board config come
+from `load_kit_config` (`$KIT_REPO`, `KIT_PROJECTS_V2`). Reads `.claude/kit.config.json` from the
+working directory.
+
+Creates the **parent issue** (the plan) + **N native sub-issues** for one effort. See
+`rules/effort-model.md` for the model and the parent-issue template. GitHub is the single source of
+truth — the parent issue IS the plan (no separate plan file).
+
+## Inputs
+
+| Field        | Required | Notes                                                                                       |
+| ------------ | -------- | ------------------------------------------------------------------------------------------- |
+| Title        | ✓        | The human **name only** (no `[Effort]`/number prefix) — the skill composes the board title. Concise, no jargon (`effort_title_lint`) |
+| Role         | ✓        | `tech-lead` / `frontend` / … → `role:<role>` label + board Role field                       |
+| Flow         | optional | Controlled-vocab flow (`EFFORT_FLOWS`) → `[Flow]` title tag + `flow:<flow>` label            |
+| Goal         | ✓        | 1–2 lines — `## Goal`                                                                       |
+| Scope        | ✓        | The sub-issue DAG — `## Scope` (mark each parallel \| sequential)                           |
+| For agents   | ✓        | Exact file paths / entry points — `## For agents`                                           |
+| Verification | ✓        | How we know it's done — `## Verification`                                                   |
+| Sub-issues   | ✓        | List of `name :: one-line desc` — one per concern (the skill numbers + prefixes them)        |
+| Depends on   | optional | `#N` list → native GitHub `blocked_by` edge + a `## Relations` line (the visible chain)      |
+| Priority     | optional | `p0`–`p3` → `priority:<p>` label (default `p1`)                                             |
+| Milestone    | optional | Inherited onto the parent (sub-issues inherit it too)                                       |
+
+## Execution
+
+```bash
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/kit-config.sh" && load_kit_config
+[[ "$KIT_PROJECTS_V2" == "true" ]] && { source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/gh-project.sh"; load_project_ids; }
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/role-identity.sh" 2>/dev/null || true
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/effort.sh"
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/effort-metrics.sh"   # effort_ctx_bucket
+
+# TITLE = the human NAME only; the board title is composed as "[Effort] <N> · [<FLOW>] <TITLE>"
+# (N is injected after creation — it's the issue's own number). FLOW is an optional controlled-vocab tag.
+FLOW_TAG=""; [[ -n "${FLOW:-}" ]] && FLOW_TAG="[$FLOW] "
+
+# 0. Guard the title content BEFORE creating anything: concise, no jargon, valid flow tag.
+#    Lint with a placeholder number — the rule is about the NAME, not the (not-yet-assigned) N.
+effort_title_lint "[Effort] 0 · ${FLOW_TAG}${TITLE}" \
+  || { echo "✗ fix the effort title (above) before creating — concise / no-jargon / valid flow" >&2; return 1; }
+
+# 1. Compose the parent body (the 4 sections) + an optional ## Relations chain.
+RELATIONS=""
+if [[ -n "${DEPENDS_ON:-}" ]]; then
+  RELATIONS=$'\n\n## Relations\n'
+  for d in ${DEPENDS_ON//,/ }; do d="${d#\#}"; RELATIONS+="- Depends on #$d"$'\n'; done
+fi
+PARENT_BODY=$(cat <<EOF
+## Goal
+
+$GOAL
+
+## Scope
+
+$SCOPE
+
+## For agents
+
+$FOR_AGENTS
+
+## Verification
+
+$VERIFICATION$RELATIONS
+EOF
+)
+
+# 2. Create the parent issue (the plan). kind:task is the effort default unless overridden. Labels
+#    add `ctx:*` (session weight, first-pass from the sub count; refined at kit-effort-start) + an
+#    optional `flow:<flow>` tag.
+SUBCOUNT=$(printf '%s\n' "$SUBS" | grep -c . 2>/dev/null || echo 1); [[ "$SUBCOUNT" -ge 1 ]] || SUBCOUNT=1
+CTX="$(effort_ctx_bucket 1 "$SUBCOUNT")"
+FLOW_LABEL=""; [[ -n "${FLOW:-}" ]] && FLOW_LABEL=",flow:$(printf '%s' "$FLOW" | tr '[:upper:]' '[:lower:]')"
+PARENT_URL=$(gh issue create --repo "$KIT_REPO" \
+  --title "[Effort] PLACEHOLDER · ${FLOW_TAG}${TITLE}" \
+  --body "$PARENT_BODY" \
+  --label "$CTX,kind:task,priority:${PRIORITY:-p1},role:$ROLE$FLOW_LABEL" \
+  ${MILESTONE:+--milestone "$MILESTONE"})
+PARENT_NUM=$(basename "$PARENT_URL")
+# Inject the real effort id (== the issue number) into the title now that we have it.
+gh issue edit "$PARENT_NUM" --repo "$KIT_REPO" --title "[Effort] $PARENT_NUM · ${FLOW_TAG}${TITLE}" >/dev/null
+echo "✓ parent #$PARENT_NUM — $PARENT_URL"
+
+# 2b. Native dependency edges from DEPENDS_ON — the visible board chain.
+if [[ -n "${DEPENDS_ON:-}" ]]; then
+  for d in ${DEPENDS_ON//,/ }; do d="${d#\#}"; effort_set_blocked_by "$PARENT_NUM" "$d"; done
+fi
+
+# 3. Add the parent to the board, set Status=Todo + Role (if Projects v2 is enabled).
+if [[ "$KIT_PROJECTS_V2" == "true" ]]; then
+  PARENT_NODE=$(gh api "repos/$KIT_REPO/issues/$PARENT_NUM" --jq .node_id)
+  PARENT_ITEM=$(project_add_item "$PARENT_NODE" 2>/dev/null || echo "")
+  if [[ -n "$PARENT_ITEM" ]]; then
+    project_set_single_select "$PARENT_ITEM" "$STATUS_FIELD_ID" "$STATUS_OPT_TODO"
+    ROLE_OPT=$(role_option_id "$ROLE" 2>/dev/null || echo "")
+    [[ -n "$ROLE_OPT" ]] && project_set_single_select "$PARENT_ITEM" "$ROLE_FIELD_ID" "$ROLE_OPT"
+  fi
+fi
+
+# 4. Create each sub-issue, link it natively under the parent, add it to the board.
+#    SUBS is a newline-delimited list of "name :: one-line description". The skill numbers them
+#    1..k and composes the "[Effort <parent>] <M> · <name>" title (effort-model.md), linting each.
+#    Sub-issue bodies are intentionally short: the parent carries the narrative.
+SUB_M=0
+printf '%s\n' "$SUBS" | while IFS= read -r line; do
+  [[ -z "$line" ]] && continue
+  SUB_M=$((SUB_M + 1))
+  SUB_NAME="${line%% :: *}"
+  SUB_DESC="${line#* :: }"; [[ "$SUB_DESC" == "$line" ]] && SUB_DESC=""
+  SUB_TITLE="[Effort $PARENT_NUM] $SUB_M · $SUB_NAME"
+  effort_title_lint "$SUB_TITLE" \
+    || { echo "  ✗ sub title fails the rule (above) — rename and re-run: $SUB_TITLE" >&2; continue; }
+  SUB_URL=$(gh issue create --repo "$KIT_REPO" \
+    --title "$SUB_TITLE" \
+    --body "$SUB_DESC
+
+Sub-issue of #$PARENT_NUM (effort)." \
+    --label "kind:task,priority:${PRIORITY:-p1},role:$ROLE" \
+    ${MILESTONE:+--milestone "$MILESTONE"})
+  SUB_NUM=$(basename "$SUB_URL")
+  echo "  ✓ sub #$SUB_NUM — $SUB_TITLE"
+
+  # Native parent/child link via the sub-issues REST API (child DB id, not number).
+  effort_link_sub "$PARENT_NUM" "$SUB_NUM"
+
+  # Board: add sub, Status=Todo + Role.
+  if [[ "$KIT_PROJECTS_V2" == "true" ]]; then
+    SUB_NODE=$(gh api "repos/$KIT_REPO/issues/$SUB_NUM" --jq .node_id)
+    SUB_ITEM=$(project_add_item "$SUB_NODE" 2>/dev/null || echo "")
+    if [[ -n "$SUB_ITEM" ]]; then
+      project_set_single_select "$SUB_ITEM" "$STATUS_FIELD_ID" "$STATUS_OPT_TODO"
+      ROLE_OPT=$(role_option_id "$ROLE" 2>/dev/null || echo "")
+      [[ -n "$ROLE_OPT" ]] && project_set_single_select "$SUB_ITEM" "$ROLE_FIELD_ID" "$ROLE_OPT"
+    fi
+  fi
+done
+
+echo "✓ effort #$PARENT_NUM created — next: /kit-effort-start $PARENT_NUM"
+```
+
+## Output
+
+- Parent issue URL + number (the plan)
+- One line per sub-issue (number + title + native-link confirmation)
+- Parent + all subs on the board at Status=Todo with the Role field set (if Projects v2 is on)
+- Suggested next: `/kit-effort-start <parent>`
+
+## Rules
+
+- **The parent issue IS the plan** — never write a separate plan file; see `plan-output-format.md`.
+- **Titles pass `effort_title_lint`** — concise, plain-language outcome, optional `[Flow]` tag from
+  the controlled vocabulary; no jargon / glyphs / code identifiers / parentheses / sub-clauses /
+  >6 words. The skill refuses to create an effort whose title fails. Detail goes in the body.
+- **Carry the flow + the chain** — set `Flow` so the title shows `[Flow]` and the `flow:<flow>` label
+  is applied; pass `Depends on #N` so the native GitHub `blocked_by` edge + a `## Relations` line make
+  the chain visible on the board. `ctx:*` (session weight) is applied automatically.
+- The parent body MUST carry all four template sections (Goal / Scope / For agents / Verification) —
+  a missing section is a review blocker.
+- Sub-issues are **native** GitHub sub-issues (`POST …/issues/{parent}/sub_issues` with the child's
+  **database id**, resolved via `gh api repos/$KIT_REPO/issues/$N --jq .id`) — not just a checklist.
+- Sub-issue bodies stay short (one line) — the parent holds the narrative.
+- Never invent scope: ask for the sub-issue list if not provided.
+- Scrub secrets from any pasted path/snippet before it enters the issue body (trace hygiene).

package/skills/kit-effort-pr/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: kit-effort-pr
+description: Open the ONE pull request for an effort — `effort/<N>` → base branch — with a rich human-facing review body plus a `## For agents` section listing the file paths/entry points. Title `[Role] [#N] <title>`. Inherits labels + milestone from the parent issue and moves it to In Review on the board.
+when_to_use: When an effort branch is ready for review (all its sub-issues built + merged into the effort branch). One effort = one PR (effort-model.md) — never open per-sub PRs to the base branch. Mirrors `kit-task-pr` for the effort lifecycle.
+---
+
+# kit-effort-pr
+
+Plugin-direct skill — runs straight from `${CLAUDE_PLUGIN_ROOT}` (no per-project `scripts/` checkout
+needed). Helpers (config, role identity, board) are sourced from the plugin (kit-engine-boundary
+#1/#2). Respects `KIT_BASE_BRANCH` (default `main`) and the `KIT_PROJECTS_V2` board toggle.
+
+Opens the **single** PR for an effort. The PR carries the human-facing review write-up + a
+`## For agents` section (retrieval context / the work record). The parent issue holds the plan;
+this PR is where humans review the result. The title carries `[#N]` (the effort id) — mandatory
+(effort-model.md, effort-id taxonomy).
+
+## Inputs
+
+| Field          | Required | Notes                                                       |
+| -------------- | -------- | ----------------------------------------------------------- |
+| Issue number   | optional | The **parent** effort #N — derived from `effort/<N>-<slug>` |
+| Summary        | ✓        | The human review write-up (what changed + why)              |
+| For agents     | ✓        | File paths / entry points — the PR's `## For agents` block  |
+| Commit message | optional | Defaults to `<role>: <issue title>` for any pending changes |
+
+## Execution
+
+```bash
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/kit-config.sh" && load_kit_config
+[[ "$KIT_PROJECTS_V2" == "true" ]] && { source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/gh-project.sh"; load_project_ids; }
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/role-identity.sh" 2>/dev/null || true
+BASE="${KIT_BASE_BRANCH:-main}"
+
+# 1. Parse the parent effort number from the branch (effort/<N>-<slug>).
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+NUM="${INPUT_NUM:-}"
+[[ -z "$NUM" ]] && NUM=$(echo "$BRANCH" | sed -nE 's#^effort/([0-9]+)-.*#\1#p')
+[[ -z "$NUM" ]] && { echo "✗ Branch $BRANCH is not an effort branch (effort/<N>-<slug>)"; exit 1; }
+
+# 2. Pull parent issue metadata.
+META=$(gh issue view "$NUM" --repo "$KIT_REPO" --json title,labels,milestone)
+TITLE=$(echo "$META" | jq -r .title)
+LABELS=$(echo "$META" | jq -r '[.labels[].name] | join(",")')
+MILESTONE=$(echo "$META" | jq -r '.milestone.title // ""')
+ROLE=$(echo "$LABELS" | tr ',' '\n' | grep '^role:' | head -1 | cut -d: -f2)
+ROLE_DISPLAY=$(role_display "$ROLE" 2>/dev/null || echo ""); [[ -z "$ROLE_DISPLAY" ]] && ROLE_DISPLAY="Tech Lead"
+
+# 3. Commit any pending changes — role identity is a Co-authored-by TRAILER, never the git author
+#    (some deploy providers refuse commits whose author email matches no account).
+COMMIT_MSG="${COMMIT_MSG:-$ROLE: $TITLE}"
+if [[ -n "$(git status --porcelain)" ]]; then
+  git add -A
+  AUTHOR=$(role_git_author "$ROLE" 2>/dev/null || echo "")
+  if [[ -n "$AUTHOR" ]]; then
+    git commit -m "$COMMIT_MSG" -m "Co-authored-by: ${AUTHOR%%|*} <${AUTHOR##*|}>"
+  else
+    git commit -m "$COMMIT_MSG"
+  fi
+fi
+
+# 4. Push.
+git push -u origin "$BRANCH"
+
+# 5. Compose the PR body — rich human review + the agent-facing retrieval block.
+PR_BODY=$(cat <<EOF
+## For the orchestrator
+
+Effort #$NUM — one PR for the whole effort. Review: the summary below + the diff.
+
+Closes #$NUM
+
+## Summary
+
+$SUMMARY
+
+## For agents
+
+$FOR_AGENTS
+
+## Verification
+
+- [ ] Each sub-issue change is present in the diff
+- [ ] No unrelated files in the diff
+- [ ] Labels + milestone match the parent issue
+- [ ] Local lint/typecheck pass
+
+$(role_signature "$ROLE" 2>/dev/null || true)
+EOF
+)
+
+# 6. Create the PR. Title: [Role] [#N] <title> — the [#N] effort id is mandatory.
+URL=$(gh pr create --repo "$KIT_REPO" \
+  --base "$BASE" \
+  --head "$BRANCH" \
+  --title "[$ROLE_DISPLAY] [#$NUM] $TITLE" \
+  --body "$PR_BODY" \
+  ${LABELS:+--label "$LABELS"} \
+  ${MILESTONE:+--milestone "$MILESTONE"} \
+  --assignee "@me")
+echo "✓ $URL"
+
+# 7. Board (if Projects v2): add the PR (In Review) + inherit Role; move the parent issue to In Review.
+if [[ "$KIT_PROJECTS_V2" == "true" ]]; then
+  PR_NUM=$(basename "$URL")
+  PR_NODE=$(gh api "repos/$KIT_REPO/pulls/$PR_NUM" --jq .node_id)
+  PR_ITEM=$(project_add_item "$PR_NODE" 2>/dev/null || echo "")
+  if [[ -n "$PR_ITEM" ]]; then
+    ROLE_OPT=$(role_option_id "$ROLE" 2>/dev/null || echo "")
+    [[ -n "$ROLE_OPT" ]] && project_set_single_select "$PR_ITEM" "$ROLE_FIELD_ID" "$ROLE_OPT"
+    project_set_single_select "$PR_ITEM" "$STATUS_FIELD_ID" "$STATUS_OPT_IN_REVIEW"
+  fi
+  # Parent issue → In Review (the finder paginates the whole board, not just the first page).
+  PARENT_ITEM=$(project_find_item_by_issue "$NUM")
+  [[ -n "$PARENT_ITEM" ]] && project_set_single_select "$PARENT_ITEM" "$STATUS_FIELD_ID" "$STATUS_OPT_IN_REVIEW"
+fi
+
+echo "  Next: review, then /kit-effort-close $NUM"
+```
+
+## Output
+
+- The single effort PR URL (title `[Role] [#N] <title>`)
+- PR + parent issue both at In Review on the board (if Projects v2 is on)
+- Suggested next: `/kit-effort-close <N>`
+
+## Rules
+
+- **ONE PR per effort** — `effort/<N>` → base branch. Never open a PR from a `sub/<N><letter>`
+  branch to the base; sub-issues merge into the effort branch first (effort-model.md).
+- The title MUST carry `[#N]` (the effort id) — a PR title without it is a review blocker
+  (effort-model.md, effort-id taxonomy).
+- The body MUST include both a human `## Summary` and a `## For agents` (file paths) — the latter is
+  retrieval context + part of the work record.
+- `Closes #$NUM` closes the **parent** on merge; the sub-issues are closed by `/kit-effort-close`
+  (so their pre-squash diffs are snapshotted first).
+- Never invent a Summary or For-agents block — ask if missing.
+- Labels + milestone mirror the parent issue; never strip them.
+- Never push to a release branch directly.

package/skills/kit-effort-start/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: kit-effort-start
+description: Start an effort — create the `effort/<N>-<slug>` integration branch + isolated worktree from the base branch and mark the parent issue In Progress on the board. Sub-issues later branch from this effort branch or commit directly on it.
+when_to_use: After `/kit-effort-new`, to begin building an effort. The effort branch is the single integration branch for the whole effort — its sub-issues merge into it, and exactly one PR opens from it (`/kit-effort-pr`). See rules/effort-model.md.
+---
+
+# kit-effort-start
+
+Plugin-direct skill — runs straight from `${CLAUDE_PLUGIN_ROOT}` (no per-project `scripts/` checkout
+needed). Helpers are sourced from the plugin; repo state (`gh`, `git`, the board) is the project
+you're standing in. Respects `KIT_BASE_BRANCH` (default `main`) so the same code serves any project.
+Reads `.claude/kit.config.json` from the working directory.
+
+## Inputs
+
+| Field        | Required | Notes                                                          |
+| ------------ | -------- | -------------------------------------------------------------- |
+| Issue number | ✓        | The **parent** effort issue `N`                                |
+| Slug         | optional | Short kebab-case suffix; defaults to a slug of the issue title |
+
+> **One effort = one branch = one worktree** (effort-model.md). The branch is `effort/<N>-<slug>`
+> and the worktree is `.claude/worktrees/effort+<N>-<slug>`. Sub-issues either commit directly on
+> this branch (sequential — one commit per sub-issue, that commit's diff IS the sub's work record)
+> or use their own file-disjoint `sub/<N><letter>-<slug>` worktrees off this branch and merge in.
+> Exactly ONE PR opens from `effort/<N>` (`/kit-effort-pr`).
+
+## Execution
+
+```bash
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/kit-config.sh" && load_kit_config
+[[ "$KIT_PROJECTS_V2" == "true" ]] && { source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/gh-project.sh"; load_project_ids; }
+BASE="${KIT_BASE_BRANCH:-main}"   # branch off the integration branch (override per project)
+
+NUM=""; SLUG_OVERRIDE=""
+for a in "$@"; do
+  [[ -z "$NUM" ]] && NUM="$a" || SLUG_OVERRIDE="$a"
+done
+[[ -n "$NUM" ]] || { echo "✗ kit-effort-start: parent issue number required"; exit 1; }
+
+META=$(gh issue view "$NUM" --repo "$KIT_REPO" --json title,labels,projectItems)
+TITLE=$(echo "$META" | jq -r .title)
+
+if [[ -n "$SLUG_OVERRIDE" ]]; then SLUG="$SLUG_OVERRIDE"; else
+  SLUG=$(echo "$TITLE" | sed -E 's/^\[[^]]+\][[:space:]]*//' \
+    | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-|-$//g' | cut -c1-40)
+fi
+
+# The integration branch is ALWAYS effort/<N>-<slug> (branch-naming.md), regardless of the
+# parent's kind:* label. The worktree dir still encodes #N so kit-gc protects it while #N is open.
+BRANCH="effort/$NUM-$SLUG"
+WT_DIR=".claude/worktrees/effort+${NUM}-${SLUG}"
+
+git fetch origin "$BASE" --quiet
+if git worktree list --porcelain | grep -q "/effort+${NUM}-${SLUG}$"; then
+  echo "✓ Worktree already exists: $WT_DIR (branch $BRANCH)"
+else
+  git worktree add -B "$BRANCH" "$WT_DIR" "origin/$BASE"
+fi
+
+if [[ "$KIT_PROJECTS_V2" == "true" ]]; then
+  ITEM_ID=$(echo "$META" | jq -r --arg t "$KIT_PROJECT_TITLE" '.projectItems[]? | select(.title==$t) | .id')
+  [[ -n "$ITEM_ID" ]] && project_set_single_select "$ITEM_ID" "$STATUS_FIELD_ID" "$STATUS_OPT_IN_PROGRESS"
+fi
+
+echo "→ cd $WT_DIR   # ALL effort work happens here; sub-issues merge into $BRANCH"
+echo "✓ Worktree $WT_DIR on branch $BRANCH (from $BASE) — effort #$NUM In Progress"
+echo "  Next: build the sub-issues, then /kit-effort-pr $NUM"
+```
+
+## Output
+
+- Worktree path + `effort/<N>-<slug>` branch — **work continues inside the worktree** (`cd $WT_DIR`)
+- Parent issue #N now In Progress on the board (if Projects v2 is on)
+- Reminder that exactly one PR opens from this branch (`/kit-effort-pr <N>`)
+
+## Rules
+
+- The integration branch is **always** `effort/<N>-<slug>` (branch-naming.md, effort-model.md) —
+  never `task/` or `feat/` for the parent.
+- Branch from the base branch (`KIT_BASE_BRANCH`) only — never from a feature branch.
+- **Worktree always** — one branch per worktree, never share a checkout. The `effort+<N>-<slug>`
+  worktree-dir name encodes #N so `kit-gc` won't wipe it while the issue is open.
+- Sub-issue branches are `sub/<N><letter>-<slug>` off THIS branch and **never open their own PR to
+  the base branch** — they merge into `effort/<N>`.
+- Don't re-run for the parent if its worktree already exists — the skill reuses it.

package/skills/kit-gc/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: kit-gc
+description: Garbage-collect the repo — prune worktrees whose PR already merged, delete merged local + remote branches, surface orphan/unpushed commits and stale stashes, and flag issues whose PR merged but stayed open. Dry-run by default; destructive steps require explicit confirmation.
+when_to_use: When the repo has accumulated stale branches, orphan worktrees, or stashes (the SessionStart hygiene hook flags this), or on demand to tidy before/after a chapter of work. Replaces the manual cleanup sweep.
+---
+
+# kit-gc — repo garbage collector
+
+Plugin-direct skill — helpers resolve from `${CLAUDE_PLUGIN_ROOT}`.
+
+Cleans what accumulates: merged-but-undeleted branches (local + remote), orphan
+worktrees, stale stashes, orphan unpushed commits, and stale-open issues.
+
+**Safety contract:** read-only **analysis first** → present a plan → only delete
+after the user confirms. Never touch: the base branch (`main`/`develop`), branches
+with an **open PR**, worktrees of an open-PR branch, **a branch/worktree whose
+associated issue is still OPEN**, or branches/commits whose work is **not on the base
+branch's remote** (orphan work is surfaced, never auto-deleted).
+
+> **Worktree↔issue association.** A branch `<kind>/<N>-<slug>` (or worktree dir
+> `<kind>+<N>-<slug>`) belongs to issue **#N** — derived from the name, not registered.
+> `gc` resolves #N and **refuses to remove anything whose issue is still open, even
+> with no PR yet** — this protects in-progress worktrees that haven't opened a PR.
+> Helper: `${CLAUDE_PLUGIN_ROOT}/scripts/lib/worktree-issue.sh` (`wt_issue_number`, `wt_protected_reason`).
+
+## Execution
+
+### 1. Refresh + analyze (read-only)
+
+```bash
+# Read-only analysis lives in the CANONICAL Family-1 home — the skill is a thin caller (#419):
+#   scripts/lib/kit-gc.sh :: kit_gc_analyze   (also what `kit gc` + the kit-ui cockpit run)
+source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/kit-config.sh" && load_kit_config
+KIT_GC_REPO="$KIT_REPO" source "${CLAUDE_PLUGIN_ROOT}/scripts/lib/kit-gc.sh"
+kit_gc_analyze       # worktrees / branches / stashes, each tagged PROTECTED/SAFE/ACTIVE/ORPHAN
+```
+
+Classify every branch/worktree (issue-open protection wins over everything except an explicit force):
+
+| Bucket | Rule | Action |
+| --- | --- | --- |
+| **Protected (open issue)** | `wt_protected_reason` non-empty — associated issue **#N still OPEN** | **keep** — never prune, even with no PR / merged PR |
+| **Safe to delete** | PR `MERGED`, level with its remote (no unpushed commits), **and** issue closed/absent | prune |
+| **Active** | open PR, or the base branch, or a worktree branch with an open PR | keep |
+| **Orphan** | local commits **not on the base branch's remote** and no merged PR | **surface, never auto-delete** — offer to open a recovery PR |
+
+For squash-merged branches, `--is-ancestor` is unreliable — trust the **PR state**, then verify the branch is level with its remote (`git rev-list --count origin/<b>..<b>` = 0) before deleting.
+
+### 2. Present the plan
+
+Print a table: worktrees to remove, branches to delete (local + remote), orphans to recover, stashes to drop, and stale-open issues (PR merged but issue still open). **Ask for confirmation** before any destructive step. Let the user veto per-bucket.
+
+### 3. Execute (after confirmation)
+
+```bash
+# Worktrees whose PR merged
+git worktree remove <path> --force && git worktree prune
+# Merged branches — local then remote
+git branch -D <branch>
+git push origin --delete <branch>
+# Stale-open issues (PR already merged)
+gh issue close <n> --repo "$KIT_REPO" --reason completed --comment "Delivered via PR #<pr>."
+# Stashes — only after showing each diff and getting an explicit OK
+git stash drop 'stash@{n}'   # or: git stash clear
+```
+
+### 4. Orphan handling
+
+For each orphan branch with unique unpushed work: **do not delete**. Recover it
+into a clean PR off the base branch (branch from `$BASE`, `git checkout <orphan> --
+<paths>`, commit, push, open PR) so the user decides merge vs close.
+
+## Rules
+
+- **Dry-run + confirm by default.** Never delete without showing the plan first.
+- **Never** delete the base branch (`main`/`develop`) or an open-PR branch/worktree.
+- **Never** remove a worktree/branch whose **associated issue is still open** (`wt_protected_reason` non-empty) — close the issue first, or pass an explicit per-item override.
+- **Never** drop a stash or delete an orphan branch without explicit per-item consent (stashes and unpushed commits are irreversible).
+- Verify a branch is **level with its remote** before deleting — an "ahead" branch may hold orphan work.
+- Prefer enabling GitHub **"Automatically delete head branches"** so remote pruning stops being a manual step.