claude-dev-env 2.4.0 → 2.5.0

package/skills/e-code-review/reference/medium.md

@@ -0,0 +1,153 @@
+`medium effort → 3+5 angles → 1-vote verify`
+
+You are reviewing for **precision** at medium effort: every finding you surface
+should be one a maintainer would act on.
+
+## Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+## Phase 1 — Find candidates (3 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle)
+
+Run **8 independent finder angles** via the Agent tool. Each surfaces
+candidate findings with `file`, `line`, a one-line `summary`, and a concrete
+`failure_scenario`. If the Agent tool is not available in your current tool
+set, do not error — perform each angle (and each verification) yourself,
+sequentially, in this context.
+
+### Angle A — line-by-line diff scan
+
+Read every hunk in the diff, line by line. Then Read the enclosing function for
+each hunk — bugs in unchanged lines of a touched function are in scope (the PR
+re-exposes or fails to fix them). For every line ask: what input, state, timing,
+or platform makes this line wrong? Look for inverted/wrong conditions,
+off-by-one, null/undefined deref, missing `await`, falsy-zero checks,
+wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
+
+### Angle B — removed-behavior auditor
+
+For every line the diff DELETES or replaces, name the invariant or behavior it
+enforced, then search the new code for where that invariant is re-established.
+If you can't find it, that's a candidate: a removed guard, a dropped error
+path, a narrowed validation, a deleted test that was covering a real case.
+
+### Angle C — cross-file tracer
+
+For each function the diff changes, find its callers (Grep for the symbol) and
+check whether the change breaks any call site: a new precondition, a changed
+return shape, a new exception, a timing/ordering dependency. Also check callees:
+does a parallel change in the same PR make a call unsafe?
+
+### Reuse
+
+The angles above hunt for bugs; this one and the next two hunt for cleanup in
+the changed code. Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+### Altitude
+
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
+
+### Conventions (CLAUDE.md)
+
+Find the CLAUDE.md files that govern the changed code: the user-level
+~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any CLAUDE.md or
+CLAUDE.local.md in a directory that is an ancestor of a changed file (a
+directory's CLAUDE.md only applies to files at or below it). Read each one
+that exists, then check the diff for clear violations of the rules they state.
+
+Only flag a violation when you can quote the exact rule and the exact line
+that breaks it — no style preferences, no vague "spirit of the doc"
+inferences. In the finding, name the CLAUDE.md path and quote the rule so the
+report can cite it. If no CLAUDE.md applies, return nothing for this angle.
+
+Cleanup, altitude, and conventions candidates use the same
+`file`/`line`/`summary` shape; in `failure_scenario`, state the concrete
+cost (what is duplicated, wasted, harder to maintain, or which CLAUDE.md rule
+is broken) instead of a crash. Correctness bugs always outrank cleanup,
+altitude, and conventions findings.
+
+Pass every candidate with a nameable failure scenario through — finders that
+silently drop half-believed candidates bypass the verify step and are the
+dominant cause of misses.
+
+## Phase 2 — Verify (1-vote, 3-state)
+
+Dedup candidates that point at the same line/mechanism, keeping the one with
+the most concrete failure scenario. For each remaining candidate, run **one
+verifier** via the Agent tool: give it the diff, the relevant
+file(s), and the candidate, and have it return exactly one of:
+
+- **CONFIRMED** — can name the inputs/state that trigger it and the wrong
+  output or crash. Quote the line.
+- **PLAUSIBLE** — mechanism is real, trigger is uncertain (timing, env,
+  config). State what would confirm it.
+- **REFUTED** — factually wrong (code doesn't say that) or guarded elsewhere.
+  Quote the line that proves it.
+
+Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
+
+## Output
+
+Report this review's results — `{level, findings}` — through the structured
+findings-report call: the mechanism that renders a review's results as a typed
+list in the host UI, ranked most-severe first. Each entry has `file`, `line`,
+`summary`, `short_summary` — the claim compressed to ≤60 characters, no
+rationale or consequence clause — `failure_scenario`, and `category` — a short
+kebab-case slug for the angle that produced it (`correctness`,
+`simplification`, `efficiency`, `reuse`, `altitude`, `conventions`, or a more
+specific slug like `test-coverage` when one fits better) — plus `verdict` when
+a verify pass produced one. If nothing survives verification, make that call
+with an empty array. Do not also print the findings as text, and do not create
+or publish an artifact of the review — the structured call is the report.
+
+## Applying fixes (--fix)
+
+The `--fix` flag was passed. Follow `reference\fix.md` (relative to this
+skill's folder) for the exact fix, commit-gate, and skip-handling behavior —
+it governs which agent applies each fix, how a fix gets committed, how a skip
+is logged, and how outcomes get reported. Do not repeat the findings as text;
+follow that document's reporting rules once fixes land.
+
+## If findings are fixed later
+
+Whenever a reported finding is fixed later in this session — the user asks you
+to fix it, or later work fixes it incidentally — follow `reference\fix.md`'s
+reporting rules again: report the same findings through the structured
+findings-report call, each carrying an `outcome`. Do not repeat the findings
+as text. Make that call immediately after the fixes land, before any prose
+summary; the host UI's per-finding status updates only from that call.
+
+## Looping (`loop`)
+
+The `loop` arg was passed. Follow `reference\loop.md` (relative to this
+skill's folder) for how to re-run Phases 0–2, Output, and (if `--fix` is also
+present) `reference\fix.md`'s fix pass, repeatedly — including its exit
+condition, iteration cap, and re-invocation rules. Do not treat a single pass
+through this document as complete while `loop` is active; hand control to that
+document instead of stopping at Output.

package/skills/e-code-review/reference/xhigh.md

@@ -0,0 +1,182 @@
+`xhigh effort → 5+5 angles → 1-vote verify → sweep`
+
+You are reviewing for **recall** at extra-high effort: catch every real bug. At
+this level, catching real bugs matters more than avoiding false positives — a
+missed bug ships. Err on the side of surfacing.
+
+## Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+## Phase 1 — Find candidates (5 correctness angles + 3 cleanup angles + 1 altitude angle + 1 conventions angle)
+
+Run **10 independent finder angles** via the Agent tool. Each surfaces
+candidate findings. Do NOT let one angle's conclusions suppress another's — if
+two angles flag the same line for different reasons, record both. If the Agent
+tool is not available in your current tool set, do not error — perform each
+angle (and each verification) yourself, sequentially, in this context.
+
+### Angle A — line-by-line diff scan
+
+Read every hunk in the diff, line by line. Then Read the enclosing function for
+each hunk — bugs in unchanged lines of a touched function are in scope (the PR
+re-exposes or fails to fix them). For every line ask: what input, state, timing,
+or platform makes this line wrong? Look for inverted/wrong conditions,
+off-by-one, null/undefined deref, missing `await`, falsy-zero checks,
+wrong-variable copy-paste, error swallowed in catch, unescaped regex metachars.
+
+### Angle B — removed-behavior auditor
+
+For every line the diff DELETES or replaces, name the invariant or behavior it
+enforced, then search the new code for where that invariant is re-established.
+If you can't find it, that's a candidate: a removed guard, a dropped error
+path, a narrowed validation, a deleted test that was covering a real case.
+
+### Angle C — cross-file tracer
+
+For each function the diff changes, find its callers (Grep for the symbol) and
+check whether the change breaks any call site: a new precondition, a changed
+return shape, a new exception, a timing/ordering dependency. Also check callees:
+does a parallel change in the same PR make a call unsafe?
+
+### Angle D — language-pitfall specialist
+
+Scan for the classic pitfalls of the diff's language/framework — for example:
+JS falsy-zero, `==` coercion, closure-captured loop var; Python mutable default
+args, late-binding closures; Go nil-map write, range-var capture; SQL injection;
+timezone/DST drift; float equality. Flag any instance the diff introduces.
+
+### Angle E — wrapper/proxy correctness
+
+When the PR adds or modifies a type that wraps another (cache, proxy, decorator,
+adapter): check that every method routes to the wrapped instance and not back
+through a registry/session/global — e.g. a caching provider holding a
+`delegate` field that resolves IDs via `session.get(...)` instead of
+`delegate.get(...)` will re-enter the cache or recurse. Also check that the
+wrapper forwards all the methods the callers actually use.
+
+### Reuse
+
+The angles above hunt for bugs; this one and the next two hunt for cleanup in
+the changed code. Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+### Altitude
+
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
+
+### Conventions (CLAUDE.md)
+
+Find the CLAUDE.md files that govern the changed code: the user-level
+~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any CLAUDE.md or
+CLAUDE.local.md in a directory that is an ancestor of a changed file (a
+directory's CLAUDE.md only applies to files at or below it). Read each one
+that exists, then check the diff for clear violations of the rules they state.
+
+Only flag a violation when you can quote the exact rule and the exact line
+that breaks it — no style preferences, no vague "spirit of the doc"
+inferences. In the finding, name the CLAUDE.md path and quote the rule so the
+report can cite it. If no CLAUDE.md applies, return nothing for this angle.
+
+Cleanup, altitude, and conventions candidates use the same
+`file`/`line`/`summary` shape; in `failure_scenario`, state the concrete
+cost (what is duplicated, wasted, harder to maintain, or which CLAUDE.md rule
+is broken) instead of a crash. Correctness bugs always outrank cleanup,
+altitude, and conventions findings.
+
+## Phase 2 — Verify (1-vote, 3-state)
+
+Dedup candidates that point at the same line/mechanism, keeping the one with
+the most concrete failure scenario. For each remaining candidate, run **one
+verifier** via the Agent tool: give it the diff, the relevant
+file(s), and the candidate, and have it return exactly one of:
+
+- **CONFIRMED** — can name the inputs/state that trigger it and the wrong
+  output or crash. Quote the line.
+- **PLAUSIBLE** — mechanism is real, trigger is uncertain (timing, env,
+  config). State what would confirm it.
+- **REFUTED** — factually wrong (code doesn't say that) or guarded elsewhere.
+  Quote the line that proves it.
+
+Keep candidates where the vote is CONFIRMED or PLAUSIBLE.
+
+This is recall mode — a single non-REFUTED vote carries the finding. Do NOT
+drop on uncertainty.
+
+## Phase 3 — Sweep for gaps
+
+Run **one more finder** as a fresh reviewer who has the verified list. Re-read
+the diff and enclosing functions looking ONLY for defects not already listed.
+Do not re-derive or re-confirm anything already there — the job is gaps. Focus
+on what the first pass tends to miss: moved/extracted code that dropped a guard
+or anchor; second-tier footguns (dataclass default evaluated once, `hash()`
+non-determinism, lock-scope shrink, predicate methods with side effects);
+setup/teardown asymmetry in tests; config defaults flipped.
+
+Surface additional candidates, each naming a defect not already on the list.
+If nothing new, return an empty sweep — do not pad.
+
+## Output
+
+Report this review's results — `{level, findings}` — through the structured
+findings-report call: the mechanism that renders a review's results as a typed
+list in the host UI, ranked most-severe first. Each entry has `file`, `line`,
+`summary`, `short_summary` — the claim compressed to ≤60 characters, no
+rationale or consequence clause — `failure_scenario`, and `category` — a short
+kebab-case slug for the angle that produced it (`correctness`,
+`simplification`, `efficiency`, `reuse`, `altitude`, `conventions`, or a more
+specific slug like `test-coverage` when one fits better) — plus `verdict` when
+a verify pass produced one. If nothing survives verification, make that call
+with an empty array. Do not also print the findings as text, and do not create
+or publish an artifact of the review — the structured call is the report.
+
+## Applying fixes (--fix)
+
+The `--fix` flag was passed. Follow `reference\fix.md` (relative to this
+skill's folder) for the exact fix, commit-gate, and skip-handling behavior —
+it governs which agent applies each fix, how a fix gets committed, how a skip
+is logged, and how outcomes get reported. Do not repeat the findings as text;
+follow that document's reporting rules once fixes land.
+
+## If findings are fixed later
+
+Whenever a reported finding is fixed later in this session — the user asks you
+to fix it, or later work fixes it incidentally — follow `reference\fix.md`'s
+reporting rules again: report the same findings through the structured
+findings-report call, each carrying an `outcome`. Do not repeat the findings
+as text. Make that call immediately after the fixes land, before any prose
+summary; the host UI's per-finding status updates only from that call.
+
+## Looping (`loop`)
+
+The `loop` arg was passed. Follow `reference\loop.md` (relative to this
+skill's folder) for how to re-run Phases 0–3, Output, and (if `--fix` is also
+present) `reference\fix.md`'s fix pass, repeatedly — including its exit
+condition, iteration cap, and re-invocation rules. Do not treat a single pass
+through this document as complete while `loop` is active; hand control to that
+document instead of stopping at Output.

package/skills/e-simplify/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: e-simplify
+description: >-
+  Cleanup-only pass on the current diff — reuse, simplification, efficiency,
+  altitude — that fixes what it finds directly; no correctness-bug hunting.
+  Triggers: /e-simplify.
+---
+
+# e-simplify
+
+**Core principle:** Four parallel cleanup angles (reuse, simplification, efficiency, altitude) over the current diff, applied directly — not a bug hunt, and not a report.
+
+## Gotchas
+
+- This skill fixes code quality, not correctness. A request for bug-hunting belongs to `/e-code-review`, not here — see the refusal case below.
+- Applying a fix that changes intended behavior, or that reaches well outside the reviewed diff, is worse than leaving a flagged item unfixed — skip and note it instead of stretching the fix to cover it.
+
+## When this skill applies
+
+Triggers: `/e-simplify` on the current diff (or a PR/branch/path passed as an argument).
+
+**Refusal cases — first match wins:**
+
+- **Asked to find correctness bugs (crashes, wrong output, security issues) rather than cleanup.** Respond exactly: `That's a correctness review — use /e-code-review, not this skill.`
+
+## The process
+
+`/simplify → 4 cleanup agents in parallel → apply the fixes`
+
+You are improving the quality of the changed code, not hunting for bugs. Review
+it for reuse, simplification, efficiency, and altitude issues, then fix what you
+find. Do not look for correctness bugs — that is what `/code-review` is for.
+
+### Phase 0 — Gather the diff
+
+Run `git diff @{upstream}...HEAD` (or `git diff main...HEAD` / `git diff HEAD~1`
+if there's no upstream) to get the unified diff under review. If there are
+uncommitted changes, or the range diff is empty, also run `git diff HEAD` and
+include the working-tree changes in scope — the review often runs before the
+commit. If a PR number, branch name, or file path was passed as an argument,
+review that target instead. Treat this diff as the review scope.
+
+### Phase 1 — Review (4 cleanup agents in parallel)
+
+Launch **4 independent review agents** via the Agent tool, all in a
+single message so they run concurrently. Pass each agent the diff and one of
+the four angles below. Each returns its findings with `file`, `line`, a
+one-line `summary`, and the concrete cost (what is duplicated, wasted, or
+harder to maintain).
+
+#### Reuse
+
+Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
+
+#### Simplification
+
+Flag unnecessary complexity the diff adds: redundant or derivable state,
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
+
+#### Efficiency
+
+Flag wasted work the diff introduces: redundant computation or repeated I/O,
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+alternative.
+
+#### Altitude
+
+Check that each change is implemented at the right depth, not as a fragile
+bandaid. Special cases layered on shared infrastructure are a sign the fix
+isn't deep enough — prefer generalizing the underlying mechanism over adding
+special cases.
+
+### Phase 2 — Apply the fixes
+
+Wait for all four agents to complete, dedup findings that point at the same
+line or mechanism, and fix each remaining one directly. Skip any finding whose
+fix would change intended behavior, require changes well outside the reviewed
+diff, or that you judge to be a false positive — note the skip rather than
+arguing with it. Finish with a brief summary of what was fixed and what was
+skipped (or confirm the code was already clean).
+
+## File index
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | This hub — the full cleanup procedure, refusal case |
+
+## Folder map
+
+- `SKILL.md` — hub: full procedure, refusal case.

package/skills/issue-tracker/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: issue-tracker
+description: >-
+  File, update, and close GitHub work as one epic with native sub-issues.
+  Dedup open and closed issues first. Edit status only inside marker sections.
+  Refresh the epic checklist so it matches its children. Triggers: issue tracker,
+  file an issue, track this issue, open an epic, update the epic, close the issue,
+  refresh the epic checklist, attach a sub-issue.
+argument-hint: "[issue action - file | update | close | refresh-epic | full handoff]"
+---
+
+# Issue tracker
+
+**User wants an issue action done. Here is how those actions work.**
+
+**dedup -> do the work -> markers only -> numbers + URLs**
+
+Run every step the ask needs in one go (file, label, attach, refresh, and so on). The `issue-tracker` agent is the primary handler for one action per turn; this skill is the session path when the agent is unavailable or the ask spans several steps.
+
+Prefer the **same warm** `issue-tracker` agent for follow-ups on the same issue or a related issue on the same epic. Spawn a new agent only for an unrelated work-stream or when the warm agent is gone.
+
+## Voice
+
+Use the `plain-brief` output style (`output-styles/plain-brief.md`). End with the issue number(s) and URL(s) the caller must keep.
+
+## Gotchas
+
+Append a bullet when an action fails in a new way.
+
+- Use REST `.id`, not display `#N`, to attach a sub-issue - [operation-matrix](reference/operation-matrix.md).
+- `gh` attach: `-F sub_issue_id=<n>` (typed int), never `-f`.
+- Status goes in markers, not comments - comments are cross-links only.
+- Dedup open **and** closed; closed twin -> reopen vs file new, never silent refile.
+- Edit only between markers - free-form epic edits break the children checklist.
+- Auto-close is PR-body-first: a related-only UI link does not close the issue on merge.
+
+## The model
+
+One **epic** issue owns a work-stream. Each unit of work is a native GitHub **sub-issue** under it. The epic checklist and every status block live inside marker pairs. Skeletons and refresh steps: [reference/epic-and-sub-issue-model.md](reference/epic-and-sub-issue-model.md).
+
+## Labels
+
+- Parent: `epic`.
+- Sub-issue: `type: roadblock`, `type: task`, `type: bug`, or `type: enhancement`.
+
+Create a missing label, then apply it. Label create is in the operation matrix.
+
+## Markers
+
+- Status (any issue): `<!-- issue-tracker:status -->` … `<!-- /issue-tracker:status -->`
+- Children checklist (epic only): `<!-- issue-tracker:children -->` … `<!-- /issue-tracker:children -->`
+
+Update path: read body -> replace only the text between the target pair -> write the full body back.
+
+## Dedup
+
+Search open and closed issues on the target repo before create. Open twin -> update in place. Closed twin -> ask reopen vs file new.
+
+## Tools
+
+Prefer GitHub MCP. Fall back to `gh` on the same REST endpoints. Full map and `.id` rule: [reference/operation-matrix.md](reference/operation-matrix.md).
+
+## Handoff input
+
+Optional issue-candidate JSON from orchestrator or closeout. Full schema and consume path: [reference/handoff-schema.md](reference/handoff-schema.md).
+
+## Close the sub-issue through the PR (required when a fix ships)
+
+GitHub closes the sub-issue when someone **merges** a pull request into the **default branch** and that PR carries a closing keyword for the issue.
+
+**Required on the PR that merges into the default branch:** put `Closes #N` in the PR body for each finished sub-issue. One keyword per issue: write `Closes #12` and `Closes #13`, not `Closes #12, #13` (only the first number closes in the comma form).
+
+**Preferred on commits:** also put `Closes #N` in the first commit message when the fix starts. Commit alone is backup; the PR body is the contract.
+
+**Stacked / intermediate PRs** that do not merge into the default branch: use a plain `#N` reference in the body so the issue links without a false close promise. Put `Closes #N` only on the PR that actually lands on the default branch.
+
+**Not enough:** a Development "related" link with no closing keyword. **Not enough:** closing the PR without merging.
+
+**Who owns `#N`:** the agent or session writing the PR must use the correct sub-issue number. Nothing in this package verifies the number matches the fix.
+
+## Return shape
+
+Reply with every affected issue number and URL - no narration after that payload.
+
+## File index
+
+| File | Purpose |
+|------|---------|
+| `SKILL.md` | Hub: how issue actions work, gotchas, model, markers, dedup, PR auto-close, return shape |
+| `reference/operation-matrix.md` | MCP + `gh` per action; sub-issue `.id` rule |
+| `reference/epic-and-sub-issue-model.md` | Epic model, markers, body skeleton, checklist refresh |
+| `reference/handoff-schema.md` | Issue-candidate JSON and consume flow |

package/skills/issue-tracker/reference/epic-and-sub-issue-model.md

@@ -0,0 +1,55 @@
+# Epic and sub-issue model
+
+One **epic** issue holds a whole work-stream. Each unit of work under it is a native GitHub **sub-issue**. The epic carries the `epic` label; each sub-issue carries a `type:` label. The epic body mirrors its children as a checklist, and every issue — epic and sub-issue alike — carries a status section. Both sections live between marker comments so a body edit can replace one section and leave the rest untouched.
+
+## The two marker pairs
+
+- `<!-- issue-tracker:status -->` … `<!-- /issue-tracker:status -->` — on every issue. Holds the current status line.
+- `<!-- issue-tracker:children -->` … `<!-- /issue-tracker:children -->` — on the epic only. Holds the checklist of sub-issues.
+
+An edit reads the whole body, swaps only the text between one marker pair, and writes the whole body back. Text outside the markers stays byte-for-byte the same.
+
+## Epic body skeleton
+
+```markdown
+## Epic — <work-stream label>
+
+<One sentence naming the work-stream and its goal.>
+
+<!-- issue-tracker:status -->
+Status: in progress — 1 of 3 children closed.
+<!-- /issue-tracker:status -->
+
+<!-- issue-tracker:children -->
+- [x] owner/repo#12 — parser rejects an empty path
+- [ ] owner/repo#13 — attach reads the display number
+- [ ] owner/repo#14 — label create skips an existing label
+<!-- /issue-tracker:children -->
+```
+
+## Sub-issue body skeleton
+
+```markdown
+## <sub-issue title>
+
+<One sentence: what the work is.>
+
+<!-- issue-tracker:status -->
+Status: open.
+<!-- /issue-tracker:status -->
+
+## Detail
+
+<The evidence, where, impact, and proposed fix — self-contained.>
+```
+
+## Refresh the epic checklist
+
+After you create a sub-issue or close one, refresh the epic's `children` section so it matches the children:
+
+1. Read the epic body.
+2. Add a `- [ ] owner/repo#<N> — <title>` line for a newly created sub-issue, or flip a line to `- [x]` for a closed one.
+3. Update the epic's status line to name the closed count against the total.
+4. Write the whole body back with the issue-update op, replacing only the two marker sections you touched.
+
+A created or closed sub-issue always triggers this refresh, so the epic checklist stays in step with the sub-issues at every step.

package/skills/issue-tracker/reference/handoff-schema.md

@@ -0,0 +1,64 @@
+# Handoff schema
+
+An orchestrator or the closeout skill hands the tracker one **issue-candidate** JSON record per obstacle. The tracker consumes each record through the full path and returns the issue number and URL.
+
+## The record
+
+```json
+{
+  "kind": "roadblock | task | bug | enhancement",
+  "title": "<short imperative title>",
+  "epic": "<work-stream label the sub-issue belongs under>",
+  "summary": "<one sentence a reader with zero session context acts on>",
+  "evidence": "<verbatim line captured this session — error text, command, or log line>",
+  "where": "<file, hook, gate, or tool the evidence names — path relative to the repo root>",
+  "impact": "<what the obstacle cost: work blocked, count of times hit, workaround forced>",
+  "proposed_fix": "<the specific change — name the failure mode and the condition>",
+  "blocking": true
+}
+```
+
+## Field meanings
+
+| Field | Meaning |
+|-------|---------|
+| `kind` | The sub-issue's `type:` label stem. `roadblock`, `task`, `bug`, or `enhancement`. |
+| `title` | The sub-issue title. Short and imperative. |
+| `epic` | The work-stream the sub-issue belongs under. The tracker finds or creates the matching epic. |
+| `summary` | The one-sentence body opener. Self-contained — a reader with no session context acts on it. |
+| `evidence` | A verbatim line captured this session, placed in a fenced block in the body. |
+| `where` | The file, hook, gate, or tool the evidence names. A repo-relative path, no volatile temp path. |
+| `impact` | What the obstacle cost. |
+| `proposed_fix` | The specific change. |
+| `blocking` | `true` routes the sub-issue to `type: roadblock`, overriding `kind`. `false` keeps the `kind` label. |
+
+`kind` maps to the `type:` label. `blocking: true` takes precedence and routes the sub-issue to `type: roadblock`.
+
+## Filled example
+
+```json
+{
+  "kind": "bug",
+  "title": "Inline-collection gate fires in exempt test files",
+  "epic": "hook exemptions for test files",
+  "summary": "The code_rules_enforcer inline-collection check blocks a valid list literal in a test file, where test files are exempt from the magic-value gate.",
+  "evidence": "BLOCKED: [MAGIC_VALUE] Inline list literal [200, 404, 500] in a function body -- extract to a named constant in config/.",
+  "where": "packages/claude-dev-env/hooks/blocking/code_rules_enforcer.py",
+  "impact": "Hit 3 times in one session on three test files; each forced a workaround move to a module constant.",
+  "proposed_fix": "Extend the magic-value test-file exemption to cover the inline-collection check, so list and set literals in test bodies pass.",
+  "blocking": false
+}
+```
+
+## Consume flow
+
+For each record, in order:
+
+1. **Dedup** — search open and closed issues on the target repository for a twin.
+2. **Find or create the epic** — match the `epic` label; open a parent with the `epic` label when none matches.
+3. **Create the sub-issue** — body from `summary`, `evidence`, `where`, `impact`, `proposed_fix`.
+4. **Labels** — apply the `type:` label from `kind`, or `type: roadblock` when `blocking` is `true`. Create the label when the repository lacks it.
+5. **Attach the native sub-issue** — read the child's REST database `.id` and attach it under the epic.
+6. **Refresh the epic checklist** — add the child's `- [ ] owner/repo#<N>` line and update the epic status.
+
+The return is the sub-issue number and URL (and the epic number and URL when the epic was created this call).