john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite all docs copy in Pragmatic Technical Writing style

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
2025-11-26 15:50:29 -08:00
parent 13d317029f
commit d367b2574d
6 changed files with 196 additions and 260 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/pages/agents.html
View File

@@ -75,8 +75,7 @@
<article class="docs-article">
<h1><i class="fa-solid fa-users-gear color-accent"></i> Agent Reference</h1>
<p class="lead">
Complete documentation for all 23 specialized AI agents. Each agent brings deep expertise
in a specific domain and can be invoked individually or orchestrated together.
Think of agents as your expert teammates who never sleep. You've got 23 specialists here—each one obsessed with a single domain. Call them individually when you need focused expertise, or orchestrate them together for multi-angle analysis. They're opinionated, they're fast, and they remember your codebase better than you do.
</p>
<div class="usage-box">
@@ -97,7 +96,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<!-- Review Agents -->
<section id="review-agents">
<h2><i class="fa-solid fa-code-pull-request"></i> Review Agents (10)</h2>
<p>Code review agents that examine changes from multiple perspectives: conventions, security, performance, architecture, and quality.</p>
<p>Your code review dream team. These agents catch what humans miss at 2am—security holes, performance cliffs, architectural drift, and those "it works but I hate it" moments. They're picky. They disagree with each other. That's the point.</p>
<div class="agent-detail" id="kieran-rails-reviewer">
<div class="agent-detail-header">
@@ -105,8 +104,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Rails</span>
</div>
<p class="agent-detail-description">
Super senior Rails developer with impeccable taste and an exceptionally high bar for Rails code quality.
Reviews with strict conventions while being pragmatic on new isolated code.
Your senior Rails developer who's seen too many "clever" solutions fail in production. Obsessed with code that's boring, predictable, and maintainable. Strict on existing code (because touching it risks everything), pragmatic on new isolated features (because shipping matters). If you've ever thought "this works but feels wrong," this reviewer will tell you why.
</p>
<h4>Key Principles</h4>
<ul>
@@ -129,8 +127,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Rails</span>
</div>
<p class="agent-detail-description">
Brutally honest Rails code review from David Heinemeier Hansson's perspective.
Focuses on Rails conventions, simplicity, and avoiding over-engineering.
What if DHH reviewed your Rails PR? He'd ask why you're building React inside Rails, why you need six layers of abstraction for a form, and whether you've forgotten that Rails already solved this problem. This agent channels that energy—blunt, opinionated, allergic to complexity.
</p>
<h4>Key Focus Areas</h4>
<ul>
@@ -150,8 +147,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Python</span>
</div>
<p class="agent-detail-description">
Reviews Python code with an exceptionally high quality bar. Enforces type hints, Pythonic patterns,
and modern Python 3.10+ syntax.
Your Pythonic perfectionist who believes type hints aren't optional and <code>dict.get()</code> beats try/except KeyError. Expects modern Python 3.10+ patterns—no legacy syntax, no <code>typing.List</code> when <code>list</code> works natively. If your code looks like Java translated to Python, prepare for rewrites.
</p>
<h4>Key Focus Areas</h4>
<ul>
@@ -172,8 +168,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">TypeScript</span>
</div>
<p class="agent-detail-description">
Reviews TypeScript code with an exceptionally high quality bar. Enforces type safety,
modern patterns, and clean architecture.
TypeScript's type system is a gift—don't throw it away with <code>any</code>. This reviewer treats <code>any</code> like a code smell that needs justification. Expects proper types, clean imports, and code that doesn't need comments because the types explain everything. You added TypeScript for safety; this agent makes sure you actually get it.
</p>
<h4>Key Focus Areas</h4>
<ul>
@@ -194,8 +189,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge critical">Security</span>
</div>
<p class="agent-detail-description">
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.
</p>
<h4>Security Checks</h4>
<ul>
@@ -218,8 +212,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Performance</span>
</div>
<p class="agent-detail-description">
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.
</p>
<h4>Analysis Areas</h4>
<ul>
@@ -242,8 +235,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Architecture</span>
</div>
<p class="agent-detail-description">
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."
</p>
<h4>Analysis Areas</h4>
<ul>
@@ -265,8 +257,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge critical">Data</span>
</div>
<p class="agent-detail-description">
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.
</p>
<h4>Review Areas</h4>
<ul>
@@ -288,8 +279,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Patterns</span>
</div>
<p class="agent-detail-description">
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.
</p>
<h4>Detection Areas</h4>
<ul>
@@ -311,8 +301,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Quality</span>
</div>
<p class="agent-detail-description">
Ensures code is as simple and minimal as possible. Applies YAGNI rigorously
and challenges unnecessary abstractions.
Simplicity is violent discipline. This agent asks "do you actually need this?" about every line, every abstraction, every dependency. YAGNI isn't a suggestion—it's the law. Your 200-line feature with three layers of indirection? This agent will show you the 50-line version that does the same thing. Complexity is a liability; simplicity compounds.
</p>
<h4>Simplification Checks</h4>
<ul>
@@ -332,7 +321,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<!-- Research Agents -->
<section id="research-agents">
<h2><i class="fa-solid fa-microscope"></i> Research Agents (4)</h2>
<p>Research agents that gather information from documentation, repositories, and git history to inform development decisions.</p>
<p>Stop guessing. These agents dig through documentation, GitHub repos, git history, and real-world examples to give you answers backed by evidence. They read faster than you, remember more than you, and synthesize patterns you'd miss. Perfect for "how should I actually do this?" questions.</p>
<div class="agent-detail" id="framework-docs-researcher">
<div class="agent-detail-header">
@@ -340,7 +329,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Research</span>
</div>
<p class="agent-detail-description">
Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies.
Official docs are scattered. GitHub examples are inconsistent. Deprecations hide in changelogs. This agent pulls it all together—docs, source code, version constraints, real-world examples. Ask "how do I use Hotwire Turbo?" and get back patterns that actually work in production, not toy tutorials.
</p>
<h4>Capabilities</h4>
<ul>
@@ -361,7 +350,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Research</span>
</div>
<p class="agent-detail-description">
Researches and gathers external best practices, documentation, and examples for any technology.
"Best practices" are everywhere and contradictory. This agent cuts through the noise by evaluating sources (official docs, trusted blogs, real GitHub repos), checking recency, and synthesizing actionable guidance. You get code templates, patterns that scale, and answers you can trust—not StackOverflow copy-paste roulette.
</p>
<h4>Capabilities</h4>
<ul>
@@ -382,7 +371,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Git</span>
</div>
<p class="agent-detail-description">
Archaeological analysis of code repositories to understand evolution and patterns.
Your codebase has a history—decisions, patterns, mistakes. This agent does archaeology with git tools: file evolution, blame analysis, contributor expertise mapping. Ask "why does this code exist?" and get the commit that explains it. Spot patterns in how bugs appear. Understand the design decisions buried in history.
</p>
<h4>Analysis Techniques</h4>
<ul>
@@ -403,7 +392,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Research</span>
</div>
<p class="agent-detail-description">
Conducts thorough research on repository structure, documentation, and patterns.
Every repo has conventions—some documented, most tribal knowledge. This agent reads ARCHITECTURE.md, issue templates, PR patterns, and actual code to reverse-engineer the standards. Perfect for joining a new project or ensuring your PR matches the team's implicit style. Finds the rules nobody wrote down.
</p>
<h4>Analysis Areas</h4>
<ul>
@@ -422,7 +411,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<!-- Workflow Agents -->
<section id="workflow-agents">
<h2><i class="fa-solid fa-gears"></i> Workflow Agents (5)</h2>
<p>Workflow agents that automate common development tasks like bug reproduction, PR resolution, and linting.</p>
<p>Tedious work you hate doing. These agents handle the grind—reproducing bugs, resolving PR comments, running linters, analyzing specs. They're fast, they don't complain, and they free you up to solve interesting problems instead of mechanical ones.</p>
<div class="agent-detail" id="bug-reproduction-validator">
<div class="agent-detail-header">
@@ -430,8 +419,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Bugs</span>
</div>
<p class="agent-detail-description">
Verifies whether bug reports are actual bugs through systematic reproduction.
Classifies bugs and provides severity assessment.
Half of bug reports aren't bugs—they're user errors, environment issues, or misunderstood features. This agent systematically reproduces the reported behavior, classifies what it finds (Confirmed, Can't Reproduce, Not a Bug, etc.), and assesses severity. Saves you from chasing ghosts or missing real issues.
</p>
<h4>Classification Types</h4>
<ul>
@@ -453,7 +441,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">PR</span>
</div>
<p class="agent-detail-description">
Addresses code review comments by implementing requested changes and reporting resolutions.
Code review comments pile up. This agent reads them, plans fixes, implements changes, and reports back what it did. It doesn't argue with reviewers or skip hard feedback—it just resolves the work systematically. Great for burning through a dozen "change this variable name" comments in seconds.
</p>
<h4>Workflow</h4>
<ul>
@@ -474,8 +462,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Quality</span>
</div>
<p class="agent-detail-description">
Runs linting and code quality checks on Ruby and ERB files.
Uses Haiku model for efficiency.
Linters are pedantic robots that enforce consistency. This agent runs StandardRB, ERBLint, and Brakeman for you—checking Ruby style, ERB templates, and security issues. It's fast (uses the Haiku model) and catches the formatting noise before CI does.
</p>
<h4>Tools Run</h4>
<ul>
@@ -494,8 +481,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Testing</span>
</div>
<p class="agent-detail-description">
Analyzes specifications and plans for user flows and gap identification.
Uses Sonnet model for analysis.
Specs always have gaps—edge cases nobody thought about, ambiguous requirements, missing error states. This agent maps all possible user flows, identifies what's unclear or missing, and generates the questions you need to ask stakeholders. Runs before you code to avoid building the wrong thing.
</p>
<h4>Analysis Areas</h4>
<ul>
@@ -516,7 +502,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Content</span>
</div>
<p class="agent-detail-description">
Reviews and edits text content to conform to Every's specific style guide.
Style guides are arbitrary rules that make writing consistent. This agent enforces Every's particular quirks—title case in headlines, no overused filler words ("actually," "very"), active voice, Oxford commas. It's a line-by-line grammar cop for content that needs to match the brand.
</p>
<h4>Style Checks</h4>
<ul>
@@ -535,7 +521,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<!-- Design Agents -->
<section id="design-agents">
<h2><i class="fa-solid fa-palette"></i> Design Agents (3)</h2>
<p>Design agents that help with UI implementation, Figma synchronization, and iterative design refinement.</p>
<p>Design is iteration. These agents take screenshots, compare them to Figma, make targeted improvements, and repeat. They fix spacing, alignment, colors, typography—the visual details that compound into polish. Perfect for closing the gap between "it works" and "it looks right."</p>
<div class="agent-detail" id="design-iterator">
<div class="agent-detail-header">
@@ -543,8 +529,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Design</span>
</div>
<p class="agent-detail-description">
Systematic UI/UX design refinement through iterative improvements.
Takes screenshots, analyzes, implements changes, and repeats.
Design doesn't happen in one pass. This agent runs a loop: screenshot the UI, analyze what's off (spacing, colors, alignment), implement 3-5 targeted fixes, repeat. Run it for 10 iterations and watch rough interfaces transform into polished designs through systematic refinement.
</p>
<h4>Process</h4>
<ul>
@@ -565,8 +550,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Figma</span>
</div>
<p class="agent-detail-description">
Automatically detects and fixes visual differences between Figma designs and web implementations.
Uses Sonnet model.
Designers hand you a Figma file. You build it. Then: "the spacing is wrong, the font is off, the colors don't match." This agent compares your implementation to the Figma spec, identifies every visual discrepancy, and fixes them automatically. Designers stay happy. You stay sane.
</p>
<h4>Workflow</h4>
<ul>
@@ -587,8 +571,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Review</span>
</div>
<p class="agent-detail-description">
Verifies UI implementations match Figma design specifications.
Uses Opus model for detailed analysis.
Before you ship UI changes, run this agent. It compares your implementation against Figma at a pixel level—layouts, typography, colors, spacing, responsive behavior. Uses the Opus model for detailed visual analysis. Catches the "close enough" mistakes that users notice but you don't.
</p>
<h4>Comparison Areas</h4>
<ul>
@@ -614,8 +597,7 @@ claude agent security-sentinel "Audit the payment flow"</code></pre>
<span class="agent-badge">Docs</span>
</div>
<p class="agent-detail-description">
Creates/updates README files following Ankane-style template for Ruby gems.
Optimized for conciseness with every sentence kept to 15 words or less.
Andrew Kane writes READMEs that are models of clarity—concise, scannable, zero fluff. This agent generates gem documentation in that style: 15 words max per sentence, imperative voice, single-purpose code examples. If your README rambles, this agent will fix it.
</p>
<h4>Section Order</h4>
<ol>