feat: /audit and /optimize commands for token profiling

.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 — <date>
+
+### Token Budget Summary
+| Category | Est. tokens | Notes |
+|---|---|---|
+| All agent descriptions | ~<N> | Loaded every session |
+| Unreferenced agent files | ~<N> | Loaded every session, 0 commands reference them |
+| Est. savings — archive unreferenced | ~<N>/session | |
+| Est. savings — compress descriptions | ~<N>/session | Assumes 3× reduction |
+
+### Unreferenced Agents
+No command spawns these — they load into context but are never called:
+
+| Agent | File | Est. tokens | Description (truncated) |
+|---|---|---|---|
+| <name> | <file> | ~<N> | <first 80 chars> |
+
+Suggestion: archive to `.claude/agents/archive/` or add commands that surface them.
+
+### Cold Agents (learning log cross-reference)
+<results or skip notice>
+
+### Verbose Descriptions (>200 chars)
+| Agent | Chars | Est. tokens | Savings to 100 chars |
+|---|---|---|---|
+| <name> | <N> | ~<N> | ~<N> tok |
+
+### Minimal Descriptions (<60 chars)
+<list or "None found.">
+
+### Tool Scope Issues
+| Agent | Flag | Details |
+|---|---|---|
+| <name> | Unscoped Bash | Consider: Bash(cmd:*) restriction |
+| <name> | MultiEdit on read-only agent | Review if write access is needed |
+
+### Empty Command Directories
+<list or "None found.">
+
+### Recommendations (ranked by token impact)
+1. **Archive <N> unreferenced agents** — saves ~<N> tok/session
+   Run: `/optimize structural`
+
+2. **Compress <N> verbose descriptions** — saves ~<N> tok/session
+   Run: `/optimize` (or `/optimize descriptions`)
+
+3. **Scope unscoped Bash on <N> 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`.

.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 <N> rewrites
+> - `<name> <name> ...` — 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/<name>.md — saved ~<N> 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: <list unreferenced_agents>
+
+Steps:
+  mkdir -p .claude/agents/archive
+  git mv .claude/agents/<name>.md .claude/agents/archive/
+  # repeat for each
+  git commit -m "chore: archive unreferenced agents"
+
+Token savings: ~<N>/session (full file content no longer loaded)
+Reversible: git mv .claude/agents/archive/<name>.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:
+
+<per-agent table: current tools → suggested scoped tools>
+
+These require manual edits — read each agent body to confirm what shell
+commands it actually needs before narrowing the scope.
+
+### Clean Empty Command Directories
+<list empty dirs>
+
+Verify empty, then:
+  rmdir .claude/commands/<dirname>/
+```
+
+### 5. Summary
+
+```markdown
+## Optimization Summary
+
+Applied:
+  - Description rewrites: <N> agents updated, ~<N> tokens saved/session
+    (or "None applied — descriptions mode skipped or no changes confirmed")
+
+Printed as instructions (not applied):
+  - Archive <N> unreferenced agents (~<N> tok/session if completed)
+  - Scope Bash on <N> agents (security improvement)
+  - Clean <N> empty directories
+
+Total potential:
+  - Already applied: ~<N> tok/session
+  - If structural steps completed: ~<N> 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.

.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