claude-dev-env 2.4.0 → 2.7.0

package/skills/fresh-branch/scripts/test_create_fresh_branch.py

@@ -245,28 +245,23 @@ class TestResolveAgentSlug:
 
 
 class TestResolveAgentWorktreeRoot:
-    def should_use_userprofile_scratch_on_windows(
+    def should_nest_under_the_repository_claude_worktrees_directory(
         self,
-        monkeypatch: pytest.MonkeyPatch,
+        tmp_path: Path,
     ) -> None:
         module = load_create_fresh_branch_module()
-        monkeypatch.setattr(module.sys, "platform", "win32")
-        monkeypatch.setenv("USERPROFILE", r"C:\Users\example")
-        worktree_root = module.resolve_agent_worktree_root("grok")
-        assert worktree_root == (
-            Path(r"C:\Users\example") / "AppData" / "Local" / "Temp" / "grok"
-        )
+        worktree_root = module.resolve_agent_worktree_root(tmp_path, "grok")
+        assert worktree_root == tmp_path / ".claude" / "worktrees" / "grok"
 
-    def should_fall_back_to_gettempdir_off_windows(
+    def should_keep_each_agent_in_its_own_subdirectory(
         self,
-        monkeypatch: pytest.MonkeyPatch,
         tmp_path: Path,
     ) -> None:
         module = load_create_fresh_branch_module()
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(module.tempfile, "gettempdir", lambda: str(tmp_path))
-        worktree_root = module.resolve_agent_worktree_root("claude")
-        assert worktree_root == tmp_path / "claude"
+        grok_root = module.resolve_agent_worktree_root(tmp_path, "grok")
+        claude_root = module.resolve_agent_worktree_root(tmp_path, "claude")
+        assert grok_root != claude_root
+        assert grok_root.parent == claude_root.parent
 
 
 class TestResolveUniqueWorktreePath:
@@ -301,18 +296,9 @@ class TestAgentSlugPathSafety:
     def should_reject_parent_segment_agent_slug_without_mkdir_outside(
         self,
         tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         module = load_create_fresh_branch_module()
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
-        escaped_agent_root = (agent_scratch_parent / ".." / "escape-agent").resolve()
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
+        escaped_agent_root = (tmp_path / "escape-agent").resolve()
         with pytest.raises(ValueError, match="agent slug"):
             module.create_fresh_branch(
                 branch_name="fix/safe-branch",
@@ -321,22 +307,13 @@ class TestAgentSlugPathSafety:
                 base_ref=DEFAULT_BASE_REF,
             )
         assert not escaped_agent_root.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()
 
     def should_reject_empty_agent_slug(
         self,
         tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         module = load_create_fresh_branch_module()
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         with pytest.raises(ValueError, match="agent slug"):
             module.create_fresh_branch(
                 branch_name="fix/safe-branch",
@@ -344,25 +321,16 @@ class TestAgentSlugPathSafety:
                 agent_slug="",
                 base_ref=DEFAULT_BASE_REF,
             )
-        assert not any(agent_scratch_parent.iterdir())
+        assert not (tmp_path / "unused-repo").exists()
 
 
 class TestBranchNamePathSafety:
     def should_reject_parent_segments_without_mkdir_outside(
         self,
         tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         module = load_create_fresh_branch_module()
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
-        escaped_path = agent_scratch_parent / "escape"
+        escaped_path = tmp_path / "escape"
         with pytest.raises(ValueError, match="relative path"):
             module.create_fresh_branch(
                 branch_name="fix/../../escape",
@@ -371,23 +339,14 @@ class TestBranchNamePathSafety:
                 base_ref=DEFAULT_BASE_REF,
             )
         assert not escaped_path.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()
 
     def should_reject_absolute_branch_without_mkdir_outside(
         self,
         tmp_path: Path,
-        monkeypatch: pytest.MonkeyPatch,
     ) -> None:
         module = load_create_fresh_branch_module()
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
         outside_target = tmp_path / "outside-evil"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         with pytest.raises(ValueError, match="relative path"):
             module.create_fresh_branch(
                 branch_name=str(outside_target),
@@ -396,7 +355,7 @@ class TestBranchNamePathSafety:
                 base_ref=DEFAULT_BASE_REF,
             )
         assert not outside_target.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()
 
 
 class TestCreateFreshBranchIntegration:
@@ -409,13 +368,6 @@ class TestCreateFreshBranchIntegration:
         repository_path = build_repo_with_origin(tmp_path / "repo")
         caller_head_before = read_head_branch(repository_path)
         caller_commit_before = read_head_commit(repository_path)
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         success_payload = module.create_fresh_branch(
             branch_name="fix/example-one",
             repo_path=repository_path,
@@ -424,7 +376,14 @@ class TestCreateFreshBranchIntegration:
         )
         worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
         assert worktree_path.is_dir()
-        assert worktree_path == agent_scratch_parent / "grok" / "fix" / "example-one"
+        assert worktree_path == (
+            repository_path.resolve()
+            / ".claude"
+            / "worktrees"
+            / "grok"
+            / "fix"
+            / "example-one"
+        )
         assert read_head_branch(worktree_path) == "fix/example-one"
         assert read_head_commit(worktree_path) == caller_commit_before
         assert success_payload[PAYLOAD_KEY_BRANCH] == "fix/example-one"
@@ -445,14 +404,10 @@ class TestCreateFreshBranchIntegration:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
+        repository_worktree_root = (
+            repository_path.resolve() / ".claude" / "worktrees" / "claude"
         )
-        occupied_path = agent_scratch_parent / "claude" / "fix" / "collision"
+        occupied_path = repository_worktree_root / "fix" / "collision"
         occupied_path.mkdir(parents=True)
         success_payload = module.create_fresh_branch(
             branch_name="fix/collision",
@@ -461,7 +416,7 @@ class TestCreateFreshBranchIntegration:
             base_ref=DEFAULT_BASE_REF,
         )
         worktree_path = Path(success_payload[PAYLOAD_KEY_WORKTREE_PATH])
-        assert worktree_path == agent_scratch_parent / "claude" / "fix" / "collision-2"
+        assert worktree_path == repository_worktree_root / "fix" / "collision-2"
         assert worktree_path.is_dir()
         assert read_head_branch(worktree_path) == "fix/collision"
 
@@ -472,13 +427,6 @@ class TestCreateFreshBranchIntegration:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         module.create_fresh_branch(
             branch_name="fix/dup",
             repo_path=repository_path,
@@ -515,13 +463,6 @@ class TestCreateFreshBranchIntegration:
         )
         local_main_commit = read_head_commit(repository_path)
         assert local_main_commit != origin_tip_before
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         success_payload = module.create_fresh_branch(
             branch_name="fix/bare-base",
             repo_path=repository_path,
@@ -543,13 +484,6 @@ class TestWorktreeBranchTracking:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         success_payload = module.create_fresh_branch(
             branch_name="fix/no-upstream",
             repo_path=repository_path,
@@ -574,13 +508,6 @@ class TestWorktreeBranchTracking:
             repository_path,
             empty_hooks_path=empty_hooks_path,
         )
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         success_payload = module.create_fresh_branch(
             branch_name="feature/silent-push",
             repo_path=repository_path,
@@ -619,13 +546,6 @@ class TestMainCli:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         monkeypatch.setattr(
             sys,
             "argv",
@@ -697,15 +617,7 @@ class TestMainCli:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
-        escaped_path = agent_scratch_parent / "escape"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
+        escaped_path = tmp_path / "escape"
         monkeypatch.setattr(
             sys,
             "argv",
@@ -726,7 +638,7 @@ class TestMainCli:
         assert PAYLOAD_KEY_ERROR in error_payload
         assert "relative path" in error_payload[PAYLOAD_KEY_ERROR]
         assert not escaped_path.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()
 
     def should_print_error_json_for_absolute_branch_name(
         self,
@@ -736,15 +648,7 @@ class TestMainCli:
     ) -> None:
         module = load_create_fresh_branch_module()
         repository_path = build_repo_with_origin(tmp_path / "repo")
-        agent_scratch_parent = tmp_path / "agent-scratch"
-        agent_scratch_parent.mkdir()
         outside_target = tmp_path / "outside-evil"
-        monkeypatch.setattr(module.sys, "platform", "linux")
-        monkeypatch.setattr(
-            module.tempfile,
-            "gettempdir",
-            lambda: str(agent_scratch_parent),
-        )
         monkeypatch.setattr(
             sys,
             "argv",
@@ -765,4 +669,4 @@ class TestMainCli:
         assert PAYLOAD_KEY_ERROR in error_payload
         assert "relative path" in error_payload[PAYLOAD_KEY_ERROR]
         assert not outside_target.exists()
-        assert not (agent_scratch_parent / "claude").exists()
+        assert not (tmp_path / "unused-repo").exists()

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).

package/skills/issue-tracker/reference/operation-matrix.md

@@ -0,0 +1,41 @@
+# Operation matrix
+
+Each issue op maps to a GitHub MCP tool and a `gh` fallback that reaches the same REST endpoint. Prefer the MCP tool; fall back to `gh` when the MCP server is unreachable. The REST endpoint column names the authoritative contract both surfaces call, so a session with neither surface can still drive the raw API.
+
+The MCP tool names below match the connected GitHub MCP server's issue toolset. When a server exposes a tool under a different name, pick the tool by what the row describes, and the REST endpoint tells you what it must call.
+
+| Operation | GitHub MCP tool | REST endpoint | `gh` fallback |
+|-----------|-----------------|---------------|---------------|
+| Search open + closed | `mcp__github__search_issues` | `GET /search/issues?q=<terms>+repo:{owner}/{repo}` | `gh issue list --search "<terms>" --state all` |
+| Create epic / sub-issue | `mcp__github__issue_write` (create) | `POST /repos/{owner}/{repo}/issues` | `gh issue create --title "<t>" --body-file <path> --label <label>` |
+| Read issue body | `mcp__github__issue_read` | `GET /repos/{owner}/{repo}/issues/{number}` | `gh issue view <number> --json body` |
+| Update body / labels | `mcp__github__issue_write` (update) | `PATCH /repos/{owner}/{repo}/issues/{number}` | `gh issue edit <number> --body-file <path> --add-label <label>` |
+| Attach native sub-issue | `mcp__github__sub_issue_write` | `POST /repos/{owner}/{repo}/issues/{number}/sub_issues` | `gh api repos/{owner}/{repo}/issues/{number}/sub_issues -F sub_issue_id=<int>` |
+| Add cross-reference comment | `mcp__github__add_issue_comment` | `POST /repos/{owner}/{repo}/issues/{number}/comments` | `gh issue comment <number> --body-file <path>` |
+| Create label | `mcp__github__` label-create tool | `POST /repos/{owner}/{repo}/labels` | `gh label create <name> --color <hex> --description "<text>"` |
+
+## The sub-issue `.id` rule (read this before every attach)
+
+The sub-issues endpoint identifies the child by its REST **database `.id`** — a large integer such as `2138472019` — not by its display number (`#42`). The two are different values. Passing the display number attaches nothing.
+
+Read the child's `.id` from the create op's response, or fetch it:
+
+```
+gh api repos/{owner}/{repo}/issues/{number} --jq .id
+```
+
+`gh issue view <number> --json id` returns the GraphQL node id, a base64 string — the wrong value for this endpoint. Use `gh api ... --jq .id` for the REST database id.
+
+The gh attach uses `-F` (typed field), which sends the id as a JSON integer. `-f` sends a string, and the endpoint rejects a string sub-issue id.
+
+```
+gh api repos/{owner}/{repo}/issues/{parent}/sub_issues -F sub_issue_id=2138472019
+```
+
+## Body content through `--body-file`
+
+Every `gh issue create`, `gh issue edit`, and `gh issue comment` passes body content with `--body-file <path>`, never `--body "<text>"`. A `--body` string mangles backticks on GitHub — they land as literal `\``. Write the body to a temp file and point `--body-file` at it.
+
+## Paginated reads
+
+`gh issue list` needs no pagination flags. For a `gh api` read of a paginated list endpoint (an issue's comments, a repository's issues), pass `--paginate --slurp` and pipe to external `jq` — `gh`'s built-in `--jq` runs per page and gives wrong cross-page results.