claude-dev-env 1.68.0 → 1.69.0

package/skills/anthropic-plan/scripts/anthropic_plan_scripts_constants/CLAUDE.md

@@ -0,0 +1,16 @@
+# anthropic_plan_scripts_constants
+
+Python package of named constants for `anthropic-plan/scripts/`.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `validate_packet_constants.py` | Defines `ALL_REQUIRED_RELATIVE_PATHS` — the tuple of every relative path that must exist inside a valid plan packet (e.g. `README.md`, `packet.json`, `context/source-map.md`, `implementation/tdd-plan.md`, `handoff/build-prompt.md`). Also defines `MARKDOWN_FILE_SUFFIX` and `EXIT_CODE_VALIDATION_FAILED`. |
+
+## Usage
+
+```python
+from anthropic_plan_scripts_constants.validate_packet_constants import ALL_REQUIRED_RELATIVE_PATHS
+```

package/skills/anthropic-plan/templates/CLAUDE.md

@@ -0,0 +1,13 @@
+# templates
+
+Template files the `plan-packet.mjs` workflow renders when building a plan packet.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `README.md` | Markdown template for the packet's top-level `README.md`. Placeholder slots for plan title, goal, status, packet map, and build path. |
+| `build-prompt.md` | Template for `handoff/build-prompt.md` — the standalone prompt the build agent reads to start coding without needing the rest of the packet. |
+| `reuse-audit.md` | Template for `validation/reuse-audit.md` — the per-item verdict table the workflow fills in during the reuse audit step. |
+| `source-map.md` | Template for `context/source-map.md` — the inventory of source files and facts the planner extracts. |
+| `visual-plan.template.html` | Single-file offline HTML template. The workflow fills this with packet data after validation to produce `visual-plan.html` beside the packet. Inlines all CSS and JavaScript; references no external assets. |

package/skills/anthropic-plan/workflow/CLAUDE.md

@@ -0,0 +1,14 @@
+# workflow
+
+Workflow scripts for the `anthropic-plan` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `plan-packet.mjs` | Main workflow script. Resolves repo root, reads project context, builds the source inventory, writes the full packet under `docs/plans/<slug>/`, runs `validate_packet.py`, spawns `plan-packet-validator` in a fresh context, runs the reuse audit, builds the visual HTML from `templates/visual-plan.template.html`, and returns the packet path and validation state. |
+| `plan-packet.contract.test.mjs` | Contract tests that verify the workflow script's interface and required steps without a live repo. |
+
+## Running
+
+The `plan-packet.mjs` script runs via the `Workflow` tool — do not invoke it directly with Node. The skill's `SKILL.md` specifies the exact call signature and required `args`.

package/skills/auditing-claude-config/CLAUDE.md

@@ -0,0 +1,20 @@
+# auditing-claude-config
+
+**Trigger:** `/auditing-claude-config`, reviewing the startup instruction load, `/memory` showing unexpected files, adding new rules, periodic config hygiene.
+
+Audits a Claude Code setup — user `CLAUDE.md`, `~/.claude/rules/`, project `.claude/` — for context-budget waste: duplicate `@`-imports, always-on rules that could be path-scoped or turned into skills, and oversized files. Produces a migration table with line savings.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Full audit protocol: inventory the always-loaded set, find duplicate imports, classify each rule, produce the migration table, stage recommendations by risk, and verify lazy-load behavior with an optional probe hook. |
+
+## What the skill produces
+
+1. **Baseline** — total always-loaded lines, broken down by file.
+2. **Migration table** — one row per rule: current lines, verdict, specific action, lines removed from preload.
+3. **Recommended next step** — the single highest-leverage change.
+4. **Open questions** — anything not verified by the probe hook.
+
+No scripts or workflow files. The skill body holds all logic.

package/skills/autoconverge/CLAUDE.md

@@ -0,0 +1,30 @@
+# autoconverge
+
+**Trigger:** `/autoconverge`, "autoconverge this PR", "converge this PR in one run", "run the converge workflow", "drive the PR to ready autonomously".
+
+Drives one draft PR to convergence in a single autonomous workflow run. Each round runs Cursor Bugbot, a code-review pass, and a bug-audit in parallel on the same HEAD, deduplicates findings, applies every fix in one commit, re-verifies, clears a Copilot wait-gate, and marks the PR ready on convergence. State lives in the workflow journal; no `ScheduleWakeup` ticks.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Markdown docs the skill and workflow cite: round shape, stop conditions, gotchas, and closing report format. |
+| `workflow/` | The `.mjs` convergence workflow, Python report scripts, test files, and the `autoconverge_report_constants/` package. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Full entry-point protocol: pre-flight steps, worktree setup, `Workflow` call, budget-aware round boundaries, teardown, and the per-round convergence loop summary. |
+| `workflow/converge.mjs` | Main convergence workflow. Runs rounds, gates on Copilot, checks convergence, and marks the PR ready. |
+| `workflow/aggregate_runs.py` | Merges every autoconverge journal for a PR into one deduped journal. |
+| `workflow/convergence_summary.py` | Builds the convergence-summary agent prompt over the merged findings. |
+| `workflow/render_report.py` | Builds the closing HTML report from the merged journal and summary. |
+| `reference/convergence.md` | Round shape: the three parallel lenses, deduplication, fix commit, and the ready definition. |
+| `reference/stop-conditions.md` | Every way the run ends short of ready. |
+| `reference/gotchas.md` | Hard-won failure lessons. |
+| `reference/closing-report.md` | Specification for the closing HTML report format. |
+
+## Entry point
+
+Requires the `Workflow` tool. The `SKILL.md` body specifies the exact pre-flight sequence and `Workflow` call.

package/skills/autoconverge/reference/CLAUDE.md

@@ -0,0 +1,12 @@
+# reference
+
+Reference documentation for the `autoconverge` skill. The `converge.mjs` workflow and the `SKILL.md` cite these files to define behavior precisely.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `convergence.md` | Round shape: the three parallel lenses (Bugbot, code-review, bug-audit), deduplication, the fix commit step, and the definition of a clean convergence. |
+| `stop-conditions.md` | Every condition that ends the run short of ready: budget cap, iteration cap, blocker exit, Copilot bypass. |
+| `gotchas.md` | Hard-won lessons from failed runs: PR title validation, conflicting PRs, worktree branch lock, resumed sessions rerooting, and minter issues. |
+| `closing-report.md` | Specification for the closing HTML convergence report the teardown step builds and publishes. |

package/skills/autoconverge/workflow/CLAUDE.md

@@ -0,0 +1,23 @@
+# workflow
+
+Workflow scripts and report utilities for the `autoconverge` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `converge.mjs` | Main convergence workflow script. Each round runs Bugbot, code-review, and bug-audit lenses in parallel, deduplicates findings, applies fixes, pushes, gates on Copilot, checks convergence, and marks the PR ready. Runs via the `Workflow` tool — not directly with Node. |
+| `aggregate_runs.py` | Merges every autoconverge journal for a given PR (matched by run id) into one merged journal. Prints a JSON line with `mergedJournal`, `roundCount`, `finalSha`, and `findingCount`. |
+| `convergence_summary.py` | Builds the convergence-summary agent prompt over the merged journal's findings. The teardown step spawns a `general-purpose` subagent on this prompt. |
+| `render_report.py` | Builds the closing HTML insights report. Takes `--journal`, `--summary-file`, `--out`, `--pr`, `--final-sha`, and `--rounds`. Writes the HTML to `--out` and prints the output path on stdout. |
+| `autoconverge_report_constants/` | Named constants package for `render_report.py` and `convergence_summary.py`. |
+| `converge.contract.test.mjs` | Contract tests for `converge.mjs` — verify the workflow interface and step ordering. |
+| `converge.clean-audit.test.mjs` | Tests the clean-audit path (all lenses clean on first round). |
+| `converge.copilot-gate.test.mjs` | Tests Copilot gate behavior (bypass on quota exhaustion). |
+| `converge.fix-progress.test.mjs` | Tests fix-progress tracking across rounds. |
+| `converge.fix-recovery.test.mjs` | Tests recovery when a fix commit fails. |
+| `converge.run-input.test.mjs` | Tests workflow input validation. |
+| `test_aggregate_runs.py` | Tests for `aggregate_runs.py`. |
+| `test_convergence_summary.py` | Tests for `convergence_summary.py`. |
+| `test_render_report.py` | Tests for `render_report.py`. |
+| `fixtures/` | Test fixture data for the workflow tests. |

package/skills/autoconverge/workflow/autoconverge_report_constants/CLAUDE.md

@@ -0,0 +1,16 @@
+# autoconverge_report_constants
+
+Python package of named constants for `render_report.py` and `convergence_summary.py` in the `autoconverge/workflow/` directory.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `render_report_constants.py` | Named constants for the report renderer: structured output tool name, journal label prefixes (`resolve-head`, `lens:`, `fix:`, `copilot-gate`, `convergence-summary`), journal sibling directory names, default finding category and severity, date and SHA length constants, workflow name, projects directory name, merged run id prefix, summary detail character limit, and `onexc` Python version threshold. |
+
+## Usage
+
+```python
+from autoconverge_report_constants.render_report_constants import LABEL_PREFIX_LENS
+```

package/skills/bdd-protocol/CLAUDE.md

@@ -0,0 +1,26 @@
+# bdd-protocol
+
+**Trigger:** `/bdd-protocol`, "Example Mapping", "BDD anti-patterns", "§7.6", writing executable specifications, BDD scenario quality, "the one where" discovery examples.
+
+On-demand BDD depth layered on top of the always-on `<behavior_protocol>` in the system prompt. The skill adds the Example Mapping algorithm (Smart & Molak §6.4), the scenario quality catalog (§7.6), outside-in test layout, and solo BDD patterns.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `references/` | Loaded reference docs: Example Mapping algorithm and the anti-patterns catalog. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Entry point. `@`-imports both reference files so they load with the skill. Lists authorities and scope boundaries. |
+| `references/example-mapping.md` | Example Mapping algorithm: core moves ("The one where …"), the chat algorithm for solo use, time-boxing guidance. Source: Smart & Molak §6.4. |
+| `references/anti-patterns.md` | §7.6 scenario quality catalog: anti-patterns to avoid and the criteria for a good scenario. |
+
+## What the skill adds
+
+The base `<behavior_protocol>` (Deliberate Discovery → Illustrate → Formulate → Automate) is always active. This skill adds depth only when:
+- The task needs Example Mapping steps or parking-lot question management.
+- Scenarios need the §7.6 quality bar applied.
+- Tests need outside-in layout using describe / when / should.

package/skills/bdd-protocol/references/CLAUDE.md

@@ -0,0 +1,10 @@
+# references
+
+Reference documentation loaded by the `bdd-protocol` skill. Both files are `@`-imported in `SKILL.md` and load when the skill activates.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `example-mapping.md` | Example Mapping algorithm (Smart & Molak §6.4). Covers core moves, the "The one where …" phrasing, probes, parking-lot questions, the solo chat algorithm, and time-boxing guidance. |
+| `anti-patterns.md` | §7.6 scenario quality catalog. Lists anti-patterns to avoid and the criteria for a well-formed BDD scenario. |

package/skills/bg-agent/CLAUDE.md

@@ -0,0 +1,17 @@
+# bg-agent
+
+Delegates a task to a background agent so the main session stays free. Triggered by `/bg-agent`, `bg-agent`, or `background agent for this`.
+
+## Purpose
+
+This skill picks a suitable agent type for the task, spawns it via the `Agent` tool with `run_in_background: true`, and returns control at once. The spawned agent notifies on completion. Other skills (such as `gotcha`) invoke this skill to offload their own PR-creation steps.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full instructions: how to parse the task argument, how to pick an agent type, how to write a self-contained spawn prompt, and how to report spawn to the user. |
+
+## How this skill is invoked
+
+The user types `/bg-agent <task description>` or a calling skill invokes it by name. The skill always spawns with `run_in_background: true` — it never runs the task inline in the main session.

package/skills/bugteam/CLAUDE.md

@@ -0,0 +1,30 @@
+# bugteam
+
+Runs an audit-fix loop on an open pull request until all findings are resolved or the 20-loop cap is reached. Triggered by `/bugteam`, `run the bug team`, `auto-fix the PR until clean`, or `loop audit and fix`.
+
+## Purpose
+
+Each loop: a `code-quality-agent` (fresh context, all A–P audit categories) produces an outcome XML; a `clean-coder` agent applies every fix; the lead commits, pushes, and posts a GitHub PR review (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty). Grants `.claude/**` write permissions at the start and revokes them at the end.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Hub — pre-flight call, refusals, audit-posting protocol, progress checklist, and situation-to-reference table. Read this first. |
+| `PROMPTS.md` | Spawn XML, A–P category bindings, outcome XML schemas. |
+| `CONSTRAINTS.md` | Invariants — what the loop must never violate. |
+| `EXAMPLES.md` | Exit scenarios: converged, cap-reached, stuck, refusal, mixed-outcome. |
+| `sources.md` | Doc URLs and verbatim quotes cited in the skill body. |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `reference/` | Expanded workflow detail loaded on demand (team setup, audit contract, GitHub PR review shape, teardown). |
+| `scripts/` | Python scripts executed by the lead or teammates at runtime. |
+
+## Environment controls
+
+- `CLAUDE_REVIEWS_DISABLED=bugteam` — disables the skill entirely (pre-flight exits 7).
+- `BUGTEAM_PREFLIGHT_SKIP=1` — skips pytest in pre-flight.
+- `BUGTEAM_REVIEWER_ACCOUNT=<login>` — names the alternate `gh` account for posting reviews when the PR author and reviewer identity match.

package/skills/bugteam/reference/CLAUDE.md

@@ -0,0 +1,22 @@
+# bugteam/reference
+
+Expanded workflow detail for the `bugteam` skill. Load a file from this directory when the orchestration stub in `SKILL.md` is not enough — for example, when debugging GitHub review shape, understanding gate semantics, or working through teardown edge cases.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `README.md` | Index of all files in this directory with one-line domain summaries. |
+| `team-setup.md` | Permissions grant, PR scope resolution, run name, temp dir, and loop state. |
+| `audit-and-teammates.md` | Pre-audit CODE_RULES gate, full cycle numbering, AUDIT and FIX action detail. |
+| `audit-contract.md` | Finding shape (Shape A / B), Haiku secondary merge rules, post-fix self-audit. |
+| `github-pr-reviews.md` | Per-loop review posting, `jq`+`gh api` payloads, inline anchors, fallbacks, REST endpoints. |
+| `teardown-publish-permissions.md` | Teardown steps, PR description rewrite via `pr-description-writer`, permission revoke, final report. |
+| `design-rationale.md` | Why clean-room subagents, when `/bugteam` applies, refusal reasons. |
+| `copilot-gap-analysis.md` | Historical gap analysis (reference only). |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `obstacles/` | Per-step obstacle guides — one file per common failure point (e.g., write XML, resolve thread, push, test suite). |

package/skills/bugteam/reference/obstacles/CLAUDE.md

@@ -0,0 +1,24 @@
+# bugteam/reference/obstacles
+
+Per-step obstacle guides for the `bugteam` skill. Each file addresses a specific failure point that can occur during an audit-fix loop. Load the matching file when a step fails rather than improvising a fix.
+
+## Files
+
+| File | Obstacle it addresses |
+|---|---|
+| `audit-assign-ids.md` | Assigning stable finding IDs in the audit output. |
+| `audit-capture-excerpts.md` | Capturing code excerpts for each finding. |
+| `audit-walk-categories.md` | Walking all A–P categories without skipping. |
+| `audit-write-xml.md` | Writing the outcome XML from an audit pass. |
+| `fix-append-summary.md` | Appending the fix summary to the outcome XML. |
+| `fix-apply-fixes.md` | Applying code fixes from the finding list. |
+| `fix-git-add-commit.md` | Staging and committing the fixed files. |
+| `fix-git-push.md` | Pushing the fix commit to the remote branch. |
+| `fix-post-reply.md` | Posting inline replies to finding threads on the PR. |
+| `fix-publish-summary.md` | Publishing the loop summary to the PR. |
+| `fix-py-compile.md` | Verifying Python syntax after fixes. |
+| `fix-read-files.md` | Reading the files referenced in a finding. |
+| `fix-resolve-thread.md` | Resolving a finding's review thread on GitHub. |
+| `fix-test-suite.md` | Running the test suite and interpreting failures. |
+| `fix-violation-count.md` | Counting open violations after a fix pass. |
+| `fix-write-xml.md` | Writing the per-fix XML record. |

package/skills/bugteam/scripts/CLAUDE.md

@@ -0,0 +1,36 @@
+# bugteam/scripts
+
+Python scripts executed by the bugteam lead or teammates at runtime. These are not loaded into context as instructions — they run as subprocess calls from within the skill workflow.
+
+## Scripts
+
+| File | Purpose |
+|---|---|
+| `bugteam_preflight.py` | Run pytest and optional `pre-commit` before the first loop. Skips pytest when `BUGTEAM_PREFLIGHT_SKIP=1` or no test files exist. |
+| `bugteam_fix_hookspath.py` | Auto-remediate a stale `core.hooksPath` override, set the canonical global value, re-run preflight. |
+| `bugteam_code_rules_gate.py` | Run `validate_content` from `code_rules_enforcer.py` on PR-scoped files. Exit 1 on mandatory rule failures. |
+| `grant_project_claude_permissions.py` | Grant Edit/Write/Read on `cwd/.claude/**` in `~/.claude/settings.json`. |
+| `revoke_project_claude_permissions.py` | Remove the matching grant entries from `~/.claude/settings.json`. |
+| `_bugteam_permissions_common.py` | Shared helpers for grant/revoke (atomic JSON writes, settings sections). |
+| `windows_safe_rmtree.py` | Remove a directory tree on Windows by stripping ReadOnly attributes and retrying on failure. |
+| `probe_code_rules_enforcer_check.py` | Load `code_rules_enforcer.py` and invoke a named check function against a fixture file. |
+| `reflow_skill_md.py` | Reflow the bugteam SKILL.md body to fit line-length limits. |
+
+## Test files
+
+| File | Tests |
+|---|---|
+| `test_bugteam_preflight.py` | `bugteam_preflight.py` |
+| `test_bugteam_code_rules_gate.py` | `bugteam_code_rules_gate.py` |
+| `test_bugteam_fix_hookspath.py` | `bugteam_fix_hookspath.py` |
+| `test_bugteam_permissions_common.py` | `_bugteam_permissions_common.py` |
+| `test__bugteam_permissions_common.py` | Internal helpers in `_bugteam_permissions_common.py` |
+| `test_agent_config_carveout.py` | `.claude/**` grant/revoke carveout logic |
+| `test_probe_code_rules_enforcer_check.py` | `probe_code_rules_enforcer_check.py` |
+| `test_windows_safe_rmtree.py` | `windows_safe_rmtree.py` |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `bugteam_scripts_constants/` | Named constants imported by the scripts above. |

package/skills/bugteam/scripts/bugteam_scripts_constants/CLAUDE.md

@@ -0,0 +1,20 @@
+# bugteam/scripts/bugteam_scripts_constants
+
+Python package of named constants imported by the bugteam scripts. Each module holds the constants for one script; importing from this package keeps magic values out of the script bodies.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `bugteam_preflight_constants.py` | `bugteam_preflight.py` — env var name, hooks path suffix, exit codes, ignore dirs, argument tuples, config filenames. |
+| `bugteam_code_rules_gate_constants.py` | `bugteam_code_rules_gate.py` — gate-related path and exit-code constants. |
+| `bugteam_fix_hookspath_constants.py` | `bugteam_fix_hookspath.py` — canonical hooks path, remediation message strings. |
+| `claude_permissions_common_constants.py` | `_bugteam_permissions_common.py` — settings JSON keys, glob patterns for the grant/revoke scripts. |
+| `probe_code_rules_enforcer_check_constants.py` | `probe_code_rules_enforcer_check.py` — enforcer module path and function name constants. |
+| `reflow_skill_md_constants.py` | `reflow_skill_md.py` — line-length and formatting constants. |
+| `windows_safe_rmtree_constants.py` | `windows_safe_rmtree.py` — retry count and wait constants. |
+| `__init__.py` | Empty package marker. |
+
+## Convention
+
+Scripts import from this package at module scope. No constant is defined inline in a script body — the hook enforces this at write time.

package/skills/caveman/CLAUDE.md

@@ -0,0 +1,15 @@
+# caveman
+
+Trims noise from conversational text in the current turn. Triggered by `/caveman`, `caveman this`, `trim this`, `make it terse`, or `caveman voice`.
+
+## Purpose
+
+The inline counterpart to the `caveman` agent. When the user wants preamble, hedging, filler transitions, restatements, empty future-proofing, dead examples, or pleasantries stripped from the last assistant message or from text passed as an argument, this skill performs the trim directly in the main session — no `Agent` spawn. The entire reply is the trimmed text; no report, no commentary about what was cut.
+
+Use the `caveman` agent (`subagent_type: caveman`) when the input is a file path, a multi-section artifact that needs a structured report, or a delegated workflow.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Instructions: resolve the source (argument or prior message), noise categories to cut, what to preserve verbatim, and the escape hatch for load-bearing spans. |

package/skills/code/CLAUDE.md

@@ -0,0 +1,17 @@
+# code
+
+Activates strict code standards for the entire implementation session. Triggered by `/code`, `code standards`, `strict code`, `enforce standards`, or `implement with standards`.
+
+## Purpose
+
+Prepends a set of binary completion criteria to every implementation task: no `Any`, no `cast()`, no `# type: ignore`, treated-as-immutable TypedDicts with explicit `_encode_*`/`_decode_*` functions, 100% statement and branch coverage, zero mocks, zero stubs, zero fallbacks, and proper module structure. Every criterion is pass-or-fail; partial credit does not exist.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Sixteen numbered criteria (typing strictness, error handling, test coverage, DI hooks, DRY, TypedDict protocol, Redis boundary, TOML boundary, JSON recursive types, ASGI boundaries, dynamic import pattern, documentation, build infrastructure, lint gates, Protocol signature match, auth/credentials), plus gotchas for Windows PowerShell invocation and per-module `_test_hooks.py` placement. |
+
+## Invocation note
+
+Invoke at the start of an implementation task. The standards persist for the full session. The skill refuses research or planning tasks and redirects them to `/anthropic-plan`.

package/skills/copilot-review/CLAUDE.md

@@ -0,0 +1,17 @@
+# copilot-review
+
+Spawns a background subagent that polls the GitHub Copilot reviewer on the current PR, fixes unaddressed findings, and re-requests review each tick until the PR is clean. Triggered by `/copilot-review`, `watch copilot`, `babysit copilot review`, or `keep re-requesting copilot`.
+
+## Purpose
+
+The main session gathers PR context (number, HEAD SHA, owner/repo, branch), spawns a self-terminating background subagent with a fully filled-in prompt, and returns control at once. The subagent loops on a 5-minute `ScheduleWakeup` cadence: fetch Copilot's latest review, TDD-fix any inline findings, push a commit, reply inline, re-request review. It stops on convergence, a persistent blocker, `TaskStop`, or after 20 ticks.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Four-step orchestration (opt-out check, gather PR context, spawn subagent, report to user), the verbatim subagent prompt template with all placeholders, fix protocol, stop conditions, and ground rules (one commit per tick, honor hooks, preserve draft state, use `copilot-pull-request-reviewer[bot]` with the `[bot]` suffix). |
+
+## Environment opt-out
+
+Set `CLAUDE_REVIEWS_DISABLED=copilot` to disable. The skill checks this before spawning anything.

package/skills/deep-research/CLAUDE.md

@@ -0,0 +1,17 @@
+# deep-research
+
+Runs an iterative multi-source research pipeline that produces a comprehensive Obsidian report with citations. Triggered by `/deep-research [topic]`.
+
+## Purpose
+
+The skill operates in two phases. Phase 1 (main thread) turns the raw topic into a precise research brief through a short AskUserQuestion session covering audience, scope, recency, and depth. Phase 2 delegates to the `deep-research` agent with the confirmed brief and an iteration budget (8 / 15 / 25 based on depth preference). The agent handles iteration, state tracking, and Obsidian output.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Phase 1 steps (classify, ask, construct `<research_brief>` XML, set iteration budget) and Phase 2 spawn instructions, including `mode: bypassPermissions` for unrestricted web access. |
+
+## Post-run cleanup
+
+After the agent returns, the skill summarizes the Obsidian path, source counts, and any gaps, then deletes the `.deep-research-state.md` temp file.

package/skills/doc-gist/CLAUDE.md

@@ -0,0 +1,25 @@
+# doc-gist
+
+Designs fresh HTML artifacts and publishes them as secret GitHub gists with a shareable htmlpreview URL. Triggered by `/doc-gist`, `publish this`, `share as a gist`, `open this as a webpage`, `make me a writeup`, or any request ending in a shareable HTML preview URL.
+
+## Purpose
+
+The skill ships transport, not templates. For each request the model designs a fresh HTML artifact suited to the work, marks it with `<!-- @publish-as-gist -->`, and writes it to disk. A PostToolUse hook (`hooks/workflow/doc_gist_auto_publish.py`) spots the marker, runs `packages/claude-dev-env/skills/doc-gist/scripts/gist_upload.py`, and prints the gist and htmlpreview URLs into the tool output for the user to click.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Full instructions: the auto-publish hook flow, the transport script CLI, a gallery-to-artifact-type mapping table, and gotchas (`gh` auth, marker syntax, self-contained HTML only, secret-not-private note). |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `references/` | Reference material — the example HTML gallery and related docs. |
+| `scripts/` | The `gist_upload.py` transport script and its constants package. |
+
+## Auto-publish vs manual
+
+- **Auto:** write HTML with `<!-- @publish-as-gist -->` anywhere in the file; the hook handles the rest.
+- **Manual:** run `python scripts/gist_upload.py --input <path>` for an existing file or when the marker route does not apply.

package/skills/doc-gist/references/CLAUDE.md

@@ -0,0 +1,9 @@
+# doc-gist/references
+
+Reference material for the `doc-gist` skill.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `examples/` | A gallery of 21 self-contained HTML artifact examples that show distinct shapes — annotated PR diff, design system swatches, slide deck, incident timeline, prompt tuner, decision sign-off, and more. Study these when designing a fresh artifact; do not copy them verbatim. |

package/skills/doc-gist/references/examples/CLAUDE.md

@@ -0,0 +1,25 @@
+# doc-gist/references/examples
+
+HTML artifact gallery for the `doc-gist` skill. Has 21 self-contained `.html` files that cover distinct artifact shapes the skill can produce.
+
+Files `01`–`20` are Thariq Shihipar's html-effectiveness prototypes (used with permission). File `21-decision-signoff.html` is an original addition in the same style.
+
+## Use
+
+Study the matching file when designing a fresh artifact for a request. Crib palette, typography, spatial layout, and component patterns — then adapt to the specific request. The gallery teaches what shapes work; each new artifact is its own design.
+
+See `SKILL.md` for the full gallery-to-artifact-type mapping table (PR writeup, code review, implementation plan, slide deck, etc.).
+
+## Files (sample)
+
+| File | Shape |
+|---|---|
+| `01-exploration-code-approaches.html` | Side-by-side approach exploration |
+| `03-code-review-pr.html` | Annotated diff / code review |
+| `09-slide-deck.html` | Keyboard-navigable slide deck |
+| `12-incident-report.html` | Incident timeline / post-mortem |
+| `16-implementation-plan.html` | Implementation plan with timeline and risks |
+| `17-pr-writeup.html` | PR writeup with file-by-file tour |
+| `21-decision-signoff.html` | Decision / sign-off doc with accept-or-change per call |
+
+All 21 files are present; the table above is a representative sample.

package/skills/doc-gist/scripts/CLAUDE.md

@@ -0,0 +1,27 @@
+# doc-gist/scripts
+
+Transport script and supporting constants for the `doc-gist` skill.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `gist_upload.py` | Core transport: reads HTML from a file path or stdin, runs `gh gist create`, prints `Gist:` and `Preview:` URLs to stderr, prints the preview URL to stdout, and opens it in the default browser (unless `--no-open`). |
+| `test_gist_upload.py` | Tests for `gist_upload.py`. |
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `doc_gist_scripts_constants/` | Named constants imported by `gist_upload.py` (URL prefixes, default filename, timeout). |
+
+## CLI usage
+
+```
+python gist_upload.py --input <path-or-stdin>
+                      [--filename gist-file.html]
+                      [--description "short label"]
+                      [--no-open]
+```
+
+Pass `--input -` to read from stdin. The auto-publish hook calls this script with the written file's path; the skill body documents when to call it manually.

package/skills/doc-gist/scripts/doc_gist_scripts_constants/CLAUDE.md

@@ -0,0 +1,10 @@
+# doc-gist/scripts/doc_gist_scripts_constants
+
+Named constants for `gist_upload.py`. Importing from this package keeps all URL templates, default filenames, and timeout values out of the script body.
+
+## Modules
+
+| File | Constants |
+|---|---|
+| `gist_upload_constants.py` | `GIST_HOST_PREFIX` — base URL for parsing gist output; `PREVIEW_URL_TEMPLATE` — htmlpreview.github.io URL shape; `GIST_DEFAULT_FILENAME` — filename when input is stdin; `MINIMUM_GIST_URL_PARTS` — fewest path segments in a valid gist URL; `UPLOAD_TIMEOUT_SECONDS` — subprocess timeout for `gh gist create`. |
+| `__init__.py` | Empty package marker. |

package/skills/everything-search/CLAUDE.md

@@ -0,0 +1,17 @@
+# everything-search
+
+Fast file search on Windows using the Everything (voidtools) `es.exe` command-line tool. Triggered by `find files`, `search for files`, `locate files`, or any request to use Everything.
+
+## Purpose
+
+Searches files by extension, name, date modified, size, or path against Everything's real-time index. Returns results instantly regardless of drive size. The skill covers the correct `es.exe` path, search operator syntax, multi-extension patterns, output options, and the junction/symlink note (Everything indexes real NTFS paths only — not junctions or mapped drives).
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Command syntax for WSL and Windows paths, all search operators (`ext:`, `dm:`, `size:`, wildcards, OR/AND/NOT), output flags (`-sort`, `-n`, `-size`), worked examples, and a junction/drive-mapping lookup table. |
+
+## When to use
+
+Use for file-system searches by name, extension, size, or date. For content searches use Grep. If a path is a junction or mapped drive and Everything returns nothing, translate to the real NTFS path or fall back to the Glob tool.

package/skills/findbugs/CLAUDE.md

@@ -0,0 +1,20 @@
+# findbugs
+
+Audits the current branch's pull request for bugs by spawning the `code-quality-agent` against the full PR diff in a clean room. Triggered by `/findbugs`, `find bugs in this PR`, `audit the PR`, or `bug audit on the branch`.
+
+## Purpose
+
+Read-only. The skill resolves PR scope, writes the diff to a scoped temp file, and spawns two `code-quality-agent` instances (primary sonnet + secondary haiku) with a self-contained, context-free prompt covering all A–P audit categories. After both return it merges findings (de-dup, max-wins severity), posts one audit review to the PR via `post_audit_thread.py` (APPROVE on clean, REQUEST_CHANGES with inline anchored comments on dirty), and reports totals and cleared categories to the user.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Five-step process: resolve scope, capture diff to a scoped temp path, spawn agents (clean-room prompt XML), post audit review via `post_audit_thread.py`, surface findings and offer `/fixbugs`. Includes refusals, output format, and the anchored-vs-unanchored finding split. |
+
+## Constraints
+
+- Never edits files, never commits, never pushes.
+- One audit review per invocation is posted back to the PR — required so the unresolved-thread gate sees the audit pass.
+- Disabled by `CLAUDE_REVIEWS_DISABLED=bugteam` (shared token across the audit-skill family).
+- Always ask before running `/fixbugs`; never auto-spawn the fixer.

package/skills/fixbugs/CLAUDE.md

@@ -0,0 +1,19 @@
+# fixbugs
+
+Bridges `/findbugs` audit results to `/agent-prompt` for automated fixing. Triggered by `/fixbugs`, `fix all the bugs`, `apply the audit fixes`, or `implement the findbugs results`.
+
+## Purpose
+
+A thin bridge: recover the prior `/findbugs` findings from the current conversation, apply an optional severity filter (`P0`, `P0+P1`, `P1`, or all), re-resolve PR scope, then hand the filtered finding list to `/agent-prompt` as a structured goal string. `/agent-prompt` authors the XML prompt, shows an Outcome preview, asks for confirmation, and spawns a background sonnet `clean-coder` agent to apply all fixes in one commit.
+
+This skill never audits, never edits files, and never spawns agents directly. The `/agent-prompt` confirmation gate is always preserved.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Four-step process: recover findings, apply severity filter, re-resolve PR scope, hand off to `/agent-prompt` with a goal string in the exact expected shape. Includes refusal cases (no findings, zero bugs, empty filter, missing `agent-prompt` skill) and the implementer constraints (one commit, no `--force`, no rebase, explicit `git add` by path). |
+
+## Invocation order
+
+Run `/findbugs` first, then `/fixbugs`. Running `/fixbugs` with no prior `/findbugs` in the session returns `No findings in this session. Run /findbugs first.`

package/skills/fresh-branch/CLAUDE.md

@@ -0,0 +1,15 @@
+# fresh-branch
+
+Creates a new branch from `origin/main` (always fresh-fetched). Triggered by `fresh branch`, `new branch from main`, `/fresh-branch`, or `start fresh`.
+
+## Purpose
+
+A shared primitive used by other skills and directly by the user. Fetches `origin/main`, suggests 2–4 branch names via `AskUserQuestion` when a topic is available (polling recent branch naming patterns from `git branch -r`), then creates and checks out the branch with `git checkout -b <name> origin/main`.
+
+Does not push the branch. Does not create a PR. Does not switch an existing branch. Callers that need the new branch name (for example, to open a PR) receive it as a return value.
+
+## Key file
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | Four-phase instructions: fetch `origin/main`, pick branch name (suggest or prompt), create branch, report. Includes gotchas discovered during use. |

package/skills/gh-paginate/CLAUDE.md

@@ -0,0 +1,18 @@
+# gh-paginate skill
+
+Provides the safe-pagination rule and patterns for `gh api` calls against paginated GitHub list endpoints (PR reviews, PR comments, issue comments, pulls, issues). The rule prevents two silent-truncation defects: default page truncation and per-page `--jq` evaluation.
+
+**Trigger:** Loaded by the `gh-paginate` skill name or when any skill or rule references the pagination rule.
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `SKILL.md` | The complete rule: affected endpoints, safe `--paginate --slurp \| jq` pattern, single-page bound pattern, single-object pattern, newest-first walk pattern, and enforcement notes |
+
+## Conventions
+
+- The preferred pattern pipes `--paginate --slurp` to an **external** `jq` invocation so cross-page operations (`sort_by`, `last`, `reverse`) run on the merged array-of-pages. The built-in `--jq` flag is incompatible with `--slurp` and runs per-page, producing wrong cross-page results.
+- Single-object endpoints (e.g., `pulls/<number>`) are not paginated; `--paginate` is unnecessary and `gh --jq` is safe.
+- The single-page bound pattern (`?per_page=100` without `--paginate`) is acceptable only when the list is confirmed to stay under 100 entries.
+- This skill ships as documentation only; enforcement via a future PreToolUse hook is noted in `SKILL.md`.