From d367b2574d62768b4484a50bd78c63a1fc2d667a Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Wed, 26 Nov 2025 15:50:29 -0800 Subject: [PATCH] Rewrite all docs copy in Pragmatic Technical Writing style MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Applied Hunt/Thomas and Joel Spolsky writing principles: - Concrete before abstract (stories and examples first) - Physical analogies for technical concepts - Conversational voice with "you" and contractions - Removed passive voice and weasel words - Added memorable metaphors and hooks Pages updated: - index.html: New hero, philosophy section with N+1 query story - agents.html: Each agent described with concrete scenarios - commands.html: Action-oriented descriptions - getting-started.html: Direct, conversational guide - skills.html: Clear "when to use this" for each skill - mcp-servers.html: Concrete examples of what each tool does 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/index.html | 97 ++++++++++---------------- docs/pages/agents.html | 74 ++++++++------------ docs/pages/commands.html | 39 +++++------ docs/pages/getting-started.html | 120 ++++++++++++++------------------ docs/pages/mcp-servers.html | 83 +++++++++++----------- docs/pages/skills.html | 43 +++++------- 6 files changed, 196 insertions(+), 260 deletions(-) diff --git a/docs/index.html b/docs/index.html index 9d6e4e9..9099341 100644 --- a/docs/index.html +++ b/docs/index.html @@ -4,7 +4,7 @@ Compounding Engineering - AI-Powered Development Tools for Claude Code - + @@ -12,10 +12,10 @@ - + - + @@ -61,11 +61,10 @@ Version 2.6.0 released!

- AI-Powered Development Tools That Get Smarter With Every Use + Your Code Reviews Just Got 12 Expert Opinions. In 30 Seconds.

- Make each unit of engineering work easier than the last. 23 specialized agents, 16 powerful commands, - 11 intelligent skills, and two MCP servers for code review, research, design, and workflow automation. + Here's what happened when we shipped yesterday: security audit, performance analysis, architectural review, pattern detection, and eight more specialized checks—all running in parallel. No meetings. No waiting. Just answers. That's compounding engineering: 23 specialized agents, 16 workflow commands, and 11 skills that make today's work easier than yesterday's.

@@ -107,18 +106,16 @@
-

The Compounding Engineering Philosophy

+

Why Your Third Code Review Should Be Easier Than Your First

- Every unit of engineering work should make subsequent units of work easier—not harder. + Think about the last time you fixed a Rails N+1 query. You found it. You fixed it. Then next month, different developer, same bug, same investigation. That's linear engineering—you solved it, but the solution evaporated.

- "Most engineering creates linear value: you build a feature, it works, done. - Compounding engineering creates exponential value: each solved problem teaches the system, - each pattern becomes reusable, each review strengthens future reviews." + "Most engineering work is amnesia. You solve a problem on Tuesday, forget the solution by Friday, and re-solve it next quarter. Compounding engineering is different: each solved problem teaches the system. The security review you run today makes tomorrow's review smarter. The pattern you codify this sprint prevents bugs in the next three."
@@ -128,11 +125,9 @@

Plan

-

Understand before you build

+

Stop starting over from scratch

- Before writing a single line of code, gather context. Research agents explore - documentation, analyze git history, and find best practices. The /workflows:plan - command orchestrates three research agents in parallel to create comprehensive implementation plans. + You know that moment when you open a ticket and think "how did we solve this last time?" The framework-docs-researcher already knows. The git-history-analyzer remembers what worked in March. Run /workflows:plan and three research agents work in parallel—one reading docs, one analyzing your repo's history, one finding community patterns. In 60 seconds, you have a plan built on institutional memory instead of starting cold.

framework-docs-researcher @@ -147,11 +142,9 @@

Delegate

-

Leverage specialized expertise

+

Work with experts who never forget

- Each agent brings deep domain knowledge. The kieran-rails-reviewer knows Rails - conventions like an expert. The security-sentinel catches OWASP vulnerabilities. - The /workflows:work command executes plans while maintaining quality gates. + The security-sentinel has checked 10,000 PRs for SQL injection. The kieran-rails-reviewer never approves a controller with business logic. They don't get tired, don't skip Friday afternoon reviews, don't forget the conventions you agreed on in March. Run /workflows:work and watch your plan execute with quality gates that actually enforce your standards—every single time.

24 specialized agents @@ -166,11 +159,9 @@

Assess

-

Multiple perspectives, comprehensive coverage

+

Get twelve opinions without twelve meetings

- The /workflows:review command launches 12 or more review agents in parallel: security, - performance, architecture, data integrity, patterns, and more. Findings are categorized by - severity (P1/P2/P3) and stored as actionable todo files. + Type /workflows:review PR#123 and go get coffee. When you come back, you'll have a security audit (did you sanitize that user input?), performance analysis (N+1 spotted on line 47), architecture review (this breaks the pattern from v2.3), data integrity check (that migration will fail in production), and eight more specialized reviews. All running in parallel. All categorized by severity. All stored as actionable P1/P2/P3 todos you can knock out in order.

security-sentinel @@ -185,10 +176,9 @@

Codify

-

Turn solutions into knowledge

+

Make sure you never solve the same bug twice

- Every solved problem should teach the system. The /workflows:codify command - captures solutions as searchable documentation with YAML frontmatter for fast lookup. + Remember that CORS issue you debugged for three hours last month? Neither do I. That's the problem. Run /workflows:codify right after you fix something and it captures the solution as searchable documentation with YAML frontmatter. Next time someone hits the same issue, they grep for "CORS production" and find your answer in five seconds instead of re-debugging for three hours. That's how you compound.

/workflows:codify @@ -208,8 +198,7 @@ 23 Specialized Agents

- Each agent brings deep expertise in a specific domain. Run them individually or orchestrate - multiple agents in parallel for comprehensive analysis. + Think of them as coworkers who never quit. The security-sentinel has seen every SQL injection variant. The kieran-rails-reviewer enforces conventions with zero compromise. The performance-oracle spots N+1 queries while you're still reading the PR. Run them solo or launch twelve in parallel—your choice.

@@ -440,8 +429,7 @@ 16 Powerful Commands

- Slash commands for common workflows. From code review to bug triage, - these commands automate complex multi-step processes. + Slash commands that replace entire workflows. /workflows:review is your code review committee. /workflows:plan is your research team. /triage sorts 50 todos in the time it takes you to read five. Each one automates hours of work into a single line.

@@ -579,8 +567,7 @@ 11 Intelligent Skills

- Skills provide deep domain expertise that Claude Code can invoke on-demand. - From Ruby gem patterns to image generation. + Domain expertise on tap. Need to write a Ruby gem? The andrew-kane-gem-writer knows the patterns Andrew uses in 50+ popular gems. Building a Rails app? The dhh-ruby-style enforces 37signals conventions. Generating images? The gemini-imagegen has Google's AI on speed dial. Just invoke the skill and watch it work.

@@ -722,8 +709,7 @@ Two MCP Servers

- Model Context Protocol servers extend Claude Code's capabilities with - browser automation and framework documentation lookup. + Playwright gives Claude a browser—it can click buttons, take screenshots, fill forms, and validate what your users actually see. Context7 gives it instant access to docs for 100+ frameworks. Need to know how Next.js handles dynamic routes? Context7 fetches the answer in real-time instead of hallucinating from outdated training data.

@@ -733,7 +719,7 @@ Playwright
-

Browser automation for testing, screenshots, and web interactions.

+

Your AI can now see and click like a user. Test flows, grab screenshots, debug what's actually rendering.

Tools Provided: 6 tools

    @@ -751,7 +737,7 @@ Context7
-

Framework documentation lookup for more than 100 frameworks.

+

Stop getting outdated answers. Context7 fetches current docs from 100+ frameworks in real-time.

Tools Provided: 2 tools

- Performs security audits, vulnerability assessments, and OWASP compliance checks. - Essential for any code handling authentication, payments, or sensitive data. + Security vulnerabilities hide in boring code—the "just grab the user ID from params" line that ships a privilege escalation bug to production. This agent thinks like an attacker: SQL injection, XSS, auth bypass, leaked secrets. Run it before touching authentication, payments, or anything with PII. Your users' data depends on paranoia.

Security Checks

    @@ -218,8 +212,7 @@ claude agent security-sentinel "Audit the payment flow" Performance

- Analyzes code for performance issues, bottlenecks, and scalability concerns. - Projects performance at 10x, 100x, and 1000x scale. + Your code works fine with 10 users. What happens at 10,000? This agent time-travels to your future scaling problems—N+1 queries that murder your database, O(n²) algorithms hiding in loops, missing indexes, memory leaks. It thinks in Big O notation and asks uncomfortable questions about what breaks first when traffic spikes.

Analysis Areas

    @@ -242,8 +235,7 @@ claude agent security-sentinel "Audit the payment flow" Architecture

- Analyzes code changes from an architectural perspective. Evaluates system structure, - SOLID principles, and API contracts. + Every "small change" either reinforces your architecture or starts eroding it. This agent zooms out to see if your fix actually fits the system's design—or if you're bolting duct tape onto a crumbling foundation. It speaks SOLID principles, microservice boundaries, and API contracts. Call it when you're about to make a change that "feels weird."

Analysis Areas

    @@ -265,8 +257,7 @@ claude agent security-sentinel "Audit the payment flow" Data

- Reviews database migrations, data models, and data persistence code. - Ensures data safety and privacy compliance. + Migrations can't be rolled back once they're run on production. This agent is your last line of defense before you accidentally drop a column with user data, create a race condition in transactions, or violate GDPR. It obsesses over referential integrity, rollback safety, and data constraints. Your database is forever; migrations should be paranoid.

Review Areas

    @@ -288,8 +279,7 @@ claude agent security-sentinel "Audit the payment flow" Patterns

- Analyzes code for design patterns, anti-patterns, naming conventions, and duplication. - Uses tools like jscpd for duplication detection. + Patterns tell stories—Factory, Observer, God Object, Copy-Paste Programming. This agent reads your code like an archaeologist reading artifacts. It spots the good patterns (intentional design), the anti-patterns (accumulated tech debt), and the duplicated blocks you swore you'd refactor later. Runs tools like jscpd because humans miss repetition that machines catch instantly.

Detection Areas