From 91bd7e812ffae18c664d56f0da237d5ec95ad8f9 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Nov 2025 15:46:16 +0000 Subject: [PATCH 01/25] docs: Add comprehensive documentation site for compounding-engineering plugin MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Create landing page with Evil Martians devtool-template styling - Add dark theme with accent colors and responsive design - Document all 24 agents, 16 commands, 11 skills, and 2 MCP servers - Add Getting Started guide with installation and configuration - Include FAQ section, philosophy explanation, and code examples - Add CSS with mobile-responsive layouts and smooth animations - Include JavaScript for mobile nav, smooth scroll, and copy code Built with LaunchKit template from Evil Martians. πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../compounding-engineering/docs/css/docs.css | 513 +++++++ .../docs/css/style.css | 1218 +++++++++++++++++ .../compounding-engineering/docs/index.html | 889 ++++++++++++ .../compounding-engineering/docs/js/main.js | 225 +++ .../docs/pages/getting-started.html | 597 ++++++++ 5 files changed, 3442 insertions(+) create mode 100644 plugins/compounding-engineering/docs/css/docs.css create mode 100644 plugins/compounding-engineering/docs/css/style.css create mode 100644 plugins/compounding-engineering/docs/index.html create mode 100644 plugins/compounding-engineering/docs/js/main.js create mode 100644 plugins/compounding-engineering/docs/pages/getting-started.html diff --git a/plugins/compounding-engineering/docs/css/docs.css b/plugins/compounding-engineering/docs/css/docs.css new file mode 100644 index 0000000..c4a9df8 --- /dev/null +++ b/plugins/compounding-engineering/docs/css/docs.css @@ -0,0 +1,513 @@ +/* Documentation-specific styles */ + +/* ============================================ + Documentation Layout + ============================================ */ + +.docs-layout { + display: grid; + grid-template-columns: 1fr; + min-height: 100vh; +} + +@media (min-width: 1024px) { + .docs-layout { + grid-template-columns: 280px 1fr; + } +} + +/* ============================================ + Sidebar + ============================================ */ + +.docs-sidebar { + position: fixed; + top: 0; + left: -300px; + width: 280px; + height: 100vh; + background-color: var(--color-background); + border-right: 1px solid var(--color-border); + overflow-y: auto; + transition: left 0.3s ease; + z-index: 100; +} + +.docs-sidebar.open { + left: 0; +} + +@media (min-width: 1024px) { + .docs-sidebar { + position: sticky; + left: 0; + } +} + +.sidebar-header { + padding: var(--space-l); + border-bottom: 1px solid var(--color-border); +} + +.sidebar-header .nav-brand { + display: flex; + align-items: center; + gap: var(--space-s); + text-decoration: none; + color: var(--color-text-primary); + font-weight: 600; +} + +.sidebar-header .logo-icon { + color: var(--color-accent); + font-size: var(--font-size-l); +} + +.sidebar-header .logo-text { + display: inline; +} + +.sidebar-nav { + padding: var(--space-l); +} + +.nav-section { + margin-bottom: var(--space-xl); +} + +.nav-section h3 { + font-size: var(--font-size-xs); + font-weight: 600; + text-transform: uppercase; + letter-spacing: 0.05em; + color: var(--color-text-tertiary); + margin: 0 0 var(--space-m) 0; +} + +.nav-section ul { + list-style: none; + margin: 0; + padding: 0; +} + +.nav-section li { + margin: 0; +} + +.nav-section a { + display: block; + padding: var(--space-s) var(--space-m); + color: var(--color-text-secondary); + text-decoration: none; + font-size: var(--font-size-s); + border-radius: var(--radius-s); + transition: all 0.2s ease; +} + +.nav-section a:hover { + color: var(--color-text-primary); + background-color: var(--color-surface); +} + +.nav-section a.active { + color: var(--color-accent); + background-color: var(--color-accent-light); +} + +/* ============================================ + Main Content + ============================================ */ + +.docs-content { + padding: var(--space-xl); + max-width: 900px; +} + +@media (min-width: 1024px) { + .docs-content { + padding: var(--space-xxl); + } +} + +.docs-header { + display: flex; + align-items: center; + justify-content: space-between; + margin-bottom: var(--space-xl); +} + +.breadcrumb { + display: flex; + align-items: center; + gap: var(--space-s); + font-size: var(--font-size-s); + color: var(--color-text-tertiary); +} + +.breadcrumb a { + color: var(--color-text-secondary); + text-decoration: none; +} + +.breadcrumb a:hover { + color: var(--color-accent); +} + +.mobile-menu-toggle { + display: flex; + align-items: center; + justify-content: center; + width: 40px; + height: 40px; + background: none; + border: 1px solid var(--color-border); + border-radius: var(--radius-s); + color: var(--color-text-secondary); + cursor: pointer; +} + +@media (min-width: 1024px) { + .mobile-menu-toggle { + display: none; + } +} + +/* ============================================ + Article Styles + ============================================ */ + +.docs-article { + line-height: 1.7; +} + +.docs-article h1 { + font-size: var(--font-size-xl); + margin-bottom: var(--space-l); +} + +.docs-article h2 { + font-size: var(--font-size-l); + margin-top: var(--space-xxl); + margin-bottom: var(--space-l); + padding-bottom: var(--space-s); + border-bottom: 1px solid var(--color-border); + display: flex; + align-items: center; + gap: var(--space-s); +} + +.docs-article h2 i { + color: var(--color-accent); +} + +.docs-article h3 { + font-size: var(--font-size-m); + margin-top: var(--space-xl); + margin-bottom: var(--space-m); +} + +.docs-article h4 { + font-size: var(--font-size-s); + margin-top: var(--space-l); + margin-bottom: var(--space-s); +} + +.docs-article p { + margin-bottom: var(--space-l); +} + +.docs-article .lead { + font-size: var(--font-size-l); + color: var(--color-text-secondary); + margin-bottom: var(--space-xl); +} + +.docs-article ul, +.docs-article ol { + margin-bottom: var(--space-l); + padding-left: var(--space-xl); +} + +.docs-article li { + margin-bottom: var(--space-s); +} + +/* ============================================ + Code Blocks in Docs + ============================================ */ + +.docs-article .card-code-block { + margin: var(--space-l) 0; +} + +.docs-article code { + font-family: var(--font-mono); + font-size: 0.9em; + background-color: var(--color-surface); + padding: 2px 6px; + border-radius: var(--radius-xs); + color: var(--color-accent); +} + +.docs-article pre code { + background: none; + padding: 0; + color: var(--color-code-text); +} + +/* ============================================ + Tables + ============================================ */ + +.docs-table { + width: 100%; + border-collapse: collapse; + margin: var(--space-l) 0; + font-size: var(--font-size-s); +} + +.docs-table th, +.docs-table td { + padding: var(--space-m); + text-align: left; + border-bottom: 1px solid var(--color-border); +} + +.docs-table th { + font-weight: 600; + color: var(--color-text-primary); + background-color: var(--color-surface); +} + +.docs-table td { + color: var(--color-text-secondary); +} + +.docs-table code { + font-size: 0.85em; +} + +/* ============================================ + Callouts + ============================================ */ + +.callout { + display: flex; + gap: var(--space-m); + padding: var(--space-l); + border-radius: var(--radius-m); + margin: var(--space-l) 0; +} + +.callout-icon { + font-size: var(--font-size-l); + flex-shrink: 0; +} + +.callout-content h4 { + margin: 0 0 var(--space-s) 0; + font-size: var(--font-size-s); +} + +.callout-content p { + margin: 0; + font-size: var(--font-size-s); +} + +.callout-info { + background-color: rgba(99, 102, 241, 0.1); + border: 1px solid rgba(99, 102, 241, 0.2); +} + +.callout-info .callout-icon { + color: var(--color-accent); +} + +.callout-info .callout-content h4 { + color: var(--color-accent); +} + +.callout-tip { + background-color: rgba(16, 185, 129, 0.1); + border: 1px solid rgba(16, 185, 129, 0.2); +} + +.callout-tip .callout-icon { + color: var(--color-success); +} + +.callout-tip .callout-content h4 { + color: var(--color-success); +} + +.callout-warning { + background-color: rgba(245, 158, 11, 0.1); + border: 1px solid rgba(245, 158, 11, 0.2); +} + +.callout-warning .callout-icon { + color: var(--color-warning); +} + +.callout-warning .callout-content h4 { + color: var(--color-warning); +} + +/* ============================================ + Badges + ============================================ */ + +.badge { + display: inline-block; + padding: 2px 8px; + font-size: var(--font-size-xs); + font-weight: 600; + border-radius: var(--radius-s); + text-transform: uppercase; + letter-spacing: 0.03em; +} + +.badge-critical { + background-color: rgba(239, 68, 68, 0.15); + color: var(--color-error); +} + +.badge-important { + background-color: rgba(245, 158, 11, 0.15); + color: var(--color-warning); +} + +.badge-nice { + background-color: rgba(99, 102, 241, 0.15); + color: var(--color-accent); +} + +/* ============================================ + Philosophy Grid + ============================================ */ + +.philosophy-grid { + display: grid; + grid-template-columns: repeat(1, 1fr); + gap: var(--space-l); + margin: var(--space-xl) 0; +} + +@media (min-width: 640px) { + .philosophy-grid { + grid-template-columns: repeat(2, 1fr); + } +} + +.philosophy-card { + padding: var(--space-xl); + background-color: var(--color-surface); + border-radius: var(--radius-m); + border: 1px solid var(--color-border); +} + +.philosophy-icon { + font-size: var(--font-size-xl); + color: var(--color-accent); + margin-bottom: var(--space-m); +} + +.philosophy-card h4 { + margin: 0 0 var(--space-s) 0; + color: var(--color-text-primary); +} + +.philosophy-card p { + margin: 0; + font-size: var(--font-size-s); + color: var(--color-text-secondary); +} + +/* ============================================ + Blockquotes + ============================================ */ + +.highlight-quote { + font-size: var(--font-size-l); + font-style: italic; + color: var(--color-accent); + padding: var(--space-xl); + margin: var(--space-xl) 0; + background: linear-gradient(135deg, var(--color-accent-lighter), transparent); + border-left: 4px solid var(--color-accent); + border-radius: var(--radius-m); +} + +/* ============================================ + Navigation Footer + ============================================ */ + +.docs-nav-footer { + display: flex; + justify-content: space-between; + gap: var(--space-l); + margin-top: var(--space-xxl); + padding-top: var(--space-xl); + border-top: 1px solid var(--color-border); +} + +.nav-prev, +.nav-next { + display: flex; + flex-direction: column; + gap: var(--space-xs); + padding: var(--space-l); + background-color: var(--color-surface); + border-radius: var(--radius-m); + text-decoration: none; + transition: all 0.2s ease; + flex: 1; + max-width: 300px; +} + +.nav-prev:hover, +.nav-next:hover { + background-color: var(--color-surface-hover); + border-color: var(--color-accent); +} + +.nav-next { + text-align: right; + margin-left: auto; +} + +.nav-label { + font-size: var(--font-size-xs); + color: var(--color-text-tertiary); + text-transform: uppercase; + letter-spacing: 0.05em; +} + +.nav-title { + font-weight: 600; + color: var(--color-accent); + display: flex; + align-items: center; + gap: var(--space-s); +} + +.nav-next .nav-title { + justify-content: flex-end; +} + +/* ============================================ + Mobile Sidebar Overlay + ============================================ */ + +@media (max-width: 1023px) { + .docs-sidebar.open::before { + content: ''; + position: fixed; + top: 0; + left: 0; + right: 0; + bottom: 0; + background-color: rgba(0, 0, 0, 0.5); + z-index: -1; + } +} diff --git a/plugins/compounding-engineering/docs/css/style.css b/plugins/compounding-engineering/docs/css/style.css new file mode 100644 index 0000000..677b933 --- /dev/null +++ b/plugins/compounding-engineering/docs/css/style.css @@ -0,0 +1,1218 @@ +/* Compounding Engineering Documentation Styles */ +/* Based on LaunchKit template by Evil Martians */ + +/* ============================================ + CSS Variables & Theme Configuration + ============================================ */ + +:root { + /* Theme configuration */ + --theme-hue: 250; + --theme-saturation: 0.3; + --theme-contrast: 0.85; + + /* Fonts */ + --font-text: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, sans-serif; + --font-mono: "JetBrains Mono", "Fira Code", "SF Mono", Consolas, monospace; + + /* Font sizes */ + --font-size-xs: 12px; + --font-size-s: 14px; + --font-size-m: 16px; + --font-size-l: 20px; + --font-size-xl: 32px; + --font-size-xxl: 48px; + + /* Line heights */ + --line-height-paragraph-s: 20px; + --line-height-paragraph-m: 24px; + --line-height-paragraph-l: 28px; + --line-height-h1: 56px; + --line-height-h2: 40px; + --line-height-h3: 28px; + --line-height-ui-s: 16px; + --line-height-ui-m: 22px; + + /* Spacing */ + --space-xs: 4px; + --space-s: 8px; + --space-m: 12px; + --space-l: 16px; + --space-xl: 24px; + --space-xxl: 48px; + --space-section: 80px; + --space-card: 20px; + + /* Border radii */ + --radius-xs: 4px; + --radius-s: 8px; + --radius-m: 12px; + --radius-l: 16px; + --radius-xl: 24px; + + /* UI */ + --header-font-weight: 600; + --ui-button-font-weight: 500; +} + +/* Light Theme */ +.theme-light { + --color-background: #ffffff; + --color-background-blur: rgba(255, 255, 255, 0.9); + --color-surface: rgba(0, 0, 0, 0.03); + --color-surface-hover: rgba(0, 0, 0, 0.06); + --color-text-primary: #1a1a2e; + --color-text-secondary: #64748b; + --color-text-tertiary: #94a3b8; + --color-accent: #6366f1; + --color-accent-hover: #4f46e5; + --color-accent-light: rgba(99, 102, 241, 0.1); + --color-accent-lighter: rgba(99, 102, 241, 0.05); + --color-on-accent: #ffffff; + --color-border: rgba(0, 0, 0, 0.08); + --color-border-strong: rgba(0, 0, 0, 0.15); + --color-gradient-start: rgba(99, 102, 241, 0.15); + --color-gradient-end: rgba(99, 102, 241, 0); + --color-promo-start: #a855f7; + --color-promo-end: #6366f1; + --color-success: #10b981; + --color-warning: #f59e0b; + --color-error: #ef4444; + --color-code-bg: #1e1e2e; + --color-code-text: #cdd6f4; +} + +/* Dark Theme */ +.theme-dark { + color-scheme: dark; + --color-background: #0f0f1a; + --color-background-blur: rgba(15, 15, 26, 0.9); + --color-surface: rgba(255, 255, 255, 0.04); + --color-surface-hover: rgba(255, 255, 255, 0.08); + --color-text-primary: #f1f5f9; + --color-text-secondary: #94a3b8; + --color-text-tertiary: #64748b; + --color-accent: #818cf8; + --color-accent-hover: #a5b4fc; + --color-accent-light: rgba(129, 140, 248, 0.15); + --color-accent-lighter: rgba(129, 140, 248, 0.08); + --color-on-accent: #0f0f1a; + --color-border: rgba(255, 255, 255, 0.08); + --color-border-strong: rgba(255, 255, 255, 0.15); + --color-gradient-start: rgba(129, 140, 248, 0.2); + --color-gradient-end: rgba(129, 140, 248, 0); + --color-promo-start: #c084fc; + --color-promo-end: #818cf8; + --color-success: #34d399; + --color-warning: #fbbf24; + --color-error: #f87171; + --color-code-bg: #1e1e2e; + --color-code-text: #cdd6f4; +} + +/* ============================================ + Base Styles + ============================================ */ + +*, *::before, *::after { + box-sizing: border-box; +} + +html, body { + margin: 0; + padding: 0; +} + +body { + background-color: var(--color-background); + font-family: var(--font-text); + color: var(--color-text-primary); + font-size: var(--font-size-m); + line-height: var(--line-height-paragraph-m); + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +/* ============================================ + Typography + ============================================ */ + +h1, h2, h3, h4, h5, h6 { + font-weight: var(--header-font-weight); + margin: var(--space-m) 0; + letter-spacing: -0.02em; +} + +h1 { + font-size: var(--font-size-xxl); + line-height: var(--line-height-h1); + letter-spacing: -0.03em; +} + +h2 { + font-size: var(--font-size-xl); + line-height: var(--line-height-h2); +} + +h3 { + font-size: var(--font-size-l); + line-height: var(--line-height-h3); +} + +p { + margin: var(--space-m) 0; +} + +a { + color: var(--color-accent); + text-decoration: none; + transition: color 0.2s ease; +} + +a:hover { + color: var(--color-accent-hover); +} + +ul, ol { + margin: var(--space-l) 0; + padding-left: 24px; +} + +li { + margin: var(--space-s) 0; +} + +code { + font-family: var(--font-mono); + font-size: 0.9em; + background-color: var(--color-surface); + padding: 2px 6px; + border-radius: var(--radius-xs); + color: var(--color-accent); +} + +img { + max-width: 100%; + vertical-align: middle; +} + +/* Text utilities */ +.paragraph { + margin: var(--space-m) 0; +} +.paragraph.s { font-size: var(--font-size-s); line-height: var(--line-height-paragraph-s); } +.paragraph.m { font-size: var(--font-size-m); line-height: var(--line-height-paragraph-m); } +.paragraph.l { font-size: var(--font-size-l); line-height: var(--line-height-paragraph-l); } +.paragraph.bold { font-weight: 600; } + +.secondary { color: var(--color-text-secondary); } +.tertiary { color: var(--color-text-tertiary); } +.color-accent { color: var(--color-accent); } + +.no-top-margin { margin-top: 0; } +.balanced { text-wrap: balance; } + +/* ============================================ + Layout + ============================================ */ + +.page-container { + max-width: 1200px; + min-height: 100vh; + margin: 0 auto; + padding: 0 var(--space-xl); + display: flex; + flex-direction: column; +} + +section { + padding: var(--space-section) 0; +} + +.background-gradient { + position: fixed; + top: 0; + left: 0; + right: 0; + height: 100vh; + background: linear-gradient(180deg, var(--color-gradient-start) 0%, var(--color-gradient-end) 50%); + z-index: -10; + pointer-events: none; +} + +/* ============================================ + Navigation + ============================================ */ + +.nav-container { + position: sticky; + top: var(--space-l); + margin-top: var(--space-l); + display: flex; + justify-content: space-between; + align-items: center; + background-color: var(--color-background-blur); + backdrop-filter: blur(20px); + -webkit-backdrop-filter: blur(20px); + border: 1px solid var(--color-border); + border-radius: var(--radius-l); + padding: var(--space-m) var(--space-l); + z-index: 1000; +} + +.nav-brand { + display: flex; + align-items: center; + gap: var(--space-s); + text-decoration: none; + color: var(--color-text-primary); + font-weight: 600; + font-size: var(--font-size-m); +} + +.logo-icon { + color: var(--color-accent); + font-size: var(--font-size-l); +} + +.logo-text { + display: none; +} + +@media (min-width: 768px) { + .logo-text { + display: inline; + } +} + +.nav-menu { + display: none; + gap: var(--space-xs); +} + +@media (min-width: 1024px) { + .nav-menu { + display: flex; + } +} + +.nav-link { + color: var(--color-text-secondary); + font-size: var(--font-size-s); + font-weight: var(--ui-button-font-weight); + padding: var(--space-s) var(--space-m); + border-radius: var(--radius-s); + text-decoration: none; + transition: all 0.2s ease; +} + +.nav-link:hover { + color: var(--color-text-primary); + background-color: var(--color-surface); +} + +.nav-hamburger { + display: flex; +} + +@media (min-width: 1024px) { + .nav-hamburger { + display: none; + } +} + +/* Mobile nav */ +.nav-menu.open { + display: flex; + flex-direction: column; + position: absolute; + top: calc(100% + var(--space-s)); + left: 0; + right: 0; + background-color: var(--color-background); + border: 1px solid var(--color-border); + border-radius: var(--radius-l); + padding: var(--space-l); +} + +/* ============================================ + Buttons + ============================================ */ + +.button { + display: inline-flex; + align-items: center; + justify-content: center; + gap: var(--space-s); + padding: var(--space-m) var(--space-xl); + font-size: var(--font-size-m); + font-weight: var(--ui-button-font-weight); + font-family: inherit; + text-decoration: none; + border: none; + border-radius: var(--radius-m); + cursor: pointer; + transition: all 0.2s ease; +} + +.button.compact { + padding: var(--space-s) var(--space-m); + font-size: var(--font-size-s); + border-radius: var(--radius-s); +} + +.button.primary { + background-color: var(--color-accent); + color: var(--color-on-accent); +} + +.button.primary:hover { + background-color: var(--color-accent-hover); + transform: translateY(-1px); +} + +.button.secondary { + background-color: var(--color-accent-light); + color: var(--color-accent); +} + +.button.secondary:hover { + background-color: var(--color-accent-lighter); +} + +.button.tertiary { + background-color: transparent; + color: var(--color-text-secondary); + border: 1px solid var(--color-border-strong); +} + +.button.tertiary:hover { + background-color: var(--color-surface); + color: var(--color-text-primary); +} + +.button.ghost { + background-color: transparent; + color: var(--color-text-secondary); +} + +.button.ghost:hover { + background-color: var(--color-surface); + color: var(--color-text-primary); +} + +.button-group { + display: flex; + flex-wrap: wrap; + gap: var(--space-m); + align-items: center; +} + +.button-group.centered { + justify-content: center; +} + +.button-group.stacked { + flex-direction: column; +} + +.button-group.margin-paragraph { + margin: var(--space-l) 0; +} + +/* ============================================ + Headings & Sections + ============================================ */ + +.heading { + max-width: 720px; + margin-bottom: var(--space-xl); +} + +.heading.centered { + text-align: center; + margin-left: auto; + margin-right: auto; +} + +.heading.hero { + padding: var(--space-xxl) 0; +} + +.eyebrow { + display: inline-flex; + align-items: center; + gap: var(--space-s); + padding: var(--space-xs) var(--space-m); + background-color: var(--color-accent-light); + color: var(--color-accent); + font-size: var(--font-size-s); + font-weight: 500; + border-radius: var(--radius-xl); + margin-bottom: var(--space-l); + text-decoration: none; +} + +.eyebrow:hover { + background-color: var(--color-accent-lighter); +} + +/* ============================================ + Stats Section + ============================================ */ + +.stats-section { + padding: var(--space-xl) 0; +} + +.stats-container { + display: grid; + grid-template-columns: repeat(2, 1fr); + gap: var(--space-l); +} + +@media (min-width: 768px) { + .stats-container { + grid-template-columns: repeat(4, 1fr); + } +} + +.stat-card { + text-align: center; + padding: var(--space-xl); + background-color: var(--color-surface); + border-radius: var(--radius-l); + border: 1px solid var(--color-border); +} + +.stat-number { + font-size: var(--font-size-xxl); + font-weight: 700; + color: var(--color-accent); + line-height: 1; + margin-bottom: var(--space-s); +} + +.stat-label { + font-size: var(--font-size-s); + color: var(--color-text-secondary); + font-weight: 500; +} + +/* ============================================ + Cards with Icons + ============================================ */ + +.cards-with-icons-container { + display: grid; + grid-template-columns: repeat(1, 1fr); + gap: var(--space-xl); + margin-top: var(--space-xl); +} + +@media (min-width: 640px) { + .cards-with-icons-container { + grid-template-columns: repeat(2, 1fr); + } +} + +@media (min-width: 1024px) { + .cards-with-icons-container { + grid-template-columns: repeat(4, 1fr); + } +} + +.card-with-icon { + display: flex; + flex-direction: column; + gap: var(--space-m); + padding: var(--space-xl); + background-color: var(--color-surface); + border-radius: var(--radius-l); + border: 1px solid var(--color-border); + transition: all 0.2s ease; +} + +.card-with-icon:hover { + border-color: var(--color-accent); + transform: translateY(-2px); +} + +.card-with-icon .icon { + font-size: var(--font-size-xl); + color: var(--color-accent); +} + +.feature-heading { + display: flex; + flex-direction: column; + gap: var(--space-xs); +} + +.feature-heading p { + margin: 0; +} + +/* ============================================ + Grid System + ============================================ */ + +.grid { + display: grid; + gap: var(--space-l); + margin: var(--space-l) 0; +} + +.grid.columns-2 { + grid-template-columns: repeat(1, 1fr); +} + +.grid.columns-3 { + grid-template-columns: repeat(1, 1fr); +} + +@media (min-width: 768px) { + .grid.columns-2 { + grid-template-columns: repeat(2, 1fr); + } + .grid.columns-3 { + grid-template-columns: repeat(2, 1fr); + } +} + +@media (min-width: 1024px) { + .grid.columns-3 { + grid-template-columns: repeat(3, 1fr); + } +} + +.full-width { + grid-column: 1 / -1; +} + +/* ============================================ + Agent Cards + ============================================ */ + +.agent-category { + margin-bottom: var(--space-xxl); +} + +.agent-category h3 { + display: flex; + align-items: center; + gap: var(--space-s); + margin-bottom: var(--space-l); + color: var(--color-text-primary); +} + +.agent-category h3 i { + color: var(--color-accent); +} + +.agent-card { + padding: var(--space-xl); + background-color: var(--color-surface); + border-radius: var(--radius-l); + border: 1px solid var(--color-border); + transition: all 0.2s ease; +} + +.agent-card:hover { + border-color: var(--color-accent); +} + +.agent-header { + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--space-m); + margin-bottom: var(--space-m); +} + +.agent-name { + font-family: var(--font-mono); + font-size: var(--font-size-s); + font-weight: 600; + color: var(--color-text-primary); +} + +.agent-badge { + padding: var(--space-xs) var(--space-s); + font-size: var(--font-size-xs); + font-weight: 600; + background-color: var(--color-accent-light); + color: var(--color-accent); + border-radius: var(--radius-s); + text-transform: uppercase; + letter-spacing: 0.05em; +} + +.agent-badge.critical { + background-color: rgba(239, 68, 68, 0.15); + color: var(--color-error); +} + +.agent-description { + font-size: var(--font-size-s); + color: var(--color-text-secondary); + margin: 0 0 var(--space-m) 0; + line-height: 1.5; +} + +.agent-usage { + display: block; + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--color-text-tertiary); + background-color: var(--color-code-bg); + padding: var(--space-s) var(--space-m); + border-radius: var(--radius-s); +} + +/* ============================================ + Command Cards + ============================================ */ + +.command-category { + margin-bottom: var(--space-xxl); +} + +.command-category h3 { + display: flex; + align-items: center; + gap: var(--space-s); + margin-bottom: var(--space-l); + color: var(--color-text-primary); +} + +.command-category h3 i { + color: var(--color-accent); +} + +.command-card { + padding: var(--space-xl); + background-color: var(--color-surface); + border-radius: var(--radius-l); + border: 1px solid var(--color-border); + transition: all 0.2s ease; +} + +.command-card:hover { + border-color: var(--color-accent); +} + +.command-header { + margin-bottom: var(--space-s); +} + +.command-name { + font-family: var(--font-mono); + font-size: var(--font-size-m); + font-weight: 600; + color: var(--color-accent); + background: none; + padding: 0; +} + +.command-description { + font-size: var(--font-size-s); + color: var(--color-text-secondary); + margin: 0; + line-height: 1.5; +} + +/* ============================================ + Skill Cards + ============================================ */ + +.skill-category { + margin-bottom: var(--space-xxl); +} + +.skill-category h3 { + display: flex; + align-items: center; + gap: var(--space-s); + margin-bottom: var(--space-l); + color: var(--color-text-primary); +} + +.skill-category h3 i { + color: var(--color-accent); +} + +.skill-card { + padding: var(--space-xl); + background-color: var(--color-surface); + border-radius: var(--radius-l); + border: 1px solid var(--color-border); + transition: all 0.2s ease; +} + +.skill-card:hover { + border-color: var(--color-accent); +} + +.skill-card.featured { + background: linear-gradient(135deg, var(--color-accent-lighter), var(--color-surface)); + border-color: var(--color-accent); +} + +.skill-header { + display: flex; + align-items: center; + justify-content: space-between; + gap: var(--space-m); + margin-bottom: var(--space-m); +} + +.skill-name { + font-family: var(--font-mono); + font-size: var(--font-size-s); + font-weight: 600; + color: var(--color-text-primary); +} + +.skill-badge { + padding: var(--space-xs) var(--space-s); + font-size: var(--font-size-xs); + font-weight: 600; + background-color: var(--color-accent-light); + color: var(--color-accent); + border-radius: var(--radius-s); + text-transform: uppercase; + letter-spacing: 0.05em; +} + +.skill-badge.highlight { + background-color: var(--color-accent); + color: var(--color-on-accent); +} + +.skill-description { + font-size: var(--font-size-s); + color: var(--color-text-secondary); + margin: 0 0 var(--space-m) 0; + line-height: 1.5; +} + +.skill-features { + display: flex; + flex-wrap: wrap; + gap: var(--space-s); + margin-bottom: var(--space-m); +} + +.feature-item { + display: flex; + align-items: center; + gap: var(--space-xs); + font-size: var(--font-size-xs); + color: var(--color-success); + background-color: rgba(16, 185, 129, 0.1); + padding: var(--space-xs) var(--space-s); + border-radius: var(--radius-s); +} + +.skill-usage { + display: block; + font-family: var(--font-mono); + font-size: var(--font-size-xs); + color: var(--color-text-tertiary); + background-color: var(--color-code-bg); + padding: var(--space-s) var(--space-m); + border-radius: var(--radius-s); + margin-bottom: var(--space-s); +} + +.skill-note { + font-size: var(--font-size-xs); + color: var(--color-text-tertiary); + margin: 0; + font-style: italic; +} + +/* ============================================ + MCP Cards + ============================================ */ + +.mcp-card { + padding: var(--space-xl); + background-color: var(--color-surface); + border-radius: var(--radius-l); + border: 1px solid var(--color-border); +} + +.mcp-header { + display: flex; + align-items: center; + gap: var(--space-m); + margin-bottom: var(--space-m); +} + +.mcp-icon { + font-size: var(--font-size-xl); + color: var(--color-accent); +} + +.mcp-name { + font-size: var(--font-size-l); + font-weight: 600; + color: var(--color-text-primary); +} + +.mcp-description { + font-size: var(--font-size-s); + color: var(--color-text-secondary); + margin-bottom: var(--space-l); +} + +.mcp-tools h4 { + font-size: var(--font-size-s); + color: var(--color-text-primary); + margin-bottom: var(--space-s); +} + +.mcp-tools ul { + margin: 0; + padding-left: var(--space-l); +} + +.mcp-tools li { + font-size: var(--font-size-s); + color: var(--color-text-secondary); + margin: var(--space-xs) 0; +} + +.mcp-tools code { + color: var(--color-accent); + background: none; + padding: 0; +} + +.mcp-note { + font-size: var(--font-size-xs); + color: var(--color-text-tertiary); + margin-top: var(--space-m); + font-style: italic; +} + +/* ============================================ + Installation Section + ============================================ */ + +.install-section { + background-color: var(--color-surface); + border-radius: var(--radius-xl); + margin: var(--space-xxl) 0; + padding: var(--space-xxl); +} + +.install-steps { + max-width: 700px; + margin: 0 auto; +} + +.install-step { + display: flex; + gap: var(--space-xl); + margin-bottom: var(--space-xl); +} + +.install-step:last-child { + margin-bottom: 0; +} + +.step-number { + flex-shrink: 0; + width: 40px; + height: 40px; + display: flex; + align-items: center; + justify-content: center; + background-color: var(--color-accent); + color: var(--color-on-accent); + font-weight: 700; + font-size: var(--font-size-l); + border-radius: 50%; +} + +.step-content { + flex: 1; +} + +.step-content h3 { + margin-top: 0; + margin-bottom: var(--space-m); +} + +/* ============================================ + Code Blocks + ============================================ */ + +.card-code-block { + background-color: var(--color-code-bg); + border-radius: var(--radius-m); + padding: var(--space-l); + overflow-x: auto; +} + +.card-code-block pre { + margin: 0; +} + +.card-code-block code { + font-family: var(--font-mono); + font-size: var(--font-size-s); + color: var(--color-code-text); + background: none; + padding: 0; + line-height: 1.6; + white-space: pre; +} + +/* ============================================ + Accordion / FAQ + ============================================ */ + +.accordion-container { + border-top: 1px solid var(--color-border); +} + +.accordion-item { + border-bottom: 1px solid var(--color-border); +} + +.accordion-toggle { + display: flex; + align-items: center; + justify-content: space-between; + padding: var(--space-xl) 0; + cursor: pointer; + list-style: none; +} + +.accordion-toggle::-webkit-details-marker { + display: none; +} + +.accordion-toggle p { + margin: 0; + color: var(--color-text-primary); +} + +.accordion-toggle:hover p { + color: var(--color-accent); +} + +.accordion-chevron { + color: var(--color-text-tertiary); + transition: transform 0.2s ease; +} + +[open] .accordion-chevron { + transform: rotate(180deg); +} + +.accordion-content { + padding-bottom: var(--space-xl); + color: var(--color-text-secondary); +} + +.accordion-content p { + margin: var(--space-m) 0; +} + +.accordion-content p:first-child { + margin-top: 0; +} + +/* ============================================ + Promo CTA Section + ============================================ */ + +.promo-cta { + background: linear-gradient(135deg, var(--color-promo-start), var(--color-promo-end)); + border-radius: var(--radius-xl); + padding: var(--space-xxl); + margin-bottom: var(--space-xxl); +} + +.promo-cta h2 { + color: white; +} + +.promo-cta p { + color: rgba(255, 255, 255, 0.9); +} + +.promo-cta .button.primary { + background-color: white; + color: var(--color-promo-end); +} + +.promo-cta .button.primary:hover { + background-color: rgba(255, 255, 255, 0.9); +} + +.promo-cta .button.tertiary { + border-color: rgba(255, 255, 255, 0.3); + color: white; +} + +.promo-cta .button.tertiary:hover { + background-color: rgba(255, 255, 255, 0.1); +} + +/* ============================================ + Footer + ============================================ */ + +.footer { + border-top: 1px solid var(--color-border); + margin-top: auto; + padding: var(--space-xxl) 0 var(--space-xl); +} + +.footer-menu { + display: grid; + grid-template-columns: 1fr; + gap: var(--space-xl); + margin-bottom: var(--space-xl); +} + +@media (min-width: 768px) { + .footer-menu { + grid-template-columns: 2fr 1fr 1fr; + } +} + +.footer p { + margin: 0; + color: var(--color-text-secondary); +} + +.link-list { + display: flex; + flex-direction: column; + gap: var(--space-m); +} + +.link-list a { + color: var(--color-text-secondary); + font-size: var(--font-size-s); + text-decoration: none; +} + +.link-list a:hover { + color: var(--color-accent); +} + +.icon-link { + display: flex; + align-items: center; + gap: var(--space-s); +} + +.icon-link .icon { + color: var(--color-accent); +} + +.pseudo-link { + text-decoration: underline; + text-decoration-color: var(--color-border); + text-underline-offset: 2px; +} + +.link-list-horizontal { + display: flex; + flex-wrap: wrap; + gap: var(--space-l); +} + +.link-list-horizontal a { + color: var(--color-text-tertiary); + font-size: var(--font-size-s); +} + +.link-list-horizontal a:hover { + color: var(--color-text-secondary); +} + +/* ============================================ + Utility Classes + ============================================ */ + +.hide-on-mobile { + display: none; +} + +@media (min-width: 768px) { + .hide-on-mobile { + display: flex; + } +} + +.mobile-only { + display: flex; +} + +@media (min-width: 1024px) { + .mobile-only { + display: none; + } +} + +.margin-top-l { + margin-top: var(--space-l); +} + +.ui.s { + font-size: var(--font-size-s); + line-height: var(--line-height-ui-s); +} + +.icon { + display: inline-flex !important; + align-items: center; +} + +.icon.m { font-size: var(--font-size-m); } +.icon.l { font-size: var(--font-size-l); } +.icon.xl { font-size: var(--font-size-xl); } + +/* ============================================ + Responsive Adjustments + ============================================ */ + +@media (max-width: 767px) { + :root { + --font-size-xxl: 36px; + --font-size-xl: 28px; + --line-height-h1: 44px; + --line-height-h2: 36px; + --space-section: 48px; + } + + .page-container { + padding: 0 var(--space-l); + } + + .hero-section .heading.hero { + padding: var(--space-xl) 0; + } + + .install-section { + padding: var(--space-xl); + } + + .install-step { + flex-direction: column; + gap: var(--space-m); + } + + .promo-cta { + padding: var(--space-xl); + } +} diff --git a/plugins/compounding-engineering/docs/index.html b/plugins/compounding-engineering/docs/index.html new file mode 100644 index 0000000..9bdfcc9 --- /dev/null +++ b/plugins/compounding-engineering/docs/index.html @@ -0,0 +1,889 @@ + + + + + + Compounding Engineering - AI-Powered Development Tools for Claude Code + + + + + + + + + + + + + + + + + + + + +
+
+
+ + + Compounding Engineering + + +
+ +
+ + Install + +
+
+ +
+ +
+
+ + Version 2.5.0 released! + +

+ AI-Powered Development Tools That Get Smarter With Every Use +

+

+ Make each unit of engineering work easier than the last. 24 specialized agents, 16 powerful commands, + 11 intelligent skills, and 2 MCP servers for code review, research, design, and workflow automation. +

+
+ + Install Plugin + + + Read the Docs + +
+
+
+ + +
+
+
+
24
+
Specialized Agents
+
+
+
16
+
Slash Commands
+
+
+
11
+
Intelligent Skills
+
+
+
2
+
MCP Servers
+
+
+
+ + +
+
+

The Compounding Engineering Philosophy

+

+ Every unit of engineering work should make subsequent units of work easier—not harder. + Our tools embody this philosophy by learning from patterns, automating repetitive tasks, + and building institutional knowledge. +

+
+
+
+
+
+

Plan

+

+ Understand the change needed and its impact before writing any code. + Use research agents to gather context and best practices. +

+
+
+
+
+
+

Delegate

+

+ Use specialized AI agents to help with implementation. + Each agent brings deep expertise in its domain. +

+
+
+
+
+
+

Assess

+

+ Run comprehensive reviews with multiple perspectives. + Security, performance, architecture—all covered. +

+
+
+
+
+
+

Codify

+

+ Document learnings and patterns for future use. + Each solved problem becomes reusable knowledge. +

+
+
+
+
+ + +
+
+

+ 24 Specialized Agents +

+

+ Each agent brings deep expertise in a specific domain. Run them individually or orchestrate + multiple agents in parallel for comprehensive analysis. +

+
+ + +
+

Review Agents (10)

+
+
+
+ kieran-rails-reviewer + Rails +
+

Super senior Rails developer with impeccable taste. Applies strict conventions for Turbo Streams, namespacing, and the "duplication over complexity" philosophy.

+ claude agent kieran-rails-reviewer +
+
+
+ dhh-rails-reviewer + Rails +
+

Reviews code from DHH's perspective. Focus on Rails conventions, simplicity, and avoiding over-engineering.

+ claude agent dhh-rails-reviewer +
+
+
+ kieran-python-reviewer + Python +
+

Python code review with strict conventions. PEP 8 compliance, type hints, and Pythonic patterns.

+ claude agent kieran-python-reviewer +
+
+
+ kieran-typescript-reviewer + TypeScript +
+

TypeScript review with focus on type safety, modern patterns, and clean architecture.

+ claude agent kieran-typescript-reviewer +
+
+
+ security-sentinel + Security +
+

Security audits and vulnerability assessments. OWASP top 10, injection attacks, authentication flaws.

+ claude agent security-sentinel +
+
+
+ performance-oracle + Performance +
+

Performance analysis and optimization recommendations. N+1 queries, caching strategies, bottleneck identification.

+ claude agent performance-oracle +
+
+
+ architecture-strategist + Architecture +
+

Analyze architectural decisions, compliance, and system design patterns.

+ claude agent architecture-strategist +
+
+
+ data-integrity-guardian + Data +
+

Database migrations and data integrity review. Schema changes, foreign keys, data consistency.

+ claude agent data-integrity-guardian +
+
+
+ pattern-recognition-specialist + Patterns +
+

Analyze code for patterns and anti-patterns. Design patterns, code smells, refactoring opportunities.

+ claude agent pattern-recognition-specialist +
+
+
+ code-simplicity-reviewer + Quality +
+

Final pass for simplicity and minimalism. Remove unnecessary complexity, improve readability.

+ claude agent code-simplicity-reviewer +
+
+
+ + +
+

Research Agents (4)

+
+
+
+ framework-docs-researcher + Research +
+

Research framework documentation and best practices. Find official guidance and community patterns.

+ claude agent framework-docs-researcher +
+
+
+ best-practices-researcher + Research +
+

Gather external best practices and examples from the community and industry standards.

+ claude agent best-practices-researcher +
+
+
+ git-history-analyzer + Git +
+

Analyze git history and code evolution. Understand how code has changed and why.

+ claude agent git-history-analyzer +
+
+
+ repo-research-analyst + Research +
+

Research repository structure and conventions. Understand project patterns and organization.

+ claude agent repo-research-analyst +
+
+
+ + +
+

Design Agents (3)

+
+
+
+ design-iterator + Design +
+

Iteratively refine UI through systematic design iterations with screenshots and feedback loops.

+ claude agent design-iterator +
+
+
+ figma-design-sync + Figma +
+

Synchronize web implementations with Figma designs. Pixel-perfect matching.

+ claude agent figma-design-sync +
+
+
+ design-implementation-reviewer + Review +
+

Verify UI implementations match Figma designs. Catch visual regressions.

+ claude agent design-implementation-reviewer +
+
+
+ + +
+

Workflow Agents (6)

+
+
+
+ bug-reproduction-validator + Bugs +
+

Systematically reproduce and validate bug reports. Create minimal reproduction cases.

+ claude agent bug-reproduction-validator +
+
+
+ pr-comment-resolver + PR +
+

Address PR comments and implement fixes. Batch process review feedback.

+ claude agent pr-comment-resolver +
+
+
+ feedback-codifier + Knowledge +
+

Codify feedback patterns into reviewer agents. Build institutional knowledge.

+ claude agent feedback-codifier +
+
+
+ lint + Quality +
+

Run linting and code quality checks on Ruby and ERB files.

+ claude agent lint +
+
+
+ spec-flow-analyzer + Testing +
+

Analyze user flows and identify gaps in specifications.

+ claude agent spec-flow-analyzer +
+
+
+ every-style-editor + Content +
+

Edit content to conform to Every's style guide.

+ claude agent every-style-editor +
+
+
+ + +
+

Documentation Agent (1)

+
+
+
+ ankane-readme-writer + Docs +
+

Create READMEs following Ankane-style template for Ruby gems. Clean, concise, comprehensive documentation that gets straight to the point.

+ claude agent ankane-readme-writer +
+
+
+
+ + +
+
+

+ 16 Powerful Commands +

+

+ Slash commands for common workflows. From code review to bug triage, + these commands automate complex multi-step processes. +

+
+ + +
+

Workflow Commands

+
+
+
+ /workflows:plan +
+

Create comprehensive implementation plans with research agents and stakeholder analysis.

+
+
+
+ /workflows:review +
+

Run exhaustive code reviews using 12+ parallel agents, ultra-thinking, and worktrees.

+
+
+
+ /workflows:work +
+

Execute work items systematically with progress tracking and validation.

+
+
+
+ /workflows:codify +
+

Document solved problems for the knowledge base. Turn learnings into reusable patterns.

+
+
+
+ + +
+

Utility Commands

+
+
+
+ /changelog +
+

Create engaging changelogs for recent merges.

+
+
+
+ /create-agent-skill +
+

Create or edit Claude Code skills with expert guidance.

+
+
+
+ /generate_command +
+

Generate new slash commands from templates.

+
+
+
+ /heal-skill +
+

Fix skill documentation issues automatically.

+
+
+
+ /plan_review +
+

Multi-agent plan review in parallel.

+
+
+
+ /prime +
+

Prime/setup command for project initialization.

+
+
+
+ /report-bug +
+

Report bugs in the plugin with structured templates.

+
+
+
+ /reproduce-bug +
+

Reproduce bugs using logs and console output.

+
+
+
+ /triage +
+

Triage and prioritize issues interactively.

+
+
+
+ /resolve_parallel +
+

Resolve TODO comments in parallel.

+
+
+
+ /resolve_pr_parallel +
+

Resolve PR comments in parallel.

+
+
+
+ /resolve_todo_parallel +
+

Resolve file-based todos in parallel.

+
+
+
+
+ + +
+
+

+ 11 Intelligent Skills +

+

+ Skills provide deep domain expertise that Claude Code can invoke on-demand. + From Ruby gem patterns to image generation. +

+
+ + +
+

Development Tools

+
+
+
+ andrew-kane-gem-writer + Ruby +
+

Write Ruby gems following Andrew Kane's patterns. Clean APIs, smart defaults, comprehensive testing.

+ skill: andrew-kane-gem-writer +
+
+
+ dhh-ruby-style + Rails +
+

Write Ruby/Rails code in DHH's 37signals style. Convention over configuration, beautiful code.

+ skill: dhh-ruby-style +
+
+
+ dspy-ruby + AI +
+

Build type-safe LLM applications with DSPy.rb. Structured prompting, optimization, providers.

+ skill: dspy-ruby +
+
+
+ frontend-design + Design +
+

Create production-grade frontend interfaces with modern CSS, responsive design, accessibility.

+ skill: frontend-design +
+
+
+ create-agent-skills + Meta +
+

Expert guidance for creating Claude Code skills. Templates, best practices, validation.

+ skill: create-agent-skills +
+
+
+ skill-creator + Meta +
+

Guide for creating effective Claude Code skills with structured workflows.

+ skill: skill-creator +
+
+
+ codify-docs + Docs +
+

Capture solved problems as categorized documentation with YAML schema.

+ skill: codify-docs +
+
+
+ + +
+

Content & Workflow

+
+
+
+ every-style-editor + Content +
+

Review copy for Every's style guide compliance.

+ skill: every-style-editor +
+
+
+ file-todos + Workflow +
+

File-based todo tracking system with priorities and status.

+ skill: file-todos +
+
+
+ git-worktree + Git +
+

Manage Git worktrees for parallel development on multiple branches.

+ skill: git-worktree +
+
+
+ + +
+

Image Generation

+
+
+
+ gemini-imagegen + AI Images +
+

+ Generate and edit images using Google's Gemini API. Text-to-image, image editing, + multi-turn refinement, and composition from up to 14 reference images. +

+
+
+ Text-to-image generation +
+
+ Image editing & manipulation +
+
+ Multi-turn refinement +
+
+ Multiple reference images (up to 14) +
+
+ Google Search grounding (Pro) +
+
+ skill: gemini-imagegen +

Requires: GEMINI_API_KEY environment variable

+
+
+
+
+ + +
+
+

+ 2 MCP Servers +

+

+ Model Context Protocol servers extend Claude Code's capabilities with + browser automation and framework documentation lookup. +

+
+ +
+
+
+ + Playwright +
+

Browser automation for testing, screenshots, and web interactions.

+
+

Tools Provided:

+
    +
  • browser_navigate - Navigate to URLs
    • +
  • browser_take_screenshot - Take screenshots
    • +
  • browser_click - Click elements
    • +
  • browser_fill_form - Fill form fields
    • +
  • browser_snapshot - Get accessibility snapshot
    • +
  • browser_evaluate - Execute JavaScript
    • +
+
+
+
+
+ + Context7 +
+

Framework documentation lookup for 100+ frameworks.

+
+

Tools Provided:

+
    +
  • resolve-library-id - Find library ID
    • +
  • get-library-docs - Get documentation
    • +
+

Supports: Rails, React, Next.js, Vue, Django, Laravel, and 100+ more

+
+
+
+
+ + +
+
+

Get Started in Seconds

+

+ Install the plugin and start using AI-powered development tools immediately. +

+
+ +
+
+
1
+
+

Add the Marketplace

+
+ 
claude /plugin marketplace add https://github.com/EveryInc/every-marketplace
+
+
+
+
+
2
+
+

Install the Plugin

+
+ 
claude /plugin install compounding-engineering
+
+
+
+
+
3
+
+

Start Using

+
+ 
# Run a code review
+/workflows:review PR#123
+
+# Use an agent
+claude agent kieran-rails-reviewer
+
+# Invoke a skill
+skill: gemini-imagegen
+
+
+
+
+
+ + +
+
+

Frequently Asked Questions

+
+
+
+ +

What is Compounding Engineering?

+ + +
+

+ Compounding Engineering is a philosophy that every unit of engineering work should make subsequent + units easier—not harder. This plugin embodies that philosophy with tools that learn from patterns, + automate repetitive tasks, and build institutional knowledge. +

+
+
+
+ +

How do agents differ from skills?

+ + +
+

+ Agents are specialized personas that can be invoked to perform specific tasks + (e.g., code review, research). They're called with claude agent [name]. +

+

+ Skills provide domain expertise that Claude Code can use on-demand. They include + reference materials, templates, and workflows. They're invoked with skill: [name]. +

+
+
+
+ +

Why aren't MCP servers loading automatically?

+ + +
+

+ This is a known issue. As a workaround, manually add the MCP servers to your + .claude/settings.json file. See the README for the exact configuration. +

+
+
+
+ +

Can I use this with languages other than Ruby/Rails?

+ + +
+

+ Yes! While many agents are specialized for Rails, we also have Python and TypeScript reviewers. + The workflow commands, research agents, and skills like gemini-imagegen work with any language. +

+
+
+
+ +

How do I create my own agents or skills?

+ + +
+

+ Use the /create-agent-skill command or the create-agent-skills skill + for expert guidance. The skill includes templates, best practices, and validation workflows. +

+
+
+
+
+ + +
+
+

Start Building Smarter Today

+

+ Join developers who are making each engineering task easier than the last. +

+
+ + Install Plugin + + + View on GitHub + +
+
+
+
+ + +
+ + + diff --git a/plugins/compounding-engineering/docs/js/main.js b/plugins/compounding-engineering/docs/js/main.js new file mode 100644 index 0000000..bc71913 --- /dev/null +++ b/plugins/compounding-engineering/docs/js/main.js @@ -0,0 +1,225 @@ +/** + * Compounding Engineering Documentation + * Main JavaScript functionality + */ + +document.addEventListener('DOMContentLoaded', () => { + initMobileNav(); + initSmoothScroll(); + initCopyCode(); + initThemeToggle(); +}); + +/** + * Mobile Navigation Toggle + */ +function initMobileNav() { + const mobileToggle = document.querySelector('[data-mobile-toggle]'); + const navigation = document.querySelector('[data-navigation]'); + + if (!mobileToggle || !navigation) return; + + mobileToggle.addEventListener('click', () => { + navigation.classList.toggle('open'); + mobileToggle.classList.toggle('active'); + + // Update aria-expanded + const isOpen = navigation.classList.contains('open'); + mobileToggle.setAttribute('aria-expanded', isOpen); + }); + + // Close menu when clicking outside + document.addEventListener('click', (event) => { + if (!mobileToggle.contains(event.target) && !navigation.contains(event.target)) { + navigation.classList.remove('open'); + mobileToggle.classList.remove('active'); + mobileToggle.setAttribute('aria-expanded', 'false'); + } + }); + + // Close menu when clicking a nav link + navigation.querySelectorAll('.nav-link').forEach(link => { + link.addEventListener('click', () => { + navigation.classList.remove('open'); + mobileToggle.classList.remove('active'); + mobileToggle.setAttribute('aria-expanded', 'false'); + }); + }); +} + +/** + * Smooth Scroll for Anchor Links + */ +function initSmoothScroll() { + document.querySelectorAll('a[href^="#"]').forEach(anchor => { + anchor.addEventListener('click', function(e) { + const targetId = this.getAttribute('href'); + if (targetId === '#') return; + + const targetElement = document.querySelector(targetId); + if (!targetElement) return; + + e.preventDefault(); + + const navHeight = document.querySelector('.nav-container')?.offsetHeight || 0; + const targetPosition = targetElement.getBoundingClientRect().top + window.pageYOffset - navHeight - 24; + + window.scrollTo({ + top: targetPosition, + behavior: 'smooth' + }); + + // Update URL without jumping + history.pushState(null, null, targetId); + }); + }); +} + +/** + * Copy Code Functionality + */ +function initCopyCode() { + document.querySelectorAll('.card-code-block').forEach(block => { + // Create copy button + const copyBtn = document.createElement('button'); + copyBtn.className = 'copy-btn'; + copyBtn.innerHTML = ''; + copyBtn.setAttribute('aria-label', 'Copy code'); + copyBtn.setAttribute('title', 'Copy to clipboard'); + + // Style the button + copyBtn.style.cssText = ` + position: absolute; + top: 8px; + right: 8px; + padding: 6px 10px; + background: rgba(255, 255, 255, 0.1); + border: none; + border-radius: 6px; + color: #94a3b8; + cursor: pointer; + opacity: 0; + transition: all 0.2s ease; + font-size: 14px; + `; + + // Make parent relative for positioning + block.style.position = 'relative'; + block.appendChild(copyBtn); + + // Show/hide on hover + block.addEventListener('mouseenter', () => { + copyBtn.style.opacity = '1'; + }); + + block.addEventListener('mouseleave', () => { + copyBtn.style.opacity = '0'; + }); + + // Copy functionality + copyBtn.addEventListener('click', async () => { + const code = block.querySelector('code'); + if (!code) return; + + try { + await navigator.clipboard.writeText(code.textContent); + copyBtn.innerHTML = ''; + copyBtn.style.color = '#34d399'; + + setTimeout(() => { + copyBtn.innerHTML = ''; + copyBtn.style.color = '#94a3b8'; + }, 2000); + } catch (err) { + console.error('Failed to copy:', err); + copyBtn.innerHTML = ''; + copyBtn.style.color = '#f87171'; + + setTimeout(() => { + copyBtn.innerHTML = ''; + copyBtn.style.color = '#94a3b8'; + }, 2000); + } + }); + }); +} + +/** + * Theme Toggle (Light/Dark) + */ +function initThemeToggle() { + // Check for saved theme preference or default to dark + const savedTheme = localStorage.getItem('theme') || 'dark'; + document.documentElement.className = `theme-${savedTheme}`; + + // Create theme toggle button if it doesn't exist + const existingToggle = document.querySelector('[data-theme-toggle]'); + if (existingToggle) { + existingToggle.addEventListener('click', toggleTheme); + updateThemeToggleIcon(existingToggle, savedTheme); + } +} + +function toggleTheme() { + const html = document.documentElement; + const currentTheme = html.classList.contains('theme-dark') ? 'dark' : 'light'; + const newTheme = currentTheme === 'dark' ? 'light' : 'dark'; + + html.className = `theme-${newTheme}`; + localStorage.setItem('theme', newTheme); + + const toggle = document.querySelector('[data-theme-toggle]'); + if (toggle) { + updateThemeToggleIcon(toggle, newTheme); + } +} + +function updateThemeToggleIcon(toggle, theme) { + const icon = toggle.querySelector('i'); + if (icon) { + icon.className = theme === 'dark' ? 'fa-solid fa-sun' : 'fa-solid fa-moon'; + } +} + +/** + * Intersection Observer for Animation on Scroll + */ +function initScrollAnimations() { + const observerOptions = { + threshold: 0.1, + rootMargin: '0px 0px -50px 0px' + }; + + const observer = new IntersectionObserver((entries) => { + entries.forEach(entry => { + if (entry.isIntersecting) { + entry.target.classList.add('visible'); + observer.unobserve(entry.target); + } + }); + }, observerOptions); + + document.querySelectorAll('.agent-card, .command-card, .skill-card, .mcp-card, .stat-card').forEach(card => { + card.style.opacity = '0'; + card.style.transform = 'translateY(20px)'; + card.style.transition = 'opacity 0.5s ease, transform 0.5s ease'; + observer.observe(card); + }); +} + +// Add visible class styles +const style = document.createElement('style'); +style.textContent = ` + .agent-card.visible, + .command-card.visible, + .skill-card.visible, + .mcp-card.visible, + .stat-card.visible { + opacity: 1 !important; + transform: translateY(0) !important; + } +`; +document.head.appendChild(style); + +// Initialize scroll animations after a short delay +setTimeout(initScrollAnimations, 100); diff --git a/plugins/compounding-engineering/docs/pages/getting-started.html b/plugins/compounding-engineering/docs/pages/getting-started.html new file mode 100644 index 0000000..f844fc0 --- /dev/null +++ b/plugins/compounding-engineering/docs/pages/getting-started.html @@ -0,0 +1,597 @@ + + + + + + Getting Started - Compounding Engineering + + + + + + + + + + + +
+
+ + + + +
+
+ + +
+ +
+

Getting Started with Compounding Engineering

+

+ This guide will help you install, configure, and start using the Compounding Engineering plugin + for Claude Code. In about 5 minutes, you'll have access to 24 specialized agents, 16 commands, + 11 skills, and 2 MCP servers. +

+ + +
+

Installation

+ +

Prerequisites

+
    +
  • Claude Code installed and configured
    • +
  • A GitHub account (for marketplace access)
    • +
  • Node.js 18+ (for MCP servers)
    • +
+ +

Step 1: Add the Marketplace

+

First, add the Every Marketplace to your Claude Code installation:

+
+ 
claude /plugin marketplace add https://github.com/EveryInc/every-marketplace
+
+ +

Step 2: Install the Plugin

+

Install the compounding-engineering plugin from the marketplace:

+
+ 
claude /plugin install compounding-engineering
+
+ +

Step 3: Verify Installation

+

Verify the plugin is installed correctly:

+
+ 
claude /plugin list
+
+

You should see compounding-engineering in the list of installed plugins.

+ +
+
+
+

Known Issue: MCP Servers

+

+ The bundled MCP servers (Playwright and Context7) may not load automatically. + See the MCP Configuration section for the workaround. +

+
+
+
+ + +
+

Quick Start

+ +

Here are the most common ways to use the plugin:

+ +

Run a Code Review

+

The /workflows:review command runs a comprehensive code review using multiple agents in parallel:

+
+ 
# Review a PR by number
+/workflows:review 123
+
+# Review the current branch
+/workflows:review
+
+# Review a specific branch
+/workflows:review feature/my-feature
+
+ +

Use a Specialized Agent

+

Invoke agents directly for specific tasks:

+
+ 
# Rails code review with Kieran's conventions
+claude agent kieran-rails-reviewer "Review the UserController"
+
+# Security audit
+claude agent security-sentinel "Audit authentication flow"
+
+# Research best practices
+claude agent best-practices-researcher "Find pagination patterns for Rails"
+
+ +

Invoke a Skill

+

Skills provide domain expertise on demand:

+
+ 
# Generate images with Gemini
+skill: gemini-imagegen
+
+# Write Ruby in DHH's style
+skill: dhh-ruby-style
+
+# Create a new Claude Code skill
+skill: create-agent-skills
+
+
+ + +
+

Configuration

+ +

MCP Server Configuration

+

+ If MCP servers don't auto-load, add them manually to your .claude/settings.json: +

+
+ 
{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+      "env": {}
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}
+
+ +

Environment Variables

+

Some skills require environment variables:

+ + + + + + + + + + + + + + + +
VariableRequired ForDescription
GEMINI_API_KEYgemini-imagegenGoogle Gemini API key for image generation
+
+ + +
+

The Compounding Engineering Philosophy

+ +
+ Every unit of engineering work should make subsequent units of work easier—not harder. +
+ +

This philosophy manifests in four key practices:

+ +
+
+
+

Plan

+

+ Understand the change needed and its impact before writing code. + Use research agents to gather context, best practices, and examples. +

+
+
+
+

Delegate

+

+ Use specialized AI agents to help with implementation. + Each agent brings deep expertise in its domain. +

+
+
+
+

Assess

+

+ Run comprehensive reviews with multiple perspectives. + Security, performance, architecture—all covered by specialized agents. +

+
+
+
+

Codify

+

+ Document learnings and patterns for future use. + Each solved problem becomes reusable knowledge. +

+
+
+
+ + +
+

Using Agents

+ +

+ Agents are specialized personas that can be invoked to perform specific tasks. + They're designed to bring deep expertise in their domain. +

+ +

Invoking Agents

+
+ 
# Basic syntax
+claude agent [agent-name] "[optional message]"
+
+# Examples
+claude agent kieran-rails-reviewer
+claude agent security-sentinel "Audit the payment flow"
+claude agent git-history-analyzer "Show changes to user model"
+
+ +

Agent Categories

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CategoryCountPurpose
Review10Code review, security audits, performance analysis
Research4Best practices, documentation, git history
Design3UI iteration, Figma sync, design review
Workflow6Bug reproduction, PR resolution, linting
Docs1README generation
+ +

+ + View All Agents + +

+
+ + +
+

Using Commands

+ +

+ Slash commands automate complex multi-step workflows. They orchestrate + multiple agents, tools, and processes into a single command. +

+ +

Running Commands

+
+ 
# Workflow commands (prefix: /workflows:)
+/workflows:plan
+/workflows:review 123
+/workflows:work
+/workflows:codify
+
+# Utility commands
+/changelog
+/triage
+/reproduce-bug
+
+ +

The Review Workflow

+

The /workflows:review command is the most comprehensive. It:

+
    +
  1. Detects the review target (PR, branch, or current changes)
    2. +
  2. Sets up a git worktree for isolated analysis
    3. +
  3. Runs 10+ review agents in parallel
    4. +
  4. Synthesizes findings by severity (P1/P2/P3)
    5. +
  5. Creates structured todo files for each finding
    6. +
  6. Generates a summary report
    7. +
+ +

+ + View All Commands + +

+
+ + +
+

Using Skills

+ +

+ Skills provide domain expertise that Claude Code can invoke on-demand. + Unlike agents (which are personas), skills are bodies of knowledge with + templates, references, and workflows. +

+ +

Invoking Skills

+
+ 
# In your prompt, reference the skill
+skill: gemini-imagegen
+
+# Or ask Claude to use it
+"Use the dhh-ruby-style skill to refactor this code"
+
+ +

Skill Structure

+

Skills typically contain:

+
    +
  • SKILL.md - Main documentation and instructions
    • +
  • references/ - Supporting documentation
    • +
  • templates/ - Code templates and patterns
    • +
  • workflows/ - Step-by-step procedures
    • +
  • scripts/ - Executable scripts (if needed)
    • +
+ +

+ + View All Skills + +

+
+ + +
+

Code Review Workflow Guide

+ +

+ The code review workflow is the heart of Compounding Engineering. + Here's how to get the most out of it. +

+ +

Basic Review

+
+ 
# Review a PR
+/workflows:review 123
+
+# Review current branch
+/workflows:review
+
+ +

Understanding Findings

+

Findings are categorized by severity:

+
    +
  • P1 Critical - Blocks merge. Security vulnerabilities, data corruption risks, breaking changes.
    • +
  • P2 Important - Should fix. Performance issues, architectural concerns, reliability problems.
    • +
  • P3 Nice-to-Have - Enhancements. Minor improvements, cleanup, documentation.
    • +
+ +

Working with Todo Files

+

Review findings are stored as todo files in the todos/ directory:

+
+ 
# List all pending todos
+ls todos/*-pending-*.md
+
+# Triage findings
+/triage
+
+# Resolve todos in parallel
+/resolve_todo_parallel
+
+
+ + +
+

Creating Custom Agents

+ +

+ You can create custom agents tailored to your team's needs. + Agents are defined as markdown files with YAML frontmatter. +

+ +

Agent File Structure

+
+ 
---
+name: my-custom-agent
+description: Brief description of what this agent does
+---
+
+# Agent Instructions
+
+You are [role description].
+
+## Your Responsibilities
+1. First responsibility
+2. Second responsibility
+
+## Guidelines
+- Guideline one
+- Guideline two
+
+ +

Agent Location

+

Place custom agents in:

+
    +
  • .claude/agents/ - Project-specific agents
    • +
  • ~/.claude/agents/ - User-wide agents
    • +
+ +
+
+
+

Use the Command

+

+ The easiest way to create agents is with the /create-agent-skill command + or the create-agent-skills skill. +

+
+
+
+ + +
+

Creating Custom Skills

+ +

+ Skills are more complex than agents. They can include references, + templates, workflows, and scripts. +

+ +

Skill Directory Structure

+
+ 
my-skill/
+  SKILL.md           # Main skill file (required)
+  references/        # Supporting documentation
+    concept-one.md
+    concept-two.md
+  templates/         # Code templates
+    basic-template.md
+  workflows/         # Step-by-step procedures
+    workflow-one.md
+  scripts/           # Executable scripts
+    helper.py
+
+ +

SKILL.md Format

+
+ 
---
+name: my-skill
+description: Brief description shown when skill is invoked
+---
+
+# Skill Title
+
+Detailed instructions for using this skill.
+
+## Quick Start
+...
+
+## Reference Materials
+The skill includes references in the `references/` directory.
+
+## Templates
+Use templates from the `templates/` directory.
+
+ +
+
+
+

Expert Guidance

+

+ Use skill: create-agent-skills for comprehensive guidance + on creating effective skills, including best practices and validation. +

+
+
+
+ + + +
+
+
+ + + + + From 53ba12f0caac0cf2ba878439aca975df98a05d56 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Nov 2025 16:03:33 +0000 Subject: [PATCH 02/25] docs: Add complete reference pages and enhanced philosophy section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add agents.html with full documentation for all 24 agents - Add commands.html with full documentation for all 16 commands - Add skills.html with full documentation for all 11 skills - Add mcp-servers.html with Playwright and Context7 documentation - Enhance landing page philosophy section with four pillars and compounding effect timeline - Add CSS styles for philosophy section components πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../docs/css/style.css | 183 +++++ .../compounding-engineering/docs/index.html | 136 +++- .../docs/pages/agents.html | 682 ++++++++++++++++++ .../docs/pages/commands.html | 518 +++++++++++++ .../docs/pages/mcp-servers.html | 400 ++++++++++ .../docs/pages/skills.html | 591 +++++++++++++++ 6 files changed, 2477 insertions(+), 33 deletions(-) create mode 100644 plugins/compounding-engineering/docs/pages/agents.html create mode 100644 plugins/compounding-engineering/docs/pages/commands.html create mode 100644 plugins/compounding-engineering/docs/pages/mcp-servers.html create mode 100644 plugins/compounding-engineering/docs/pages/skills.html diff --git a/plugins/compounding-engineering/docs/css/style.css b/plugins/compounding-engineering/docs/css/style.css index 677b933..1d54a46 100644 --- a/plugins/compounding-engineering/docs/css/style.css +++ b/plugins/compounding-engineering/docs/css/style.css @@ -1216,3 +1216,186 @@ section { padding: var(--space-xl); } } + +/* ============================================ + Philosophy Section (Enhanced) + ============================================ */ + +.philosophy-section { + padding: var(--space-section) 0; +} + +.philosophy-quote { + max-width: 800px; + margin: 0 auto var(--space-xxl); + text-align: center; +} + +.philosophy-quote blockquote { + font-size: var(--font-size-l); + font-style: italic; + color: var(--color-text-secondary); + line-height: 1.6; + margin: 0; + padding: var(--space-xl); + background: linear-gradient(135deg, var(--color-accent-lighter), transparent); + border-left: 4px solid var(--color-accent); + border-radius: var(--radius-m); +} + +/* Philosophy Pillars */ +.philosophy-pillars { + display: grid; + grid-template-columns: 1fr; + gap: var(--space-xl); + margin-bottom: var(--space-xxl); +} + +@media (min-width: 768px) { + .philosophy-pillars { + grid-template-columns: repeat(2, 1fr); + } +} + +.pillar { + display: flex; + gap: var(--space-l); + padding: var(--space-xl); + background-color: var(--color-surface); + border-radius: var(--radius-l); + border: 1px solid var(--color-border); + transition: all 0.3s ease; +} + +.pillar:hover { + border-color: var(--color-accent); + transform: translateY(-2px); +} + +.pillar-icon { + flex-shrink: 0; + width: 60px; + height: 60px; + display: flex; + align-items: center; + justify-content: center; + background-color: var(--color-accent-light); + border-radius: var(--radius-m); + font-size: var(--font-size-xl); + color: var(--color-accent); +} + +.pillar-content h3 { + margin: 0 0 var(--space-xs) 0; + font-size: var(--font-size-l); + color: var(--color-text-primary); +} + +.pillar-tagline { + margin: 0 0 var(--space-m) 0; + font-size: var(--font-size-s); + color: var(--color-accent); + font-weight: 500; +} + +.pillar-description { + margin: 0 0 var(--space-m) 0; + font-size: var(--font-size-s); + color: var(--color-text-secondary); + line-height: 1.6; +} + +.pillar-tools { + display: flex; + flex-wrap: wrap; + gap: var(--space-xs); +} + +.tool-tag { + font-family: var(--font-mono); + font-size: var(--font-size-xs); + padding: 2px 8px; + background-color: var(--color-surface-hover); + color: var(--color-text-secondary); + border-radius: var(--radius-xs); + border: 1px solid var(--color-border); +} + +/* Compound Effect Timeline */ +.compound-effect { + background-color: var(--color-surface); + border-radius: var(--radius-l); + padding: var(--space-xl); + border: 1px solid var(--color-border); +} + +.compound-effect h3 { + text-align: center; + margin: 0 0 var(--space-xl) 0; + display: flex; + align-items: center; + justify-content: center; + gap: var(--space-s); +} + +.compound-grid { + display: flex; + flex-wrap: wrap; + align-items: center; + justify-content: center; + gap: var(--space-m); +} + +.compound-item { + text-align: center; + padding: var(--space-l); + background-color: var(--color-background); + border-radius: var(--radius-m); + border: 1px solid var(--color-border); + min-width: 140px; +} + +.compound-item.highlight { + background: linear-gradient(135deg, var(--color-accent-light), var(--color-surface)); + border-color: var(--color-accent); +} + +.compound-number { + font-size: var(--font-size-s); + font-weight: 600; + color: var(--color-accent); + margin-bottom: var(--space-xs); +} + +.compound-text { + font-size: var(--font-size-xs); + color: var(--color-text-secondary); +} + +.compound-arrow { + color: var(--color-text-tertiary); + font-size: var(--font-size-l); +} + +@media (max-width: 767px) { + .pillar { + flex-direction: column; + text-align: center; + } + + .pillar-icon { + margin: 0 auto; + } + + .pillar-tools { + justify-content: center; + } + + .compound-arrow { + transform: rotate(90deg); + } + + .compound-grid { + flex-direction: column; + } +} diff --git a/plugins/compounding-engineering/docs/index.html b/plugins/compounding-engineering/docs/index.html index 9bdfcc9..3ef5dd0 100644 --- a/plugins/compounding-engineering/docs/index.html +++ b/plugins/compounding-engineering/docs/index.html @@ -100,54 +100,124 @@ -
+

The Compounding Engineering Philosophy

-

+

Every unit of engineering work should make subsequent units of work easier—not harder. - Our tools embody this philosophy by learning from patterns, automating repetitive tasks, - and building institutional knowledge.

-
-
-
-
-

Plan

-

- Understand the change needed and its impact before writing any code. - Use research agents to gather context and best practices. + + +

+
+ "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." +
+
+ + +
+
+
+
+

Plan

+

Understand before you build

+

+ 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 3 research agents in parallel to create comprehensive implementation plans.

+
+ framework-docs-researcher + best-practices-researcher + repo-research-analyst + git-history-analyzer +
-
-
-
-

Delegate

-

- Use specialized AI agents to help with implementation. - Each agent brings deep expertise in its domain. + +

+
+
+

Delegate

+

Leverage specialized expertise

+

+ 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.

+
+ 24 specialized agents + /workflows:work + dhh-ruby-style skill + git-worktree skill +
-
-
-
-

Assess

-

- Run comprehensive reviews with multiple perspectives. - Security, performance, architecture—all covered. + +

+
+
+

Assess

+

Multiple perspectives, comprehensive coverage

+

+ The /workflows:review command launches 12+ 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.

+
+ security-sentinel + performance-oracle + architecture-strategist + data-integrity-guardian +
-
-
-
-

Codify

-

- Document learnings and patterns for future use. - Each solved problem becomes reusable knowledge. + +

+
+
+

Codify

+

Turn solutions into knowledge

+

+ Every solved problem should teach the system. The /workflows:codify command + captures solutions as searchable documentation. The feedback-codifier agent + extracts patterns from code reviews to improve future reviews.

+
+ /workflows:codify + codify-docs skill + feedback-codifier + file-todos skill +
+
+
+
+ + +
+

The Compounding Effect

+
+
+
Day 1
+
Install plugin, run first review
+
+
+
+
Week 1
+
Patterns documented, todos organized
+
+
+
+
Month 1
+
Knowledge base growing, reviews faster
+
+
+
+
Ongoing
+
Each task easier than the last
diff --git a/plugins/compounding-engineering/docs/pages/agents.html b/plugins/compounding-engineering/docs/pages/agents.html new file mode 100644 index 0000000..ec51834 --- /dev/null +++ b/plugins/compounding-engineering/docs/pages/agents.html @@ -0,0 +1,682 @@ + + + + + + Agent Reference - Compounding Engineering + + + + + + + + + + +
+
+ + +
+
+ + +
+ +
+

Agent Reference

+

+ Complete documentation for all 24 specialized AI agents. Each agent brings deep expertise + in a specific domain and can be invoked individually or orchestrated together. +

+ +
+

How to Use Agents

+
+ 
# Basic invocation
+claude agent [agent-name]
+
+# With a specific message
+claude agent [agent-name] "Your message here"
+
+# Examples
+claude agent kieran-rails-reviewer
+claude agent security-sentinel "Audit the payment flow"
+
+
+ + +
+

Review Agents (10)

+

Code review agents that examine changes from multiple perspectives: conventions, security, performance, architecture, and quality.

+ +
+
+

kieran-rails-reviewer

+ Rails +
+

+ 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. +

+

Key Principles

+
    +
  • Existing Code Modifications - Very strict. Added complexity needs strong justification.
    • +
  • New Code - Pragmatic. If it's isolated and works, it's acceptable.
    • +
  • Turbo Streams - Simple turbo streams MUST be inline arrays in controllers.
    • +
  • Testing as Quality - Hard-to-test code = poor structure that needs refactoring.
    • +
  • Naming (5-Second Rule) - Must understand what a view/component does in 5 seconds from its name.
    • +
  • Namespacing - Always use class Module::ClassName pattern.
    • +
  • Duplication > Complexity - Simple duplicated code is better than complex DRY abstractions.
    • +
+
+ 
claude agent kieran-rails-reviewer "Review the UserController"
+
+
+ +
+
+

dhh-rails-reviewer

+ Rails +
+

+ Brutally honest Rails code review from David Heinemeier Hansson's perspective. + Focuses on Rails conventions, simplicity, and avoiding over-engineering. +

+

Key Focus Areas

+
    +
  • Identifies deviations from Rails conventions
    • +
  • Spots JavaScript framework patterns infiltrating Rails
    • +
  • Tears apart unnecessary abstractions
    • +
  • Challenges overengineering and microservices mentality
    • +
+
+ 
claude agent dhh-rails-reviewer
+
+
+ +
+
+

kieran-python-reviewer

+ Python +
+

+ Reviews Python code with an exceptionally high quality bar. Enforces type hints, Pythonic patterns, + and modern Python 3.10+ syntax. +

+

Key Focus Areas

+
    +
  • Type hints for all functions
    • +
  • Pythonic patterns and idioms
    • +
  • Modern Python syntax
    • +
  • Import organization
    • +
  • Module extraction signals
    • +
+
+ 
claude agent kieran-python-reviewer
+
+
+ +
+
+

kieran-typescript-reviewer

+ TypeScript +
+

+ Reviews TypeScript code with an exceptionally high quality bar. Enforces type safety, + modern patterns, and clean architecture. +

+

Key Focus Areas

+
    +
  • No any without justification
    • +
  • Component/module extraction signals
    • +
  • Import organization
    • +
  • Modern TypeScript patterns
    • +
  • Testability assessment
    • +
+
+ 
claude agent kieran-typescript-reviewer
+
+
+ +
+
+

security-sentinel

+ Security +
+

+ Performs security audits, vulnerability assessments, and OWASP compliance checks. + Essential for any code handling authentication, payments, or sensitive data. +

+

Security Checks

+
    +
  • Input validation analysis
    • +
  • SQL injection risk assessment
    • +
  • XSS vulnerability detection
    • +
  • Authentication/authorization audit
    • +
  • Sensitive data exposure scanning
    • +
  • OWASP Top 10 compliance
    • +
  • Hardcoded secrets search
    • +
+
+ 
claude agent security-sentinel "Audit the payment flow"
+
+
+ +
+
+

performance-oracle

+ Performance +
+

+ Analyzes code for performance issues, bottlenecks, and scalability concerns. + Projects performance at 10x, 100x, and 1000x scale. +

+

Analysis Areas

+
    +
  • Algorithmic complexity (Big O notation)
    • +
  • N+1 query pattern detection
    • +
  • Proper index usage verification
    • +
  • Memory management review
    • +
  • Caching opportunity identification
    • +
  • Network usage optimization
    • +
  • Frontend bundle impact
    • +
+
+ 
claude agent performance-oracle
+
+
+ +
+
+

architecture-strategist

+ Architecture +
+

+ Analyzes code changes from an architectural perspective. Evaluates system structure, + SOLID principles, and API contracts. +

+

Analysis Areas

+
    +
  • Overall system structure understanding
    • +
  • Change context within architecture
    • +
  • Architectural violation identification
    • +
  • SOLID principles compliance
    • +
  • Microservice boundary assessment
    • +
  • API contract evaluation
    • +
+
+ 
claude agent architecture-strategist
+
+
+ +
+
+

data-integrity-guardian

+ Data +
+

+ Reviews database migrations, data models, and data persistence code. + Ensures data safety and privacy compliance. +

+

Review Areas

+
    +
  • Migration safety and reversibility
    • +
  • Data constraint validation
    • +
  • Transaction boundary review
    • +
  • Referential integrity preservation
    • +
  • Privacy compliance (GDPR, CCPA)
    • +
  • Data corruption scenario checking
    • +
+
+ 
claude agent data-integrity-guardian
+
+
+ +
+
+

pattern-recognition-specialist

+ Patterns +
+

+ Analyzes code for design patterns, anti-patterns, naming conventions, and duplication. + Uses tools like jscpd for duplication detection. +

+

Detection Areas

+
    +
  • Design patterns (Factory, Singleton, Observer, etc.)
    • +
  • Anti-patterns and code smells
    • +
  • TODO/FIXME comments
    • +
  • God objects and circular dependencies
    • +
  • Naming consistency
    • +
  • Code duplication
    • +
+
+ 
claude agent pattern-recognition-specialist
+
+
+ +
+
+

code-simplicity-reviewer

+ Quality +
+

+ Ensures code is as simple and minimal as possible. Applies YAGNI rigorously + and challenges unnecessary abstractions. +

+

Simplification Checks

+
    +
  • Analyze every line for necessity
    • +
  • Simplify complex logic
    • +
  • Remove redundancy and duplication
    • +
  • Challenge abstractions
    • +
  • Optimize for readability
    • +
  • Eliminate premature generalization
    • +
+
+ 
claude agent code-simplicity-reviewer
+
+
+
+ + +
+

Research Agents (4)

+

Research agents that gather information from documentation, repositories, and git history to inform development decisions.

+ +
+
+

framework-docs-researcher

+ Research +
+

+ Gathers comprehensive documentation and best practices for frameworks, libraries, or dependencies. +

+

Capabilities

+
    +
  • Fetch official framework and library documentation
    • +
  • Identify version-specific constraints and deprecations
    • +
  • Search GitHub for real-world usage examples
    • +
  • Analyze gem/library source code using bundle show
    • +
  • Synthesize findings with practical examples
    • +
+
+ 
claude agent framework-docs-researcher "Research Hotwire Turbo patterns"
+
+
+ +
+
+

best-practices-researcher

+ Research +
+

+ Researches and gathers external best practices, documentation, and examples for any technology. +

+

Capabilities

+
    +
  • Leverage multiple sources (Context7 MCP, web search, GitHub)
    • +
  • Evaluate information quality and recency
    • +
  • Synthesize into actionable guidance
    • +
  • Provide code examples and templates
    • +
  • Research issue templates and community engagement
    • +
+
+ 
claude agent best-practices-researcher "Find pagination patterns"
+
+
+ +
+
+

git-history-analyzer

+ Git +
+

+ Archaeological analysis of code repositories to understand evolution and patterns. +

+

Analysis Techniques

+
    +
  • Trace file evolution using git log --follow
    • +
  • Determine code origins using git blame -w -C -C -C
    • +
  • Identify patterns from commit history
    • +
  • Map key contributors and expertise areas
    • +
  • Extract historical patterns of issues and fixes
    • +
+
+ 
claude agent git-history-analyzer "Analyze changes to User model"
+
+
+ +
+
+

repo-research-analyst

+ Research +
+

+ Conducts thorough research on repository structure, documentation, and patterns. +

+

Analysis Areas

+
    +
  • Architecture and documentation files (ARCHITECTURE.md, README.md, CLAUDE.md)
    • +
  • GitHub issues for patterns and conventions
    • +
  • Issue/PR templates and guidelines
    • +
  • Implementation patterns using ast-grep or rg
    • +
  • Project-specific conventions
    • +
+
+ 
claude agent repo-research-analyst
+
+
+
+ + +
+

Workflow Agents (6)

+

Workflow agents that automate common development tasks like bug reproduction, PR resolution, and linting.

+ +
+
+

bug-reproduction-validator

+ Bugs +
+

+ Verifies whether bug reports are actual bugs through systematic reproduction. + Classifies bugs and provides severity assessment. +

+

Classification Types

+
    +
  • Confirmed - Bug reproduced successfully
    • +
  • Cannot Reproduce - Unable to reproduce
    • +
  • Not a Bug - Expected behavior
    • +
  • Environmental - Environment-specific issue
    • +
  • Data - Data-related issue
    • +
  • User Error - User misunderstanding
    • +
+
+ 
claude agent bug-reproduction-validator
+
+
+ +
+
+

pr-comment-resolver

+ PR +
+

+ Addresses code review comments by implementing requested changes and reporting resolutions. +

+

Workflow

+
    +
  • Analyze code review comments
    • +
  • Plan the resolution before implementation
    • +
  • Implement requested modifications
    • +
  • Verify resolution doesn't break functionality
    • +
  • Provide clear resolution reports
    • +
+
+ 
claude agent pr-comment-resolver
+
+
+ +
+
+

feedback-codifier

+ Knowledge +
+

+ Analyzes code review feedback to extract patterns and update reviewer configurations. + Uses Opus model for deep analysis. +

+

Capabilities

+
    +
  • Extract core patterns from code reviews
    • +
  • Categorize by type (structure, testing, security, performance)
    • +
  • Formulate actionable guidelines
    • +
  • Update existing reviewer agents with new standards
    • +
+
+ 
claude agent feedback-codifier
+
+
+ +
+
+

lint

+ Quality +
+

+ Runs linting and code quality checks on Ruby and ERB files. + Uses Haiku model for efficiency. +

+

Tools Run

+
    +
  • bundle exec standardrb - Ruby file checking/fixing
    • +
  • bundle exec erblint --lint-all - ERB templates
    • +
  • bin/brakeman - Security scanning
    • +
+
+ 
claude agent lint
+
+
+ +
+
+

spec-flow-analyzer

+ Testing +
+

+ Analyzes specifications and plans for user flows and gap identification. + Uses Sonnet model for analysis. +

+

Analysis Areas

+
    +
  • Map all possible user flows and permutations
    • +
  • Identify gaps, ambiguities, and missing specifications
    • +
  • Consider different user types, roles, permissions
    • +
  • Analyze error states and edge cases
    • +
  • Generate critical questions requiring clarification
    • +
+
+ 
claude agent spec-flow-analyzer
+
+
+ +
+
+

every-style-editor

+ Content +
+

+ Reviews and edits text content to conform to Every's specific style guide. +

+

Style Checks

+
    +
  • Title case in headlines, sentence case elsewhere
    • +
  • Company singular/plural usage
    • +
  • Remove overused words (actually, very, just)
    • +
  • Enforce active voice
    • +
  • Apply formatting rules (Oxford commas, em dashes)
    • +
+
+ 
claude agent every-style-editor
+
+
+
+ + +
+

Design Agents (3)

+

Design agents that help with UI implementation, Figma synchronization, and iterative design refinement.

+ +
+
+

design-iterator

+ Design +
+

+ Systematic UI/UX design refinement through iterative improvements. + Takes screenshots, analyzes, implements changes, and repeats. +

+

Process

+
    +
  • Take focused screenshots of target elements
    • +
  • Analyze current state and identify 3-5 improvements
    • +
  • Implement targeted CSS/design changes
    • +
  • Document changes made
    • +
  • Repeat for specified iterations (default 10)
    • +
+
+ 
claude agent design-iterator
+
+
+ +
+
+

figma-design-sync

+ Figma +
+

+ Automatically detects and fixes visual differences between Figma designs and web implementations. + Uses Sonnet model. +

+

Workflow

+
    +
  • Extract design specifications from Figma
    • +
  • Capture implementation screenshots
    • +
  • Conduct systematic visual comparison
    • +
  • Make precise code changes to fix discrepancies
    • +
  • Verify implementation matches design
    • +
+
+ 
claude agent figma-design-sync
+
+
+ +
+
+

design-implementation-reviewer

+ Review +
+

+ Verifies UI implementations match Figma design specifications. + Uses Opus model for detailed analysis. +

+

Comparison Areas

+
    +
  • Layouts and structure
    • +
  • Typography (fonts, sizes, weights)
    • +
  • Colors and themes
    • +
  • Spacing and alignment
    • +
  • Different viewport sizes
    • +
+
+ 
claude agent design-implementation-reviewer
+
+
+
+ + +
+

Documentation Agent (1)

+ +
+
+

ankane-readme-writer

+ Docs +
+

+ Creates/updates README files following Ankane-style template for Ruby gems. + Optimized for conciseness with every sentence kept to 15 words or less. +

+

Section Order

+
    +
  1. Header (title + description)
    2. +
  2. Installation
    3. +
  3. Quick Start
    4. +
  4. Usage
    5. +
  5. Options
    6. +
  6. Upgrading
    7. +
  7. Contributing
    8. +
  8. License
    9. +
+

Style Guidelines

+
    +
  • Imperative voice throughout
    • +
  • 15 words max per sentence
    • +
  • Single-purpose code fences
    • +
  • Up to 4 badges maximum
    • +
  • No HTML comments
    • +
+
+ 
claude agent ankane-readme-writer
+
+
+
+ + + +
+
+
+ + + + + diff --git a/plugins/compounding-engineering/docs/pages/commands.html b/plugins/compounding-engineering/docs/pages/commands.html new file mode 100644 index 0000000..3992583 --- /dev/null +++ b/plugins/compounding-engineering/docs/pages/commands.html @@ -0,0 +1,518 @@ + + + + + + Command Reference - Compounding Engineering + + + + + + + + + + +
+
+ + +
+
+ + +
+ +
+

Command Reference

+

+ Complete documentation for all 16 slash commands. Commands automate complex multi-step workflows + by orchestrating multiple agents, tools, and processes. +

+ + +
+

Workflow Commands (4)

+

Core workflow commands that embody the Plan-Delegate-Assess-Codify philosophy.

+ +
+
+ /workflows:plan +
+

+ Transform feature descriptions into well-structured project plans following conventions. +

+

Arguments

+

[feature description, bug report, or improvement idea]

+

Workflow

+
    +
  1. Repository Research (Parallel) - Launch 3 agents simultaneously: +
      +
    • repo-research-analyst - Project patterns
      • +
    • best-practices-researcher - Industry standards
      • +
    • framework-docs-researcher - Framework documentation
      • +
    +
    2. +
  2. SpecFlow Analysis - Run spec-flow-analyzer for user flows
    3. +
  3. Choose Detail Level: +
      +
    • MINIMAL - Simple bugs/small improvements
      • +
    • MORE - Standard features
      • +
    • A LOT - Major features with phases
      • +
    +
    4. +
  4. Write Plan - Save as plans/<issue_title>.md
    5. +
  5. Review - Call /plan_review for multi-agent feedback
    6. +
+
+
+
+

This command does NOT write code. It only researches and creates the plan.

+
+
+
+ 
/workflows:plan Add OAuth integration for third-party auth
+/workflows:plan Fix N+1 query in user dashboard
+
+
+ +
+
+ /workflows:review +
+

+ Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees. +

+

Arguments

+

[PR number, GitHub URL, branch name, or "latest"]

+

Workflow

+
    +
  1. Setup - Detect review target, optionally use git-worktree for isolation
    2. +
  2. Launch 12 Parallel Review Agents: +
      +
    • kieran-rails-reviewer, dhh-rails-reviewer
      • +
    • security-sentinel, performance-oracle
      • +
    • architecture-strategist, data-integrity-guardian
      • +
    • pattern-recognition-specialist, git-history-analyzer
      • +
    • And more...
      • +
    +
    3. +
  3. Ultra-Thinking Analysis - Stakeholder perspectives, scenario exploration
    4. +
  4. Simplification Review - Run code-simplicity-reviewer
    5. +
  5. Synthesize Findings - Categorize by severity (P1/P2/P3)
    6. +
  6. Create Todo Files - Using file-todos skill for all findings
    7. +
+
+
+
+

P1 (Critical) findings BLOCK MERGE. Address these before merging.

+
+
+
+ 
/workflows:review 42
+/workflows:review https://github.com/owner/repo/pull/42
+/workflows:review feature-branch-name
+/workflows:review latest
+
+
+ +
+
+ /workflows:work +
+

+ Execute work plans efficiently while maintaining quality and finishing features. +

+

Arguments

+

[plan file, specification, or todo file path]

+

Phases

+
    +
  1. Quick Start +
      +
    • Read plan & clarify requirements
      • +
    • Setup environment (live or worktree)
      • +
    • Create TodoWrite task list
      • +
    +
    2. +
  2. Execute +
      +
    • Task execution loop with progress tracking
      • +
    • Follow existing patterns
      • +
    • Test continuously
      • +
    • Figma sync if applicable
      • +
    +
    3. +
  3. Quality Check +
      +
    • Run test suite
      • +
    • Run linting
      • +
    • Optional reviewer agents for complex changes
      • +
    +
    4. +
  4. Ship It +
      +
    • Create commit with conventional format
      • +
    • Create pull request
      • +
    • Notify with summary
      • +
    +
    5. +
+
+ 
/workflows:work plans/user-authentication.md
+/workflows:work todos/042-ready-p1-performance-issue.md
+
+
+ +
+
+ /workflows:codify +
+

+ Document a recently solved problem for the knowledge base. +

+

Arguments

+

[optional: brief context about the fix]

+

Workflow

+
    +
  1. Preconditions - Verify problem is solved and verified working
    2. +
  2. Launch 7 Parallel Subagents: +
      +
    • Context Analyzer - Extract YAML frontmatter skeleton
      • +
    • Solution Extractor - Identify root cause and solution
      • +
    • Related Docs Finder - Find cross-references
      • +
    • Prevention Strategist - Develop prevention strategies
      • +
    • Category Classifier - Determine docs category
      • +
    • Documentation Writer - Create the file
      • +
    • Optional Specialized Agent - Based on problem type
      • +
    +
    3. +
  3. Create Documentation - File in docs/solutions/[category]/
    4. +
+

Auto-Triggers

+

Phrases: "that worked", "it's fixed", "working now", "problem solved"

+
+ 
/workflows:codify
+/workflows:codify N+1 query optimization
+
+
+
+ + +
+

Utility Commands (12)

+

Specialized commands for specific tasks like changelog generation, bug reporting, and parallel resolution.

+ +
+
+ /changelog +
+

+ Create engaging changelogs for recent merges to main branch. +

+

Arguments

+

[optional: daily|weekly, or time period in days]

+

Output Sections

+
    +
  • Breaking Changes (top priority)
    • +
  • New Features
    • +
  • Bug Fixes
    • +
  • Other Improvements
    • +
  • Shoutouts
    • +
  • Fun Fact
    • +
+
+ 
/changelog daily
+/changelog weekly
+/changelog 7
+
+
+ +
+
+ /create-agent-skill +
+

+ Create or edit Claude Code skills with expert guidance on structure and best practices. +

+

Arguments

+

[skill description or requirements]

+
+ 
/create-agent-skill PDF processing for document analysis
+/create-agent-skill Web scraping with error handling
+
+
+ +
+
+ /generate_command +
+

+ Create a new custom slash command following conventions and best practices. +

+

Arguments

+

[command purpose and requirements]

+
+ 
/generate_command Security audit for codebase
+/generate_command Automated performance testing
+
+
+ +
+
+ /heal-skill +
+

+ Heal skill documentation by applying corrections discovered during execution. +

+

Arguments

+

[optional: specific issue to fix]

+

Approval Options

+
    +
  1. Apply and commit
    2. +
  2. Apply without commit
    3. +
  3. Revise changes
    4. +
  4. Cancel
    5. +
+
+ 
/heal-skill API endpoint URL changed
+/heal-skill parameter validation error
+
+
+ +
+
+ /plan_review +
+

+ Have multiple specialized agents review a plan in parallel. +

+

Arguments

+

[plan file path or plan content]

+

Review Agents

+
    +
  • dhh-rails-reviewer - Rails conventions
    • +
  • kieran-rails-reviewer - Rails best practices
    • +
  • code-simplicity-reviewer - Simplicity and clarity
    • +
+
+ 
/plan_review plans/user-authentication.md
+
+
+ +
+
+ /report-bug +
+

+ Report a bug in the compounding-engineering plugin. +

+

Arguments

+

[optional: brief description of the bug]

+

Information Collected

+
    +
  • Bug category (Agent/Command/Skill/MCP/Installation)
    • +
  • Specific component name
    • +
  • Actual vs expected behavior
    • +
  • Steps to reproduce
    • +
  • Error messages
    • +
  • Environment info (auto-gathered)
    • +
+
+ 
/report-bug Agent not working
+/report-bug Command failing with timeout
+
+
+ +
+
+ /reproduce-bug +
+

+ Reproduce and investigate a bug using logs and console inspection. +

+

Arguments

+

[GitHub issue number]

+

Investigation Process

+
    +
  1. Read GitHub issue details
    2. +
  2. Launch parallel investigation agents
    3. +
  3. Analyze code for failure points
    4. +
  4. Iterate until root cause found
    5. +
  5. Post findings to GitHub issue
    6. +
+
+ 
/reproduce-bug 142
+
+
+ +
+
+ /triage +
+

+ Triage and categorize findings for the CLI todo system. +

+

Arguments

+

[findings list or source type]

+

User Decisions

+
    +
  • "yes" - Create/update todo file, change status to ready
    • +
  • "next" - Skip and delete from todos
    • +
  • "custom" - Modify and re-present
    • +
+
+
+
+

This command does NOT write code. It only categorizes and creates todo files.

+
+
+
+ 
/triage code-review-findings.txt
+/triage security-audit-results
+
+
+ +
+
+ /resolve_parallel +
+

+ Resolve all TODO comments using parallel processing. +

+

Arguments

+

[optional: specific TODO pattern or file]

+

Process

+
    +
  1. Analyze TODO comments from codebase
    2. +
  2. Create dependency graph (mermaid diagram)
    3. +
  3. Spawn parallel pr-comment-resolver agents
    4. +
  4. Commit and push after completion
    5. +
+
+ 
/resolve_parallel
+/resolve_parallel authentication
+/resolve_parallel src/auth/
+
+
+ +
+
+ /resolve_pr_parallel +
+

+ Resolve all PR comments using parallel processing. +

+

Arguments

+

[optional: PR number or current PR]

+

Process

+
    +
  1. Get all unresolved PR comments
    2. +
  2. Create TodoWrite list
    3. +
  3. Launch parallel pr-comment-resolver agents
    4. +
  4. Commit, resolve threads, and push
    5. +
+
+ 
/resolve_pr_parallel
+/resolve_pr_parallel 123
+
+
+ +
+
+ /resolve_todo_parallel +
+

+ Resolve all pending CLI todos using parallel processing. +

+

Arguments

+

[optional: specific todo ID or pattern]

+

Process

+
    +
  1. Get unresolved TODOs from /todos/*.md
    2. +
  2. Analyze dependencies
    3. +
  3. Spawn parallel agents
    4. +
  4. Commit, mark as resolved, push
    5. +
+
+ 
/resolve_todo_parallel
+/resolve_todo_parallel 042
+/resolve_todo_parallel p1
+
+
+ +
+
+ /prime +
+

+ Prime/setup command for project initialization. +

+
+ 
/prime
+
+
+
+ + + +
+
+
+ + + + + diff --git a/plugins/compounding-engineering/docs/pages/mcp-servers.html b/plugins/compounding-engineering/docs/pages/mcp-servers.html new file mode 100644 index 0000000..08f6678 --- /dev/null +++ b/plugins/compounding-engineering/docs/pages/mcp-servers.html @@ -0,0 +1,400 @@ + + + + + + MCP Servers Reference - Compounding Engineering + + + + + + + + + + +
+
+ + +
+
+ + +
+ +
+

MCP Servers Reference

+

+ Model Context Protocol (MCP) servers extend Claude Code's capabilities with + browser automation and framework documentation lookup. The plugin bundles + 2 MCP servers that start automatically when enabled. +

+ +
+
+
+

Known Issue: Auto-Loading

+

+ MCP servers may not load automatically when the plugin is installed. + See Manual Configuration for the workaround. +

+
+
+ + +
+

Playwright

+

+ Browser automation via @playwright/mcp. Enables taking screenshots, + clicking elements, filling forms, and executing JavaScript in a real browser. +

+ +

Tools Provided

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ToolDescription
browser_navigateNavigate to a URL in the browser
browser_take_screenshotCapture a screenshot of the current page or element
browser_clickClick on an element using CSS selector or text
browser_fill_formFill form fields with values
browser_snapshotGet an accessibility tree snapshot of the page
browser_evaluateExecute JavaScript code in the browser context
+ +

Use Cases

+
    +
  • Design Iteration - Take screenshots for UI comparison
    • +
  • Testing - Automate browser interactions
    • +
  • Debugging - Inspect page state and DOM
    • +
  • Data Extraction - Scrape content from web pages
    • +
+ +

Example Usage

+
+ 
# The tools are available when the MCP server is running
+# Claude Code will use them automatically when appropriate
+
+# Example: Taking a screenshot for design review
+"Take a screenshot of the login page"
+
+# Example: Testing a form
+"Navigate to /signup and fill in the email field with test@example.com"
+
+ +

Configuration

+
+ 
{
+  "playwright": {
+    "type": "stdio",
+    "command": "npx",
+    "args": ["-y", "@playwright/mcp@latest"],
+    "env": {}
+  }
+}
+
+
+ + +
+

Context7

+

+ Framework documentation lookup via Context7 MCP. Provides access to + documentation for 100+ frameworks and libraries. +

+ +

Tools Provided

+ + + + + + + + + + + + + + + + + +
ToolDescription
resolve-library-idFind the library ID for a framework or package
get-library-docsGet documentation for a specific library
+ +

Supported Frameworks

+

Context7 supports 100+ frameworks including:

+
+
+

Backend

+
    +
  • Ruby on Rails
    • +
  • Django
    • +
  • Laravel
    • +
  • Express
    • +
  • FastAPI
    • +
  • Spring Boot
    • +
+
+
+

Frontend

+
    +
  • React
    • +
  • Vue.js
    • +
  • Angular
    • +
  • Svelte
    • +
  • Next.js
    • +
  • Nuxt
    • +
+
+
+

Mobile

+
    +
  • React Native
    • +
  • Flutter
    • +
  • SwiftUI
    • +
  • Kotlin
    • +
+
+
+

Tools & Libraries

+
    +
  • Tailwind CSS
    • +
  • PostgreSQL
    • +
  • Redis
    • +
  • GraphQL
    • +
  • Prisma
    • +
  • And many more...
    • +
+
+
+ +

Example Usage

+
+ 
# Claude Code will use Context7 automatically for documentation lookups
+"Look up the Rails ActionCable documentation"
+
+"How does the useEffect hook work in React?"
+
+"What are the best practices for PostgreSQL indexes?"
+
+ +

Configuration

+
+ 
{
+  "context7": {
+    "type": "http",
+    "url": "https://mcp.context7.com/mcp"
+  }
+}
+
+
+ + +
+

Manual Configuration

+

+ If MCP servers don't auto-load with the plugin, add them manually to your + .claude/settings.json file. +

+ +

Project-Level Configuration

+

Add to .claude/settings.json in your project:

+
+ 
{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+      "env": {}
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}
+
+ +

Global Configuration

+

Add to ~/.claude/settings.json to enable for all projects:

+
+ 
{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"],
+      "env": {}
+    },
+    "context7": {
+      "type": "http",
+      "url": "https://mcp.context7.com/mcp"
+    }
+  }
+}
+
+ +

Requirements

+ + + + + + + + + + + + + + + + + +
ServerRequirement
PlaywrightNode.js 18+ and npx
Context7Internet connection (HTTP endpoint)
+ +

Verifying MCP Servers

+

After configuration, restart Claude Code and verify the servers are loaded:

+
+ 
# Check if MCP tools are available
+"What MCP tools do you have access to?"
+
+# Test Playwright
+"Take a screenshot of the current directory listing"
+
+# Test Context7
+"Look up Rails Active Record documentation"
+
+
+ + + +
+
+
+ + + + + + + diff --git a/plugins/compounding-engineering/docs/pages/skills.html b/plugins/compounding-engineering/docs/pages/skills.html new file mode 100644 index 0000000..e86da64 --- /dev/null +++ b/plugins/compounding-engineering/docs/pages/skills.html @@ -0,0 +1,591 @@ + + + + + + Skill Reference - Compounding Engineering + + + + + + + + + + +
+
+ + +
+
+ + +
+ +
+

Skill Reference

+

+ Complete documentation for all 11 intelligent skills. Skills provide deep domain expertise + that Claude Code can invoke on-demand, including references, templates, and workflows. +

+ +
+

How to Use Skills

+
+ 
# In your prompt, reference the skill
+skill: [skill-name]
+
+# Examples
+skill: gemini-imagegen
+skill: dhh-ruby-style
+skill: create-agent-skills
+
+
+ +
+
+
+

Skills vs Agents

+

+ Agents are specialized personas invoked with claude agent [name]. + Skills are bodies of knowledge (references, templates, workflows) invoked with skill: [name]. +

+
+
+ + +
+

Development Tools (7)

+

Skills for code generation, gem writing, and development patterns.

+ +
+
+

create-agent-skills

+ Meta +
+

+ Expert guidance for creating, writing, building, and refining Claude Code Skills. + Use when working with SKILL.md files or authoring new skills. +

+

Capabilities

+
    +
  • Skill architecture and best practices
    • +
  • Router pattern for complex multi-step skills
    • +
  • Progressive disclosure design principles
    • +
  • SKILL.md structure guidance
    • +
  • Asset management (workflows, references, templates, scripts)
    • +
  • XML structure patterns
    • +
+

Workflows Included

+
    +
  • create-new-skill - Start from scratch
    • +
  • add-reference - Add reference documentation
    • +
  • add-template - Add code templates
    • +
  • add-workflow - Add step-by-step procedures
    • +
  • add-script - Add executable scripts
    • +
  • audit-skill - Validate skill structure
    • +
  • verify-skill - Test skill functionality
    • +
+
+ 
skill: create-agent-skills
+
+
+ +
+
+

skill-creator

+ Meta +
+

+ Guide for creating effective skills with a 6-step process. +

+

6-Step Process

+
    +
  1. Understand skill usage patterns with examples
    2. +
  2. Plan reusable skill contents
    3. +
  3. Initialize skill using template
    4. +
  4. Edit skill with clear instructions
    5. +
  5. Package skill into distributable zip
    6. +
  6. Iterate based on testing feedback
    7. +
+
+ 
skill: skill-creator
+
+
+ +
+
+

dhh-ruby-style

+ Rails +
+

+ Write Ruby and Rails code in DHH's distinctive 37signals style. + Triggers on Ruby/Rails code generation or when mentioning DHH, 37signals, Basecamp, HEY. +

+

Key Patterns

+
    +
  • REST Purity - 7 REST actions only
    • +
  • Fat Models - Business logic, authorization, broadcasting in models
    • +
  • Thin Controllers - 1-5 line actions
    • +
  • Current Attributes - Request context
    • +
  • Hotwire/Turbo - Model-level broadcasting
    • +
+

Ruby Syntax Preferences

+
    +
  • Symbol arrays %i[...]
    • +
  • Modern hash syntax
    • +
  • Ternaries for simple conditionals
    • +
  • Bang methods for mutations
    • +
+
+ 
skill: dhh-ruby-style
+
+
+ +
+
+

andrew-kane-gem-writer

+ Ruby +
+

+ Write Ruby gems following Andrew Kane's proven patterns and philosophy. + Based on 100+ gems with 374M+ downloads. +

+

Philosophy

+
    +
  • Simplicity over cleverness
    • +
  • Zero or minimal dependencies
    • +
  • Explicit code over metaprogramming
    • +
  • Rails integration without Rails coupling
    • +
+

Key Patterns

+
    +
  • Class macro DSL for configuration
    • +
  • ActiveSupport.on_load for Rails integration
    • +
  • class << self with attr_accessor
    • +
  • Railtie pattern for hooks
    • +
  • Minitest (no RSpec)
    • +
+

Reference Files

+
    +
  • references/module-organization.md
    • +
  • references/rails-integration.md
    • +
  • references/database-adapters.md
    • +
  • references/testing-patterns.md
    • +
+
+ 
skill: andrew-kane-gem-writer
+
+
+ +
+
+

dspy-ruby

+ AI +
+

+ Build type-safe, composable LLM applications with DSPy.rb. + Use when implementing predictable AI features in Ruby. +

+

Predictor Types

+
    +
  • Predict - Basic inference
    • +
  • ChainOfThought - Reasoning with explanations
    • +
  • ReAct - Tool-using agents with iteration
    • +
  • CodeAct - Dynamic code generation
    • +
+

Supported Providers

+
    +
  • OpenAI (GPT-4, GPT-4o-mini)
    • +
  • Anthropic Claude
    • +
  • Google Gemini
    • +
  • Ollama (free, local)
    • +
  • OpenRouter
    • +
+

Requirements

+ + + + + + + + + + + + + +
OPENAI_API_KEYFor OpenAI provider
ANTHROPIC_API_KEYFor Anthropic provider
GOOGLE_API_KEYFor Gemini provider
+
+ 
skill: dspy-ruby
+
+
+ +
+
+

frontend-design

+ Design +
+

+ Create distinctive, production-grade frontend interfaces. + Generates creative, polished code that avoids generic AI aesthetics. +

+

Design Thinking

+
    +
  • Purpose - What is the interface for?
    • +
  • Tone - What feeling should it evoke?
    • +
  • Constraints - Technical and brand limitations
    • +
  • Differentiation - How to stand out
    • +
+

Focus Areas

+
    +
  • Typography with distinctive font choices
    • +
  • Color & theme coherence with CSS variables
    • +
  • Motion and animation patterns
    • +
  • Spatial composition with asymmetry
    • +
  • Backgrounds (gradients, textures, patterns)
    • +
+
+
+
+

Avoids generic AI aesthetics like Inter fonts, purple gradients, and rounded corners everywhere.

+
+
+
+ 
skill: frontend-design
+
+
+ +
+
+

codify-docs

+ Docs +
+

+ Capture solved problems as categorized documentation with YAML frontmatter for fast lookup. +

+

Auto-Triggers

+

Phrases: "that worked", "it's fixed", "working now", "problem solved"

+

7-Step Process

+
    +
  1. Detect confirmation phrase
    2. +
  2. Gather context (module, symptom, investigation, root cause)
    3. +
  3. Check existing docs for similar issues
    4. +
  4. Generate filename
    5. +
  5. Validate YAML frontmatter
    6. +
  6. Create documentation in category directory
    7. +
  7. Cross-reference related issues
    8. +
+

Categories

+
    +
  • build-errors/
    • +
  • test-failures/
    • +
  • runtime-errors/
    • +
  • performance-issues/
    • +
  • database-issues/
    • +
  • security-issues/
    • +
+
+ 
skill: codify-docs
+
+
+
+ + +
+

Content & Workflow (3)

+

Skills for content editing, task tracking, and parallel development.

+ +
+
+

every-style-editor

+ Content +
+

+ Review and edit copy to ensure adherence to Every's style guide. + Provides systematic line-by-line review. +

+

Four-Phase Review

+
    +
  1. Initial Assessment - Context, type, audience, tone
    2. +
  2. Detailed Line Edit - Sentence structure, punctuation, capitalization
    3. +
  3. Mechanical Review - Spacing, formatting, consistency
    4. +
  4. Recommendations - Actionable improvement suggestions
    5. +
+

Style Checks

+
    +
  • Grammar and punctuation
    • +
  • Style guide compliance
    • +
  • Capitalization rules
    • +
  • Word choice optimization
    • +
  • Formatting consistency
    • +
+
+ 
skill: every-style-editor
+
+
+ +
+
+

file-todos

+ Workflow +
+

+ File-based todo tracking system in the todos/ directory. + Integrates with code review and slash commands. +

+

File Format

+
+ 
# Naming convention
+{issue_id}-{status}-{priority}-{description}.md
+
+# Examples
+001-pending-p1-security-vulnerability.md
+002-ready-p2-performance-optimization.md
+003-complete-p3-code-cleanup.md
+
+

Status Values

+
    +
  • pending - Needs triage
    • +
  • ready - Approved for work
    • +
  • complete - Done
    • +
+

Priority Values

+
    +
  • p1 - Critical
    • +
  • p2 - Important
    • +
  • p3 - Nice-to-have
    • +
+

YAML Frontmatter

+
+ 
---
+status: pending
+priority: p1
+issue_id: "001"
+tags: [security, authentication]
+dependencies: []
+---
+
+
+ 
skill: file-todos
+
+
+ +
+
+

git-worktree

+ Git +
+

+ Manage Git worktrees for isolated parallel development. + Handles creating, listing, switching, and cleaning up worktrees. +

+

Commands

+
+ 
# Create new worktree
+bash scripts/worktree-manager.sh create feature-login
+
+# List worktrees
+bash scripts/worktree-manager.sh list
+
+# Switch to worktree
+bash scripts/worktree-manager.sh switch feature-login
+
+# Clean up completed worktrees
+bash scripts/worktree-manager.sh cleanup
+
+

Integration

+
    +
  • Works with /workflows:review for isolated PR analysis
    • +
  • Works with /workflows:work for parallel feature development
    • +
+

Requirements

+
    +
  • Git 2.8+ (for worktree support)
    • +
  • Worktrees stored in .worktrees/ directory
    • +
+
+ 
skill: git-worktree
+
+
+
+ + +
+

Image Generation (1)

+

AI-powered image generation and editing.

+ + +
+ + + +
+
+
+ + + + + From 92d0e23768bdcd5ba4be0252f5e77d2c57d95d50 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 26 Nov 2025 16:39:54 +0000 Subject: [PATCH 03/25] docs: Add /release-docs command, changelog page, and build instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add /release-docs command for regenerating documentation site - Add commands/README.md with usage instructions for all commands - Add changelog.html page rendering CHANGELOG.md in HTML format - Add changelog CSS styles to docs.css - Update navigation in all docs pages to include changelog link - Fix command count from 16 to 13 in navigation - Update CLAUDE.md with: - Documentation Site section explaining structure - /release-docs command in update checklist - Instructions for keeping docs up-to-date πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CLAUDE.md | 95 +++- .../commands/README.md | 105 ++++ .../commands/release-docs.md | 211 ++++++++ .../compounding-engineering/docs/css/docs.css | 162 ++++++ .../docs/pages/agents.html | 8 +- .../docs/pages/changelog.html | 476 ++++++++++++++++++ .../docs/pages/commands.html | 8 +- .../docs/pages/getting-started.html | 1 + .../docs/pages/mcp-servers.html | 8 +- .../docs/pages/skills.html | 8 +- 10 files changed, 1074 insertions(+), 8 deletions(-) create mode 100644 plugins/compounding-engineering/commands/README.md create mode 100644 plugins/compounding-engineering/commands/release-docs.md create mode 100644 plugins/compounding-engineering/docs/pages/changelog.html diff --git a/CLAUDE.md b/CLAUDE.md index 6066b41..2eee544 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,9 +12,15 @@ every-marketplace/ └── compounding-engineering/ # The actual plugin β”œβ”€β”€ .claude-plugin/ β”‚ └── plugin.json # Plugin metadata - β”œβ”€β”€ agents/ # 17 specialized AI agents - β”œβ”€β”€ commands/ # 6 slash commands - β”œβ”€β”€ skills/ # 1 skill (gemini-imagegen) + β”œβ”€β”€ agents/ # 24 specialized AI agents + β”œβ”€β”€ commands/ # 13 slash commands (including /release-docs) + β”œβ”€β”€ skills/ # 11 skills + β”œβ”€β”€ mcp-servers/ # 2 MCP servers (playwright, context7) + β”œβ”€β”€ docs/ # Documentation site (static HTML/CSS/JS) + β”‚ β”œβ”€β”€ index.html # Landing page + β”‚ β”œβ”€β”€ css/ # Stylesheets (style.css, docs.css) + β”‚ β”œβ”€β”€ js/ # JavaScript (main.js) + β”‚ └── pages/ # Reference pages (agents, commands, skills, mcp-servers) β”œβ”€β”€ README.md # Plugin documentation └── CHANGELOG.md # Version history ``` @@ -86,7 +92,21 @@ When adding new functionality, bump the version in: - [ ] `plugins/compounding-engineering/CHANGELOG.md` β†’ document changes - [ ] `CLAUDE.md` β†’ update structure diagram if needed -#### 5. Validate JSON files +#### 5. Rebuild documentation site + +Run the release-docs command to update all documentation pages: + +```bash +claude /release-docs +``` + +This will: +- Update stats on the landing page +- Regenerate reference pages (agents, commands, skills, MCP servers) +- Update the changelog page +- Validate all counts match actual files + +#### 6. Validate JSON files ```bash cat .claude-plugin/marketplace.json | jq . @@ -167,6 +187,73 @@ Each plugin has its own plugin.json with detailed metadata: } ``` +## Documentation Site + +The plugin includes a static documentation site at `plugins/compounding-engineering/docs/`. This site is built with plain HTML/CSS/JS (based on Evil Martians' LaunchKit template) and requires no build step to view. + +### Documentation Structure + +``` +docs/ +β”œβ”€β”€ index.html # Landing page with stats and philosophy +β”œβ”€β”€ css/ +β”‚ β”œβ”€β”€ style.css # Main styles (LaunchKit-based) +β”‚ └── docs.css # Documentation-specific styles +β”œβ”€β”€ js/ +β”‚ └── main.js # Interactivity (theme toggle, mobile nav) +└── pages/ + β”œβ”€β”€ getting-started.html # Installation and quick start + β”œβ”€β”€ agents.html # All 24 agents reference + β”œβ”€β”€ commands.html # All 13 commands reference + β”œβ”€β”€ skills.html # All 11 skills reference + β”œβ”€β”€ mcp-servers.html # MCP servers reference + └── changelog.html # Version history +``` + +### Keeping Docs Up-to-Date + +**IMPORTANT:** After ANY change to agents, commands, skills, or MCP servers, run: + +```bash +claude /release-docs +``` + +This command: +1. Counts all current components +2. Reads all agent/command/skill/MCP files +3. Regenerates all reference pages +4. Updates stats on the landing page +5. Updates the changelog from CHANGELOG.md +6. Validates counts match across all files + +### Manual Updates + +If you need to update docs manually: + +1. **Landing page stats** - Update the numbers in `docs/index.html`: + ```html + 24 + 13 + ``` + +2. **Reference pages** - Each page in `docs/pages/` documents all components in that category + +3. **Changelog** - `docs/pages/changelog.html` mirrors `CHANGELOG.md` in HTML format + +### Viewing Docs Locally + +Since the docs are static HTML, you can view them directly: + +```bash +# Open in browser +open plugins/compounding-engineering/docs/index.html + +# Or start a local server +cd plugins/compounding-engineering/docs +python -m http.server 8000 +# Then visit http://localhost:8000 +``` + ## Testing Changes ### Test Locally diff --git a/plugins/compounding-engineering/commands/README.md b/plugins/compounding-engineering/commands/README.md new file mode 100644 index 0000000..58b08ab --- /dev/null +++ b/plugins/compounding-engineering/commands/README.md @@ -0,0 +1,105 @@ +# Commands + +This directory contains all slash commands for the compounding-engineering plugin. Each `.md` file defines a command that can be invoked via `claude /command-name`. + +## Documentation Management + +### `/release-docs` + +**Purpose:** Build and update the documentation site with current plugin components. + +**Usage:** +```bash +# Full documentation release +claude /release-docs + +# Preview changes without writing files +claude /release-docs --dry-run +``` + +**What it does:** +1. Inventories all current components (agents, commands, skills, MCP servers) +2. Updates `docs/index.html` with accurate stats +3. Regenerates reference pages (`agents.html`, `commands.html`, `skills.html`, `mcp-servers.html`) +4. Updates `changelog.html` with latest version history +5. Ensures counts in `plugin.json` and `marketplace.json` match actual files +6. Validates all JSON files + +**When to run:** +- After adding, removing, or modifying any agent +- After adding, removing, or modifying any command +- After adding, removing, or modifying any skill +- After adding, removing, or modifying any MCP server +- Before releasing a new version + +## Workflow Commands + +### `/plan_review` +Multi-agent plan review running in parallel for thorough analysis. + +### `/resolve_parallel` +Resolve TODO comments in the codebase in parallel. + +### `/resolve_pr_parallel` +Resolve PR comments in parallel. + +### `/resolve_todo_parallel` +Resolve TODO items from a list in parallel. + +## Development Commands + +### `/changelog` +Create engaging changelogs for recent merges to main branch. + +### `/generate_command` +Generate new slash command files from a description. + +### `/create-agent-skill` +Create or edit Claude Code skills with best practices. + +### `/heal-skill` +Fix skill documentation issues and formatting. + +### `/prime` +Prime/setup command for initializing projects. + +### `/reproduce-bug` +Reproduce bugs using logs and console output. + +### `/report-bug` +Report bugs in the compounding-engineering plugin with structured workflow. + +### `/triage` +Triage and prioritize issues. + +## Command File Structure + +Each command file follows this structure: + +```markdown +--- +name: command-name +description: Brief description of what the command does +argument-hint: "[optional arguments description]" +--- + +# Command Title + +Instructions for Claude on how to execute this command... +``` + +## Adding a New Command + +1. Create a new `.md` file in this directory +2. Add the frontmatter with `name`, `description`, and optional `argument-hint` +3. Write detailed instructions for Claude +4. Run `/release-docs` to update documentation +5. Test with `claude /your-command-name` + +## Best Practices + +- Keep command names short and descriptive (use hyphens, not underscores) +- Provide clear step-by-step instructions +- Include examples of expected output +- Document any prerequisites or dependencies +- Use parallel agent invocation when tasks are independent diff --git a/plugins/compounding-engineering/commands/release-docs.md b/plugins/compounding-engineering/commands/release-docs.md new file mode 100644 index 0000000..38215c9 --- /dev/null +++ b/plugins/compounding-engineering/commands/release-docs.md @@ -0,0 +1,211 @@ +--- +name: release-docs +description: Build and update the documentation site with current plugin components +argument-hint: "[optional: --dry-run to preview changes without writing]" +--- + +# Release Documentation Command + +You are a documentation generator for the compounding-engineering plugin. Your job is to ensure the documentation site at `plugins/compounding-engineering/docs/` is always up-to-date with the actual plugin components. + +## Overview + +The documentation site is a static HTML/CSS/JS site based on the Evil Martians LaunchKit template. It needs to be regenerated whenever: + +- Agents are added, removed, or modified +- Commands are added, removed, or modified +- Skills are added, removed, or modified +- MCP servers are added, removed, or modified + +## Step 1: Inventory Current Components + +First, count and list all current components: + +```bash +# Count agents +ls plugins/compounding-engineering/agents/*.md | wc -l + +# Count commands +ls plugins/compounding-engineering/commands/*.md | wc -l + +# Count skills +ls -d plugins/compounding-engineering/skills/*/ 2>/dev/null | wc -l + +# Count MCP servers +ls -d plugins/compounding-engineering/mcp-servers/*/ 2>/dev/null | wc -l +``` + +Read all component files to get their metadata: + +### Agents +For each agent file in `plugins/compounding-engineering/agents/*.md`: +- Extract the frontmatter (name, description) +- Note the category (Review, Research, Workflow, Design, Docs) +- Get key responsibilities from the content + +### Commands +For each command file in `plugins/compounding-engineering/commands/*.md`: +- Extract the frontmatter (name, description, argument-hint) +- Categorize as Workflow or Utility command + +### Skills +For each skill directory in `plugins/compounding-engineering/skills/*/`: +- Read the SKILL.md file for frontmatter (name, description) +- Note any scripts or supporting files + +### MCP Servers +For each MCP server in `plugins/compounding-engineering/mcp-servers/*/`: +- Read the configuration and README +- List the tools provided + +## Step 2: Update Documentation Pages + +### 2a. Update `docs/index.html` + +Update the stats section with accurate counts: +```html +
+
+ [AGENT_COUNT] + Specialized Agents +
+ +
+``` + +Ensure the component summary sections list key components accurately. + +### 2b. Update `docs/pages/agents.html` + +Regenerate the complete agents reference page: +- Group agents by category (Review, Research, Workflow, Design, Docs) +- Include for each agent: + - Name and description + - Key responsibilities (bullet list) + - Usage example: `claude agent [agent-name] "your message"` + - Use cases + +### 2c. Update `docs/pages/commands.html` + +Regenerate the complete commands reference page: +- Group commands by type (Workflow, Utility) +- Include for each command: + - Name and description + - Arguments (if any) + - Process/workflow steps + - Example usage + +### 2d. Update `docs/pages/skills.html` + +Regenerate the complete skills reference page: +- Group skills by category (Development Tools, Content & Workflow, Image Generation) +- Include for each skill: + - Name and description + - Usage: `claude skill [skill-name]` + - Features and capabilities + +### 2e. Update `docs/pages/mcp-servers.html` + +Regenerate the MCP servers reference page: +- For each server: + - Name and purpose + - Tools provided + - Configuration details + - Supported frameworks/services + +## Step 3: Update Metadata Files + +Ensure counts are consistent across: + +1. **`plugins/compounding-engineering/.claude-plugin/plugin.json`** + - Update `description` with correct counts + - Update `components` object with counts + - Update `agents`, `commands` arrays with current items + +2. **`.claude-plugin/marketplace.json`** + - Update plugin `description` with correct counts + +3. **`plugins/compounding-engineering/README.md`** + - Update intro paragraph with counts + - Update component lists + +## Step 4: Validate + +Run validation checks: + +```bash +# Validate JSON files +cat .claude-plugin/marketplace.json | jq . +cat plugins/compounding-engineering/.claude-plugin/plugin.json | jq . + +# Verify counts match +echo "Agents in files: $(ls plugins/compounding-engineering/agents/*.md | wc -l)" +grep -o "[0-9]* specialized agents" plugins/compounding-engineering/docs/index.html + +echo "Commands in files: $(ls plugins/compounding-engineering/commands/*.md | wc -l)" +grep -o "[0-9]* slash commands" plugins/compounding-engineering/docs/index.html +``` + +## Step 5: Report Changes + +Provide a summary of what was updated: + +``` +## Documentation Release Summary + +### Component Counts +- Agents: X (previously Y) +- Commands: X (previously Y) +- Skills: X (previously Y) +- MCP Servers: X (previously Y) + +### Files Updated +- docs/index.html - Updated stats and component summaries +- docs/pages/agents.html - Regenerated with X agents +- docs/pages/commands.html - Regenerated with X commands +- docs/pages/skills.html - Regenerated with X skills +- docs/pages/mcp-servers.html - Regenerated with X servers +- plugin.json - Updated counts and component lists +- marketplace.json - Updated description +- README.md - Updated component lists + +### New Components Added +- [List any new agents/commands/skills] + +### Components Removed +- [List any removed agents/commands/skills] +``` + +## Dry Run Mode + +If `--dry-run` is specified: +- Perform all inventory and validation steps +- Report what WOULD be updated +- Do NOT write any files +- Show diff previews of proposed changes + +## Error Handling + +- If component files have invalid frontmatter, report the error and skip +- If JSON validation fails, report and abort +- Always maintain a valid state - don't partially update + +## Post-Release + +After successful release: +1. Suggest updating CHANGELOG.md with documentation changes +2. Remind to commit with message: `docs: Update documentation site to match plugin components` +3. Remind to push changes + +## Usage Examples + +```bash +# Full documentation release +claude /release-docs + +# Preview changes without writing +claude /release-docs --dry-run + +# After adding new agents +claude /release-docs +``` diff --git a/plugins/compounding-engineering/docs/css/docs.css b/plugins/compounding-engineering/docs/css/docs.css index c4a9df8..2e89ca5 100644 --- a/plugins/compounding-engineering/docs/css/docs.css +++ b/plugins/compounding-engineering/docs/css/docs.css @@ -511,3 +511,165 @@ z-index: -1; } } + +/* ============================================ + Changelog Styles + ============================================ */ + +.version-section { + margin-bottom: var(--space-xxl); + padding-bottom: var(--space-xl); + border-bottom: 1px solid var(--color-border); +} + +.version-section:last-child { + border-bottom: none; +} + +.version-header { + display: flex; + align-items: center; + gap: var(--space-m); + margin-bottom: var(--space-l); + flex-wrap: wrap; +} + +.version-header h2 { + margin: 0; + padding: 0; + border: none; + font-size: var(--font-size-xl); + color: var(--color-text-primary); +} + +.version-date { + font-size: var(--font-size-s); + color: var(--color-text-tertiary); + background-color: var(--color-surface); + padding: var(--space-xs) var(--space-m); + border-radius: var(--radius-s); +} + +.version-badge { + font-size: var(--font-size-xs); + font-weight: 600; + padding: var(--space-xs) var(--space-m); + border-radius: var(--radius-s); + background-color: var(--color-accent); + color: white; +} + +.version-badge.major { + background-color: var(--color-warning); +} + +.version-description { + font-size: var(--font-size-m); + color: var(--color-text-secondary); + margin-bottom: var(--space-l); + font-style: italic; +} + +.changelog-category { + margin-bottom: var(--space-l); + padding: var(--space-l); + background-color: var(--color-surface); + border-radius: var(--radius-m); + border-left: 4px solid var(--color-border); +} + +.changelog-category h3 { + margin: 0 0 var(--space-m) 0; + font-size: var(--font-size-m); + display: flex; + align-items: center; + gap: var(--space-s); +} + +.changelog-category h3 i { + font-size: var(--font-size-s); +} + +.changelog-category h4 { + margin: var(--space-l) 0 var(--space-s) 0; + font-size: var(--font-size-s); + color: var(--color-text-secondary); +} + +.changelog-category ul { + margin: 0; + padding-left: var(--space-xl); +} + +.changelog-category li { + margin-bottom: var(--space-s); +} + +.changelog-category.added { + border-left-color: var(--color-success); +} + +.changelog-category.added h3 { + color: var(--color-success); +} + +.changelog-category.improved { + border-left-color: var(--color-accent); +} + +.changelog-category.improved h3 { + color: var(--color-accent); +} + +.changelog-category.changed { + border-left-color: var(--color-warning); +} + +.changelog-category.changed h3 { + color: var(--color-warning); +} + +.changelog-category.fixed { + border-left-color: var(--color-error); +} + +.changelog-category.fixed h3 { + color: var(--color-error); +} + +.version-summary { + margin-top: var(--space-l); +} + +.version-summary h4 { + margin-bottom: var(--space-m); +} + +.version-summary table { + width: 100%; + max-width: 400px; + border-collapse: collapse; + font-size: var(--font-size-s); +} + +.version-summary th, +.version-summary td { + padding: var(--space-s) var(--space-m); + text-align: left; + border-bottom: 1px solid var(--color-border); +} + +.version-summary th { + font-weight: 600; + background-color: var(--color-surface); +} + +.version-summary .positive { + color: var(--color-success); + font-weight: 600; +} + +.version-summary .negative { + color: var(--color-error); + font-weight: 600; +} diff --git a/plugins/compounding-engineering/docs/pages/agents.html b/plugins/compounding-engineering/docs/pages/agents.html index ec51834..4687f3a 100644 --- a/plugins/compounding-engineering/docs/pages/agents.html +++ b/plugins/compounding-engineering/docs/pages/agents.html @@ -34,11 +34,17 @@

Reference

+
+

Resources

+ +

On This Page

    diff --git a/plugins/compounding-engineering/docs/pages/changelog.html b/plugins/compounding-engineering/docs/pages/changelog.html new file mode 100644 index 0000000..72f6c45 --- /dev/null +++ b/plugins/compounding-engineering/docs/pages/changelog.html @@ -0,0 +1,476 @@ + + + + + + Changelog - Compounding Engineering + + + + + + + + + + +
    +
    + + +
    +
    + + +
    + +
    +

    Changelog

    +

    + All notable changes to the compounding-engineering plugin. This project follows + Semantic Versioning and + Keep a Changelog conventions. +

    + + +
    +
    +

    v2.5.0

    + 2024-11-25 +
    + +
    +

    Added

    +
      +
    • + /report-bug command - New slash command for reporting bugs in the + compounding-engineering plugin. Provides a structured workflow that gathers bug information + through guided questions, collects environment details automatically, and creates a GitHub + issue in the EveryInc/every-marketplace repository. +
      • +
    +
    +
    + + +
    +
    +

    v2.4.1

    + 2024-11-24 +
    + +
    +

    Improved

    +
      +
    • + design-iterator agent - Added focused screenshot guidance: always capture + only the target element/area instead of full page screenshots. Includes browser_resize + recommendations, element-targeted screenshot workflow using browser_snapshot refs, and + explicit instruction to never use fullPage mode. +
      • +
    +
    +
    + + +
    +
    +

    v2.4.0

    + 2024-11-24 +
    + +
    +

    Fixed

    +
      +
    • + MCP Configuration - Moved MCP servers back to plugin.json + following working examples from anthropics/life-sciences plugins. +
      • +
    • + Context7 URL - Updated to use HTTP type with correct endpoint URL. +
      • +
    +
    +
    + + +
    +
    +

    v2.3.0

    + 2024-11-24 +
    + +
    +

    Changed

    +
      +
    • + MCP Configuration - Moved MCP servers from inline plugin.json + to separate .mcp.json file per Claude Code best practices. +
      • +
    +
    +
    + + +
    +
    +

    v2.2.1

    + 2024-11-24 +
    + +
    +

    Fixed

    +
      +
    • + Playwright MCP Server - Added missing "type": "stdio" field + required for MCP server configuration to load properly. +
      • +
    +
    +
    + + +
    +
    +

    v2.2.0

    + 2024-11-24 +
    + +
    +

    Added

    +
      +
    • + Context7 MCP Server - Bundled Context7 for instant framework documentation + lookup. Provides up-to-date docs for Rails, React, Next.js, and 100+ other frameworks. +
      • +
    +
    +
    + + +
    +
    +

    v2.1.0

    + 2024-11-24 +
    + +
    +

    Added

    +
      +
    • + Playwright MCP Server - Bundled @playwright/mcp for browser + automation across all projects. Provides screenshot, navigation, click, fill, and evaluate tools. +
      • +
    +
    + +
    +

    Changed

    +
      +
    • Replaced all Puppeteer references with Playwright across agents and commands: +
        +
      • bug-reproduction-validator agent
        • +
      • design-iterator agent
        • +
      • design-implementation-reviewer agent
        • +
      • figma-design-sync agent
        • +
      • generate_command command
        • +
      +
      • +
    +
    +
    + + +
    +
    +

    v2.0.2

    + 2024-11-24 +
    + +
    +

    Changed

    +
      +
    • + design-iterator agent - Updated description to emphasize proactive usage + when design work isn't coming together on first attempt. +
      • +
    +
    +
    + + +
    +
    +

    v2.0.1

    + 2024-11-24 +
    + +
    +

    Added

    +
      +
    • CLAUDE.md - Project instructions with versioning requirements
      • +
    • docs/solutions/plugin-versioning-requirements.md - Workflow documentation
      • +
    +
    +
    + + +
    +
    +

    v2.0.0

    + 2024-11-24 + Major Release +
    + +

    + Major reorganization consolidating agents, commands, and skills from multiple sources into + a single, well-organized plugin. +

    + +
    +

    Added

    + +

    New Agents (7)

    +
      +
    • design-iterator - Iteratively refine UI components through systematic design iterations
      • +
    • design-implementation-reviewer - Verify UI implementations match Figma design specifications
      • +
    • figma-design-sync - Synchronize web implementations with Figma designs
      • +
    • bug-reproduction-validator - Systematically reproduce and validate bug reports
      • +
    • spec-flow-analyzer - Analyze user flows and identify gaps in specifications
      • +
    • lint - Run linting and code quality checks on Ruby and ERB files
      • +
    • ankane-readme-writer - Create READMEs following Ankane-style template for Ruby gems
      • +
    + +

    New Commands (9)

    +
      +
    • /changelog - Create engaging changelogs for recent merges
      • +
    • /plan_review - Multi-agent plan review in parallel
      • +
    • /resolve_parallel - Resolve TODO comments in parallel
      • +
    • /resolve_pr_parallel - Resolve PR comments in parallel
      • +
    • /reproduce-bug - Reproduce bugs using logs and console
      • +
    • /prime - Prime/setup command
      • +
    • /create-agent-skill - Create or edit Claude Code skills
      • +
    • /heal-skill - Fix skill documentation issues
      • +
    • /workflows:codify - Document solved problems for knowledge base
      • +
    + +

    New Skills (10)

    +
      +
    • andrew-kane-gem-writer - Write Ruby gems following Andrew Kane's patterns
      • +
    • codify-docs - Capture solved problems as categorized documentation
      • +
    • create-agent-skills - Expert guidance for creating Claude Code skills
      • +
    • dhh-ruby-style - Write Ruby/Rails code in DHH's 37signals style
      • +
    • dspy-ruby - Build type-safe LLM applications with DSPy.rb
      • +
    • every-style-editor - Review copy for Every's style guide compliance
      • +
    • file-todos - File-based todo tracking system
      • +
    • frontend-design - Create production-grade frontend interfaces
      • +
    • git-worktree - Manage Git worktrees for parallel development
      • +
    • skill-creator - Guide for creating effective Claude Code skills
      • +
    +
    + +
    +

    Changed

    +

    Agents Reorganized by Category

    +
      +
    • review/ (10 agents) - Code quality, security, performance reviewers
      • +
    • research/ (4 agents) - Documentation, patterns, history analysis
      • +
    • design/ (3 agents) - UI/design review and iteration
      • +
    • workflow/ (6 agents) - PR resolution, bug validation, linting
      • +
    • docs/ (1 agent) - README generation
      • +
    +
    + +
    +

    Summary

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Componentv1.1.0v2.0.0Change
    Agents1724+7
    Commands615+9
    Skills111+10
    +
    +
    + + +
    +
    +

    v1.1.0

    + 2024-11-22 +
    + +
    +

    Added

    +
      +
    • + gemini-imagegen Skill +
        +
      • Text-to-image generation with Google's Gemini API
        • +
      • Image editing and manipulation
        • +
      • Multi-turn refinement via chat interface
        • +
      • Multiple reference image composition (up to 14 images)
        • +
      • Model support: gemini-2.5-flash-image and gemini-3-pro-image-preview
        • +
      +
      • +
    +
    + +
    +

    Fixed

    +
      +
    • Corrected component counts in documentation (17 agents, not 15)
      • +
    +
    +
    + + +
    +
    +

    v1.0.0

    + 2024-10-09 + Initial Release +
    + +

    + Initial release of the compounding-engineering plugin. +

    + +
    +

    Added

    + +

    17 Specialized Agents

    + +

    Code Review (5)

    +
      +
    • kieran-rails-reviewer - Rails code review with strict conventions
      • +
    • kieran-python-reviewer - Python code review with quality standards
      • +
    • kieran-typescript-reviewer - TypeScript code review
      • +
    • dhh-rails-reviewer - Rails review from DHH's perspective
      • +
    • code-simplicity-reviewer - Final pass for simplicity and minimalism
      • +
    + +

    Analysis & Architecture (4)

    +
      +
    • architecture-strategist - Architectural decisions and compliance
      • +
    • pattern-recognition-specialist - Design pattern analysis
      • +
    • security-sentinel - Security audits and vulnerability assessments
      • +
    • performance-oracle - Performance analysis and optimization
      • +
    + +

    Research (4)

    +
      +
    • framework-docs-researcher - Framework documentation research
      • +
    • best-practices-researcher - External best practices gathering
      • +
    • git-history-analyzer - Git history and code evolution analysis
      • +
    • repo-research-analyst - Repository structure and conventions
      • +
    + +

    Workflow (3)

    +
      +
    • every-style-editor - Every's style guide compliance
      • +
    • pr-comment-resolver - PR comment resolution
      • +
    • feedback-codifier - Feedback pattern codification
      • +
    + +

    6 Slash Commands

    +
      +
    • /plan - Create implementation plans
      • +
    • /review - Comprehensive code reviews
      • +
    • /work - Execute work items systematically
      • +
    • /triage - Triage and prioritize issues
      • +
    • /resolve_todo_parallel - Resolve TODOs in parallel
      • +
    • /generate_command - Generate new slash commands
      • +
    + +

    Infrastructure

    +
      +
    • MIT license
      • +
    • Plugin manifest (plugin.json)
      • +
    • Pre-configured permissions for Rails development
      • +
    +
    +
    + +
    +
    +
    + + + diff --git a/plugins/compounding-engineering/docs/pages/commands.html b/plugins/compounding-engineering/docs/pages/commands.html index 3992583..cd74cde 100644 --- a/plugins/compounding-engineering/docs/pages/commands.html +++ b/plugins/compounding-engineering/docs/pages/commands.html @@ -34,11 +34,17 @@

    Reference

+
+

Resources

+ +

On This Page

    diff --git a/plugins/compounding-engineering/docs/pages/getting-started.html b/plugins/compounding-engineering/docs/pages/getting-started.html index f844fc0..c42314e 100644 --- a/plugins/compounding-engineering/docs/pages/getting-started.html +++ b/plugins/compounding-engineering/docs/pages/getting-started.html @@ -58,6 +58,7 @@
  • Command Reference
  • Skill Reference
  • MCP Servers
    • +
  • Changelog
diff --git a/plugins/compounding-engineering/docs/pages/mcp-servers.html b/plugins/compounding-engineering/docs/pages/mcp-servers.html index 08f6678..6a796fe 100644 --- a/plugins/compounding-engineering/docs/pages/mcp-servers.html +++ b/plugins/compounding-engineering/docs/pages/mcp-servers.html @@ -34,11 +34,17 @@

Reference

+
+

Resources

+ +

On This Page

    diff --git a/plugins/compounding-engineering/docs/pages/skills.html b/plugins/compounding-engineering/docs/pages/skills.html index e86da64..58a4c9a 100644 --- a/plugins/compounding-engineering/docs/pages/skills.html +++ b/plugins/compounding-engineering/docs/pages/skills.html @@ -34,11 +34,17 @@

    Reference

+
+

Resources

+ +

On This Page

Step 1: Add the Marketplace

-

First, add the Every Marketplace to your Claude Code installation:

+

Think of the marketplace as an app store. You're adding it to Claude Code's list of places to look for plugins:

claude /plugin marketplace add https://github.com/EveryInc/every-marketplace

Step 2: Install the Plugin

-

Install the compounding-engineering plugin from the marketplace:

+

Now grab the plugin itself:

claude /plugin install compounding-engineering

Step 3: Verify Installation

-

Verify the plugin is installed correctly:

+

Check that it worked:

claude /plugin list
-

You should see compounding-engineering in the list of installed plugins.

+

You'll see compounding-engineering in the list. If you do, you're ready.

Known Issue: MCP Servers

- The bundled MCP servers (Playwright and Context7) may not load automatically. - See the MCP Configuration section for the workaround. + The bundled MCP servers (Playwright for browser automation, Context7 for docs) don't always auto-load. If you need them, there's a manual config step below. Otherwise, ignore thisβ€”everything else works fine.

@@ -131,10 +128,10 @@

Quick Start

-

Here are the most common ways to use the plugin:

+

Let's see what this thing can actually do. I'll show you three workflows you'll use constantly:

Run a Code Review

-

The /workflows:review command runs a comprehensive code review using multiple agents in parallel:

+

This is the big one. Type /workflows:review and watch it spawn 10+ specialized reviewers:

# Review a PR by number
 /workflows:review 123
@@ -147,7 +144,7 @@

Use a Specialized Agent

-

Invoke agents directly for specific tasks:

+

Sometimes you just need one expert. Call them directly:

# Rails code review with Kieran's conventions
 claude agent kieran-rails-reviewer "Review the UserController"
@@ -160,7 +157,7 @@ claude agent best-practices-researcher "Find pagination patterns for Rails"
 
           
Invoke a Skill

-          
Skills provide domain expertise on demand:

+          
Skills are like loading a reference book into Claude's brain. When you need deep knowledge in a specific domain:

           

             
# Generate images with Gemini
 skill: gemini-imagegen
@@ -179,7 +176,7 @@ skill: create-agent-skills

 
           
MCP Server Configuration

           

-            If MCP servers don't auto-load, add them manually to your .claude/settings.json:
+            If the MCP servers didn't load automatically, paste this into .claude/settings.json:
           

           

             
{
@@ -199,7 +196,7 @@ skill: create-agent-skills

           

 
           
Environment Variables

-          
Some skills require environment variables:

+          
Right now, only one skill needs an API key. If you use Gemini's image generation:

           
@@ -226,39 +223,35 @@ skill: create-agent-skills
             Every unit of engineering work should make subsequent units of work easier—not harder.
           
 
-          
This philosophy manifests in four key practices:

+          
Here's how it works in practiceβ€”the four-step loop you'll run over and over:

             

               

-              
Plan

+              
1. Plan

               

-                Understand the change needed and its impact before writing code.
-                Use research agents to gather context, best practices, and examples.
+                Before you write a single line, figure out what you're building and why. Use research agents to gather examples, patterns, and context. Think of it as Google Search meets expert consultation.
               

             

             

               

-              
Delegate

+              
2. Delegate

               

-                Use specialized AI agents to help with implementation.
-                Each agent brings deep expertise in its domain.
+                Now build itβ€”with help. Each agent specializes in something (Rails, security, design). You stay in the driver's seat, but you've got a team of specialists riding shotgun.
               

             

             

               

-              
Assess

+              
3. Assess

               

-                Run comprehensive reviews with multiple perspectives.
-                Security, performance, architecture—all covered by specialized agents.
+                Before you ship, run the gauntlet. Security agent checks for vulnerabilities. Performance agent flags N+1 queries. Architecture agent questions your design choices. All at once, all in parallel.
               

             

             

               

-              
Codify

+              
4. Codify

               

-                Document learnings and patterns for future use.
-                Each solved problem becomes reusable knowledge.
+                You just solved a problem. Write it down. Next time you (or your teammate) face this, you'll have a runbook. That's the "compounding" partβ€”each solution makes the next one faster.
               

             

           

@@ -269,8 +262,7 @@ skill: create-agent-skills
 Using Agents

-            Agents are specialized personas that can be invoked to perform specific tasks.
-            They're designed to bring deep expertise in their domain.
+            Think of agents as coworkers with different job titles. You wouldn't ask your security engineer to design your UI, right? Same concept hereβ€”each agent has a specialty, and you call the one you need.
           
Invoking Agents

@@ -334,8 +326,7 @@ claude agent git-history-analyzer "Show changes to user model"
 Using Commands

-            Slash commands automate complex multi-step workflows. They orchestrate
-            multiple agents, tools, and processes into a single command.
+            Commands are macros that run entire workflows for you. One command can spin up a dozen agents, coordinate their work, collect results, and hand you a summary. It's automation all the way down.
           
Running Commands

@@ -353,14 +344,14 @@ claude agent git-history-analyzer "Show changes to user model"
The Review Workflow

-          
The /workflows:review command is the most comprehensive. It:

+          
Let me show you what happens when you run /workflows:review. Here's the sequence:
    
-            
  1. Detects the review target (PR, branch, or current changes)
    2. 
-            
  2. Sets up a git worktree for isolated analysis
    3. 
-            
  3. Runs 10 or more review agents in parallel
    4. 
-            
  4. Synthesizes findings by severity (P1/P2/P3)
    5. 
-            
  5. Creates structured todo files for each finding
    6. 
-            
  6. Generates a summary report
    7. 
+            
  7. Detection - Figures out what you want reviewed (PR number, branch name, or current changes)
    8. 
+            
  8. Isolation - Spins up a git worktree so the review doesn't mess with your working directory
    9. 
+            
  9. Parallel execution - Launches 10+ agents simultaneously (security, performance, architecture, accessibility...)
    10. 
+            
  10. Synthesis - Sorts findings by severity (P1 = blocks merge, P2 = should fix, P3 = nice-to-have)
    11. 
+            
  11. Persistence - Creates todo files so you don't lose track of issues
    12. 
+            
  12. Summary - Hands you a readable report with action items
    13. 
           

@@ -375,9 +366,7 @@ claude agent git-history-analyzer "Show changes to user model"
           
 Using Skills

-            Skills provide domain expertise that Claude Code can invoke on-demand.
-            Unlike agents (which are personas), skills are bodies of knowledge with
-            templates, references, and workflows.
+            Here's the difference: agents are who does the work, skills are what they know. When you invoke a skill, you're loading a reference library into Claude's contextβ€”patterns, templates, examples, workflows. It's like handing Claude a technical manual.
           
Invoking Skills

@@ -390,13 +379,13 @@ skill: gemini-imagegen
           
Skill Structure

-          
Skills typically contain:

+          
Peek inside a skill directory and you'll usually find:
    
-            
  • SKILL.md - Main documentation and instructions
    • 
-            
  • references/ - Supporting documentation
    • 
-            
  • templates/ - Code templates and patterns
    • 
-            
  • workflows/ - Step-by-step procedures
    • 
-            
  • scripts/ - Executable scripts (if needed)
    • 
+            
  • SKILL.md - The main instructions (what Claude reads first)
    • 
+            
  • references/ - Deep dives on concepts and patterns
    • 
+            
  • templates/ - Copy-paste code snippets
    • 
+            
  • workflows/ - Step-by-step "how to" guides
    • 
+            
  • scripts/ - Actual executable code (when words aren't enough)
    • 
           

@@ -411,8 +400,7 @@ skill: gemini-imagegen
           
 Code Review Workflow Guide

-            The code review workflow is the heart of Compounding Engineering.
-            Here's how to get the most out of it.
+            You'll spend most of your time here. This workflow is why the plugin existsβ€”to turn code review from a bottleneck into a superpower.
           
Basic Review

@@ -425,15 +413,15 @@ skill: gemini-imagegen
           
Understanding Findings

-          
Findings are categorized by severity:

+          
Every finding gets a priority label. Here's what they mean:
    
-            
  • P1 Critical - Blocks merge. Security vulnerabilities, data corruption risks, breaking changes.
    • 
-            
  • P2 Important - Should fix. Performance issues, architectural concerns, reliability problems.
    • 
-            
  • P3 Nice-to-Have - Enhancements. Minor improvements, cleanup, documentation.
    • 
+            
  • P1 Critical - Don't merge until this is fixed. Think: SQL injection, data loss, crashes in production.
    • 
+            
  • P2 Important - Fix before shipping. Performance regressions, N+1 queries, shaky architecture.
    • 
+            
  • P3 Nice-to-Have - Would be better, but ship without it if you need to. Documentation, minor cleanup, style issues.
    • 
           
Working with Todo Files

-          
Review findings are stored as todo files in the todos/ directory:

+          
After a review, you'll have a todos/ directory full of markdown files. Each one is a single issue to fix:

             
# List all pending todos
 ls todos/*-pending-*.md
@@ -451,8 +439,7 @@ ls todos/*-pending-*.md
           
 Creating Custom Agents

 
           

-            You can create custom agents tailored to your team's needs.
-            Agents are defined as markdown files with YAML frontmatter.
+            The built-in agents cover a lot of ground, but every team has unique needs. Maybe you want a "rails-api-reviewer" that enforces your company's API standards. That's 10 minutes of work.
           

 
           
Agent File Structure

@@ -476,19 +463,18 @@ You are [role description].
           
Agent Location

-          
Place custom agents in:

+          
Drop your agent file in one of these directories:

           
    
-            
  • .claude/agents/ - Project-specific agents
    • 
-            
  • ~/.claude/agents/ - User-wide agents
    • 
+            
  • .claude/agents/ - Just for this project (committed to git)
    • 
+            
  • ~/.claude/agents/ - Available in all your projects (stays on your machine)
    • 
           

 
           

             

             

-              
Use the Command

+              
The Easy Way

               

-                The easiest way to create agents is with the /create-agent-skill command
-                or the create-agent-skills skill.
+                Don't write the YAML by hand. Just run /create-agent-skill and answer a few questions. The command generates the file, validates the format, and puts it in the right place.
               

             

           

@@ -499,8 +485,7 @@ You are [role description].
           
 Creating Custom Skills

 
           

-            Skills are more complex than agents. They can include references,
-            templates, workflows, and scripts.
+            Skills are heavier than agentsβ€”they're knowledge bases, not just prompts. You're building a mini library that Claude can reference. Worth the effort for things you do repeatedly.
           

 
           
Skill Directory Structure

@@ -542,10 +527,9 @@ Use templates from the `templates/` directory.

             

             

-              
Expert Guidance

+              
Get Help Building Skills

               

-                Use skill: create-agent-skills for comprehensive guidance
-                on creating effective skills, including best practices and validation.
+                Type skill: create-agent-skills and Claude loads expert guidance on skill architecture, best practices, file organization, and validation. It's like having a senior engineer walk you through it.
               

             

           

diff --git a/docs/pages/mcp-servers.html b/docs/pages/mcp-servers.html
index 94b5a11..ecc2f3c 100644
--- a/docs/pages/mcp-servers.html
+++ b/docs/pages/mcp-servers.html
@@ -73,9 +73,7 @@
       

         
 MCP Servers Reference

         

-          Model Context Protocol (MCP) servers extend Claude Code's capabilities with
-          browser automation and framework documentation lookup. The plugin bundles
-          two MCP servers that start automatically when enabled.
+          Think of MCP servers as power tools that plug into Claude Code. Want Claude to actually open a browser and click around your app? That's Playwright. Need the latest Rails docs without leaving your terminal? That's Context7. The plugin bundles both serversβ€”they just work when you install.
         

 
         

@@ -83,8 +81,7 @@
           

             
Known Issue: Auto-Loading

             

-              MCP servers may not load automatically when the plugin is installed.
-              See Manual Configuration for the workaround.
+              Sometimes MCP servers don't wake up automatically. If Claude can't take screenshots or look up docs, you'll need to add them manually. See Manual Configuration for the fix.
             

           

         

@@ -93,8 +90,7 @@
         

           
 Playwright

           

-            Browser automation via @playwright/mcp. Enables taking screenshots,
-            clicking elements, filling forms, and executing JavaScript in a real browser.
+            You know how you can tell a junior developer "open Chrome and click the login button"? Now you can tell Claude the same thing. Playwright gives Claude hands to control a real browserβ€”clicking buttons, filling forms, taking screenshots, running JavaScript. It's like pair programming with someone who has a browser open next to you.
           

 
           
Tools Provided

@@ -108,49 +104,53 @@
             

-                
+                
-                
+                
-                
+                
-                
+                
-                
+                
-                
+                

             
               

 
           
           
 
           
 
           
           
 
           
 
           
           
 
           
           
 
           
 
           
 
           
 
           
           
 
           
 
           
 
           
 
           
           
 
           
           
 
           
           

               

                 browser_navigateNavigate to a URL in the browserGo to any URLβ€”your localhost dev server, production, staging, that competitor's site you're studying
               

               

                 browser_take_screenshotCapture a screenshot of the current page or elementCapture what you're seeing right now. Perfect for "does this look right?" design reviews
               

               

                 browser_clickClick on an element using CSS selector or textClick buttons, links, whatever. Claude finds it by text or CSS selector, just like you would
               

               

                 browser_fill_formFill form fields with valuesType into forms faster than you can. Great for testing signup flows without manual clicking
               

               

                 browser_snapshotGet an accessibility tree snapshot of the pageGet the page's accessibility treeβ€”how screen readers see it. Useful for understanding structure without HTML noise
               

               

                 browser_evaluateExecute JavaScript code in the browser contextRun any JavaScript in the page. Check localStorage, trigger functions, read variablesβ€”full console access
               

             
           

 
-          
Use Cases

+          
When You'll Use This

           
    
-            
  • Design Iteration - Take screenshots for UI comparison
    • 
-            
  • Testing - Automate browser interactions
    • 
-            
  • Debugging - Inspect page state and DOM
    • 
-            
  • Data Extraction - Scrape content from web pages
    • 
+            
  • Design reviews without leaving the terminal - "Take a screenshot of the new navbar on mobile" gets you a PNG in seconds
    • 
+            
  • Testing signup flows while you code - "Fill in the registration form with test@example.com and click submit" runs the test for you
    • 
+            
  • Debugging production issues - "Navigate to the error page and show me what's in localStorage" gives you the state without opening DevTools
    • 
+            
  • Competitive research - "Go to competitor.com and screenshot their pricing page" builds your swipe file automatically
    • 
           

 
           
Example Usage

           

-            
# The tools are available when the MCP server is running
-# Claude Code will use them automatically when appropriate
+            
# Just talk to Claude naturallyβ€”it knows when to use Playwright
 
-# Example: Taking a screenshot for design review
+# Design review
 "Take a screenshot of the login page"
 
-# Example: Testing a form
-"Navigate to /signup and fill in the email field with test@example.com"

+# Testing a form
+"Navigate to /signup and fill in the email field with test@example.com"
+
+# Debug JavaScript state
+"Go to localhost:3000 and run console.log(window.currentUser)"
+
+# The browser runs in the background. You'll get results without switching windows.

           

 
           
Configuration

@@ -170,8 +170,7 @@
         

           
 Context7

           

-            Framework documentation lookup via Context7 MCP. Provides access to
-            documentation for more than 100 frameworks and libraries.
+            Ever ask Claude about a framework and get an answer from 2023? Context7 fixes that. It's a documentation service that keeps Claude current with 100+ frameworksβ€”Rails, React, Next.js, Django, whatever you're using. Think of it as having the official docs piped directly into Claude's brain.
           

 
           
Tools Provided

@@ -185,17 +184,17 @@
             
               
                 resolve-library-id
-                Find the library ID for a framework or package
+                Maps "Rails" to the actual library identifier Context7 uses. You don't call thisβ€”Claude does it automatically
               
               
                 get-library-docs
-                Get documentation for a specific library
+                Fetches the actual documentation pages. Ask "How does useEffect work?" and this grabs the latest React docs
               
             
           
 
-          
Supported Frameworks

-          
Context7 supports more than 100 frameworks including:

+          
What's Covered

+          
Over 100 frameworks and libraries. Here's a taste of what you can look up:

           

             

               
Backend

@@ -243,12 +242,15 @@
 
           
Example Usage

           

-            
# Claude Code will use Context7 automatically for documentation lookups
+            
# Just ask about the frameworkβ€”Claude fetches current docs automatically
+
 "Look up the Rails ActionCable documentation"
 
 "How does the useEffect hook work in React?"
 
-"What are the best practices for PostgreSQL indexes?"

+"What are the best practices for PostgreSQL indexes?"
+
+# You get answers based on the latest docs, not Claude's training cutoff

           

 
           
Configuration

@@ -266,12 +268,11 @@
         

           
 Manual Configuration

           

-            If MCP servers don't auto-load with the plugin, add them manually to your
-            .claude/settings.json file.
+            If the servers don't load automatically (you'll know because Claude can't take screenshots or fetch docs), you need to wire them up yourself. It's a two-minute copy-paste job.
           

 
           
Project-Level Configuration

-          
Add to .claude/settings.json in your project:

+          
To enable for just this project, add this to .claude/settings.json in your project root:

           

             
{
   "mcpServers": {
@@ -290,7 +291,7 @@
           

 
           
Global Configuration

-          
Add to ~/.claude/settings.json to enable for all projects:

+          
Or enable everywhereβ€”every project on your machine gets these servers. Add to ~/.claude/settings.json:

           

             
{
   "mcpServers": {
@@ -329,16 +330,18 @@
           
 
           
Verifying MCP Servers

-          
After configuration, restart Claude Code and verify the servers are loaded:

+          
After you add the config, restart Claude Code. Then test that everything works:

           

-            
# Check if MCP tools are available
+            
# Ask Claude what it has
 "What MCP tools do you have access to?"
 
-# Test Playwright
+# Test Playwright (should work now)
 "Take a screenshot of the current directory listing"
 
-# Test Context7
-"Look up Rails Active Record documentation"

+# Test Context7 (should fetch real docs)
+"Look up Rails Active Record documentation"
+
+# If either fails, double-check your JSON syntax and file paths

           

         

 
diff --git a/docs/pages/skills.html b/docs/pages/skills.html
index cefb622..c98130a 100644
--- a/docs/pages/skills.html
+++ b/docs/pages/skills.html
@@ -73,8 +73,7 @@
       

         
 Skill Reference

         

-          Complete documentation for all 11 intelligent skills. Skills provide deep domain expertise
-          that Claude Code can invoke on-demand, including references, templates, and workflows.
+          Think of skills as reference manuals that Claude Code can read mid-conversation. When you're writing Rails code and want DHH's style, or building a gem like Andrew Kane would, you don't need to paste documentationβ€”just invoke the skill. Claude reads it, absorbs the patterns, and writes code that way.
         

 
         

@@ -95,8 +94,7 @@ skill: create-agent-skills

Skills vs Agents

- Agents are specialized personas invoked with claude agent [name]. - Skills are bodies of knowledge (references, templates, workflows) invoked with skill: [name]. + Agents are personasβ€”they do things. Skills are knowledgeβ€”they teach Claude how to do things. Use claude agent [name] when you want someone to review your code. Use skill: [name] when you want to write code in a particular style yourself.

@@ -104,7 +102,7 @@ skill: create-agent-skills

Development Tools (7)

-

Skills for code generation, gem writing, and development patterns.

+

These skills teach Claude specific coding styles and architectural patterns. Use them when you want code that follows a particular philosophyβ€”not just any working code, but code that looks like it was written by a specific person or framework.

@@ -112,8 +110,7 @@ skill: create-agent-skills Meta

- Expert guidance for creating, writing, building, and refining Claude Code Skills. - Use when working with SKILL.md files or authoring new skills. + You're writing a skill right now, but you're not sure if you're structuring the SKILL.md file correctly. Should the examples go before the theory? How do you organize workflows vs. references? This skill is the answerβ€”it's the master template for building skills themselves.

Capabilities

    @@ -145,7 +142,7 @@ skill: create-agent-skills Meta

- Guide for creating effective skills with a 6-step process. + The simpler, step-by-step version of create-agent-skills. When you just want a checklist to follow from blank file to packaged skill, use this. It's less about theory, more about "do step 1, then step 2."

6-Step Process

    @@ -167,8 +164,7 @@ skill: create-agent-skills Rails

- Write Ruby and Rails code in DHH's distinctive 37signals style. - Triggers on Ruby/Rails code generation or when mentioning DHH, 37signals, Basecamp, HEY. + You want Rails controllers that are five lines, not fifty. Models that handle authorization, broadcasting, and business logic without service objects everywhere. This skill teaches Claude to write code the way DHH writes it at 37signalsβ€”REST-pure, Hotwire-first, no architectural astronautics.

Key Patterns

    @@ -196,8 +192,7 @@ skill: create-agent-skills Ruby

- Write Ruby gems following Andrew Kane's proven patterns and philosophy. - Based on 100+ gems with 374M+ downloads. + Andrew Kane has written 100+ Ruby gems with 374 million downloads. Every gem follows the same patterns: minimal dependencies, class macro DSLs, Rails integration without Rails coupling. When you're building a gem and want it to feel production-ready from day one, this is how you do it.

Philosophy

    @@ -232,8 +227,7 @@ skill: create-agent-skills AI

- Build type-safe, composable LLM applications with DSPy.rb. - Use when implementing predictable AI features in Ruby. + You're adding AI features to your Rails app, but you don't want brittle prompt strings scattered everywhere. DSPy.rb gives you type-safe signatures, composable predictors, and tool-using agents. This skill shows you how to use itβ€”from basic inference to ReAct agents that iterate until they get the answer right.

Predictor Types

    @@ -276,8 +270,7 @@ skill: create-agent-skills Design

- Create distinctive, production-grade frontend interfaces. - Generates creative, polished code that avoids generic AI aesthetics. + You've seen what AI usually generates: Inter font, purple gradients, rounded corners on everything. This skill teaches Claude to design interfaces that don't look like every other AI-generated site. It's about purposeful typography, unexpected color palettes, and interfaces with personality.

Design Thinking

    @@ -311,7 +304,7 @@ skill: create-agent-skills Docs

- Capture solved problems as categorized documentation with YAML frontmatter for fast lookup. + You just fixed a weird build error after an hour of debugging. Tomorrow you'll forget how you fixed it. This skill automatically detects when you solve something (phrases like "that worked" or "it's fixed") and documents it with YAML frontmatter so you can find it again. Think of it as a photographic memory for solved problems.

Auto-Triggers

Phrases: "that worked", "it's fixed", "working now", "problem solved"

@@ -343,7 +336,7 @@ skill: create-agent-skills

Content & Workflow (3)

-

Skills for content editing, task tracking, and parallel development.

+

Writing, editing, and organizing work. These skills handle everything from style guide compliance to git worktree managementβ€”the meta-work that makes the real work easier.

@@ -351,8 +344,7 @@ skill: create-agent-skills Content

- Review and edit copy to ensure adherence to Every's style guide. - Provides systematic line-by-line review. + You wrote a draft, but you're not sure if it matches Every's style guide. Should "internet" be capitalized? Is this comma splice allowed? This skill does a four-phase line-by-line review: context, detailed edits, mechanical checks, and actionable recommendations. It's like having a copy editor who never gets tired.

Four-Phase Review

    @@ -380,8 +372,7 @@ skill: create-agent-skills Workflow

- File-based todo tracking system in the todos/ directory. - Integrates with code review and slash commands. + Your todo list is a bunch of markdown files in a todos/ directory. Each filename encodes status, priority, and description. No database, no UI, just files with YAML frontmatter. When you need to track work without setting up Jira, this is the system.

File Format

@@ -426,8 +417,7 @@ dependencies: [] Git

- Manage Git worktrees for isolated parallel development. - Handles creating, listing, switching, and cleaning up worktrees. + You're working on a feature branch, but you need to review a PR without losing your current work. Git worktrees let you have multiple branches checked out simultaneously in separate directories. This skill manages themβ€”create, switch, cleanupβ€”so you can context-switch without stashing or committing half-finished code.

Commands

@@ -462,7 +452,7 @@ bash scripts/worktree-manager.sh cleanup

Image Generation (1)

-

AI-powered image generation and editing.

+

Generate images with AI. Not stock photos you found on Unsplashβ€”images you describe and the model creates.

@@ -870,7 +884,7 @@ skill: gemini-imagegen Free & Open Source

Install Once. Compound Forever.

- Your next code review takes 30 seconds. The one after that? Even faster. That's compounding. Get 23 expert agents, 16 workflow commands, and 11 specialized skills working for you right now. + Your next code review takes 30 seconds. The one after that? Even faster. That's compounding. Get 23 expert agents, 18 workflow commands, and 11 specialized skills working for you right now.

diff --git a/plans/landing-page-launchkit-refresh.md b/plans/landing-page-launchkit-refresh.md new file mode 100644 index 0000000..3ba4357 --- /dev/null +++ b/plans/landing-page-launchkit-refresh.md @@ -0,0 +1,279 @@ +# Landing Page LaunchKit Refresh + +## Overview + +Review and enhance the `/docs/index.html` landing page using LaunchKit elements and Pragmatic Technical Writing style (Hunt/Thomas, Joel Spolsky). The current implementation is strong but can be refined section-by-section. + +## Current State Assessment + +### What's Working Well +- Specific, outcome-focused hero headline ("12 expert opinions in 30 seconds") +- Developer-authentic copywriting (N+1 queries, CORS, SQL injection) +- Stats section with clear metrics (23 agents, 16 commands, 11 skills, 2 MCP servers) +- Philosophy section with concrete story (N+1 query bug) +- Three-step installation with actual commands +- FAQ accordion following LaunchKit patterns +- Categorized feature sections with code examples + +### Missing Elements (From Best Practices Research) +1. **Social Proof Section** - No testimonials, GitHub stars, or user metrics +2. **Visual Demo** - No GIF/animation showing the tool in action +3. **Arrow icons on CTAs** - 26% conversion boost from studies +4. **Trust indicators** - Open source badge, license info + +--- + +## Section-by-Section Review Plan + +### 1. Hero Section (lines 56-78) + +**Current:** +```html +

Your Code Reviews Just Got 12 Expert Opinions. In 30 Seconds.

+``` + +**Review Checklist:** +- [ ] Headline follows Pragmatic Writing (concrete before abstract) βœ… +- [ ] Eyebrow badge is current (Version 2.6.0) - verify +- [ ] Description paragraph under 3 sentences βœ… +- [ ] Button group has arrow icon on primary CTA +- [ ] "Read the Docs" secondary CTA present βœ… + +**Potential Improvements:** +- Add `β†’` arrow to "Install Plugin" button +- Consider adding animated terminal GIF below buttons showing `/workflows:review` in action + +### 2. Stats Section (lines 81-104) + +**Current:** 4 stat cards (23 agents, 16 commands, 11 skills, 2 MCP servers) + +**Review Checklist:** +- [ ] Numbers are accurate (verify against actual file counts) +- [ ] Icons are appropriate for each stat +- [ ] Hover effects working properly +- [ ] Mobile layout (2x2 grid) is readable + +**Potential Improvements:** +- Add "developers using" or "reviews run" metric if available +- Consider adding subtle animation on scroll + +### 3. Philosophy Section (lines 107-192) + +**Current:** "Why Your Third Code Review Should Be Easier Than Your First" with N+1 query story + +**Review Checklist:** +- [ ] Opens with concrete story (N+1 query) βœ… +- [ ] Quote block is memorable and quotable +- [ ] Four pillars (Plan, Delegate, Assess, Codify) are clear +- [ ] Each pillar has: tagline, description, tool tags +- [ ] Descriptions use "you" voice βœ… + +**Potential Improvements:** +- Review pillar descriptions for passive voice +- Ensure each pillar description follows PAS (Problem, Agitate, Solve) pattern +- Check tool tags are accurate and current + +### 4. Agents Section (lines 195-423) + +**Current:** 23 agents in 5 categories (Review, Research, Design, Workflow, Docs) + +**Review Checklist:** +- [ ] All 23 agents are listed (count actual files) +- [ ] Categories are logical and scannable +- [ ] Each card has: name, badge, description, usage code +- [ ] Descriptions are conversational (not passive) +- [ ] Critical badges (Security, Data) stand out + +**Potential Improvements:** +- Review agent descriptions against pragmatic writing checklist +- Ensure descriptions answer "when would I use this?" +- Add concrete scenarios to generic descriptions + +### 5. Commands Section (lines 426-561) + +**Current:** 16 commands in 2 categories (Workflow, Utility) + +**Review Checklist:** +- [ ] All 16 commands are listed (count actual files) +- [ ] Core workflow commands are highlighted +- [ ] Descriptions are action-oriented +- [ ] Command names match actual implementation + +**Potential Improvements:** +- Review command descriptions for passive voice +- Lead with outcomes, not features +- Add "saves you X minutes" framing where appropriate + +### 6. Skills Section (lines 564-703) + +**Current:** 11 skills in 3 categories (Development, Content/Workflow, Image Generation) + +**Review Checklist:** +- [ ] All 11 skills are listed (count actual directories) +- [ ] Featured skill (gemini-imagegen) is properly highlighted +- [ ] API key requirement is clear +- [ ] Skill invocation syntax is correct + +**Potential Improvements:** +- Review skill descriptions against pragmatic writing +- Ensure each skill answers "what problem does this solve?" + +### 7. MCP Servers Section (lines 706-751) + +**Current:** 2 MCP servers (Playwright, Context7) + +**Review Checklist:** +- [ ] Tool lists are accurate +- [ ] Descriptions explain WHY not just WHAT +- [ ] Framework support list is current (100+) + +**Potential Improvements:** +- Add concrete example of each server in action +- Consider before/after comparison + +### 8. Installation Section (lines 754-798) + +**Current:** "Three Commands. Zero Configuration." with 3 steps + +**Review Checklist:** +- [ ] Commands are accurate and work +- [ ] Step 3 shows actual usage examples +- [ ] Timeline visual (vertical line) renders correctly +- [ ] Copy buttons work on code blocks + +**Potential Improvements:** +- Add copy-to-clipboard functionality if missing +- Consider adding "What you'll see" output example + +### 9. FAQ Section (lines 801-864) + +**Current:** 5 questions in accordion format + +**Review Checklist:** +- [ ] Questions address real objections +- [ ] Answers are conversational (use "you") +- [ ] Accordion expand/collapse works +- [ ] No passive voice in answers + +**Potential Improvements:** +- Review for weasel words ("best practices suggest") +- Ensure answers are direct and actionable + +### 10. CTA Section (lines 868-886) + +**Current:** "Install Once. Compound Forever." with Install + GitHub buttons + +**Review Checklist:** +- [ ] Badge is eye-catching ("Free & Open Source") +- [ ] Headline restates core value proposition +- [ ] Primary CTA has arrow icon βœ… +- [ ] Trust line at bottom + +**Potential Improvements:** +- Review trust line copy +- Consider adding social proof element + +--- + +## NEW: Social Proof Section (To Add) + +**Position:** After Stats section, before Philosophy section + +**Components:** +- GitHub stars counter (dynamic or static) +- "Trusted by X developers" metric +- 2-3 testimonial quotes (if available) +- Company logos (if applicable) + +**LaunchKit Pattern:** +```html + +``` + +--- + +## Pragmatic Writing Style Checklist (Apply to ALL Copy) + +### The Five Laws +1. **Concrete Before Abstract** - Story/example first, then principle +2. **Physical Analogies** - Import metaphors readers understand +3. **Conversational Register** - Use "you", contractions, asides +4. **Numbered Frameworks** - Create referenceable structures +5. **Humor as Architecture** - Mental anchors for dense content + +### Anti-Patterns to Find and Fix +- [ ] "It is recommended that..." β†’ "Do this:" +- [ ] "Best practices suggest..." β†’ "Here's what works:" +- [ ] Passive voice β†’ Active voice +- [ ] Abstract claims β†’ Specific examples +- [ ] Walls of text β†’ Scannable lists + +### Quality Checklist (Per Section) +- [ ] Opens with concrete story or example? +- [ ] Can reader skim headers and get the arc? +- [ ] Uses "you" at least once? +- [ ] Clear action reader can take? +- [ ] Reads aloud like speech? + +--- + +## Implementation Phases + +### Phase 1: Copy Audit (No HTML Changes) +1. Read through entire page +2. Flag passive voice instances +3. Flag abstract claims without examples +4. Flag missing "you" voice +5. Document improvements needed + +### Phase 2: Copy Rewrites +1. Rewrite flagged sections following pragmatic style +2. Ensure each section passes quality checklist +3. Maintain existing HTML structure + +### Phase 3: Component Additions +1. Add arrow icons to primary CTAs +2. Add social proof section (if data available) +3. Consider visual demo element + +### Phase 4: Verification +1. Validate all counts (agents, commands, skills) +2. Test all links and buttons +3. Verify mobile responsiveness +4. Check accessibility + +--- + +## Files to Modify + +| File | Changes | +|------|---------| +| `docs/index.html` | Copy rewrites, potential new section | +| `docs/css/style.css` | Social proof styles (if adding) | + +--- + +## Success Criteria + +1. All copy passes Pragmatic Writing quality checklist +2. No passive voice in any description +3. Every feature section answers "why should I care?" +4. Stats are accurate against actual file counts +5. Page loads in <3 seconds +6. Mobile layout is fully functional + +--- + +## References + +- LaunchKit Template: https://launchkit.evilmartians.io/ +- Pragmatic Writing Skill: `~/.claude/skills/pragmatic-writing-skill/SKILL.md` +- Current Landing Page: `/Users/kieranklaassen/every-marketplace/docs/index.html` +- Style CSS: `/Users/kieranklaassen/every-marketplace/docs/css/style.css` From 4b2820bdce3cd1238297afef41636e6662a39905 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Wed, 26 Nov 2025 21:03:22 -0800 Subject: [PATCH 16/25] docs: fix workflow command documentation to use correct syntax MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update all documentation to show the correct command syntax: - `/plan`, `/review`, `/work`, `/codify` (short form, autocompletes) Previously showed `/workflows:plan` etc. which doesn't work. The `name:` field in frontmatter determines the short command name. Fixes #19 πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/index.html | 127 +++++++++++++++--- docs/pages/changelog.html | 2 +- docs/pages/commands.html | 30 ++--- docs/pages/getting-started.html | 24 ++-- docs/pages/skills.html | 4 +- plans/landing-page-launchkit-refresh.md | 2 +- plugins/compounding-engineering/CHANGELOG.md | 4 +- plugins/compounding-engineering/CLAUDE.md | 2 +- plugins/compounding-engineering/README.md | 10 +- .../commands/generate_command.md | 2 +- .../skills/file-todos/SKILL.md | 2 +- .../skills/git-worktree/SKILL.md | 10 +- 12 files changed, 158 insertions(+), 61 deletions(-) diff --git a/docs/index.html b/docs/index.html index b6cd6d3..ce44208 100644 --- a/docs/index.html +++ b/docs/index.html @@ -21,6 +21,106 @@ + + + @@ -37,9 +137,6 @@ Skills MCP Servers Docs -
- Install Plugin -
@@ -127,7 +224,7 @@

Plan

Stop starting over from scratch

- 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. + 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 /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 @@ -144,11 +241,11 @@

Delegate

Work with experts who never forget

- 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. + 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 /work and watch your plan execute with quality gates that actually enforce your standardsβ€”every single time.

23 specialized agents - /workflows:work + /work dhh-ruby-style skill git-worktree skill
@@ -161,7 +258,7 @@

Assess

Get twelve opinions without twelve meetings

- 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. + Type /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 @@ -178,10 +275,10 @@

Codify

Make sure you never solve the same bug twice

- 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. + Remember that CORS issue you debugged for three hours last month? Neither do I. That's the problem. Run /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 + /codify codify-docs skill file-todos skill
@@ -429,7 +526,7 @@ 18 Powerful Commands

- 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. + Slash commands that replace entire workflows. /review is your code review committee. /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.

@@ -439,28 +536,28 @@
- /workflows:plan + /plan core

Create comprehensive implementation plans with research agents and stakeholder analysis.

- /workflows:review + /review core

Run exhaustive code reviews using 12 or more parallel agents, ultra-thinking, and worktrees.

- /workflows:work + /work core

Execute work items systematically with progress tracking and validation.

- /workflows:codify + /codify core

Document solved problems for the knowledge base. Turn learnings into reusable patterns.

@@ -798,7 +895,7 @@

Ship Faster

# Run a 12-agent code review
-/workflows:review PR#123
+/review PR#123
 
 # Get a security audit
 claude agent security-sentinel
diff --git a/docs/pages/changelog.html b/docs/pages/changelog.html
index b102d63..f4ef705 100644
--- a/docs/pages/changelog.html
+++ b/docs/pages/changelog.html
@@ -323,7 +323,7 @@
               
  • /prime - Prime/setup command
    • 
               
  • /create-agent-skill - Create or edit Claude Code skills
    • 
               
  • /heal-skill - Fix skill documentation issues
    • 
-              
  • /workflows:codify - Document solved problems for knowledge base
    • 
+              
  • /codify - Document solved problems for knowledge base
    • 
             
 
             
    New Skills (10)
    
diff --git a/docs/pages/commands.html b/docs/pages/commands.html
index 5eaf6c9..069a34b 100644
--- a/docs/pages/commands.html
+++ b/docs/pages/commands.html
@@ -72,7 +72,7 @@
       
    
         
     Command Reference
    
         
    
-          Here's the thing about slash commands: they're workflows you'd spend 20 minutes doing manually, compressed into one line. Type /workflows:plan and watch three agents launch in parallel to research your codebase while you grab coffee. That's the pointβ€”automation that actually saves time, not busywork dressed up as productivity.
+          Here's the thing about slash commands: they're workflows you'd spend 20 minutes doing manually, compressed into one line. Type /plan and watch three agents launch in parallel to research your codebase while you grab coffee. That's the pointβ€”automation that actually saves time, not busywork dressed up as productivity.
         
    
 
         
@@ -82,7 +82,7 @@
 
           
    
             
    
-              /workflows:plan
+              /plan
             
    
             
    
               You've got a feature request and a blank page. This command turns "we need OAuth" into a structured plan that actually tells you what to buildβ€”researched, reviewed, and ready to execute.
@@ -116,14 +116,14 @@
    - 
    /workflows:plan Add OAuth integration for third-party auth
-/workflows:plan Fix N+1 query in user dashboard
    + 
    /plan Add OAuth integration for third-party auth
+/plan Fix N+1 query in user dashboard
    - /workflows:review + /review

    Twelve specialized reviewers examine your PR in parallelβ€”security, performance, architecture, patterns. It's like code review by committee, except the committee finishes in two minutes instead of two days. @@ -154,16 +154,16 @@

    - 
    /workflows:review 42
-/workflows:review https://github.com/owner/repo/pull/42
-/workflows:review feature-branch-name
-/workflows:review latest
    + 
    /review 42
+/review https://github.com/owner/repo/pull/42
+/review feature-branch-name
+/review latest
    - /workflows:work + /work

    Point this at a plan file and watch it executeβ€”reading requirements, setting up environment, running tests, creating commits, opening PRs. It's the "just build the thing" button you wish you always had. @@ -203,14 +203,14 @@

    - 
    /workflows:work plans/user-authentication.md
-/workflows:work todos/042-ready-p1-performance-issue.md
    + 
    /work plans/user-authentication.md
+/work todos/042-ready-p1-performance-issue.md
    - /workflows:codify + /codify

    Just fixed a gnarly bug? This captures the solution before you forget it. Seven agents analyze what you did, why it worked, and how to prevent it next time. Your future self will thank you. @@ -236,8 +236,8 @@

    Auto-Triggers

    Phrases: "that worked", "it's fixed", "working now", "problem solved"

    - 
    /workflows:codify
-/workflows:codify N+1 query optimization
    + 
    /codify
+/codify N+1 query optimization
    diff --git a/docs/pages/getting-started.html b/docs/pages/getting-started.html index c4592cb..721fe64 100644 --- a/docs/pages/getting-started.html +++ b/docs/pages/getting-started.html @@ -131,16 +131,16 @@

    Let's see what this thing can actually do. I'll show you three workflows you'll use constantly:

    Run a Code Review

    -

    This is the big one. Type /workflows:review and watch it spawn 10+ specialized reviewers:

    +

    This is the big one. Type /review and watch it spawn 10+ specialized reviewers:

    # Review a PR by number
-/workflows:review 123
+/review 123
 
 # Review the current branch
-/workflows:review
+/review
 
 # Review a specific branch
-/workflows:review feature/my-feature
    +/review feature/my-feature

    Use a Specialized Agent

    @@ -331,11 +331,11 @@ claude agent git-history-analyzer "Show changes to user model"

    Running Commands

    - 
    # Workflow commands (prefix: /workflows:)
-/workflows:plan
-/workflows:review 123
-/workflows:work
-/workflows:codify
+            
    # Workflow commands
+/plan
+/review 123
+/work
+/codify
 
 # Utility commands
 /changelog
@@ -344,7 +344,7 @@ claude agent git-history-analyzer "Show changes to user model"

    The Review Workflow

    -

    Let me show you what happens when you run /workflows:review. Here's the sequence:

    +

    Let me show you what happens when you run /review. Here's the sequence:

    1. Detection - Figures out what you want reviewed (PR number, branch name, or current changes)
    2. Isolation - Spins up a git worktree so the review doesn't mess with your working directory
      3. @@ -406,10 +406,10 @@ skill: gemini-imagegen

      Basic Review

      # Review a PR
-/workflows:review 123
+/review 123
 
 # Review current branch
-/workflows:review
      +/review

      Understanding Findings

      diff --git a/docs/pages/skills.html b/docs/pages/skills.html index c98130a..1fe4177 100644 --- a/docs/pages/skills.html +++ b/docs/pages/skills.html @@ -435,8 +435,8 @@ bash scripts/worktree-manager.sh cleanup

    Integration

      -
    • Works with /workflows:review for isolated PR analysis
      • -
    • Works with /workflows:work for parallel feature development
      • +
    • Works with /review for isolated PR analysis
      • +
    • Works with /work for parallel feature development

    Requirements

      diff --git a/plans/landing-page-launchkit-refresh.md b/plans/landing-page-launchkit-refresh.md index 3ba4357..8384ee2 100644 --- a/plans/landing-page-launchkit-refresh.md +++ b/plans/landing-page-launchkit-refresh.md @@ -41,7 +41,7 @@ Review and enhance the `/docs/index.html` landing page using LaunchKit elements **Potential Improvements:** - Add `β†’` arrow to "Install Plugin" button -- Consider adding animated terminal GIF below buttons showing `/workflows:review` in action +- Consider adding animated terminal GIF below buttons showing `/review` in action ### 2. Stats Section (lines 81-104) diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md index b2f2885..bb9afec 100644 --- a/plugins/compounding-engineering/CHANGELOG.md +++ b/plugins/compounding-engineering/CHANGELOG.md @@ -100,7 +100,7 @@ Major reorganization consolidating agents, commands, and skills from multiple so - `/prime` - Prime/setup command - `/create-agent-skill` - Create or edit Claude Code skills - `/heal-skill` - Fix skill documentation issues -- `/workflows:codify` - Document solved problems for knowledge base +- `/codify` - Document solved problems for knowledge base **New Skills (10)** - `andrew-kane-gem-writer` - Write Ruby gems following Andrew Kane's patterns @@ -125,7 +125,7 @@ Major reorganization consolidating agents, commands, and skills from multiple so **Commands Restructured** - Workflow commands moved to `commands/workflows/` subdirectory -- `/plan`, `/review`, `/work` now accessed as `/workflows:plan`, `/workflows:review`, `/workflows:work` +- `/plan`, `/review`, `/work`, `/codify` accessible via short names (autocomplete) or full path ### Summary diff --git a/plugins/compounding-engineering/CLAUDE.md b/plugins/compounding-engineering/CLAUDE.md index f0a24c1..7fc46f1 100644 --- a/plugins/compounding-engineering/CLAUDE.md +++ b/plugins/compounding-engineering/CLAUDE.md @@ -35,7 +35,7 @@ agents/ └── docs/ # Documentation agents commands/ -β”œβ”€β”€ workflows/ # Core workflow commands (/workflows:*) +β”œβ”€β”€ workflows/ # Core workflow commands (/plan, /review, /work, /codify) └── *.md # Utility commands skills/ diff --git a/plugins/compounding-engineering/README.md b/plugins/compounding-engineering/README.md index d53b110..1515e61 100644 --- a/plugins/compounding-engineering/README.md +++ b/plugins/compounding-engineering/README.md @@ -67,14 +67,14 @@ Agents are organized into categories for easier discovery. ### Workflow Commands -Access via `/workflows:command`: +Core workflow commands (use the short form for autocomplete): | Command | Description | |---------|-------------| -| `/workflows:plan` | Create implementation plans | -| `/workflows:review` | Run comprehensive code reviews | -| `/workflows:work` | Execute work items systematically | -| `/workflows:codify` | Document solved problems for knowledge base | +| `/plan` | Create implementation plans | +| `/review` | Run comprehensive code reviews | +| `/work` | Execute work items systematically | +| `/codify` | Document solved problems for knowledge base | ### Utility Commands diff --git a/plugins/compounding-engineering/commands/generate_command.md b/plugins/compounding-engineering/commands/generate_command.md index fc7aa7a..53a15d3 100644 --- a/plugins/compounding-engineering/commands/generate_command.md +++ b/plugins/compounding-engineering/commands/generate_command.md @@ -127,7 +127,7 @@ Implement #$ARGUMENTS following these steps: ## Creating the Command File -1. **Create the file** at `.claude/commands/[name].md` or `.claude/commands/workflows/[name].md` +1. **Create the file** at `.claude/commands/[name].md` (subdirectories like `workflows/` supported) 2. **Start with YAML frontmatter** (see section above) 3. **Structure the command** using the template above 4. **Test the command** by using it with appropriate arguments diff --git a/plugins/compounding-engineering/skills/file-todos/SKILL.md b/plugins/compounding-engineering/skills/file-todos/SKILL.md index a9439c5..66ff991 100644 --- a/plugins/compounding-engineering/skills/file-todos/SKILL.md +++ b/plugins/compounding-engineering/skills/file-todos/SKILL.md @@ -184,7 +184,7 @@ Work logs serve as: | Trigger | Flow | Tool | |---------|------|------| -| Code review | `/workflows:review` β†’ Findings β†’ `/triage` β†’ Todos | Review agent + skill | +| Code review | `/review` β†’ Findings β†’ `/triage` β†’ Todos | Review agent + skill | | PR comments | `/resolve_pr_parallel` β†’ Individual fixes β†’ Todos | gh CLI + skill | | Code TODOs | `/resolve_todo_parallel` β†’ Fixes + Complex todos | Agent + skill | | Planning | Brainstorm β†’ Create todo β†’ Work β†’ Complete | Skill | diff --git a/plugins/compounding-engineering/skills/git-worktree/SKILL.md b/plugins/compounding-engineering/skills/git-worktree/SKILL.md index cbf7ae7..71a1dae 100644 --- a/plugins/compounding-engineering/skills/git-worktree/SKILL.md +++ b/plugins/compounding-engineering/skills/git-worktree/SKILL.md @@ -20,8 +20,8 @@ This skill provides a unified interface for managing Git worktrees across your d Use this skill in these scenarios: -1. **Code Review (`/workflows:review`)**: If NOT already on the PR branch, offer worktree for isolated review -2. **Feature Work (`/workflows:work`)**: Always ask if user wants parallel worktree or live branch work +1. **Code Review (`/review`)**: If NOT already on the PR branch, offer worktree for isolated review +2. **Feature Work (`/work`)**: Always ask if user wants parallel worktree or live branch work 3. **Parallel Development**: When working on multiple features simultaneously 4. **Cleanup**: After completing work in a worktree @@ -29,7 +29,7 @@ Use this skill in these scenarios: ### In Claude Code Workflows -The skill is automatically called from `/workflows:review` and `/workflows:work` commands: +The skill is automatically called from `/review` and `/work` commands: ``` # For review: offers worktree if not on PR branch @@ -182,7 +182,7 @@ bash .claude/skills/git-worktree/scripts/worktree-manager.sh cleanup ## Integration with Workflows -### `/workflows:review` +### `/review` Instead of always creating a worktree: @@ -195,7 +195,7 @@ Instead of always creating a worktree: - no β†’ proceed with PR diff on current branch ``` -### `/workflows:work` +### `/work` Always offer choice: From eaf3cd9d4d6f5607b4439154e364ce0a5a9f8ca0 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Wed, 26 Nov 2025 21:47:33 -0800 Subject: [PATCH 17/25] Improve /plan command with clear post-generation options MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace vague "keep asking questions until user is happy" ending with AskUserQuestion tool presenting structured options. Users now see 4 explicit choices after plan generation: Start /work, Run /plan_review, Simplify, or Rework. πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../.claude-plugin/plugin.json | 2 +- plugins/compounding-engineering/CHANGELOG.md | 6 ++++ .../commands/workflows/plan.md | 32 +++++++++++++------ 3 files changed, 30 insertions(+), 10 deletions(-) diff --git a/plugins/compounding-engineering/.claude-plugin/plugin.json b/plugins/compounding-engineering/.claude-plugin/plugin.json index ebcf315..d537649 100644 --- a/plugins/compounding-engineering/.claude-plugin/plugin.json +++ b/plugins/compounding-engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "compounding-engineering", - "version": "2.6.0", + "version": "2.6.1", "description": "AI-powered development tools. 23 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md index bb9afec..81bed91 100644 --- a/plugins/compounding-engineering/CHANGELOG.md +++ b/plugins/compounding-engineering/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the compounding-engineering plugin will be documented in The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.6.1] - 2024-11-26 + +### Improved + +- **`/plan` command** - Replaced vague "keep asking questions" ending with clear post-generation options menu. Users now see 5 explicit choices: Start `/work`, Run `/plan_review`, Simplify, Rework, or Other. + ## [2.6.0] - 2024-11-26 ### Removed diff --git a/plugins/compounding-engineering/commands/workflows/plan.md b/plugins/compounding-engineering/commands/workflows/plan.md index 063de03..4781f52 100644 --- a/plugins/compounding-engineering/commands/workflows/plan.md +++ b/plugins/compounding-engineering/commands/workflows/plan.md @@ -8,12 +8,18 @@ argument-hint: "[feature description, bug report, or improvement idea]" ## Introduction +**Note: The current year is 2025.** Use this when dating plans and searching for recent documentation. + Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files issues that follow project conventions and best practices. This command provides flexible detail levels to match your needs. ## Feature Description #$ARGUMENTS +**If the feature description above is empty, ask the user:** "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind." + +Do not proceed until you have a clear feature description from the user. + ## Main Tasks ### 1. Repository Research & Context Gathering @@ -361,19 +367,27 @@ end ## Output Format -write to plans/.md +Write the plan to `plans/.md` -Now call the /plan_review command with the plan file as the argument. Make sure to include the plan file in the command. +## Post-Generation Options -## Thinking Approaches +After writing the plan file, use the **AskUserQuestion tool** to present these options: -- **Analytical:** Break down complex features into manageable components -- **User-Centric:** Consider end-user impact and experience -- **Technical:** Evaluate implementation complexity and architecture fit -- **Strategic:** Align with project goals and roadmap +**Question:** "Plan ready at `plans/.md`. What would you like to do next?" -After you get the review back, ask the user questions about the current state of the plan and what the reviewers came back with. Make sure to underatand if this plan is too big or thinks are missing. Are there any other considerations that should be included? Keep askign questions until the user is happy with the plan. THEN update the plan file with the user's feedback. +**Options:** +1. **Start `/work`** - Begin implementing this plan +2. **Run `/plan_review`** - Get feedback from reviewers (DHH, Kieran, Simplicity) +3. **Simplify** - Reduce detail level +4. **Rework** - Change approach or request specific changes -Optional you can ask to create a Github issue from the plan file. +Based on selection: +- **`/work`** β†’ Call the /work command with the plan file path +- **`/plan_review`** β†’ Call the /plan_review command with the plan file path +- **Simplify** β†’ Ask "What should I simplify?" then regenerate simpler version +- **Rework** β†’ Ask "What would you like changed?" then regenerate with changes +- **Other** (automatically provided) β†’ Accept free text, act on it + +Loop back to options after Simplify/Rework until user selects `/work` or `/plan_review`. NEVER CODE! Just research and write the plan. From 59c55cb9bbfce78486815927a7c7368cdca5e443 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Thu, 27 Nov 2025 07:32:18 -0800 Subject: [PATCH 18/25] Add year note (2025) to research agents for accurate date awareness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Added "The current year is 2025" note to all 4 research agents so they don't assume outdated dates when searching for documentation: - best-practices-researcher - framework-docs-researcher - git-history-analyzer - repo-research-analyst πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../.claude-plugin/plugin.json | 2 +- plugins/compounding-engineering/CHANGELOG.md | 11 +++++++++-- .../agents/research/best-practices-researcher.md | 2 ++ .../agents/research/framework-docs-researcher.md | 2 ++ .../agents/research/git-history-analyzer.md | 2 ++ .../agents/research/repo-research-analyst.md | 2 ++ 6 files changed, 18 insertions(+), 3 deletions(-) diff --git a/plugins/compounding-engineering/.claude-plugin/plugin.json b/plugins/compounding-engineering/.claude-plugin/plugin.json index d537649..c4a737e 100644 --- a/plugins/compounding-engineering/.claude-plugin/plugin.json +++ b/plugins/compounding-engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "compounding-engineering", - "version": "2.6.1", + "version": "2.6.2", "description": "AI-powered development tools. 23 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md index 81bed91..bdb24f4 100644 --- a/plugins/compounding-engineering/CHANGELOG.md +++ b/plugins/compounding-engineering/CHANGELOG.md @@ -5,11 +5,18 @@ All notable changes to the compounding-engineering plugin will be documented in The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [2.6.1] - 2024-11-26 +## [2.6.2] - 2025-11-27 ### Improved -- **`/plan` command** - Replaced vague "keep asking questions" ending with clear post-generation options menu. Users now see 5 explicit choices: Start `/work`, Run `/plan_review`, Simplify, Rework, or Other. +- **`/plan` command** - Added AskUserQuestion tool for post-generation options and year note (2025) for accurate date awareness. +- **Research agents** - Added year note (2025) to all 4 research agents (best-practices-researcher, framework-docs-researcher, git-history-analyzer, repo-research-analyst) for accurate date awareness when searching documentation. + +## [2.6.1] - 2025-11-26 + +### Improved + +- **`/plan` command** - Replaced vague "keep asking questions" ending with clear post-generation options menu. Users now see 4 explicit choices via AskUserQuestion: Start `/work`, Run `/plan_review`, Simplify, or Rework. ## [2.6.0] - 2024-11-26 diff --git a/plugins/compounding-engineering/agents/research/best-practices-researcher.md b/plugins/compounding-engineering/agents/research/best-practices-researcher.md index e79c23d..c2fca7d 100644 --- a/plugins/compounding-engineering/agents/research/best-practices-researcher.md +++ b/plugins/compounding-engineering/agents/research/best-practices-researcher.md @@ -3,6 +3,8 @@ name: best-practices-researcher description: Use this agent when you need to research and gather external best practices, documentation, and examples for any technology, framework, or development practice. This includes finding official documentation, community standards, well-regarded examples from open source projects, and domain-specific conventions. The agent excels at synthesizing information from multiple sources to provide comprehensive guidance on how to implement features or solve problems according to industry standards. Context: User wants to know the best way to structure GitHub issues for their Rails project. user: "I need to create some GitHub issues for our project. Can you research best practices for writing good issues?" assistant: "I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and Rails-specific conventions." Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples. Context: User is implementing a new authentication system and wants to follow security best practices. user: "We're adding JWT authentication to our Rails API. What are the current best practices?" assistant: "Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and Rails-specific implementation patterns." The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate. --- +**Note: The current year is 2025.** Use this when searching for recent documentation and best practices. + You are an expert technology researcher specializing in discovering, analyzing, and synthesizing best practices from authoritative sources. Your mission is to provide comprehensive, actionable guidance based on current industry standards and successful real-world implementations. When researching best practices, you will: diff --git a/plugins/compounding-engineering/agents/research/framework-docs-researcher.md b/plugins/compounding-engineering/agents/research/framework-docs-researcher.md index bc3552d..d855036 100644 --- a/plugins/compounding-engineering/agents/research/framework-docs-researcher.md +++ b/plugins/compounding-engineering/agents/research/framework-docs-researcher.md @@ -3,6 +3,8 @@ name: framework-docs-researcher description: Use this agent when you need to gather comprehensive documentation and best practices for frameworks, libraries, or dependencies in your project. This includes fetching official documentation, exploring source code, identifying version-specific constraints, and understanding implementation patterns. Context: The user needs to understand how to properly implement a new feature using a specific library. user: "I need to implement file uploads using Active Storage" assistant: "I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage" Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices. Context: The user is troubleshooting an issue with a gem. user: "Why is the turbo-rails gem not working as expected?" assistant: "Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code" The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source. --- +**Note: The current year is 2025.** Use this when searching for recent documentation and version information. + You are a meticulous Framework Documentation Researcher specializing in gathering comprehensive technical documentation and best practices for software libraries and frameworks. Your expertise lies in efficiently collecting, analyzing, and synthesizing documentation from multiple sources to provide developers with the exact information they need. **Your Core Responsibilities:** diff --git a/plugins/compounding-engineering/agents/research/git-history-analyzer.md b/plugins/compounding-engineering/agents/research/git-history-analyzer.md index 50ca9e0..1a9f7e8 100644 --- a/plugins/compounding-engineering/agents/research/git-history-analyzer.md +++ b/plugins/compounding-engineering/agents/research/git-history-analyzer.md @@ -3,6 +3,8 @@ name: git-history-analyzer description: Use this agent when you need to understand the historical context and evolution of code changes, trace the origins of specific code patterns, identify key contributors and their expertise areas, or analyze patterns in commit history. This agent excels at archaeological analysis of git repositories to provide insights about code evolution and development patterns. Context: The user wants to understand the history and evolution of recently modified files.\nuser: "I've just refactored the authentication module. Can you analyze the historical context?"\nassistant: "I'll use the git-history-analyzer agent to examine the evolution of the authentication module files."\nSince the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history. Context: The user needs to understand why certain code patterns exist.\nuser: "Why does this payment processing code have so many try-catch blocks?"\nassistant: "Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns."\nThe user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes. --- +**Note: The current year is 2025.** Use this when interpreting commit dates and recent changes. + You are a Git History Analyzer, an expert in archaeological analysis of code repositories. Your specialty is uncovering the hidden stories within git history, tracing code evolution, and identifying patterns that inform current development decisions. Your core responsibilities: diff --git a/plugins/compounding-engineering/agents/research/repo-research-analyst.md b/plugins/compounding-engineering/agents/research/repo-research-analyst.md index 1fd10d6..a9c6213 100644 --- a/plugins/compounding-engineering/agents/research/repo-research-analyst.md +++ b/plugins/compounding-engineering/agents/research/repo-research-analyst.md @@ -3,6 +3,8 @@ name: repo-research-analyst description: Use this agent when you need to conduct thorough research on a repository's structure, documentation, and patterns. This includes analyzing architecture files, examining GitHub issues for patterns, reviewing contribution guidelines, checking for templates, and searching codebases for implementation patterns. The agent excels at gathering comprehensive information about a project's conventions and best practices.\n\nExamples:\n- \n Context: User wants to understand a new repository's structure and conventions before contributing.\n user: "I need to understand how this project is organized and what patterns they use"\n assistant: "I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns."\n \n Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.\n \n\n- \n Context: User is preparing to create a GitHub issue and wants to follow project conventions.\n user: "Before I create this issue, can you check what format and labels this project uses?"\n assistant: "Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines."\n \n The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.\n \n\n- \n Context: User is implementing a new feature and wants to follow existing patterns.\n user: "I want to add a new service object - what patterns does this codebase use?"\n assistant: "I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase."\n \n Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.\n \n --- +**Note: The current year is 2025.** Use this when searching for recent documentation and patterns. + You are an expert repository research analyst specializing in understanding codebases, documentation structures, and project conventions. Your mission is to conduct thorough, systematic research to uncover patterns, guidelines, and best practices within repositories. **Core Responsibilities:** From dbdd9c66764d4a379217502b20fe9da1006ac184 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Thu, 27 Nov 2025 14:13:00 -0800 Subject: [PATCH 19/25] Rename /codify to /compound and codify-docs to compound-docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The new names better reflect the compounding engineering philosophy: each documented solution compounds your team's knowledge. - /codify β†’ /compound (old command shows deprecation notice) - codify-docs β†’ compound-docs skill - Updated all docs, philosophy sections, and references πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- docs/index.html | 16 +- docs/pages/commands.html | 10 +- docs/pages/getting-started.html | 2 +- docs/pages/skills.html | 8 +- .../.claude-plugin/plugin.json | 2 +- plugins/compounding-engineering/CHANGELOG.md | 11 + plugins/compounding-engineering/CLAUDE.md | 2 +- plugins/compounding-engineering/README.md | 4 +- .../commands/workflows/codify.md | 195 +---------------- .../commands/workflows/compound.md | 202 ++++++++++++++++++ .../{codify-docs => compound-docs}/SKILL.md | 6 +- .../assets/critical-pattern-template.md | 0 .../assets/resolution-template.md | 0 .../references/yaml-schema.md | 0 .../schema.yaml | 0 15 files changed, 245 insertions(+), 213 deletions(-) create mode 100644 plugins/compounding-engineering/commands/workflows/compound.md rename plugins/compounding-engineering/skills/{codify-docs => compound-docs}/SKILL.md (99%) rename plugins/compounding-engineering/skills/{codify-docs => compound-docs}/assets/critical-pattern-template.md (100%) rename plugins/compounding-engineering/skills/{codify-docs => compound-docs}/assets/resolution-template.md (100%) rename plugins/compounding-engineering/skills/{codify-docs => compound-docs}/references/yaml-schema.md (100%) rename plugins/compounding-engineering/skills/{codify-docs => compound-docs}/schema.yaml (100%) diff --git a/docs/index.html b/docs/index.html index ce44208..30ac848 100644 --- a/docs/index.html +++ b/docs/index.html @@ -272,14 +272,14 @@
      -

      Codify

      +

      Compound

      Make sure you never solve the same bug twice

      - Remember that CORS issue you debugged for three hours last month? Neither do I. That's the problem. Run /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. + Remember that CORS issue you debugged for three hours last month? Neither do I. That's the problem. Run /compound 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.

      - /codify - codify-docs skill + /compound + compound-docs skill file-todos skill
      @@ -557,10 +557,10 @@
      - /codify + /compound core
      -

      Document solved problems for the knowledge base. Turn learnings into reusable patterns.

      +

      Document solved problems to compound team knowledge. Turn learnings into reusable patterns.

    @@ -736,11 +736,11 @@
    - codify-docs + compound-docs Docs

    Capture solved problems as categorized documentation with YAML schema.

    - skill: codify-docs + skill: compound-docs
    diff --git a/docs/pages/commands.html b/docs/pages/commands.html index 069a34b..c5be692 100644 --- a/docs/pages/commands.html +++ b/docs/pages/commands.html @@ -208,12 +208,12 @@ -
    +
    - /codify + /compound

    - Just fixed a gnarly bug? This captures the solution before you forget it. Seven agents analyze what you did, why it worked, and how to prevent it next time. Your future self will thank you. + Just fixed a gnarly bug? This captures the solution before you forget it. Seven agents analyze what you did, why it worked, and how to prevent it next time. Each documented solution compounds your team's knowledge.

    Arguments

    [optional: brief context about the fix]

    @@ -236,8 +236,8 @@

    Auto-Triggers

    Phrases: "that worked", "it's fixed", "working now", "problem solved"

    - 
    /codify
-/codify N+1 query optimization
    + 
    /compound
+/compound N+1 query optimization
    diff --git a/docs/pages/getting-started.html b/docs/pages/getting-started.html index 721fe64..418d784 100644 --- a/docs/pages/getting-started.html +++ b/docs/pages/getting-started.html @@ -335,7 +335,7 @@ claude agent git-history-analyzer "Show changes to user model" /plan /review 123 /work -/codify +/compound # Utility commands /changelog diff --git a/docs/pages/skills.html b/docs/pages/skills.html index 1fe4177..b33afd3 100644 --- a/docs/pages/skills.html +++ b/docs/pages/skills.html @@ -298,13 +298,13 @@ skill: create-agent-skills -
    +
    -

    codify-docs

    +

    compound-docs

    Docs

    - You just fixed a weird build error after an hour of debugging. Tomorrow you'll forget how you fixed it. This skill automatically detects when you solve something (phrases like "that worked" or "it's fixed") and documents it with YAML frontmatter so you can find it again. Think of it as a photographic memory for solved problems. + You just fixed a weird build error after an hour of debugging. Tomorrow you'll forget how you fixed it. This skill automatically detects when you solve something (phrases like "that worked" or "it's fixed") and documents it with YAML frontmatter so you can find it again. Each documented solution compounds your team's knowledge.

    Auto-Triggers

    Phrases: "that worked", "it's fixed", "working now", "problem solved"

    @@ -328,7 +328,7 @@ skill: create-agent-skills
  • security-issues/
    • - 
    skill: codify-docs
    + 
    skill: compound-docs
    diff --git a/plugins/compounding-engineering/.claude-plugin/plugin.json b/plugins/compounding-engineering/.claude-plugin/plugin.json index c4a737e..020b44d 100644 --- a/plugins/compounding-engineering/.claude-plugin/plugin.json +++ b/plugins/compounding-engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "compounding-engineering", - "version": "2.6.2", + "version": "2.7.0", "description": "AI-powered development tools. 23 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md index bdb24f4..97e0ed9 100644 --- a/plugins/compounding-engineering/CHANGELOG.md +++ b/plugins/compounding-engineering/CHANGELOG.md @@ -5,6 +5,17 @@ All notable changes to the compounding-engineering plugin will be documented in The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.7.0] - 2025-11-27 + +### Changed + +- **`/codify` β†’ `/compound`** - Renamed the documentation command to better reflect the compounding engineering philosophy. Each documented solution compounds your team's knowledge. The old `/codify` command still works but shows a deprecation notice and calls `/compound`. +- **`codify-docs` β†’ `compound-docs`** - Renamed the skill to match the new command name. + +### Updated + +- All documentation, philosophy sections, and references updated to use `/compound` and `compound-docs` + ## [2.6.2] - 2025-11-27 ### Improved diff --git a/plugins/compounding-engineering/CLAUDE.md b/plugins/compounding-engineering/CLAUDE.md index 7fc46f1..c3f055c 100644 --- a/plugins/compounding-engineering/CLAUDE.md +++ b/plugins/compounding-engineering/CLAUDE.md @@ -35,7 +35,7 @@ agents/ └── docs/ # Documentation agents commands/ -β”œβ”€β”€ workflows/ # Core workflow commands (/plan, /review, /work, /codify) +β”œβ”€β”€ workflows/ # Core workflow commands (/plan, /review, /work, /compound) └── *.md # Utility commands skills/ diff --git a/plugins/compounding-engineering/README.md b/plugins/compounding-engineering/README.md index 1515e61..6cc4c80 100644 --- a/plugins/compounding-engineering/README.md +++ b/plugins/compounding-engineering/README.md @@ -74,7 +74,7 @@ Core workflow commands (use the short form for autocomplete): | `/plan` | Create implementation plans | | `/review` | Run comprehensive code reviews | | `/work` | Execute work items systematically | -| `/codify` | Document solved problems for knowledge base | +| `/compound` | Document solved problems to compound team knowledge | ### Utility Commands @@ -100,7 +100,7 @@ Core workflow commands (use the short form for autocomplete): | Skill | Description | |-------|-------------| | `andrew-kane-gem-writer` | Write Ruby gems following Andrew Kane's patterns | -| `codify-docs` | Capture solved problems as categorized documentation | +| `compound-docs` | Capture solved problems as categorized documentation | | `create-agent-skills` | Expert guidance for creating Claude Code skills | | `dhh-ruby-style` | Write Ruby/Rails code in DHH's 37signals style | | `dspy-ruby` | Build type-safe LLM applications with DSPy.rb | diff --git a/plugins/compounding-engineering/commands/workflows/codify.md b/plugins/compounding-engineering/commands/workflows/codify.md index 0f2c27e..69a022e 100644 --- a/plugins/compounding-engineering/commands/workflows/codify.md +++ b/plugins/compounding-engineering/commands/workflows/codify.md @@ -1,198 +1,17 @@ --- name: codify -description: Document a recently solved problem for the knowledge base +description: "[DEPRECATED] Use /compound instead - Document solved problems" argument-hint: "[optional: brief context about the fix]" --- -# /codify +# /codify is deprecated -Coordinate multiple subagents working in parallel to document a recently solved problem. +**This command has been renamed to `/compound`.** -## Purpose +The new name better reflects the compounding engineering philosophy: each documented solution compounds your team's knowledge. -Captures problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency. +--- -## Usage +Tell the user: "Note: `/codify` has been renamed to `/compound`. Please use `/compound` going forward." -```bash -/codify # Document the most recent fix -/codify [brief context] # Provide additional context hint -``` - -## Execution Strategy: Parallel Subagents - -This command launches multiple specialized subagents IN PARALLEL to maximize efficiency: - -### 1. **Context Analyzer** (Parallel) - - Extracts conversation history - - Identifies problem type, component, symptoms - - Validates against CORA schema - - Returns: YAML frontmatter skeleton - -### 2. **Solution Extractor** (Parallel) - - Analyzes all investigation steps - - Identifies root cause - - Extracts working solution with code examples - - Returns: Solution content block - -### 3. **Related Docs Finder** (Parallel) - - Searches `docs/solutions/` for related documentation - - Identifies cross-references and links - - Finds related GitHub issues - - Returns: Links and relationships - -### 4. **Prevention Strategist** (Parallel) - - Develops prevention strategies - - Creates best practices guidance - - Generates test cases if applicable - - Returns: Prevention/testing content - -### 5. **Category Classifier** (Parallel) - - Determines optimal `docs/solutions/` category - - Validates category against schema - - Suggests filename based on slug - - Returns: Final path and filename - -### 6. **Documentation Writer** (Parallel) - - Assembles complete markdown file - - Validates YAML frontmatter - - Formats content for readability - - Creates the file in correct location - -### 7. **Optional: Specialized Agent Invocation** (Post-Documentation) - Based on problem type detected, automatically invoke applicable agents: - - **performance_issue** β†’ `performance-oracle` - - **security_issue** β†’ `security-sentinel` - - **database_issue** β†’ `data-integrity-guardian` - - **test_failure** β†’ `cora-test-reviewer` - - Any code-heavy issue β†’ `kieran-rails-reviewer` + `code-simplicity-reviewer` - -## What It Captures - -- **Problem symptom**: Exact error messages, observable behavior -- **Investigation steps tried**: What didn't work and why -- **Root cause analysis**: Technical explanation -- **Working solution**: Step-by-step fix with code examples -- **Prevention strategies**: How to avoid in future -- **Cross-references**: Links to related issues and docs - -## Preconditions - - - - Problem has been solved (not in-progress) - - - Solution has been verified working - - - Non-trivial problem (not simple typo or obvious error) - - - -## What It Creates - -**Organized documentation:** - -- File: `docs/solutions/[category]/[filename].md` - -**Categories auto-detected from problem:** - -- build-errors/ -- test-failures/ -- runtime-errors/ -- performance-issues/ -- database-issues/ -- security-issues/ -- ui-bugs/ -- integration-issues/ -- logic-errors/ - -## Success Output - -``` -βœ“ Parallel documentation generation complete - -Primary Subagent Results: - βœ“ Context Analyzer: Identified performance_issue in brief_system - βœ“ Solution Extractor: Extracted 3 code fixes - βœ“ Related Docs Finder: Found 2 related issues - βœ“ Prevention Strategist: Generated test cases - βœ“ Category Classifier: docs/solutions/performance-issues/ - βœ“ Documentation Writer: Created complete markdown - -Specialized Agent Reviews (Auto-Triggered): - βœ“ performance-oracle: Validated query optimization approach - βœ“ kieran-rails-reviewer: Code examples meet Rails standards - βœ“ code-simplicity-reviewer: Solution is appropriately minimal - βœ“ every-style-editor: Documentation style verified - -File created: -- docs/solutions/performance-issues/n-plus-one-brief-generation.md - -This documentation will be searchable for future reference when similar -issues occur in the Email Processing or Brief System modules. - -What's next? -1. Continue workflow (recommended) -2. Link related documentation -3. Update other references -4. View documentation -5. Other -``` - -## Why This Matters - -This creates a compounding knowledge system: - -1. First time you solve "N+1 query in brief generation" β†’ Research (30 min) -2. Document the solution β†’ docs/solutions/performance-issues/n-plus-one-briefs.md (5 min) -3. Next time similar issue occurs β†’ Quick lookup (2 min) -4. Knowledge compounds β†’ Team gets smarter - -The feedback loop: - -``` -Build β†’ Test β†’ Find Issue β†’ Research β†’ Improve β†’ Document β†’ Validate β†’ Deploy - ↑ ↓ - β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -## Auto-Invoke - - - "that worked" - "it's fixed" - "working now" - "problem solved" - - Use /codify [context] to document immediately without waiting for auto-detection. - -## Routes To - -`codify-docs` skill - -## Applicable Specialized Agents - -Based on problem type, these agents can enhance documentation: - -### Code Quality & Review -- **kieran-rails-reviewer**: Reviews code examples for Rails best practices -- **code-simplicity-reviewer**: Ensures solution code is minimal and clear -- **pattern-recognition-specialist**: Identifies anti-patterns or repeating issues - -### Specific Domain Experts -- **performance-oracle**: Analyzes performance_issue category solutions -- **security-sentinel**: Reviews security_issue solutions for vulnerabilities -- **cora-test-reviewer**: Creates test cases for prevention strategies -- **data-integrity-guardian**: Reviews database_issue migrations and queries - -### Enhancement & Documentation -- **best-practices-researcher**: Enriches solution with industry best practices -- **every-style-editor**: Reviews documentation style and clarity -- **framework-docs-researcher**: Links to Rails/gem documentation references - -### When to Invoke -- **Auto-triggered** (optional): Agents can run post-documentation for enhancement -- **Manual trigger**: User can invoke agents after /codify completes for deeper review - -## Related Commands - -- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns) -- `/plan` - Planning workflow (references documented solutions) +Now run the `/compound` command with the same arguments: #$ARGUMENTS diff --git a/plugins/compounding-engineering/commands/workflows/compound.md b/plugins/compounding-engineering/commands/workflows/compound.md new file mode 100644 index 0000000..dc4cde2 --- /dev/null +++ b/plugins/compounding-engineering/commands/workflows/compound.md @@ -0,0 +1,202 @@ +--- +name: compound +description: Document a recently solved problem to compound your team's knowledge +argument-hint: "[optional: brief context about the fix]" +--- + +# /compound + +Coordinate multiple subagents working in parallel to document a recently solved problem. + +## Purpose + +Captures problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency. + +**Why "compound"?** Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds. + +## Usage + +```bash +/compound # Document the most recent fix +/compound [brief context] # Provide additional context hint +``` + +## Execution Strategy: Parallel Subagents + +This command launches multiple specialized subagents IN PARALLEL to maximize efficiency: + +### 1. **Context Analyzer** (Parallel) + - Extracts conversation history + - Identifies problem type, component, symptoms + - Validates against CORA schema + - Returns: YAML frontmatter skeleton + +### 2. **Solution Extractor** (Parallel) + - Analyzes all investigation steps + - Identifies root cause + - Extracts working solution with code examples + - Returns: Solution content block + +### 3. **Related Docs Finder** (Parallel) + - Searches `docs/solutions/` for related documentation + - Identifies cross-references and links + - Finds related GitHub issues + - Returns: Links and relationships + +### 4. **Prevention Strategist** (Parallel) + - Develops prevention strategies + - Creates best practices guidance + - Generates test cases if applicable + - Returns: Prevention/testing content + +### 5. **Category Classifier** (Parallel) + - Determines optimal `docs/solutions/` category + - Validates category against schema + - Suggests filename based on slug + - Returns: Final path and filename + +### 6. **Documentation Writer** (Parallel) + - Assembles complete markdown file + - Validates YAML frontmatter + - Formats content for readability + - Creates the file in correct location + +### 7. **Optional: Specialized Agent Invocation** (Post-Documentation) + Based on problem type detected, automatically invoke applicable agents: + - **performance_issue** β†’ `performance-oracle` + - **security_issue** β†’ `security-sentinel` + - **database_issue** β†’ `data-integrity-guardian` + - **test_failure** β†’ `cora-test-reviewer` + - Any code-heavy issue β†’ `kieran-rails-reviewer` + `code-simplicity-reviewer` + +## What It Captures + +- **Problem symptom**: Exact error messages, observable behavior +- **Investigation steps tried**: What didn't work and why +- **Root cause analysis**: Technical explanation +- **Working solution**: Step-by-step fix with code examples +- **Prevention strategies**: How to avoid in future +- **Cross-references**: Links to related issues and docs + +## Preconditions + + + + Problem has been solved (not in-progress) + + + Solution has been verified working + + + Non-trivial problem (not simple typo or obvious error) + + + +## What It Creates + +**Organized documentation:** + +- File: `docs/solutions/[category]/[filename].md` + +**Categories auto-detected from problem:** + +- build-errors/ +- test-failures/ +- runtime-errors/ +- performance-issues/ +- database-issues/ +- security-issues/ +- ui-bugs/ +- integration-issues/ +- logic-errors/ + +## Success Output + +``` +βœ“ Parallel documentation generation complete + +Primary Subagent Results: + βœ“ Context Analyzer: Identified performance_issue in brief_system + βœ“ Solution Extractor: Extracted 3 code fixes + βœ“ Related Docs Finder: Found 2 related issues + βœ“ Prevention Strategist: Generated test cases + βœ“ Category Classifier: docs/solutions/performance-issues/ + βœ“ Documentation Writer: Created complete markdown + +Specialized Agent Reviews (Auto-Triggered): + βœ“ performance-oracle: Validated query optimization approach + βœ“ kieran-rails-reviewer: Code examples meet Rails standards + βœ“ code-simplicity-reviewer: Solution is appropriately minimal + βœ“ every-style-editor: Documentation style verified + +File created: +- docs/solutions/performance-issues/n-plus-one-brief-generation.md + +This documentation will be searchable for future reference when similar +issues occur in the Email Processing or Brief System modules. + +What's next? +1. Continue workflow (recommended) +2. Link related documentation +3. Update other references +4. View documentation +5. Other +``` + +## The Compounding Philosophy + +This creates a compounding knowledge system: + +1. First time you solve "N+1 query in brief generation" β†’ Research (30 min) +2. Document the solution β†’ docs/solutions/performance-issues/n-plus-one-briefs.md (5 min) +3. Next time similar issue occurs β†’ Quick lookup (2 min) +4. Knowledge compounds β†’ Team gets smarter + +The feedback loop: + +``` +Build β†’ Test β†’ Find Issue β†’ Research β†’ Improve β†’ Document β†’ Validate β†’ Deploy + ↑ ↓ + β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +**Each unit of engineering work should make subsequent units of work easierβ€”not harder.** + +## Auto-Invoke + + - "that worked" - "it's fixed" - "working now" - "problem solved" + + Use /compound [context] to document immediately without waiting for auto-detection. + +## Routes To + +`compound-docs` skill + +## Applicable Specialized Agents + +Based on problem type, these agents can enhance documentation: + +### Code Quality & Review +- **kieran-rails-reviewer**: Reviews code examples for Rails best practices +- **code-simplicity-reviewer**: Ensures solution code is minimal and clear +- **pattern-recognition-specialist**: Identifies anti-patterns or repeating issues + +### Specific Domain Experts +- **performance-oracle**: Analyzes performance_issue category solutions +- **security-sentinel**: Reviews security_issue solutions for vulnerabilities +- **cora-test-reviewer**: Creates test cases for prevention strategies +- **data-integrity-guardian**: Reviews database_issue migrations and queries + +### Enhancement & Documentation +- **best-practices-researcher**: Enriches solution with industry best practices +- **every-style-editor**: Reviews documentation style and clarity +- **framework-docs-researcher**: Links to Rails/gem documentation references + +### When to Invoke +- **Auto-triggered** (optional): Agents can run post-documentation for enhancement +- **Manual trigger**: User can invoke agents after /compound completes for deeper review + +## Related Commands + +- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns) +- `/plan` - Planning workflow (references documented solutions) diff --git a/plugins/compounding-engineering/skills/codify-docs/SKILL.md b/plugins/compounding-engineering/skills/compound-docs/SKILL.md similarity index 99% rename from plugins/compounding-engineering/skills/codify-docs/SKILL.md rename to plugins/compounding-engineering/skills/compound-docs/SKILL.md index 63232f1..32dede5 100644 --- a/plugins/compounding-engineering/skills/codify-docs/SKILL.md +++ b/plugins/compounding-engineering/skills/compound-docs/SKILL.md @@ -1,5 +1,5 @@ --- -name: codify-docs +name: compound-docs description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup allowed-tools: - Read # Parse conversation context @@ -11,7 +11,7 @@ preconditions: - Solution has been verified working --- -# codify-docs Skill +# compound-docs Skill **Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types). @@ -348,7 +348,7 @@ Action: ## Integration Points **Invoked by:** -- /codify command (primary interface) +- /compound command (primary interface) - Manual invocation in conversation after solution confirmed - Can be triggered by detecting confirmation phrases like "that worked", "it's fixed", etc. diff --git a/plugins/compounding-engineering/skills/codify-docs/assets/critical-pattern-template.md b/plugins/compounding-engineering/skills/compound-docs/assets/critical-pattern-template.md similarity index 100% rename from plugins/compounding-engineering/skills/codify-docs/assets/critical-pattern-template.md rename to plugins/compounding-engineering/skills/compound-docs/assets/critical-pattern-template.md diff --git a/plugins/compounding-engineering/skills/codify-docs/assets/resolution-template.md b/plugins/compounding-engineering/skills/compound-docs/assets/resolution-template.md similarity index 100% rename from plugins/compounding-engineering/skills/codify-docs/assets/resolution-template.md rename to plugins/compounding-engineering/skills/compound-docs/assets/resolution-template.md diff --git a/plugins/compounding-engineering/skills/codify-docs/references/yaml-schema.md b/plugins/compounding-engineering/skills/compound-docs/references/yaml-schema.md similarity index 100% rename from plugins/compounding-engineering/skills/codify-docs/references/yaml-schema.md rename to plugins/compounding-engineering/skills/compound-docs/references/yaml-schema.md diff --git a/plugins/compounding-engineering/skills/codify-docs/schema.yaml b/plugins/compounding-engineering/skills/compound-docs/schema.yaml similarity index 100% rename from plugins/compounding-engineering/skills/codify-docs/schema.yaml rename to plugins/compounding-engineering/skills/compound-docs/schema.yaml From 80fa2e3d824849a166d4d70336ae7d8ed483cebf Mon Sep 17 00:00:00 2001 From: Julik Tarkhanov Date: Fri, 28 Nov 2025 00:59:16 +0000 Subject: [PATCH 20/25] Add a specialized JS reviewer agent who focuses on UI races with maniacal obsession. --- .../review/julik-frontend-races-reviewer.md | 215 ++++++++++++++++++ 1 file changed, 215 insertions(+) create mode 100644 plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md diff --git a/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md b/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md new file mode 100644 index 0000000..40df39b --- /dev/null +++ b/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md @@ -0,0 +1,215 @@ +--- +name: julik-frontend-races-reviewer +description: | + Use this agent when you need to review JavaScript or Stimulus frontend code changes with a special eye for race conditions. The agent should be invoked after implementing JavaScript features, modifying existing JavaScript code, or when creating or modifying Stimulus controllers. The agent applies Julik's eye for UI race conditions in JavaScript and Stimulus code. + + Examples: + - + Context: The user has just implemented a new Stimulus controller. + user: "I've created a new controller for showing and hiding toasts" + assistant: "I've implemented the controller. Now let me have Julik take a look at possible race conditions and DOM irregularities." + + Since new Stimulus controller code was written, use the julik-frontend-races-reviewer agent to apply Julik's uncanny knowledge of UI data races and quality checks in JavaScript and Stimulus code. + + + - + Context: The user has refactored an existing Stimulus controller. + user: "Please refactor the controller to slowly animate one of the targets" + assistant: "I've refactored the controller to slowly animate one of the targets." + + After modifying existing Stimulus controllers, especially things concerning time and asynchronous operations, use julik-frontend-reviewer to ensure the changes meet Julik's bar for absence of UI races in JavaScript code. + + + +--- + +You are Julik, a seasoned full-stack developer with a keen eye for data races and UI quality. You review all code changes with focus on timing, because timing is everything. + +Your review approach follows these principles: + +## 1. Compatibility with Hotwire and Turbo + +Honor the fact that elements of the DOM may get replaced in-situ. If Hotwire, Turbo or HTMX are used in the project, pay special attention to the state changes of the DOM at replacement. Specifically: + +* Remember that Turbo and similar tech does things the following way: + 1. Prepare the new node but keep it detached from the document + 2. Remove the node that is getting replaced from the DOM + 3. Attach the new node into the document where the previous node used to be +* React components will get unmounted and remounted at a Turbo swap/change/morph +* Stimulus controllers that wish to retain state between Turbo swaps must create that state in the initialize() method, not in connect(). In those cases, Stimulus controllers get retained, but they get disconnected and then reconnected again +* Event handlers must be properly disposed of in disconnect(), same for all the defined intervals and timeouts + +## 2. Use of DOM events + +When defining event listeners using the DOM, propose using a centralized manager for those handlers that can then be centrally disposed of: + +```js +class EventListenerManager { + constructor() { + this.releaseFns = []; + } + + add(target, event, handlerFn, options) { + target.addEventListener(event, handlerFn, options); + this.releaseFns.unshift(() => { + target.removeEventListener(event, handlerFn, options); + }); + } + + removeAll() { + for (let r of this.releaseFns) { + r(); + } + this.releaseFns.length = 0; + } +} +``` + +Recommend event propagation instead of attaching `data-action` attributes to many repeated elements. Those events usually can be handled on `this.element` of the controller, or on the wrapper target: + +```html +
    +
    ...
    +
    ...
    +
    ...
    + +
    +``` + +instead of + +```html +
    ...
    +
    ...
    +
    ...
    + +``` + +## 3. Promises + +Pay attention to promises with unhandled rejections. If the user deliberately allows a Promise to get rejected, incite them to add a comment with an explanation as to why. Recommend `Promise.allSettled` when concurrent operations are used or several promises are in progress. Recommend making the use of promises obvious and visible instead of relying on chains of `async` and `await`. + +Recommend using `Promise#finally()` for cleanup and state transitions instead of doing the same work within resolve and reject functions. + +## 4. setTimeout(), setInterval(), requestAnimationFrame + +All set timeouts and all set intervals should contain cancelation token checks in their code, and allow cancelation that would be propagated to an already executing timer function: + +```js +function setTimeoutWithCancelation(fn, delay, ...params) { + let cancelToken = {canceled: false}; + let handlerWithCancelation = (...params) => { + if (cancelToken.canceled) return; + return fn(...params); + }; + let timeoutId = setTimeout(handler, delay, ...params); + let cancel = () => { + cancelToken.canceled = true; + clearTimeout(timeoutId); + }; + return {timeoutId, cancel}; +} +// and in disconnect() of the controller +this.reloadTimeout.cancel(); +``` + +If an async handler also schedules some async action, the cancelation token should be propagated into that "grandchild" async handler. + +When setting a timeout that can overwrite another - like loading previews, modals and the like - verify that the previous timeout has been properly canceled. Apply similar logic for `setInterval`. + +When `requestAnimationFrame` is used, there is no need to make it cancelable by ID but do verify that if it enqueues the next `requestAnimationFrame` this is done only after having checked a cancelation variable: + +```js +var st = performance.now(); +let cancelToken = {canceled: false}; +const animFn = () => { + const now = performance.now(); + const ds = performance.now() - st; + st = now; + // Compute the travel using the time delta ds... + if (!cancelToken.canceled) { + requestAnimationFrame(animFn); + } +} +requestAnimationFrame(animFn); // start the loop +``` + +## 5. CSS transitions and animations + +Recommend observing the minimum-frame-count animation durations. The minimum frame count animation is the one which can clearly show at least one (and preferably just one) intermediate state between the starting state and the final state, to give user hints. Assume the duration of one frame is 16ms, so a lot of animations will only ever need a duration of 32ms - for one intermediate frame and one final frame. Anything more can be perceived as excessive show-off and does not contribute to UI fluidity. + +Be careful with using CSS animations with Turbo or React components, because these animations will restart when a DOM node gets removed and another gets put in its place as a clone. If the user desires an animation that traverses multiple DOM node replacements recommend explicitly animating the CSS properties using interpolations. + +## 6. Keeping track of concurrent operations + +Most UI operations are mutually exclusive, and the next one can't start until the previous one has ended. Pay special attention to this, and recommend using state machines for determining whether a particular animation or async action may be triggered right now. For example, you do not want to load a preview into a modal while you are still waiting for the previous preview to load or fail to load. + +For key interactions managed by a React component or a Stimulus controller, store state variables and recommend a transition to a state machine if a single boolean does not cut it anymore - to prevent combinatorial explosion: + +```js +this.isLoading = true; +// ...do the loading which may fail or succeed +loadAsync().finally(() => this.isLoading = false); +``` + +but: + +```js +const priorState = this.state; // imagine it is STATE_IDLE +this.state = STATE_LOADING; // which is usually best as a Symbol() +// ...do the loading which may fail or succeed +loadAsync().finally(() => this.state = priorState); // reset +``` + +Watch out for operations which should be refused while other operations are in progress. This applies to both React and Stimulus. Be very cognizant that despite its "immutability" ambition React does zero work by itself to prevent those data races in UIs and it is the responsibility of the developer. + +Always try to construct a matrix of possible UI states and try to find gaps in how the code covers the matrix entries. + +Recommend const symbols for states: + +```js +const STATE_PRIMING = Symbol(); +const STATE_LOADING = Symbol(); +const STATE_ERRORED = Symbol(); +const STATE_LOADED = Symbol(); +``` + +## 7. Deferred image and iframe loading + +When working with images and iframes, use the "load handler then set src" trick: + +```js +const img = new Image(); +img.__loaded = false; +img.onload = () => img.__loaded = true; +img.src = remoteImageUrl; + +// and when the image has to be displayed +if (img.__loaded) { + canvasContext.drawImage(...) +} +``` + +## 8. Guidelines + +The underlying ideas: + +* Always assume the DOM is async and reactive, and it will be doing things in the background +* Embrace native DOM state (selection, CSS properties, data attributes, native events) +* Prevent jank by ensuring there are no racing animations, no racing async loads +* Prevent conflicting interactions that will cause weird UI behavior from happening at the same time +* Prevent stale timers messing up the DOM when the DOM changes underneath the timer + +When reviewing code: + +1. Start with the most critical issues (obvious races) +2. Check for proper cleanups +3. Give the user tips on how to induce failures or data races (like forcing a dynamic iframe to load very slowly) +4. Suggest specific improvements with examples and patterns which are known to be robust +5. Recommend approaches with the least amount of indirection, because data races are hard as they are. + +Your reviews should be thorough but actionable, with clear examples of how to avoid races. + +## 9. Review style and wit + +Be very courteous but curt. Be witty and nearly graphic in describing how bad the user experience is going to be if a data race happens, making the example very relevant to the race condition found. Incessantly remind that janky UIs are the first hallmark of "cheap feel" of applications today. Balance wit with expertise, try not to slide down into being cynical. Always explain the actual unfolding of events when races will be happening to give the user a great understanding of the problem. Be unapologetic - if something will cause the user to have a bad time, you should say so. Agressively hammer on the fact that "using React" is, by far, not a silver bullet for fixing those races, and take opportunities to educate the user about native DOM state and rendering. \ No newline at end of file From 224d4bb52b6aa9650f8d332a6b04f81329607ec2 Mon Sep 17 00:00:00 2001 From: Julik Tarkhanov Date: Fri, 28 Nov 2025 01:01:32 +0000 Subject: [PATCH 21/25] Some more tips --- .../agents/review/julik-frontend-races-reviewer.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md b/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md index 40df39b..75e1d41 100644 --- a/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md +++ b/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md @@ -212,4 +212,11 @@ Your reviews should be thorough but actionable, with clear examples of how to av ## 9. Review style and wit -Be very courteous but curt. Be witty and nearly graphic in describing how bad the user experience is going to be if a data race happens, making the example very relevant to the race condition found. Incessantly remind that janky UIs are the first hallmark of "cheap feel" of applications today. Balance wit with expertise, try not to slide down into being cynical. Always explain the actual unfolding of events when races will be happening to give the user a great understanding of the problem. Be unapologetic - if something will cause the user to have a bad time, you should say so. Agressively hammer on the fact that "using React" is, by far, not a silver bullet for fixing those races, and take opportunities to educate the user about native DOM state and rendering. \ No newline at end of file +Be very courteous but curt. Be witty and nearly graphic in describing how bad the user experience is going to be if a data race happens, making the example very relevant to the race condition found. Incessantly remind that janky UIs are the first hallmark of "cheap feel" of applications today. Balance wit with expertise, try not to slide down into being cynical. Always explain the actual unfolding of events when races will be happening to give the user a great understanding of the problem. Be unapologetic - if something will cause the user to have a bad time, you should say so. Agressively hammer on the fact that "using React" is, by far, not a silver bullet for fixing those races, and take opportunities to educate the user about native DOM state and rendering. + +Your communication style should be a blend of British, Eastern-European and Dutch in terms of wit and directness, but being rude. Be candid, be frank and be direct - but not rude. + + +## 10. Dependencies + +Discourage the user from pulling in too many dependencies, explaining that the job is to first understand the race conditions, and then pick a tool for removing them. That tool is usually just a dozen lines, if not less - no need to pull in half of NPM for that. From 466a7f1979d2adae333bd36704712e047eb3ede2 Mon Sep 17 00:00:00 2001 From: Julik Tarkhanov Date: Fri, 28 Nov 2025 01:07:36 +0000 Subject: [PATCH 22/25] No rudeboi --- .../agents/review/julik-frontend-races-reviewer.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md b/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md index 75e1d41..276b057 100644 --- a/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md +++ b/plugins/compounding-engineering/agents/review/julik-frontend-races-reviewer.md @@ -214,8 +214,7 @@ Your reviews should be thorough but actionable, with clear examples of how to av Be very courteous but curt. Be witty and nearly graphic in describing how bad the user experience is going to be if a data race happens, making the example very relevant to the race condition found. Incessantly remind that janky UIs are the first hallmark of "cheap feel" of applications today. Balance wit with expertise, try not to slide down into being cynical. Always explain the actual unfolding of events when races will be happening to give the user a great understanding of the problem. Be unapologetic - if something will cause the user to have a bad time, you should say so. Agressively hammer on the fact that "using React" is, by far, not a silver bullet for fixing those races, and take opportunities to educate the user about native DOM state and rendering. -Your communication style should be a blend of British, Eastern-European and Dutch in terms of wit and directness, but being rude. Be candid, be frank and be direct - but not rude. - +Your communication style should be a blend of British (wit) and Eastern-European and Dutch (directness), with bias towards candor. Be candid, be frank and be direct - but not rude. ## 10. Dependencies From e00b9d3d02d749718712caa5b91a133a521b3ca0 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Thu, 27 Nov 2025 18:31:34 -0800 Subject: [PATCH 23/25] Bump version to 2.8.0 for julik-frontend-races-reviewer agent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add CHANGELOG entry for new frontend race condition reviewer - Update agent count from 23 to 24 in plugin.json and marketplace.json πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude-plugin/marketplace.json | 4 ++-- plugins/compounding-engineering/.claude-plugin/plugin.json | 4 ++-- plugins/compounding-engineering/CHANGELOG.md | 6 ++++++ 3 files changed, 10 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6c98eb6..efb0c35 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,8 +11,8 @@ "plugins": [ { "name": "compounding-engineering", - "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 23 specialized agents, 16 commands, and 11 skills.", - "version": "2.6.0", + "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 24 specialized agents, 16 commands, and 11 skills.", + "version": "2.8.0", "author": { "name": "Kieran Klaassen", "url": "https://github.com/kieranklaassen", diff --git a/plugins/compounding-engineering/.claude-plugin/plugin.json b/plugins/compounding-engineering/.claude-plugin/plugin.json index 020b44d..119e00f 100644 --- a/plugins/compounding-engineering/.claude-plugin/plugin.json +++ b/plugins/compounding-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "compounding-engineering", - "version": "2.7.0", - "description": "AI-powered development tools. 23 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.", + "version": "2.8.0", + "description": "AI-powered development tools. 24 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", "email": "kieran@every.to", diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md index 97e0ed9..61df97e 100644 --- a/plugins/compounding-engineering/CHANGELOG.md +++ b/plugins/compounding-engineering/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the compounding-engineering plugin will be documented in The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.8.0] - 2025-11-27 + +### Added + +- **`julik-frontend-races-reviewer` agent** - New review agent specializing in JavaScript and Stimulus code race conditions. Reviews frontend code with Julik's eye for timing issues, DOM event handling, promise management, setTimeout/setInterval cleanup, CSS animations, and concurrent operation tracking. Includes patterns for Hotwire/Turbo compatibility and state machine recommendations. + ## [2.7.0] - 2025-11-27 ### Changed From 814c23724a0f8075bb937d71c053c1c6b393589a Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Thu, 27 Nov 2025 19:59:03 -0800 Subject: [PATCH 24/25] [2.8.1] Add GitHub/Linear issue creation to /plan command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add "Create Issue" option to post-generation menu in /plan - Detect project tracker from user's CLAUDE.md (project_tracker: github or linear) - Use gh issue create for GitHub, linear CLI for Linear - Show issue URL after creation and offer to continue to /work or /plan_review πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...row-your-own-garden-plugin-architecture.md | 644 ++++++++++++++++++ .../.claude-plugin/plugin.json | 2 +- plugins/compounding-engineering/CHANGELOG.md | 6 + .../commands/workflows/plan.md | 35 +- 4 files changed, 684 insertions(+), 3 deletions(-) create mode 100644 plans/grow-your-own-garden-plugin-architecture.md diff --git a/plans/grow-your-own-garden-plugin-architecture.md b/plans/grow-your-own-garden-plugin-architecture.md new file mode 100644 index 0000000..729a0ba --- /dev/null +++ b/plans/grow-your-own-garden-plugin-architecture.md @@ -0,0 +1,644 @@ +# Grow Your Own Garden: Adaptive Agent Ecosystem + +> **Issue Reference:** https://github.com/EveryInc/compounding-engineering-plugin/issues/20 +> **Date:** 2025-11-27 +> **Status:** Draft Plan + +## Overview + +Transform the compounding-engineering plugin from a monolithic collection into an **adaptive ecosystem** where users grow their own personalized agent gardens from a minimal seed. The core loop (`/plan`, `/work`, `/review`, `/compound`) stays universal, but each user's agent collection evolves based on their learnings. + +**Philosophy:** Everyone grows their own garden, but we're all using the same process. + +--- + +## Problem Statement + +### Current State +- Monolithic plugin: 24 agents, 16 commands, 11 skills +- Users get everything, use maybe 30% +- No personalization - same agents for Rails developer and Python developer +- No growth mechanism - static collection that doesn't adapt + +### Desired State +- Minimal seed: 4 commands + ~6 core agents +- Organic growth: `/compound` suggests relevant agents based on learnings +- Personalized gardens: Rails developer accumulates Rails experts, Python developer accumulates Python experts +- Shared process: Core workflow identical across all users + +--- + +## Proposed Solution + +### Architecture: Seed + Growth Model + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SEED PLUGIN (Core) β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ /plan β”‚ β”‚ /work β”‚ β”‚ /review β”‚ β”‚/compound β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ β”‚ +β”‚ Core Agents: security-sentinel, performance-oracle, β”‚ +β”‚ code-simplicity-reviewer, architecture-strategist β”‚ +β”‚ pattern-recognition-specialist β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ /compound triggers growth + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ USER'S GARDEN (~/.claude/agents/) β”‚ +β”‚ β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ Predefined β”‚ β”‚ Dynamic β”‚ β”‚ Custom β”‚ β”‚ +β”‚ β”‚ (from library) β”‚ β”‚ (generated) β”‚ β”‚ (user-written) β”‚ β”‚ +β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ β€’ dhh-rails β”‚ β”‚ β€’ actor-model β”‚ β”‚ β€’ our-api-style β”‚ β”‚ +β”‚ β”‚ β€’ kieran-python β”‚ β”‚ expert β”‚ β”‚ β€’ team-patterns β”‚ β”‚ +β”‚ β”‚ β€’ typescript β”‚ β”‚ β€’ graphql-best β”‚ β”‚ β”‚ β”‚ +β”‚ β”‚ reviewer β”‚ β”‚ practices β”‚ β”‚ β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β”‚ /review discovers all agents + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ PROJECT OVERRIDES (.claude/agents/) β”‚ +β”‚ β”‚ +β”‚ Project-specific agents that override or supplement global β”‚ +β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ +β”‚ β”‚ β€’ cora-specific β”‚ (only runs in ~/Reels/cora/) β”‚ +β”‚ β”‚ β€’ hotwire-nativeβ”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### The Growth Loop + +``` +User completes work + β”‚ + β–Ό + Runs /compound + β”‚ + β–Ό +System analyzes: +β€’ Git diff (files changed, patterns) +β€’ Tech stack (Gemfile, package.json) +β€’ Learning content + β”‚ + β–Ό +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ SUGGESTION ENGINE β”‚ +β”‚ β”‚ +β”‚ Match detected patterns against: β”‚ +β”‚ 1. Predefined agent library (curated) β”‚ +β”‚ 2. Dynamic generation capability β”‚ +β”‚ 3. User's existing agents (avoid duplicates) β”‚ +β”‚ β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + Three possible outcomes: + β”‚ + β”œβ”€β–Ί "You're using Rails. Add DHH reviewer?" [y/n] + β”‚ (Predefined agent from library) + β”‚ + β”œβ”€β–Ί "You're using actor model. Create an expert?" [y/n] + β”‚ (Dynamic agent generation) + β”‚ + └─► "Want to create a custom agent for this pattern?" [y/n] + (User-defined agent) + β”‚ + β–Ό + Agent added to ~/.claude/agents/ + β”‚ + β–Ό + Next /review includes new agent +``` + +--- + +## Technical Approach + +### Phase 1: Split Into Core + Agent Library + +**New Marketplace Structure:** + +``` +every-marketplace/ +β”œβ”€β”€ .claude-plugin/ +β”‚ └── marketplace.json +β”œβ”€β”€ plugins/ +β”‚ β”œβ”€β”€ compounding-engineering/ # CORE (seed) +β”‚ β”‚ β”œβ”€β”€ .claude-plugin/plugin.json +β”‚ β”‚ β”œβ”€β”€ agents/ +β”‚ β”‚ β”‚ β”œβ”€β”€ review/ +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ security-sentinel.md +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ performance-oracle.md +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ code-simplicity-reviewer.md +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ architecture-strategist.md +β”‚ β”‚ β”‚ β”‚ └── pattern-recognition-specialist.md +β”‚ β”‚ β”‚ β”œβ”€β”€ research/ +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ best-practices-researcher.md +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ framework-docs-researcher.md +β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ git-history-analyzer.md +β”‚ β”‚ β”‚ β”‚ └── repo-research-analyst.md +β”‚ β”‚ β”‚ └── workflow/ +β”‚ β”‚ β”‚ β”œβ”€β”€ bug-reproduction-validator.md +β”‚ β”‚ β”‚ └── spec-flow-analyzer.md +β”‚ β”‚ β”œβ”€β”€ commands/ +β”‚ β”‚ β”‚ └── workflows/ +β”‚ β”‚ β”‚ β”œβ”€β”€ plan.md +β”‚ β”‚ β”‚ β”œβ”€β”€ work.md +β”‚ β”‚ β”‚ β”œβ”€β”€ review.md +β”‚ β”‚ β”‚ └── compound.md +β”‚ β”‚ β”œβ”€β”€ skills/ +β”‚ β”‚ β”‚ β”œβ”€β”€ compound-docs/ +β”‚ β”‚ β”‚ β”œβ”€β”€ file-todos/ +β”‚ β”‚ β”‚ β”œβ”€β”€ git-worktree/ +β”‚ β”‚ β”‚ β”œβ”€β”€ create-agent-skills/ +β”‚ β”‚ β”‚ └── skill-creator/ +β”‚ β”‚ └── mcp-servers/ +β”‚ β”‚ β”œβ”€β”€ playwright +β”‚ β”‚ └── context7 +β”‚ β”‚ +β”‚ └── agent-library/ # OPTIONAL (predefined agents) +β”‚ β”œβ”€β”€ .claude-plugin/plugin.json +β”‚ β”œβ”€β”€ rails/ +β”‚ β”‚ β”œβ”€β”€ kieran-rails-reviewer.md +β”‚ β”‚ β”œβ”€β”€ dhh-rails-reviewer.md +β”‚ β”‚ └── data-integrity-guardian.md +β”‚ β”œβ”€β”€ python/ +β”‚ β”‚ └── kieran-python-reviewer.md +β”‚ β”œβ”€β”€ typescript/ +β”‚ β”‚ └── kieran-typescript-reviewer.md +β”‚ β”œβ”€β”€ frontend/ +β”‚ β”‚ β”œβ”€β”€ julik-frontend-races-reviewer.md +β”‚ β”‚ β”œβ”€β”€ design-iterator.md +β”‚ β”‚ β”œβ”€β”€ design-implementation-reviewer.md +β”‚ β”‚ └── figma-design-sync.md +β”‚ └── editorial/ +β”‚ └── every-style-editor.md +└── docs/ +``` + +**Core Plugin Components (Seed):** + +| Category | Components | Count | +|----------|------------|-------| +| Commands | /plan, /work, /review, /compound | 4 | +| Review Agents | security, performance, simplicity, architecture, patterns | 5 | +| Research Agents | best-practices, framework-docs, git-history, repo-analyst | 4 | +| Workflow Agents | bug-reproduction, spec-flow | 2 | +| Skills | compound-docs, file-todos, git-worktree, create-agent-skills, skill-creator | 5 | +| MCP Servers | playwright, context7 | 2 | +| **TOTAL** | | **22 components** | + +**Agent Library (Optional Install):** + +| Category | Agents | Count | +|----------|--------|-------| +| Rails | kieran-rails, dhh-rails, data-integrity | 3 | +| Python | kieran-python | 1 | +| TypeScript | kieran-typescript | 1 | +| Frontend | julik-races, design-iterator, design-reviewer, figma-sync | 4 | +| Editorial | every-style-editor | 1 | +| **TOTAL** | | **10 agents** | + +### Phase 2: Agent Discovery & Storage + +**Agent Storage Locations (priority order):** + +``` +1. Project agents: .claude/agents/*.md (highest priority) +2. User agents: ~/.claude/agents/*.md (user's garden) +3. Plugin agents: plugin/agents/*.md (from installed plugins) +``` + +**Agent Metadata Format (frontmatter):** + +```yaml +--- +name: dhh-rails-reviewer +description: Reviews Rails code from DHH's perspective +tech_stack: [rails, ruby] # When to suggest +commands: [review] # Which commands use this +priority: 10 # Execution order (higher = first) +source: predefined # predefined | dynamic | custom +version: 1.0.0 +enabled: true # Can be disabled without deletion +--- +``` + +**Discovery Mechanism:** + +```ruby +# Pseudocode for /review agent discovery +def discover_agents(command: "review") + agents = [] + + # 1. Project agents (highest priority) + agents += glob(".claude/agents/**/*.md") + .filter { |a| a.commands.include?(command) && a.enabled } + + # 2. User's garden + agents += glob("~/.claude/agents/**/*.md") + .filter { |a| a.commands.include?(command) && a.enabled } + .reject { |a| agents.any? { |pa| pa.name == a.name } } # no duplicates + + # 3. Plugin agents + installed_plugins.each do |plugin| + agents += plugin.agents + .filter { |a| a.commands.include?(command) && a.enabled } + .reject { |a| agents.any? { |ea| ea.name == a.name } } + end + + agents.sort_by(&:priority).reverse +end +``` + +### Phase 3: Enhanced /compound with Growth + +**Updated /compound Flow:** + +```markdown +## /compound command (enhanced) + +1. Document the learning (existing behavior) + - Capture solution to compound-docs + +2. Analyze context (NEW) + - Detect tech stack from project files + - Analyze git diff for patterns + - Check user's existing agents + +3. Suggest growth (NEW) + - Match patterns to agent library + - Consider dynamic agent generation + - Present suggestion with clear UX + +4. Handle response (NEW) + - Accept: Install agent to ~/.claude/agents/ + - Decline: Record preference, don't ask again for this agent + - Custom: Launch agent creation workflow +``` + +**Suggestion UX (non-blocking):** + +``` +βœ… Learning documented to compound-docs + +πŸ’‘ Growth suggestion: + Your solution uses Rails conventions extensively. + + Would you like to add the "DHH Rails Reviewer" agent? + This agent reviews code from DHH's perspective, checking for: + β€’ Rails conventions and idioms + β€’ Hotwire/Turbo patterns + β€’ Fat models, skinny controllers + + [y] Yes, add it [n] No thanks [?] Tell me more [x] Never suggest this +``` + +**Tech Stack Detection:** + +```ruby +def detect_tech_stack(project_root) + stack = [] + + # Ruby/Rails + stack << :rails if File.exist?("Gemfile") && + File.read("Gemfile").include?("rails") + stack << :ruby if File.exist?("Gemfile") + + # JavaScript/TypeScript + if File.exist?("package.json") + pkg = JSON.parse(File.read("package.json")) + stack << :react if pkg.dig("dependencies", "react") + stack << :vue if pkg.dig("dependencies", "vue") + stack << :typescript if pkg.dig("devDependencies", "typescript") + stack << :node if pkg["type"] == "module" || pkg["main"] + end + + # Python + stack << :python if File.exist?("requirements.txt") || + File.exist?("pyproject.toml") + stack << :django if File.exist?("manage.py") + stack << :fastapi if File.read("requirements.txt")&.include?("fastapi") + + # Go + stack << :go if File.exist?("go.mod") + + stack +end +``` + +### Phase 4: Agent Management Commands + +**New Commands:** + +```bash +# List all agents in user's garden + plugins +/agents list +/agents list --tech rails # Filter by tech stack +/agents list --command review # Filter by command + +# Add agent from library +/agents add dhh-rails-reviewer +/agents add kieran-python-reviewer + +# Remove agent from garden +/agents remove dhh-rails-reviewer + +# Disable without removing +/agents disable dhh-rails-reviewer +/agents enable dhh-rails-reviewer + +# Create custom agent +/agents create "Our API Style Guide" + +# View agent details +/agents show dhh-rails-reviewer + +# Export for sharing +/agents export dhh-rails-reviewer > my-dhh-tweaks.md + +# Import shared agent +/agents import ./shared-agents/team-patterns.md +``` + +--- + +## Alternative Approaches Considered + +### Option A: Keep Monolithic (Current) +- **Pros:** Simple, one install, everything works +- **Cons:** Bloated, no personalization, no growth +- **Decision:** Rejected - doesn't support the "grow your garden" vision + +### Option B: Separate Plugins per Tech Stack +- **Pros:** Users install only what they need +- **Cons:** No dependency support in Claude Code, manual multi-install required +- **Decision:** Rejected - friction too high, doesn't enable organic growth + +### Option C: Core + Agent Library + Growth (Proposed) +- **Pros:** Minimal start, organic growth, personalized, shared process +- **Cons:** More complex implementation, new UX to design +- **Decision:** Selected - best aligns with vision + +--- + +## Acceptance Criteria + +### Functional Requirements + +- [ ] Core plugin installs with 4 commands + ~11 core agents +- [ ] `/review` discovers agents from project β†’ user β†’ plugin locations +- [ ] `/compound` detects tech stack and suggests relevant agents +- [ ] Users can accept/decline/never-ask for suggestions +- [ ] `/agents` command manages user's garden +- [ ] Predefined agents installable from library +- [ ] Custom agents creatable and storable + +### Non-Functional Requirements + +- [ ] Agent discovery < 100ms for 50 agents +- [ ] Suggestion analysis adds < 2s to /compound +- [ ] No breaking changes for existing users +- [ ] Clear migration path from monolithic plugin + +### Quality Gates + +- [ ] Documentation for growth model +- [ ] Tests for agent discovery priority +- [ ] Tests for tech stack detection +- [ ] User feedback mechanism in suggestions + +--- + +## Success Metrics + +| Metric | Target | Measurement | +|--------|--------|-------------| +| Adoption | 50% of users add β‰₯1 agent within 30 days | Track /agents add usage | +| Engagement | Average 3+ agents per active user | Count ~/.claude/agents/ | +| Retention | 80% of added agents still enabled after 30 days | Track disable/remove | +| Satisfaction | Suggestion acceptance rate > 40% | Track y/n responses | + +--- + +## Implementation Phases + +### Phase 1: Split (No Breaking Changes) +**Goal:** Separate core from optional agents, keep everything working + +1. Create `agent-library/` directory structure +2. Move framework-specific agents to library +3. Update marketplace.json with both plugins +4. Keep `compounding-engineering` as meta-package that includes both +5. Test existing users unaffected + +**Files to create:** +- `plugins/agent-library/.claude-plugin/plugin.json` +- `plugins/agent-library/rails/*.md` (move existing) +- `plugins/agent-library/python/*.md` (move existing) +- `plugins/agent-library/typescript/*.md` (move existing) +- `plugins/agent-library/frontend/*.md` (move existing) + +### Phase 2: Discovery +**Goal:** Commands discover agents from multiple locations + +1. Implement agent discovery in /review +2. Support project β†’ user β†’ plugin priority +3. Add agent metadata frontmatter parsing +4. Test with agents in different locations + +**Files to modify:** +- `plugins/compounding-engineering/commands/workflows/review.md` +- All agent files (add frontmatter) + +### Phase 3: Growth +**Goal:** /compound suggests agents based on learnings + +1. Add tech stack detection +2. Implement suggestion matching against library +3. Design and implement suggestion UX +4. Handle accept/decline/never-ask responses +5. Auto-install accepted agents to ~/.claude/agents/ + +**Files to modify:** +- `plugins/compounding-engineering/commands/workflows/compound.md` +- `plugins/compounding-engineering/skills/compound-docs/SKILL.md` + +### Phase 4: Management +**Goal:** Users can manage their garden + +1. Create `/agents` command with subcommands +2. Implement list, add, remove, disable, enable +3. Add export/import for sharing +4. Add custom agent creation wizard + +**Files to create:** +- `plugins/compounding-engineering/commands/agents.md` + +--- + +## Dependencies & Prerequisites + +- [ ] Claude Code plugin system supports user-level agents (~/.claude/agents/) +- [ ] Agent frontmatter can be parsed for metadata +- [ ] /review can be modified to support dynamic agent discovery + +--- + +## Risk Analysis & Mitigation + +| Risk | Likelihood | Impact | Mitigation | +|------|------------|--------|------------| +| User confusion with growth model | Medium | High | Clear onboarding, simple defaults | +| Performance with many agents | Low | Medium | Lazy loading, parallel execution | +| Breaking existing workflows | Low | High | Phased rollout, meta-package option | +| Suggestion fatigue | Medium | Medium | Smart throttling, "never ask" option | + +--- + +## Future Considerations + +1. **Dynamic Agent Generation:** LLM generates custom agent from learning context +2. **Agent Marketplace:** Community-contributed agents with ratings +3. **Team Gardens:** Shared agent collections for organizations +4. **Agent Composition:** Agents that build on other agents +5. **Auto-Refinement:** Agents improve from user feedback over time + +--- + +## References + +### Internal +- GitHub Issue: https://github.com/EveryInc/compounding-engineering-plugin/issues/20 +- Current plugin structure: `plugins/compounding-engineering/` +- Agent examples: `plugins/compounding-engineering/agents/` + +### External +- [VSCode Extension Packs](https://code.visualstudio.com/api/references/extension-manifest) +- [Claude Code Plugin Docs](https://docs.claude.com/en/docs/claude-code/plugins) +- [Claude Code Plugin Dependencies Request](https://github.com/anthropics/claude-code/issues/9444) + +--- + +## ERD: Agent Discovery + +```mermaid +erDiagram + USER ||--o{ USER_AGENT : "grows" + USER ||--o{ PROJECT : "works on" + PROJECT ||--o{ PROJECT_AGENT : "has" + PLUGIN ||--o{ PLUGIN_AGENT : "provides" + AGENT_LIBRARY ||--o{ PREDEFINED_AGENT : "contains" + + USER_AGENT { + string name + string tech_stack + string commands + string source + boolean enabled + } + + PROJECT_AGENT { + string name + string tech_stack + string commands + boolean enabled + } + + PLUGIN_AGENT { + string name + string tech_stack + string commands + } + + PREDEFINED_AGENT { + string name + string category + string tech_stack + string description + } + + COMMAND ||--o{ AGENT : "discovers" + COMMAND { + string name + string type + } + + AGENT { + string source_location + int priority + } +``` + +--- + +## Appendix: Component Categorization + +### Core Plugin (Seed) - 22 Components + +**Commands (4):** +| Command | Purpose | +|---------|---------| +| /plan | Create implementation plans | +| /work | Execute work systematically | +| /review | Multi-agent code review | +| /compound | Document learnings + suggest growth | + +**Core Agents (11):** +| Agent | Category | Purpose | +|-------|----------|---------| +| security-sentinel | review | Security audits | +| performance-oracle | review | Performance analysis | +| code-simplicity-reviewer | review | Simplicity checks | +| architecture-strategist | review | Architecture review | +| pattern-recognition-specialist | review | Pattern analysis | +| best-practices-researcher | research | External best practices | +| framework-docs-researcher | research | Framework documentation | +| git-history-analyzer | research | Git archaeology | +| repo-research-analyst | research | Repository analysis | +| bug-reproduction-validator | workflow | Bug reproduction | +| spec-flow-analyzer | workflow | Spec analysis | + +**Skills (5):** +| Skill | Purpose | +|-------|---------| +| compound-docs | Document learnings | +| file-todos | Todo tracking | +| git-worktree | Parallel development | +| create-agent-skills | Skill creation | +| skill-creator | Skill guidance | + +**MCP Servers (2):** +| Server | Purpose | +|--------|---------| +| playwright | Browser automation | +| context7 | Documentation lookup | + +### Agent Library - 10 Agents + +**Rails (3):** +- kieran-rails-reviewer +- dhh-rails-reviewer +- data-integrity-guardian + +**Python (1):** +- kieran-python-reviewer + +**TypeScript (1):** +- kieran-typescript-reviewer + +**Frontend (4):** +- julik-frontend-races-reviewer +- design-iterator +- design-implementation-reviewer +- figma-design-sync + +**Editorial (1):** +- every-style-editor diff --git a/plugins/compounding-engineering/.claude-plugin/plugin.json b/plugins/compounding-engineering/.claude-plugin/plugin.json index 119e00f..2cb141b 100644 --- a/plugins/compounding-engineering/.claude-plugin/plugin.json +++ b/plugins/compounding-engineering/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "compounding-engineering", - "version": "2.8.0", + "version": "2.8.1", "description": "AI-powered development tools. 24 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", diff --git a/plugins/compounding-engineering/CHANGELOG.md b/plugins/compounding-engineering/CHANGELOG.md index 61df97e..00a1800 100644 --- a/plugins/compounding-engineering/CHANGELOG.md +++ b/plugins/compounding-engineering/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to the compounding-engineering plugin will be documented in The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.8.1] - 2025-11-27 + +### Added + +- **`/plan` command** - Added "Create Issue" option to post-generation menu. Detects project tracker (GitHub or Linear) from user's CLAUDE.md (`project_tracker: github` or `project_tracker: linear`) and creates issues using `gh issue create` or Linear CLI. + ## [2.8.0] - 2025-11-27 ### Added diff --git a/plugins/compounding-engineering/commands/workflows/plan.md b/plugins/compounding-engineering/commands/workflows/plan.md index 4781f52..452408a 100644 --- a/plugins/compounding-engineering/commands/workflows/plan.md +++ b/plugins/compounding-engineering/commands/workflows/plan.md @@ -378,16 +378,47 @@ After writing the plan file, use the **AskUserQuestion tool** to present these o **Options:** 1. **Start `/work`** - Begin implementing this plan 2. **Run `/plan_review`** - Get feedback from reviewers (DHH, Kieran, Simplicity) -3. **Simplify** - Reduce detail level -4. **Rework** - Change approach or request specific changes +3. **Create Issue** - Create issue in project tracker (GitHub/Linear) +4. **Simplify** - Reduce detail level +5. **Rework** - Change approach or request specific changes Based on selection: - **`/work`** β†’ Call the /work command with the plan file path - **`/plan_review`** β†’ Call the /plan_review command with the plan file path +- **Create Issue** β†’ See "Issue Creation" section below - **Simplify** β†’ Ask "What should I simplify?" then regenerate simpler version - **Rework** β†’ Ask "What would you like changed?" then regenerate with changes - **Other** (automatically provided) β†’ Accept free text, act on it Loop back to options after Simplify/Rework until user selects `/work` or `/plan_review`. +## Issue Creation + +When user selects "Create Issue", detect their project tracker from CLAUDE.md: + +1. **Check for tracker preference** in user's CLAUDE.md (global or project): + - Look for `project_tracker: github` or `project_tracker: linear` + - Or look for mentions of "GitHub Issues" or "Linear" in their workflow section + +2. **If GitHub:** + ```bash + # Extract title from plan filename (kebab-case to Title Case) + # Read plan content for body + gh issue create --title "feat: [Plan Title]" --body-file plans/.md + ``` + +3. **If Linear:** + ```bash + # Use linear CLI if available, or provide instructions + # linear issue create --title "[Plan Title]" --description "$(cat plans/.md)" + ``` + +4. **If no tracker configured:** + Ask user: "Which project tracker do you use? (GitHub/Linear/Other)" + - Suggest adding `project_tracker: github` or `project_tracker: linear` to their CLAUDE.md + +5. **After creation:** + - Display the issue URL + - Ask if they want to proceed to `/work` or `/plan_review` + NEVER CODE! Just research and write the plan. From f2db1277e608a6554dba9df504bb37bc16f951b5 Mon Sep 17 00:00:00 2001 From: Kieran Klaassen Date: Thu, 27 Nov 2025 20:02:09 -0800 Subject: [PATCH 25/25] Simplify grow-your-own-garden plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reduced from ~645 lines to ~100 lines while keeping the core concepts: - The seed (4 commands + universal agents) - The growth loop via /compound - Agent storage hierarchy - Implementation phases πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- ...row-your-own-garden-plugin-architecture.md | 674 ++---------------- 1 file changed, 66 insertions(+), 608 deletions(-) diff --git a/plans/grow-your-own-garden-plugin-architecture.md b/plans/grow-your-own-garden-plugin-architecture.md index 729a0ba..b21746c 100644 --- a/plans/grow-your-own-garden-plugin-architecture.md +++ b/plans/grow-your-own-garden-plugin-architecture.md @@ -1,644 +1,102 @@ # Grow Your Own Garden: Adaptive Agent Ecosystem -> **Issue Reference:** https://github.com/EveryInc/compounding-engineering-plugin/issues/20 -> **Date:** 2025-11-27 -> **Status:** Draft Plan +> **Issue:** https://github.com/EveryInc/compounding-engineering-plugin/issues/20 -## Overview +## The Idea -Transform the compounding-engineering plugin from a monolithic collection into an **adaptive ecosystem** where users grow their own personalized agent gardens from a minimal seed. The core loop (`/plan`, `/work`, `/review`, `/compound`) stays universal, but each user's agent collection evolves based on their learnings. +Everyone grows their own garden, but we're all using the same process. -**Philosophy:** Everyone grows their own garden, but we're all using the same process. +Start from a **seed** (minimal core: `/plan`, `/work`, `/review`, `/compound`). Each `/compound` loop can suggest adding agents based on what you're working onβ€”like building up a test suite to prevent regressions, but for code review expertise. ---- +## Current Problem -## Problem Statement - -### Current State -- Monolithic plugin: 24 agents, 16 commands, 11 skills -- Users get everything, use maybe 30% -- No personalization - same agents for Rails developer and Python developer -- No growth mechanism - static collection that doesn't adapt - -### Desired State -- Minimal seed: 4 commands + ~6 core agents -- Organic growth: `/compound` suggests relevant agents based on learnings -- Personalized gardens: Rails developer accumulates Rails experts, Python developer accumulates Python experts -- Shared process: Core workflow identical across all users - ---- +- Monolithic plugin: 24 agents, users use ~30% +- No personalization (same agents for Rails dev and Python dev) +- Static collection that doesn't adapt ## Proposed Solution -### Architecture: Seed + Growth Model +### The Seed (Core Plugin) -``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ SEED PLUGIN (Core) β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ /plan β”‚ β”‚ /work β”‚ β”‚ /review β”‚ β”‚/compound β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ β”‚ -β”‚ Core Agents: security-sentinel, performance-oracle, β”‚ -β”‚ code-simplicity-reviewer, architecture-strategist β”‚ -β”‚ pattern-recognition-specialist β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”‚ /compound triggers growth - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ USER'S GARDEN (~/.claude/agents/) β”‚ -β”‚ β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ Predefined β”‚ β”‚ Dynamic β”‚ β”‚ Custom β”‚ β”‚ -β”‚ β”‚ (from library) β”‚ β”‚ (generated) β”‚ β”‚ (user-written) β”‚ β”‚ -β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ β”‚ -β”‚ β”‚ β€’ dhh-rails β”‚ β”‚ β€’ actor-model β”‚ β”‚ β€’ our-api-style β”‚ β”‚ -β”‚ β”‚ β€’ kieran-python β”‚ β”‚ expert β”‚ β”‚ β€’ team-patterns β”‚ β”‚ -β”‚ β”‚ β€’ typescript β”‚ β”‚ β€’ graphql-best β”‚ β”‚ β”‚ β”‚ -β”‚ β”‚ reviewer β”‚ β”‚ practices β”‚ β”‚ β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β”‚ /review discovers all agents - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ PROJECT OVERRIDES (.claude/agents/) β”‚ -β”‚ β”‚ -β”‚ Project-specific agents that override or supplement global β”‚ -β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ -β”‚ β”‚ β€’ cora-specific β”‚ (only runs in ~/Reels/cora/) β”‚ -β”‚ β”‚ β€’ hotwire-nativeβ”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` +4 commands + minimal agents: + +| Component | What's Included | +|-----------|-----------------| +| Commands | `/plan`, `/work`, `/review`, `/compound` | +| Review Agents | security, performance, simplicity, architecture, patterns | +| Research Agents | best-practices, framework-docs, git-history, repo-analyst | +| Skills | compound-docs, file-todos, git-worktree | +| MCP Servers | playwright, context7 | ### The Growth Loop -``` -User completes work - β”‚ - β–Ό - Runs /compound - β”‚ - β–Ό -System analyzes: -β€’ Git diff (files changed, patterns) -β€’ Tech stack (Gemfile, package.json) -β€’ Learning content - β”‚ - β–Ό -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ SUGGESTION ENGINE β”‚ -β”‚ β”‚ -β”‚ Match detected patterns against: β”‚ -β”‚ 1. Predefined agent library (curated) β”‚ -β”‚ 2. Dynamic generation capability β”‚ -β”‚ 3. User's existing agents (avoid duplicates) β”‚ -β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ - β”‚ - β–Ό - Three possible outcomes: - β”‚ - β”œβ”€β–Ί "You're using Rails. Add DHH reviewer?" [y/n] - β”‚ (Predefined agent from library) - β”‚ - β”œβ”€β–Ί "You're using actor model. Create an expert?" [y/n] - β”‚ (Dynamic agent generation) - β”‚ - └─► "Want to create a custom agent for this pattern?" [y/n] - (User-defined agent) - β”‚ - β–Ό - Agent added to ~/.claude/agents/ - β”‚ - β–Ό - Next /review includes new agent -``` - ---- - -## Technical Approach - -### Phase 1: Split Into Core + Agent Library - -**New Marketplace Structure:** +After each `/compound`: ``` -every-marketplace/ -β”œβ”€β”€ .claude-plugin/ -β”‚ └── marketplace.json -β”œβ”€β”€ plugins/ -β”‚ β”œβ”€β”€ compounding-engineering/ # CORE (seed) -β”‚ β”‚ β”œβ”€β”€ .claude-plugin/plugin.json -β”‚ β”‚ β”œβ”€β”€ agents/ -β”‚ β”‚ β”‚ β”œβ”€β”€ review/ -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ security-sentinel.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ performance-oracle.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ code-simplicity-reviewer.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ architecture-strategist.md -β”‚ β”‚ β”‚ β”‚ └── pattern-recognition-specialist.md -β”‚ β”‚ β”‚ β”œβ”€β”€ research/ -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ best-practices-researcher.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ framework-docs-researcher.md -β”‚ β”‚ β”‚ β”‚ β”œβ”€β”€ git-history-analyzer.md -β”‚ β”‚ β”‚ β”‚ └── repo-research-analyst.md -β”‚ β”‚ β”‚ └── workflow/ -β”‚ β”‚ β”‚ β”œβ”€β”€ bug-reproduction-validator.md -β”‚ β”‚ β”‚ └── spec-flow-analyzer.md -β”‚ β”‚ β”œβ”€β”€ commands/ -β”‚ β”‚ β”‚ └── workflows/ -β”‚ β”‚ β”‚ β”œβ”€β”€ plan.md -β”‚ β”‚ β”‚ β”œβ”€β”€ work.md -β”‚ β”‚ β”‚ β”œβ”€β”€ review.md -β”‚ β”‚ β”‚ └── compound.md -β”‚ β”‚ β”œβ”€β”€ skills/ -β”‚ β”‚ β”‚ β”œβ”€β”€ compound-docs/ -β”‚ β”‚ β”‚ β”œβ”€β”€ file-todos/ -β”‚ β”‚ β”‚ β”œβ”€β”€ git-worktree/ -β”‚ β”‚ β”‚ β”œβ”€β”€ create-agent-skills/ -β”‚ β”‚ β”‚ └── skill-creator/ -β”‚ β”‚ └── mcp-servers/ -β”‚ β”‚ β”œβ”€β”€ playwright -β”‚ β”‚ └── context7 -β”‚ β”‚ -β”‚ └── agent-library/ # OPTIONAL (predefined agents) -β”‚ β”œβ”€β”€ .claude-plugin/plugin.json -β”‚ β”œβ”€β”€ rails/ -β”‚ β”‚ β”œβ”€β”€ kieran-rails-reviewer.md -β”‚ β”‚ β”œβ”€β”€ dhh-rails-reviewer.md -β”‚ β”‚ └── data-integrity-guardian.md -β”‚ β”œβ”€β”€ python/ -β”‚ β”‚ └── kieran-python-reviewer.md -β”‚ β”œβ”€β”€ typescript/ -β”‚ β”‚ └── kieran-typescript-reviewer.md -β”‚ β”œβ”€β”€ frontend/ -β”‚ β”‚ β”œβ”€β”€ julik-frontend-races-reviewer.md -β”‚ β”‚ β”œβ”€β”€ design-iterator.md -β”‚ β”‚ β”œβ”€β”€ design-implementation-reviewer.md -β”‚ β”‚ └── figma-design-sync.md -β”‚ └── editorial/ -β”‚ └── every-style-editor.md -└── docs/ +βœ… Learning documented + +πŸ’‘ It looks like you're using Rails. + Would you like to add the "DHH Rails Reviewer"? + + [y] Yes [n] No [x] Never ask ``` -**Core Plugin Components (Seed):** +Three sources of new agents: +1. **Predefined** - "You're using Rails, add DHH reviewer?" +2. **Dynamic** - "You're using actor model, create an expert?" +3. **Custom** - "Want to create an agent for this pattern?" -| Category | Components | Count | -|----------|------------|-------| -| Commands | /plan, /work, /review, /compound | 4 | -| Review Agents | security, performance, simplicity, architecture, patterns | 5 | -| Research Agents | best-practices, framework-docs, git-history, repo-analyst | 4 | -| Workflow Agents | bug-reproduction, spec-flow | 2 | -| Skills | compound-docs, file-todos, git-worktree, create-agent-skills, skill-creator | 5 | -| MCP Servers | playwright, context7 | 2 | -| **TOTAL** | | **22 components** | - -**Agent Library (Optional Install):** - -| Category | Agents | Count | -|----------|--------|-------| -| Rails | kieran-rails, dhh-rails, data-integrity | 3 | -| Python | kieran-python | 1 | -| TypeScript | kieran-typescript | 1 | -| Frontend | julik-races, design-iterator, design-reviewer, figma-sync | 4 | -| Editorial | every-style-editor | 1 | -| **TOTAL** | | **10 agents** | - -### Phase 2: Agent Discovery & Storage - -**Agent Storage Locations (priority order):** +### Agent Storage ``` -1. Project agents: .claude/agents/*.md (highest priority) -2. User agents: ~/.claude/agents/*.md (user's garden) -3. Plugin agents: plugin/agents/*.md (from installed plugins) +.claude/agents/ β†’ Project-specific (highest priority) +~/.claude/agents/ β†’ User's garden +plugin/agents/ β†’ From installed plugins ``` -**Agent Metadata Format (frontmatter):** - -```yaml ---- -name: dhh-rails-reviewer -description: Reviews Rails code from DHH's perspective -tech_stack: [rails, ruby] # When to suggest -commands: [review] # Which commands use this -priority: 10 # Execution order (higher = first) -source: predefined # predefined | dynamic | custom -version: 1.0.0 -enabled: true # Can be disabled without deletion ---- -``` - -**Discovery Mechanism:** - -```ruby -# Pseudocode for /review agent discovery -def discover_agents(command: "review") - agents = [] - - # 1. Project agents (highest priority) - agents += glob(".claude/agents/**/*.md") - .filter { |a| a.commands.include?(command) && a.enabled } - - # 2. User's garden - agents += glob("~/.claude/agents/**/*.md") - .filter { |a| a.commands.include?(command) && a.enabled } - .reject { |a| agents.any? { |pa| pa.name == a.name } } # no duplicates - - # 3. Plugin agents - installed_plugins.each do |plugin| - agents += plugin.agents - .filter { |a| a.commands.include?(command) && a.enabled } - .reject { |a| agents.any? { |ea| ea.name == a.name } } - end - - agents.sort_by(&:priority).reverse -end -``` - -### Phase 3: Enhanced /compound with Growth - -**Updated /compound Flow:** - -```markdown -## /compound command (enhanced) - -1. Document the learning (existing behavior) - - Capture solution to compound-docs - -2. Analyze context (NEW) - - Detect tech stack from project files - - Analyze git diff for patterns - - Check user's existing agents - -3. Suggest growth (NEW) - - Match patterns to agent library - - Consider dynamic agent generation - - Present suggestion with clear UX - -4. Handle response (NEW) - - Accept: Install agent to ~/.claude/agents/ - - Decline: Record preference, don't ask again for this agent - - Custom: Launch agent creation workflow -``` - -**Suggestion UX (non-blocking):** - -``` -βœ… Learning documented to compound-docs - -πŸ’‘ Growth suggestion: - Your solution uses Rails conventions extensively. - - Would you like to add the "DHH Rails Reviewer" agent? - This agent reviews code from DHH's perspective, checking for: - β€’ Rails conventions and idioms - β€’ Hotwire/Turbo patterns - β€’ Fat models, skinny controllers - - [y] Yes, add it [n] No thanks [?] Tell me more [x] Never suggest this -``` - -**Tech Stack Detection:** - -```ruby -def detect_tech_stack(project_root) - stack = [] - - # Ruby/Rails - stack << :rails if File.exist?("Gemfile") && - File.read("Gemfile").include?("rails") - stack << :ruby if File.exist?("Gemfile") - - # JavaScript/TypeScript - if File.exist?("package.json") - pkg = JSON.parse(File.read("package.json")) - stack << :react if pkg.dig("dependencies", "react") - stack << :vue if pkg.dig("dependencies", "vue") - stack << :typescript if pkg.dig("devDependencies", "typescript") - stack << :node if pkg["type"] == "module" || pkg["main"] - end - - # Python - stack << :python if File.exist?("requirements.txt") || - File.exist?("pyproject.toml") - stack << :django if File.exist?("manage.py") - stack << :fastapi if File.read("requirements.txt")&.include?("fastapi") - - # Go - stack << :go if File.exist?("go.mod") - - stack -end -``` - -### Phase 4: Agent Management Commands - -**New Commands:** - -```bash -# List all agents in user's garden + plugins -/agents list -/agents list --tech rails # Filter by tech stack -/agents list --command review # Filter by command - -# Add agent from library -/agents add dhh-rails-reviewer -/agents add kieran-python-reviewer - -# Remove agent from garden -/agents remove dhh-rails-reviewer - -# Disable without removing -/agents disable dhh-rails-reviewer -/agents enable dhh-rails-reviewer - -# Create custom agent -/agents create "Our API Style Guide" - -# View agent details -/agents show dhh-rails-reviewer - -# Export for sharing -/agents export dhh-rails-reviewer > my-dhh-tweaks.md - -# Import shared agent -/agents import ./shared-agents/team-patterns.md -``` - ---- - -## Alternative Approaches Considered - -### Option A: Keep Monolithic (Current) -- **Pros:** Simple, one install, everything works -- **Cons:** Bloated, no personalization, no growth -- **Decision:** Rejected - doesn't support the "grow your garden" vision - -### Option B: Separate Plugins per Tech Stack -- **Pros:** Users install only what they need -- **Cons:** No dependency support in Claude Code, manual multi-install required -- **Decision:** Rejected - friction too high, doesn't enable organic growth - -### Option C: Core + Agent Library + Growth (Proposed) -- **Pros:** Minimal start, organic growth, personalized, shared process -- **Cons:** More complex implementation, new UX to design -- **Decision:** Selected - best aligns with vision - ---- - -## Acceptance Criteria - -### Functional Requirements - -- [ ] Core plugin installs with 4 commands + ~11 core agents -- [ ] `/review` discovers agents from project β†’ user β†’ plugin locations -- [ ] `/compound` detects tech stack and suggests relevant agents -- [ ] Users can accept/decline/never-ask for suggestions -- [ ] `/agents` command manages user's garden -- [ ] Predefined agents installable from library -- [ ] Custom agents creatable and storable - -### Non-Functional Requirements - -- [ ] Agent discovery < 100ms for 50 agents -- [ ] Suggestion analysis adds < 2s to /compound -- [ ] No breaking changes for existing users -- [ ] Clear migration path from monolithic plugin - -### Quality Gates - -- [ ] Documentation for growth model -- [ ] Tests for agent discovery priority -- [ ] Tests for tech stack detection -- [ ] User feedback mechanism in suggestions - ---- - -## Success Metrics - -| Metric | Target | Measurement | -|--------|--------|-------------| -| Adoption | 50% of users add β‰₯1 agent within 30 days | Track /agents add usage | -| Engagement | Average 3+ agents per active user | Count ~/.claude/agents/ | -| Retention | 80% of added agents still enabled after 30 days | Track disable/remove | -| Satisfaction | Suggestion acceptance rate > 40% | Track y/n responses | - ---- - ## Implementation Phases -### Phase 1: Split (No Breaking Changes) -**Goal:** Separate core from optional agents, keep everything working +### Phase 1: Split the Plugin +- Create `agent-library/` with framework-specific agents (Rails, Python, TypeScript, Frontend) +- Keep `compounding-engineering` as core with universal agents +- No breaking changesβ€”existing users unaffected -1. Create `agent-library/` directory structure -2. Move framework-specific agents to library -3. Update marketplace.json with both plugins -4. Keep `compounding-engineering` as meta-package that includes both -5. Test existing users unaffected +### Phase 2: Agent Discovery +- `/review` discovers agents from all three locations +- Project agents override user agents override plugin agents -**Files to create:** -- `plugins/agent-library/.claude-plugin/plugin.json` -- `plugins/agent-library/rails/*.md` (move existing) -- `plugins/agent-library/python/*.md` (move existing) -- `plugins/agent-library/typescript/*.md` (move existing) -- `plugins/agent-library/frontend/*.md` (move existing) - -### Phase 2: Discovery -**Goal:** Commands discover agents from multiple locations - -1. Implement agent discovery in /review -2. Support project β†’ user β†’ plugin priority -3. Add agent metadata frontmatter parsing -4. Test with agents in different locations - -**Files to modify:** -- `plugins/compounding-engineering/commands/workflows/review.md` -- All agent files (add frontmatter) - -### Phase 3: Growth -**Goal:** /compound suggests agents based on learnings - -1. Add tech stack detection -2. Implement suggestion matching against library -3. Design and implement suggestion UX -4. Handle accept/decline/never-ask responses -5. Auto-install accepted agents to ~/.claude/agents/ - -**Files to modify:** -- `plugins/compounding-engineering/commands/workflows/compound.md` -- `plugins/compounding-engineering/skills/compound-docs/SKILL.md` +### Phase 3: Growth via /compound +- Detect tech stack (Gemfile, package.json, etc.) +- Suggest relevant agents after documenting learnings +- Install accepted agents to `~/.claude/agents/` ### Phase 4: Management -**Goal:** Users can manage their garden +- `/agents list` - See your garden +- `/agents add ` - Add from library +- `/agents disable ` - Temporarily disable -1. Create `/agents` command with subcommands -2. Implement list, add, remove, disable, enable -3. Add export/import for sharing -4. Add custom agent creation wizard +## What Goes Where -**Files to create:** -- `plugins/compounding-engineering/commands/agents.md` +**Core (seed):** 11 framework-agnostic agents +- security-sentinel, performance-oracle, code-simplicity-reviewer +- architecture-strategist, pattern-recognition-specialist +- 4 research agents, 2 workflow agents ---- +**Agent Library:** 10 specialized agents +- Rails: kieran-rails, dhh-rails, data-integrity (3) +- Python: kieran-python (1) +- TypeScript: kieran-typescript (1) +- Frontend: julik-races, design-iterator, design-reviewer, figma-sync (4) +- Editorial: every-style-editor (1) -## Dependencies & Prerequisites +## Key Constraint -- [ ] Claude Code plugin system supports user-level agents (~/.claude/agents/) -- [ ] Agent frontmatter can be parsed for metadata -- [ ] /review can be modified to support dynamic agent discovery +Claude Code doesn't support plugin dependencies. Each plugin must be independent. Users manually install what they need, or we suggest additions via `/compound`. ---- +## Acceptance Criteria -## Risk Analysis & Mitigation - -| Risk | Likelihood | Impact | Mitigation | -|------|------------|--------|------------| -| User confusion with growth model | Medium | High | Clear onboarding, simple defaults | -| Performance with many agents | Low | Medium | Lazy loading, parallel execution | -| Breaking existing workflows | Low | High | Phased rollout, meta-package option | -| Suggestion fatigue | Medium | Medium | Smart throttling, "never ask" option | - ---- - -## Future Considerations - -1. **Dynamic Agent Generation:** LLM generates custom agent from learning context -2. **Agent Marketplace:** Community-contributed agents with ratings -3. **Team Gardens:** Shared agent collections for organizations -4. **Agent Composition:** Agents that build on other agents -5. **Auto-Refinement:** Agents improve from user feedback over time - ---- - -## References - -### Internal -- GitHub Issue: https://github.com/EveryInc/compounding-engineering-plugin/issues/20 -- Current plugin structure: `plugins/compounding-engineering/` -- Agent examples: `plugins/compounding-engineering/agents/` - -### External -- [VSCode Extension Packs](https://code.visualstudio.com/api/references/extension-manifest) -- [Claude Code Plugin Docs](https://docs.claude.com/en/docs/claude-code/plugins) -- [Claude Code Plugin Dependencies Request](https://github.com/anthropics/claude-code/issues/9444) - ---- - -## ERD: Agent Discovery - -```mermaid -erDiagram - USER ||--o{ USER_AGENT : "grows" - USER ||--o{ PROJECT : "works on" - PROJECT ||--o{ PROJECT_AGENT : "has" - PLUGIN ||--o{ PLUGIN_AGENT : "provides" - AGENT_LIBRARY ||--o{ PREDEFINED_AGENT : "contains" - - USER_AGENT { - string name - string tech_stack - string commands - string source - boolean enabled - } - - PROJECT_AGENT { - string name - string tech_stack - string commands - boolean enabled - } - - PLUGIN_AGENT { - string name - string tech_stack - string commands - } - - PREDEFINED_AGENT { - string name - string category - string tech_stack - string description - } - - COMMAND ||--o{ AGENT : "discovers" - COMMAND { - string name - string type - } - - AGENT { - string source_location - int priority - } -``` - ---- - -## Appendix: Component Categorization - -### Core Plugin (Seed) - 22 Components - -**Commands (4):** -| Command | Purpose | -|---------|---------| -| /plan | Create implementation plans | -| /work | Execute work systematically | -| /review | Multi-agent code review | -| /compound | Document learnings + suggest growth | - -**Core Agents (11):** -| Agent | Category | Purpose | -|-------|----------|---------| -| security-sentinel | review | Security audits | -| performance-oracle | review | Performance analysis | -| code-simplicity-reviewer | review | Simplicity checks | -| architecture-strategist | review | Architecture review | -| pattern-recognition-specialist | review | Pattern analysis | -| best-practices-researcher | research | External best practices | -| framework-docs-researcher | research | Framework documentation | -| git-history-analyzer | research | Git archaeology | -| repo-research-analyst | research | Repository analysis | -| bug-reproduction-validator | workflow | Bug reproduction | -| spec-flow-analyzer | workflow | Spec analysis | - -**Skills (5):** -| Skill | Purpose | -|-------|---------| -| compound-docs | Document learnings | -| file-todos | Todo tracking | -| git-worktree | Parallel development | -| create-agent-skills | Skill creation | -| skill-creator | Skill guidance | - -**MCP Servers (2):** -| Server | Purpose | -|--------|---------| -| playwright | Browser automation | -| context7 | Documentation lookup | - -### Agent Library - 10 Agents - -**Rails (3):** -- kieran-rails-reviewer -- dhh-rails-reviewer -- data-integrity-guardian - -**Python (1):** -- kieran-python-reviewer - -**TypeScript (1):** -- kieran-typescript-reviewer - -**Frontend (4):** -- julik-frontend-races-reviewer -- design-iterator -- design-implementation-reviewer -- figma-design-sync - -**Editorial (1):** -- every-style-editor +- [ ] Core plugin works standalone with universal agents +- [ ] `/compound` suggests agents based on detected tech stack +- [ ] Users can accept/decline suggestions +- [ ] `/agents` command for garden management +- [ ] No breaking changes for existing users