claude-dev-env 1.68.0 → 1.69.1

package/skills/_shared/pr-loop/CLAUDE.md

@@ -0,0 +1,27 @@
+# pr-loop
+
+Shared infrastructure for the PR audit-fix loop used by `bugteam` and `pr-converge`. Provides the XML prompt template, Python runtime scripts, and named constants that both skills invoke during each loop tick.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `prompts/` | XML agent prompt templates. |
+| `scripts/` | Python scripts for loop state management, prompt building, outcome recording, path resolution, and preflight checks. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `prompts/pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/build_audit_prompt.py` | Assembles the audit agent prompt from loop state and the constants module. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/init_loop_state.py` | Initializes the per-PR loop state JSON file. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_audit_outcomes.py` | Writes the per-loop audit outcome XML into the workspace. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/write_fix_outcomes.py` | Writes the per-loop fix outcome XML into the workspace. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/preflight_worktree.py` | Verifies the working directory is a healthy worktree for the target PR's repo. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/teardown_worktrees.py` | Removes loop worktrees on clean exit. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_path_resolver.py` | Resolves workspace and worktree paths from PR metadata. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_cli_utils.py` | Shared CLI argument parsing helpers. |
+| `packages/claude-dev-env/skills/_shared/pr-loop/scripts/_xml_utils.py` | XML serialization helpers. |
+| `scripts/skills_pr_loop_constants/` | Named constants package imported by the scripts above. |

package/skills/_shared/pr-loop/prompts/CLAUDE.md

@@ -0,0 +1,9 @@
+# prompts
+
+XML agent prompt templates for the PR audit-fix loop.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `pr-consistency-audit.xml` | Structured prompt artifact for the cross-file consistency audit agent. Defines the agent role, scope anchors, a ten-rule detection workflow, and output format. `bugteam` and `pr-converge` both inject this prompt when running the consistency audit step. |

package/skills/_shared/pr-loop/scripts/CLAUDE.md

@@ -0,0 +1,23 @@
+# scripts
+
+Python scripts that run the PR audit-fix loop at runtime. Both `bugteam` and `pr-converge` invoke these scripts during each loop tick.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `build_audit_prompt.py` | Assembles the audit agent prompt from loop state and category constants. |
+| `build_fix_prompt.py` | Assembles the fix agent prompt from loop state and findings XML. |
+| `init_loop_state.py` | Initializes the per-PR `loop-state.json` file in the workspace directory. |
+| `write_audit_outcomes.py` | Writes per-loop audit outcome XML into the workspace. |
+| `write_fix_outcomes.py` | Writes per-loop fix outcome XML into the workspace. |
+| `preflight_worktree.py` | Verifies the working directory is a healthy git worktree for the target PR's repo. Supports `--mode strict` to abort when the repo does not match. |
+| `teardown_worktrees.py` | Removes per-PR worktrees after a clean loop exit. |
+| `_path_resolver.py` | Resolves workspace and worktree paths from PR owner, repo, and number. |
+| `_cli_utils.py` | Shared CLI argument parsing helpers (argparse wrappers). |
+| `_xml_utils.py` | XML serialization helpers for outcome files. |
+| `skills_pr_loop_constants/` | Named constants package imported by the scripts above. |
+
+## Tests
+
+Each script has a paired test file (`test_build_audit_prompt.py`, `test_build_fix_prompt.py`, etc.) in this directory. Run with `python -m pytest` from the repo root.

package/skills/_shared/pr-loop/scripts/skills_pr_loop_constants/CLAUDE.md

@@ -0,0 +1,19 @@
+# skills_pr_loop_constants
+
+Python package of named constants for the `pr-loop` shared scripts. All constants are `UPPER_SNAKE_CASE` module-level names imported by the sibling scripts.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `__init__.py` | Package marker. |
+| `path_resolver_constants.py` | Path template strings and format constants: workspace directory naming, worktree directory name, diff patch filename pattern, outcome XML filename patterns, loop state filename, fix status values, audit constraint texts, audit category entries, fix execution steps, fix constraint texts, and XML serialization settings. |
+| `preflight_constants.py` | Constants used by `preflight_worktree.py` for exit codes and output marker strings. |
+
+## Usage
+
+Scripts import directly from the package:
+
+```python
+from skills_pr_loop_constants.path_resolver_constants import LOOP_STATE_FILENAME
+```

package/skills/anthropic-plan/CLAUDE.md

@@ -0,0 +1,34 @@
+# anthropic-plan
+
+**Trigger:** `/anthropic-plan`, `/plan`, "plan this first", "think before coding", "make a plan", "scope this out", "don't code yet", and non-trivial requests that need source-grounded design before build work.
+
+Creates a repo-local plan packet under `docs/plans/<slug>/` by running the `plan-packet.mjs` workflow. The packet holds context, spec, implementation steps, validation, and a handoff prompt for the build agent. The skill stops before any production code changes.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `scripts/` | Python validator (`validate_packet.py`) that checks the packet's required files, placeholders, and consistency. |
+| `templates/` | Template files the workflow renders when building the packet (`README.md`, `build-prompt.md`, `reuse-audit.md`, `source-map.md`, `visual-plan.template.html`). |
+| `workflow/` | The `.mjs` workflow scripts and their test files. |
+
+## Key files
+
+| File | Role |
+|---|---|
+| `SKILL.md` | Entry point. Full planning protocol, workflow contract, packet shape, and validation rules. |
+| `workflow/plan-packet.mjs` | Main workflow script. Reads repo context, writes the packet, runs the validator, spawns `plan-packet-validator`, runs the reuse audit, builds the visual HTML, and returns the packet path. |
+| `workflow/plan-packet.contract.test.mjs` | Contract tests for the workflow script. |
+| `packages/claude-dev-env/skills/anthropic-plan/scripts/validate_packet.py` | Deterministic validator: checks required files, open questions, source-map strength, TDD coverage, and `packet.json` consistency. Exits with code 2 on failure. |
+| `templates/visual-plan.template.html` | Template for the single-file offline visual HTML the workflow builds after validation. |
+
+## Entry point
+
+```js
+Workflow({
+  scriptPath: "$HOME/.claude/skills/anthropic-plan/workflow/plan-packet.mjs",
+  args: { task: "<user request>", cwd: "<working directory>" }
+})
+```
+
+The session must be in a worktree (path has `.claude/worktrees/`) before calling the workflow.

package/skills/anthropic-plan/SKILL.md

@@ -41,7 +41,7 @@ The workflow handles the full planning loop:
 2. Read project instructions, rules, relevant skills, manifests, docs, tests, hooks, agents, commands, configs, and workflows.
 3. Build a source inventory and extract source facts into `context/source-map.md`.
 4. Write the packet under `docs/plans/<slug>/`.
-5. Run `scripts/validate_packet.py`.
+5. Run `packages/claude-dev-env/skills/anthropic-plan/scripts/validate_packet.py`.
 6. Spawn `plan-packet-validator` in fresh context.
 7. Repair packet findings up to the workflow cap.
 8. Run the reuse audit: search the codebase for existing equivalents of each new file/symbol the packet introduces, write `validation/reuse-audit.md`, and gate approval on any unjustified reproduction.

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

@@ -0,0 +1,11 @@
+# scripts
+
+Python scripts for the `anthropic-plan` skill.
+
+## Key files
+
+| File | Role |
+|---|---|
+| `validate_packet.py` | Deterministic packet validator. Checks that all required files exist under `docs/plans/<slug>/`, that no placeholder text remains, that `packet.json` is consistent with the folder contents, and that the TDD plan is present. Exits with code 2 on failure; the workflow treats a non-zero exit as a blocking finding. |
+| `test_validate_packet.py` | Tests for `validate_packet.py`. |
+| `anthropic_plan_scripts_constants/` | Named constants package (`validate_packet_constants.py`) that lists every required relative path the validator checks. |

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