diff --git a/README.md b/README.md index 18650e6..f20f945 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,7 @@

Self-correcting memory that compounds over 50+ sessions. You correct Claude once — it never makes the same mistake again.
+ 24 skills • 8 agents • 21 commands • 29 hook scripts across 24 events
Works with Claude Code, Cursor, and 32+ agents via SkillKit.

@@ -72,21 +73,58 @@ cd ~/.claude/plugins/*/pro-workflow && npm install && npm run build +--- + +## What's New in v3.2 + +- **LLM Gates** — First plugin with `type: "prompt"` hooks for AI-powered commit validation and secret detection +- **Permission Tuner** — Analyzes denial patterns, generates optimized allow/deny rules +- **Compact Guard** — Protects context through compaction (5-file restore limit, 50K budget) +- **Cost Tracker** — Session cost awareness with budget benchmarks +- **MCP Audit** — Analyzes MCP server token overhead per request +- **Auto Setup** — Detects project type, configures quality gates automatically +- **File Watcher** — Reactive workflows with `CLAUDE_ENV_FILE` injection +- **Agent Optimization** — `omitClaudeMd` on read-only agents saves tokens +- **6 New Hook Events** — PermissionDenied, Setup, WorktreeCreate, WorktreeRemove, CwdChanged, TaskCreated + +--- + +## How Pro Workflow Compares + +| Feature | Pro Workflow | [Superpowers](https://github.com/obra/superpowers) | [ECC](https://github.com/affaan-m/everything-claude-code) | [gstack](https://github.com/garrytan/gstack) | [GSD](https://github.com/gsd-build/get-shit-done) | +|---------|:-----------:|:-----------:|:---:|:------:|:---:| +| Self-correcting memory (SQLite + FTS5) | **Yes** | No | No | No | No | +| LLM-powered hooks (`type: "prompt"`) | **Yes** | No | No | No | No | +| Permission denial analysis | **Yes** | No | No | No | No | +| Compaction-aware state preservation | **Yes** | No | No | No | No | +| Cost tracking and budget alerts | **Yes** | No | No | No | No | +| MCP overhead auditing | **Yes** | No | No | No | No | +| Cross-agent (32+ agents via SkillKit) | **Yes** | No | Some | No | No | +| Skills | 24 | 14 | 140+ | 18+ | 0 | +| Agents | 8 | 5 | 36 | 0 | 18 | +| Commands | 21 | 3 | 60+ | 5+ | 57 | +| Hook Events | 24 | 8 | 18 | 0 | 0 | + +--- + ## Try It ```bash -/develop add user authentication # Multi-phase: Research → Plan → Implement → Review +/develop add user authentication # Multi-phase: Research > Plan > Implement > Review /wrap-up # End session, capture learnings, audit changes /doctor # Check your setup health /learn-rule # Extract a correction into persistent memory -/commit # Quality gates → staged review → conventional commit +/commit # Quality gates > staged review > conventional commit +/permission-tuner # Analyze denials, generate allow/deny rules +/cost-tracker # Check session costs and token spend +/mcp-audit # Audit MCP servers for overhead ``` --- ## What's Inside -### 17 Skills +### 24 Skills | Skill | What It Does | |:------|:------------| @@ -107,8 +145,15 @@ cd ~/.claude/plugins/*/pro-workflow && npm install && npm run build | **Sprint Status** | Track progress across sessions | | **Thoroughness Scoring** | Rate completeness of implementations | | **Learn Rule** | Capture corrections as persistent learning rules | +| **LLM Gate** | AI-powered quality gates using `type: "prompt"` hooks | +| **Permission Tuner** | Analyze denial patterns, generate allow/deny rules | +| **Compact Guard** | State preservation through compaction cycles | +| **Cost Tracker** | Session cost awareness with budget benchmarks | +| **MCP Audit** | Audit MCP servers for token overhead and redundancy | +| **Auto Setup** | Detect project type, configure quality gates automatically | +| **File Watcher** | Reactive workflows on config and dependency changes | -### 6 Agents +### 8 Agents | Agent | Purpose | |-------|---------| @@ -118,8 +163,10 @@ cd ~/.claude/plugins/*/pro-workflow && npm install && npm run build | **orchestrator** | Multi-phase feature development (Research > Plan > Implement > Review) | | **debugger** | Systematic bug investigation (hypothesis-driven) | | **context-engineer** | Context window analysis and optimization (lightweight, read-only) | +| **permission-analyst** | Analyze permission denial patterns, recommend rule optimizations | +| **cost-analyst** | Analyze token usage patterns, identify expensive operations | -### 16 Commands +### 21 Commands | Command | What It Does | |---------|-------------| @@ -139,29 +186,43 @@ cd ~/.claude/plugins/*/pro-workflow && npm install && npm run build | `/learn` | Interactive Claude Code best practices guide | | `/safe-mode` | Toggle destructive operation guardrails | | `/sprint-status` | Track multi-session progress | - -### 23 Hook Scripts (18 Events) - -| Hook | When | What | -|------|------|------| -| SessionStart | New session | Load learnings from database | -| UserPromptSubmit | Each prompt | Drift detection, correction tracking | -| PreToolUse | Before edits | Track edit count, quality gate reminders | -| PreToolUse | Before git | Remind about quality gates | -| PostToolUse | After edits | Check for console.log, TODOs, secrets | -| PostToolUse | After tests | Suggest learning from failures | -| Stop | Each response | Context-aware reminders | -| SessionEnd | Session close | Save session stats to database | -| PreCompact | Before compaction | Save context state | -| PostCompact | After compaction | Re-inject critical context summary | -| SubagentStart/Stop | Agent lifecycle | Log and collect results | -| TaskCompleted | Task done | Quality gate on completion | -| PermissionRequest | Permission dialog | Flag dangerous operations | -| PostToolUseFailure | Tool fails | Track failures, suggest learnings | -| TeammateIdle | Teammate idle | Detect blockers in agent teams | -| StopFailure | API error | Log errors with retry advice | -| FileChanged | Config modified | Watch package.json, .env, CI | -| ConfigChange | Settings change | Detect mid-session changes | +| `/auto-setup` | Auto-detect project type and configure quality gates | +| `/compact-guard` | Protected compaction with state preservation | +| `/cost-tracker` | Track session costs and optimization tips | +| `/mcp-audit` | Audit MCP servers for token overhead | +| `/permission-tuner` | Analyze denial patterns, generate allow/deny rules | + +### 29 Hook Scripts (24 Events) + +| Hook Event | Scripts | What | +|------------|:-------:|------| +| SessionStart | 1 | Load learnings from database | +| SessionEnd | 1 | Save session stats to database | +| UserPromptSubmit | 2 | Correction tracking, drift detection | +| PreToolUse (Edit/Write) | 1 | Track edit count, quality gate reminders | +| PreToolUse (Bash) | 3 | Pre-commit check, LLM commit validation, pre-push check | +| PreToolUse (Write) | 1 | LLM-powered secret detection | +| PostToolUse (Edit) | 1 | Check for console.log, TODOs, secrets | +| PostToolUse (Bash) | 1 | Suggest learning from test failures | +| Stop | 2 | Context-aware reminders, auto-capture [LEARN] blocks | +| PreCompact | 1 | Save context state before compaction | +| PostCompact | 1 | Re-inject critical context summary | +| SubagentStart | 1 | Log subagent lifecycle for observability | +| SubagentStop | 1 | Log subagent completion and capture results | +| TaskCompleted | 1 | Quality gate on completion | +| TaskCreated | 1 | Validate task descriptions for tracking | +| PermissionRequest | 1 | Flag dangerous operations | +| PermissionDenied | 1 | Track denial patterns for optimization | +| PostToolUseFailure | 1 | Track failures, suggest learnings | +| TeammateIdle | 1 | Detect blockers in agent teams | +| StopFailure | 1 | Log errors with retry advice | +| FileChanged | 1 | Watch package.json, .env, CI configs | +| ConfigChange | 1 | Detect mid-session settings changes | +| Notification | 1 | Log permission requests | +| Setup | 1 | Auto-detect project type on init | +| WorktreeCreate | 1 | Log worktree creation for parallel tracking | +| WorktreeRemove | 1 | Cleanup worktree tracking on removal | +| CwdChanged | 1 | Detect project type on directory change | ### 10 Reference Guides @@ -182,11 +243,7 @@ cd ~/.claude/plugins/*/pro-workflow && npm install && npm run build ## How It Works -> "80% of my code is written by AI, 20% is spent reviewing and correcting it." — Karpathy - -> "The bottleneck was never the model. It was always the workflow." — @getvibecodes - -Pro Workflow optimizes for that ratio. Every correction becomes a rule. Every rule prevents future mistakes. The loop compounds. +Pro Workflow optimizes for the 80/20 ratio. Every correction becomes a rule. Every rule prevents future mistakes. The loop compounds. ### The `/develop` Flow @@ -229,6 +286,8 @@ Learnings stored in SQLite with FTS5 full-text search: | **Multi-Phase Dev** | Research > Plan > Implement > Review with gates | | **Learning Log** | Auto-document insights | | **Orchestration** | Command > Agent > Skill wiring for complex features | +| **LLM Gates** | AI-powered verification before destructive operations | +| **Permission Tuning** | Reduce prompt fatigue with denial pattern analysis | --- @@ -268,19 +327,35 @@ Rule: Start with 3 MCPs. Add only for concrete needs. ```text pro-workflow/ -├── skills/ # 17 skills -├── agents/ # 6 agents -├── commands/ # 16 slash commands -├── hooks/ # 18 events, 23 scripts +├── skills/ # 24 skills +├── agents/ # 8 agents +├── commands/ # 21 slash commands +├── hooks/ # 24 events, 29 scripts ├── docs/ # 10 reference guides ├── rules/ # 7 rules (Cursor + universal) ├── contexts/ # 3 context modes ├── templates/ # Split CLAUDE.md + AGENTS.md -├── scripts/ # 23 hook scripts +├── scripts/ # 29 hook scripts ├── src/ # TypeScript source (SQLite) └── config.json ``` +--- + +## Tips from the Community + +> "80% of my code is written by AI, 20% is spent reviewing and correcting it." — [Andrej Karpathy](https://x.com/karpathy/status/2015883857489522876) + +> "Use subagents to throw more compute at a problem — offload tasks to keep your main context clean." — [Boris Cherny](https://x.com/bcherny/status/2017742755737555434) + +> "If you do something more than once a day, turn it into a skill or command." — [Boris Cherny](https://x.com/bcherny/status/2017742748984742078) + +> "Write detailed specs and reduce ambiguity before handing work off — the more specific you are, the better the output." — [Boris Cherny](https://x.com/bcherny/status/2017742752566632544) + +> "Skill description field is a trigger, not a summary — write it for the model." — [Thariq Shihipar](https://x.com/trq212/status/2033949937936085378) + +--- + ## Philosophy 1. **Compound improvements** — Small corrections lead to big gains over time @@ -291,6 +366,17 @@ pro-workflow/ --- +## Related Projects + +| Project | Description | +|---------|-------------| +| [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | 140+ skills, 36 agents — the comprehensive collection | +| [claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice) | Curated tips, comparisons, and community best practices | +| [SkillKit](https://github.com/rohitg00/skillkit) | Universal CLI for managing skills across 32+ agents | +| [awesome-claude-code-toolkit](https://github.com/rohitg00/awesome-claude-code-toolkit) | 850+ files, 135 agents, 176 plugins — curated directory | + +--- + ## Star History diff --git a/hooks/hooks.json b/hooks/hooks.json index e98af0a..7cf9493 100644 --- a/hooks/hooks.json +++ b/hooks/hooks.json @@ -8,9 +8,37 @@ { "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate.js\"" + }, + { + "type": "command", + "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/read-before-write.js\"" + } + ], + "description": "Track edits for quality gate checks and read-before-write enforcement" + }, + { + "matcher": "Read", + "hooks": [ + { + "type": "command", + "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/reread-tracker.js\"" + }, + { + "type": "command", + "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/read-before-write.js\"" + } + ], + "description": "Track file reads to detect unnecessary re-reads and enable read-before-write enforcement" + }, + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/tool-call-budget.js\"" } ], - "description": "Track edits for quality gate checks" + "description": "Track tool call count against budget thresholds" }, { "matcher": "Bash", diff --git a/package.json b/package.json index b5de6f9..e020d2c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "pro-workflow", - "version": "3.1.0", + "version": "3.2.0", "description": "Complete AI coding workflow system with orchestration patterns, cross-agent support, reference guides, and searchable learnings", "main": "dist/index.js", "types": "dist/index.d.ts", @@ -24,7 +24,10 @@ "sqlite", "fts5", "adaptive-thinking", - "context-compaction" + "context-compaction", + "token-efficiency", + "anti-sycophancy", + "tool-call-budget" ], "author": { "name": "Rohit Ghumare", diff --git a/rules/communication-style.mdc b/rules/communication-style.mdc index d5cd15b..4391e7b 100644 --- a/rules/communication-style.mdc +++ b/rules/communication-style.mdc @@ -1,14 +1,30 @@ --- -description: Communication preferences - concise responses, action-oriented, acknowledge mistakes +description: Communication preferences - concise responses, action-oriented, no filler, acknowledge mistakes alwaysApply: true --- Be concise. Action over explanation. +No sycophantic openers: never start with "Sure!", "Great question!", "Absolutely!", "Of course!", "I'd be happy to!". Lead with the answer or action. + +No closing fluff: never end with "Let me know if you need anything!", "I hope this helps!", "Feel free to ask!". Stop after the answer. + +No prompt restatement: do not repeat or paraphrase the question before answering. + +No "As an AI" framing: no disclaimers about being an AI model. + +Code first, explanation after: return code blocks, then explain only if non-obvious. No preambles before code. + +Structured output when possible: prefer tables, bullets, and JSON over prose paragraphs. + +ASCII-only output: use -- not em dashes, use straight quotes not smart quotes. No Unicode decorators. + Ask when requirements are unclear rather than assuming. Acknowledge mistakes directly and propose fixes. Do not add features, refactor code, or make improvements beyond what was asked. A bug fix does not need surrounding code cleaned up. +No unsolicited suggestions: deliver exactly what was asked. Do not add "you might also want to..." unless requested. + Keep solutions simple and focused. The right amount of complexity is the minimum needed for the current task. diff --git a/rules/context-discipline.mdc b/rules/context-discipline.mdc index 7436342..2cc7622 100644 --- a/rules/context-discipline.mdc +++ b/rules/context-discipline.mdc @@ -1,9 +1,15 @@ --- -description: Manage AI context window efficiently - read before edit, plan before multi-file changes +description: Manage AI context window efficiently - read before write, no re-reads, tool-call budgets, one-pass discipline alwaysApply: true --- -Always read a file before editing it. Understand existing code before suggesting modifications. +Read before write: always read a file before editing or writing it. Never modify a file you have not read in this session. + +No re-reads: do not re-read a file already read in this session unless it was modified since the last read. + +One-pass coding: for simple-to-medium tasks, write the complete solution in one pass. Run tests once. If tests pass, stop immediately. Do not refactor, improve, or polish passing code. Never iterate more than twice on the same failure. + +Tool-call budgets: track tool calls per session. Quick fix: 20 calls. Bug fix: 30. Feature: 50. Large feature: 80. At 80% of budget, wrap up current task. Use plan mode for changes touching more than 3 files, architecture decisions, or unclear requirements. @@ -14,3 +20,5 @@ Keep MCP servers under 10 enabled and total tools under 80. Use subagents to isolate high-volume output (test runs, log analysis, documentation searches). Summarize exploration findings before acting on them. + +Read tests before coding: understand what the tests assert before writing implementation code. diff --git a/rules/core-rules.md b/rules/core-rules.md index 0757db7..af7ff09 100644 --- a/rules/core-rules.md +++ b/rules/core-rules.md @@ -15,10 +15,13 @@ Universal rules for any project. Add to CLAUDE.md or use as reference. - Review before push ## Context -- Read before edit +- Read before edit — never write a file you haven't read +- No re-reads — don't re-read unchanged files - Plan before multi-file - Compact at milestones - <10 MCPs enabled +- One-pass discipline: write complete solution, test, stop if green +- Tool-call budgets: 20 (quick fix), 30 (bug fix), 50 (feature), 80 (large) ## Learning - Capture corrections: [LEARN] Category: Rule @@ -30,6 +33,11 @@ Universal rules for any project. Add to CLAUDE.md or use as reference. - Action > explanation - Ask when unclear - Acknowledge mistakes +- No sycophantic openers ("Sure!", "Great question!") +- No closing fluff ("Let me know if you need anything!") +- No prompt restatement before answering +- Code first, explanation after (only if non-obvious) +- ASCII only: -- not em dashes, " not smart quotes ## Performance - Haiku for quick tasks diff --git a/rules/token-efficiency.mdc b/rules/token-efficiency.mdc new file mode 100644 index 0000000..6949358 --- /dev/null +++ b/rules/token-efficiency.mdc @@ -0,0 +1,30 @@ +--- +description: Token efficiency rules - eliminate waste in AI output, enforce read-before-write, prevent iteration cycles +alwaysApply: true +--- + +No sycophantic openers: never start with "Sure!", "Great question!", "Absolutely!", "Of course!", "I'd be happy to!". + +No hollow closing fluff: never end with "Let me know if you need anything!", "I hope this helps!", "Feel free to ask!". + +No prompt restatement: do not repeat or paraphrase the question before answering. Lead with the answer. + +No unsolicited suggestions: deliver exactly what was asked. Do not add "you might also want to..." unless requested. + +No "As an AI" framing: never include disclaimers about being an AI model. + +ASCII-only output: use -- not em dashes, use " not smart quotes, use ' not curly apostrophes. No Unicode decorators. + +Read before write: never write or edit a file you have not read in this session. No exceptions. + +No re-reads: do not re-read a file already read in this session unless it was modified since the last read. + +One-pass discipline for simple tasks: write the complete solution in one pass, run tests once. If tests pass, stop. Do not refactor, improve, or polish passing code. + +No write-delete-rewrite cycles: understand the target file structure before writing. Plan the change, then execute once. + +Do not over-engineer: simplest working solution first. No unnecessary abstractions, error handling for impossible scenarios, or speculative features. + +Code first, explanation after: return code, then explain only if non-obvious. No preambles before code blocks. + +Structured output when possible: prefer tables, bullets, and JSON over prose paragraphs. diff --git a/scripts/read-before-write.js b/scripts/read-before-write.js new file mode 100644 index 0000000..62fd8f0 --- /dev/null +++ b/scripts/read-before-write.js @@ -0,0 +1,76 @@ +#!/usr/bin/env node +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +function getTempDir() { + return path.join(os.tmpdir(), 'pro-workflow'); +} + +function ensureDir(dir) { + if (!fs.existsSync(dir)) { + fs.mkdirSync(dir, { recursive: true }); + } +} + +async function main() { + const sessionId = process.env.CLAUDE_SESSION_ID || String(process.ppid) || 'default'; + const tempDir = getTempDir(); + ensureDir(tempDir); + + const readTrackFile = path.join(tempDir, `reads-${sessionId}.json`); + + let input = ''; + try { + input = fs.readFileSync('/dev/stdin', 'utf8'); + } catch (e) { + process.exit(0); + } + + let parsed; + try { + parsed = JSON.parse(input); + } catch (e) { + process.exit(0); + } + + const tool = parsed.tool_name || parsed.tool || ''; + const toolInput = parsed.tool_input || {}; + + let readFiles = {}; + if (fs.existsSync(readTrackFile)) { + try { + readFiles = JSON.parse(fs.readFileSync(readTrackFile, 'utf8')); + } catch (e) { + readFiles = {}; + } + } + + if (tool === 'Read') { + const filePath = toolInput.file_path || ''; + if (filePath) { + readFiles[filePath] = Date.now(); + fs.writeFileSync(readTrackFile, JSON.stringify(readFiles)); + } + process.exit(0); + } + + if (tool === 'Write' || tool === 'Edit') { + const filePath = toolInput.file_path || ''; + if (!filePath) { + process.exit(0); + } + + if (tool === 'Write' && !fs.existsSync(filePath)) { + process.exit(0); + } + + if (!readFiles[filePath]) { + console.error(`[TokenEfficiency] Warning: ${tool} on ${path.basename(filePath)} without reading it first. Read the file before modifying.`); + } + } + + process.exit(0); +} + +main().catch(() => process.exit(0)); diff --git a/scripts/reread-tracker.js b/scripts/reread-tracker.js new file mode 100644 index 0000000..aa9e6f6 --- /dev/null +++ b/scripts/reread-tracker.js @@ -0,0 +1,79 @@ +#!/usr/bin/env node +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +function getTempDir() { + return path.join(os.tmpdir(), 'pro-workflow'); +} + +function ensureDir(dir) { + if (!fs.existsSync(dir)) { + fs.mkdirSync(dir, { recursive: true }); + } +} + +async function main() { + const sessionId = process.env.CLAUDE_SESSION_ID || String(process.ppid) || 'default'; + const tempDir = getTempDir(); + ensureDir(tempDir); + + const trackFile = path.join(tempDir, `read-track-${sessionId}.json`); + + let input = ''; + try { + input = fs.readFileSync('/dev/stdin', 'utf8'); + } catch (e) { + process.exit(0); + } + + let parsed; + try { + parsed = JSON.parse(input); + } catch (e) { + process.exit(0); + } + + const toolInput = parsed.tool_input || {}; + const filePath = toolInput.file_path || ''; + if (!filePath) { + process.exit(0); + } + + let tracked = {}; + if (fs.existsSync(trackFile)) { + try { + tracked = JSON.parse(fs.readFileSync(trackFile, 'utf8')); + } catch (e) { + tracked = {}; + } + } + + const lastRead = tracked[filePath]; + const now = Date.now(); + + if (lastRead) { + let modified = false; + try { + const stat = fs.statSync(filePath); + modified = stat.mtimeMs > lastRead; + } catch (e) { + modified = true; + } + + if (!modified) { + const readCount = (tracked[`${filePath}:count`] || 1) + 1; + tracked[`${filePath}:count`] = readCount; + if (readCount >= 2) { + console.error(`[TokenEfficiency] Re-reading ${path.basename(filePath)} (${readCount}x) — file unchanged since last read. Consider using cached knowledge.`); + } + } + } + + tracked[filePath] = now; + fs.writeFileSync(trackFile, JSON.stringify(tracked)); + + process.exit(0); +} + +main().catch(() => process.exit(0)); diff --git a/scripts/tool-call-budget.js b/scripts/tool-call-budget.js new file mode 100644 index 0000000..2937979 --- /dev/null +++ b/scripts/tool-call-budget.js @@ -0,0 +1,56 @@ +#!/usr/bin/env node +const fs = require('fs'); +const path = require('path'); +const os = require('os'); + +function getTempDir() { + return path.join(os.tmpdir(), 'pro-workflow'); +} + +function ensureDir(dir) { + if (!fs.existsSync(dir)) { + fs.mkdirSync(dir, { recursive: true }); + } +} + +async function main() { + const sessionId = process.env.CLAUDE_SESSION_ID || String(process.ppid) || 'default'; + const tempDir = getTempDir(); + ensureDir(tempDir); + + const budgetFile = path.join(tempDir, `tool-budget-${sessionId}`); + + let count = 0; + if (fs.existsSync(budgetFile)) { + count = parseInt(fs.readFileSync(budgetFile, 'utf8').trim(), 10) || 0; + } + count++; + fs.writeFileSync(budgetFile, String(count)); + + const thresholds = [ + { limit: 20, label: 'quick-fix budget (20 calls)' }, + { limit: 30, label: 'bug-fix budget (30 calls)' }, + { limit: 50, label: 'feature budget (50 calls)' }, + { limit: 80, label: 'large-feature budget (80 calls)' } + ]; + + for (const t of thresholds) { + const warnAt = Math.floor(t.limit * 0.8); + if (count === warnAt) { + console.error(`[TokenEfficiency] ${count} tool calls — approaching ${t.label}. Consider wrapping up or compacting.`); + break; + } + if (count === t.limit) { + console.error(`[TokenEfficiency] ${count} tool calls — hit ${t.label}. Commit progress and assess remaining work.`); + break; + } + } + + if (count === 65) { + console.error('[TokenEfficiency] 65 tool calls — approaching large-feature limit. Wrap up current task.'); + } + + process.exit(0); +} + +main().catch(() => process.exit(0)); diff --git a/skills/context-optimizer/SKILL.md b/skills/context-optimizer/SKILL.md index fcca5c1..9944ada 100644 --- a/skills/context-optimizer/SKILL.md +++ b/skills/context-optimizer/SKILL.md @@ -71,6 +71,29 @@ The main session stays clean while subagents handle the volume. | Testing | < 80% | Delegate to subagent | | Review | < 90% | Start fresh session | +## Token Efficiency + +### Output Reduction (40-60% savings) +- No sycophantic openers ("Sure!", "Great question!") +- No closing fluff ("Let me know if you need anything!") +- No prompt restatement before answering +- Code first, explanation only if non-obvious +- Structured output (tables, bullets) over prose +- ASCII only: -- not em dashes, straight quotes not smart quotes + +### Behavioral Efficiency +- One-pass coding: complete solution, test once, stop if green +- Read before write: never modify unread files +- No re-reads: don't re-read unchanged files +- Tool-call budgets: 20 (quick fix) to 80 (large feature) +- Never iterate more than twice on the same failure + +### Task Profiles +Switch response style based on context: +- **Coding**: code first, minimal explanation, simplest solution +- **Agent/Pipeline**: structured output only, no prose, parseable +- **Analysis**: finding first, tables over paragraphs, sourced numbers + ## CLAUDE.md Optimization - Root CLAUDE.md: < 60 lines ideal, < 150 max diff --git a/skills/cost-tracker/SKILL.md b/skills/cost-tracker/SKILL.md index 012db4e..0ead858 100644 --- a/skills/cost-tracker/SKILL.md +++ b/skills/cost-tracker/SKILL.md @@ -44,6 +44,20 @@ Use when: | Refactor | $1.00-5.00 | $7.00 | | Code review | $0.20-1.00 | $2.00 | +### Tool-Call Budgets + +Set explicit budgets by task complexity: + +| Task Type | Tool-Call Budget | Wrap-Up At | +|-----------|-----------------|------------| +| Quick fix / lookup | 20 calls | 15 | +| Bug fix | 30 calls | 25 | +| Feature (small) | 50 calls | 40 | +| Feature (large) | 80 calls | 65 | +| Refactor | 50 calls | 40 | + +At the wrap-up threshold: commit progress, assess remaining work, decide whether to continue or start fresh. + ### Optimization Strategies 1. **Scope prompts tightly** — "Fix the auth bug in src/auth/login.ts" vs "Fix the auth bug" @@ -52,6 +66,10 @@ Use when: 4. **Compact proactively** — Don't wait for auto-compact; compact at task boundaries 5. **Read selectively** — Use `offset` and `limit` params for large files 6. **Batch operations** — Multiple independent tool calls in one message +7. **One-pass discipline** — Write complete solution, test once, stop if green +8. **No re-reads** — Don't re-read unchanged files; trust cached knowledge +9. **Read before write** — Never write a file without reading it first +10. **Kill output bloat** — No sycophantic openers, no closing fluff, no prompt restatement ## Budget Alerts diff --git a/skills/token-efficiency/SKILL.md b/skills/token-efficiency/SKILL.md new file mode 100644 index 0000000..cc002fa --- /dev/null +++ b/skills/token-efficiency/SKILL.md @@ -0,0 +1,115 @@ +--- +name: token-efficiency +description: Reduce token waste by 40-60% through anti-sycophancy rules, tool-call budgets, one-pass coding, task profiles, and read-before-write enforcement. Inspired by drona23/claude-token-efficient. +--- + +# Token Efficiency + +Reduce output token waste and prevent iteration cycles that consume context. + +## Trigger + +Use when: +- Sessions feel expensive or slow +- Output is verbose with filler text +- Claude is re-reading files or iterating unnecessarily +- Setting up a new project for token-efficient work + +## Anti-Sycophancy Rules + +These patterns waste 30-60% of output tokens: + +| Pattern | Example | Fix | +|---------|---------|-----| +| Sycophantic opener | "Sure! Great question!" | Delete. Lead with answer. | +| Prompt restatement | "You're asking about X..." | Delete. Answer directly. | +| Closing fluff | "Let me know if you need anything!" | Delete. Stop after the answer. | +| Unsolicited suggestions | "You might also want to..." | Delete unless asked. | +| AI disclaimers | "As an AI model..." | Delete entirely. | +| Verbose preambles | "I'll help you with that..." | Delete. Start with the action. | + +## Tool-Call Budgets + +Set explicit budgets by task complexity: + +| Task Type | Tool-Call Budget | Wrap-Up At | +|-----------|-----------------|------------| +| Quick fix / lookup | 20 calls | 15 | +| Bug fix | 30 calls | 25 | +| Feature (small) | 50 calls | 40 | +| Feature (large) | 80 calls | 65 | +| Refactor | 50 calls | 40 | +| Exploration / research | 30 calls | 25 | + +At the wrap-up threshold: commit progress, assess remaining work, decide whether to continue or start fresh. + +## One-Pass Coding Discipline + +For simple-to-medium tasks: + +1. **Read all relevant files** including tests first +2. **Understand what tests assert** before coding +3. **Write complete solution in one pass** — not incrementally +4. **Run tests once** — if pass, STOP immediately +5. **If fail**: read the error, fix once, retest +6. **Never iterate** more than twice on the same failure — rethink approach +7. **Never refactor, improve, or polish passing code** + +## Task Profiles + +Switch profiles based on what you're doing: + +### Coding Profile +- Return code first, explanation after (only if non-obvious) +- Simplest working solution, no over-engineering +- Read file before modifying — always +- No docstrings on unchanged code +- No error handling for impossible scenarios +- State bug, show fix, stop + +### Agent/Pipeline Profile +- Structured output only: JSON, bullets, tables +- No prose unless targeting a human reader +- Every output must be parseable without post-processing +- Execute task, do not narrate actions +- Never invent file paths, API endpoints, or function names +- If unknown: return null or "UNKNOWN", never guess + +### Analysis Profile +- Lead with finding, context and methodology after +- Tables and bullets over prose +- Numbers must include units +- Never fabricate data points +- Summary first (3 bullets max), caveats last + +## Read-Before-Write Enforcement + +Hard rules: +1. **Never write a file you haven't read** in this session +2. **Never re-read a file** already read unless it was modified +3. **Read tests before coding** — understand what passes before writing +4. **Read error output carefully** before attempting a fix + +## ASCII-Only Output + +Use ASCII characters only in all output: +- `--` not `—` (em dash) +- `"` not `"` `"` (smart quotes) +- `'` not `'` `'` (curly apostrophes) +- No emoji unless explicitly requested +- No Unicode decorators or special characters + +This ensures clean copy-paste for code and compatibility with downstream systems. + +## Measuring Impact + +Track these metrics to measure token savings: +- **Output length**: average words per response (target: 30-50% reduction) +- **Tool calls per task**: should stay within budget tier +- **Re-read count**: should be near zero +- **Write-without-read count**: should be zero +- **Iteration cycles**: tests should pass in 1-2 attempts, not 5+ + +## Attribution + +Token efficiency patterns adapted from [drona23/claude-token-efficient](https://github.com/drona23/claude-token-efficient) (MIT).