claude-dev-env 1.67.2 → 1.69.0

package/hooks/observability/CLAUDE.md

@@ -0,0 +1,16 @@
+# hooks/observability
+
+PostToolUse hooks that record agent behavior for later review. These hooks do not block tool calls; they log or annotate them.
+
+## Key files
+
+| File | Event | What it does |
+|---|---|---|
+| `instructions_loaded_logger.py` | PostToolUse (file load events) | Appends a JSONL record to `~/.claude/logs/instructions_loaded.jsonl` each time Claude Code loads a context file (CLAUDE.md, rules, skills), capturing the file path, load reason, memory type, and session ID |
+| `test_instructions_loaded_logger.py` | — | Tests for `instructions_loaded_logger.py` |
+
+## Conventions
+
+- The log file is append-only; the hook creates the parent directory if needed.
+- Errors during logging are caught and written as error records rather than propagated — the hook never blocks the tool call.
+- Tests run with `python -m pytest observability/test_instructions_loaded_logger.py`.

package/hooks/session/CLAUDE.md

@@ -0,0 +1,21 @@
+# hooks/session
+
+SessionStart and SessionEnd hooks that manage per-session resources: cleaning up stale directories at startup and pruning plugin data at shutdown.
+
+## Key files
+
+| File | Event | What it does |
+|---|---|---|
+| `session_env_cleanup.py` | SessionStart | Removes the current session's pre-existing `~/.claude/session-env/<session_id>/` directory and prunes sibling entries older than the stale-age threshold. Prevents `EEXIST` errors from non-recursive `mkdir` calls in the Bash tool on Windows. |
+| `gh_pr_author_session_cleanup.py` | SessionEnd | Clears any PR-author swap state left over from the current session |
+| `plugin_data_dir_cleanup.py` | SessionEnd | Prunes stale plugin data directories |
+| `untracked_repo_detector.py` | SessionStart | Detects when the session cwd is inside a git repository that is not registered in `~/.claude/project-paths.json` and logs a warning |
+| `test_gh_pr_author_session_cleanup.py` | — | Tests for `gh_pr_author_session_cleanup.py` |
+| `test_session_env_cleanup.py` | — | Tests for `session_env_cleanup.py` |
+| `test_untracked_repo_detector.py` | — | Tests for `untracked_repo_detector.py` |
+
+## Conventions
+
+- `session_env_cleanup.py` is Windows-specific in effect but safe to run on all platforms; it exits 0 when the target directory does not exist.
+- Constants (stale-age threshold, directory names) live in `hooks_constants/session_env_cleanup_constants.py`.
+- Tests run with `python -m pytest session/test_<name>.py`.

package/hooks/validation/CLAUDE.md

@@ -0,0 +1,19 @@
+# hooks/validation
+
+PostToolUse hooks that validate code quality after Claude writes or edits a file. Unlike the blocking hooks (which fire PreToolUse and can deny the write), these hooks run after the write and report errors that need a follow-up fix.
+
+## Key files
+
+| File | Event | What it does |
+|---|---|---|
+| `mypy_validator.py` | PostToolUse (Write/Edit on `.py` files) | Runs mypy on the written file and blocks (via PostToolUse block decision) when type errors are found — catches missing attributes, wrong signatures, type mismatches, and import errors |
+| `hook_format_validator.py` | PostToolUse | Validates that a hook script's output JSON matches the expected Claude Code hook-output schema |
+| `test_mypy_validator.py` | — | Tests for `mypy_validator.py` |
+
+## Conventions
+
+- `mypy_validator.py` resolves the project root via `CLAUDE_PROJECT_ROOT` or `git rev-parse --show-toplevel`.
+- It works on both WSL and Windows.
+- Constants (timeouts, max displayed errors) are inline in `mypy_validator.py`; longer tunables go in `hooks_constants/`.
+- The `eval_*.txt` files in this directory are evaluation exports used during development — not runtime artifacts.
+- Tests run with `python -m pytest validation/test_<name>.py`.

package/hooks/validators/CLAUDE.md

@@ -0,0 +1,49 @@
+# hooks/validators
+
+A library of check modules used by the validation hooks. Each module focuses on one concern; `run_all_validators.py` runs them all and collects results. These modules do not hook into Claude Code directly — they are imported by the validation hooks.
+
+## Core infrastructure
+
+| File | Role |
+|---|---|
+| `validator_base.py` | Defines the `Violation` dataclass (`file`, `line`, `message`) used by every check module |
+| `validator_defaults.py` | Default configuration values shared across check modules |
+| `exempt_paths.py` | Path exemption logic — paths that checks skip (e.g. vendored code) |
+| `output_formatter.py` | Formats `Violation` lists into human-readable output |
+| `run_all_validators.py` | Entry point — runs every check module and aggregates results |
+| `health_check.py` | Verifies that all validator dependencies (ruff, mypy) are reachable |
+
+## Check modules
+
+| Module | What it checks |
+|---|---|
+| `abbreviation_checks.py` | Abbreviated names in Python code |
+| `code_quality_checks.py` | General code quality concerns (dead code, stub bodies, etc.) |
+| `comment_checks.py` | Inline comment presence and content |
+| `file_structure_checks.py` | File-level structural rules (line count, module layout) |
+| `git_checks.py` | Git-state checks (untracked files, merge conflicts) |
+| `magic_value_checks.py` | Magic numbers and strings |
+| `mypy_integration.py` | Runs mypy and converts its output to `Violation` objects |
+| `pr_reference_checks.py` | PR references in commit messages and changelogs |
+| `python_antipattern_checks.py` | Python-specific anti-patterns (bare `except`, `Any`, etc.) |
+| `python_style_checks.py` | Python style rules (naming, imports, type hints) |
+| `react_checks.py` | React/TSX-specific checks (class component patterns, PureComponent usage) |
+| `ruff_integration.py` | Runs ruff and converts its output to `Violation` objects |
+| `security_checks.py` | Security anti-patterns (hardcoded secrets, unsafe calls) |
+| `todo_checks.py` | TODO/FIXME markers without an associated issue reference |
+| `type_safety_checks.py` | Type-safety rules (no `Any`, no `cast`, no `# type: ignore`) |
+| `useless_test_checks.py` | Tests that check only existence or constant values |
+| `verify_paths.py` | Validates that file paths referenced in code actually exist |
+
+## Subdirectory
+
+| Directory | Role |
+|---|---|
+| `test_files/` | Fixture files used by the validator tests — not checked-in test code |
+
+## Conventions
+
+- Every check module exposes one or more functions that take file content or an AST and return a list of `Violation` objects.
+- Test files live beside the modules they test: `test_<module>.py`. Run with `python -m pytest validators/test_<name>.py`.
+- `conftest.py` provides shared test fixtures (sample files, fixture paths).
+- `README.md` in this directory documents the validator design and how to add a new check.

package/hooks/workflow/CLAUDE.md

@@ -0,0 +1,22 @@
+# hooks/workflow
+
+PostToolUse hooks that trigger side-effects after Claude writes a file. They do not block writes; they produce companion artifacts or publish content automatically.
+
+## Key files
+
+| File | Event | What it does |
+|---|---|---|
+| `auto_formatter.py` | PostToolUse (Write/Edit) | Runs the project's auto-formatter (ruff, prettier, etc.) on the written file and sends a desktop notification when formatting changes are applied |
+| `doc_gist_auto_publish.py` | PostToolUse (Write on `.html` files) | When an `.html` file has the `<!-- @publish-as-gist -->` marker, uploads it as a secret GitHub Gist and prints the htmlpreview URL into the harness output |
+| `md_to_html_companion.py` | PostToolUse (Write/Edit on `.md` files) | Generates a styled `.html` companion file from the `.md` source with dark-mode styling |
+| `investigation_tracker_reset.py` | PostToolUse | Resets the investigation tracker state after a tool call |
+| `test_auto_formatter.py` | — | Tests for `auto_formatter.py` |
+| `test_doc_gist_auto_publish.py` | — | Tests for `doc_gist_auto_publish.py` |
+| `test_md_to_html_companion.py` | — | Tests for `md_to_html_companion.py` |
+
+## Conventions
+
+- All three main hooks exit 0 even on failure — they log warnings to stderr but do not break Claude's flow.
+- `doc_gist_auto_publish.py` checks for the `<!-- @publish-as-gist -->` marker before doing any work; HTML files without it are ignored.
+- Constants (marker text, blocked URL schemes, gist upload script path) live in `hooks_constants/doc_gist_auto_publish_constants.py` and `hooks_constants/html_companion_constants.py`.
+- Tests run with `python -m pytest workflow/test_<name>.py`.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "1.67.2",
+    "version": "1.69.0",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {

package/rules/CLAUDE.md

@@ -0,0 +1,46 @@
+# rules
+
+Rule files installed into `~/.claude/rules/` by `bin/install.mjs`. Claude Code loads these as always-on behavioral constraints for every session. Each `.md` file covers one named rule; hook-enforced rules are also backed by a Python hook in `hooks/`.
+
+## Files
+
+| File | Rule |
+|---|---|
+| `agent-spawn-protocol.md` | Protocol for spawning subagents: context sufficiency check, prompt generation via `/prompt-generator`, then spawn |
+| `ask-user-question-required.md` | Every user-directed question goes through the `AskUserQuestion` tool — no plain-text questions |
+| `bdd.md` | BDD discovery-driven development workflow and Example Mapping reference |
+| `cleanup-temp-files.md` | Remove temporary files created during a task when the task is complete |
+| `code-reviews.md` | Mandatory protocol for responding to GitHub PR review feedback |
+| `code-standards.md` | Pointer to `CODE_RULES.md` as the single source of truth |
+| `confirm-implementation-forks.md` | Stop and ask when two or more workable implementation paths change the deliverable |
+| `conservative-action.md` | Research and recommend when intent is ambiguous; act only on explicit request |
+| `context7.md` | Use Context7 MCP to fetch current library docs; always prefer live docs over built-in knowledge |
+| `docstring-prose-matches-implementation.md` | Prose enumerations in docstrings cover every behavior the body applies |
+| `explore-thoroughly.md` | Read relevant files and map existing patterns before proposing a change |
+| `file-global-constants.md` | File-global constants need at least two same-file references; otherwise move value to `config/` |
+| `gh-body-file.md` | Use `--body-file` with a temp file for all `gh` commands carrying markdown body content |
+| `gh-paginate.md` | Use `--paginate --slurp` piped to external `jq` for paginated GitHub API list endpoints |
+| `git-workflow.md` | PR workflow: always create as draft, one commit per review stage, never commit working docs or images |
+| `hook-prose-matches-detector.md` | Hook prose descriptions match what the hook actually detects |
+| `long-horizon-autonomy.md` | Autonomous-run behaviors: act on what you have, do not end on a promise, delegate and keep working |
+| `no-cross-skill-duplicate-helpers.md` | No duplicating shared helpers across skills; use `_shared/` |
+| `no-historical-clutter.md` | Documentation describes current state only; no historical or transitional language |
+| `no-inline-destructive-literals.md` | No destructive-command literals in Bash tool command strings, even as data |
+| `orphan-css-class.md` | Every `class="..."` attribute in Python-generated markup has a matching selector in the `<style>` block |
+| `parallel-tools.md` | Make all independent tool calls in a single response |
+| `plain-language.md` | Everyday words, short active sentences, lead with the answer |
+| `prompt-workflow-context-controls.md` | Keep prompt-workflow instruction layers small and stable; load heavy skills on demand |
+| `research-mode.md` | Three anti-hallucination constraints: say "I don't know", verify with citations, quote for factual grounding |
+| `right-sized-engineering.md` | Simple over clever; functions over classes; concrete over abstract |
+| `self-contained-docs.md` | Every document is fully self-contained; no references to the conversation that produced it |
+| `shell-invocation-policy.md` | All Windows shell commands use `pwsh`; `powershell.exe`, `cmd /c`, and `bash -c` are blocked |
+| `tdd.md` | Test-driven development: red → green → refactor, no production code before a failing test |
+| `testing.md` | Test quality and infrastructure standards |
+| `vault-context.md` | Search Obsidian vault for prior sessions and decisions before substantive project work |
+| `verify-before-asking.md` | Answer questions by inspecting files or running tools before asking the user |
+| `windows-filesystem-safe.md` | Use safe `rmtree` patterns on Windows; `mkdirSync` with `recursive: true` on possibly-existing paths |
+| `workflow-substitution-slots.md` | Per-iteration values in `.workflow.js` templates use angle-bracket slots |
+
+## Hook enforcement
+
+Rules marked with ⚡ in `packages/claude-dev-env/docs/CODE_RULES.md` are backed by a blocking hook in `hooks/blocking/`. Rules without a hook are judgment-based and enforced via audit rubrics (`audit-rubrics/`).

package/rules/docstring-prose-matches-implementation.md

@@ -6,7 +6,7 @@
 
 When a docstring enumerates the behaviors a body applies, the enumeration covers every behavior the body applies. A reader trusts the list to be complete: an item the code applies but the prose omits is a silent gap that misleads every future reader and reviewer.
 
-The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"` — has no signature to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose. It carries documented-but-pending hook coverage; the audit lane below is the enforcement until a deterministic gate check exists.
+The gate validator `check_docstring_args_match_signature` covers the `Args:` section parameter names. Two more gate validators each cover one deterministic slice of the free-form prose. `check_docstring_fallback_branch_coverage` covers a summary that scopes a fallback to a single condition (`only when`, `falls back to ... when`) while the body routes to that same fallback call from two or more distinct early-return guards. `check_class_docstring_names_public_methods` covers a class whose docstring is a single summary line while the class exposes two or more public methods whose names the summary never spells out — the drift where a one-line class summary keeps naming its first feature after the class grows a second public entry point. The remaining free-form prose — `"a field counts as read when ..."`, `"resolves to shared temp only"`, `"strip ceremony, then drop blockquotes"`, and module-level responsibility paragraphs — has no signature, method roster, or single structural shape to compare against, so the gate cannot catch its drift. This rule is the judgment standard for that prose; the audit lane below is the enforcement for everything outside the three gated slices.
 
 ## What to check before you write the docstring
 
@@ -14,6 +14,7 @@ Read the body and the docstring side by side:
 
 - **Read-source / match-source unions.** A body that computes `read_names = a | b | c` (or any union of "what counts") names each union member in the prose enumeration. A union member the code applies but the prose omits is a gap.
 - **Suppressor / skip lists.** A body with several early returns that suppress the check names each suppressor in the prose.
+- **Shared fallback routes.** A summary that scopes a fallback call to one condition names every condition that reaches that call. When the body routes to the same fallback from two or more early-return guards (`if a is None: fallback(); return` and `if random() < p: fallback(); return`), the prose enumerates both guards. The `check_docstring_fallback_branch_coverage` gate blocks the single-condition form of this drift at Write/Edit time.
 - **Step order.** A docstring that says `A then B then C` matches the call order in the body.
 - **Predicate breadth.** A boolean helper whose prose promises a narrow check accepts only the inputs the prose names — no broader input class the name and prose do not mention.
 
@@ -36,7 +37,7 @@ A docstring that enumerates "attribute read, augmented-assignment target, class-
 
 ## Enforcement (audit lane)
 
-This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding.
+This drift class is sub-bucket **O6** in `packages/claude-dev-env/audit-rubrics/category_rubrics/category-o-docstring-vs-impl-drift.md` (free-form `Note:` / `Returns:` / responsibility-list claims). The audit teammate lists every prose enumeration in a changed docstring and verifies each item against the body, and lists every union member / suppressor / step in the body and verifies each appears in the prose. A union member or suppressor in the body that the prose omits is an O6 finding. The single-condition shared-fallback shape of this drift is gated deterministically by `check_docstring_fallback_branch_coverage` (`packages/claude-dev-env/hooks/blocking/code_rules_docstrings.py`); the audit lane covers every O6 shape the gate cannot match.
 
 ## Why
 

package/scripts/CLAUDE.md

@@ -0,0 +1,34 @@
+# scripts
+
+Utility scripts installed into `~/.claude/scripts/` by `bin/install.mjs`. Each script is a standalone tool a user or hook can invoke directly.
+
+## Scripts
+
+| File | Purpose |
+|---|---|
+| `setup_project_paths.py` | One-time bootstrap: discovers git repos via `es.exe` (Everything) and writes `~/.claude/project-paths.json`; never hardcodes scan roots |
+| `sweep_empty_dirs.py` | Deletes empty directories older than a configurable age under a given root; runs once (`--once`) or in continuous-watch mode |
+| `sync_to_cursor.py` | Entry point for syncing Claude rules to Cursor `.mdc` files; delegates to the `sync_to_cursor/` package |
+
+## PowerShell scripts
+
+| File | Purpose |
+|---|---|
+| `Audit-ShellPolicy.ps1` | Audits Bash tool calls in session transcripts against the `pwsh`-only shell policy |
+| `Migrate-ShellPolicy.ps1` | Applies automated fixes for common shell-policy violations found by the audit script |
+| `Install-SweepEmptyDirs.ps1` | Registers `sweep_empty_dirs.py` as a scheduled task on Windows |
+| `check.ps1` | Runs the full code-quality check suite |
+
+## Subdirectories
+
+| Entry | Description |
+|---|---|
+| `dev_env_scripts_constants/` | Named constants (`timing.py`) for scripts in this directory |
+| `sync_to_cursor/` | Package that builds Cursor `.mdc` files from Claude rules and docs |
+| `tests/` | pytest suite for the Python scripts in this directory |
+
+## Running tests
+
+```bash
+python -m pytest packages/claude-dev-env/scripts/tests/
+```

package/scripts/dev_env_scripts_constants/CLAUDE.md

@@ -0,0 +1,14 @@
+# dev_env_scripts_constants
+
+Named constants for scripts in `scripts/`. Follows the project convention that timeouts, delays, and retries live in `timing.py`.
+
+## Modules
+
+| File | Constants for |
+|---|---|
+| `timing.py` | `sweep_empty_dirs.py` — `DEFAULT_AGE_SECONDS` (smallest age before an empty directory is eligible for removal) and `DEFAULT_POLL_INTERVAL` (seconds between sweep passes in continuous-watch mode) |
+| `__init__.py` | Empty package marker |
+
+## Convention
+
+Every constant is `UPPER_SNAKE_CASE` with an explicit type annotation and a docstring. Scripts import from here rather than embedding literal values in their bodies.

package/scripts/sync_to_cursor/CLAUDE.md

@@ -0,0 +1,23 @@
+# sync_to_cursor
+
+Python package that syncs Claude rules and docs to Cursor `.mdc` files. Entry point is `packages/claude-dev-env/scripts/sync_to_cursor.py`; this package holds the implementation modules.
+
+## Modules
+
+| File | Purpose |
+|---|---|
+| `engine.py` | Main sync logic: loads the manifest, builds rule mappings, hashes sources, writes `.mdc` files, and updates the manifest |
+| `rules.py` | Builds `RuleMapping` objects from Claude rule markdown files; applies transforms to fit Cursor's `.mdc` format |
+| `canonical_docs.py` | Checks and syncs canonical documentation files (`CODE_RULES.md`, `TEST_QUALITY.md`) to the Cursor rules directory |
+| `paths.py` | Resolves the Claude and Cursor layout paths; respects the `LLM_SETTINGS_ROOT` env var for non-home layouts |
+| `hashing.py` | SHA-256 helpers that detect whether source files changed since the last sync run |
+| `config.py` | Package-level constants: `GENERATOR_VERSION`, `CANONICAL_DOC_FILES`, `MAX_RULE_BODY_LINES` |
+| `__init__.py` | Empty package marker |
+
+## Layout resolution
+
+`paths.py` reads `LLM_SETTINGS_ROOT` from the environment. When set, it uses that path as the base for both `.claude/` and `.cursor/`. When unset, it falls back to `Path.home()`.
+
+## Tests
+
+Tests live in `packages/claude-dev-env/scripts/tests/test_sync_to_cursor.py`.

package/scripts/tests/CLAUDE.md

@@ -0,0 +1,18 @@
+# scripts/tests
+
+pytest suite for the Python scripts in `scripts/`.
+
+## Test files
+
+| File | Covers |
+|---|---|
+| `test_setup_project_paths.py` | `setup_project_paths.py` — discovery, filtering, and `project-paths.json` writing |
+| `test_setup_project_paths_config.py` | Configuration constants used by `setup_project_paths.py` |
+| `test_sweep_empty_dirs.py` | `sweep_empty_dirs.py` — age check, one-shot mode, and continuous-watch behavior |
+| `test_sync_to_cursor.py` | `sync_to_cursor/` package — mapping, hashing, manifest, and path resolution |
+
+## Running
+
+```bash
+python -m pytest packages/claude-dev-env/scripts/tests/
+```

package/skills/CLAUDE.md

@@ -0,0 +1,66 @@
+# Skills Directory
+
+Each skill is a self-contained folder Claude Code loads on demand. At startup, only the skill's `name` and `description` metadata load. The full `SKILL.md` body and any support files load only when a skill becomes relevant to the conversation.
+
+## Skill folder convention
+
+| Item | Role |
+|---|---|
+| `SKILL.md` | Required entry point. YAML frontmatter with `name` and `description` (the trigger). Body holds the skill's full instructions. |
+| `scripts/` | Python helper scripts the skill invokes at runtime. |
+| `workflow/` | `.mjs` workflow scripts run via the `Workflow` tool. |
+| `templates/` | Template files the skill or workflow renders at build time. |
+| `reference/` | Reference docs the skill cites or the workflow reads. |
+| `*_constants/` | Python package of named constants imported by `scripts/`. |
+
+Skills install to `~/.claude/skills/<skill-name>/` via `packages/claude-dev-env/bin/install.mjs`. See `docs/references/skill-install-system.md` for the install pipeline.
+
+## Shared support code
+
+`_shared/` — support code used by more than one skill. It holds `pr-loop/`, which provides prompt templates and Python helper scripts shared between `bugteam` and `pr-converge`.
+
+## Skill groups
+
+**Planning and implementation**
+- `anthropic-plan` — creates a source-grounded plan packet before any code changes
+- `implement` — structured implementation from an existing plan packet
+- `bdd-protocol` — BDD depth: Example Mapping, scenario quality, outside-in layout
+- `verified-build` — build + test loop that gates on a verifier verdict
+
+**PR review and convergence**
+- `autoconverge` — autonomous single-run workflow that drives a PR to ready
+- `pr-converge` — paced convergence loop across `ScheduleWakeup` ticks
+- `bugteam` — open-loop audit-fix until convergence
+- `pr-review-responder` — fetches all reviewer comments and replies systematically
+- `pr-consistency-audit` — cross-file consistency check on a PR diff
+- `copilot-review` — requests and polls a GitHub Copilot review
+- `findbugs` / `fixbugs` — find bugs then fix them in separate passes
+- `code` — strict-mode code generation session
+
+**Research and discovery**
+- `deep-research` — multi-source research with citation
+- `research-mode` — activates anti-hallucination discipline for a session
+- `recall` — retrieves facts from memory files
+- `remember` — saves a decision, gotcha, or architectural choice to the Obsidian vault
+- `everything-search` — file-system search via the Everything MCP tool
+- `caveman` — trims noise from a draft artifact
+
+**Session and workflow management**
+- `session-log` — logs a session report to the Obsidian vault
+- `session-tidy` — tidies the session folder
+- `bg-agent` — launches a background agent
+- `task-build` — gathers open tasks
+- `update` — updates the dev-env package
+- `gh-paginate` — safe `gh api` pagination patterns
+- `fresh-branch` — creates a clean branch off main
+- `rebase` — rebases onto main
+- `gotcha` — records a hard-won lesson to memory
+- `logifix` — restores the Logitech Gaming Software (LCore) tray icon when it disappears on Windows
+- `refine` — refinement pass on an artifact
+- `structure-prompt` — structures a freeform prompt
+- `monitor-open-prs` — polls open PRs for status
+- `pre-compact` — compact-safe session handoff
+- `qbug` — required baseline PR audit; one clean-coder subagent loops audit → fix → commit → push until clean or stuck
+- `skill-builder` — complete skill-building lifecycle
+- `doc-gist` — uploads an HTML file as a secret gist
+- `auditing-claude-config` — audits a Claude Code setup for context-budget waste and produces a migration table with savings

package/skills/_shared/CLAUDE.md

@@ -0,0 +1,11 @@
+# _shared
+
+Support code shared across multiple skills. Each subdirectory targets a specific cross-skill concern.
+
+## Subdirectories
+
+| Directory | Role |
+|---|---|
+| `pr-loop/` | Prompt templates and Python helper scripts used by both `bugteam` and `pr-converge` for their audit-fix loop. |
+
+Files here are not skills themselves and have no `SKILL.md`. They install alongside each consuming skill via the install pipeline in `packages/claude-dev-env/bin/install.mjs`.

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.