claude-dev-env 8.62.1 → 8.63.0

package/.agents/skills/context-audit/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: context-audit
+description: Inventory every file an agent loads from a repository checkout, with size, trigger, and depth mode, then list what to clean up. Use when the user asks to audit the context in a repository, measure instruction or skill load, or find bloated CLAUDE.md, AGENTS.md, rules, or skills.
+---
+
+# Context audit
+
+Use this skill when the user says "audit the context in <repository>" or asks what an agent loads from a checkout.
+
+## Run
+
+```
+python "${CLAUDE_SKILL_DIR}/scripts/context_audit.py" <repository-root> --rows <scratch>/rows.jsonl
+```
+
+Add these options when they apply:
+
+| Option | When |
+|---|---|
+| `--rules-dir <path>` | The repository ships a folder that installs as the user rules folder. |
+| `--skills-dir <path>` | The repository ships a folder that installs as the user skills folder. |
+| `--session-start-text <file>` | A SessionStart hook prints text. Save that text to a file first. Repeat for each hook. |
+
+Paths for `--rules-dir` and `--skills-dir` are relative to the repository root. The script runs no hook command.
+
+## Read the output
+
+The report opens with the startup load in lines and estimated tokens, then a table by trigger. The cleanup list follows in three sections.
+
+1. **Carries depth over cap.** An entry file holds depth that belongs in a reference. Move that depth into a linked file and leave a pointer.
+2. **Empty instruction stubs.** An instruction file or rule with no content. Delete it unless a tool needs the file to exist.
+3. **Long skills to split.** A skill body over 200 lines. Keep the steps every run uses in `SKILL.md` and move the rest into `references/`.
+
+Content used on every invocation stays in the entry file. Moving it behind a link adds a read to every run.
+
+Hand the user the cleanup list with paths, line counts, and caps. The rows file holds every row for follow-up questions.
+
+[references/depth-modes.md](references/depth-modes.md) has the triggers, the depth modes, the caps table, and the row fields.
+
+## Layout
+
+| File | Purpose |
+|---|---|
+| `scripts/context_audit.py` | Command line entry point. Prints the report and writes the rows file. |
+| `scripts/context_inventory.py` | Walks the checkout and records one row per loaded file. |
+| `scripts/context_sources.py` | Reads files, parses frontmatter, follows links and imports, and measures rows. |
+| `scripts/context_report.py` | Formats the summary, the trigger table, and the cleanup list. |
+| `scripts/context_audit_constants/config/constants.py` | Caps, patterns, labels, and report templates. |

package/.agents/skills/context-audit/references/depth-modes.md

@@ -0,0 +1,67 @@
+# Triggers, depth modes, and caps
+
+## Principle
+
+Keep entry points thin and references thick. An entry file loads on a trigger the agent does not choose, so every line in it costs context on every run. A reference loads only when a link sends the agent there.
+
+Content used on every invocation stays in the entry file. Moving it behind a link adds a file read to every run and saves nothing.
+
+## Triggers
+
+| Trigger | What loads the file |
+|---|---|
+| `session-start` | Root `CLAUDE.md`, `AGENTS.md`, `CLAUDE.local.md` and their `@` imports, rules without `paths`, skill descriptions in a project or installed skills folder, and saved SessionStart hook text. |
+| `folder-enter` | Instruction files in a subfolder, and skill descriptions in a nested `.claude/skills` folder. |
+| `path-match` | Rules whose frontmatter has `paths`. They load when the agent reads a matching file. |
+| `skill-invoke` | A skill body. It loads when the skill runs. |
+| `on-link` | Files under a skill folder other than `SKILL.md`, and markdown files reached through a relative link. Link depth counts hops from the first entry file. |
+| `file-open` | A Python module docstring. The agent reads it when it opens the file. |
+
+A skill with `disable-model-invocation: true` has no listing row. Skills under folders named `tests` or `fixtures`, or with `archive` in a folder name, are skipped.
+
+## Depth modes
+
+| Mode | Meaning |
+|---|---|
+| `empty` | One byte or less. |
+| `carries` | Over the line cap, or over the cap times 120 bytes. |
+| `points` | Within the cap, with relative links out. |
+| `lean` | Within the cap, with no links out. |
+| `reference` | On-link depth. No cap applies. |
+
+## Caps
+
+| Kind | Cap |
+|---|---|
+| Root instructions and their imports, saved hook text | 20 lines |
+| Nested instructions and their imports | 12 lines |
+| Rule | 20 lines |
+| Skill body | 200 lines |
+| Module docstring | 15 lines |
+| Skill description | 500 characters. The listing truncates at 1,536. |
+
+The caps live in `scripts/context_audit_constants/config/constants.py`.
+
+## Row fields
+
+Each line of the rows file is one JSON object.
+
+| Field | Meaning |
+|---|---|
+| `path` | Path relative to the repository root, or the hook text file name. |
+| `kind` | `instructions`, `import`, `rule`, `skill-description`, `skill-body`, `skill-reference`, `hook-text`, `linked-doc`, or `docstring`. |
+| `loader` | What reads the file. |
+| `trigger` | One trigger from the table above. |
+| `bytes`, `lines` | Size of the text the agent receives. |
+| `est_tokens` | Bytes divided by 4. An estimate. |
+| `links_out` | Relative markdown links that resolve inside the repository. |
+| `depth_mode` | One mode from the table above. |
+| `cap` | The cap that applies, or null. |
+| `note` | Extra context, such as link depth. |
+
+## Splitting a long file
+
+1. List the steps every run uses. Keep them in the entry file.
+2. Move each detail that only some runs need into its own file under `references/`.
+3. Link each moved file from the entry file with one line that says when to read it.
+4. Rerun the audit and confirm the entry file is `points` or `lean`.

package/.agents/skills/context-audit/scripts/context_audit.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""Inventory every file an agent loads from one checkout, then print a cleanup list.
+
+::
+
+    python context_audit.py <repo-root> --rows rows.jsonl
+    # Context audit: my-repo
+    412 loaded files. Startup loads 96 lines, about 1830 tokens, from 9 files.
+    ## Carries depth over cap
+    | AGENTS.md | instructions | session-start | 64 | 20 | 1210 |
+
+Each JSON row names a path, kind, loader, trigger, size, and depth mode.
+Hook text is read from saved files; the script runs no hook command.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from pathlib import Path
+
+from context_audit_constants.config import constants
+from context_inventory import audit_checkout
+from context_report import format_report
+from context_sources import ContextRow
+
+
+def write_rows(all_rows: list[ContextRow], into: Path) -> None:
+    """Write one JSON object per row to *into*.
+
+    Args:
+        all_rows: Inventory rows.
+        into: The JSON Lines file to write.
+    """
+    with into.open("w", encoding=constants.TEXT_ENCODING) as rows_file:
+        for each_row in all_rows:
+            rows_file.write(json.dumps(asdict(each_row)) + constants.LINE_BREAK)
+
+
+def _parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument("root", type=Path, help="the repository checkout to audit")
+    parser.add_argument("--rows", type=Path, help="write every row as JSON Lines here")
+    parser.add_argument(
+        "--rules-dir",
+        type=Path,
+        help="tracked folder installed as the user rules folder",
+    )
+    parser.add_argument(
+        "--skills-dir",
+        type=Path,
+        help="tracked folder installed as the user skills folder",
+    )
+    parser.add_argument(
+        "--session-start-text",
+        type=Path,
+        action="append",
+        default=[],
+        help="saved text a SessionStart hook prints; repeat for each hook",
+    )
+    return parser.parse_args()
+
+
+def _input_error(parsed: argparse.Namespace) -> str | None:
+    if not (parsed.root / constants.GIT_FOLDER_NAME).exists():
+        return constants.ERROR_NOT_A_CHECKOUT_TEMPLATE.format(path=parsed.root)
+    for each_hook_text_file in parsed.session_start_text:
+        if not each_hook_text_file.is_file():
+            return constants.ERROR_MISSING_FILE_TEMPLATE.format(
+                path=each_hook_text_file
+            )
+    return None
+
+
+def _resolve_under(root: Path, maybe_folder: Path | None) -> Path | None:
+    return (root / maybe_folder).resolve() if maybe_folder else None
+
+
+def main() -> int:
+    """Run the audit and print the report.
+
+    Returns:
+        The process exit code.
+    """
+    parsed = _parse_arguments()
+    error_message = _input_error(parsed)
+    if error_message:
+        print(error_message, file=sys.stderr)
+        return constants.EXIT_CODE_INPUT_ERROR
+    root = parsed.root.resolve()
+    all_rows = audit_checkout(
+        root,
+        _resolve_under(root, parsed.rules_dir),
+        _resolve_under(root, parsed.skills_dir),
+        tuple(parsed.session_start_text),
+    )
+    report = format_report(root.name, all_rows)
+    if parsed.rows:
+        write_rows(all_rows, parsed.rows)
+        rows_line = constants.REPORT_ROWS_WRITTEN_TEMPLATE.format(path=parsed.rows)
+        report += constants.LINE_BREAK + rows_line + constants.LINE_BREAK
+    print(report, end="")
+    return constants.EXIT_CODE_AUDITED
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/.agents/skills/context-audit/scripts/context_audit_constants/__init__.py

@@ -0,0 +1 @@
+"""Named constants for the context-audit skill scripts."""

package/.agents/skills/context-audit/scripts/context_audit_constants/config/__init__.py

@@ -0,0 +1 @@
+"""Configuration for the context audit."""

package/.agents/skills/context-audit/scripts/context_audit_constants/config/constants.py

@@ -0,0 +1,179 @@
+"""Constants for the context audit.
+
+The enums name each trigger, depth mode, row kind, and cap.
+The plain constants hold the caps, file names, patterns, and labels.
+The report constants hold the headings and row templates.
+"""
+
+from __future__ import annotations
+
+from enum import StrEnum
+
+
+class Trigger(StrEnum):
+    """When an agent loads a file into its context."""
+
+    SESSION_START = "session-start"
+    FOLDER_ENTER = "folder-enter"
+    PATH_MATCH = "path-match"
+    SKILL_INVOKE = "skill-invoke"
+    ON_LINK = "on-link"
+    FILE_OPEN = "file-open"
+
+
+class DepthMode(StrEnum):
+    """How much depth a file carries against its cap."""
+
+    EMPTY = "empty"
+    CARRIES = "carries"
+    POINTS = "points"
+    LEAN = "lean"
+    REFERENCE = "reference"
+
+
+class RowKind(StrEnum):
+    """What role a loaded file plays."""
+
+    INSTRUCTIONS = "instructions"
+    IMPORT = "import"
+    RULE = "rule"
+    SKILL_DESCRIPTION = "skill-description"
+    SKILL_BODY = "skill-body"
+    SKILL_REFERENCE = "skill-reference"
+    HOOK_TEXT = "hook-text"
+    LINKED_DOC = "linked-doc"
+    DOCSTRING = "docstring"
+
+
+class CapKey(StrEnum):
+    """Which line cap applies to a row."""
+
+    ROOT_INSTRUCTIONS = "root-instructions"
+    NESTED_INSTRUCTIONS = "nested-instructions"
+    RULE = "rule"
+    SKILL_BODY = "skill-body"
+    DOCSTRING = "docstring"
+
+
+ALL_LINE_CAP_BY_KEY = {
+    CapKey.ROOT_INSTRUCTIONS: 20,
+    CapKey.NESTED_INSTRUCTIONS: 12,
+    CapKey.RULE: 20,
+    CapKey.SKILL_BODY: 200,
+    CapKey.DOCSTRING: 15,
+}
+DESCRIPTION_CHARACTER_CAP = 500
+DESCRIPTION_LISTING_CHARACTER_LIMIT = 1536
+CHARACTERS_PER_CAPPED_LINE = 120
+BYTES_PER_ESTIMATED_TOKEN = 4
+EMPTY_FILE_BYTE_LIMIT = 1
+FIRST_LINK_DEPTH = 1
+DESCRIPTION_LINE_COUNT = 1
+
+ALL_SKIPPED_PATH_PARTS = frozenset(
+    {
+        ".git",
+        ".venv",
+        "node_modules",
+        "__pycache__",
+        ".pytest_cache",
+        ".mypy_cache",
+    }
+)
+ALL_TEXT_SUFFIXES = frozenset({".md", ".mdc", ".txt"})
+PYTHON_SUFFIX = ".py"
+MARKDOWN_SUFFIX = ".md"
+ALL_INSTRUCTION_FILE_NAMES = frozenset({"CLAUDE.md", "AGENTS.md", "CLAUDE.local.md"})
+AGENTS_FILE_NAME = "AGENTS.md"
+CLAUDE_FILE_NAME = "CLAUDE.md"
+AGENTS_IMPORT_LINE = "@AGENTS.md"
+SKILL_FILE_NAME = "SKILL.md"
+GIT_FOLDER_NAME = ".git"
+CLAUDE_FOLDER_NAME = ".claude"
+SKILLS_FOLDER_NAME = "skills"
+PLUGINS_FOLDER_NAME = "plugins"
+ALL_PROJECT_RULES_PATH_PARTS = (CLAUDE_FOLDER_NAME, "rules")
+ALL_SKILL_HOME_FOLDER_NAMES = frozenset({CLAUDE_FOLDER_NAME, ".agents"})
+ARCHIVE_FOLDER_MARKER = "archive"
+ALL_FIXTURE_FOLDER_NAMES = frozenset({"tests", "fixtures"})
+MINIMUM_SKILL_PATH_PARTS = 3
+
+ALL_GIT_LIST_FILES_ARGUMENTS = ("git", "ls-files", "-z")
+GIT_LIST_FILES_SEPARATOR = b"\0"
+TEXT_ENCODING = "utf-8"
+TEXT_DECODE_ERRORS = "replace"
+LINE_BREAK = "\n"
+NOTE_SEPARATOR = "; "
+
+LINK_PATTERN = r"\[[^\]]*\]\(([^)\s#]+)(?:#[^)]*)?\)"
+IMPORT_PATTERN = r"(?m)^\s*@([^\s]+)"
+URL_SCHEME_PATTERN = r"^[a-z]+:"
+FRONTMATTER_FENCE = "---"
+FRONTMATTER_CLOSING_FENCE = "\n---"
+FRONTMATTER_FIELD_PATTERN = r"^([A-Za-z_-]+):\s*(.*)$"
+ALL_FRONTMATTER_CONTINUATION_PREFIXES = (" ", "\t", "-")
+PATHS_FIELD = "paths"
+DESCRIPTION_FIELD = "description"
+WHEN_TO_USE_FIELD = "when_to_use"
+DISABLE_MODEL_INVOCATION_FIELD = "disable-model-invocation"
+TRUE_TEXT = "true"
+DESCRIPTION_JOIN_TEMPLATE = "{description} {when_to_use}"
+
+LOADER_HARNESS = "Claude Code harness"
+LOADER_AGENTS_IMPORTED = "@import from CLAUDE.md"
+LOADER_AGENTS_SHADOWED = (
+    "not read by Claude Code (sibling CLAUDE.md, no import); Codex reads it"
+)
+LOADER_AGENTS_NATIVE = "Claude Code native AGENTS.md read; Codex reads it"
+LOADER_IMPORT_TEMPLATE = "@import from {source}"
+LOADER_RULE_PROJECT = "Claude Code harness, .claude/rules"
+LOADER_RULE_INSTALLED = "Claude Code harness, installed rules folder"
+LOADER_SKILL_LISTING_TEMPLATE = "skill listing, {location}"
+LOADER_SKILL_INVOCATION = "skill invocation"
+LOADER_SKILL_REFERENCE_TEMPLATE = "read on demand from {source}"
+LOADER_LINK_TEMPLATE = "markdown link from {source}"
+LOADER_DOCSTRING = "module docstring, read when an agent opens the file"
+LOADER_LINKED_DOCSTRING_TEMPLATE = "module docstring linked from {source}"
+LOADER_HOOK_TEXT = "SessionStart hook text"
+LOCATION_PROJECT_SKILLS = "project skills folder"
+LOCATION_NESTED_SKILLS = "nested .claude/skills folder"
+LOCATION_INSTALLED_SKILLS = "installed skills folder"
+LOCATION_PLUGIN_SKILLS = "plugin skills folder"
+NOTE_CODEX_AGENTS = (
+    "Codex: loaded when the working directory is at or below this folder"
+)
+NOTE_IMPORT = "imports load in full with the importing file"
+NOTE_INSTALLED_RULE = "installed rule: loads in every project"
+NOTE_DESCRIPTION_TRUNCATED = "listing truncates at 1,536 characters"
+NOTE_LINK_DEPTH_TEMPLATE = "link depth {depth}"
+NOTE_HOOK_TEXT = "measured from the saved hook text file"
+NOTE_PLUGIN_SKILL = "loads when the plugin is installed"
+
+REPORT_TITLE_TEMPLATE = "# Context audit: {name}"
+REPORT_SUMMARY_TEMPLATE = (
+    "{row_count} loaded files. Startup loads {lines} lines, about "
+    "{tokens} tokens, from {files} files."
+)
+REPORT_TRIGGER_HEADING = "## Load by trigger"
+REPORT_TRIGGER_HEADER = "| trigger | files | lines | est tokens |"
+REPORT_FOUR_COLUMN_RULE = "|---|---|---|---|"
+REPORT_TRIGGER_ROW_TEMPLATE = "| {trigger} | {files} | {lines} | {tokens} |"
+REPORT_CARRIES_HEADING = "## Carries depth over cap"
+REPORT_CARRIES_HEADER = "| path | kind | trigger | lines | cap | est tokens |"
+REPORT_SIX_COLUMN_RULE = "|---|---|---|---|---|---|"
+REPORT_CARRIES_ROW_TEMPLATE = (
+    "| {path} | {kind} | {trigger} | {lines} | {cap} | {tokens} |"
+)
+REPORT_EMPTY_HEADING = "## Empty instruction stubs"
+REPORT_EMPTY_ROW_TEMPLATE = "- {path} ({kind})"
+REPORT_SPLIT_HEADING = "## Long skills to split"
+REPORT_SPLIT_HEADER = "| path | lines | cap | est tokens |"
+REPORT_SPLIT_ROW_TEMPLATE = "| {path} | {lines} | {cap} | {tokens} |"
+REPORT_NONE_LINE = "None."
+REPORT_ROWS_WRITTEN_TEMPLATE = "Rows written to {path}."
+ALL_STUB_KINDS = frozenset({RowKind.INSTRUCTIONS, RowKind.IMPORT, RowKind.RULE})
+
+ERROR_NOT_A_CHECKOUT_TEMPLATE = "not a git checkout: {path}"
+ERROR_MISSING_FILE_TEMPLATE = "file not found: {path}"
+EXIT_CODE_AUDITED = 0
+EXIT_CODE_INPUT_ERROR = 2