diff --git a/.claude/commands/optimization/audit.md b/.claude/commands/optimization/audit.md new file mode 100644 index 0000000..930efee --- /dev/null +++ b/.claude/commands/optimization/audit.md @@ -0,0 +1,173 @@ +--- +description: "Read-only token audit of .claude/. Profiles agent description cost, finds unreferenced/cold agents, flags over-permissioned tools, estimates per-session token budget. Run /optimize to apply fixes." +argument-hint: [verbose] +--- + +# /audit — .claude Token & Usage Audit + +Read-only analysis of the `.claude/` directory. Profiles token cost, finds unreferenced agents, verbose descriptions, and over-permissioned tools. Makes no changes. + +**Not in scope**: skill trigger gaps → use `/improve`. AI quality critique → use `/self-improve`. + +## Steps + +### 1. Agent inventory + +```bash +ls .claude/agents/*.md 2>/dev/null +wc -c .claude/agents/*.md 2>/dev/null +grep -h '^description:' .claude/agents/*.md 2>/dev/null +grep -h '^name:' .claude/agents/*.md 2>/dev/null +``` + +For each agent compute: +- `desc_chars` = character count of the `description:` value (strip surrounding quotes) +- `desc_tokens` = `desc_chars / 4` (rounded) +- `file_tokens` = `file_bytes / 4` (rounded) + +### 2. Command cross-reference + +```bash +grep -rh 'agent:' .claude/commands/ 2>/dev/null +grep -rl 'subagent_type' .claude/commands/ 2>/dev/null +grep -rh 'subagent_type' .claude/commands/ 2>/dev/null +grep -rh '@agents/' .claude/commands/ 2>/dev/null +``` + +Also search agent names (by slug) in all command bodies: +```bash +for agent in .claude/agents/*.md; do + name=$(grep '^name:' "$agent" | head -1 | sed "s/name: *//;s/['\"]//g") + count=$(grep -rl "$name" .claude/commands/ 2>/dev/null | wc -l) + echo "$count $name" +done +``` + +Build: +- `referenced_agents` = agents named in any command file +- `unreferenced_agents` = agents present in `.claude/agents/` with zero command references + +### 3. Learning log cross-reference (optional) + +```bash +ls .claude/learning/sessions/*.jsonl 2>/dev/null | head -5 +``` + +- If **no logs found**: note "Learning logs not found — cold agent detection skipped. Enable the learning logger hook, or logs will appear after sessions run." +- If **`mempalace.yaml` exists** in the project root: note it as an alternative memory source (do not parse it — different schema). +- If logs found: + ```bash + cat .claude/learning/sessions/*.jsonl 2>/dev/null + ``` + Aggregate every agent name that ever appeared in any `agents_spawned` array. + - `cold_agents` = filesystem agents whose name never appeared + - `log_date_range` = min/max `date` values + - `log_record_count` = total records + - If `agents_spawned: []` in **all** records: flag as data gap ("logger may not capture Task-tool sub-agent spawns") — do NOT report all agents as cold. + +### 4. Verbosity scan + +```bash +grep -h '^description:' .claude/agents/*.md 2>/dev/null +``` + +Flag: +- **Verbose** = description > 200 chars (~50+ tokens) — inflates system prompt every session +- **Minimal** = description < 60 chars — may be too sparse for accurate agent selection + +Rank all agents by `desc_chars` descending. + +### 5. Tool scope scan + +```bash +grep -h '^tools:' .claude/agents/*.md 2>/dev/null +grep -h '^name:\|^tools:' .claude/agents/*.md 2>/dev/null +``` + +Flag: +- Bare `Bash` with no parentheses (unscoped — can run any shell command) +- `MultiEdit` or `TodoWrite` on agents whose role is read-only (reviewer, researcher, reader agents) + +### 6. Empty directory scan + +```bash +find .claude/commands/ -mindepth 1 -maxdepth 1 -type d | while read d; do + count=$(ls "$d"/*.md 2>/dev/null | wc -l) + echo "$count $d" +done +``` + +Flag dirs where count = 0. + +### 7. Token budget + +Compute: +- `total_desc_tokens` = sum of all `desc_tokens` (loaded every session via system prompt) +- `unref_file_tokens` = sum of `file_tokens` for unreferenced agents +- `savings_archive` = `unref_file_tokens` +- `savings_compress` = `total_desc_tokens * 0.67` (assumes compression to ~100 chars avg) + +### 8. Output report + +```markdown +## /audit Report — + +### Token Budget Summary +| Category | Est. tokens | Notes | +|---|---|---| +| All agent descriptions | ~ | Loaded every session | +| Unreferenced agent files | ~ | Loaded every session, 0 commands reference them | +| Est. savings — archive unreferenced | ~/session | | +| Est. savings — compress descriptions | ~/session | Assumes 3× reduction | + +### Unreferenced Agents +No command spawns these — they load into context but are never called: + +| Agent | File | Est. tokens | Description (truncated) | +|---|---|---|---| +| | | ~ | | + +Suggestion: archive to `.claude/agents/archive/` or add commands that surface them. + +### Cold Agents (learning log cross-reference) + + +### Verbose Descriptions (>200 chars) +| Agent | Chars | Est. tokens | Savings to 100 chars | +|---|---|---|---| +| | | ~ | ~ tok | + +### Minimal Descriptions (<60 chars) + + +### Tool Scope Issues +| Agent | Flag | Details | +|---|---|---| +| | Unscoped Bash | Consider: Bash(cmd:*) restriction | +| | MultiEdit on read-only agent | Review if write access is needed | + +### Empty Command Directories + + +### Recommendations (ranked by token impact) +1. **Archive unreferenced agents** — saves ~ tok/session + Run: `/optimize structural` + +2. **Compress verbose descriptions** — saves ~ tok/session + Run: `/optimize` (or `/optimize descriptions`) + +3. **Scope unscoped Bash on agents** — security improvement + Run: `/optimize structural` for instructions +``` + +Print "None found." for any empty section. + +If `$ARGUMENTS` is `verbose`, include a full per-agent table with name, desc_chars, desc_tokens, file_tokens, and reference count. + +## Notes + +- Read-only — no files are modified. +- Token estimates: chars/4 approximation (±20% accuracy). +- Learning logs are optional infrastructure. `/audit` works fully without them. +- For skill trigger gaps use `/improve`. For multi-AI quality critique use `/self-improve`. +- To apply safe fixes run `/optimize`. diff --git a/.claude/commands/optimization/optimize.md b/.claude/commands/optimization/optimize.md new file mode 100644 index 0000000..c9be7dd --- /dev/null +++ b/.claude/commands/optimization/optimize.md @@ -0,0 +1,152 @@ +--- +description: "Apply safe token optimizations to .claude/ agents. AI-rewrites verbose descriptions to ~100 chars. Prints manual instructions for archiving unreferenced agents and scoping tools. Requires confirmation before writing any file." +argument-hint: [descriptions | structural | all] +--- + +# /optimize — .claude Token Optimizer + +Applies safe, reversible optimizations to reduce per-session token cost. + +- **`descriptions`** (default) — AI-rewrites verbose `description:` fields to ~100 chars. Requires confirmation before any write. +- **`structural`** — prints manual instructions for archiving agents and scoping tools. No files written. +- **`all`** — both of the above. + +**Write scope**: only the `description:` line in agent frontmatter. Agent bodies are never modified. +**Not in scope**: skill trigger gaps (use `/improve`), AI quality critique (use `/self-improve`). + +## Steps + +### 1. Determine mode + +``` +MODE = $ARGUMENTS (default if empty: "descriptions") +``` + +### 2. Gather current state + +Run these reads regardless of mode: + +```bash +grep -h '^name:\|^description:\|^tools:' .claude/agents/*.md 2>/dev/null +wc -c .claude/agents/*.md 2>/dev/null +grep -rh 'agent:' .claude/commands/ 2>/dev/null +grep -rh '@agents/' .claude/commands/ 2>/dev/null +``` + +Identify: +- `verbose_agents` = agents with description > 200 chars +- `unreferenced_agents` = agents with 0 command references +- `unscoped_bash_agents` = agents where `tools:` contains bare `Bash` (no parentheses) + +### 3. Description compression (if mode is `descriptions` or `all`) + +For each agent in `verbose_agents`, generate a compressed description. + +**Compression rules:** +- Target: 80–110 characters (20–28 tokens) +- Preserve: role, who invokes it (if a sub-agent), primary output artifact +- Remove: filler phrases ("Be sure to", "Always call", "Proactively"), redundant workflow step labels, over-specified minor behaviors +- Keep: spawn relationships ("Invoked by X only"), tool restrictions ("Never modifies files") + +Show a diff-style preview for every agent before writing anything: + +``` +━━━ dev-lead.md ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ + Before: 341 chars (~85 tok) + "Dev lead orchestrator (opus). Owns end-to-end implementation of a single + GitHub issue. Reads the issue and PRP, classifies the work, spawns + engineering sub-agents in sequence with narrow context, runs all 5 + validation gates, and ships. Never writes code directly — delegates to + dev-backend, dev-frontend, dev-test, dev-e2e, and dev-reviewer." + + After: 102 chars (~26 tok) + "Implements a GitHub issue end-to-end. Classifies work, spawns sub-agents + with narrow context, runs 5 validation gates, ships PR." + + Savings: ~59 tokens +``` + +After showing all previews, ask: + +> **Apply description rewrites?** +> - `all` — apply all rewrites +> - ` ...` — apply only listed agents (space-separated slugs) +> - `none` — skip + +Wait for user response. If `none` or no response confirms, skip all writes. + +For each approved agent: +1. Read the full agent file +2. Locate the `description:` line in the frontmatter (between the opening `---` and closing `---`) +3. Replace only that line with the new value (preserve all surrounding frontmatter and body) +4. Write the file back +5. Confirm: `✓ Updated .claude/agents/.md — saved ~ tokens` + +### 4. Structural instructions (if mode is `structural` or `all`) + +Print the following as instructions — do NOT auto-execute any of these: + +```markdown +## Structural Optimization Instructions + +### Archive Unreferenced Agents +These agents load into every session but no command ever spawns them. +Moving to an archive directory removes them from the agent loader. + +Files: + +Steps: + mkdir -p .claude/agents/archive + git mv .claude/agents/.md .claude/agents/archive/ + # repeat for each + git commit -m "chore: archive unreferenced agents" + +Token savings: ~/session (full file content no longer loaded) +Reversible: git mv .claude/agents/archive/.md .claude/agents/ + +To surface them instead of archiving, create wrapper commands: + .claude/commands/optimization/validate.md → spawns validation-gates + .claude/commands/optimization/architect.md → spawns system-architect + .claude/commands/optimization/document.md → spawns documentation-manager + +### Scope Unscoped Bash Tools +Agents with bare Bash access (no parentheses). Restricting reduces blast radius: + + + +These require manual edits — read each agent body to confirm what shell +commands it actually needs before narrowing the scope. + +### Clean Empty Command Directories + + +Verify empty, then: + rmdir .claude/commands// +``` + +### 5. Summary + +```markdown +## Optimization Summary + +Applied: + - Description rewrites: agents updated, ~ tokens saved/session + (or "None applied — descriptions mode skipped or no changes confirmed") + +Printed as instructions (not applied): + - Archive unreferenced agents (~ tok/session if completed) + - Scope Bash on agents (security improvement) + - Clean empty directories + +Total potential: + - Already applied: ~ tok/session + - If structural steps completed: ~ additional tok/session +``` + +## Notes + +- The only files this command writes are `.claude/agents/*.md` description lines. +- All writes are git-tracked — verify with `git diff .claude/agents/`. +- Structural changes (git mv, tools: edits) must be done manually. +- Learning logs are not required — optimization works from static file analysis alone. +- Run `/audit` first for the full profiling report before optimizing. diff --git a/.gitignore b/.gitignore index c565d8d..a4c4edf 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,7 @@ __pycache__/ # Personal Claude overrides — machine-local, never shared with teammates. CLAUDE.local.md + +# Tool-generated index files +entities.json +mempalace.yaml