feat: Rename workflows:* to ce:* with backwards-compatible deprecation (v2.38.0)
Add ce:plan, ce:work, ce:review, ce:brainstorm, ce:compound as the new primary commands. Old workflows:* names remain as thin deprecation wrappers that warn and forward with disable-model-invocation. Also removes the unused GitHub Pages documentation site. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Kieran Klaassen
@@ -12,7 +12,7 @@
|
||||
{
|
||||
"name": "compound-engineering",
|
||||
"description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 22 commands, and 20 skills.",
|
||||
"version": "2.37.2",
|
||||
"version": "2.38.0",
|
||||
"author": {
|
||||
"name": "Kieran Klaassen",
|
||||
"url": "https://github.com/kieranklaassen",
|
||||
|
||||
@@ -130,10 +130,10 @@ Plan → Work → Review → Compound → Repeat
|
||||
|
||||
| Command | Purpose |
|
||||
|---------|---------|
|
||||
| `/workflows:plan` | Turn feature ideas into detailed implementation plans |
|
||||
| `/workflows:work` | Execute plans with worktrees and task tracking |
|
||||
| `/workflows:review` | Multi-agent code review before merging |
|
||||
| `/workflows:compound` | Document learnings to make future work easier |
|
||||
| `/ce:plan` | Turn feature ideas into detailed implementation plans |
|
||||
| `/ce:work` | Execute plans with worktrees and task tracking |
|
||||
| `/ce:review` | Multi-agent code review before merging |
|
||||
| `/ce:compound` | Document learnings to make future work easier |
|
||||
|
||||
Each cycle compounds: plans inform future plans, reviews catch more issues, patterns get documented.
|
||||
|
||||
|
||||
@@ -1,675 +0,0 @@
|
||||
/* 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;
|
||||
}
|
||||
}
|
||||
|
||||
/* ============================================
|
||||
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;
|
||||
}
|
||||
2886
docs/css/style.css
2886
docs/css/style.css
File diff suppressed because it is too large
Load Diff
1046
docs/index.html
1046
docs/index.html
File diff suppressed because it is too large
Load Diff
225
docs/js/main.js
225
docs/js/main.js
@@ -1,225 +0,0 @@
|
||||
/**
|
||||
* 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 = '<i class="fa-regular fa-copy"></i>';
|
||||
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 = '<i class="fa-solid fa-check"></i>';
|
||||
copyBtn.style.color = '#34d399';
|
||||
|
||||
setTimeout(() => {
|
||||
copyBtn.innerHTML = '<i class="fa-regular fa-copy"></i>';
|
||||
copyBtn.style.color = '#94a3b8';
|
||||
}, 2000);
|
||||
} catch (err) {
|
||||
console.error('Failed to copy:', err);
|
||||
copyBtn.innerHTML = '<i class="fa-solid fa-xmark"></i>';
|
||||
copyBtn.style.color = '#f87171';
|
||||
|
||||
setTimeout(() => {
|
||||
copyBtn.innerHTML = '<i class="fa-regular fa-copy"></i>';
|
||||
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);
|
||||
@@ -1,649 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en" class="theme-dark">
|
||||
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Agent Reference - Compounding Engineering</title>
|
||||
<meta content="Complete reference for all 23 specialized AI agents in the Compounding Engineering plugin." name="description" />
|
||||
<meta content="width=device-width, initial-scale=1" name="viewport" />
|
||||
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" />
|
||||
<link href="../css/style.css" rel="stylesheet" type="text/css" />
|
||||
<link href="../css/docs.css" rel="stylesheet" type="text/css" />
|
||||
<script src="../js/main.js" type="text/javascript" defer></script>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div class="background-gradient"></div>
|
||||
<div class="docs-layout">
|
||||
<aside class="docs-sidebar">
|
||||
<div class="sidebar-header">
|
||||
<a href="../index.html" class="nav-brand">
|
||||
<span class="logo-icon"><i class="fa-solid fa-layer-group"></i></span>
|
||||
<span class="logo-text">CE Docs</span>
|
||||
</a>
|
||||
</div>
|
||||
<nav class="sidebar-nav">
|
||||
<div class="nav-section">
|
||||
<h3>Getting Started</h3>
|
||||
<ul>
|
||||
<li><a href="getting-started.html">Installation</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Reference</h3>
|
||||
<ul>
|
||||
<li><a href="agents.html" class="active">Agents (23)</a></li>
|
||||
<li><a href="commands.html">Commands (13)</a></li>
|
||||
<li><a href="skills.html">Skills (11)</a></li>
|
||||
<li><a href="mcp-servers.html">MCP Servers (2)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Resources</h3>
|
||||
<ul>
|
||||
<li><a href="changelog.html">Changelog</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>On This Page</h3>
|
||||
<ul>
|
||||
<li><a href="#review-agents">Review (10)</a></li>
|
||||
<li><a href="#research-agents">Research (4)</a></li>
|
||||
<li><a href="#workflow-agents">Workflow (5)</a></li>
|
||||
<li><a href="#design-agents">Design (3)</a></li>
|
||||
<li><a href="#docs-agents">Docs (1)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</nav>
|
||||
</aside>
|
||||
|
||||
<main class="docs-content">
|
||||
<div class="docs-header">
|
||||
<nav class="breadcrumb">
|
||||
<a href="../index.html">Home</a>
|
||||
<span>/</span>
|
||||
<a href="getting-started.html">Docs</a>
|
||||
<span>/</span>
|
||||
<span>Agents</span>
|
||||
</nav>
|
||||
<button class="mobile-menu-toggle" data-sidebar-toggle>
|
||||
<i class="fa-solid fa-bars"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<article class="docs-article">
|
||||
<h1><i class="fa-solid fa-users-gear color-accent"></i> Agent Reference</h1>
|
||||
<p class="lead">
|
||||
Think of agents as your expert teammates who never sleep. You've got 23 specialists here—each one obsessed with a single domain. Call them individually when you need focused expertise, or orchestrate them together for multi-angle analysis. They're opinionated, they're fast, and they remember your codebase better than you do.
|
||||
</p>
|
||||
|
||||
<div class="usage-box">
|
||||
<h3>How to Use Agents</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code># 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"</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Review Agents -->
|
||||
<section id="review-agents">
|
||||
<h2><i class="fa-solid fa-code-pull-request"></i> Review Agents (10)</h2>
|
||||
<p>Your code review dream team. These agents catch what humans miss at 2am—security holes, performance cliffs, architectural drift, and those "it works but I hate it" moments. They're picky. They disagree with each other. That's the point.</p>
|
||||
|
||||
<div class="agent-detail" id="kieran-rails-reviewer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>kieran-rails-reviewer</h3>
|
||||
<span class="agent-badge">Rails</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Your senior Rails developer who's seen too many "clever" solutions fail in production. Obsessed with code that's boring, predictable, and maintainable. Strict on existing code (because touching it risks everything), pragmatic on new isolated features (because shipping matters). If you've ever thought "this works but feels wrong," this reviewer will tell you why.
|
||||
</p>
|
||||
<h4>Key Principles</h4>
|
||||
<ul>
|
||||
<li><strong>Existing Code Modifications</strong> - Very strict. Added complexity needs strong justification.</li>
|
||||
<li><strong>New Code</strong> - Pragmatic. If it's isolated and works, it's acceptable.</li>
|
||||
<li><strong>Turbo Streams</strong> - Simple turbo streams MUST be inline arrays in controllers.</li>
|
||||
<li><strong>Testing as Quality</strong> - Hard-to-test code = poor structure that needs refactoring.</li>
|
||||
<li><strong>Naming (5-Second Rule)</strong> - Must understand what a view/component does in 5 seconds from its name.</li>
|
||||
<li><strong>Namespacing</strong> - Always use <code>class Module::ClassName</code> pattern.</li>
|
||||
<li><strong>Duplication > Complexity</strong> - Simple duplicated code is better than complex DRY abstractions.</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent kieran-rails-reviewer "Review the UserController"</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="dhh-rails-reviewer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>dhh-rails-reviewer</h3>
|
||||
<span class="agent-badge">Rails</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
What if DHH reviewed your Rails PR? He'd ask why you're building React inside Rails, why you need six layers of abstraction for a form, and whether you've forgotten that Rails already solved this problem. This agent channels that energy—blunt, opinionated, allergic to complexity.
|
||||
</p>
|
||||
<h4>Key Focus Areas</h4>
|
||||
<ul>
|
||||
<li>Identifies deviations from Rails conventions</li>
|
||||
<li>Spots JavaScript framework patterns infiltrating Rails</li>
|
||||
<li>Tears apart unnecessary abstractions</li>
|
||||
<li>Challenges overengineering and microservices mentality</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent dhh-rails-reviewer</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="kieran-python-reviewer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>kieran-python-reviewer</h3>
|
||||
<span class="agent-badge">Python</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Your Pythonic perfectionist who believes type hints aren't optional and <code>dict.get()</code> beats try/except KeyError. Expects modern Python 3.10+ patterns—no legacy syntax, no <code>typing.List</code> when <code>list</code> works natively. If your code looks like Java translated to Python, prepare for rewrites.
|
||||
</p>
|
||||
<h4>Key Focus Areas</h4>
|
||||
<ul>
|
||||
<li>Type hints for all functions</li>
|
||||
<li>Pythonic patterns and idioms</li>
|
||||
<li>Modern Python syntax</li>
|
||||
<li>Import organization</li>
|
||||
<li>Module extraction signals</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent kieran-python-reviewer</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="kieran-typescript-reviewer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>kieran-typescript-reviewer</h3>
|
||||
<span class="agent-badge">TypeScript</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
TypeScript's type system is a gift—don't throw it away with <code>any</code>. This reviewer treats <code>any</code> like a code smell that needs justification. Expects proper types, clean imports, and code that doesn't need comments because the types explain everything. You added TypeScript for safety; this agent makes sure you actually get it.
|
||||
</p>
|
||||
<h4>Key Focus Areas</h4>
|
||||
<ul>
|
||||
<li>No <code>any</code> without justification</li>
|
||||
<li>Component/module extraction signals</li>
|
||||
<li>Import organization</li>
|
||||
<li>Modern TypeScript patterns</li>
|
||||
<li>Testability assessment</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent kieran-typescript-reviewer</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="security-sentinel">
|
||||
<div class="agent-detail-header">
|
||||
<h3>security-sentinel</h3>
|
||||
<span class="agent-badge critical">Security</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Security vulnerabilities hide in boring code—the "just grab the user ID from params" line that ships a privilege escalation bug to production. This agent thinks like an attacker: SQL injection, XSS, auth bypass, leaked secrets. Run it before touching authentication, payments, or anything with PII. Your users' data depends on paranoia.
|
||||
</p>
|
||||
<h4>Security Checks</h4>
|
||||
<ul>
|
||||
<li>Input validation analysis</li>
|
||||
<li>SQL injection risk assessment</li>
|
||||
<li>XSS vulnerability detection</li>
|
||||
<li>Authentication/authorization audit</li>
|
||||
<li>Sensitive data exposure scanning</li>
|
||||
<li>OWASP Top 10 compliance</li>
|
||||
<li>Hardcoded secrets search</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent security-sentinel "Audit the payment flow"</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="performance-oracle">
|
||||
<div class="agent-detail-header">
|
||||
<h3>performance-oracle</h3>
|
||||
<span class="agent-badge">Performance</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Your code works fine with 10 users. What happens at 10,000? This agent time-travels to your future scaling problems—N+1 queries that murder your database, O(n²) algorithms hiding in loops, missing indexes, memory leaks. It thinks in Big O notation and asks uncomfortable questions about what breaks first when traffic spikes.
|
||||
</p>
|
||||
<h4>Analysis Areas</h4>
|
||||
<ul>
|
||||
<li>Algorithmic complexity (Big O notation)</li>
|
||||
<li>N+1 query pattern detection</li>
|
||||
<li>Proper index usage verification</li>
|
||||
<li>Memory management review</li>
|
||||
<li>Caching opportunity identification</li>
|
||||
<li>Network usage optimization</li>
|
||||
<li>Frontend bundle impact</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent performance-oracle</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="architecture-strategist">
|
||||
<div class="agent-detail-header">
|
||||
<h3>architecture-strategist</h3>
|
||||
<span class="agent-badge">Architecture</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Every "small change" either reinforces your architecture or starts eroding it. This agent zooms out to see if your fix actually fits the system's design—or if you're bolting duct tape onto a crumbling foundation. It speaks SOLID principles, microservice boundaries, and API contracts. Call it when you're about to make a change that "feels weird."
|
||||
</p>
|
||||
<h4>Analysis Areas</h4>
|
||||
<ul>
|
||||
<li>Overall system structure understanding</li>
|
||||
<li>Change context within architecture</li>
|
||||
<li>Architectural violation identification</li>
|
||||
<li>SOLID principles compliance</li>
|
||||
<li>Microservice boundary assessment</li>
|
||||
<li>API contract evaluation</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent architecture-strategist</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="data-integrity-guardian">
|
||||
<div class="agent-detail-header">
|
||||
<h3>data-integrity-guardian</h3>
|
||||
<span class="agent-badge critical">Data</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Migrations can't be rolled back once they're run on production. This agent is your last line of defense before you accidentally drop a column with user data, create a race condition in transactions, or violate GDPR. It obsesses over referential integrity, rollback safety, and data constraints. Your database is forever; migrations should be paranoid.
|
||||
</p>
|
||||
<h4>Review Areas</h4>
|
||||
<ul>
|
||||
<li>Migration safety and reversibility</li>
|
||||
<li>Data constraint validation</li>
|
||||
<li>Transaction boundary review</li>
|
||||
<li>Referential integrity preservation</li>
|
||||
<li>Privacy compliance (GDPR, CCPA)</li>
|
||||
<li>Data corruption scenario checking</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent data-integrity-guardian</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="pattern-recognition-specialist">
|
||||
<div class="agent-detail-header">
|
||||
<h3>pattern-recognition-specialist</h3>
|
||||
<span class="agent-badge">Patterns</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Patterns tell stories—Factory, Observer, God Object, Copy-Paste Programming. This agent reads your code like an archaeologist reading artifacts. It spots the good patterns (intentional design), the anti-patterns (accumulated tech debt), and the duplicated blocks you swore you'd refactor later. Runs tools like jscpd because humans miss repetition that machines catch instantly.
|
||||
</p>
|
||||
<h4>Detection Areas</h4>
|
||||
<ul>
|
||||
<li>Design patterns (Factory, Singleton, Observer, etc.)</li>
|
||||
<li>Anti-patterns and code smells</li>
|
||||
<li>TODO/FIXME comments</li>
|
||||
<li>God objects and circular dependencies</li>
|
||||
<li>Naming consistency</li>
|
||||
<li>Code duplication</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent pattern-recognition-specialist</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="code-simplicity-reviewer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>code-simplicity-reviewer</h3>
|
||||
<span class="agent-badge">Quality</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Simplicity is violent discipline. This agent asks "do you actually need this?" about every line, every abstraction, every dependency. YAGNI isn't a suggestion—it's the law. Your 200-line feature with three layers of indirection? This agent will show you the 50-line version that does the same thing. Complexity is a liability; simplicity compounds.
|
||||
</p>
|
||||
<h4>Simplification Checks</h4>
|
||||
<ul>
|
||||
<li>Analyze every line for necessity</li>
|
||||
<li>Simplify complex logic</li>
|
||||
<li>Remove redundancy and duplication</li>
|
||||
<li>Challenge abstractions</li>
|
||||
<li>Optimize for readability</li>
|
||||
<li>Eliminate premature generalization</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent code-simplicity-reviewer</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Research Agents -->
|
||||
<section id="research-agents">
|
||||
<h2><i class="fa-solid fa-microscope"></i> Research Agents (4)</h2>
|
||||
<p>Stop guessing. These agents dig through documentation, GitHub repos, git history, and real-world examples to give you answers backed by evidence. They read faster than you, remember more than you, and synthesize patterns you'd miss. Perfect for "how should I actually do this?" questions.</p>
|
||||
|
||||
<div class="agent-detail" id="framework-docs-researcher">
|
||||
<div class="agent-detail-header">
|
||||
<h3>framework-docs-researcher</h3>
|
||||
<span class="agent-badge">Research</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Official docs are scattered. GitHub examples are inconsistent. Deprecations hide in changelogs. This agent pulls it all together—docs, source code, version constraints, real-world examples. Ask "how do I use Hotwire Turbo?" and get back patterns that actually work in production, not toy tutorials.
|
||||
</p>
|
||||
<h4>Capabilities</h4>
|
||||
<ul>
|
||||
<li>Fetch official framework and library documentation</li>
|
||||
<li>Identify version-specific constraints and deprecations</li>
|
||||
<li>Search GitHub for real-world usage examples</li>
|
||||
<li>Analyze gem/library source code using <code>bundle show</code></li>
|
||||
<li>Synthesize findings with practical examples</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent framework-docs-researcher "Research Hotwire Turbo patterns"</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="best-practices-researcher">
|
||||
<div class="agent-detail-header">
|
||||
<h3>best-practices-researcher</h3>
|
||||
<span class="agent-badge">Research</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
"Best practices" are everywhere and contradictory. This agent cuts through the noise by evaluating sources (official docs, trusted blogs, real GitHub repos), checking recency, and synthesizing actionable guidance. You get code templates, patterns that scale, and answers you can trust—not StackOverflow copy-paste roulette.
|
||||
</p>
|
||||
<h4>Capabilities</h4>
|
||||
<ul>
|
||||
<li>Leverage multiple sources (Context7 MCP, web search, GitHub)</li>
|
||||
<li>Evaluate information quality and recency</li>
|
||||
<li>Synthesize into actionable guidance</li>
|
||||
<li>Provide code examples and templates</li>
|
||||
<li>Research issue templates and community engagement</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent best-practices-researcher "Find pagination patterns"</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="git-history-analyzer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>git-history-analyzer</h3>
|
||||
<span class="agent-badge">Git</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Your codebase has a history—decisions, patterns, mistakes. This agent does archaeology with git tools: file evolution, blame analysis, contributor expertise mapping. Ask "why does this code exist?" and get the commit that explains it. Spot patterns in how bugs appear. Understand the design decisions buried in history.
|
||||
</p>
|
||||
<h4>Analysis Techniques</h4>
|
||||
<ul>
|
||||
<li>Trace file evolution using <code>git log --follow</code></li>
|
||||
<li>Determine code origins using <code>git blame -w -C -C -C</code></li>
|
||||
<li>Identify patterns from commit history</li>
|
||||
<li>Map key contributors and expertise areas</li>
|
||||
<li>Extract historical patterns of issues and fixes</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent git-history-analyzer "Analyze changes to User model"</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="repo-research-analyst">
|
||||
<div class="agent-detail-header">
|
||||
<h3>repo-research-analyst</h3>
|
||||
<span class="agent-badge">Research</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Every repo has conventions—some documented, most tribal knowledge. This agent reads ARCHITECTURE.md, issue templates, PR patterns, and actual code to reverse-engineer the standards. Perfect for joining a new project or ensuring your PR matches the team's implicit style. Finds the rules nobody wrote down.
|
||||
</p>
|
||||
<h4>Analysis Areas</h4>
|
||||
<ul>
|
||||
<li>Architecture and documentation files (ARCHITECTURE.md, README.md, CLAUDE.md)</li>
|
||||
<li>GitHub issues for patterns and conventions</li>
|
||||
<li>Issue/PR templates and guidelines</li>
|
||||
<li>Implementation patterns using ast-grep or rg</li>
|
||||
<li>Project-specific conventions</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent repo-research-analyst</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Workflow Agents -->
|
||||
<section id="workflow-agents">
|
||||
<h2><i class="fa-solid fa-gears"></i> Workflow Agents (5)</h2>
|
||||
<p>Tedious work you hate doing. These agents handle the grind—reproducing bugs, resolving PR comments, running linters, analyzing specs. They're fast, they don't complain, and they free you up to solve interesting problems instead of mechanical ones.</p>
|
||||
|
||||
<div class="agent-detail" id="bug-reproduction-validator">
|
||||
<div class="agent-detail-header">
|
||||
<h3>bug-reproduction-validator</h3>
|
||||
<span class="agent-badge">Bugs</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Half of bug reports aren't bugs—they're user errors, environment issues, or misunderstood features. This agent systematically reproduces the reported behavior, classifies what it finds (Confirmed, Can't Reproduce, Not a Bug, etc.), and assesses severity. Saves you from chasing ghosts or missing real issues.
|
||||
</p>
|
||||
<h4>Classification Types</h4>
|
||||
<ul>
|
||||
<li><strong>Confirmed</strong> - Bug reproduced successfully</li>
|
||||
<li><strong>Cannot Reproduce</strong> - Unable to reproduce</li>
|
||||
<li><strong>Not a Bug</strong> - Expected behavior</li>
|
||||
<li><strong>Environmental</strong> - Environment-specific issue</li>
|
||||
<li><strong>Data</strong> - Data-related issue</li>
|
||||
<li><strong>User Error</strong> - User misunderstanding</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent bug-reproduction-validator</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="pr-comment-resolver">
|
||||
<div class="agent-detail-header">
|
||||
<h3>pr-comment-resolver</h3>
|
||||
<span class="agent-badge">PR</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Code review comments pile up. This agent reads them, plans fixes, implements changes, and reports back what it did. It doesn't argue with reviewers or skip hard feedback—it just resolves the work systematically. Great for burning through a dozen "change this variable name" comments in seconds.
|
||||
</p>
|
||||
<h4>Workflow</h4>
|
||||
<ul>
|
||||
<li>Analyze code review comments</li>
|
||||
<li>Plan the resolution before implementation</li>
|
||||
<li>Implement requested modifications</li>
|
||||
<li>Verify resolution doesn't break functionality</li>
|
||||
<li>Provide clear resolution reports</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent pr-comment-resolver</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="lint">
|
||||
<div class="agent-detail-header">
|
||||
<h3>lint</h3>
|
||||
<span class="agent-badge">Quality</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Linters are pedantic robots that enforce consistency. This agent runs StandardRB, ERBLint, and Brakeman for you—checking Ruby style, ERB templates, and security issues. It's fast (uses the Haiku model) and catches the formatting noise before CI does.
|
||||
</p>
|
||||
<h4>Tools Run</h4>
|
||||
<ul>
|
||||
<li><code>bundle exec standardrb</code> - Ruby file checking/fixing</li>
|
||||
<li><code>bundle exec erblint --lint-all</code> - ERB templates</li>
|
||||
<li><code>bin/brakeman</code> - Security scanning</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent lint</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="spec-flow-analyzer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>spec-flow-analyzer</h3>
|
||||
<span class="agent-badge">Testing</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Specs always have gaps—edge cases nobody thought about, ambiguous requirements, missing error states. This agent maps all possible user flows, identifies what's unclear or missing, and generates the questions you need to ask stakeholders. Runs before you code to avoid building the wrong thing.
|
||||
</p>
|
||||
<h4>Analysis Areas</h4>
|
||||
<ul>
|
||||
<li>Map all possible user flows and permutations</li>
|
||||
<li>Identify gaps, ambiguities, and missing specifications</li>
|
||||
<li>Consider different user types, roles, permissions</li>
|
||||
<li>Analyze error states and edge cases</li>
|
||||
<li>Generate critical questions requiring clarification</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent spec-flow-analyzer</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="every-style-editor">
|
||||
<div class="agent-detail-header">
|
||||
<h3>every-style-editor</h3>
|
||||
<span class="agent-badge">Content</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Style guides are arbitrary rules that make writing consistent. This agent enforces Every's particular quirks—title case in headlines, no overused filler words ("actually," "very"), active voice, Oxford commas. It's a line-by-line grammar cop for content that needs to match the brand.
|
||||
</p>
|
||||
<h4>Style Checks</h4>
|
||||
<ul>
|
||||
<li>Title case in headlines, sentence case elsewhere</li>
|
||||
<li>Company singular/plural usage</li>
|
||||
<li>Remove overused words (actually, very, just)</li>
|
||||
<li>Enforce active voice</li>
|
||||
<li>Apply formatting rules (Oxford commas, em dashes)</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent every-style-editor</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Design Agents -->
|
||||
<section id="design-agents">
|
||||
<h2><i class="fa-solid fa-palette"></i> Design Agents (3)</h2>
|
||||
<p>Design is iteration. These agents take screenshots, compare them to Figma, make targeted improvements, and repeat. They fix spacing, alignment, colors, typography—the visual details that compound into polish. Perfect for closing the gap between "it works" and "it looks right."</p>
|
||||
|
||||
<div class="agent-detail" id="design-iterator">
|
||||
<div class="agent-detail-header">
|
||||
<h3>design-iterator</h3>
|
||||
<span class="agent-badge">Design</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Design doesn't happen in one pass. This agent runs a loop: screenshot the UI, analyze what's off (spacing, colors, alignment), implement 3-5 targeted fixes, repeat. Run it for 10 iterations and watch rough interfaces transform into polished designs through systematic refinement.
|
||||
</p>
|
||||
<h4>Process</h4>
|
||||
<ul>
|
||||
<li>Take focused screenshots of target elements</li>
|
||||
<li>Analyze current state and identify 3-5 improvements</li>
|
||||
<li>Implement targeted CSS/design changes</li>
|
||||
<li>Document changes made</li>
|
||||
<li>Repeat for specified iterations (default 10)</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent design-iterator</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="figma-design-sync">
|
||||
<div class="agent-detail-header">
|
||||
<h3>figma-design-sync</h3>
|
||||
<span class="agent-badge">Figma</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Designers hand you a Figma file. You build it. Then: "the spacing is wrong, the font is off, the colors don't match." This agent compares your implementation to the Figma spec, identifies every visual discrepancy, and fixes them automatically. Designers stay happy. You stay sane.
|
||||
</p>
|
||||
<h4>Workflow</h4>
|
||||
<ul>
|
||||
<li>Extract design specifications from Figma</li>
|
||||
<li>Capture implementation screenshots</li>
|
||||
<li>Conduct systematic visual comparison</li>
|
||||
<li>Make precise code changes to fix discrepancies</li>
|
||||
<li>Verify implementation matches design</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent figma-design-sync</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="agent-detail" id="design-implementation-reviewer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>design-implementation-reviewer</h3>
|
||||
<span class="agent-badge">Review</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Before you ship UI changes, run this agent. It compares your implementation against Figma at a pixel level—layouts, typography, colors, spacing, responsive behavior. Uses the Opus model for detailed visual analysis. Catches the "close enough" mistakes that users notice but you don't.
|
||||
</p>
|
||||
<h4>Comparison Areas</h4>
|
||||
<ul>
|
||||
<li>Layouts and structure</li>
|
||||
<li>Typography (fonts, sizes, weights)</li>
|
||||
<li>Colors and themes</li>
|
||||
<li>Spacing and alignment</li>
|
||||
<li>Different viewport sizes</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent design-implementation-reviewer</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Docs Agents -->
|
||||
<section id="docs-agents">
|
||||
<h2><i class="fa-solid fa-file-lines"></i> Documentation Agent (1)</h2>
|
||||
|
||||
<div class="agent-detail" id="ankane-readme-writer">
|
||||
<div class="agent-detail-header">
|
||||
<h3>ankane-readme-writer</h3>
|
||||
<span class="agent-badge">Docs</span>
|
||||
</div>
|
||||
<p class="agent-detail-description">
|
||||
Andrew Kane writes READMEs that are models of clarity—concise, scannable, zero fluff. This agent generates gem documentation in that style: 15 words max per sentence, imperative voice, single-purpose code examples. If your README rambles, this agent will fix it.
|
||||
</p>
|
||||
<h4>Section Order</h4>
|
||||
<ol>
|
||||
<li>Header (title + description)</li>
|
||||
<li>Installation</li>
|
||||
<li>Quick Start</li>
|
||||
<li>Usage</li>
|
||||
<li>Options</li>
|
||||
<li>Upgrading</li>
|
||||
<li>Contributing</li>
|
||||
<li>License</li>
|
||||
</ol>
|
||||
<h4>Style Guidelines</h4>
|
||||
<ul>
|
||||
<li>Imperative voice throughout</li>
|
||||
<li>15 words max per sentence</li>
|
||||
<li>Single-purpose code fences</li>
|
||||
<li>Up to 4 badges maximum</li>
|
||||
<li>No HTML comments</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude agent ankane-readme-writer</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Navigation -->
|
||||
<nav class="docs-nav-footer">
|
||||
<a href="getting-started.html" class="nav-prev">
|
||||
<span class="nav-label">Previous</span>
|
||||
<span class="nav-title"><i class="fa-solid fa-arrow-left"></i> Getting Started</span>
|
||||
</a>
|
||||
<a href="commands.html" class="nav-next">
|
||||
<span class="nav-label">Next</span>
|
||||
<span class="nav-title">Commands <i class="fa-solid fa-arrow-right"></i></span>
|
||||
</a>
|
||||
</nav>
|
||||
</article>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
document.querySelector('[data-sidebar-toggle]')?.addEventListener('click', () => {
|
||||
document.querySelector('.docs-sidebar').classList.toggle('open');
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -1,534 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en" class="theme-dark">
|
||||
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Changelog - Compounding Engineering</title>
|
||||
<meta content="Version history and release notes for the Compounding Engineering plugin." name="description" />
|
||||
<meta content="width=device-width, initial-scale=1" name="viewport" />
|
||||
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" />
|
||||
<link href="../css/style.css" rel="stylesheet" type="text/css" />
|
||||
<link href="../css/docs.css" rel="stylesheet" type="text/css" />
|
||||
<script src="../js/main.js" type="text/javascript" defer></script>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div class="background-gradient"></div>
|
||||
<div class="docs-layout">
|
||||
<aside class="docs-sidebar">
|
||||
<div class="sidebar-header">
|
||||
<a href="../index.html" class="nav-brand">
|
||||
<span class="logo-icon"><i class="fa-solid fa-layer-group"></i></span>
|
||||
<span class="logo-text">CE Docs</span>
|
||||
</a>
|
||||
</div>
|
||||
<nav class="sidebar-nav">
|
||||
<div class="nav-section">
|
||||
<h3>Getting Started</h3>
|
||||
<ul>
|
||||
<li><a href="getting-started.html">Installation</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Reference</h3>
|
||||
<ul>
|
||||
<li><a href="agents.html">Agents (23)</a></li>
|
||||
<li><a href="commands.html">Commands (13)</a></li>
|
||||
<li><a href="skills.html">Skills (11)</a></li>
|
||||
<li><a href="mcp-servers.html">MCP Servers (two)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Resources</h3>
|
||||
<ul>
|
||||
<li><a href="changelog.html" class="active">Changelog</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>On This Page</h3>
|
||||
<ul>
|
||||
<li><a href="#v2.32.2">v2.32.2</a></li>
|
||||
<li><a href="#v2.32.1">v2.32.1</a></li>
|
||||
<li><a href="#v2.6.0">v2.6.0</a></li>
|
||||
<li><a href="#v2.5.0">v2.5.0</a></li>
|
||||
<li><a href="#v2.4.1">v2.4.1</a></li>
|
||||
<li><a href="#v2.4.0">v2.4.0</a></li>
|
||||
<li><a href="#v2.3.0">v2.3.0</a></li>
|
||||
<li><a href="#v2.2.1">v2.2.1</a></li>
|
||||
<li><a href="#v2.2.0">v2.2.0</a></li>
|
||||
<li><a href="#v2.1.0">v2.1.0</a></li>
|
||||
<li><a href="#v2.0.0">v2.0.0</a></li>
|
||||
<li><a href="#v1.1.0">v1.1.0</a></li>
|
||||
<li><a href="#v1.0.0">v1.0.0</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</nav>
|
||||
</aside>
|
||||
|
||||
<main class="docs-content">
|
||||
<div class="docs-header">
|
||||
<nav class="breadcrumb">
|
||||
<a href="../index.html">Home</a>
|
||||
<span>/</span>
|
||||
<a href="getting-started.html">Docs</a>
|
||||
<span>/</span>
|
||||
<span>Changelog</span>
|
||||
</nav>
|
||||
<button class="mobile-menu-toggle" data-sidebar-toggle>
|
||||
<i class="fa-solid fa-bars"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<article class="docs-article">
|
||||
<h1><i class="fa-solid fa-clock-rotate-left color-accent"></i> Changelog</h1>
|
||||
<p class="lead">
|
||||
All notable changes to the compound-engineering plugin. This project follows
|
||||
<a href="https://semver.org/">Semantic Versioning</a> and
|
||||
<a href="https://keepachangelog.com/">Keep a Changelog</a> conventions.
|
||||
</p>
|
||||
|
||||
<!-- Version 2.32.2 -->
|
||||
<section id="v2.32.2" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.32.2</h2>
|
||||
<span class="version-date">2026-02-12</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category changed">
|
||||
<h3><i class="fa-solid fa-arrows-rotate"></i> Changed</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong><code>/release-docs</code> command moved from plugin to local <code>.claude/commands/</code></strong> -
|
||||
This is a repository maintenance command and should not be distributed to users. Command count reduced from 24 to 23.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.32.1 -->
|
||||
<section id="v2.32.1" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.32.1</h2>
|
||||
<span class="version-date">2026-02-12</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category changed">
|
||||
<h3><i class="fa-solid fa-arrows-rotate"></i> Changed</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong><code>/workflows:review</code> command</strong> - Added <code>learnings-researcher</code>
|
||||
agent to the parallel review phase. The review now searches <code>docs/solutions/</code> for past
|
||||
issues related to the PR's modules and patterns, surfacing "Known Pattern" findings during synthesis.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.6.0 -->
|
||||
<section id="v2.6.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.6.0</h2>
|
||||
<span class="version-date">2024-11-26</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category removed">
|
||||
<h3><i class="fa-solid fa-minus"></i> Removed</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong><code>feedback-codifier</code> agent</strong> - Removed from workflow agents.
|
||||
Agent count reduced from 24 to 23.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.5.0 -->
|
||||
<section id="v2.5.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.5.0</h2>
|
||||
<span class="version-date">2024-11-25</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category added">
|
||||
<h3><i class="fa-solid fa-plus"></i> Added</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong><code>/report-bug</code> command</strong> - New slash command for reporting bugs in the
|
||||
compound-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/compound-engineering-plugin repository.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.4.1 -->
|
||||
<section id="v2.4.1" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.4.1</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category improved">
|
||||
<h3><i class="fa-solid fa-arrow-up"></i> Improved</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>design-iterator agent</strong> - 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.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.4.0 -->
|
||||
<section id="v2.4.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.4.0</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category fixed">
|
||||
<h3><i class="fa-solid fa-bug"></i> Fixed</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>MCP Configuration</strong> - Moved MCP servers back to <code>plugin.json</code>
|
||||
following working examples from anthropics/life-sciences plugins.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Context7 URL</strong> - Updated to use HTTP type with correct endpoint URL.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.3.0 -->
|
||||
<section id="v2.3.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.3.0</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category changed">
|
||||
<h3><i class="fa-solid fa-arrows-rotate"></i> Changed</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>MCP Configuration</strong> - Moved MCP servers from inline <code>plugin.json</code>
|
||||
to separate <code>.mcp.json</code> file per Claude Code best practices.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.2.1 -->
|
||||
<section id="v2.2.1" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.2.1</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category fixed">
|
||||
<h3><i class="fa-solid fa-bug"></i> Fixed</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>Playwright MCP Server</strong> - Added missing <code>"type": "stdio"</code> field
|
||||
required for MCP server configuration to load properly.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.2.0 -->
|
||||
<section id="v2.2.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.2.0</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category added">
|
||||
<h3><i class="fa-solid fa-plus"></i> Added</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>Context7 MCP Server</strong> - Bundled Context7 for instant framework documentation
|
||||
lookup. Provides up-to-date docs for Rails, React, Next.js, and more than 100 other frameworks.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.1.0 -->
|
||||
<section id="v2.1.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.1.0</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category added">
|
||||
<h3><i class="fa-solid fa-plus"></i> Added</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>Playwright MCP Server</strong> - Bundled <code>@playwright/mcp</code> for browser
|
||||
automation across all projects. Provides screenshot, navigation, click, fill, and evaluate tools.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category changed">
|
||||
<h3><i class="fa-solid fa-arrows-rotate"></i> Changed</h3>
|
||||
<ul>
|
||||
<li>Replaced all Puppeteer references with Playwright across agents and commands:
|
||||
<ul>
|
||||
<li><code>bug-reproduction-validator</code> agent</li>
|
||||
<li><code>design-iterator</code> agent</li>
|
||||
<li><code>design-implementation-reviewer</code> agent</li>
|
||||
<li><code>figma-design-sync</code> agent</li>
|
||||
<li><code>generate_command</code> command</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.0.2 -->
|
||||
<section id="v2.0.2" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.0.2</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category changed">
|
||||
<h3><i class="fa-solid fa-arrows-rotate"></i> Changed</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>design-iterator agent</strong> - Updated description to emphasize proactive usage
|
||||
when design work isn't coming together on first attempt.
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.0.1 -->
|
||||
<section id="v2.0.1" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.0.1</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category added">
|
||||
<h3><i class="fa-solid fa-plus"></i> Added</h3>
|
||||
<ul>
|
||||
<li><strong>CLAUDE.md</strong> - Project instructions with versioning requirements</li>
|
||||
<li><strong>docs/solutions/plugin-versioning-requirements.md</strong> - Workflow documentation</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 2.0.0 -->
|
||||
<section id="v2.0.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v2.0.0</h2>
|
||||
<span class="version-date">2024-11-24</span>
|
||||
<span class="version-badge major">Major Release</span>
|
||||
</div>
|
||||
|
||||
<p class="version-description">
|
||||
Major reorganization consolidating agents, commands, and skills from multiple sources into
|
||||
a single, well-organized plugin.
|
||||
</p>
|
||||
|
||||
<div class="changelog-category added">
|
||||
<h3><i class="fa-solid fa-plus"></i> Added</h3>
|
||||
|
||||
<h4>New Agents (seven)</h4>
|
||||
<ul>
|
||||
<li><code>design-iterator</code> - Iteratively refine UI components through systematic design iterations</li>
|
||||
<li><code>design-implementation-reviewer</code> - Verify UI implementations match Figma design specifications</li>
|
||||
<li><code>figma-design-sync</code> - Synchronize web implementations with Figma designs</li>
|
||||
<li><code>bug-reproduction-validator</code> - Systematically reproduce and validate bug reports</li>
|
||||
<li><code>spec-flow-analyzer</code> - Analyze user flows and identify gaps in specifications</li>
|
||||
<li><code>lint</code> - Run linting and code quality checks on Ruby and ERB files</li>
|
||||
<li><code>ankane-readme-writer</code> - Create READMEs following Ankane-style template for Ruby gems</li>
|
||||
</ul>
|
||||
|
||||
<h4>New Commands (nine)</h4>
|
||||
<ul>
|
||||
<li><code>/changelog</code> - Create engaging changelogs for recent merges</li>
|
||||
<li><code>/plan_review</code> - Multi-agent plan review in parallel</li>
|
||||
<li><code>/resolve_parallel</code> - Resolve TODO comments in parallel</li>
|
||||
<li><code>/resolve_pr_parallel</code> - Resolve PR comments in parallel</li>
|
||||
<li><code>/reproduce-bug</code> - Reproduce bugs using logs and console</li>
|
||||
<li><code>/prime</code> - Prime/setup command</li>
|
||||
<li><code>/create-agent-skill</code> - Create or edit Claude Code skills</li>
|
||||
<li><code>/heal-skill</code> - Fix skill documentation issues</li>
|
||||
<li><code>/codify</code> - Document solved problems for knowledge base</li>
|
||||
</ul>
|
||||
|
||||
<h4>New Skills (10)</h4>
|
||||
<ul>
|
||||
<li><code>andrew-kane-gem-writer</code> - Write Ruby gems following Andrew Kane's patterns</li>
|
||||
<li><code>codify-docs</code> - Capture solved problems as categorized documentation</li>
|
||||
<li><code>create-agent-skills</code> - Expert guidance for creating Claude Code skills</li>
|
||||
<li><code>dhh-ruby-style</code> - Write Ruby/Rails code in DHH's 37signals style</li>
|
||||
<li><code>dspy-ruby</code> - Build type-safe LLM applications with DSPy.rb</li>
|
||||
<li><code>every-style-editor</code> - Review copy for Every's style guide compliance</li>
|
||||
<li><code>file-todos</code> - File-based todo tracking system</li>
|
||||
<li><code>frontend-design</code> - Create production-grade frontend interfaces</li>
|
||||
<li><code>git-worktree</code> - Manage Git worktrees for parallel development</li>
|
||||
<li><code>skill-creator</code> - Guide for creating effective Claude Code skills</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category changed">
|
||||
<h3><i class="fa-solid fa-arrows-rotate"></i> Changed</h3>
|
||||
<h4>Agents Reorganized by Category</h4>
|
||||
<ul>
|
||||
<li><code>review/</code> (10 agents) - Code quality, security, performance reviewers</li>
|
||||
<li><code>research/</code> (four agents) - Documentation, patterns, history analysis</li>
|
||||
<li><code>design/</code> (three agents) - UI/design review and iteration</li>
|
||||
<li><code>workflow/</code> (six agents) - PR resolution, bug validation, linting</li>
|
||||
<li><code>docs/</code> (one agent) - README generation</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="version-summary">
|
||||
<h4>Summary</h4>
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Component</th>
|
||||
<th>v1.1.0</th>
|
||||
<th>v2.0.0</th>
|
||||
<th>Change</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Agents</td>
|
||||
<td>17</td>
|
||||
<td>24</td>
|
||||
<td class="positive">+7</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Commands</td>
|
||||
<td>6</td>
|
||||
<td>15</td>
|
||||
<td class="positive">+9</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Skills</td>
|
||||
<td>1</td>
|
||||
<td>11</td>
|
||||
<td class="positive">+10</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 1.1.0 -->
|
||||
<section id="v1.1.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v1.1.0</h2>
|
||||
<span class="version-date">2024-11-22</span>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category added">
|
||||
<h3><i class="fa-solid fa-plus"></i> Added</h3>
|
||||
<ul>
|
||||
<li>
|
||||
<strong>gemini-imagegen Skill</strong>
|
||||
<ul>
|
||||
<li>Text-to-image generation with Google's Gemini API</li>
|
||||
<li>Image editing and manipulation</li>
|
||||
<li>Multi-turn refinement via chat interface</li>
|
||||
<li>Multiple reference image composition (up to 14 images)</li>
|
||||
<li>Model support: <code>gemini-2.5-flash-image</code> and <code>gemini-3-pro-image-preview</code></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<div class="changelog-category fixed">
|
||||
<h3><i class="fa-solid fa-bug"></i> Fixed</h3>
|
||||
<ul>
|
||||
<li>Corrected component counts in documentation (17 agents, not 15)</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Version 1.0.0 -->
|
||||
<section id="v1.0.0" class="version-section">
|
||||
<div class="version-header">
|
||||
<h2>v1.0.0</h2>
|
||||
<span class="version-date">2024-10-09</span>
|
||||
<span class="version-badge">Initial Release</span>
|
||||
</div>
|
||||
|
||||
<p class="version-description">
|
||||
Initial release of the compound-engineering plugin.
|
||||
</p>
|
||||
|
||||
<div class="changelog-category added">
|
||||
<h3><i class="fa-solid fa-plus"></i> Added</h3>
|
||||
|
||||
<h4>17 Specialized Agents</h4>
|
||||
|
||||
<p><strong>Code Review (five)</strong></p>
|
||||
<ul>
|
||||
<li><code>kieran-rails-reviewer</code> - Rails code review with strict conventions</li>
|
||||
<li><code>kieran-python-reviewer</code> - Python code review with quality standards</li>
|
||||
<li><code>kieran-typescript-reviewer</code> - TypeScript code review</li>
|
||||
<li><code>dhh-rails-reviewer</code> - Rails review from DHH's perspective</li>
|
||||
<li><code>code-simplicity-reviewer</code> - Final pass for simplicity and minimalism</li>
|
||||
</ul>
|
||||
|
||||
<p><strong>Analysis & Architecture (four)</strong></p>
|
||||
<ul>
|
||||
<li><code>architecture-strategist</code> - Architectural decisions and compliance</li>
|
||||
<li><code>pattern-recognition-specialist</code> - Design pattern analysis</li>
|
||||
<li><code>security-sentinel</code> - Security audits and vulnerability assessments</li>
|
||||
<li><code>performance-oracle</code> - Performance analysis and optimization</li>
|
||||
</ul>
|
||||
|
||||
<p><strong>Research (four)</strong></p>
|
||||
<ul>
|
||||
<li><code>framework-docs-researcher</code> - Framework documentation research</li>
|
||||
<li><code>best-practices-researcher</code> - External best practices gathering</li>
|
||||
<li><code>git-history-analyzer</code> - Git history and code evolution analysis</li>
|
||||
<li><code>repo-research-analyst</code> - Repository structure and conventions</li>
|
||||
</ul>
|
||||
|
||||
<p><strong>Workflow (three)</strong></p>
|
||||
<ul>
|
||||
<li><code>every-style-editor</code> - Every's style guide compliance</li>
|
||||
<li><code>pr-comment-resolver</code> - PR comment resolution</li>
|
||||
<li><code>feedback-codifier</code> - Feedback pattern codification</li>
|
||||
</ul>
|
||||
|
||||
<h4>Six Slash Commands</h4>
|
||||
<ul>
|
||||
<li><code>/plan</code> - Create implementation plans</li>
|
||||
<li><code>/review</code> - Comprehensive code reviews</li>
|
||||
<li><code>/work</code> - Execute work items systematically</li>
|
||||
<li><code>/triage</code> - Triage and prioritize issues</li>
|
||||
<li><code>/resolve_todo_parallel</code> - Resolve TODOs in parallel</li>
|
||||
<li><code>/generate_command</code> - Generate new slash commands</li>
|
||||
</ul>
|
||||
|
||||
<h4>Infrastructure</h4>
|
||||
<ul>
|
||||
<li>MIT license</li>
|
||||
<li>Plugin manifest (<code>plugin.json</code>)</li>
|
||||
<li>Pre-configured permissions for Rails development</li>
|
||||
</ul>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
</article>
|
||||
</main>
|
||||
</div>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -1,523 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en" class="theme-dark">
|
||||
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Command Reference - Compounding Engineering</title>
|
||||
<meta content="Complete reference for all 16 slash commands in the Compounding Engineering plugin." name="description" />
|
||||
<meta content="width=device-width, initial-scale=1" name="viewport" />
|
||||
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" />
|
||||
<link href="../css/style.css" rel="stylesheet" type="text/css" />
|
||||
<link href="../css/docs.css" rel="stylesheet" type="text/css" />
|
||||
<script src="../js/main.js" type="text/javascript" defer></script>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div class="background-gradient"></div>
|
||||
<div class="docs-layout">
|
||||
<aside class="docs-sidebar">
|
||||
<div class="sidebar-header">
|
||||
<a href="../index.html" class="nav-brand">
|
||||
<span class="logo-icon"><i class="fa-solid fa-layer-group"></i></span>
|
||||
<span class="logo-text">CE Docs</span>
|
||||
</a>
|
||||
</div>
|
||||
<nav class="sidebar-nav">
|
||||
<div class="nav-section">
|
||||
<h3>Getting Started</h3>
|
||||
<ul>
|
||||
<li><a href="getting-started.html">Installation</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Reference</h3>
|
||||
<ul>
|
||||
<li><a href="agents.html">Agents (23)</a></li>
|
||||
<li><a href="commands.html" class="active">Commands (13)</a></li>
|
||||
<li><a href="skills.html">Skills (11)</a></li>
|
||||
<li><a href="mcp-servers.html">MCP Servers (two)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Resources</h3>
|
||||
<ul>
|
||||
<li><a href="changelog.html">Changelog</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>On This Page</h3>
|
||||
<ul>
|
||||
<li><a href="#workflow-commands">Workflow (four)</a></li>
|
||||
<li><a href="#utility-commands">Utility (12)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</nav>
|
||||
</aside>
|
||||
|
||||
<main class="docs-content">
|
||||
<div class="docs-header">
|
||||
<nav class="breadcrumb">
|
||||
<a href="../index.html">Home</a>
|
||||
<span>/</span>
|
||||
<a href="getting-started.html">Docs</a>
|
||||
<span>/</span>
|
||||
<span>Commands</span>
|
||||
</nav>
|
||||
<button class="mobile-menu-toggle" data-sidebar-toggle>
|
||||
<i class="fa-solid fa-bars"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<article class="docs-article">
|
||||
<h1><i class="fa-solid fa-terminal color-accent"></i> Command Reference</h1>
|
||||
<p class="lead">
|
||||
Here's the thing about slash commands: they're workflows you'd spend 20 minutes doing manually, compressed into one line. Type <code>/plan</code> 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.
|
||||
</p>
|
||||
|
||||
<!-- Workflow Commands -->
|
||||
<section id="workflow-commands">
|
||||
<h2><i class="fa-solid fa-arrows-spin"></i> Workflow Commands (four)</h2>
|
||||
<p>These are the big four: Plan your feature, Review your code, Work through the implementation, and Codify what you learned. Every professional developer does this cycle—these commands just make you faster at it.</p>
|
||||
|
||||
<div class="command-detail" id="workflows-plan">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/plan</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[feature description, bug report, or improvement idea]</code></p>
|
||||
<h4>Workflow</h4>
|
||||
<ol>
|
||||
<li><strong>Repository Research (Parallel)</strong> - Launch three agents simultaneously:
|
||||
<ul>
|
||||
<li><code>repo-research-analyst</code> - Project patterns</li>
|
||||
<li><code>best-practices-researcher</code> - Industry standards</li>
|
||||
<li><code>framework-docs-researcher</code> - Framework documentation</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>SpecFlow Analysis</strong> - Run <code>spec-flow-analyzer</code> for user flows</li>
|
||||
<li><strong>Choose Detail Level</strong>:
|
||||
<ul>
|
||||
<li><strong>MINIMAL</strong> - Simple bugs/small improvements</li>
|
||||
<li><strong>MORE</strong> - Standard features</li>
|
||||
<li><strong>A LOT</strong> - Major features with phases</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Write Plan</strong> - Save as <code>plans/<issue_title>.md</code></li>
|
||||
<li><strong>Review</strong> - Call <code>/plan_review</code> for multi-agent feedback</li>
|
||||
</ol>
|
||||
<div class="callout callout-info">
|
||||
<div class="callout-icon"><i class="fa-solid fa-circle-info"></i></div>
|
||||
<div class="callout-content">
|
||||
<p>This command does NOT write code. It only researches and creates the plan.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/plan Add OAuth integration for third-party auth
|
||||
/plan Fix N+1 query in user dashboard</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="workflows-review">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/review</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[PR number, GitHub URL, branch name, or "latest"]</code></p>
|
||||
<h4>Workflow</h4>
|
||||
<ol>
|
||||
<li><strong>Setup</strong> - Detect review target, optionally use git-worktree for isolation</li>
|
||||
<li><strong>Launch 12 Parallel Review Agents</strong>:
|
||||
<ul>
|
||||
<li><code>kieran-rails-reviewer</code>, <code>dhh-rails-reviewer</code></li>
|
||||
<li><code>security-sentinel</code>, <code>performance-oracle</code></li>
|
||||
<li><code>architecture-strategist</code>, <code>data-integrity-guardian</code></li>
|
||||
<li><code>pattern-recognition-specialist</code>, <code>git-history-analyzer</code></li>
|
||||
<li>And more...</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Ultra-Thinking Analysis</strong> - Stakeholder perspectives, scenario exploration</li>
|
||||
<li><strong>Simplification Review</strong> - Run <code>code-simplicity-reviewer</code></li>
|
||||
<li><strong>Synthesize Findings</strong> - Categorize by severity (P1/P2/P3)</li>
|
||||
<li><strong>Create Todo Files</strong> - Using file-todos skill for all findings</li>
|
||||
</ol>
|
||||
<div class="callout callout-warning">
|
||||
<div class="callout-icon"><i class="fa-solid fa-triangle-exclamation"></i></div>
|
||||
<div class="callout-content">
|
||||
<p><strong>P1 (Critical) findings BLOCK MERGE.</strong> Address these before merging.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/review 42
|
||||
/review https://github.com/owner/repo/pull/42
|
||||
/review feature-branch-name
|
||||
/review latest</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="workflows-work">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/work</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[plan file, specification, or todo file path]</code></p>
|
||||
<h4>Phases</h4>
|
||||
<ol>
|
||||
<li><strong>Quick Start</strong>
|
||||
<ul>
|
||||
<li>Read plan & clarify requirements</li>
|
||||
<li>Setup environment (live or worktree)</li>
|
||||
<li>Create TodoWrite task list</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Execute</strong>
|
||||
<ul>
|
||||
<li>Task execution loop with progress tracking</li>
|
||||
<li>Follow existing patterns</li>
|
||||
<li>Test continuously</li>
|
||||
<li>Figma sync if applicable</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Quality Check</strong>
|
||||
<ul>
|
||||
<li>Run test suite</li>
|
||||
<li>Run linting</li>
|
||||
<li>Optional reviewer agents for complex changes</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Ship It</strong>
|
||||
<ul>
|
||||
<li>Create commit with conventional format</li>
|
||||
<li>Create pull request</li>
|
||||
<li>Notify with summary</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/work plans/user-authentication.md
|
||||
/work todos/042-ready-p1-performance-issue.md</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="workflows-compound">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/compound</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[optional: brief context about the fix]</code></p>
|
||||
<h4>Workflow</h4>
|
||||
<ol>
|
||||
<li><strong>Preconditions</strong> - Verify problem is solved and verified working</li>
|
||||
<li><strong>Launch seven parallel subagents</strong>:
|
||||
<ul>
|
||||
<li>Context Analyzer - Extract YAML frontmatter skeleton</li>
|
||||
<li>Solution Extractor - Identify root cause and solution</li>
|
||||
<li>Related Docs Finder - Find cross-references</li>
|
||||
<li>Prevention Strategist - Develop prevention strategies</li>
|
||||
<li>Category Classifier - Determine docs category</li>
|
||||
<li>Documentation Writer - Create the file</li>
|
||||
<li>Optional Specialized Agent - Based on problem type</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><strong>Create Documentation</strong> - File in <code>docs/solutions/[category]/</code></li>
|
||||
</ol>
|
||||
<h4>Auto-Triggers</h4>
|
||||
<p>Phrases: "that worked", "it's fixed", "working now", "problem solved"</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/compound
|
||||
/compound N+1 query optimization</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Utility Commands -->
|
||||
<section id="utility-commands">
|
||||
<h2><i class="fa-solid fa-wrench"></i> Utility Commands (12)</h2>
|
||||
<p>The supporting cast—commands that do one specific thing really well. Generate changelogs, resolve todos in parallel, triage findings, create new commands. The utilities you reach for daily.</p>
|
||||
|
||||
<div class="command-detail" id="changelog">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/changelog</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Turn your git history into a changelog people actually want to read. Breaking changes at the top, fun facts at the bottom, everything organized by what matters to your users.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[optional: daily|weekly, or time period in days]</code></p>
|
||||
<h4>Output Sections</h4>
|
||||
<ul>
|
||||
<li>Breaking Changes (top priority)</li>
|
||||
<li>New Features</li>
|
||||
<li>Bug Fixes</li>
|
||||
<li>Other Improvements</li>
|
||||
<li>Shoutouts</li>
|
||||
<li>Fun Fact</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/changelog daily
|
||||
/changelog weekly
|
||||
/changelog 7</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="create-agent-skill">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/create-agent-skill</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Need a new skill? This walks you through creating one that actually works—proper frontmatter, clear documentation, all the conventions baked in. Think of it as scaffolding for skills.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[skill description or requirements]</code></p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/create-agent-skill PDF processing for document analysis
|
||||
/create-agent-skill Web scraping with error handling</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="generate-command">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/generate_command</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Same idea, but for commands instead of skills. Tell it what workflow you're tired of doing manually, and it generates a proper slash command with all the right patterns.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[command purpose and requirements]</code></p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/generate_command Security audit for codebase
|
||||
/generate_command Automated performance testing</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="heal-skill">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/heal-skill</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Skills drift—APIs change, URLs break, parameters get renamed. When a skill stops working, this figures out what's wrong and fixes the documentation. You approve the changes before anything commits.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[optional: specific issue to fix]</code></p>
|
||||
<h4>Approval Options</h4>
|
||||
<ol>
|
||||
<li>Apply and commit</li>
|
||||
<li>Apply without commit</li>
|
||||
<li>Revise changes</li>
|
||||
<li>Cancel</li>
|
||||
</ol>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/heal-skill API endpoint URL changed
|
||||
/heal-skill parameter validation error</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="plan-review">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/plan_review</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Before you execute a plan, have three reviewers tear it apart—Rails conventions, best practices, simplicity. Better to find the problems in the plan than in production.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[plan file path or plan content]</code></p>
|
||||
<h4>Review Agents</h4>
|
||||
<ul>
|
||||
<li><code>dhh-rails-reviewer</code> - Rails conventions</li>
|
||||
<li><code>kieran-rails-reviewer</code> - Rails best practices</li>
|
||||
<li><code>code-simplicity-reviewer</code> - Simplicity and clarity</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/plan_review plans/user-authentication.md</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="report-bug">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/report-bug</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Something broken? This collects all the context—what broke, what you expected, error messages, environment—and files a proper bug report. No more "it doesn't work" issues.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[optional: brief description of the bug]</code></p>
|
||||
<h4>Information Collected</h4>
|
||||
<ul>
|
||||
<li>Bug category (Agent/Command/Skill/MCP/Installation)</li>
|
||||
<li>Specific component name</li>
|
||||
<li>Actual vs expected behavior</li>
|
||||
<li>Steps to reproduce</li>
|
||||
<li>Error messages</li>
|
||||
<li>Environment info (auto-gathered)</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/report-bug Agent not working
|
||||
/report-bug Command failing with timeout</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="reproduce-bug">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/reproduce-bug</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Give it a GitHub issue number and it tries to actually reproduce the bug—reading the issue, analyzing code paths, iterating until it finds the root cause. Then it posts findings back to the issue.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[GitHub issue number]</code></p>
|
||||
<h4>Investigation Process</h4>
|
||||
<ol>
|
||||
<li>Read GitHub issue details</li>
|
||||
<li>Launch parallel investigation agents</li>
|
||||
<li>Analyze code for failure points</li>
|
||||
<li>Iterate until root cause found</li>
|
||||
<li>Post findings to GitHub issue</li>
|
||||
</ol>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/reproduce-bug 142</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="triage">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/triage</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Got a pile of code review findings or security audit results? This turns them into actionable todos—one at a time, you decide: create the todo, skip it, or modify and re-present.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[findings list or source type]</code></p>
|
||||
<h4>User Decisions</h4>
|
||||
<ul>
|
||||
<li><strong>"yes"</strong> - Create/update todo file, change status to ready</li>
|
||||
<li><strong>"next"</strong> - Skip and delete from todos</li>
|
||||
<li><strong>"custom"</strong> - Modify and re-present</li>
|
||||
</ul>
|
||||
<div class="callout callout-info">
|
||||
<div class="callout-icon"><i class="fa-solid fa-circle-info"></i></div>
|
||||
<div class="callout-content">
|
||||
<p>This command does NOT write code. It only categorizes and creates todo files.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/triage code-review-findings.txt
|
||||
/triage security-audit-results</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="resolve-parallel">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/resolve_parallel</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
All those TODO comments scattered through your codebase? This finds them, builds a dependency graph, and spawns parallel agents to resolve them all at once. Clears the backlog in minutes.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[optional: specific TODO pattern or file]</code></p>
|
||||
<h4>Process</h4>
|
||||
<ol>
|
||||
<li>Analyze TODO comments from codebase</li>
|
||||
<li>Create dependency graph (mermaid diagram)</li>
|
||||
<li>Spawn parallel <code>pr-comment-resolver</code> agents</li>
|
||||
<li>Commit and push after completion</li>
|
||||
</ol>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/resolve_parallel
|
||||
/resolve_parallel authentication
|
||||
/resolve_parallel src/auth/</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="resolve-pr-parallel">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/resolve_pr_parallel</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Same deal, but for PR review comments. Fetch unresolved threads, spawn parallel resolver agents, commit the fixes, and mark threads as resolved. Your reviewers will wonder how you're so fast.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[optional: PR number or current PR]</code></p>
|
||||
<h4>Process</h4>
|
||||
<ol>
|
||||
<li>Get all unresolved PR comments</li>
|
||||
<li>Create TodoWrite list</li>
|
||||
<li>Launch parallel <code>pr-comment-resolver</code> agents</li>
|
||||
<li>Commit, resolve threads, and push</li>
|
||||
</ol>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/resolve_pr_parallel
|
||||
/resolve_pr_parallel 123</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="resolve-todo-parallel">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/resolve_todo_parallel</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Those todo files in your <code>/todos</code> directory? Point this at them and watch parallel agents knock them out—analyzing dependencies, executing in the right order, marking resolved as they finish.
|
||||
</p>
|
||||
<h4>Arguments</h4>
|
||||
<p><code>[optional: specific todo ID or pattern]</code></p>
|
||||
<h4>Process</h4>
|
||||
<ol>
|
||||
<li>Get unresolved TODOs from <code>/todos/*.md</code></li>
|
||||
<li>Analyze dependencies</li>
|
||||
<li>Spawn parallel agents</li>
|
||||
<li>Commit, mark as resolved, push</li>
|
||||
</ol>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/resolve_todo_parallel
|
||||
/resolve_todo_parallel 042
|
||||
/resolve_todo_parallel p1</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="command-detail" id="prime">
|
||||
<div class="command-detail-header">
|
||||
<code class="command-detail-name">/prime</code>
|
||||
</div>
|
||||
<p class="command-detail-description">
|
||||
Your project initialization command. What exactly it does depends on your project setup—think of it as the "get everything ready" button before you start coding.
|
||||
</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>/prime</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Navigation -->
|
||||
<nav class="docs-nav-footer">
|
||||
<a href="agents.html" class="nav-prev">
|
||||
<span class="nav-label">Previous</span>
|
||||
<span class="nav-title"><i class="fa-solid fa-arrow-left"></i> Agents</span>
|
||||
</a>
|
||||
<a href="skills.html" class="nav-next">
|
||||
<span class="nav-label">Next</span>
|
||||
<span class="nav-title">Skills <i class="fa-solid fa-arrow-right"></i></span>
|
||||
</a>
|
||||
</nav>
|
||||
</article>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
document.querySelector('[data-sidebar-toggle]')?.addEventListener('click', () => {
|
||||
document.querySelector('.docs-sidebar').classList.toggle('open');
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -1,582 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en" class="theme-dark">
|
||||
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Getting Started - Compounding Engineering</title>
|
||||
<meta content="Complete guide to installing and using the Compounding Engineering plugin for Claude Code." name="description" />
|
||||
<meta content="width=device-width, initial-scale=1" name="viewport" />
|
||||
|
||||
<!-- Styles -->
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" />
|
||||
<link href="../css/style.css" rel="stylesheet" type="text/css" />
|
||||
<link href="../css/docs.css" rel="stylesheet" type="text/css" />
|
||||
<script src="../js/main.js" type="text/javascript" defer></script>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div class="background-gradient"></div>
|
||||
<div class="docs-layout">
|
||||
<!-- Sidebar -->
|
||||
<aside class="docs-sidebar">
|
||||
<div class="sidebar-header">
|
||||
<a href="../index.html" class="nav-brand">
|
||||
<span class="logo-icon"><i class="fa-solid fa-layer-group"></i></span>
|
||||
<span class="logo-text">CE Docs</span>
|
||||
</a>
|
||||
</div>
|
||||
<nav class="sidebar-nav">
|
||||
<div class="nav-section">
|
||||
<h3>Getting Started</h3>
|
||||
<ul>
|
||||
<li><a href="#installation" class="active">Installation</a></li>
|
||||
<li><a href="#quick-start">Quick Start</a></li>
|
||||
<li><a href="#configuration">Configuration</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Core Concepts</h3>
|
||||
<ul>
|
||||
<li><a href="#philosophy">Philosophy</a></li>
|
||||
<li><a href="#agents">Using Agents</a></li>
|
||||
<li><a href="#commands">Using Commands</a></li>
|
||||
<li><a href="#skills">Using Skills</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Guides</h3>
|
||||
<ul>
|
||||
<li><a href="#code-review">Code Review Workflow</a></li>
|
||||
<li><a href="#creating-agents">Creating Custom Agents</a></li>
|
||||
<li><a href="#creating-skills">Creating Custom Skills</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Reference</h3>
|
||||
<ul>
|
||||
<li><a href="agents.html">Agent Reference</a></li>
|
||||
<li><a href="commands.html">Command Reference</a></li>
|
||||
<li><a href="skills.html">Skill Reference</a></li>
|
||||
<li><a href="mcp-servers.html">MCP Servers</a></li>
|
||||
<li><a href="changelog.html">Changelog</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</nav>
|
||||
</aside>
|
||||
|
||||
<!-- Main Content -->
|
||||
<main class="docs-content">
|
||||
<div class="docs-header">
|
||||
<nav class="breadcrumb">
|
||||
<a href="../index.html">Home</a>
|
||||
<span>/</span>
|
||||
<span>Getting Started</span>
|
||||
</nav>
|
||||
<button class="mobile-menu-toggle" data-sidebar-toggle>
|
||||
<i class="fa-solid fa-bars"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<article class="docs-article">
|
||||
<h1>Getting Started with Compounding Engineering</h1>
|
||||
<p class="lead">
|
||||
Five minutes from now, you'll run a single command that spins up 10 AI agents—each with a different specialty—to review your pull request in parallel. Security, performance, architecture, accessibility, all happening at once. That's the plugin. Let's get you set up.
|
||||
</p>
|
||||
|
||||
<!-- Installation Section -->
|
||||
<section id="installation">
|
||||
<h2><i class="fa-solid fa-download"></i> Installation</h2>
|
||||
|
||||
<h3>Prerequisites</h3>
|
||||
<ul>
|
||||
<li><a href="https://claude.ai/claude-code" target="_blank">Claude Code</a> installed and configured</li>
|
||||
<li>A GitHub account (for marketplace access)</li>
|
||||
<li>Node.js 18+ (for MCP servers)</li>
|
||||
</ul>
|
||||
|
||||
<h3>Step 1: Add the Marketplace</h3>
|
||||
<p>Think of the marketplace as an app store. You're adding it to Claude Code's list of places to look for plugins:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude /plugin marketplace add https://github.com/EveryInc/compound-engineering-plugin</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Step 2: Install the Plugin</h3>
|
||||
<p>Now grab the plugin itself:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude /plugin install compound-engineering</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Step 3: Verify Installation</h3>
|
||||
<p>Check that it worked:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>claude /plugin list</code></pre>
|
||||
</div>
|
||||
<p>You'll see <code>compound-engineering</code> in the list. If you do, you're ready.</p>
|
||||
|
||||
<div class="callout callout-info">
|
||||
<div class="callout-icon"><i class="fa-solid fa-circle-info"></i></div>
|
||||
<div class="callout-content">
|
||||
<h4>Known Issue: MCP Servers</h4>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Quick Start Section -->
|
||||
<section id="quick-start">
|
||||
<h2><i class="fa-solid fa-rocket"></i> Quick Start</h2>
|
||||
|
||||
<p>Let's see what this thing can actually do. I'll show you three workflows you'll use constantly:</p>
|
||||
|
||||
<h3>Run a Code Review</h3>
|
||||
<p>This is the big one. Type <code>/review</code> and watch it spawn 10+ specialized reviewers:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code># Review a PR by number
|
||||
/review 123
|
||||
|
||||
# Review the current branch
|
||||
/review
|
||||
|
||||
# Review a specific branch
|
||||
/review feature/my-feature</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Use a Specialized Agent</h3>
|
||||
<p>Sometimes you just need one expert. Call them directly:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code># 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"</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Invoke a Skill</h3>
|
||||
<p>Skills are like loading a reference book into Claude's brain. When you need deep knowledge in a specific domain:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code># 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</code></pre>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Configuration Section -->
|
||||
<section id="configuration">
|
||||
<h2><i class="fa-solid fa-gear"></i> Configuration</h2>
|
||||
|
||||
<h3 id="mcp-configuration">MCP Server Configuration</h3>
|
||||
<p>
|
||||
If the MCP servers didn't load automatically, paste this into <code>.claude/settings.json</code>:
|
||||
</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>{
|
||||
"mcpServers": {
|
||||
"playwright": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@playwright/mcp@latest"],
|
||||
"env": {}
|
||||
},
|
||||
"context7": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.context7.com/mcp"
|
||||
}
|
||||
}
|
||||
}</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Environment Variables</h3>
|
||||
<p>Right now, only one skill needs an API key. If you use Gemini's image generation:</p>
|
||||
<table class="docs-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Variable</th>
|
||||
<th>Required For</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>GEMINI_API_KEY</code></td>
|
||||
<td>gemini-imagegen</td>
|
||||
<td>Google Gemini API key for image generation</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
|
||||
<!-- Philosophy Section -->
|
||||
<section id="philosophy">
|
||||
<h2><i class="fa-solid fa-lightbulb"></i> The Compounding Engineering Philosophy</h2>
|
||||
|
||||
<blockquote class="highlight-quote">
|
||||
Every unit of engineering work should make subsequent units of work easier—not harder.
|
||||
</blockquote>
|
||||
|
||||
<p>Here's how it works in practice—the four-step loop you'll run over and over:</p>
|
||||
|
||||
<div class="philosophy-grid">
|
||||
<div class="philosophy-card">
|
||||
<div class="philosophy-icon"><i class="fa-solid fa-brain"></i></div>
|
||||
<h4>1. Plan</h4>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
<div class="philosophy-card">
|
||||
<div class="philosophy-icon"><i class="fa-solid fa-robot"></i></div>
|
||||
<h4>2. Delegate</h4>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
<div class="philosophy-card">
|
||||
<div class="philosophy-icon"><i class="fa-solid fa-magnifying-glass"></i></div>
|
||||
<h4>3. Assess</h4>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
<div class="philosophy-card">
|
||||
<div class="philosophy-icon"><i class="fa-solid fa-book"></i></div>
|
||||
<h4>4. Codify</h4>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Using Agents Section -->
|
||||
<section id="agents">
|
||||
<h2><i class="fa-solid fa-users-gear"></i> Using Agents</h2>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Invoking Agents</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code># 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"</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Agent Categories</h3>
|
||||
<table class="docs-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Category</th>
|
||||
<th>Count</th>
|
||||
<th>Purpose</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Review</td>
|
||||
<td>10</td>
|
||||
<td>Code review, security audits, performance analysis</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Research</td>
|
||||
<td>four</td>
|
||||
<td>Best practices, documentation, git history</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Design</td>
|
||||
<td>three</td>
|
||||
<td>UI iteration, Figma sync, design review</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Workflow</td>
|
||||
<td>five</td>
|
||||
<td>Bug reproduction, PR resolution, linting</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Docs</td>
|
||||
<td>one</td>
|
||||
<td>README generation</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<p>
|
||||
<a href="agents.html" class="button secondary">
|
||||
<i class="fa-solid fa-arrow-right"></i> View All Agents
|
||||
</a>
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Using Commands Section -->
|
||||
<section id="commands">
|
||||
<h2><i class="fa-solid fa-terminal"></i> Using Commands</h2>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Running Commands</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code># Workflow commands
|
||||
/plan
|
||||
/review 123
|
||||
/work
|
||||
/compound
|
||||
|
||||
# Utility commands
|
||||
/changelog
|
||||
/triage
|
||||
/reproduce-bug</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>The Review Workflow</h3>
|
||||
<p>Let me show you what happens when you run <code>/review</code>. Here's the sequence:</p>
|
||||
<ol>
|
||||
<li><strong>Detection</strong> - Figures out what you want reviewed (PR number, branch name, or current changes)</li>
|
||||
<li><strong>Isolation</strong> - Spins up a git worktree so the review doesn't mess with your working directory</li>
|
||||
<li><strong>Parallel execution</strong> - Launches 10+ agents simultaneously (security, performance, architecture, accessibility...)</li>
|
||||
<li><strong>Synthesis</strong> - Sorts findings by severity (P1 = blocks merge, P2 = should fix, P3 = nice-to-have)</li>
|
||||
<li><strong>Persistence</strong> - Creates todo files so you don't lose track of issues</li>
|
||||
<li><strong>Summary</strong> - Hands you a readable report with action items</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
<a href="commands.html" class="button secondary">
|
||||
<i class="fa-solid fa-arrow-right"></i> View All Commands
|
||||
</a>
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Using Skills Section -->
|
||||
<section id="skills">
|
||||
<h2><i class="fa-solid fa-wand-magic-sparkles"></i> Using Skills</h2>
|
||||
|
||||
<p>
|
||||
Here's the difference: agents are <em>who</em> does the work, skills are <em>what they know</em>. 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.
|
||||
</p>
|
||||
|
||||
<h3>Invoking Skills</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code># 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"</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Skill Structure</h3>
|
||||
<p>Peek inside a skill directory and you'll usually find:</p>
|
||||
<ul>
|
||||
<li><strong>SKILL.md</strong> - The main instructions (what Claude reads first)</li>
|
||||
<li><strong>references/</strong> - Deep dives on concepts and patterns</li>
|
||||
<li><strong>templates/</strong> - Copy-paste code snippets</li>
|
||||
<li><strong>workflows/</strong> - Step-by-step "how to" guides</li>
|
||||
<li><strong>scripts/</strong> - Actual executable code (when words aren't enough)</li>
|
||||
</ul>
|
||||
|
||||
<p>
|
||||
<a href="skills.html" class="button secondary">
|
||||
<i class="fa-solid fa-arrow-right"></i> View All Skills
|
||||
</a>
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<!-- Code Review Workflow Guide -->
|
||||
<section id="code-review">
|
||||
<h2><i class="fa-solid fa-code-pull-request"></i> Code Review Workflow Guide</h2>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Basic Review</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code># Review a PR
|
||||
/review 123
|
||||
|
||||
# Review current branch
|
||||
/review</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Understanding Findings</h3>
|
||||
<p>Every finding gets a priority label. Here's what they mean:</p>
|
||||
<ul>
|
||||
<li><span class="badge badge-critical">P1 Critical</span> - Don't merge until this is fixed. Think: SQL injection, data loss, crashes in production.</li>
|
||||
<li><span class="badge badge-important">P2 Important</span> - Fix before shipping. Performance regressions, N+1 queries, shaky architecture.</li>
|
||||
<li><span class="badge badge-nice">P3 Nice-to-Have</span> - Would be better, but ship without it if you need to. Documentation, minor cleanup, style issues.</li>
|
||||
</ul>
|
||||
|
||||
<h3>Working with Todo Files</h3>
|
||||
<p>After a review, you'll have a <code>todos/</code> directory full of markdown files. Each one is a single issue to fix:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code># List all pending todos
|
||||
ls todos/*-pending-*.md
|
||||
|
||||
# Triage findings
|
||||
/triage
|
||||
|
||||
# Resolve todos in parallel
|
||||
/resolve_todo_parallel</code></pre>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Creating Custom Agents -->
|
||||
<section id="creating-agents">
|
||||
<h2><i class="fa-solid fa-plus"></i> Creating Custom Agents</h2>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Agent File Structure</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code>---
|
||||
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</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Agent Location</h3>
|
||||
<p>Drop your agent file in one of these directories:</p>
|
||||
<ul>
|
||||
<li><code>.claude/agents/</code> - Just for this project (committed to git)</li>
|
||||
<li><code>~/.claude/agents/</code> - Available in all your projects (stays on your machine)</li>
|
||||
</ul>
|
||||
|
||||
<div class="callout callout-tip">
|
||||
<div class="callout-icon"><i class="fa-solid fa-lightbulb"></i></div>
|
||||
<div class="callout-content">
|
||||
<h4>The Easy Way</h4>
|
||||
<p>
|
||||
Don't write the YAML by hand. Just run <code>/create-agent-skill</code> and answer a few questions. The command generates the file, validates the format, and puts it in the right place.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Creating Custom Skills -->
|
||||
<section id="creating-skills">
|
||||
<h2><i class="fa-solid fa-plus"></i> Creating Custom Skills</h2>
|
||||
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Skill Directory Structure</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code>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</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>SKILL.md Format</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code>---
|
||||
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.</code></pre>
|
||||
</div>
|
||||
|
||||
<div class="callout callout-tip">
|
||||
<div class="callout-icon"><i class="fa-solid fa-lightbulb"></i></div>
|
||||
<div class="callout-content">
|
||||
<h4>Get Help Building Skills</h4>
|
||||
<p>
|
||||
Type <code>skill: create-agent-skills</code> 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.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Navigation -->
|
||||
<nav class="docs-nav-footer">
|
||||
<a href="../index.html" class="nav-prev">
|
||||
<span class="nav-label">Previous</span>
|
||||
<span class="nav-title"><i class="fa-solid fa-arrow-left"></i> Home</span>
|
||||
</a>
|
||||
<a href="agents.html" class="nav-next">
|
||||
<span class="nav-label">Next</span>
|
||||
<span class="nav-title">Agent Reference <i class="fa-solid fa-arrow-right"></i></span>
|
||||
</a>
|
||||
</nav>
|
||||
</article>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
// Sidebar toggle for mobile
|
||||
document.querySelector('[data-sidebar-toggle]')?.addEventListener('click', () => {
|
||||
document.querySelector('.docs-sidebar').classList.toggle('open');
|
||||
});
|
||||
|
||||
// Active link highlighting
|
||||
const sections = document.querySelectorAll('section[id]');
|
||||
const navLinks = document.querySelectorAll('.sidebar-nav a');
|
||||
|
||||
window.addEventListener('scroll', () => {
|
||||
let current = '';
|
||||
sections.forEach(section => {
|
||||
const sectionTop = section.offsetTop;
|
||||
if (pageYOffset >= sectionTop - 100) {
|
||||
current = section.getAttribute('id');
|
||||
}
|
||||
});
|
||||
|
||||
navLinks.forEach(link => {
|
||||
link.classList.remove('active');
|
||||
if (link.getAttribute('href') === `#${current}`) {
|
||||
link.classList.add('active');
|
||||
}
|
||||
});
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -1,409 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en" class="theme-dark">
|
||||
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>MCP Servers Reference - Compounding Engineering</title>
|
||||
<meta content="Complete reference for the two MCP servers in the Compounding Engineering plugin." name="description" />
|
||||
<meta content="width=device-width, initial-scale=1" name="viewport" />
|
||||
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" />
|
||||
<link href="../css/style.css" rel="stylesheet" type="text/css" />
|
||||
<link href="../css/docs.css" rel="stylesheet" type="text/css" />
|
||||
<script src="../js/main.js" type="text/javascript" defer></script>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div class="background-gradient"></div>
|
||||
<div class="docs-layout">
|
||||
<aside class="docs-sidebar">
|
||||
<div class="sidebar-header">
|
||||
<a href="../index.html" class="nav-brand">
|
||||
<span class="logo-icon"><i class="fa-solid fa-layer-group"></i></span>
|
||||
<span class="logo-text">CE Docs</span>
|
||||
</a>
|
||||
</div>
|
||||
<nav class="sidebar-nav">
|
||||
<div class="nav-section">
|
||||
<h3>Getting Started</h3>
|
||||
<ul>
|
||||
<li><a href="getting-started.html">Installation</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Reference</h3>
|
||||
<ul>
|
||||
<li><a href="agents.html">Agents (23)</a></li>
|
||||
<li><a href="commands.html">Commands (13)</a></li>
|
||||
<li><a href="skills.html">Skills (11)</a></li>
|
||||
<li><a href="mcp-servers.html" class="active">MCP Servers (two)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Resources</h3>
|
||||
<ul>
|
||||
<li><a href="changelog.html">Changelog</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>On This Page</h3>
|
||||
<ul>
|
||||
<li><a href="#playwright">Playwright</a></li>
|
||||
<li><a href="#context7">Context7</a></li>
|
||||
<li><a href="#manual-config">Manual Configuration</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</nav>
|
||||
</aside>
|
||||
|
||||
<main class="docs-content">
|
||||
<div class="docs-header">
|
||||
<nav class="breadcrumb">
|
||||
<a href="../index.html">Home</a>
|
||||
<span>/</span>
|
||||
<a href="getting-started.html">Docs</a>
|
||||
<span>/</span>
|
||||
<span>MCP Servers</span>
|
||||
</nav>
|
||||
<button class="mobile-menu-toggle" data-sidebar-toggle>
|
||||
<i class="fa-solid fa-bars"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<article class="docs-article">
|
||||
<h1><i class="fa-solid fa-server color-accent"></i> MCP Servers Reference</h1>
|
||||
<p class="lead">
|
||||
Think of MCP servers as power tools that plug into Claude Code. Want Claude to actually <em>open a browser</em> 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.
|
||||
</p>
|
||||
|
||||
<div class="callout callout-warning">
|
||||
<div class="callout-icon"><i class="fa-solid fa-triangle-exclamation"></i></div>
|
||||
<div class="callout-content">
|
||||
<h4>Known Issue: Auto-Loading</h4>
|
||||
<p>
|
||||
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 <a href="#manual-config">Manual Configuration</a> for the fix.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Playwright -->
|
||||
<section id="playwright">
|
||||
<h2><i class="fa-brands fa-chrome"></i> Playwright</h2>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Tools Provided</h3>
|
||||
<table class="docs-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Tool</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>browser_navigate</code></td>
|
||||
<td>Go to any URL—your localhost dev server, production, staging, that competitor's site you're studying</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>browser_take_screenshot</code></td>
|
||||
<td>Capture what you're seeing right now. Perfect for "does this look right?" design reviews</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>browser_click</code></td>
|
||||
<td>Click buttons, links, whatever. Claude finds it by text or CSS selector, just like you would</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>browser_fill_form</code></td>
|
||||
<td>Type into forms faster than you can. Great for testing signup flows without manual clicking</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>browser_snapshot</code></td>
|
||||
<td>Get the page's accessibility tree—how screen readers see it. Useful for understanding structure without HTML noise</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>browser_evaluate</code></td>
|
||||
<td>Run any JavaScript in the page. Check localStorage, trigger functions, read variables—full console access</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>When You'll Use This</h3>
|
||||
<ul>
|
||||
<li><strong>Design reviews without leaving the terminal</strong> - "Take a screenshot of the new navbar on mobile" gets you a PNG in seconds</li>
|
||||
<li><strong>Testing signup flows while you code</strong> - "Fill in the registration form with test@example.com and click submit" runs the test for you</li>
|
||||
<li><strong>Debugging production issues</strong> - "Navigate to the error page and show me what's in localStorage" gives you the state without opening DevTools</li>
|
||||
<li><strong>Competitive research</strong> - "Go to competitor.com and screenshot their pricing page" builds your swipe file automatically</li>
|
||||
</ul>
|
||||
|
||||
<h3>Example Usage</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code># Just talk to Claude naturally—it knows when to use Playwright
|
||||
|
||||
# Design review
|
||||
"Take a screenshot of the login page"
|
||||
|
||||
# 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.</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Configuration</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code>{
|
||||
"playwright": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@playwright/mcp@latest"],
|
||||
"env": {}
|
||||
}
|
||||
}</code></pre>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Context7 -->
|
||||
<section id="context7">
|
||||
<h2><i class="fa-solid fa-book-open"></i> Context7</h2>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Tools Provided</h3>
|
||||
<table class="docs-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Tool</th>
|
||||
<th>Description</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>resolve-library-id</code></td>
|
||||
<td>Maps "Rails" to the actual library identifier Context7 uses. You don't call this—Claude does it automatically</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>get-library-docs</code></td>
|
||||
<td>Fetches the actual documentation pages. Ask "How does useEffect work?" and this grabs the latest React docs</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>What's Covered</h3>
|
||||
<p>Over 100 frameworks and libraries. Here's a taste of what you can look up:</p>
|
||||
<div class="framework-grid">
|
||||
<div class="framework-category">
|
||||
<h4>Backend</h4>
|
||||
<ul>
|
||||
<li>Ruby on Rails</li>
|
||||
<li>Django</li>
|
||||
<li>Laravel</li>
|
||||
<li>Express</li>
|
||||
<li>FastAPI</li>
|
||||
<li>Spring Boot</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="framework-category">
|
||||
<h4>Frontend</h4>
|
||||
<ul>
|
||||
<li>React</li>
|
||||
<li>Vue.js</li>
|
||||
<li>Angular</li>
|
||||
<li>Svelte</li>
|
||||
<li>Next.js</li>
|
||||
<li>Nuxt</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="framework-category">
|
||||
<h4>Mobile</h4>
|
||||
<ul>
|
||||
<li>React Native</li>
|
||||
<li>Flutter</li>
|
||||
<li>SwiftUI</li>
|
||||
<li>Kotlin</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="framework-category">
|
||||
<h4>Tools & Libraries</h4>
|
||||
<ul>
|
||||
<li>Tailwind CSS</li>
|
||||
<li>PostgreSQL</li>
|
||||
<li>Redis</li>
|
||||
<li>GraphQL</li>
|
||||
<li>Prisma</li>
|
||||
<li>And many more...</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h3>Example Usage</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code># 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?"
|
||||
|
||||
# You get answers based on the latest docs, not Claude's training cutoff</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Configuration</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code>{
|
||||
"context7": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.context7.com/mcp"
|
||||
}
|
||||
}</code></pre>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Manual Configuration -->
|
||||
<section id="manual-config">
|
||||
<h2><i class="fa-solid fa-gear"></i> Manual Configuration</h2>
|
||||
<p>
|
||||
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.
|
||||
</p>
|
||||
|
||||
<h3>Project-Level Configuration</h3>
|
||||
<p>To enable for just this project, add this to <code>.claude/settings.json</code> in your project root:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>{
|
||||
"mcpServers": {
|
||||
"playwright": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@playwright/mcp@latest"],
|
||||
"env": {}
|
||||
},
|
||||
"context7": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.context7.com/mcp"
|
||||
}
|
||||
}
|
||||
}</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Global Configuration</h3>
|
||||
<p>Or enable everywhere—every project on your machine gets these servers. Add to <code>~/.claude/settings.json</code>:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>{
|
||||
"mcpServers": {
|
||||
"playwright": {
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@playwright/mcp@latest"],
|
||||
"env": {}
|
||||
},
|
||||
"context7": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.context7.com/mcp"
|
||||
}
|
||||
}
|
||||
}</code></pre>
|
||||
</div>
|
||||
|
||||
<h3>Requirements</h3>
|
||||
<table class="docs-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Server</th>
|
||||
<th>Requirement</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td>Playwright</td>
|
||||
<td>Node.js 18+ and npx</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Context7</td>
|
||||
<td>Internet connection (HTTP endpoint)</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h3>Verifying MCP Servers</h3>
|
||||
<p>After you add the config, restart Claude Code. Then test that everything works:</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code># Ask Claude what it has
|
||||
"What MCP tools do you have access to?"
|
||||
|
||||
# Test Playwright (should work now)
|
||||
"Take a screenshot of the current directory listing"
|
||||
|
||||
# Test Context7 (should fetch real docs)
|
||||
"Look up Rails Active Record documentation"
|
||||
|
||||
# If either fails, double-check your JSON syntax and file paths</code></pre>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Navigation -->
|
||||
<nav class="docs-nav-footer">
|
||||
<a href="skills.html" class="nav-prev">
|
||||
<span class="nav-label">Previous</span>
|
||||
<span class="nav-title"><i class="fa-solid fa-arrow-left"></i> Skills</span>
|
||||
</a>
|
||||
<a href="getting-started.html" class="nav-next">
|
||||
<span class="nav-label">Back to</span>
|
||||
<span class="nav-title">Getting Started <i class="fa-solid fa-arrow-right"></i></span>
|
||||
</a>
|
||||
</nav>
|
||||
</article>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<style>
|
||||
.framework-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
gap: var(--space-l);
|
||||
margin: var(--space-l) 0;
|
||||
}
|
||||
|
||||
@media (min-width: 768px) {
|
||||
.framework-grid {
|
||||
grid-template-columns: repeat(4, 1fr);
|
||||
}
|
||||
}
|
||||
|
||||
.framework-category {
|
||||
background-color: var(--color-surface);
|
||||
padding: var(--space-l);
|
||||
border-radius: var(--radius-m);
|
||||
border: 1px solid var(--color-border);
|
||||
}
|
||||
|
||||
.framework-category h4 {
|
||||
margin: 0 0 var(--space-s) 0;
|
||||
color: var(--color-accent);
|
||||
font-size: var(--font-size-s);
|
||||
}
|
||||
|
||||
.framework-category ul {
|
||||
margin: 0;
|
||||
padding-left: var(--space-l);
|
||||
}
|
||||
|
||||
.framework-category li {
|
||||
margin: var(--space-xs) 0;
|
||||
font-size: var(--font-size-s);
|
||||
color: var(--color-text-secondary);
|
||||
}
|
||||
</style>
|
||||
|
||||
<script>
|
||||
document.querySelector('[data-sidebar-toggle]')?.addEventListener('click', () => {
|
||||
document.querySelector('.docs-sidebar').classList.toggle('open');
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -1,611 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en" class="theme-dark">
|
||||
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>Skill Reference - Compounding Engineering</title>
|
||||
<meta content="Complete reference for all 12 intelligent skills in the Compounding Engineering plugin." name="description" />
|
||||
<meta content="width=device-width, initial-scale=1" name="viewport" />
|
||||
|
||||
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.1/css/all.min.css" />
|
||||
<link href="../css/style.css" rel="stylesheet" type="text/css" />
|
||||
<link href="../css/docs.css" rel="stylesheet" type="text/css" />
|
||||
<script src="../js/main.js" type="text/javascript" defer></script>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<div class="background-gradient"></div>
|
||||
<div class="docs-layout">
|
||||
<aside class="docs-sidebar">
|
||||
<div class="sidebar-header">
|
||||
<a href="../index.html" class="nav-brand">
|
||||
<span class="logo-icon"><i class="fa-solid fa-layer-group"></i></span>
|
||||
<span class="logo-text">CE Docs</span>
|
||||
</a>
|
||||
</div>
|
||||
<nav class="sidebar-nav">
|
||||
<div class="nav-section">
|
||||
<h3>Getting Started</h3>
|
||||
<ul>
|
||||
<li><a href="getting-started.html">Installation</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Reference</h3>
|
||||
<ul>
|
||||
<li><a href="agents.html">Agents (27)</a></li>
|
||||
<li><a href="commands.html">Commands (19)</a></li>
|
||||
<li><a href="skills.html" class="active">Skills (12)</a></li>
|
||||
<li><a href="mcp-servers.html">MCP Servers (2)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>Resources</h3>
|
||||
<ul>
|
||||
<li><a href="changelog.html">Changelog</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="nav-section">
|
||||
<h3>On This Page</h3>
|
||||
<ul>
|
||||
<li><a href="#development-tools">Development (8)</a></li>
|
||||
<li><a href="#content-workflow">Content & Workflow (3)</a></li>
|
||||
<li><a href="#image-generation">Image Generation (1)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</nav>
|
||||
</aside>
|
||||
|
||||
<main class="docs-content">
|
||||
<div class="docs-header">
|
||||
<nav class="breadcrumb">
|
||||
<a href="../index.html">Home</a>
|
||||
<span>/</span>
|
||||
<a href="getting-started.html">Docs</a>
|
||||
<span>/</span>
|
||||
<span>Skills</span>
|
||||
</nav>
|
||||
<button class="mobile-menu-toggle" data-sidebar-toggle>
|
||||
<i class="fa-solid fa-bars"></i>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<article class="docs-article">
|
||||
<h1><i class="fa-solid fa-wand-magic-sparkles color-accent"></i> Skill Reference</h1>
|
||||
<p class="lead">
|
||||
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.
|
||||
</p>
|
||||
|
||||
<div class="usage-box">
|
||||
<h3>How to Use Skills</h3>
|
||||
<div class="card-code-block">
|
||||
<pre><code># In your prompt, reference the skill
|
||||
skill: [skill-name]
|
||||
|
||||
# Examples
|
||||
skill: gemini-imagegen
|
||||
skill: dhh-rails-style
|
||||
skill: create-agent-skills</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="callout callout-info">
|
||||
<div class="callout-icon"><i class="fa-solid fa-circle-info"></i></div>
|
||||
<div class="callout-content">
|
||||
<h4>Skills vs Agents</h4>
|
||||
<p>
|
||||
<strong>Agents</strong> are personas—they <em>do</em> things. <strong>Skills</strong> are knowledge—they teach Claude <em>how</em> to do things. Use <code>claude agent [name]</code> when you want someone to review your code. Use <code>skill: [name]</code> when you want to write code in a particular style yourself.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<!-- Development Tools -->
|
||||
<section id="development-tools">
|
||||
<h2><i class="fa-solid fa-code"></i> Development Tools (8)</h2>
|
||||
<p>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.</p>
|
||||
|
||||
<div class="skill-detail" id="create-agent-skills">
|
||||
<div class="skill-detail-header">
|
||||
<h3>create-agent-skills</h3>
|
||||
<span class="skill-badge">Meta</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Capabilities</h4>
|
||||
<ul>
|
||||
<li>Skill architecture and best practices</li>
|
||||
<li>Router pattern for complex multi-step skills</li>
|
||||
<li>Progressive disclosure design principles</li>
|
||||
<li>SKILL.md structure guidance</li>
|
||||
<li>Asset management (workflows, references, templates, scripts)</li>
|
||||
<li>XML structure patterns</li>
|
||||
</ul>
|
||||
<h4>Workflows Included</h4>
|
||||
<ul>
|
||||
<li><code>create-new-skill</code> - Start from scratch</li>
|
||||
<li><code>add-reference</code> - Add reference documentation</li>
|
||||
<li><code>add-template</code> - Add code templates</li>
|
||||
<li><code>add-workflow</code> - Add step-by-step procedures</li>
|
||||
<li><code>add-script</code> - Add executable scripts</li>
|
||||
<li><code>audit-skill</code> - Validate skill structure</li>
|
||||
<li><code>verify-skill</code> - Test skill functionality</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: create-agent-skills</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="skill-creator">
|
||||
<div class="skill-detail-header">
|
||||
<h3>skill-creator</h3>
|
||||
<span class="skill-badge">Meta</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
The simpler, step-by-step version of <code>create-agent-skills</code>. 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."
|
||||
</p>
|
||||
<h4>6-Step Process</h4>
|
||||
<ol>
|
||||
<li>Understand skill usage patterns with examples</li>
|
||||
<li>Plan reusable skill contents</li>
|
||||
<li>Initialize skill using template</li>
|
||||
<li>Edit skill with clear instructions</li>
|
||||
<li>Package skill into distributable zip</li>
|
||||
<li>Iterate based on testing feedback</li>
|
||||
</ol>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: skill-creator</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="dhh-rails-style">
|
||||
<div class="skill-detail-header">
|
||||
<h3>dhh-rails-style</h3>
|
||||
<span class="skill-badge">Rails</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
Comprehensive 37signals Rails conventions based on Marc Köhlbrugge's analysis of 265 PRs from the Fizzy codebase. Covers everything from REST mapping to state-as-records, Turbo/Stimulus patterns, CSS with OKLCH colors, Minitest with fixtures, and Solid Queue/Cache/Cable patterns.
|
||||
</p>
|
||||
<h4>Key Patterns</h4>
|
||||
<ul>
|
||||
<li><strong>REST Purity</strong> - Verbs become nouns (close → closure)</li>
|
||||
<li><strong>State as Records</strong> - Boolean columns → separate records</li>
|
||||
<li><strong>Fat Models</strong> - Business logic, authorization, broadcasting</li>
|
||||
<li><strong>Thin Controllers</strong> - 1-5 line actions with concerns</li>
|
||||
<li><strong>Current Attributes</strong> - Request context everywhere</li>
|
||||
<li><strong>Hotwire/Turbo</strong> - Model-level broadcasting, morphing</li>
|
||||
</ul>
|
||||
<h4>Reference Files (6)</h4>
|
||||
<ul>
|
||||
<li><code>controllers.md</code> - REST mapping, concerns, Turbo responses</li>
|
||||
<li><code>models.md</code> - Concerns, state records, callbacks, POROs</li>
|
||||
<li><code>frontend.md</code> - Turbo, Stimulus, CSS layers, OKLCH</li>
|
||||
<li><code>architecture.md</code> - Routing, auth, jobs, caching</li>
|
||||
<li><code>testing.md</code> - Minitest, fixtures, integration tests</li>
|
||||
<li><code>gems.md</code> - What to use vs avoid, decision framework</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: dhh-rails-style</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="andrew-kane-gem-writer">
|
||||
<div class="skill-detail-header">
|
||||
<h3>andrew-kane-gem-writer</h3>
|
||||
<span class="skill-badge">Ruby</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Philosophy</h4>
|
||||
<ul>
|
||||
<li>Simplicity over cleverness</li>
|
||||
<li>Zero or minimal dependencies</li>
|
||||
<li>Explicit code over metaprogramming</li>
|
||||
<li>Rails integration without Rails coupling</li>
|
||||
</ul>
|
||||
<h4>Key Patterns</h4>
|
||||
<ul>
|
||||
<li>Class macro DSL for configuration</li>
|
||||
<li><code>ActiveSupport.on_load</code> for Rails integration</li>
|
||||
<li><code>class << self</code> with <code>attr_accessor</code></li>
|
||||
<li>Railtie pattern for hooks</li>
|
||||
<li>Minitest (no RSpec)</li>
|
||||
</ul>
|
||||
<h4>Reference Files</h4>
|
||||
<ul>
|
||||
<li><code>references/module-organization.md</code></li>
|
||||
<li><code>references/rails-integration.md</code></li>
|
||||
<li><code>references/database-adapters.md</code></li>
|
||||
<li><code>references/testing-patterns.md</code></li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: andrew-kane-gem-writer</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="dspy-ruby">
|
||||
<div class="skill-detail-header">
|
||||
<h3>dspy-ruby</h3>
|
||||
<span class="skill-badge">AI</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Predictor Types</h4>
|
||||
<ul>
|
||||
<li><strong>Predict</strong> - Basic inference</li>
|
||||
<li><strong>ChainOfThought</strong> - Reasoning with explanations</li>
|
||||
<li><strong>ReAct</strong> - Tool-using agents with iteration</li>
|
||||
<li><strong>CodeAct</strong> - Dynamic code generation</li>
|
||||
</ul>
|
||||
<h4>Supported Providers</h4>
|
||||
<ul>
|
||||
<li>OpenAI (GPT-4, GPT-4o-mini)</li>
|
||||
<li>Anthropic Claude</li>
|
||||
<li>Google Gemini</li>
|
||||
<li>Ollama (free, local)</li>
|
||||
<li>OpenRouter</li>
|
||||
</ul>
|
||||
<h4>Requirements</h4>
|
||||
<table class="docs-table">
|
||||
<tr>
|
||||
<td><code>OPENAI_API_KEY</code></td>
|
||||
<td>For OpenAI provider</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>ANTHROPIC_API_KEY</code></td>
|
||||
<td>For Anthropic provider</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>GOOGLE_API_KEY</code></td>
|
||||
<td>For Gemini provider</td>
|
||||
</tr>
|
||||
</table>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: dspy-ruby</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="frontend-design">
|
||||
<div class="skill-detail-header">
|
||||
<h3>frontend-design</h3>
|
||||
<span class="skill-badge">Design</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Design Thinking</h4>
|
||||
<ul>
|
||||
<li><strong>Purpose</strong> - What is the interface for?</li>
|
||||
<li><strong>Tone</strong> - What feeling should it evoke?</li>
|
||||
<li><strong>Constraints</strong> - Technical and brand limitations</li>
|
||||
<li><strong>Differentiation</strong> - How to stand out</li>
|
||||
</ul>
|
||||
<h4>Focus Areas</h4>
|
||||
<ul>
|
||||
<li>Typography with distinctive font choices</li>
|
||||
<li>Color & theme coherence with CSS variables</li>
|
||||
<li>Motion and animation patterns</li>
|
||||
<li>Spatial composition with asymmetry</li>
|
||||
<li>Backgrounds (gradients, textures, patterns)</li>
|
||||
</ul>
|
||||
<div class="callout callout-tip">
|
||||
<div class="callout-icon"><i class="fa-solid fa-lightbulb"></i></div>
|
||||
<div class="callout-content">
|
||||
<p>Avoids generic AI aesthetics like Inter fonts, purple gradients, and rounded corners everywhere.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: frontend-design</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="compound-docs">
|
||||
<div class="skill-detail-header">
|
||||
<h3>compound-docs</h3>
|
||||
<span class="skill-badge">Docs</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Auto-Triggers</h4>
|
||||
<p>Phrases: "that worked", "it's fixed", "working now", "problem solved"</p>
|
||||
<h4>7-Step Process</h4>
|
||||
<ol>
|
||||
<li>Detect confirmation phrase</li>
|
||||
<li>Gather context (module, symptom, investigation, root cause)</li>
|
||||
<li>Check existing docs for similar issues</li>
|
||||
<li>Generate filename</li>
|
||||
<li>Validate YAML frontmatter</li>
|
||||
<li>Create documentation in category directory</li>
|
||||
<li>Cross-reference related issues</li>
|
||||
</ol>
|
||||
<h4>Categories</h4>
|
||||
<ul>
|
||||
<li><code>build-errors/</code></li>
|
||||
<li><code>test-failures/</code></li>
|
||||
<li><code>runtime-errors/</code></li>
|
||||
<li><code>performance-issues/</code></li>
|
||||
<li><code>database-issues/</code></li>
|
||||
<li><code>security-issues/</code></li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: compound-docs</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="agent-native-architecture">
|
||||
<div class="skill-detail-header">
|
||||
<h3>agent-native-architecture</h3>
|
||||
<span class="skill-badge">AI</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
Build AI agents using prompt-native architecture where features are defined in prompts, not code. When creating autonomous agents, designing MCP servers, or implementing self-modifying systems, this skill guides the "trust the agent's intelligence" philosophy.
|
||||
</p>
|
||||
<h4>Key Patterns</h4>
|
||||
<ul>
|
||||
<li><strong>Prompt-Native Features</strong> - Define features in prompts, not code</li>
|
||||
<li><strong>MCP Tool Design</strong> - Build tools agents can use effectively</li>
|
||||
<li><strong>System Prompts</strong> - Write instructions that guide agent behavior</li>
|
||||
<li><strong>Self-Modification</strong> - Allow agents to improve their own prompts</li>
|
||||
</ul>
|
||||
<h4>Core Principle</h4>
|
||||
<p>Whatever the user can do, the agent can do. Whatever the user can see, the agent can see.</p>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: agent-native-architecture</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Content & Workflow -->
|
||||
<section id="content-workflow">
|
||||
<h2><i class="fa-solid fa-pen-fancy"></i> Content & Workflow (3)</h2>
|
||||
<p>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.</p>
|
||||
|
||||
<div class="skill-detail" id="every-style-editor">
|
||||
<div class="skill-detail-header">
|
||||
<h3>every-style-editor</h3>
|
||||
<span class="skill-badge">Content</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Four-Phase Review</h4>
|
||||
<ol>
|
||||
<li><strong>Initial Assessment</strong> - Context, type, audience, tone</li>
|
||||
<li><strong>Detailed Line Edit</strong> - Sentence structure, punctuation, capitalization</li>
|
||||
<li><strong>Mechanical Review</strong> - Spacing, formatting, consistency</li>
|
||||
<li><strong>Recommendations</strong> - Actionable improvement suggestions</li>
|
||||
</ol>
|
||||
<h4>Style Checks</h4>
|
||||
<ul>
|
||||
<li>Grammar and punctuation</li>
|
||||
<li>Style guide compliance</li>
|
||||
<li>Capitalization rules</li>
|
||||
<li>Word choice optimization</li>
|
||||
<li>Formatting consistency</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: every-style-editor</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="file-todos">
|
||||
<div class="skill-detail-header">
|
||||
<h3>file-todos</h3>
|
||||
<span class="skill-badge">Workflow</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
Your todo list is a bunch of markdown files in a <code>todos/</code> 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.
|
||||
</p>
|
||||
<h4>File Format</h4>
|
||||
<div class="card-code-block">
|
||||
<pre><code># 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</code></pre>
|
||||
</div>
|
||||
<h4>Status Values</h4>
|
||||
<ul>
|
||||
<li><code>pending</code> - Needs triage</li>
|
||||
<li><code>ready</code> - Approved for work</li>
|
||||
<li><code>complete</code> - Done</li>
|
||||
</ul>
|
||||
<h4>Priority Values</h4>
|
||||
<ul>
|
||||
<li><code>p1</code> - Critical</li>
|
||||
<li><code>p2</code> - Important</li>
|
||||
<li><code>p3</code> - Nice-to-have</li>
|
||||
</ul>
|
||||
<h4>YAML Frontmatter</h4>
|
||||
<div class="card-code-block">
|
||||
<pre><code>---
|
||||
status: pending
|
||||
priority: p1
|
||||
issue_id: "001"
|
||||
tags: [security, authentication]
|
||||
dependencies: []
|
||||
---</code></pre>
|
||||
</div>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: file-todos</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="skill-detail" id="git-worktree">
|
||||
<div class="skill-detail-header">
|
||||
<h3>git-worktree</h3>
|
||||
<span class="skill-badge">Git</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
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.
|
||||
</p>
|
||||
<h4>Commands</h4>
|
||||
<div class="card-code-block">
|
||||
<pre><code># 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</code></pre>
|
||||
</div>
|
||||
<h4>Integration</h4>
|
||||
<ul>
|
||||
<li>Works with <code>/review</code> for isolated PR analysis</li>
|
||||
<li>Works with <code>/work</code> for parallel feature development</li>
|
||||
</ul>
|
||||
<h4>Requirements</h4>
|
||||
<ul>
|
||||
<li>Git 2.8+ (for worktree support)</li>
|
||||
<li>Worktrees stored in <code>.worktrees/</code> directory</li>
|
||||
</ul>
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: git-worktree</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Image Generation -->
|
||||
<section id="image-generation">
|
||||
<h2><i class="fa-solid fa-image"></i> Image Generation (1)</h2>
|
||||
<p>Generate images with AI. Not stock photos you found on Unsplash—images you describe and the model creates.</p>
|
||||
|
||||
<div class="skill-detail featured" id="gemini-imagegen">
|
||||
<div class="skill-detail-header">
|
||||
<h3>gemini-imagegen</h3>
|
||||
<span class="skill-badge highlight">AI Images</span>
|
||||
</div>
|
||||
<p class="skill-detail-description">
|
||||
Need a logo with specific text? A product mockup on a marble surface? An illustration in a kawaii style? This skill wraps Google's Gemini image generation API. You describe what you want, it generates it. You can edit existing images, refine over multiple turns, or compose from reference images. All through simple Python scripts.
|
||||
</p>
|
||||
|
||||
<h4>Features</h4>
|
||||
<div class="skill-features">
|
||||
<div class="feature-item"><i class="fa-solid fa-check"></i> Text-to-image generation</div>
|
||||
<div class="feature-item"><i class="fa-solid fa-check"></i> Image editing & manipulation</div>
|
||||
<div class="feature-item"><i class="fa-solid fa-check"></i> Multi-turn iterative refinement</div>
|
||||
<div class="feature-item"><i class="fa-solid fa-check"></i> Multiple reference images (up to 14)</div>
|
||||
<div class="feature-item"><i class="fa-solid fa-check"></i> Google Search grounding (Pro)</div>
|
||||
</div>
|
||||
|
||||
<h4>Available Models</h4>
|
||||
<table class="docs-table">
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Model</th>
|
||||
<th>Resolution</th>
|
||||
<th>Best For</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
<tr>
|
||||
<td><code>gemini-2.5-flash-image</code></td>
|
||||
<td>1024px</td>
|
||||
<td>Speed, high-volume tasks</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>gemini-3-pro-image-preview</code></td>
|
||||
<td>Up to 4K</td>
|
||||
<td>Professional assets, complex instructions</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
|
||||
<h4>Quick Start</h4>
|
||||
<div class="card-code-block">
|
||||
<pre><code># Text-to-image
|
||||
python scripts/generate_image.py "A cat wearing a wizard hat" output.png
|
||||
|
||||
# Edit existing image
|
||||
python scripts/edit_image.py input.png "Add a rainbow in the background" output.png
|
||||
|
||||
# Multi-turn chat
|
||||
python scripts/multi_turn_chat.py</code></pre>
|
||||
</div>
|
||||
|
||||
<h4>Image Configuration</h4>
|
||||
<div class="card-code-block">
|
||||
<pre><code>from google.genai import types
|
||||
|
||||
response = client.models.generate_content(
|
||||
model="gemini-3-pro-image-preview",
|
||||
contents=[prompt],
|
||||
config=types.GenerateContentConfig(
|
||||
response_modalities=['TEXT', 'IMAGE'],
|
||||
image_config=types.ImageConfig(
|
||||
aspect_ratio="16:9", # 1:1, 2:3, 3:2, 4:3, 16:9, 21:9
|
||||
image_size="2K" # 1K, 2K, 4K (Pro only)
|
||||
),
|
||||
)
|
||||
)</code></pre>
|
||||
</div>
|
||||
|
||||
<h4>Prompting Best Practices</h4>
|
||||
<ul>
|
||||
<li><strong>Photorealistic</strong> - Include camera details: lens type, lighting, angle, mood</li>
|
||||
<li><strong>Stylized Art</strong> - Specify style explicitly: kawaii, cel-shading, bold outlines</li>
|
||||
<li><strong>Text in Images</strong> - Be explicit about font style and placement (use Pro model)</li>
|
||||
<li><strong>Product Mockups</strong> - Describe lighting setup and surface</li>
|
||||
</ul>
|
||||
|
||||
<h4>Requirements</h4>
|
||||
<table class="docs-table">
|
||||
<tr>
|
||||
<td><code>GEMINI_API_KEY</code></td>
|
||||
<td>Required environment variable</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>google-genai</code></td>
|
||||
<td>Python package</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><code>pillow</code></td>
|
||||
<td>Python package for image handling</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<div class="callout callout-info">
|
||||
<div class="callout-icon"><i class="fa-solid fa-circle-info"></i></div>
|
||||
<div class="callout-content">
|
||||
<p>All generated images include SynthID watermarks. Image-only mode won't work with Google Search grounding.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="card-code-block">
|
||||
<pre><code>skill: gemini-imagegen</code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<!-- Navigation -->
|
||||
<nav class="docs-nav-footer">
|
||||
<a href="commands.html" class="nav-prev">
|
||||
<span class="nav-label">Previous</span>
|
||||
<span class="nav-title"><i class="fa-solid fa-arrow-left"></i> Commands</span>
|
||||
</a>
|
||||
<a href="mcp-servers.html" class="nav-next">
|
||||
<span class="nav-label">Next</span>
|
||||
<span class="nav-title">MCP Servers <i class="fa-solid fa-arrow-right"></i></span>
|
||||
</a>
|
||||
</nav>
|
||||
</article>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
document.querySelector('[data-sidebar-toggle]')?.addEventListener('click', () => {
|
||||
document.querySelector('.docs-sidebar').classList.toggle('open');
|
||||
});
|
||||
</script>
|
||||
</body>
|
||||
|
||||
</html>
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "compound-engineering",
|
||||
"version": "2.37.2",
|
||||
"version": "2.38.0",
|
||||
"description": "AI-powered development tools. 29 agents, 22 commands, 20 skills, 1 MCP server for code review, research, design, and workflow automation.",
|
||||
"author": {
|
||||
"name": "Kieran Klaassen",
|
||||
|
||||
@@ -5,6 +5,16 @@ All notable changes to the compound-engineering plugin will be documented in thi
|
||||
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.38.0] - 2026-03-01
|
||||
|
||||
### Changed
|
||||
- `workflows:plan`, `workflows:work`, `workflows:review`, `workflows:brainstorm`, `workflows:compound` renamed to `ce:plan`, `ce:work`, `ce:review`, `ce:brainstorm`, `ce:compound` for clarity — the `ce:` prefix unambiguously identifies these as compound-engineering commands
|
||||
|
||||
### Deprecated
|
||||
- `workflows:*` commands — all five remain functional as aliases that forward to their `ce:*` equivalents with a deprecation notice. Will be removed in a future version.
|
||||
|
||||
---
|
||||
|
||||
## [2.37.2] - 2026-03-01
|
||||
|
||||
### Added
|
||||
|
||||
@@ -35,7 +35,8 @@ agents/
|
||||
└── docs/ # Documentation agents
|
||||
|
||||
commands/
|
||||
├── workflows/ # Core workflow commands (workflows:plan, workflows:review, etc.)
|
||||
├── ce/ # Core workflow commands (ce:plan, ce:review, etc.)
|
||||
├── workflows/ # Deprecated aliases for ce:* commands
|
||||
└── *.md # Utility commands
|
||||
|
||||
skills/
|
||||
@@ -44,13 +45,14 @@ skills/
|
||||
|
||||
## Command Naming Convention
|
||||
|
||||
**Workflow commands** use `workflows:` prefix to avoid collisions with built-in commands:
|
||||
- `/workflows:plan` - Create implementation plans
|
||||
- `/workflows:review` - Run comprehensive code reviews
|
||||
- `/workflows:work` - Execute work items systematically
|
||||
- `/workflows:compound` - Document solved problems
|
||||
**Workflow commands** use `ce:` prefix to unambiguously identify them as compound-engineering commands:
|
||||
- `/ce:plan` - Create implementation plans
|
||||
- `/ce:review` - Run comprehensive code reviews
|
||||
- `/ce:work` - Execute work items systematically
|
||||
- `/ce:compound` - Document solved problems
|
||||
- `/ce:brainstorm` - Explore requirements and approaches before planning
|
||||
|
||||
**Why `workflows:`?** Claude Code has built-in `/plan` and `/review` commands. Using `name: workflows:plan` in frontmatter creates a unique `/workflows:plan` command with no collision.
|
||||
**Why `ce:`?** Claude Code has built-in `/plan` and `/review` commands. The `ce:` namespace (short for compound-engineering) makes it immediately clear these commands belong to this plugin. The legacy `workflows:` prefix is still supported as deprecated aliases that forward to the `ce:*` equivalents.
|
||||
|
||||
## Skill Compliance Checklist
|
||||
|
||||
|
||||
@@ -73,15 +73,17 @@ Agents are organized into categories for easier discovery.
|
||||
|
||||
### Workflow Commands
|
||||
|
||||
Core workflow commands use `workflows:` prefix to avoid collisions with built-in commands:
|
||||
Core workflow commands use `ce:` prefix to unambiguously identify them as compound-engineering commands:
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/workflows:brainstorm` | Explore requirements and approaches before planning |
|
||||
| `/workflows:plan` | Create implementation plans |
|
||||
| `/workflows:review` | Run comprehensive code reviews |
|
||||
| `/workflows:work` | Execute work items systematically |
|
||||
| `/workflows:compound` | Document solved problems to compound team knowledge |
|
||||
| `/ce:brainstorm` | Explore requirements and approaches before planning |
|
||||
| `/ce:plan` | Create implementation plans |
|
||||
| `/ce:review` | Run comprehensive code reviews |
|
||||
| `/ce:work` | Execute work items systematically |
|
||||
| `/ce:compound` | Document solved problems to compound team knowledge |
|
||||
|
||||
> **Deprecated aliases:** `/workflows:plan`, `/workflows:work`, `/workflows:review`, `/workflows:brainstorm`, `/workflows:compound` still work but show a deprecation warning. Use `ce:*` equivalents.
|
||||
|
||||
### Utility Commands
|
||||
|
||||
|
||||
@@ -56,4 +56,4 @@ When analyzing, consider:
|
||||
|
||||
Your insights should help developers understand not just what the code does, but why it evolved to its current state, informing better decisions for future changes.
|
||||
|
||||
Note that files in `docs/plans/` and `docs/solutions/` are compound-engineering pipeline artifacts created by `/workflows:plan`. They are intentional, permanent living documents — do not recommend their removal or characterize them as unnecessary.
|
||||
Note that files in `docs/plans/` and `docs/solutions/` are compound-engineering pipeline artifacts created by `/ce:plan`. They are intentional, permanent living documents — do not recommend their removal or characterize them as unnecessary.
|
||||
|
||||
@@ -257,7 +257,7 @@ Structure your findings as:
|
||||
## Integration Points
|
||||
|
||||
This agent is designed to be invoked by:
|
||||
- `/workflows:plan` - To inform planning with institutional knowledge
|
||||
- `/ce:plan` - To inform planning with institutional knowledge
|
||||
- `/deepen-plan` - To add depth with relevant learnings
|
||||
- Manual invocation before starting work on a feature
|
||||
|
||||
|
||||
@@ -48,7 +48,7 @@ When reviewing code, you will:
|
||||
- Eliminate extensibility points without clear use cases
|
||||
- Question generic solutions for specific problems
|
||||
- Remove "just in case" code
|
||||
- Never flag `docs/plans/*.md` or `docs/solutions/*.md` for removal — these are compound-engineering pipeline artifacts created by `/workflows:plan` and used as living documents by `/workflows:work`
|
||||
- Never flag `docs/plans/*.md` or `docs/solutions/*.md` for removal — these are compound-engineering pipeline artifacts created by `/ce:plan` and used as living documents by `/ce:work`
|
||||
|
||||
6. **Optimize for Readability**:
|
||||
- Prefer self-documenting code over comments
|
||||
|
||||
145
plugins/compound-engineering/commands/ce/brainstorm.md
Normal file
145
plugins/compound-engineering/commands/ce/brainstorm.md
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: ce:brainstorm
|
||||
description: Explore requirements and approaches through collaborative dialogue before planning implementation
|
||||
argument-hint: "[feature idea or problem to explore]"
|
||||
---
|
||||
|
||||
# Brainstorm a Feature or Improvement
|
||||
|
||||
**Note: The current year is 2026.** Use this when dating brainstorm documents.
|
||||
|
||||
Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/ce:plan`, which answers **HOW** to build it.
|
||||
|
||||
**Process knowledge:** Load the `brainstorming` skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
|
||||
|
||||
## Feature Description
|
||||
|
||||
<feature_description> #$ARGUMENTS </feature_description>
|
||||
|
||||
**If the feature description above is empty, ask the user:** "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
|
||||
|
||||
Do not proceed until you have a feature description from the user.
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 0: Assess Requirements Clarity
|
||||
|
||||
Evaluate whether brainstorming is needed based on the feature description.
|
||||
|
||||
**Clear requirements indicators:**
|
||||
- Specific acceptance criteria provided
|
||||
- Referenced existing patterns to follow
|
||||
- Described exact expected behavior
|
||||
- Constrained, well-defined scope
|
||||
|
||||
**If requirements are already clear:**
|
||||
Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/ce:plan` instead, or would you like to explore the idea further?"
|
||||
|
||||
### Phase 1: Understand the Idea
|
||||
|
||||
#### 1.1 Repository Research (Lightweight)
|
||||
|
||||
Run a quick repo scan to understand existing patterns:
|
||||
|
||||
- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
|
||||
|
||||
Focus on: similar features, established patterns, CLAUDE.md guidance.
|
||||
|
||||
#### 1.2 Collaborative Dialogue
|
||||
|
||||
Use the **AskUserQuestion tool** to ask questions **one at a time**.
|
||||
|
||||
**Guidelines (see `brainstorming` skill for detailed techniques):**
|
||||
- Prefer multiple choice when natural options exist
|
||||
- Start broad (purpose, users) then narrow (constraints, edge cases)
|
||||
- Validate assumptions explicitly
|
||||
- Ask about success criteria
|
||||
|
||||
**Exit condition:** Continue until the idea is clear OR user says "proceed"
|
||||
|
||||
### Phase 2: Explore Approaches
|
||||
|
||||
Propose **2-3 concrete approaches** based on research and conversation.
|
||||
|
||||
For each approach, provide:
|
||||
- Brief description (2-3 sentences)
|
||||
- Pros and cons
|
||||
- When it's best suited
|
||||
|
||||
Lead with your recommendation and explain why. Apply YAGNI—prefer simpler solutions.
|
||||
|
||||
Use **AskUserQuestion tool** to ask which approach the user prefers.
|
||||
|
||||
### Phase 3: Capture the Design
|
||||
|
||||
Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`.
|
||||
|
||||
**Document structure:** See the `brainstorming` skill for the template format. Key sections: What We're Building, Why This Approach, Key Decisions, Open Questions.
|
||||
|
||||
Ensure `docs/brainstorms/` directory exists before writing.
|
||||
|
||||
**IMPORTANT:** Before proceeding to Phase 4, check if there are any Open Questions listed in the brainstorm document. If there are open questions, YOU MUST ask the user about each one using AskUserQuestion before offering to proceed to planning. Move resolved questions to a "Resolved Questions" section.
|
||||
|
||||
### Phase 4: Handoff
|
||||
|
||||
Use **AskUserQuestion tool** to present next steps:
|
||||
|
||||
**Question:** "Brainstorm captured. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Review and refine** - Improve the document through structured self-review
|
||||
2. **Proceed to planning** - Run `/ce:plan` (will auto-detect this brainstorm)
|
||||
3. **Share to Proof** - Upload to Proof for collaborative review and sharing
|
||||
4. **Ask more questions** - I have more questions to clarify before moving on
|
||||
5. **Done for now** - Return later
|
||||
|
||||
**If user selects "Share to Proof":**
|
||||
|
||||
```bash
|
||||
CONTENT=$(cat docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md)
|
||||
TITLE="Brainstorm: <topic title>"
|
||||
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
|
||||
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
||||
```
|
||||
|
||||
Display the URL prominently: `View & collaborate in Proof: <PROOF_URL>`
|
||||
|
||||
If the curl fails, skip silently. Then return to the Phase 4 options.
|
||||
|
||||
**If user selects "Ask more questions":** YOU (Claude) return to Phase 1.2 (Collaborative Dialogue) and continue asking the USER questions one at a time to further refine the design. The user wants YOU to probe deeper - ask about edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4.
|
||||
|
||||
**If user selects "Review and refine":**
|
||||
|
||||
Load the `document-review` skill and apply it to the brainstorm document.
|
||||
|
||||
When document-review returns "Review complete", present next steps:
|
||||
|
||||
1. **Move to planning** - Continue to `/ce:plan` with this document
|
||||
2. **Done for now** - Brainstorming complete. To start planning later: `/ce:plan [document-path]`
|
||||
|
||||
## Output Summary
|
||||
|
||||
When complete, display:
|
||||
|
||||
```
|
||||
Brainstorm complete!
|
||||
|
||||
Document: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md
|
||||
|
||||
Key decisions:
|
||||
- [Decision 1]
|
||||
- [Decision 2]
|
||||
|
||||
Next: Run `/ce:plan` when ready to implement.
|
||||
```
|
||||
|
||||
## Important Guidelines
|
||||
|
||||
- **Stay focused on WHAT, not HOW** - Implementation details belong in the plan
|
||||
- **Ask one question at a time** - Don't overwhelm
|
||||
- **Apply YAGNI** - Prefer simpler approaches
|
||||
- **Keep outputs concise** - 200-300 words per section max
|
||||
|
||||
NEVER CODE! Just explore and document decisions.
|
||||
240
plugins/compound-engineering/commands/ce/compound.md
Normal file
240
plugins/compound-engineering/commands/ce/compound.md
Normal file
@@ -0,0 +1,240 @@
|
||||
---
|
||||
name: ce: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
|
||||
/ce:compound # Document the most recent fix
|
||||
/ce:compound [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Execution Strategy: Two-Phase Orchestration
|
||||
|
||||
<critical_requirement>
|
||||
**Only ONE file gets written - the final documentation.**
|
||||
|
||||
Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file.
|
||||
</critical_requirement>
|
||||
|
||||
### Phase 1: Parallel Research
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
|
||||
|
||||
#### 1. **Context Analyzer**
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Validates against schema
|
||||
- Returns: YAML frontmatter skeleton
|
||||
|
||||
#### 2. **Solution Extractor**
|
||||
- Analyzes all investigation steps
|
||||
- Identifies root cause
|
||||
- Extracts working solution with code examples
|
||||
- Returns: Solution content block
|
||||
|
||||
#### 3. **Related Docs Finder**
|
||||
- Searches `docs/solutions/` for related documentation
|
||||
- Identifies cross-references and links
|
||||
- Finds related GitHub issues
|
||||
- Returns: Links and relationships
|
||||
|
||||
#### 4. **Prevention Strategist**
|
||||
- Develops prevention strategies
|
||||
- Creates best practices guidance
|
||||
- Generates test cases if applicable
|
||||
- Returns: Prevention/testing content
|
||||
|
||||
#### 5. **Category Classifier**
|
||||
- Determines optimal `docs/solutions/` category
|
||||
- Validates category against schema
|
||||
- Suggests filename based on slug
|
||||
- Returns: Final path and filename
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
### Phase 2: Assembly & Write
|
||||
|
||||
<sequential_tasks>
|
||||
|
||||
**WAIT for all Phase 1 subagents to complete before proceeding.**
|
||||
|
||||
The orchestrating agent (main conversation) performs these steps:
|
||||
|
||||
1. Collect all text results from Phase 1 subagents
|
||||
2. Assemble complete markdown file from the collected pieces
|
||||
3. Validate YAML frontmatter against schema
|
||||
4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
|
||||
5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
|
||||
|
||||
</sequential_tasks>
|
||||
|
||||
### Phase 3: Optional Enhancement
|
||||
|
||||
**WAIT for Phase 2 to complete before proceeding.**
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Based on problem type, optionally invoke specialized agents to review the documentation:
|
||||
|
||||
- **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`
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
## 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
|
||||
|
||||
<preconditions enforcement="advisory">
|
||||
<check condition="problem_solved">
|
||||
Problem has been solved (not in-progress)
|
||||
</check>
|
||||
<check condition="solution_verified">
|
||||
Solution has been verified working
|
||||
</check>
|
||||
<check condition="non_trivial">
|
||||
Non-trivial problem (not simple typo or obvious error)
|
||||
</check>
|
||||
</preconditions>
|
||||
|
||||
## 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/
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
| ❌ Wrong | ✅ Correct |
|
||||
|----------|-----------|
|
||||
| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
|
||||
| Research and assembly run in parallel | Research completes → then assembly runs |
|
||||
| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
|
||||
|
||||
## Success Output
|
||||
|
||||
```
|
||||
✓ Documentation complete
|
||||
|
||||
Subagent Results:
|
||||
✓ Context Analyzer: Identified performance_issue in brief_system
|
||||
✓ Solution Extractor: 3 code fixes
|
||||
✓ Related Docs Finder: 2 related issues
|
||||
✓ Prevention Strategist: Prevention strategies, test suggestions
|
||||
✓ Category Classifier: `performance-issues`
|
||||
|
||||
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
|
||||
|
||||
<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
|
||||
|
||||
<manual_override> Use /ce:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
|
||||
|
||||
## 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 /ce:compound completes for deeper review
|
||||
- **Customize agents**: Edit `compound-engineering.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
|
||||
- `/ce:plan` - Planning workflow (references documented solutions)
|
||||
636
plugins/compound-engineering/commands/ce/plan.md
Normal file
636
plugins/compound-engineering/commands/ce/plan.md
Normal file
@@ -0,0 +1,636 @@
|
||||
---
|
||||
name: ce:plan
|
||||
description: Transform feature descriptions into well-structured project plans following conventions
|
||||
argument-hint: "[feature description, bug report, or improvement idea]"
|
||||
---
|
||||
|
||||
# Create a plan for a new feature or bug fix
|
||||
|
||||
## Introduction
|
||||
|
||||
**Note: The current year is 2026.** 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
|
||||
|
||||
<feature_description> #$ARGUMENTS </feature_description>
|
||||
|
||||
**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.
|
||||
|
||||
### 0. Idea Refinement
|
||||
|
||||
**Check for brainstorm output first:**
|
||||
|
||||
Before asking questions, look for recent brainstorm documents in `docs/brainstorms/` that match this feature:
|
||||
|
||||
```bash
|
||||
ls -la docs/brainstorms/*.md 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
**Relevance criteria:** A brainstorm is relevant if:
|
||||
- The topic (from filename or YAML frontmatter) semantically matches the feature description
|
||||
- Created within the last 14 days
|
||||
- If multiple candidates match, use the most recent one
|
||||
|
||||
**If a relevant brainstorm exists:**
|
||||
1. Read the brainstorm document **thoroughly** — every section matters
|
||||
2. Announce: "Found brainstorm from [date]: [topic]. Using as foundation for planning."
|
||||
3. Extract and carry forward **ALL** of the following into the plan:
|
||||
- Key decisions and their rationale
|
||||
- Chosen approach and why alternatives were rejected
|
||||
- Constraints and requirements discovered during brainstorming
|
||||
- Open questions (flag these for resolution during planning)
|
||||
- Success criteria and scope boundaries
|
||||
- Any specific technical choices or patterns discussed
|
||||
4. **Skip the idea refinement questions below** — the brainstorm already answered WHAT to build
|
||||
5. Use brainstorm content as the **primary input** to research and planning phases
|
||||
6. **Critical: The brainstorm is the origin document.** Throughout the plan, reference specific decisions with `(see brainstorm: docs/brainstorms/<filename>)` when carrying forward conclusions. Do not paraphrase decisions in a way that loses their original context — link back to the source.
|
||||
7. **Do not omit brainstorm content** — if the brainstorm discussed it, the plan must address it (even if briefly). Scan each brainstorm section before finalizing the plan to verify nothing was dropped.
|
||||
|
||||
**If multiple brainstorms could match:**
|
||||
Use **AskUserQuestion tool** to ask which brainstorm to use, or whether to proceed without one.
|
||||
|
||||
**If no brainstorm found (or not relevant), run idea refinement:**
|
||||
|
||||
Refine the idea through collaborative dialogue using the **AskUserQuestion tool**:
|
||||
|
||||
- Ask questions one at a time to understand the idea fully
|
||||
- Prefer multiple choice questions when natural options exist
|
||||
- Focus on understanding: purpose, constraints and success criteria
|
||||
- Continue until the idea is clear OR user says "proceed"
|
||||
|
||||
**Gather signals for research decision.** During refinement, note:
|
||||
|
||||
- **User's familiarity**: Do they know the codebase patterns? Are they pointing to examples?
|
||||
- **User's intent**: Speed vs thoroughness? Exploration vs execution?
|
||||
- **Topic risk**: Security, payments, external APIs warrant more caution
|
||||
- **Uncertainty level**: Is the approach clear or open-ended?
|
||||
|
||||
**Skip option:** If the feature description is already detailed, offer:
|
||||
"Your description is clear. Should I proceed with research, or would you like to refine it further?"
|
||||
|
||||
## Main Tasks
|
||||
|
||||
### 1. Local Research (Always Runs - Parallel)
|
||||
|
||||
<thinking>
|
||||
First, I need to understand the project's conventions, existing patterns, and any documented learnings. This is fast and local - it informs whether external research is needed.
|
||||
</thinking>
|
||||
|
||||
Run these agents **in parallel** to gather local context:
|
||||
|
||||
- Task repo-research-analyst(feature_description)
|
||||
- Task learnings-researcher(feature_description)
|
||||
|
||||
**What to look for:**
|
||||
- **Repo research:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency
|
||||
- **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned)
|
||||
|
||||
These findings inform the next step.
|
||||
|
||||
### 1.5. Research Decision
|
||||
|
||||
Based on signals from Step 0 and findings from Step 1, decide on external research.
|
||||
|
||||
**High-risk topics → always research.** Security, payments, external APIs, data privacy. The cost of missing something is too high. This takes precedence over speed signals.
|
||||
|
||||
**Strong local context → skip external research.** Codebase has good patterns, CLAUDE.md has guidance, user knows what they want. External research adds little value.
|
||||
|
||||
**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable.
|
||||
|
||||
**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed.
|
||||
|
||||
Examples:
|
||||
- "Your codebase has solid patterns for this. Proceeding without external research."
|
||||
- "This involves payment processing, so I'll research current best practices first."
|
||||
|
||||
### 1.5b. External Research (Conditional)
|
||||
|
||||
**Only run if Step 1.5 indicates external research is valuable.**
|
||||
|
||||
Run these agents in parallel:
|
||||
|
||||
- Task best-practices-researcher(feature_description)
|
||||
- Task framework-docs-researcher(feature_description)
|
||||
|
||||
### 1.6. Consolidate Research
|
||||
|
||||
After all research steps complete, consolidate findings:
|
||||
|
||||
- Document relevant file paths from repo research (e.g., `app/services/example_service.rb:42`)
|
||||
- **Include relevant institutional learnings** from `docs/solutions/` (key insights, gotchas to avoid)
|
||||
- Note external documentation URLs and best practices (if external research was done)
|
||||
- List related issues or PRs discovered
|
||||
- Capture CLAUDE.md conventions
|
||||
|
||||
**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
|
||||
|
||||
### 2. Issue Planning & Structure
|
||||
|
||||
<thinking>
|
||||
Think like a product manager - what would make this issue clear and actionable? Consider multiple perspectives
|
||||
</thinking>
|
||||
|
||||
**Title & Categorization:**
|
||||
|
||||
- [ ] Draft clear, searchable issue title using conventional format (e.g., `feat: Add user authentication`, `fix: Cart total calculation`)
|
||||
- [ ] Determine issue type: enhancement, bug, refactor
|
||||
- [ ] Convert title to filename: add today's date prefix, strip prefix colon, kebab-case, add `-plan` suffix
|
||||
- Example: `feat: Add User Authentication` → `2026-01-21-feat-add-user-authentication-plan.md`
|
||||
- Keep it descriptive (3-5 words after prefix) so plans are findable by context
|
||||
|
||||
**Stakeholder Analysis:**
|
||||
|
||||
- [ ] Identify who will be affected by this issue (end users, developers, operations)
|
||||
- [ ] Consider implementation complexity and required expertise
|
||||
|
||||
**Content Planning:**
|
||||
|
||||
- [ ] Choose appropriate detail level based on issue complexity and audience
|
||||
- [ ] List all necessary sections for the chosen template
|
||||
- [ ] Gather supporting materials (error logs, screenshots, design mockups)
|
||||
- [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists
|
||||
|
||||
### 3. SpecFlow Analysis
|
||||
|
||||
After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification:
|
||||
|
||||
- Task compound-engineering:workflow:spec-flow-analyzer(feature_description, research_findings)
|
||||
|
||||
**SpecFlow Analyzer Output:**
|
||||
|
||||
- [ ] Review SpecFlow analysis results
|
||||
- [ ] Incorporate any identified gaps or edge cases into the issue
|
||||
- [ ] Update acceptance criteria based on SpecFlow findings
|
||||
|
||||
### 4. Choose Implementation Detail Level
|
||||
|
||||
Select how comprehensive you want the issue to be, simpler is mostly better.
|
||||
|
||||
#### 📄 MINIMAL (Quick Issue)
|
||||
|
||||
**Best for:** Simple bugs, small improvements, clear features
|
||||
|
||||
**Includes:**
|
||||
|
||||
- Problem statement or feature description
|
||||
- Basic acceptance criteria
|
||||
- Essential context only
|
||||
|
||||
**Structure:**
|
||||
|
||||
````markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
[Brief problem/feature description]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Core requirement 1
|
||||
- [ ] Core requirement 2
|
||||
|
||||
## Context
|
||||
|
||||
[Any critical information]
|
||||
|
||||
## MVP
|
||||
|
||||
### test.rb
|
||||
|
||||
```ruby
|
||||
class Test
|
||||
def initialize
|
||||
@name = "test"
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## Sources
|
||||
|
||||
- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
|
||||
- Related issue: #[issue_number]
|
||||
- Documentation: [relevant_docs_url]
|
||||
````
|
||||
|
||||
#### 📋 MORE (Standard Issue)
|
||||
|
||||
**Best for:** Most features, complex bugs, team collaboration
|
||||
|
||||
**Includes everything from MINIMAL plus:**
|
||||
|
||||
- Detailed background and motivation
|
||||
- Technical considerations
|
||||
- Success metrics
|
||||
- Dependencies and risks
|
||||
- Basic implementation suggestions
|
||||
|
||||
**Structure:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
## Overview
|
||||
|
||||
[Comprehensive description]
|
||||
|
||||
## Problem Statement / Motivation
|
||||
|
||||
[Why this matters]
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
[High-level approach]
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
- Architecture impacts
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph**: [What callbacks/middleware/observers fire when this runs?]
|
||||
- **Error propagation**: [How do errors flow across layers? Do retry strategies align?]
|
||||
- **State lifecycle risks**: [Can partial failure leave orphaned/inconsistent state?]
|
||||
- **API surface parity**: [What other interfaces expose similar functionality and need the same change?]
|
||||
- **Integration test scenarios**: [Cross-layer scenarios that unit tests won't catch]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Detailed requirement 1
|
||||
- [ ] Detailed requirement 2
|
||||
- [ ] Testing requirements
|
||||
|
||||
## Success Metrics
|
||||
|
||||
[How we measure success]
|
||||
|
||||
## Dependencies & Risks
|
||||
|
||||
[What could block or complicate this]
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
|
||||
- Similar implementations: [file_path:line_number]
|
||||
- Best practices: [documentation_url]
|
||||
- Related PRs: #[pr_number]
|
||||
```
|
||||
|
||||
#### 📚 A LOT (Comprehensive Issue)
|
||||
|
||||
**Best for:** Major features, architectural changes, complex integrations
|
||||
|
||||
**Includes everything from MORE plus:**
|
||||
|
||||
- Detailed implementation plan with phases
|
||||
- Alternative approaches considered
|
||||
- Extensive technical specifications
|
||||
- Resource requirements and timeline
|
||||
- Future considerations and extensibility
|
||||
- Risk mitigation strategies
|
||||
- Documentation requirements
|
||||
|
||||
**Structure:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
## Overview
|
||||
|
||||
[Executive summary]
|
||||
|
||||
## Problem Statement
|
||||
|
||||
[Detailed problem analysis]
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
[Comprehensive solution design]
|
||||
|
||||
## Technical Approach
|
||||
|
||||
### Architecture
|
||||
|
||||
[Detailed technical design]
|
||||
|
||||
### Implementation Phases
|
||||
|
||||
#### Phase 1: [Foundation]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
#### Phase 2: [Core Implementation]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
#### Phase 3: [Polish & Optimization]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
## Alternative Approaches Considered
|
||||
|
||||
[Other solutions evaluated and why rejected]
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
### Interaction Graph
|
||||
|
||||
[Map the chain reaction: what callbacks, middleware, observers, and event handlers fire when this code runs? Trace at least two levels deep. Document: "Action X triggers Y, which calls Z, which persists W."]
|
||||
|
||||
### Error & Failure Propagation
|
||||
|
||||
[Trace errors from lowest layer up. List specific error classes and where they're handled. Identify retry conflicts, unhandled error types, and silent failure swallowing.]
|
||||
|
||||
### State Lifecycle Risks
|
||||
|
||||
[Walk through each step that persists state. Can partial failure orphan rows, duplicate records, or leave caches stale? Document cleanup mechanisms or their absence.]
|
||||
|
||||
### API Surface Parity
|
||||
|
||||
[List all interfaces (classes, DSLs, endpoints) that expose equivalent functionality. Note which need updating and which share the code path.]
|
||||
|
||||
### Integration Test Scenarios
|
||||
|
||||
[3-5 cross-layer test scenarios that unit tests with mocks would never catch. Include expected behavior for each.]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- [ ] Detailed functional criteria
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
- [ ] Performance targets
|
||||
- [ ] Security requirements
|
||||
- [ ] Accessibility standards
|
||||
|
||||
### Quality Gates
|
||||
|
||||
- [ ] Test coverage requirements
|
||||
- [ ] Documentation completeness
|
||||
- [ ] Code review approval
|
||||
|
||||
## Success Metrics
|
||||
|
||||
[Detailed KPIs and measurement methods]
|
||||
|
||||
## Dependencies & Prerequisites
|
||||
|
||||
[Detailed dependency analysis]
|
||||
|
||||
## Risk Analysis & Mitigation
|
||||
|
||||
[Comprehensive risk assessment]
|
||||
|
||||
## Resource Requirements
|
||||
|
||||
[Team, time, infrastructure needs]
|
||||
|
||||
## Future Considerations
|
||||
|
||||
[Extensibility and long-term vision]
|
||||
|
||||
## Documentation Plan
|
||||
|
||||
[What docs need updating]
|
||||
|
||||
## Sources & References
|
||||
|
||||
### Origin
|
||||
|
||||
- **Brainstorm document:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm. Key decisions carried forward: [list 2-3 major decisions from brainstorm]
|
||||
|
||||
### Internal References
|
||||
|
||||
- Architecture decisions: [file_path:line_number]
|
||||
- Similar features: [file_path:line_number]
|
||||
- Configuration: [file_path:line_number]
|
||||
|
||||
### External References
|
||||
|
||||
- Framework documentation: [url]
|
||||
- Best practices guide: [url]
|
||||
- Industry standards: [url]
|
||||
|
||||
### Related Work
|
||||
|
||||
- Previous PRs: #[pr_numbers]
|
||||
- Related issues: #[issue_numbers]
|
||||
- Design documents: [links]
|
||||
```
|
||||
|
||||
### 5. Issue Creation & Formatting
|
||||
|
||||
<thinking>
|
||||
Apply best practices for clarity and actionability, making the issue easy to scan and understand
|
||||
</thinking>
|
||||
|
||||
**Content Formatting:**
|
||||
|
||||
- [ ] Use clear, descriptive headings with proper hierarchy (##, ###)
|
||||
- [ ] Include code examples in triple backticks with language syntax highlighting
|
||||
- [ ] Add screenshots/mockups if UI-related (drag & drop or use image hosting)
|
||||
- [ ] Use task lists (- [ ]) for trackable items that can be checked off
|
||||
- [ ] Add collapsible sections for lengthy logs or optional details using `<details>` tags
|
||||
- [ ] Apply appropriate emoji for visual scanning (🐛 bug, ✨ feature, 📚 docs, ♻️ refactor)
|
||||
|
||||
**Cross-Referencing:**
|
||||
|
||||
- [ ] Link to related issues/PRs using #number format
|
||||
- [ ] Reference specific commits with SHA hashes when relevant
|
||||
- [ ] Link to code using GitHub's permalink feature (press 'y' for permanent link)
|
||||
- [ ] Mention relevant team members with @username if needed
|
||||
- [ ] Add links to external resources with descriptive text
|
||||
|
||||
**Code & Examples:**
|
||||
|
||||
````markdown
|
||||
# Good example with syntax highlighting and line references
|
||||
|
||||
|
||||
```ruby
|
||||
# app/services/user_service.rb:42
|
||||
def process_user(user)
|
||||
|
||||
# Implementation here
|
||||
|
||||
end
|
||||
```
|
||||
|
||||
# Collapsible error logs
|
||||
|
||||
<details>
|
||||
<summary>Full error stacktrace</summary>
|
||||
|
||||
`Error details here...`
|
||||
|
||||
</details>
|
||||
````
|
||||
|
||||
**AI-Era Considerations:**
|
||||
|
||||
- [ ] Account for accelerated development with AI pair programming
|
||||
- [ ] Include prompts or instructions that worked well during research
|
||||
- [ ] Note which AI tools were used for initial exploration (Claude, Copilot, etc.)
|
||||
- [ ] Emphasize comprehensive testing given rapid implementation
|
||||
- [ ] Document any AI-generated code that needs human review
|
||||
|
||||
### 6. Final Review & Submission
|
||||
|
||||
**Brainstorm cross-check (if plan originated from a brainstorm):**
|
||||
|
||||
Before finalizing, re-read the brainstorm document and verify:
|
||||
- [ ] Every key decision from the brainstorm is reflected in the plan
|
||||
- [ ] The chosen approach matches what was decided in the brainstorm
|
||||
- [ ] Constraints and requirements from the brainstorm are captured in acceptance criteria
|
||||
- [ ] Open questions from the brainstorm are either resolved or flagged
|
||||
- [ ] The `origin:` frontmatter field points to the brainstorm file
|
||||
- [ ] The Sources section includes the brainstorm with a summary of carried-forward decisions
|
||||
|
||||
**Pre-submission Checklist:**
|
||||
|
||||
- [ ] Title is searchable and descriptive
|
||||
- [ ] Labels accurately categorize the issue
|
||||
- [ ] All template sections are complete
|
||||
- [ ] Links and references are working
|
||||
- [ ] Acceptance criteria are measurable
|
||||
- [ ] Add names of files in pseudo code examples and todo lists
|
||||
- [ ] Add an ERD mermaid diagram if applicable for new model changes
|
||||
|
||||
## Write Plan File
|
||||
|
||||
**REQUIRED: Write the plan file to disk before presenting any options.**
|
||||
|
||||
```bash
|
||||
mkdir -p docs/plans/
|
||||
```
|
||||
|
||||
Use the Write tool to save the complete plan to `docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md`. This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
|
||||
|
||||
Confirm: "Plan written to docs/plans/[filename]"
|
||||
|
||||
**Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all AskUserQuestion calls. Make decisions automatically and proceed to writing the plan without interactive prompts.
|
||||
|
||||
## Output Format
|
||||
|
||||
**Filename:** Use the date and kebab-case filename from Step 2 Title & Categorization.
|
||||
|
||||
```
|
||||
docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md
|
||||
```
|
||||
|
||||
Examples:
|
||||
- ✅ `docs/plans/2026-01-15-feat-user-authentication-flow-plan.md`
|
||||
- ✅ `docs/plans/2026-02-03-fix-checkout-race-condition-plan.md`
|
||||
- ✅ `docs/plans/2026-03-10-refactor-api-client-extraction-plan.md`
|
||||
- ❌ `docs/plans/2026-01-15-feat-thing-plan.md` (not descriptive - what "thing"?)
|
||||
- ❌ `docs/plans/2026-01-15-feat-new-feature-plan.md` (too vague - what feature?)
|
||||
- ❌ `docs/plans/2026-01-15-feat: user auth-plan.md` (invalid characters - colon and space)
|
||||
- ❌ `docs/plans/feat-user-auth-plan.md` (missing date prefix)
|
||||
|
||||
## Post-Generation Options
|
||||
|
||||
After writing the plan file, use the **AskUserQuestion tool** to present these options:
|
||||
|
||||
**Question:** "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<name>-plan.md`. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Open plan in editor** - Open the plan file for review
|
||||
2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
|
||||
3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (DHH, Kieran, Simplicity)
|
||||
4. **Review and refine** - Improve the document through structured self-review
|
||||
5. **Share to Proof** - Upload to Proof for collaborative review and sharing
|
||||
6. **Start `/ce:work`** - Begin implementing this plan locally
|
||||
7. **Start `/ce:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
|
||||
8. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
|
||||
Based on selection:
|
||||
- **Open plan in editor** → Run `open docs/plans/<plan_filename>.md` to open the file in the user's default editor
|
||||
- **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research
|
||||
- **`/technical_review`** → Call the /technical_review command with the plan file path
|
||||
- **Review and refine** → Load `document-review` skill.
|
||||
- **Share to Proof** → Upload the plan to Proof:
|
||||
```bash
|
||||
CONTENT=$(cat docs/plans/<plan_filename>.md)
|
||||
TITLE="Plan: <plan title from frontmatter>"
|
||||
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
|
||||
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
||||
```
|
||||
Display: `View & collaborate in Proof: <PROOF_URL>` — skip silently if curl fails. Then return to options.
|
||||
- **`/ce:work`** → Call the /ce:work command with the plan file path
|
||||
- **`/ce:work` on remote** → Run `/ce:work docs/plans/<plan_filename>.md &` to start work in background for Claude Code web
|
||||
- **Create Issue** → See "Issue Creation" section below
|
||||
- **Other** (automatically provided) → Accept free text for rework or specific changes
|
||||
|
||||
**Note:** If running `/ce:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
|
||||
|
||||
Loop back to options after Simplify or Other changes until user selects `/ce:work` or `/technical_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:**
|
||||
|
||||
Use the title and type from Step 2 (already in context - no need to re-read the file):
|
||||
|
||||
```bash
|
||||
gh issue create --title "<type>: <title>" --body-file <plan_path>
|
||||
```
|
||||
|
||||
3. **If Linear:**
|
||||
|
||||
```bash
|
||||
linear issue create --title "<title>" --description "$(cat <plan_path>)"
|
||||
```
|
||||
|
||||
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 `/ce:work` or `/technical_review`
|
||||
|
||||
NEVER CODE! Just research and write the plan.
|
||||
525
plugins/compound-engineering/commands/ce/review.md
Normal file
525
plugins/compound-engineering/commands/ce/review.md
Normal file
@@ -0,0 +1,525 @@
|
||||
---
|
||||
name: ce:review
|
||||
description: Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees
|
||||
argument-hint: "[PR number, GitHub URL, branch name, or latest]"
|
||||
---
|
||||
|
||||
# Review Command
|
||||
|
||||
<command_purpose> Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and Git worktrees for deep local inspection. </command_purpose>
|
||||
|
||||
## Introduction
|
||||
|
||||
<role>Senior Code Review Architect with expertise in security, performance, architecture, and quality assurance</role>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<requirements>
|
||||
- Git repository with GitHub CLI (`gh`) installed and authenticated
|
||||
- Clean main/master branch
|
||||
- Proper permissions to create worktrees and access the repository
|
||||
- For document reviews: Path to a markdown file or document
|
||||
</requirements>
|
||||
|
||||
## Main Tasks
|
||||
|
||||
### 1. Determine Review Target & Setup (ALWAYS FIRST)
|
||||
|
||||
<review_target> #$ARGUMENTS </review_target>
|
||||
|
||||
<thinking>
|
||||
First, I need to determine the review target type and set up the code for analysis.
|
||||
</thinking>
|
||||
|
||||
#### Immediate Actions:
|
||||
|
||||
<task_list>
|
||||
|
||||
- [ ] Determine review type: PR number (numeric), GitHub URL, file path (.md), or empty (current branch)
|
||||
- [ ] Check current git branch
|
||||
- [ ] If ALREADY on the target branch (PR branch, requested branch name, or the branch already checked out for review) → proceed with analysis on current branch
|
||||
- [ ] If DIFFERENT branch than the review target → offer to use worktree: "Use git-worktree skill for isolated Call `skill: git-worktree` with branch name"
|
||||
- [ ] Fetch PR metadata using `gh pr view --json` for title, body, files, linked issues
|
||||
- [ ] Set up language-specific analysis tools
|
||||
- [ ] Prepare security scanning environment
|
||||
- [ ] Make sure we are on the branch we are reviewing. Use gh pr checkout to switch to the branch or manually checkout the branch.
|
||||
|
||||
Ensure that the code is ready for analysis (either in worktree or on current branch). ONLY then proceed to the next step.
|
||||
|
||||
</task_list>
|
||||
|
||||
#### Protected Artifacts
|
||||
|
||||
<protected_artifacts>
|
||||
The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
|
||||
|
||||
- `docs/plans/*.md` — Plan files created by `/ce:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/ce:work`).
|
||||
- `docs/solutions/*.md` — Solution documents created during the pipeline.
|
||||
|
||||
If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.
|
||||
</protected_artifacts>
|
||||
|
||||
#### Load Review Agents
|
||||
|
||||
Read `compound-engineering.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
|
||||
|
||||
If no settings file exists, invoke the `setup` skill to create one. Then read the newly created file and continue.
|
||||
|
||||
#### Parallel Agents to review the PR:
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Run all configured review agents in parallel using Task tool. For each agent in the `review_agents` list:
|
||||
|
||||
```
|
||||
Task {agent-name}(PR content + review context from settings body)
|
||||
```
|
||||
|
||||
Additionally, always run these regardless of settings:
|
||||
- Task agent-native-reviewer(PR content) - Verify new features are agent-accessible
|
||||
- Task learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
#### Conditional Agents (Run if applicable):
|
||||
|
||||
<conditional_agents>
|
||||
|
||||
These agents are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:
|
||||
|
||||
**MIGRATIONS: If PR contains database migrations, schema.rb, or data backfills:**
|
||||
|
||||
- Task schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
|
||||
- Task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
|
||||
- Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
|
||||
|
||||
**When to run:**
|
||||
- PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
|
||||
- PR modifies columns that store IDs, enums, or mappings
|
||||
- PR includes data backfill scripts or rake tasks
|
||||
- PR title/body mentions: migration, backfill, data transformation, ID mapping
|
||||
|
||||
**What these agents check:**
|
||||
- `schema-drift-detector`: Cross-references schema.rb changes against PR migrations to catch unrelated columns/indexes from local database state
|
||||
- `data-migration-expert`: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns
|
||||
- `deployment-verification-agent`: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans
|
||||
|
||||
</conditional_agents>
|
||||
|
||||
### 2. Ultra-Thinking Deep Dive Phases
|
||||
|
||||
<ultrathink_instruction> For each phase below, spend maximum cognitive effort. Think step by step. Consider all angles. Question assumptions. And bring all reviews in a synthesis to the user.</ultrathink_instruction>
|
||||
|
||||
<deliverable>
|
||||
Complete system context map with component interactions
|
||||
</deliverable>
|
||||
|
||||
#### Phase 1: Stakeholder Perspective Analysis
|
||||
|
||||
<thinking_prompt> ULTRA-THINK: Put yourself in each stakeholder's shoes. What matters to them? What are their pain points? </thinking_prompt>
|
||||
|
||||
<stakeholder_perspectives>
|
||||
|
||||
1. **Developer Perspective** <questions>
|
||||
|
||||
- How easy is this to understand and modify?
|
||||
- Are the APIs intuitive?
|
||||
- Is debugging straightforward?
|
||||
- Can I test this easily? </questions>
|
||||
|
||||
2. **Operations Perspective** <questions>
|
||||
|
||||
- How do I deploy this safely?
|
||||
- What metrics and logs are available?
|
||||
- How do I troubleshoot issues?
|
||||
- What are the resource requirements? </questions>
|
||||
|
||||
3. **End User Perspective** <questions>
|
||||
|
||||
- Is the feature intuitive?
|
||||
- Are error messages helpful?
|
||||
- Is performance acceptable?
|
||||
- Does it solve my problem? </questions>
|
||||
|
||||
4. **Security Team Perspective** <questions>
|
||||
|
||||
- What's the attack surface?
|
||||
- Are there compliance requirements?
|
||||
- How is data protected?
|
||||
- What are the audit capabilities? </questions>
|
||||
|
||||
5. **Business Perspective** <questions>
|
||||
- What's the ROI?
|
||||
- Are there legal/compliance risks?
|
||||
- How does this affect time-to-market?
|
||||
- What's the total cost of ownership? </questions> </stakeholder_perspectives>
|
||||
|
||||
#### Phase 2: Scenario Exploration
|
||||
|
||||
<thinking_prompt> ULTRA-THINK: Explore edge cases and failure scenarios. What could go wrong? How does the system behave under stress? </thinking_prompt>
|
||||
|
||||
<scenario_checklist>
|
||||
|
||||
- [ ] **Happy Path**: Normal operation with valid inputs
|
||||
- [ ] **Invalid Inputs**: Null, empty, malformed data
|
||||
- [ ] **Boundary Conditions**: Min/max values, empty collections
|
||||
- [ ] **Concurrent Access**: Race conditions, deadlocks
|
||||
- [ ] **Scale Testing**: 10x, 100x, 1000x normal load
|
||||
- [ ] **Network Issues**: Timeouts, partial failures
|
||||
- [ ] **Resource Exhaustion**: Memory, disk, connections
|
||||
- [ ] **Security Attacks**: Injection, overflow, DoS
|
||||
- [ ] **Data Corruption**: Partial writes, inconsistency
|
||||
- [ ] **Cascading Failures**: Downstream service issues </scenario_checklist>
|
||||
|
||||
### 3. Multi-Angle Review Perspectives
|
||||
|
||||
#### Technical Excellence Angle
|
||||
|
||||
- Code craftsmanship evaluation
|
||||
- Engineering best practices
|
||||
- Technical documentation quality
|
||||
- Tooling and automation assessment
|
||||
|
||||
#### Business Value Angle
|
||||
|
||||
- Feature completeness validation
|
||||
- Performance impact on users
|
||||
- Cost-benefit analysis
|
||||
- Time-to-market considerations
|
||||
|
||||
#### Risk Management Angle
|
||||
|
||||
- Security risk assessment
|
||||
- Operational risk evaluation
|
||||
- Compliance risk verification
|
||||
- Technical debt accumulation
|
||||
|
||||
#### Team Dynamics Angle
|
||||
|
||||
- Code review etiquette
|
||||
- Knowledge sharing effectiveness
|
||||
- Collaboration patterns
|
||||
- Mentoring opportunities
|
||||
|
||||
### 4. Simplification and Minimalism Review
|
||||
|
||||
Run the Task code-simplicity-reviewer() to see if we can simplify the code.
|
||||
|
||||
### 5. Findings Synthesis and Todo Creation Using file-todos Skill
|
||||
|
||||
<critical_requirement> ALL findings MUST be stored in the todos/ directory using the file-todos skill. Create todo files immediately after synthesis - do NOT present findings for user approval first. Use the skill for structured todo management. </critical_requirement>
|
||||
|
||||
#### Step 1: Synthesize All Findings
|
||||
|
||||
<thinking>
|
||||
Consolidate all agent reports into a categorized list of findings.
|
||||
Remove duplicates, prioritize by severity and impact.
|
||||
</thinking>
|
||||
|
||||
<synthesis_tasks>
|
||||
|
||||
- [ ] Collect findings from all parallel agents
|
||||
- [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
|
||||
- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above)
|
||||
- [ ] Categorize by type: security, performance, architecture, quality, etc.
|
||||
- [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
|
||||
- [ ] Remove duplicate or overlapping findings
|
||||
- [ ] Estimate effort for each finding (Small/Medium/Large)
|
||||
|
||||
</synthesis_tasks>
|
||||
|
||||
#### Step 2: Create Todo Files Using file-todos Skill
|
||||
|
||||
<critical_instruction> Use the file-todos skill to create todo files for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all todo files in parallel using the skill, then summarize results to user. </critical_instruction>
|
||||
|
||||
**Implementation Options:**
|
||||
|
||||
**Option A: Direct File Creation (Fast)**
|
||||
|
||||
- Create todo files directly using Write tool
|
||||
- All findings in parallel for speed
|
||||
- Use standard template from `.claude/skills/file-todos/assets/todo-template.md`
|
||||
- Follow naming convention: `{issue_id}-pending-{priority}-{description}.md`
|
||||
|
||||
**Option B: Sub-Agents in Parallel (Recommended for Scale)** For large PRs with 15+ findings, use sub-agents to create finding files in parallel:
|
||||
|
||||
```bash
|
||||
# Launch multiple finding-creator agents in parallel
|
||||
Task() - Create todos for first finding
|
||||
Task() - Create todos for second finding
|
||||
Task() - Create todos for third finding
|
||||
etc. for each finding.
|
||||
```
|
||||
|
||||
Sub-agents can:
|
||||
|
||||
- Process multiple findings simultaneously
|
||||
- Write detailed todo files with all sections filled
|
||||
- Organize findings by severity
|
||||
- Create comprehensive Proposed Solutions
|
||||
- Add acceptance criteria and work logs
|
||||
- Complete much faster than sequential processing
|
||||
|
||||
**Execution Strategy:**
|
||||
|
||||
1. Synthesize all findings into categories (P1/P2/P3)
|
||||
2. Group findings by severity
|
||||
3. Launch 3 parallel sub-agents (one per severity level)
|
||||
4. Each sub-agent creates its batch of todos using the file-todos skill
|
||||
5. Consolidate results and present summary
|
||||
|
||||
**Process (Using file-todos Skill):**
|
||||
|
||||
1. For each finding:
|
||||
|
||||
- Determine severity (P1/P2/P3)
|
||||
- Write detailed Problem Statement and Findings
|
||||
- Create 2-3 Proposed Solutions with pros/cons/effort/risk
|
||||
- Estimate effort (Small/Medium/Large)
|
||||
- Add acceptance criteria and work log
|
||||
|
||||
2. Use file-todos skill for structured todo management:
|
||||
|
||||
```bash
|
||||
skill: file-todos
|
||||
```
|
||||
|
||||
The skill provides:
|
||||
|
||||
- Template location: `.claude/skills/file-todos/assets/todo-template.md`
|
||||
- Naming convention: `{issue_id}-{status}-{priority}-{description}.md`
|
||||
- YAML frontmatter structure: status, priority, issue_id, tags, dependencies
|
||||
- All required sections: Problem Statement, Findings, Solutions, etc.
|
||||
|
||||
3. Create todo files in parallel:
|
||||
|
||||
```bash
|
||||
{next_id}-pending-{priority}-{description}.md
|
||||
```
|
||||
|
||||
4. Examples:
|
||||
|
||||
```
|
||||
001-pending-p1-path-traversal-vulnerability.md
|
||||
002-pending-p1-api-response-validation.md
|
||||
003-pending-p2-concurrency-limit.md
|
||||
004-pending-p3-unused-parameter.md
|
||||
```
|
||||
|
||||
5. Follow template structure from file-todos skill: `.claude/skills/file-todos/assets/todo-template.md`
|
||||
|
||||
**Todo File Structure (from template):**
|
||||
|
||||
Each todo must include:
|
||||
|
||||
- **YAML frontmatter**: status, priority, issue_id, tags, dependencies
|
||||
- **Problem Statement**: What's broken/missing, why it matters
|
||||
- **Findings**: Discoveries from agents with evidence/location
|
||||
- **Proposed Solutions**: 2-3 options, each with pros/cons/effort/risk
|
||||
- **Recommended Action**: (Filled during triage, leave blank initially)
|
||||
- **Technical Details**: Affected files, components, database changes
|
||||
- **Acceptance Criteria**: Testable checklist items
|
||||
- **Work Log**: Dated record with actions and learnings
|
||||
- **Resources**: Links to PR, issues, documentation, similar patterns
|
||||
|
||||
**File naming convention:**
|
||||
|
||||
```
|
||||
{issue_id}-{status}-{priority}-{description}.md
|
||||
|
||||
Examples:
|
||||
- 001-pending-p1-security-vulnerability.md
|
||||
- 002-pending-p2-performance-optimization.md
|
||||
- 003-pending-p3-code-cleanup.md
|
||||
```
|
||||
|
||||
**Status values:**
|
||||
|
||||
- `pending` - New findings, needs triage/decision
|
||||
- `ready` - Approved by manager, ready to work
|
||||
- `complete` - Work finished
|
||||
|
||||
**Priority values:**
|
||||
|
||||
- `p1` - Critical (blocks merge, security/data issues)
|
||||
- `p2` - Important (should fix, architectural/performance)
|
||||
- `p3` - Nice-to-have (enhancements, cleanup)
|
||||
|
||||
**Tagging:** Always add `code-review` tag, plus: `security`, `performance`, `architecture`, `rails`, `quality`, etc.
|
||||
|
||||
#### Step 3: Summary Report
|
||||
|
||||
After creating all todo files, present comprehensive summary:
|
||||
|
||||
````markdown
|
||||
## ✅ Code Review Complete
|
||||
|
||||
**Review Target:** PR #XXXX - [PR Title] **Branch:** [branch-name]
|
||||
|
||||
### Findings Summary:
|
||||
|
||||
- **Total Findings:** [X]
|
||||
- **🔴 CRITICAL (P1):** [count] - BLOCKS MERGE
|
||||
- **🟡 IMPORTANT (P2):** [count] - Should Fix
|
||||
- **🔵 NICE-TO-HAVE (P3):** [count] - Enhancements
|
||||
|
||||
### Created Todo Files:
|
||||
|
||||
**P1 - Critical (BLOCKS MERGE):**
|
||||
|
||||
- `001-pending-p1-{finding}.md` - {description}
|
||||
- `002-pending-p1-{finding}.md` - {description}
|
||||
|
||||
**P2 - Important:**
|
||||
|
||||
- `003-pending-p2-{finding}.md` - {description}
|
||||
- `004-pending-p2-{finding}.md` - {description}
|
||||
|
||||
**P3 - Nice-to-Have:**
|
||||
|
||||
- `005-pending-p3-{finding}.md` - {description}
|
||||
|
||||
### Review Agents Used:
|
||||
|
||||
- kieran-rails-reviewer
|
||||
- security-sentinel
|
||||
- performance-oracle
|
||||
- architecture-strategist
|
||||
- agent-native-reviewer
|
||||
- [other agents]
|
||||
|
||||
### Next Steps:
|
||||
|
||||
1. **Address P1 Findings**: CRITICAL - must be fixed before merge
|
||||
|
||||
- Review each P1 todo in detail
|
||||
- Implement fixes or request exemption
|
||||
- Verify fixes before merging PR
|
||||
|
||||
2. **Triage All Todos**:
|
||||
```bash
|
||||
ls todos/*-pending-*.md # View all pending todos
|
||||
/triage # Use slash command for interactive triage
|
||||
```
|
||||
|
||||
3. **Work on Approved Todos**:
|
||||
|
||||
```bash
|
||||
/resolve_todo_parallel # Fix all approved items efficiently
|
||||
```
|
||||
|
||||
4. **Track Progress**:
|
||||
- Rename file when status changes: pending → ready → complete
|
||||
- Update Work Log as you work
|
||||
- Commit todos: `git add todos/ && git commit -m "refactor: add code review findings"`
|
||||
|
||||
### Severity Breakdown:
|
||||
|
||||
**🔴 P1 (Critical - Blocks Merge):**
|
||||
|
||||
- Security vulnerabilities
|
||||
- Data corruption risks
|
||||
- Breaking changes
|
||||
- Critical architectural issues
|
||||
|
||||
**🟡 P2 (Important - Should Fix):**
|
||||
|
||||
- Performance issues
|
||||
- Significant architectural concerns
|
||||
- Major code quality problems
|
||||
- Reliability issues
|
||||
|
||||
**🔵 P3 (Nice-to-Have):**
|
||||
|
||||
- Minor improvements
|
||||
- Code cleanup
|
||||
- Optimization opportunities
|
||||
- Documentation updates
|
||||
````
|
||||
|
||||
### 6. End-to-End Testing (Optional)
|
||||
|
||||
<detect_project_type>
|
||||
|
||||
**First, detect the project type from PR files:**
|
||||
|
||||
| Indicator | Project Type |
|
||||
|-----------|--------------|
|
||||
| `*.xcodeproj`, `*.xcworkspace`, `Package.swift` (iOS) | iOS/macOS |
|
||||
| `Gemfile`, `package.json`, `app/views/*`, `*.html.*` | Web |
|
||||
| Both iOS files AND web files | Hybrid (test both) |
|
||||
|
||||
</detect_project_type>
|
||||
|
||||
<offer_testing>
|
||||
|
||||
After presenting the Summary Report, offer appropriate testing based on project type:
|
||||
|
||||
**For Web Projects:**
|
||||
```markdown
|
||||
**"Want to run browser tests on the affected pages?"**
|
||||
1. Yes - run `/test-browser`
|
||||
2. No - skip
|
||||
```
|
||||
|
||||
**For iOS Projects:**
|
||||
```markdown
|
||||
**"Want to run Xcode simulator tests on the app?"**
|
||||
1. Yes - run `/xcode-test`
|
||||
2. No - skip
|
||||
```
|
||||
|
||||
**For Hybrid Projects (e.g., Rails + Hotwire Native):**
|
||||
```markdown
|
||||
**"Want to run end-to-end tests?"**
|
||||
1. Web only - run `/test-browser`
|
||||
2. iOS only - run `/xcode-test`
|
||||
3. Both - run both commands
|
||||
4. No - skip
|
||||
```
|
||||
|
||||
</offer_testing>
|
||||
|
||||
#### If User Accepts Web Testing:
|
||||
|
||||
Spawn a subagent to run browser tests (preserves main context):
|
||||
|
||||
```
|
||||
Task general-purpose("Run /test-browser for PR #[number]. Test all affected pages, check for console errors, handle failures by creating todos and fixing.")
|
||||
```
|
||||
|
||||
The subagent will:
|
||||
1. Identify pages affected by the PR
|
||||
2. Navigate to each page and capture snapshots (using Playwright MCP or agent-browser CLI)
|
||||
3. Check for console errors
|
||||
4. Test critical interactions
|
||||
5. Pause for human verification on OAuth/email/payment flows
|
||||
6. Create P1 todos for any failures
|
||||
7. Fix and retry until all tests pass
|
||||
|
||||
**Standalone:** `/test-browser [PR number]`
|
||||
|
||||
#### If User Accepts iOS Testing:
|
||||
|
||||
Spawn a subagent to run Xcode tests (preserves main context):
|
||||
|
||||
```
|
||||
Task general-purpose("Run /xcode-test for scheme [name]. Build for simulator, install, launch, take screenshots, check for crashes.")
|
||||
```
|
||||
|
||||
The subagent will:
|
||||
1. Verify XcodeBuildMCP is installed
|
||||
2. Discover project and schemes
|
||||
3. Build for iOS Simulator
|
||||
4. Install and launch app
|
||||
5. Take screenshots of key screens
|
||||
6. Capture console logs for errors
|
||||
7. Pause for human verification (Sign in with Apple, push, IAP)
|
||||
8. Create P1 todos for any failures
|
||||
9. Fix and retry until all tests pass
|
||||
|
||||
**Standalone:** `/xcode-test [scheme]`
|
||||
|
||||
### Important: P1 Findings Block Merge
|
||||
|
||||
Any **🔴 P1 (CRITICAL)** findings must be addressed before merging the PR. Present these prominently and ensure they're resolved before accepting the PR.
|
||||
470
plugins/compound-engineering/commands/ce/work.md
Normal file
470
plugins/compound-engineering/commands/ce/work.md
Normal file
@@ -0,0 +1,470 @@
|
||||
---
|
||||
name: ce:work
|
||||
description: Execute work plans efficiently while maintaining quality and finishing features
|
||||
argument-hint: "[plan file, specification, or todo file path]"
|
||||
---
|
||||
|
||||
# Work Plan Execution Command
|
||||
|
||||
Execute a work plan efficiently while maintaining quality and finishing features.
|
||||
|
||||
## Introduction
|
||||
|
||||
This command takes a work document (plan, specification, or todo file) and executes it systematically. The focus is on **shipping complete features** by understanding requirements quickly, following existing patterns, and maintaining quality throughout.
|
||||
|
||||
## Input Document
|
||||
|
||||
<input_document> #$ARGUMENTS </input_document>
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
### Phase 1: Quick Start
|
||||
|
||||
1. **Read Plan and Clarify**
|
||||
|
||||
- Read the work document completely
|
||||
- Review any references or links provided in the plan
|
||||
- If anything is unclear or ambiguous, ask clarifying questions now
|
||||
- Get user approval to proceed
|
||||
- **Do not skip this** - better to ask questions now than build the wrong thing
|
||||
|
||||
2. **Setup Environment**
|
||||
|
||||
First, check the current branch:
|
||||
|
||||
```bash
|
||||
current_branch=$(git branch --show-current)
|
||||
default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
|
||||
|
||||
# Fallback if remote HEAD isn't set
|
||||
if [ -z "$default_branch" ]; then
|
||||
default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
|
||||
fi
|
||||
```
|
||||
|
||||
**If already on a feature branch** (not the default branch):
|
||||
- Ask: "Continue working on `[current_branch]`, or create a new branch?"
|
||||
- If continuing, proceed to step 3
|
||||
- If creating new, follow Option A or B below
|
||||
|
||||
**If on the default branch**, choose how to proceed:
|
||||
|
||||
**Option A: Create a new branch**
|
||||
```bash
|
||||
git pull origin [default_branch]
|
||||
git checkout -b feature-branch-name
|
||||
```
|
||||
Use a meaningful name based on the work (e.g., `feat/user-authentication`, `fix/email-validation`).
|
||||
|
||||
**Option B: Use a worktree (recommended for parallel development)**
|
||||
```bash
|
||||
skill: git-worktree
|
||||
# The skill will create a new branch from the default branch in an isolated worktree
|
||||
```
|
||||
|
||||
**Option C: Continue on the default branch**
|
||||
- Requires explicit user confirmation
|
||||
- Only proceed after user explicitly says "yes, commit to [default_branch]"
|
||||
- Never commit directly to the default branch without explicit permission
|
||||
|
||||
**Recommendation**: Use worktree if:
|
||||
- You want to work on multiple features simultaneously
|
||||
- You want to keep the default branch clean while experimenting
|
||||
- You plan to switch between branches frequently
|
||||
|
||||
3. **Create Todo List**
|
||||
- Use TodoWrite to break plan into actionable tasks
|
||||
- Include dependencies between tasks
|
||||
- Prioritize based on what needs to be done first
|
||||
- Include testing and quality check tasks
|
||||
- Keep tasks specific and completable
|
||||
|
||||
### Phase 2: Execute
|
||||
|
||||
1. **Task Execution Loop**
|
||||
|
||||
For each task in priority order:
|
||||
|
||||
```
|
||||
while (tasks remain):
|
||||
- Mark task as in_progress in TodoWrite
|
||||
- Read any referenced files from the plan
|
||||
- Look for similar patterns in codebase
|
||||
- Implement following existing conventions
|
||||
- Write tests for new functionality
|
||||
- Run System-Wide Test Check (see below)
|
||||
- Run tests after changes
|
||||
- Mark task as completed in TodoWrite
|
||||
- Mark off the corresponding checkbox in the plan file ([ ] → [x])
|
||||
- Evaluate for incremental commit (see below)
|
||||
```
|
||||
|
||||
**System-Wide Test Check** — Before marking a task done, pause and ask:
|
||||
|
||||
| Question | What to do |
|
||||
|----------|------------|
|
||||
| **What fires when this runs?** Callbacks, middleware, observers, event handlers — trace two levels out from your change. | Read the actual code (not docs) for callbacks on models you touch, middleware in the request chain, `after_*` hooks. |
|
||||
| **Do my tests exercise the real chain?** If every dependency is mocked, the test proves your logic works *in isolation* — it says nothing about the interaction. | Write at least one integration test that uses real objects through the full callback/middleware chain. No mocks for the layers that interact. |
|
||||
| **Can failure leave orphaned state?** If your code persists state (DB row, cache, file) before calling an external service, what happens when the service fails? Does retry create duplicates? | Trace the failure path with real objects. If state is created before the risky call, test that failure cleans up or that retry is idempotent. |
|
||||
| **What other interfaces expose this?** Mixins, DSLs, alternative entry points (Agent vs Chat vs ChatMethods). | Grep for the method/behavior in related classes. If parity is needed, add it now — not as a follow-up. |
|
||||
| **Do error strategies align across layers?** Retry middleware + application fallback + framework error handling — do they conflict or create double execution? | List the specific error classes at each layer. Verify your rescue list matches what the lower layer actually raises. |
|
||||
|
||||
**When to skip:** Leaf-node changes with no callbacks, no state persistence, no parallel interfaces. If the change is purely additive (new helper method, new view partial), the check takes 10 seconds and the answer is "nothing fires, skip."
|
||||
|
||||
**When this matters most:** Any change that touches models with callbacks, error handling with fallback/retry, or functionality exposed through multiple interfaces.
|
||||
|
||||
**IMPORTANT**: Always update the original plan document by checking off completed items. Use the Edit tool to change `- [ ]` to `- [x]` for each task you finish. This keeps the plan as a living document showing progress and ensures no checkboxes are left unchecked.
|
||||
|
||||
2. **Incremental Commits**
|
||||
|
||||
After completing each task, evaluate whether to create an incremental commit:
|
||||
|
||||
| Commit when... | Don't commit when... |
|
||||
|----------------|---------------------|
|
||||
| Logical unit complete (model, service, component) | Small part of a larger unit |
|
||||
| Tests pass + meaningful progress | Tests failing |
|
||||
| About to switch contexts (backend → frontend) | Purely scaffolding with no behavior |
|
||||
| About to attempt risky/uncertain changes | Would need a "WIP" commit message |
|
||||
|
||||
**Heuristic:** "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."
|
||||
|
||||
**Commit workflow:**
|
||||
```bash
|
||||
# 1. Verify tests pass (use project's test command)
|
||||
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
||||
|
||||
# 2. Stage only files related to this logical unit (not `git add .`)
|
||||
git add <files related to this logical unit>
|
||||
|
||||
# 3. Commit with conventional message
|
||||
git commit -m "feat(scope): description of this unit"
|
||||
```
|
||||
|
||||
**Handling merge conflicts:** If conflicts arise during rebasing or merging, resolve them immediately. Incremental commits make conflict resolution easier since each commit is small and focused.
|
||||
|
||||
**Note:** Incremental commits use clean conventional messages without attribution footers. The final Phase 4 commit/PR includes the full attribution.
|
||||
|
||||
3. **Follow Existing Patterns**
|
||||
|
||||
- The plan should reference similar code - read those files first
|
||||
- Match naming conventions exactly
|
||||
- Reuse existing components where possible
|
||||
- Follow project coding standards (see CLAUDE.md)
|
||||
- When in doubt, grep for similar implementations
|
||||
|
||||
4. **Test Continuously**
|
||||
|
||||
- Run relevant tests after each significant change
|
||||
- Don't wait until the end to test
|
||||
- Fix failures immediately
|
||||
- Add new tests for new functionality
|
||||
- **Unit tests with mocks prove logic in isolation. Integration tests with real objects prove the layers work together.** If your change touches callbacks, middleware, or error handling — you need both.
|
||||
|
||||
5. **Figma Design Sync** (if applicable)
|
||||
|
||||
For UI work with Figma designs:
|
||||
|
||||
- Implement components following design specs
|
||||
- Use figma-design-sync agent iteratively to compare
|
||||
- Fix visual differences identified
|
||||
- Repeat until implementation matches design
|
||||
|
||||
6. **Track Progress**
|
||||
- Keep TodoWrite updated as you complete tasks
|
||||
- Note any blockers or unexpected discoveries
|
||||
- Create new tasks if scope expands
|
||||
- Keep user informed of major milestones
|
||||
|
||||
### Phase 3: Quality Check
|
||||
|
||||
1. **Run Core Quality Checks**
|
||||
|
||||
Always run before submitting:
|
||||
|
||||
```bash
|
||||
# Run full test suite (use project's test command)
|
||||
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
||||
|
||||
# Run linting (per CLAUDE.md)
|
||||
# Use linting-agent before pushing to origin
|
||||
```
|
||||
|
||||
2. **Consider Reviewer Agents** (Optional)
|
||||
|
||||
Use for complex, risky, or large changes. Read agents from `compound-engineering.local.md` frontmatter (`review_agents`). If no settings file, invoke the `setup` skill to create one.
|
||||
|
||||
Run configured agents in parallel with Task tool. Present findings and address critical issues.
|
||||
|
||||
3. **Final Validation**
|
||||
- All TodoWrite tasks marked completed
|
||||
- All tests pass
|
||||
- Linting passes
|
||||
- Code follows existing patterns
|
||||
- Figma designs match (if applicable)
|
||||
- No console errors or warnings
|
||||
|
||||
4. **Prepare Operational Validation Plan** (REQUIRED)
|
||||
- Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change.
|
||||
- Include concrete:
|
||||
- Log queries/search terms
|
||||
- Metrics or dashboards to watch
|
||||
- Expected healthy signals
|
||||
- Failure signals and rollback/mitigation trigger
|
||||
- Validation window and owner
|
||||
- If there is truly no production/runtime impact, still include the section with: `No additional operational monitoring required` and a one-line reason.
|
||||
|
||||
### Phase 4: Ship It
|
||||
|
||||
1. **Create Commit**
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git status # Review what's being committed
|
||||
git diff --staged # Check the changes
|
||||
|
||||
# Commit with conventional format
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(scope): description of what and why
|
||||
|
||||
Brief explanation if needed.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
2. **Capture and Upload Screenshots for UI Changes** (REQUIRED for any UI work)
|
||||
|
||||
For **any** design changes, new views, or UI modifications, you MUST capture and upload screenshots:
|
||||
|
||||
**Step 1: Start dev server** (if not running)
|
||||
```bash
|
||||
bin/dev # Run in background
|
||||
```
|
||||
|
||||
**Step 2: Capture screenshots with agent-browser CLI**
|
||||
```bash
|
||||
agent-browser open http://localhost:3000/[route]
|
||||
agent-browser snapshot -i
|
||||
agent-browser screenshot output.png
|
||||
```
|
||||
See the `agent-browser` skill for detailed usage.
|
||||
|
||||
**Step 3: Upload using imgup skill**
|
||||
```bash
|
||||
skill: imgup
|
||||
# Then upload each screenshot:
|
||||
imgup -h pixhost screenshot.png # pixhost works without API key
|
||||
# Alternative hosts: catbox, imagebin, beeimg
|
||||
```
|
||||
|
||||
**What to capture:**
|
||||
- **New screens**: Screenshot of the new UI
|
||||
- **Modified screens**: Before AND after screenshots
|
||||
- **Design implementation**: Screenshot showing Figma design match
|
||||
|
||||
**IMPORTANT**: Always include uploaded image URLs in PR description. This provides visual context for reviewers and documents the change.
|
||||
|
||||
3. **Create Pull Request**
|
||||
|
||||
```bash
|
||||
git push -u origin feature-branch-name
|
||||
|
||||
gh pr create --title "Feature: [Description]" --body "$(cat <<'EOF'
|
||||
## Summary
|
||||
- What was built
|
||||
- Why it was needed
|
||||
- Key decisions made
|
||||
|
||||
## Testing
|
||||
- Tests added/modified
|
||||
- Manual testing performed
|
||||
|
||||
## Post-Deploy Monitoring & Validation
|
||||
- **What to monitor/search**
|
||||
- Logs:
|
||||
- Metrics/Dashboards:
|
||||
- **Validation checks (queries/commands)**
|
||||
- `command or query here`
|
||||
- **Expected healthy behavior**
|
||||
- Expected signal(s)
|
||||
- **Failure signal(s) / rollback trigger**
|
||||
- Trigger + immediate action
|
||||
- **Validation window & owner**
|
||||
- Window:
|
||||
- Owner:
|
||||
- **If no operational impact**
|
||||
- `No additional operational monitoring required: <reason>`
|
||||
|
||||
## Before / After Screenshots
|
||||
| Before | After |
|
||||
|--------|-------|
|
||||
|  |  |
|
||||
|
||||
## Figma Design
|
||||
[Link if applicable]
|
||||
|
||||
---
|
||||
|
||||
[](https://github.com/EveryInc/compound-engineering-plugin) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
4. **Update Plan Status**
|
||||
|
||||
If the input document has YAML frontmatter with a `status` field, update it to `completed`:
|
||||
```
|
||||
status: active → status: completed
|
||||
```
|
||||
|
||||
5. **Notify User**
|
||||
- Summarize what was completed
|
||||
- Link to PR
|
||||
- Note any follow-up work needed
|
||||
- Suggest next steps if applicable
|
||||
|
||||
---
|
||||
|
||||
## Swarm Mode (Optional)
|
||||
|
||||
For complex plans with multiple independent workstreams, enable swarm mode for parallel execution with coordinated agents.
|
||||
|
||||
### When to Use Swarm Mode
|
||||
|
||||
| Use Swarm Mode when... | Use Standard Mode when... |
|
||||
|------------------------|---------------------------|
|
||||
| Plan has 5+ independent tasks | Plan is linear/sequential |
|
||||
| Multiple specialists needed (review + test + implement) | Single-focus work |
|
||||
| Want maximum parallelism | Simpler mental model preferred |
|
||||
| Large feature with clear phases | Small feature or bug fix |
|
||||
|
||||
### Enabling Swarm Mode
|
||||
|
||||
To trigger swarm execution, say:
|
||||
|
||||
> "Make a Task list and launch an army of agent swarm subagents to build the plan"
|
||||
|
||||
Or explicitly request: "Use swarm mode for this work"
|
||||
|
||||
### Swarm Workflow
|
||||
|
||||
When swarm mode is enabled, the workflow changes:
|
||||
|
||||
1. **Create Team**
|
||||
```
|
||||
Teammate({ operation: "spawnTeam", team_name: "work-{timestamp}" })
|
||||
```
|
||||
|
||||
2. **Create Task List with Dependencies**
|
||||
- Parse plan into TaskCreate items
|
||||
- Set up blockedBy relationships for sequential dependencies
|
||||
- Independent tasks have no blockers (can run in parallel)
|
||||
|
||||
3. **Spawn Specialized Teammates**
|
||||
```
|
||||
Task({
|
||||
team_name: "work-{timestamp}",
|
||||
name: "implementer",
|
||||
subagent_type: "general-purpose",
|
||||
prompt: "Claim implementation tasks, execute, mark complete",
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
Task({
|
||||
team_name: "work-{timestamp}",
|
||||
name: "tester",
|
||||
subagent_type: "general-purpose",
|
||||
prompt: "Claim testing tasks, run tests, mark complete",
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
4. **Coordinate and Monitor**
|
||||
- Team lead monitors task completion
|
||||
- Spawn additional workers as phases unblock
|
||||
- Handle plan approval if required
|
||||
|
||||
5. **Cleanup**
|
||||
```
|
||||
Teammate({ operation: "requestShutdown", target_agent_id: "implementer" })
|
||||
Teammate({ operation: "requestShutdown", target_agent_id: "tester" })
|
||||
Teammate({ operation: "cleanup" })
|
||||
```
|
||||
|
||||
See the `orchestrating-swarms` skill for detailed swarm patterns and best practices.
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
### Start Fast, Execute Faster
|
||||
|
||||
- Get clarification once at the start, then execute
|
||||
- Don't wait for perfect understanding - ask questions and move
|
||||
- The goal is to **finish the feature**, not create perfect process
|
||||
|
||||
### The Plan is Your Guide
|
||||
|
||||
- Work documents should reference similar code and patterns
|
||||
- Load those references and follow them
|
||||
- Don't reinvent - match what exists
|
||||
|
||||
### Test As You Go
|
||||
|
||||
- Run tests after each change, not at the end
|
||||
- Fix failures immediately
|
||||
- Continuous testing prevents big surprises
|
||||
|
||||
### Quality is Built In
|
||||
|
||||
- Follow existing patterns
|
||||
- Write tests for new code
|
||||
- Run linting before pushing
|
||||
- Use reviewer agents for complex/risky changes only
|
||||
|
||||
### Ship Complete Features
|
||||
|
||||
- Mark all tasks completed before moving on
|
||||
- Don't leave features 80% done
|
||||
- A finished feature that ships beats a perfect feature that doesn't
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before creating PR, verify:
|
||||
|
||||
- [ ] All clarifying questions asked and answered
|
||||
- [ ] All TodoWrite tasks marked completed
|
||||
- [ ] Tests pass (run project's test command)
|
||||
- [ ] Linting passes (use linting-agent)
|
||||
- [ ] Code follows existing patterns
|
||||
- [ ] Figma designs match implementation (if applicable)
|
||||
- [ ] Before/after screenshots captured and uploaded (for UI changes)
|
||||
- [ ] Commit messages follow conventional format
|
||||
- [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
|
||||
- [ ] PR description includes summary, testing notes, and screenshots
|
||||
- [ ] PR description includes Compound Engineered badge
|
||||
|
||||
## When to Use Reviewer Agents
|
||||
|
||||
**Don't use by default.** Use reviewer agents only when:
|
||||
|
||||
- Large refactor affecting many files (10+)
|
||||
- Security-sensitive changes (authentication, permissions, data access)
|
||||
- Performance-critical code paths
|
||||
- Complex algorithms or business logic
|
||||
- User explicitly requests thorough review
|
||||
|
||||
For most features: tests + linting + following patterns is sufficient.
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
- **Analysis paralysis** - Don't overthink, read the plan and execute
|
||||
- **Skipping clarifying questions** - Ask now, not after building wrong thing
|
||||
- **Ignoring plan references** - The plan has links for a reason
|
||||
- **Testing at the end** - Test continuously or suffer later
|
||||
- **Forgetting TodoWrite** - Track progress or lose track of what's done
|
||||
- **80% done syndrome** - Finish the feature, don't move on early
|
||||
- **Over-reviewing simple changes** - Save reviewer agents for complex work
|
||||
@@ -10,7 +10,7 @@ argument-hint: "[path to plan file]"
|
||||
|
||||
**Note: The current year is 2026.** Use this when searching for recent documentation and best practices.
|
||||
|
||||
This command takes an existing plan (from `/workflows:plan`) and enhances each section with parallel research agents. Each major element gets its own dedicated research sub-agent to find:
|
||||
This command takes an existing plan (from `/ce:plan`) and enhances each section with parallel research agents. Each major element gets its own dedicated research sub-agent to find:
|
||||
- Best practices and industry patterns
|
||||
- Performance optimizations
|
||||
- UI/UX improvements (if applicable)
|
||||
@@ -145,13 +145,13 @@ Task general-purpose: "Use the security-patterns skill at ~/.claude/skills/secur
|
||||
### 3. Discover and Apply Learnings/Solutions
|
||||
|
||||
<thinking>
|
||||
Check for documented learnings from /workflows:compound. These are solved problems stored as markdown files. Spawn a sub-agent for each learning to check if it's relevant.
|
||||
Check for documented learnings from /ce:compound. These are solved problems stored as markdown files. Spawn a sub-agent for each learning to check if it's relevant.
|
||||
</thinking>
|
||||
|
||||
**LEARNINGS LOCATION - Check these exact folders:**
|
||||
|
||||
```
|
||||
docs/solutions/ <-- PRIMARY: Project-level learnings (created by /workflows:compound)
|
||||
docs/solutions/ <-- PRIMARY: Project-level learnings (created by /ce:compound)
|
||||
├── performance-issues/
|
||||
│ └── *.md
|
||||
├── debugging-patterns/
|
||||
@@ -370,7 +370,7 @@ Wait for ALL parallel agents to complete - skills, research agents, review agent
|
||||
**Collect outputs from ALL sources:**
|
||||
|
||||
1. **Skill-based sub-agents** - Each skill's full output (code examples, patterns, recommendations)
|
||||
2. **Learnings/Solutions sub-agents** - Relevant documented learnings from /workflows:compound
|
||||
2. **Learnings/Solutions sub-agents** - Relevant documented learnings from /ce:compound
|
||||
3. **Research agents** - Best practices, documentation, real-world examples
|
||||
4. **Review agents** - All feedback from every reviewer (architecture, security, performance, simplicity, etc.)
|
||||
5. **Context7 queries** - Framework documentation and patterns
|
||||
@@ -481,14 +481,14 @@ After writing the enhanced plan, use the **AskUserQuestion tool** to present the
|
||||
**Options:**
|
||||
1. **View diff** - Show what was added/changed
|
||||
2. **Run `/technical_review`** - Get feedback from reviewers on enhanced plan
|
||||
3. **Start `/workflows:work`** - Begin implementing this enhanced plan
|
||||
3. **Start `/ce:work`** - Begin implementing this enhanced plan
|
||||
4. **Deepen further** - Run another round of research on specific sections
|
||||
5. **Revert** - Restore original plan (if backup exists)
|
||||
|
||||
Based on selection:
|
||||
- **View diff** → Run `git diff [plan_path]` or show before/after
|
||||
- **`/technical_review`** → Call the /technical_review command with the plan file path
|
||||
- **`/workflows:work`** → Call the /workflows:work command with the plan file path
|
||||
- **`/ce:work`** → Call the /ce:work command with the plan file path
|
||||
- **Deepen further** → Ask which sections need more research, then re-run those agents
|
||||
- **Revert** → Restore from git or backup
|
||||
|
||||
|
||||
@@ -8,10 +8,10 @@ disable-model-invocation: true
|
||||
Run these slash commands in order. Do not do anything else. Do not stop between steps — complete every step through to the end.
|
||||
|
||||
1. **Optional:** If the `ralph-wiggum` skill is available, run `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`. If not available or it fails, skip and continue to step 2 immediately.
|
||||
2. `/workflows:plan $ARGUMENTS`
|
||||
2. `/ce:plan $ARGUMENTS`
|
||||
3. `/compound-engineering:deepen-plan`
|
||||
4. `/workflows:work`
|
||||
5. `/workflows:review`
|
||||
4. `/ce:work`
|
||||
5. `/ce:review`
|
||||
6. `/compound-engineering:resolve_todo_parallel`
|
||||
7. `/compound-engineering:test-browser`
|
||||
8. `/compound-engineering:feature-video`
|
||||
|
||||
@@ -10,15 +10,15 @@ Swarm-enabled LFG. Run these steps in order, parallelizing where indicated. Do n
|
||||
## Sequential Phase
|
||||
|
||||
1. **Optional:** If the `ralph-wiggum` skill is available, run `/ralph-wiggum:ralph-loop "finish all slash commands" --completion-promise "DONE"`. If not available or it fails, skip and continue to step 2 immediately.
|
||||
2. `/workflows:plan $ARGUMENTS`
|
||||
2. `/ce:plan $ARGUMENTS`
|
||||
3. `/compound-engineering:deepen-plan`
|
||||
4. `/workflows:work` — **Use swarm mode**: Make a Task list and launch an army of agent swarm subagents to build the plan
|
||||
4. `/ce:work` — **Use swarm mode**: Make a Task list and launch an army of agent swarm subagents to build the plan
|
||||
|
||||
## Parallel Phase
|
||||
|
||||
After work completes, launch steps 5 and 6 as **parallel swarm agents** (both only need code to be written):
|
||||
|
||||
5. `/workflows:review` — spawn as background Task agent
|
||||
5. `/ce:review` — spawn as background Task agent
|
||||
6. `/compound-engineering:test-browser` — spawn as background Task agent
|
||||
|
||||
Wait for both to complete before continuing.
|
||||
|
||||
@@ -323,9 +323,9 @@ mcp__xcodebuildmcp__shutdown_simulator({ simulator_id: "[uuid]" })
|
||||
/xcode-test current
|
||||
```
|
||||
|
||||
## Integration with /workflows:review
|
||||
## Integration with /ce:review
|
||||
|
||||
When reviewing PRs that touch iOS code, the `/workflows:review` command can spawn this as a subagent:
|
||||
When reviewing PRs that touch iOS code, the `/ce:review` command can spawn this as a subagent:
|
||||
|
||||
```
|
||||
Task general-purpose("Run /xcode-test for scheme [name]. Build, install on simulator, test key screens, check for crashes.")
|
||||
|
||||
@@ -1,145 +1,10 @@
|
||||
---
|
||||
name: workflows:brainstorm
|
||||
description: Explore requirements and approaches through collaborative dialogue before planning implementation
|
||||
description: "[DEPRECATED] Use /ce:brainstorm instead — renamed for clarity."
|
||||
argument-hint: "[feature idea or problem to explore]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Brainstorm a Feature or Improvement
|
||||
NOTE: /workflows:brainstorm is deprecated. Please use /ce:brainstorm instead. This alias will be removed in a future version.
|
||||
|
||||
**Note: The current year is 2026.** Use this when dating brainstorm documents.
|
||||
|
||||
Brainstorming helps answer **WHAT** to build through collaborative dialogue. It precedes `/workflows:plan`, which answers **HOW** to build it.
|
||||
|
||||
**Process knowledge:** Load the `brainstorming` skill for detailed question techniques, approach exploration patterns, and YAGNI principles.
|
||||
|
||||
## Feature Description
|
||||
|
||||
<feature_description> #$ARGUMENTS </feature_description>
|
||||
|
||||
**If the feature description above is empty, ask the user:** "What would you like to explore? Please describe the feature, problem, or improvement you're thinking about."
|
||||
|
||||
Do not proceed until you have a feature description from the user.
|
||||
|
||||
## Execution Flow
|
||||
|
||||
### Phase 0: Assess Requirements Clarity
|
||||
|
||||
Evaluate whether brainstorming is needed based on the feature description.
|
||||
|
||||
**Clear requirements indicators:**
|
||||
- Specific acceptance criteria provided
|
||||
- Referenced existing patterns to follow
|
||||
- Described exact expected behavior
|
||||
- Constrained, well-defined scope
|
||||
|
||||
**If requirements are already clear:**
|
||||
Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough to proceed directly to planning. Should I run `/workflows:plan` instead, or would you like to explore the idea further?"
|
||||
|
||||
### Phase 1: Understand the Idea
|
||||
|
||||
#### 1.1 Repository Research (Lightweight)
|
||||
|
||||
Run a quick repo scan to understand existing patterns:
|
||||
|
||||
- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
|
||||
|
||||
Focus on: similar features, established patterns, CLAUDE.md guidance.
|
||||
|
||||
#### 1.2 Collaborative Dialogue
|
||||
|
||||
Use the **AskUserQuestion tool** to ask questions **one at a time**.
|
||||
|
||||
**Guidelines (see `brainstorming` skill for detailed techniques):**
|
||||
- Prefer multiple choice when natural options exist
|
||||
- Start broad (purpose, users) then narrow (constraints, edge cases)
|
||||
- Validate assumptions explicitly
|
||||
- Ask about success criteria
|
||||
|
||||
**Exit condition:** Continue until the idea is clear OR user says "proceed"
|
||||
|
||||
### Phase 2: Explore Approaches
|
||||
|
||||
Propose **2-3 concrete approaches** based on research and conversation.
|
||||
|
||||
For each approach, provide:
|
||||
- Brief description (2-3 sentences)
|
||||
- Pros and cons
|
||||
- When it's best suited
|
||||
|
||||
Lead with your recommendation and explain why. Apply YAGNI—prefer simpler solutions.
|
||||
|
||||
Use **AskUserQuestion tool** to ask which approach the user prefers.
|
||||
|
||||
### Phase 3: Capture the Design
|
||||
|
||||
Write a brainstorm document to `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`.
|
||||
|
||||
**Document structure:** See the `brainstorming` skill for the template format. Key sections: What We're Building, Why This Approach, Key Decisions, Open Questions.
|
||||
|
||||
Ensure `docs/brainstorms/` directory exists before writing.
|
||||
|
||||
**IMPORTANT:** Before proceeding to Phase 4, check if there are any Open Questions listed in the brainstorm document. If there are open questions, YOU MUST ask the user about each one using AskUserQuestion before offering to proceed to planning. Move resolved questions to a "Resolved Questions" section.
|
||||
|
||||
### Phase 4: Handoff
|
||||
|
||||
Use **AskUserQuestion tool** to present next steps:
|
||||
|
||||
**Question:** "Brainstorm captured. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Review and refine** - Improve the document through structured self-review
|
||||
2. **Proceed to planning** - Run `/workflows:plan` (will auto-detect this brainstorm)
|
||||
3. **Share to Proof** - Upload to Proof for collaborative review and sharing
|
||||
4. **Ask more questions** - I have more questions to clarify before moving on
|
||||
5. **Done for now** - Return later
|
||||
|
||||
**If user selects "Share to Proof":**
|
||||
|
||||
```bash
|
||||
CONTENT=$(cat docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md)
|
||||
TITLE="Brainstorm: <topic title>"
|
||||
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
|
||||
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
||||
```
|
||||
|
||||
Display the URL prominently: `View & collaborate in Proof: <PROOF_URL>`
|
||||
|
||||
If the curl fails, skip silently. Then return to the Phase 4 options.
|
||||
|
||||
**If user selects "Ask more questions":** YOU (Claude) return to Phase 1.2 (Collaborative Dialogue) and continue asking the USER questions one at a time to further refine the design. The user wants YOU to probe deeper - ask about edge cases, constraints, preferences, or areas not yet explored. Continue until the user is satisfied, then return to Phase 4.
|
||||
|
||||
**If user selects "Review and refine":**
|
||||
|
||||
Load the `document-review` skill and apply it to the brainstorm document.
|
||||
|
||||
When document-review returns "Review complete", present next steps:
|
||||
|
||||
1. **Move to planning** - Continue to `/workflows:plan` with this document
|
||||
2. **Done for now** - Brainstorming complete. To start planning later: `/workflows:plan [document-path]`
|
||||
|
||||
## Output Summary
|
||||
|
||||
When complete, display:
|
||||
|
||||
```
|
||||
Brainstorm complete!
|
||||
|
||||
Document: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md
|
||||
|
||||
Key decisions:
|
||||
- [Decision 1]
|
||||
- [Decision 2]
|
||||
|
||||
Next: Run `/workflows:plan` when ready to implement.
|
||||
```
|
||||
|
||||
## Important Guidelines
|
||||
|
||||
- **Stay focused on WHAT, not HOW** - Implementation details belong in the plan
|
||||
- **Ask one question at a time** - Don't overwhelm
|
||||
- **Apply YAGNI** - Prefer simpler approaches
|
||||
- **Keep outputs concise** - 200-300 words per section max
|
||||
|
||||
NEVER CODE! Just explore and document decisions.
|
||||
/ce:brainstorm $ARGUMENTS
|
||||
|
||||
@@ -1,240 +1,10 @@
|
||||
---
|
||||
name: workflows:compound
|
||||
description: Document a recently solved problem to compound your team's knowledge
|
||||
description: "[DEPRECATED] Use /ce:compound instead — renamed for clarity."
|
||||
argument-hint: "[optional: brief context about the fix]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# /compound
|
||||
NOTE: /workflows:compound is deprecated. Please use /ce:compound instead. This alias will be removed in a future version.
|
||||
|
||||
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
|
||||
/workflows:compound # Document the most recent fix
|
||||
/workflows:compound [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Execution Strategy: Two-Phase Orchestration
|
||||
|
||||
<critical_requirement>
|
||||
**Only ONE file gets written - the final documentation.**
|
||||
|
||||
Phase 1 subagents return TEXT DATA to the orchestrator. They must NOT use Write, Edit, or create any files. Only the orchestrator (Phase 2) writes the final documentation file.
|
||||
</critical_requirement>
|
||||
|
||||
### Phase 1: Parallel Research
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Launch these subagents IN PARALLEL. Each returns text data to the orchestrator.
|
||||
|
||||
#### 1. **Context Analyzer**
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Validates against schema
|
||||
- Returns: YAML frontmatter skeleton
|
||||
|
||||
#### 2. **Solution Extractor**
|
||||
- Analyzes all investigation steps
|
||||
- Identifies root cause
|
||||
- Extracts working solution with code examples
|
||||
- Returns: Solution content block
|
||||
|
||||
#### 3. **Related Docs Finder**
|
||||
- Searches `docs/solutions/` for related documentation
|
||||
- Identifies cross-references and links
|
||||
- Finds related GitHub issues
|
||||
- Returns: Links and relationships
|
||||
|
||||
#### 4. **Prevention Strategist**
|
||||
- Develops prevention strategies
|
||||
- Creates best practices guidance
|
||||
- Generates test cases if applicable
|
||||
- Returns: Prevention/testing content
|
||||
|
||||
#### 5. **Category Classifier**
|
||||
- Determines optimal `docs/solutions/` category
|
||||
- Validates category against schema
|
||||
- Suggests filename based on slug
|
||||
- Returns: Final path and filename
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
### Phase 2: Assembly & Write
|
||||
|
||||
<sequential_tasks>
|
||||
|
||||
**WAIT for all Phase 1 subagents to complete before proceeding.**
|
||||
|
||||
The orchestrating agent (main conversation) performs these steps:
|
||||
|
||||
1. Collect all text results from Phase 1 subagents
|
||||
2. Assemble complete markdown file from the collected pieces
|
||||
3. Validate YAML frontmatter against schema
|
||||
4. Create directory if needed: `mkdir -p docs/solutions/[category]/`
|
||||
5. Write the SINGLE final file: `docs/solutions/[category]/[filename].md`
|
||||
|
||||
</sequential_tasks>
|
||||
|
||||
### Phase 3: Optional Enhancement
|
||||
|
||||
**WAIT for Phase 2 to complete before proceeding.**
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Based on problem type, optionally invoke specialized agents to review the documentation:
|
||||
|
||||
- **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`
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
## 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
|
||||
|
||||
<preconditions enforcement="advisory">
|
||||
<check condition="problem_solved">
|
||||
Problem has been solved (not in-progress)
|
||||
</check>
|
||||
<check condition="solution_verified">
|
||||
Solution has been verified working
|
||||
</check>
|
||||
<check condition="non_trivial">
|
||||
Non-trivial problem (not simple typo or obvious error)
|
||||
</check>
|
||||
</preconditions>
|
||||
|
||||
## 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/
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
| ❌ Wrong | ✅ Correct |
|
||||
|----------|-----------|
|
||||
| Subagents write files like `context-analysis.md`, `solution-draft.md` | Subagents return text data; orchestrator writes one final file |
|
||||
| Research and assembly run in parallel | Research completes → then assembly runs |
|
||||
| Multiple files created during workflow | Single file: `docs/solutions/[category]/[filename].md` |
|
||||
|
||||
## Success Output
|
||||
|
||||
```
|
||||
✓ Documentation complete
|
||||
|
||||
Subagent Results:
|
||||
✓ Context Analyzer: Identified performance_issue in brief_system
|
||||
✓ Solution Extractor: 3 code fixes
|
||||
✓ Related Docs Finder: 2 related issues
|
||||
✓ Prevention Strategist: Prevention strategies, test suggestions
|
||||
✓ Category Classifier: `performance-issues`
|
||||
|
||||
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
|
||||
|
||||
<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
|
||||
|
||||
<manual_override> Use /workflows:compound [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
|
||||
|
||||
## 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 /workflows:compound completes for deeper review
|
||||
- **Customize agents**: Edit `compound-engineering.local.md` or invoke the `setup` skill to configure which review agents are used across all workflows
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
|
||||
- `/workflows:plan` - Planning workflow (references documented solutions)
|
||||
/ce:compound $ARGUMENTS
|
||||
|
||||
@@ -1,636 +1,10 @@
|
||||
---
|
||||
name: workflows:plan
|
||||
description: Transform feature descriptions into well-structured project plans following conventions
|
||||
description: "[DEPRECATED] Use /ce:plan instead — renamed for clarity."
|
||||
argument-hint: "[feature description, bug report, or improvement idea]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Create a plan for a new feature or bug fix
|
||||
NOTE: /workflows:plan is deprecated. Please use /ce:plan instead. This alias will be removed in a future version.
|
||||
|
||||
## Introduction
|
||||
|
||||
**Note: The current year is 2026.** 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
|
||||
|
||||
<feature_description> #$ARGUMENTS </feature_description>
|
||||
|
||||
**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.
|
||||
|
||||
### 0. Idea Refinement
|
||||
|
||||
**Check for brainstorm output first:**
|
||||
|
||||
Before asking questions, look for recent brainstorm documents in `docs/brainstorms/` that match this feature:
|
||||
|
||||
```bash
|
||||
ls -la docs/brainstorms/*.md 2>/dev/null | head -10
|
||||
```
|
||||
|
||||
**Relevance criteria:** A brainstorm is relevant if:
|
||||
- The topic (from filename or YAML frontmatter) semantically matches the feature description
|
||||
- Created within the last 14 days
|
||||
- If multiple candidates match, use the most recent one
|
||||
|
||||
**If a relevant brainstorm exists:**
|
||||
1. Read the brainstorm document **thoroughly** — every section matters
|
||||
2. Announce: "Found brainstorm from [date]: [topic]. Using as foundation for planning."
|
||||
3. Extract and carry forward **ALL** of the following into the plan:
|
||||
- Key decisions and their rationale
|
||||
- Chosen approach and why alternatives were rejected
|
||||
- Constraints and requirements discovered during brainstorming
|
||||
- Open questions (flag these for resolution during planning)
|
||||
- Success criteria and scope boundaries
|
||||
- Any specific technical choices or patterns discussed
|
||||
4. **Skip the idea refinement questions below** — the brainstorm already answered WHAT to build
|
||||
5. Use brainstorm content as the **primary input** to research and planning phases
|
||||
6. **Critical: The brainstorm is the origin document.** Throughout the plan, reference specific decisions with `(see brainstorm: docs/brainstorms/<filename>)` when carrying forward conclusions. Do not paraphrase decisions in a way that loses their original context — link back to the source.
|
||||
7. **Do not omit brainstorm content** — if the brainstorm discussed it, the plan must address it (even if briefly). Scan each brainstorm section before finalizing the plan to verify nothing was dropped.
|
||||
|
||||
**If multiple brainstorms could match:**
|
||||
Use **AskUserQuestion tool** to ask which brainstorm to use, or whether to proceed without one.
|
||||
|
||||
**If no brainstorm found (or not relevant), run idea refinement:**
|
||||
|
||||
Refine the idea through collaborative dialogue using the **AskUserQuestion tool**:
|
||||
|
||||
- Ask questions one at a time to understand the idea fully
|
||||
- Prefer multiple choice questions when natural options exist
|
||||
- Focus on understanding: purpose, constraints and success criteria
|
||||
- Continue until the idea is clear OR user says "proceed"
|
||||
|
||||
**Gather signals for research decision.** During refinement, note:
|
||||
|
||||
- **User's familiarity**: Do they know the codebase patterns? Are they pointing to examples?
|
||||
- **User's intent**: Speed vs thoroughness? Exploration vs execution?
|
||||
- **Topic risk**: Security, payments, external APIs warrant more caution
|
||||
- **Uncertainty level**: Is the approach clear or open-ended?
|
||||
|
||||
**Skip option:** If the feature description is already detailed, offer:
|
||||
"Your description is clear. Should I proceed with research, or would you like to refine it further?"
|
||||
|
||||
## Main Tasks
|
||||
|
||||
### 1. Local Research (Always Runs - Parallel)
|
||||
|
||||
<thinking>
|
||||
First, I need to understand the project's conventions, existing patterns, and any documented learnings. This is fast and local - it informs whether external research is needed.
|
||||
</thinking>
|
||||
|
||||
Run these agents **in parallel** to gather local context:
|
||||
|
||||
- Task repo-research-analyst(feature_description)
|
||||
- Task learnings-researcher(feature_description)
|
||||
|
||||
**What to look for:**
|
||||
- **Repo research:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency
|
||||
- **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned)
|
||||
|
||||
These findings inform the next step.
|
||||
|
||||
### 1.5. Research Decision
|
||||
|
||||
Based on signals from Step 0 and findings from Step 1, decide on external research.
|
||||
|
||||
**High-risk topics → always research.** Security, payments, external APIs, data privacy. The cost of missing something is too high. This takes precedence over speed signals.
|
||||
|
||||
**Strong local context → skip external research.** Codebase has good patterns, CLAUDE.md has guidance, user knows what they want. External research adds little value.
|
||||
|
||||
**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable.
|
||||
|
||||
**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed.
|
||||
|
||||
Examples:
|
||||
- "Your codebase has solid patterns for this. Proceeding without external research."
|
||||
- "This involves payment processing, so I'll research current best practices first."
|
||||
|
||||
### 1.5b. External Research (Conditional)
|
||||
|
||||
**Only run if Step 1.5 indicates external research is valuable.**
|
||||
|
||||
Run these agents in parallel:
|
||||
|
||||
- Task best-practices-researcher(feature_description)
|
||||
- Task framework-docs-researcher(feature_description)
|
||||
|
||||
### 1.6. Consolidate Research
|
||||
|
||||
After all research steps complete, consolidate findings:
|
||||
|
||||
- Document relevant file paths from repo research (e.g., `app/services/example_service.rb:42`)
|
||||
- **Include relevant institutional learnings** from `docs/solutions/` (key insights, gotchas to avoid)
|
||||
- Note external documentation URLs and best practices (if external research was done)
|
||||
- List related issues or PRs discovered
|
||||
- Capture CLAUDE.md conventions
|
||||
|
||||
**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.
|
||||
|
||||
### 2. Issue Planning & Structure
|
||||
|
||||
<thinking>
|
||||
Think like a product manager - what would make this issue clear and actionable? Consider multiple perspectives
|
||||
</thinking>
|
||||
|
||||
**Title & Categorization:**
|
||||
|
||||
- [ ] Draft clear, searchable issue title using conventional format (e.g., `feat: Add user authentication`, `fix: Cart total calculation`)
|
||||
- [ ] Determine issue type: enhancement, bug, refactor
|
||||
- [ ] Convert title to filename: add today's date prefix, strip prefix colon, kebab-case, add `-plan` suffix
|
||||
- Example: `feat: Add User Authentication` → `2026-01-21-feat-add-user-authentication-plan.md`
|
||||
- Keep it descriptive (3-5 words after prefix) so plans are findable by context
|
||||
|
||||
**Stakeholder Analysis:**
|
||||
|
||||
- [ ] Identify who will be affected by this issue (end users, developers, operations)
|
||||
- [ ] Consider implementation complexity and required expertise
|
||||
|
||||
**Content Planning:**
|
||||
|
||||
- [ ] Choose appropriate detail level based on issue complexity and audience
|
||||
- [ ] List all necessary sections for the chosen template
|
||||
- [ ] Gather supporting materials (error logs, screenshots, design mockups)
|
||||
- [ ] Prepare code examples or reproduction steps if applicable, name the mock filenames in the lists
|
||||
|
||||
### 3. SpecFlow Analysis
|
||||
|
||||
After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification:
|
||||
|
||||
- Task compound-engineering:workflow:spec-flow-analyzer(feature_description, research_findings)
|
||||
|
||||
**SpecFlow Analyzer Output:**
|
||||
|
||||
- [ ] Review SpecFlow analysis results
|
||||
- [ ] Incorporate any identified gaps or edge cases into the issue
|
||||
- [ ] Update acceptance criteria based on SpecFlow findings
|
||||
|
||||
### 4. Choose Implementation Detail Level
|
||||
|
||||
Select how comprehensive you want the issue to be, simpler is mostly better.
|
||||
|
||||
#### 📄 MINIMAL (Quick Issue)
|
||||
|
||||
**Best for:** Simple bugs, small improvements, clear features
|
||||
|
||||
**Includes:**
|
||||
|
||||
- Problem statement or feature description
|
||||
- Basic acceptance criteria
|
||||
- Essential context only
|
||||
|
||||
**Structure:**
|
||||
|
||||
````markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
[Brief problem/feature description]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Core requirement 1
|
||||
- [ ] Core requirement 2
|
||||
|
||||
## Context
|
||||
|
||||
[Any critical information]
|
||||
|
||||
## MVP
|
||||
|
||||
### test.rb
|
||||
|
||||
```ruby
|
||||
class Test
|
||||
def initialize
|
||||
@name = "test"
|
||||
end
|
||||
end
|
||||
```
|
||||
|
||||
## Sources
|
||||
|
||||
- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
|
||||
- Related issue: #[issue_number]
|
||||
- Documentation: [relevant_docs_url]
|
||||
````
|
||||
|
||||
#### 📋 MORE (Standard Issue)
|
||||
|
||||
**Best for:** Most features, complex bugs, team collaboration
|
||||
|
||||
**Includes everything from MINIMAL plus:**
|
||||
|
||||
- Detailed background and motivation
|
||||
- Technical considerations
|
||||
- Success metrics
|
||||
- Dependencies and risks
|
||||
- Basic implementation suggestions
|
||||
|
||||
**Structure:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
## Overview
|
||||
|
||||
[Comprehensive description]
|
||||
|
||||
## Problem Statement / Motivation
|
||||
|
||||
[Why this matters]
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
[High-level approach]
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
- Architecture impacts
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
- **Interaction graph**: [What callbacks/middleware/observers fire when this runs?]
|
||||
- **Error propagation**: [How do errors flow across layers? Do retry strategies align?]
|
||||
- **State lifecycle risks**: [Can partial failure leave orphaned/inconsistent state?]
|
||||
- **API surface parity**: [What other interfaces expose similar functionality and need the same change?]
|
||||
- **Integration test scenarios**: [Cross-layer scenarios that unit tests won't catch]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Detailed requirement 1
|
||||
- [ ] Detailed requirement 2
|
||||
- [ ] Testing requirements
|
||||
|
||||
## Success Metrics
|
||||
|
||||
[How we measure success]
|
||||
|
||||
## Dependencies & Risks
|
||||
|
||||
[What could block or complicate this]
|
||||
|
||||
## Sources & References
|
||||
|
||||
- **Origin brainstorm:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm
|
||||
- Similar implementations: [file_path:line_number]
|
||||
- Best practices: [documentation_url]
|
||||
- Related PRs: #[pr_number]
|
||||
```
|
||||
|
||||
#### 📚 A LOT (Comprehensive Issue)
|
||||
|
||||
**Best for:** Major features, architectural changes, complex integrations
|
||||
|
||||
**Includes everything from MORE plus:**
|
||||
|
||||
- Detailed implementation plan with phases
|
||||
- Alternative approaches considered
|
||||
- Extensive technical specifications
|
||||
- Resource requirements and timeline
|
||||
- Future considerations and extensibility
|
||||
- Risk mitigation strategies
|
||||
- Documentation requirements
|
||||
|
||||
**Structure:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: [Issue Title]
|
||||
type: [feat|fix|refactor]
|
||||
status: active
|
||||
date: YYYY-MM-DD
|
||||
origin: docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md # if originated from brainstorm, otherwise omit
|
||||
---
|
||||
|
||||
# [Issue Title]
|
||||
|
||||
## Overview
|
||||
|
||||
[Executive summary]
|
||||
|
||||
## Problem Statement
|
||||
|
||||
[Detailed problem analysis]
|
||||
|
||||
## Proposed Solution
|
||||
|
||||
[Comprehensive solution design]
|
||||
|
||||
## Technical Approach
|
||||
|
||||
### Architecture
|
||||
|
||||
[Detailed technical design]
|
||||
|
||||
### Implementation Phases
|
||||
|
||||
#### Phase 1: [Foundation]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
#### Phase 2: [Core Implementation]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
#### Phase 3: [Polish & Optimization]
|
||||
|
||||
- Tasks and deliverables
|
||||
- Success criteria
|
||||
- Estimated effort
|
||||
|
||||
## Alternative Approaches Considered
|
||||
|
||||
[Other solutions evaluated and why rejected]
|
||||
|
||||
## System-Wide Impact
|
||||
|
||||
### Interaction Graph
|
||||
|
||||
[Map the chain reaction: what callbacks, middleware, observers, and event handlers fire when this code runs? Trace at least two levels deep. Document: "Action X triggers Y, which calls Z, which persists W."]
|
||||
|
||||
### Error & Failure Propagation
|
||||
|
||||
[Trace errors from lowest layer up. List specific error classes and where they're handled. Identify retry conflicts, unhandled error types, and silent failure swallowing.]
|
||||
|
||||
### State Lifecycle Risks
|
||||
|
||||
[Walk through each step that persists state. Can partial failure orphan rows, duplicate records, or leave caches stale? Document cleanup mechanisms or their absence.]
|
||||
|
||||
### API Surface Parity
|
||||
|
||||
[List all interfaces (classes, DSLs, endpoints) that expose equivalent functionality. Note which need updating and which share the code path.]
|
||||
|
||||
### Integration Test Scenarios
|
||||
|
||||
[3-5 cross-layer test scenarios that unit tests with mocks would never catch. Include expected behavior for each.]
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- [ ] Detailed functional criteria
|
||||
|
||||
### Non-Functional Requirements
|
||||
|
||||
- [ ] Performance targets
|
||||
- [ ] Security requirements
|
||||
- [ ] Accessibility standards
|
||||
|
||||
### Quality Gates
|
||||
|
||||
- [ ] Test coverage requirements
|
||||
- [ ] Documentation completeness
|
||||
- [ ] Code review approval
|
||||
|
||||
## Success Metrics
|
||||
|
||||
[Detailed KPIs and measurement methods]
|
||||
|
||||
## Dependencies & Prerequisites
|
||||
|
||||
[Detailed dependency analysis]
|
||||
|
||||
## Risk Analysis & Mitigation
|
||||
|
||||
[Comprehensive risk assessment]
|
||||
|
||||
## Resource Requirements
|
||||
|
||||
[Team, time, infrastructure needs]
|
||||
|
||||
## Future Considerations
|
||||
|
||||
[Extensibility and long-term vision]
|
||||
|
||||
## Documentation Plan
|
||||
|
||||
[What docs need updating]
|
||||
|
||||
## Sources & References
|
||||
|
||||
### Origin
|
||||
|
||||
- **Brainstorm document:** [docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md](path) — include if plan originated from a brainstorm. Key decisions carried forward: [list 2-3 major decisions from brainstorm]
|
||||
|
||||
### Internal References
|
||||
|
||||
- Architecture decisions: [file_path:line_number]
|
||||
- Similar features: [file_path:line_number]
|
||||
- Configuration: [file_path:line_number]
|
||||
|
||||
### External References
|
||||
|
||||
- Framework documentation: [url]
|
||||
- Best practices guide: [url]
|
||||
- Industry standards: [url]
|
||||
|
||||
### Related Work
|
||||
|
||||
- Previous PRs: #[pr_numbers]
|
||||
- Related issues: #[issue_numbers]
|
||||
- Design documents: [links]
|
||||
```
|
||||
|
||||
### 5. Issue Creation & Formatting
|
||||
|
||||
<thinking>
|
||||
Apply best practices for clarity and actionability, making the issue easy to scan and understand
|
||||
</thinking>
|
||||
|
||||
**Content Formatting:**
|
||||
|
||||
- [ ] Use clear, descriptive headings with proper hierarchy (##, ###)
|
||||
- [ ] Include code examples in triple backticks with language syntax highlighting
|
||||
- [ ] Add screenshots/mockups if UI-related (drag & drop or use image hosting)
|
||||
- [ ] Use task lists (- [ ]) for trackable items that can be checked off
|
||||
- [ ] Add collapsible sections for lengthy logs or optional details using `<details>` tags
|
||||
- [ ] Apply appropriate emoji for visual scanning (🐛 bug, ✨ feature, 📚 docs, ♻️ refactor)
|
||||
|
||||
**Cross-Referencing:**
|
||||
|
||||
- [ ] Link to related issues/PRs using #number format
|
||||
- [ ] Reference specific commits with SHA hashes when relevant
|
||||
- [ ] Link to code using GitHub's permalink feature (press 'y' for permanent link)
|
||||
- [ ] Mention relevant team members with @username if needed
|
||||
- [ ] Add links to external resources with descriptive text
|
||||
|
||||
**Code & Examples:**
|
||||
|
||||
````markdown
|
||||
# Good example with syntax highlighting and line references
|
||||
|
||||
|
||||
```ruby
|
||||
# app/services/user_service.rb:42
|
||||
def process_user(user)
|
||||
|
||||
# Implementation here
|
||||
|
||||
end
|
||||
```
|
||||
|
||||
# Collapsible error logs
|
||||
|
||||
<details>
|
||||
<summary>Full error stacktrace</summary>
|
||||
|
||||
`Error details here...`
|
||||
|
||||
</details>
|
||||
````
|
||||
|
||||
**AI-Era Considerations:**
|
||||
|
||||
- [ ] Account for accelerated development with AI pair programming
|
||||
- [ ] Include prompts or instructions that worked well during research
|
||||
- [ ] Note which AI tools were used for initial exploration (Claude, Copilot, etc.)
|
||||
- [ ] Emphasize comprehensive testing given rapid implementation
|
||||
- [ ] Document any AI-generated code that needs human review
|
||||
|
||||
### 6. Final Review & Submission
|
||||
|
||||
**Brainstorm cross-check (if plan originated from a brainstorm):**
|
||||
|
||||
Before finalizing, re-read the brainstorm document and verify:
|
||||
- [ ] Every key decision from the brainstorm is reflected in the plan
|
||||
- [ ] The chosen approach matches what was decided in the brainstorm
|
||||
- [ ] Constraints and requirements from the brainstorm are captured in acceptance criteria
|
||||
- [ ] Open questions from the brainstorm are either resolved or flagged
|
||||
- [ ] The `origin:` frontmatter field points to the brainstorm file
|
||||
- [ ] The Sources section includes the brainstorm with a summary of carried-forward decisions
|
||||
|
||||
**Pre-submission Checklist:**
|
||||
|
||||
- [ ] Title is searchable and descriptive
|
||||
- [ ] Labels accurately categorize the issue
|
||||
- [ ] All template sections are complete
|
||||
- [ ] Links and references are working
|
||||
- [ ] Acceptance criteria are measurable
|
||||
- [ ] Add names of files in pseudo code examples and todo lists
|
||||
- [ ] Add an ERD mermaid diagram if applicable for new model changes
|
||||
|
||||
## Write Plan File
|
||||
|
||||
**REQUIRED: Write the plan file to disk before presenting any options.**
|
||||
|
||||
```bash
|
||||
mkdir -p docs/plans/
|
||||
```
|
||||
|
||||
Use the Write tool to save the complete plan to `docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md`. This step is mandatory and cannot be skipped — even when running as part of LFG/SLFG or other automated pipelines.
|
||||
|
||||
Confirm: "Plan written to docs/plans/[filename]"
|
||||
|
||||
**Pipeline mode:** If invoked from an automated workflow (LFG, SLFG, or any `disable-model-invocation` context), skip all AskUserQuestion calls. Make decisions automatically and proceed to writing the plan without interactive prompts.
|
||||
|
||||
## Output Format
|
||||
|
||||
**Filename:** Use the date and kebab-case filename from Step 2 Title & Categorization.
|
||||
|
||||
```
|
||||
docs/plans/YYYY-MM-DD-<type>-<descriptive-name>-plan.md
|
||||
```
|
||||
|
||||
Examples:
|
||||
- ✅ `docs/plans/2026-01-15-feat-user-authentication-flow-plan.md`
|
||||
- ✅ `docs/plans/2026-02-03-fix-checkout-race-condition-plan.md`
|
||||
- ✅ `docs/plans/2026-03-10-refactor-api-client-extraction-plan.md`
|
||||
- ❌ `docs/plans/2026-01-15-feat-thing-plan.md` (not descriptive - what "thing"?)
|
||||
- ❌ `docs/plans/2026-01-15-feat-new-feature-plan.md` (too vague - what feature?)
|
||||
- ❌ `docs/plans/2026-01-15-feat: user auth-plan.md` (invalid characters - colon and space)
|
||||
- ❌ `docs/plans/feat-user-auth-plan.md` (missing date prefix)
|
||||
|
||||
## Post-Generation Options
|
||||
|
||||
After writing the plan file, use the **AskUserQuestion tool** to present these options:
|
||||
|
||||
**Question:** "Plan ready at `docs/plans/YYYY-MM-DD-<type>-<name>-plan.md`. What would you like to do next?"
|
||||
|
||||
**Options:**
|
||||
1. **Open plan in editor** - Open the plan file for review
|
||||
2. **Run `/deepen-plan`** - Enhance each section with parallel research agents (best practices, performance, UI)
|
||||
3. **Run `/technical_review`** - Technical feedback from code-focused reviewers (DHH, Kieran, Simplicity)
|
||||
4. **Review and refine** - Improve the document through structured self-review
|
||||
5. **Share to Proof** - Upload to Proof for collaborative review and sharing
|
||||
6. **Start `/workflows:work`** - Begin implementing this plan locally
|
||||
7. **Start `/workflows:work` on remote** - Begin implementing in Claude Code on the web (use `&` to run in background)
|
||||
8. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
|
||||
Based on selection:
|
||||
- **Open plan in editor** → Run `open docs/plans/<plan_filename>.md` to open the file in the user's default editor
|
||||
- **`/deepen-plan`** → Call the /deepen-plan command with the plan file path to enhance with research
|
||||
- **`/technical_review`** → Call the /technical_review command with the plan file path
|
||||
- **Review and refine** → Load `document-review` skill.
|
||||
- **Share to Proof** → Upload the plan to Proof:
|
||||
```bash
|
||||
CONTENT=$(cat docs/plans/<plan_filename>.md)
|
||||
TITLE="Plan: <plan title from frontmatter>"
|
||||
RESPONSE=$(curl -s -X POST https://www.proofeditor.ai/share/markdown \
|
||||
-H "Content-Type: application/json" \
|
||||
-d "$(jq -n --arg title "$TITLE" --arg markdown "$CONTENT" --arg by "ai:compound" '{title: $title, markdown: $markdown, by: $by}')")
|
||||
PROOF_URL=$(echo "$RESPONSE" | jq -r '.tokenUrl')
|
||||
```
|
||||
Display: `View & collaborate in Proof: <PROOF_URL>` — skip silently if curl fails. Then return to options.
|
||||
- **`/workflows:work`** → Call the /workflows:work command with the plan file path
|
||||
- **`/workflows:work` on remote** → Run `/workflows:work docs/plans/<plan_filename>.md &` to start work in background for Claude Code web
|
||||
- **Create Issue** → See "Issue Creation" section below
|
||||
- **Other** (automatically provided) → Accept free text for rework or specific changes
|
||||
|
||||
**Note:** If running `/workflows:plan` with ultrathink enabled, automatically run `/deepen-plan` after plan creation for maximum depth and grounding.
|
||||
|
||||
Loop back to options after Simplify or Other changes until user selects `/workflows:work` or `/technical_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:**
|
||||
|
||||
Use the title and type from Step 2 (already in context - no need to re-read the file):
|
||||
|
||||
```bash
|
||||
gh issue create --title "<type>: <title>" --body-file <plan_path>
|
||||
```
|
||||
|
||||
3. **If Linear:**
|
||||
|
||||
```bash
|
||||
linear issue create --title "<title>" --description "$(cat <plan_path>)"
|
||||
```
|
||||
|
||||
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 `/workflows:work` or `/technical_review`
|
||||
|
||||
NEVER CODE! Just research and write the plan.
|
||||
/ce:plan $ARGUMENTS
|
||||
|
||||
@@ -1,525 +1,10 @@
|
||||
---
|
||||
name: workflows:review
|
||||
description: Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees
|
||||
description: "[DEPRECATED] Use /ce:review instead — renamed for clarity."
|
||||
argument-hint: "[PR number, GitHub URL, branch name, or latest]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Review Command
|
||||
NOTE: /workflows:review is deprecated. Please use /ce:review instead. This alias will be removed in a future version.
|
||||
|
||||
<command_purpose> Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and Git worktrees for deep local inspection. </command_purpose>
|
||||
|
||||
## Introduction
|
||||
|
||||
<role>Senior Code Review Architect with expertise in security, performance, architecture, and quality assurance</role>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
<requirements>
|
||||
- Git repository with GitHub CLI (`gh`) installed and authenticated
|
||||
- Clean main/master branch
|
||||
- Proper permissions to create worktrees and access the repository
|
||||
- For document reviews: Path to a markdown file or document
|
||||
</requirements>
|
||||
|
||||
## Main Tasks
|
||||
|
||||
### 1. Determine Review Target & Setup (ALWAYS FIRST)
|
||||
|
||||
<review_target> #$ARGUMENTS </review_target>
|
||||
|
||||
<thinking>
|
||||
First, I need to determine the review target type and set up the code for analysis.
|
||||
</thinking>
|
||||
|
||||
#### Immediate Actions:
|
||||
|
||||
<task_list>
|
||||
|
||||
- [ ] Determine review type: PR number (numeric), GitHub URL, file path (.md), or empty (current branch)
|
||||
- [ ] Check current git branch
|
||||
- [ ] If ALREADY on the target branch (PR branch, requested branch name, or the branch already checked out for review) → proceed with analysis on current branch
|
||||
- [ ] If DIFFERENT branch than the review target → offer to use worktree: "Use git-worktree skill for isolated Call `skill: git-worktree` with branch name"
|
||||
- [ ] Fetch PR metadata using `gh pr view --json` for title, body, files, linked issues
|
||||
- [ ] Set up language-specific analysis tools
|
||||
- [ ] Prepare security scanning environment
|
||||
- [ ] Make sure we are on the branch we are reviewing. Use gh pr checkout to switch to the branch or manually checkout the branch.
|
||||
|
||||
Ensure that the code is ready for analysis (either in worktree or on current branch). ONLY then proceed to the next step.
|
||||
|
||||
</task_list>
|
||||
|
||||
#### Protected Artifacts
|
||||
|
||||
<protected_artifacts>
|
||||
The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:
|
||||
|
||||
- `docs/plans/*.md` — Plan files created by `/workflows:plan`. These are living documents that track implementation progress (checkboxes are checked off by `/workflows:work`).
|
||||
- `docs/solutions/*.md` — Solution documents created during the pipeline.
|
||||
|
||||
If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a todo for it.
|
||||
</protected_artifacts>
|
||||
|
||||
#### Load Review Agents
|
||||
|
||||
Read `compound-engineering.local.md` in the project root. If found, use `review_agents` from YAML frontmatter. If the markdown body contains review context, pass it to each agent as additional instructions.
|
||||
|
||||
If no settings file exists, invoke the `setup` skill to create one. Then read the newly created file and continue.
|
||||
|
||||
#### Parallel Agents to review the PR:
|
||||
|
||||
<parallel_tasks>
|
||||
|
||||
Run all configured review agents in parallel using Task tool. For each agent in the `review_agents` list:
|
||||
|
||||
```
|
||||
Task {agent-name}(PR content + review context from settings body)
|
||||
```
|
||||
|
||||
Additionally, always run these regardless of settings:
|
||||
- Task agent-native-reviewer(PR content) - Verify new features are agent-accessible
|
||||
- Task learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
|
||||
|
||||
</parallel_tasks>
|
||||
|
||||
#### Conditional Agents (Run if applicable):
|
||||
|
||||
<conditional_agents>
|
||||
|
||||
These agents are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:
|
||||
|
||||
**MIGRATIONS: If PR contains database migrations, schema.rb, or data backfills:**
|
||||
|
||||
- Task schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
|
||||
- Task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
|
||||
- Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
|
||||
|
||||
**When to run:**
|
||||
- PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
|
||||
- PR modifies columns that store IDs, enums, or mappings
|
||||
- PR includes data backfill scripts or rake tasks
|
||||
- PR title/body mentions: migration, backfill, data transformation, ID mapping
|
||||
|
||||
**What these agents check:**
|
||||
- `schema-drift-detector`: Cross-references schema.rb changes against PR migrations to catch unrelated columns/indexes from local database state
|
||||
- `data-migration-expert`: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns
|
||||
- `deployment-verification-agent`: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans
|
||||
|
||||
</conditional_agents>
|
||||
|
||||
### 2. Ultra-Thinking Deep Dive Phases
|
||||
|
||||
<ultrathink_instruction> For each phase below, spend maximum cognitive effort. Think step by step. Consider all angles. Question assumptions. And bring all reviews in a synthesis to the user.</ultrathink_instruction>
|
||||
|
||||
<deliverable>
|
||||
Complete system context map with component interactions
|
||||
</deliverable>
|
||||
|
||||
#### Phase 1: Stakeholder Perspective Analysis
|
||||
|
||||
<thinking_prompt> ULTRA-THINK: Put yourself in each stakeholder's shoes. What matters to them? What are their pain points? </thinking_prompt>
|
||||
|
||||
<stakeholder_perspectives>
|
||||
|
||||
1. **Developer Perspective** <questions>
|
||||
|
||||
- How easy is this to understand and modify?
|
||||
- Are the APIs intuitive?
|
||||
- Is debugging straightforward?
|
||||
- Can I test this easily? </questions>
|
||||
|
||||
2. **Operations Perspective** <questions>
|
||||
|
||||
- How do I deploy this safely?
|
||||
- What metrics and logs are available?
|
||||
- How do I troubleshoot issues?
|
||||
- What are the resource requirements? </questions>
|
||||
|
||||
3. **End User Perspective** <questions>
|
||||
|
||||
- Is the feature intuitive?
|
||||
- Are error messages helpful?
|
||||
- Is performance acceptable?
|
||||
- Does it solve my problem? </questions>
|
||||
|
||||
4. **Security Team Perspective** <questions>
|
||||
|
||||
- What's the attack surface?
|
||||
- Are there compliance requirements?
|
||||
- How is data protected?
|
||||
- What are the audit capabilities? </questions>
|
||||
|
||||
5. **Business Perspective** <questions>
|
||||
- What's the ROI?
|
||||
- Are there legal/compliance risks?
|
||||
- How does this affect time-to-market?
|
||||
- What's the total cost of ownership? </questions> </stakeholder_perspectives>
|
||||
|
||||
#### Phase 2: Scenario Exploration
|
||||
|
||||
<thinking_prompt> ULTRA-THINK: Explore edge cases and failure scenarios. What could go wrong? How does the system behave under stress? </thinking_prompt>
|
||||
|
||||
<scenario_checklist>
|
||||
|
||||
- [ ] **Happy Path**: Normal operation with valid inputs
|
||||
- [ ] **Invalid Inputs**: Null, empty, malformed data
|
||||
- [ ] **Boundary Conditions**: Min/max values, empty collections
|
||||
- [ ] **Concurrent Access**: Race conditions, deadlocks
|
||||
- [ ] **Scale Testing**: 10x, 100x, 1000x normal load
|
||||
- [ ] **Network Issues**: Timeouts, partial failures
|
||||
- [ ] **Resource Exhaustion**: Memory, disk, connections
|
||||
- [ ] **Security Attacks**: Injection, overflow, DoS
|
||||
- [ ] **Data Corruption**: Partial writes, inconsistency
|
||||
- [ ] **Cascading Failures**: Downstream service issues </scenario_checklist>
|
||||
|
||||
### 3. Multi-Angle Review Perspectives
|
||||
|
||||
#### Technical Excellence Angle
|
||||
|
||||
- Code craftsmanship evaluation
|
||||
- Engineering best practices
|
||||
- Technical documentation quality
|
||||
- Tooling and automation assessment
|
||||
|
||||
#### Business Value Angle
|
||||
|
||||
- Feature completeness validation
|
||||
- Performance impact on users
|
||||
- Cost-benefit analysis
|
||||
- Time-to-market considerations
|
||||
|
||||
#### Risk Management Angle
|
||||
|
||||
- Security risk assessment
|
||||
- Operational risk evaluation
|
||||
- Compliance risk verification
|
||||
- Technical debt accumulation
|
||||
|
||||
#### Team Dynamics Angle
|
||||
|
||||
- Code review etiquette
|
||||
- Knowledge sharing effectiveness
|
||||
- Collaboration patterns
|
||||
- Mentoring opportunities
|
||||
|
||||
### 4. Simplification and Minimalism Review
|
||||
|
||||
Run the Task code-simplicity-reviewer() to see if we can simplify the code.
|
||||
|
||||
### 5. Findings Synthesis and Todo Creation Using file-todos Skill
|
||||
|
||||
<critical_requirement> ALL findings MUST be stored in the todos/ directory using the file-todos skill. Create todo files immediately after synthesis - do NOT present findings for user approval first. Use the skill for structured todo management. </critical_requirement>
|
||||
|
||||
#### Step 1: Synthesize All Findings
|
||||
|
||||
<thinking>
|
||||
Consolidate all agent reports into a categorized list of findings.
|
||||
Remove duplicates, prioritize by severity and impact.
|
||||
</thinking>
|
||||
|
||||
<synthesis_tasks>
|
||||
|
||||
- [ ] Collect findings from all parallel agents
|
||||
- [ ] Surface learnings-researcher results: if past solutions are relevant, flag them as "Known Pattern" with links to docs/solutions/ files
|
||||
- [ ] Discard any findings that recommend deleting or gitignoring files in `docs/plans/` or `docs/solutions/` (see Protected Artifacts above)
|
||||
- [ ] Categorize by type: security, performance, architecture, quality, etc.
|
||||
- [ ] Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
|
||||
- [ ] Remove duplicate or overlapping findings
|
||||
- [ ] Estimate effort for each finding (Small/Medium/Large)
|
||||
|
||||
</synthesis_tasks>
|
||||
|
||||
#### Step 2: Create Todo Files Using file-todos Skill
|
||||
|
||||
<critical_instruction> Use the file-todos skill to create todo files for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all todo files in parallel using the skill, then summarize results to user. </critical_instruction>
|
||||
|
||||
**Implementation Options:**
|
||||
|
||||
**Option A: Direct File Creation (Fast)**
|
||||
|
||||
- Create todo files directly using Write tool
|
||||
- All findings in parallel for speed
|
||||
- Use standard template from `.claude/skills/file-todos/assets/todo-template.md`
|
||||
- Follow naming convention: `{issue_id}-pending-{priority}-{description}.md`
|
||||
|
||||
**Option B: Sub-Agents in Parallel (Recommended for Scale)** For large PRs with 15+ findings, use sub-agents to create finding files in parallel:
|
||||
|
||||
```bash
|
||||
# Launch multiple finding-creator agents in parallel
|
||||
Task() - Create todos for first finding
|
||||
Task() - Create todos for second finding
|
||||
Task() - Create todos for third finding
|
||||
etc. for each finding.
|
||||
```
|
||||
|
||||
Sub-agents can:
|
||||
|
||||
- Process multiple findings simultaneously
|
||||
- Write detailed todo files with all sections filled
|
||||
- Organize findings by severity
|
||||
- Create comprehensive Proposed Solutions
|
||||
- Add acceptance criteria and work logs
|
||||
- Complete much faster than sequential processing
|
||||
|
||||
**Execution Strategy:**
|
||||
|
||||
1. Synthesize all findings into categories (P1/P2/P3)
|
||||
2. Group findings by severity
|
||||
3. Launch 3 parallel sub-agents (one per severity level)
|
||||
4. Each sub-agent creates its batch of todos using the file-todos skill
|
||||
5. Consolidate results and present summary
|
||||
|
||||
**Process (Using file-todos Skill):**
|
||||
|
||||
1. For each finding:
|
||||
|
||||
- Determine severity (P1/P2/P3)
|
||||
- Write detailed Problem Statement and Findings
|
||||
- Create 2-3 Proposed Solutions with pros/cons/effort/risk
|
||||
- Estimate effort (Small/Medium/Large)
|
||||
- Add acceptance criteria and work log
|
||||
|
||||
2. Use file-todos skill for structured todo management:
|
||||
|
||||
```bash
|
||||
skill: file-todos
|
||||
```
|
||||
|
||||
The skill provides:
|
||||
|
||||
- Template location: `.claude/skills/file-todos/assets/todo-template.md`
|
||||
- Naming convention: `{issue_id}-{status}-{priority}-{description}.md`
|
||||
- YAML frontmatter structure: status, priority, issue_id, tags, dependencies
|
||||
- All required sections: Problem Statement, Findings, Solutions, etc.
|
||||
|
||||
3. Create todo files in parallel:
|
||||
|
||||
```bash
|
||||
{next_id}-pending-{priority}-{description}.md
|
||||
```
|
||||
|
||||
4. Examples:
|
||||
|
||||
```
|
||||
001-pending-p1-path-traversal-vulnerability.md
|
||||
002-pending-p1-api-response-validation.md
|
||||
003-pending-p2-concurrency-limit.md
|
||||
004-pending-p3-unused-parameter.md
|
||||
```
|
||||
|
||||
5. Follow template structure from file-todos skill: `.claude/skills/file-todos/assets/todo-template.md`
|
||||
|
||||
**Todo File Structure (from template):**
|
||||
|
||||
Each todo must include:
|
||||
|
||||
- **YAML frontmatter**: status, priority, issue_id, tags, dependencies
|
||||
- **Problem Statement**: What's broken/missing, why it matters
|
||||
- **Findings**: Discoveries from agents with evidence/location
|
||||
- **Proposed Solutions**: 2-3 options, each with pros/cons/effort/risk
|
||||
- **Recommended Action**: (Filled during triage, leave blank initially)
|
||||
- **Technical Details**: Affected files, components, database changes
|
||||
- **Acceptance Criteria**: Testable checklist items
|
||||
- **Work Log**: Dated record with actions and learnings
|
||||
- **Resources**: Links to PR, issues, documentation, similar patterns
|
||||
|
||||
**File naming convention:**
|
||||
|
||||
```
|
||||
{issue_id}-{status}-{priority}-{description}.md
|
||||
|
||||
Examples:
|
||||
- 001-pending-p1-security-vulnerability.md
|
||||
- 002-pending-p2-performance-optimization.md
|
||||
- 003-pending-p3-code-cleanup.md
|
||||
```
|
||||
|
||||
**Status values:**
|
||||
|
||||
- `pending` - New findings, needs triage/decision
|
||||
- `ready` - Approved by manager, ready to work
|
||||
- `complete` - Work finished
|
||||
|
||||
**Priority values:**
|
||||
|
||||
- `p1` - Critical (blocks merge, security/data issues)
|
||||
- `p2` - Important (should fix, architectural/performance)
|
||||
- `p3` - Nice-to-have (enhancements, cleanup)
|
||||
|
||||
**Tagging:** Always add `code-review` tag, plus: `security`, `performance`, `architecture`, `rails`, `quality`, etc.
|
||||
|
||||
#### Step 3: Summary Report
|
||||
|
||||
After creating all todo files, present comprehensive summary:
|
||||
|
||||
````markdown
|
||||
## ✅ Code Review Complete
|
||||
|
||||
**Review Target:** PR #XXXX - [PR Title] **Branch:** [branch-name]
|
||||
|
||||
### Findings Summary:
|
||||
|
||||
- **Total Findings:** [X]
|
||||
- **🔴 CRITICAL (P1):** [count] - BLOCKS MERGE
|
||||
- **🟡 IMPORTANT (P2):** [count] - Should Fix
|
||||
- **🔵 NICE-TO-HAVE (P3):** [count] - Enhancements
|
||||
|
||||
### Created Todo Files:
|
||||
|
||||
**P1 - Critical (BLOCKS MERGE):**
|
||||
|
||||
- `001-pending-p1-{finding}.md` - {description}
|
||||
- `002-pending-p1-{finding}.md` - {description}
|
||||
|
||||
**P2 - Important:**
|
||||
|
||||
- `003-pending-p2-{finding}.md` - {description}
|
||||
- `004-pending-p2-{finding}.md` - {description}
|
||||
|
||||
**P3 - Nice-to-Have:**
|
||||
|
||||
- `005-pending-p3-{finding}.md` - {description}
|
||||
|
||||
### Review Agents Used:
|
||||
|
||||
- kieran-rails-reviewer
|
||||
- security-sentinel
|
||||
- performance-oracle
|
||||
- architecture-strategist
|
||||
- agent-native-reviewer
|
||||
- [other agents]
|
||||
|
||||
### Next Steps:
|
||||
|
||||
1. **Address P1 Findings**: CRITICAL - must be fixed before merge
|
||||
|
||||
- Review each P1 todo in detail
|
||||
- Implement fixes or request exemption
|
||||
- Verify fixes before merging PR
|
||||
|
||||
2. **Triage All Todos**:
|
||||
```bash
|
||||
ls todos/*-pending-*.md # View all pending todos
|
||||
/triage # Use slash command for interactive triage
|
||||
```
|
||||
|
||||
3. **Work on Approved Todos**:
|
||||
|
||||
```bash
|
||||
/resolve_todo_parallel # Fix all approved items efficiently
|
||||
```
|
||||
|
||||
4. **Track Progress**:
|
||||
- Rename file when status changes: pending → ready → complete
|
||||
- Update Work Log as you work
|
||||
- Commit todos: `git add todos/ && git commit -m "refactor: add code review findings"`
|
||||
|
||||
### Severity Breakdown:
|
||||
|
||||
**🔴 P1 (Critical - Blocks Merge):**
|
||||
|
||||
- Security vulnerabilities
|
||||
- Data corruption risks
|
||||
- Breaking changes
|
||||
- Critical architectural issues
|
||||
|
||||
**🟡 P2 (Important - Should Fix):**
|
||||
|
||||
- Performance issues
|
||||
- Significant architectural concerns
|
||||
- Major code quality problems
|
||||
- Reliability issues
|
||||
|
||||
**🔵 P3 (Nice-to-Have):**
|
||||
|
||||
- Minor improvements
|
||||
- Code cleanup
|
||||
- Optimization opportunities
|
||||
- Documentation updates
|
||||
````
|
||||
|
||||
### 6. End-to-End Testing (Optional)
|
||||
|
||||
<detect_project_type>
|
||||
|
||||
**First, detect the project type from PR files:**
|
||||
|
||||
| Indicator | Project Type |
|
||||
|-----------|--------------|
|
||||
| `*.xcodeproj`, `*.xcworkspace`, `Package.swift` (iOS) | iOS/macOS |
|
||||
| `Gemfile`, `package.json`, `app/views/*`, `*.html.*` | Web |
|
||||
| Both iOS files AND web files | Hybrid (test both) |
|
||||
|
||||
</detect_project_type>
|
||||
|
||||
<offer_testing>
|
||||
|
||||
After presenting the Summary Report, offer appropriate testing based on project type:
|
||||
|
||||
**For Web Projects:**
|
||||
```markdown
|
||||
**"Want to run browser tests on the affected pages?"**
|
||||
1. Yes - run `/test-browser`
|
||||
2. No - skip
|
||||
```
|
||||
|
||||
**For iOS Projects:**
|
||||
```markdown
|
||||
**"Want to run Xcode simulator tests on the app?"**
|
||||
1. Yes - run `/xcode-test`
|
||||
2. No - skip
|
||||
```
|
||||
|
||||
**For Hybrid Projects (e.g., Rails + Hotwire Native):**
|
||||
```markdown
|
||||
**"Want to run end-to-end tests?"**
|
||||
1. Web only - run `/test-browser`
|
||||
2. iOS only - run `/xcode-test`
|
||||
3. Both - run both commands
|
||||
4. No - skip
|
||||
```
|
||||
|
||||
</offer_testing>
|
||||
|
||||
#### If User Accepts Web Testing:
|
||||
|
||||
Spawn a subagent to run browser tests (preserves main context):
|
||||
|
||||
```
|
||||
Task general-purpose("Run /test-browser for PR #[number]. Test all affected pages, check for console errors, handle failures by creating todos and fixing.")
|
||||
```
|
||||
|
||||
The subagent will:
|
||||
1. Identify pages affected by the PR
|
||||
2. Navigate to each page and capture snapshots (using Playwright MCP or agent-browser CLI)
|
||||
3. Check for console errors
|
||||
4. Test critical interactions
|
||||
5. Pause for human verification on OAuth/email/payment flows
|
||||
6. Create P1 todos for any failures
|
||||
7. Fix and retry until all tests pass
|
||||
|
||||
**Standalone:** `/test-browser [PR number]`
|
||||
|
||||
#### If User Accepts iOS Testing:
|
||||
|
||||
Spawn a subagent to run Xcode tests (preserves main context):
|
||||
|
||||
```
|
||||
Task general-purpose("Run /xcode-test for scheme [name]. Build for simulator, install, launch, take screenshots, check for crashes.")
|
||||
```
|
||||
|
||||
The subagent will:
|
||||
1. Verify XcodeBuildMCP is installed
|
||||
2. Discover project and schemes
|
||||
3. Build for iOS Simulator
|
||||
4. Install and launch app
|
||||
5. Take screenshots of key screens
|
||||
6. Capture console logs for errors
|
||||
7. Pause for human verification (Sign in with Apple, push, IAP)
|
||||
8. Create P1 todos for any failures
|
||||
9. Fix and retry until all tests pass
|
||||
|
||||
**Standalone:** `/xcode-test [scheme]`
|
||||
|
||||
### Important: P1 Findings Block Merge
|
||||
|
||||
Any **🔴 P1 (CRITICAL)** findings must be addressed before merging the PR. Present these prominently and ensure they're resolved before accepting the PR.
|
||||
/ce:review $ARGUMENTS
|
||||
|
||||
@@ -1,470 +1,10 @@
|
||||
---
|
||||
name: workflows:work
|
||||
description: Execute work plans efficiently while maintaining quality and finishing features
|
||||
description: "[DEPRECATED] Use /ce:work instead — renamed for clarity."
|
||||
argument-hint: "[plan file, specification, or todo file path]"
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Work Plan Execution Command
|
||||
NOTE: /workflows:work is deprecated. Please use /ce:work instead. This alias will be removed in a future version.
|
||||
|
||||
Execute a work plan efficiently while maintaining quality and finishing features.
|
||||
|
||||
## Introduction
|
||||
|
||||
This command takes a work document (plan, specification, or todo file) and executes it systematically. The focus is on **shipping complete features** by understanding requirements quickly, following existing patterns, and maintaining quality throughout.
|
||||
|
||||
## Input Document
|
||||
|
||||
<input_document> #$ARGUMENTS </input_document>
|
||||
|
||||
## Execution Workflow
|
||||
|
||||
### Phase 1: Quick Start
|
||||
|
||||
1. **Read Plan and Clarify**
|
||||
|
||||
- Read the work document completely
|
||||
- Review any references or links provided in the plan
|
||||
- If anything is unclear or ambiguous, ask clarifying questions now
|
||||
- Get user approval to proceed
|
||||
- **Do not skip this** - better to ask questions now than build the wrong thing
|
||||
|
||||
2. **Setup Environment**
|
||||
|
||||
First, check the current branch:
|
||||
|
||||
```bash
|
||||
current_branch=$(git branch --show-current)
|
||||
default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
|
||||
|
||||
# Fallback if remote HEAD isn't set
|
||||
if [ -z "$default_branch" ]; then
|
||||
default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
|
||||
fi
|
||||
```
|
||||
|
||||
**If already on a feature branch** (not the default branch):
|
||||
- Ask: "Continue working on `[current_branch]`, or create a new branch?"
|
||||
- If continuing, proceed to step 3
|
||||
- If creating new, follow Option A or B below
|
||||
|
||||
**If on the default branch**, choose how to proceed:
|
||||
|
||||
**Option A: Create a new branch**
|
||||
```bash
|
||||
git pull origin [default_branch]
|
||||
git checkout -b feature-branch-name
|
||||
```
|
||||
Use a meaningful name based on the work (e.g., `feat/user-authentication`, `fix/email-validation`).
|
||||
|
||||
**Option B: Use a worktree (recommended for parallel development)**
|
||||
```bash
|
||||
skill: git-worktree
|
||||
# The skill will create a new branch from the default branch in an isolated worktree
|
||||
```
|
||||
|
||||
**Option C: Continue on the default branch**
|
||||
- Requires explicit user confirmation
|
||||
- Only proceed after user explicitly says "yes, commit to [default_branch]"
|
||||
- Never commit directly to the default branch without explicit permission
|
||||
|
||||
**Recommendation**: Use worktree if:
|
||||
- You want to work on multiple features simultaneously
|
||||
- You want to keep the default branch clean while experimenting
|
||||
- You plan to switch between branches frequently
|
||||
|
||||
3. **Create Todo List**
|
||||
- Use TodoWrite to break plan into actionable tasks
|
||||
- Include dependencies between tasks
|
||||
- Prioritize based on what needs to be done first
|
||||
- Include testing and quality check tasks
|
||||
- Keep tasks specific and completable
|
||||
|
||||
### Phase 2: Execute
|
||||
|
||||
1. **Task Execution Loop**
|
||||
|
||||
For each task in priority order:
|
||||
|
||||
```
|
||||
while (tasks remain):
|
||||
- Mark task as in_progress in TodoWrite
|
||||
- Read any referenced files from the plan
|
||||
- Look for similar patterns in codebase
|
||||
- Implement following existing conventions
|
||||
- Write tests for new functionality
|
||||
- Run System-Wide Test Check (see below)
|
||||
- Run tests after changes
|
||||
- Mark task as completed in TodoWrite
|
||||
- Mark off the corresponding checkbox in the plan file ([ ] → [x])
|
||||
- Evaluate for incremental commit (see below)
|
||||
```
|
||||
|
||||
**System-Wide Test Check** — Before marking a task done, pause and ask:
|
||||
|
||||
| Question | What to do |
|
||||
|----------|------------|
|
||||
| **What fires when this runs?** Callbacks, middleware, observers, event handlers — trace two levels out from your change. | Read the actual code (not docs) for callbacks on models you touch, middleware in the request chain, `after_*` hooks. |
|
||||
| **Do my tests exercise the real chain?** If every dependency is mocked, the test proves your logic works *in isolation* — it says nothing about the interaction. | Write at least one integration test that uses real objects through the full callback/middleware chain. No mocks for the layers that interact. |
|
||||
| **Can failure leave orphaned state?** If your code persists state (DB row, cache, file) before calling an external service, what happens when the service fails? Does retry create duplicates? | Trace the failure path with real objects. If state is created before the risky call, test that failure cleans up or that retry is idempotent. |
|
||||
| **What other interfaces expose this?** Mixins, DSLs, alternative entry points (Agent vs Chat vs ChatMethods). | Grep for the method/behavior in related classes. If parity is needed, add it now — not as a follow-up. |
|
||||
| **Do error strategies align across layers?** Retry middleware + application fallback + framework error handling — do they conflict or create double execution? | List the specific error classes at each layer. Verify your rescue list matches what the lower layer actually raises. |
|
||||
|
||||
**When to skip:** Leaf-node changes with no callbacks, no state persistence, no parallel interfaces. If the change is purely additive (new helper method, new view partial), the check takes 10 seconds and the answer is "nothing fires, skip."
|
||||
|
||||
**When this matters most:** Any change that touches models with callbacks, error handling with fallback/retry, or functionality exposed through multiple interfaces.
|
||||
|
||||
**IMPORTANT**: Always update the original plan document by checking off completed items. Use the Edit tool to change `- [ ]` to `- [x]` for each task you finish. This keeps the plan as a living document showing progress and ensures no checkboxes are left unchecked.
|
||||
|
||||
2. **Incremental Commits**
|
||||
|
||||
After completing each task, evaluate whether to create an incremental commit:
|
||||
|
||||
| Commit when... | Don't commit when... |
|
||||
|----------------|---------------------|
|
||||
| Logical unit complete (model, service, component) | Small part of a larger unit |
|
||||
| Tests pass + meaningful progress | Tests failing |
|
||||
| About to switch contexts (backend → frontend) | Purely scaffolding with no behavior |
|
||||
| About to attempt risky/uncertain changes | Would need a "WIP" commit message |
|
||||
|
||||
**Heuristic:** "Can I write a commit message that describes a complete, valuable change? If yes, commit. If the message would be 'WIP' or 'partial X', wait."
|
||||
|
||||
**Commit workflow:**
|
||||
```bash
|
||||
# 1. Verify tests pass (use project's test command)
|
||||
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
||||
|
||||
# 2. Stage only files related to this logical unit (not `git add .`)
|
||||
git add <files related to this logical unit>
|
||||
|
||||
# 3. Commit with conventional message
|
||||
git commit -m "feat(scope): description of this unit"
|
||||
```
|
||||
|
||||
**Handling merge conflicts:** If conflicts arise during rebasing or merging, resolve them immediately. Incremental commits make conflict resolution easier since each commit is small and focused.
|
||||
|
||||
**Note:** Incremental commits use clean conventional messages without attribution footers. The final Phase 4 commit/PR includes the full attribution.
|
||||
|
||||
3. **Follow Existing Patterns**
|
||||
|
||||
- The plan should reference similar code - read those files first
|
||||
- Match naming conventions exactly
|
||||
- Reuse existing components where possible
|
||||
- Follow project coding standards (see CLAUDE.md)
|
||||
- When in doubt, grep for similar implementations
|
||||
|
||||
4. **Test Continuously**
|
||||
|
||||
- Run relevant tests after each significant change
|
||||
- Don't wait until the end to test
|
||||
- Fix failures immediately
|
||||
- Add new tests for new functionality
|
||||
- **Unit tests with mocks prove logic in isolation. Integration tests with real objects prove the layers work together.** If your change touches callbacks, middleware, or error handling — you need both.
|
||||
|
||||
5. **Figma Design Sync** (if applicable)
|
||||
|
||||
For UI work with Figma designs:
|
||||
|
||||
- Implement components following design specs
|
||||
- Use figma-design-sync agent iteratively to compare
|
||||
- Fix visual differences identified
|
||||
- Repeat until implementation matches design
|
||||
|
||||
6. **Track Progress**
|
||||
- Keep TodoWrite updated as you complete tasks
|
||||
- Note any blockers or unexpected discoveries
|
||||
- Create new tasks if scope expands
|
||||
- Keep user informed of major milestones
|
||||
|
||||
### Phase 3: Quality Check
|
||||
|
||||
1. **Run Core Quality Checks**
|
||||
|
||||
Always run before submitting:
|
||||
|
||||
```bash
|
||||
# Run full test suite (use project's test command)
|
||||
# Examples: bin/rails test, npm test, pytest, go test, etc.
|
||||
|
||||
# Run linting (per CLAUDE.md)
|
||||
# Use linting-agent before pushing to origin
|
||||
```
|
||||
|
||||
2. **Consider Reviewer Agents** (Optional)
|
||||
|
||||
Use for complex, risky, or large changes. Read agents from `compound-engineering.local.md` frontmatter (`review_agents`). If no settings file, invoke the `setup` skill to create one.
|
||||
|
||||
Run configured agents in parallel with Task tool. Present findings and address critical issues.
|
||||
|
||||
3. **Final Validation**
|
||||
- All TodoWrite tasks marked completed
|
||||
- All tests pass
|
||||
- Linting passes
|
||||
- Code follows existing patterns
|
||||
- Figma designs match (if applicable)
|
||||
- No console errors or warnings
|
||||
|
||||
4. **Prepare Operational Validation Plan** (REQUIRED)
|
||||
- Add a `## Post-Deploy Monitoring & Validation` section to the PR description for every change.
|
||||
- Include concrete:
|
||||
- Log queries/search terms
|
||||
- Metrics or dashboards to watch
|
||||
- Expected healthy signals
|
||||
- Failure signals and rollback/mitigation trigger
|
||||
- Validation window and owner
|
||||
- If there is truly no production/runtime impact, still include the section with: `No additional operational monitoring required` and a one-line reason.
|
||||
|
||||
### Phase 4: Ship It
|
||||
|
||||
1. **Create Commit**
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git status # Review what's being committed
|
||||
git diff --staged # Check the changes
|
||||
|
||||
# Commit with conventional format
|
||||
git commit -m "$(cat <<'EOF'
|
||||
feat(scope): description of what and why
|
||||
|
||||
Brief explanation if needed.
|
||||
|
||||
🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
|
||||
Co-Authored-By: Claude <noreply@anthropic.com>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
2. **Capture and Upload Screenshots for UI Changes** (REQUIRED for any UI work)
|
||||
|
||||
For **any** design changes, new views, or UI modifications, you MUST capture and upload screenshots:
|
||||
|
||||
**Step 1: Start dev server** (if not running)
|
||||
```bash
|
||||
bin/dev # Run in background
|
||||
```
|
||||
|
||||
**Step 2: Capture screenshots with agent-browser CLI**
|
||||
```bash
|
||||
agent-browser open http://localhost:3000/[route]
|
||||
agent-browser snapshot -i
|
||||
agent-browser screenshot output.png
|
||||
```
|
||||
See the `agent-browser` skill for detailed usage.
|
||||
|
||||
**Step 3: Upload using imgup skill**
|
||||
```bash
|
||||
skill: imgup
|
||||
# Then upload each screenshot:
|
||||
imgup -h pixhost screenshot.png # pixhost works without API key
|
||||
# Alternative hosts: catbox, imagebin, beeimg
|
||||
```
|
||||
|
||||
**What to capture:**
|
||||
- **New screens**: Screenshot of the new UI
|
||||
- **Modified screens**: Before AND after screenshots
|
||||
- **Design implementation**: Screenshot showing Figma design match
|
||||
|
||||
**IMPORTANT**: Always include uploaded image URLs in PR description. This provides visual context for reviewers and documents the change.
|
||||
|
||||
3. **Create Pull Request**
|
||||
|
||||
```bash
|
||||
git push -u origin feature-branch-name
|
||||
|
||||
gh pr create --title "Feature: [Description]" --body "$(cat <<'EOF'
|
||||
## Summary
|
||||
- What was built
|
||||
- Why it was needed
|
||||
- Key decisions made
|
||||
|
||||
## Testing
|
||||
- Tests added/modified
|
||||
- Manual testing performed
|
||||
|
||||
## Post-Deploy Monitoring & Validation
|
||||
- **What to monitor/search**
|
||||
- Logs:
|
||||
- Metrics/Dashboards:
|
||||
- **Validation checks (queries/commands)**
|
||||
- `command or query here`
|
||||
- **Expected healthy behavior**
|
||||
- Expected signal(s)
|
||||
- **Failure signal(s) / rollback trigger**
|
||||
- Trigger + immediate action
|
||||
- **Validation window & owner**
|
||||
- Window:
|
||||
- Owner:
|
||||
- **If no operational impact**
|
||||
- `No additional operational monitoring required: <reason>`
|
||||
|
||||
## Before / After Screenshots
|
||||
| Before | After |
|
||||
|--------|-------|
|
||||
|  |  |
|
||||
|
||||
## Figma Design
|
||||
[Link if applicable]
|
||||
|
||||
---
|
||||
|
||||
[](https://github.com/EveryInc/compound-engineering-plugin) 🤖 Generated with [Claude Code](https://claude.com/claude-code)
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
4. **Update Plan Status**
|
||||
|
||||
If the input document has YAML frontmatter with a `status` field, update it to `completed`:
|
||||
```
|
||||
status: active → status: completed
|
||||
```
|
||||
|
||||
5. **Notify User**
|
||||
- Summarize what was completed
|
||||
- Link to PR
|
||||
- Note any follow-up work needed
|
||||
- Suggest next steps if applicable
|
||||
|
||||
---
|
||||
|
||||
## Swarm Mode (Optional)
|
||||
|
||||
For complex plans with multiple independent workstreams, enable swarm mode for parallel execution with coordinated agents.
|
||||
|
||||
### When to Use Swarm Mode
|
||||
|
||||
| Use Swarm Mode when... | Use Standard Mode when... |
|
||||
|------------------------|---------------------------|
|
||||
| Plan has 5+ independent tasks | Plan is linear/sequential |
|
||||
| Multiple specialists needed (review + test + implement) | Single-focus work |
|
||||
| Want maximum parallelism | Simpler mental model preferred |
|
||||
| Large feature with clear phases | Small feature or bug fix |
|
||||
|
||||
### Enabling Swarm Mode
|
||||
|
||||
To trigger swarm execution, say:
|
||||
|
||||
> "Make a Task list and launch an army of agent swarm subagents to build the plan"
|
||||
|
||||
Or explicitly request: "Use swarm mode for this work"
|
||||
|
||||
### Swarm Workflow
|
||||
|
||||
When swarm mode is enabled, the workflow changes:
|
||||
|
||||
1. **Create Team**
|
||||
```
|
||||
Teammate({ operation: "spawnTeam", team_name: "work-{timestamp}" })
|
||||
```
|
||||
|
||||
2. **Create Task List with Dependencies**
|
||||
- Parse plan into TaskCreate items
|
||||
- Set up blockedBy relationships for sequential dependencies
|
||||
- Independent tasks have no blockers (can run in parallel)
|
||||
|
||||
3. **Spawn Specialized Teammates**
|
||||
```
|
||||
Task({
|
||||
team_name: "work-{timestamp}",
|
||||
name: "implementer",
|
||||
subagent_type: "general-purpose",
|
||||
prompt: "Claim implementation tasks, execute, mark complete",
|
||||
run_in_background: true
|
||||
})
|
||||
|
||||
Task({
|
||||
team_name: "work-{timestamp}",
|
||||
name: "tester",
|
||||
subagent_type: "general-purpose",
|
||||
prompt: "Claim testing tasks, run tests, mark complete",
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
4. **Coordinate and Monitor**
|
||||
- Team lead monitors task completion
|
||||
- Spawn additional workers as phases unblock
|
||||
- Handle plan approval if required
|
||||
|
||||
5. **Cleanup**
|
||||
```
|
||||
Teammate({ operation: "requestShutdown", target_agent_id: "implementer" })
|
||||
Teammate({ operation: "requestShutdown", target_agent_id: "tester" })
|
||||
Teammate({ operation: "cleanup" })
|
||||
```
|
||||
|
||||
See the `orchestrating-swarms` skill for detailed swarm patterns and best practices.
|
||||
|
||||
---
|
||||
|
||||
## Key Principles
|
||||
|
||||
### Start Fast, Execute Faster
|
||||
|
||||
- Get clarification once at the start, then execute
|
||||
- Don't wait for perfect understanding - ask questions and move
|
||||
- The goal is to **finish the feature**, not create perfect process
|
||||
|
||||
### The Plan is Your Guide
|
||||
|
||||
- Work documents should reference similar code and patterns
|
||||
- Load those references and follow them
|
||||
- Don't reinvent - match what exists
|
||||
|
||||
### Test As You Go
|
||||
|
||||
- Run tests after each change, not at the end
|
||||
- Fix failures immediately
|
||||
- Continuous testing prevents big surprises
|
||||
|
||||
### Quality is Built In
|
||||
|
||||
- Follow existing patterns
|
||||
- Write tests for new code
|
||||
- Run linting before pushing
|
||||
- Use reviewer agents for complex/risky changes only
|
||||
|
||||
### Ship Complete Features
|
||||
|
||||
- Mark all tasks completed before moving on
|
||||
- Don't leave features 80% done
|
||||
- A finished feature that ships beats a perfect feature that doesn't
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before creating PR, verify:
|
||||
|
||||
- [ ] All clarifying questions asked and answered
|
||||
- [ ] All TodoWrite tasks marked completed
|
||||
- [ ] Tests pass (run project's test command)
|
||||
- [ ] Linting passes (use linting-agent)
|
||||
- [ ] Code follows existing patterns
|
||||
- [ ] Figma designs match implementation (if applicable)
|
||||
- [ ] Before/after screenshots captured and uploaded (for UI changes)
|
||||
- [ ] Commit messages follow conventional format
|
||||
- [ ] PR description includes Post-Deploy Monitoring & Validation section (or explicit no-impact rationale)
|
||||
- [ ] PR description includes summary, testing notes, and screenshots
|
||||
- [ ] PR description includes Compound Engineered badge
|
||||
|
||||
## When to Use Reviewer Agents
|
||||
|
||||
**Don't use by default.** Use reviewer agents only when:
|
||||
|
||||
- Large refactor affecting many files (10+)
|
||||
- Security-sensitive changes (authentication, permissions, data access)
|
||||
- Performance-critical code paths
|
||||
- Complex algorithms or business logic
|
||||
- User explicitly requests thorough review
|
||||
|
||||
For most features: tests + linting + following patterns is sufficient.
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
- **Analysis paralysis** - Don't overthink, read the plan and execute
|
||||
- **Skipping clarifying questions** - Ask now, not after building wrong thing
|
||||
- **Ignoring plan references** - The plan has links for a reason
|
||||
- **Testing at the end** - Test continuously or suffer later
|
||||
- **Forgetting TodoWrite** - Track progress or lose track of what's done
|
||||
- **80% done syndrome** - Finish the feature, don't move on early
|
||||
- **Over-reviewing simple changes** - Save reviewer agents for complex work
|
||||
/ce:work $ARGUMENTS
|
||||
|
||||
@@ -131,7 +131,7 @@ topic: <kebab-case-topic>
|
||||
- [Any unresolved questions for the planning phase]
|
||||
|
||||
## Next Steps
|
||||
→ `/workflows:plan` for implementation details
|
||||
→ `/ce:plan` for implementation details
|
||||
```
|
||||
|
||||
**Output Location:** `docs/brainstorms/YYYY-MM-DD-<topic>-brainstorm.md`
|
||||
@@ -140,7 +140,7 @@ topic: <kebab-case-topic>
|
||||
|
||||
Present clear options for what to do next:
|
||||
|
||||
1. **Proceed to planning** → Run `/workflows:plan`
|
||||
1. **Proceed to planning** → Run `/ce:plan`
|
||||
2. **Refine further** → Continue exploring the design
|
||||
3. **Done for now** → User will return later
|
||||
|
||||
@@ -187,4 +187,4 @@ Planning answers **HOW** to build it:
|
||||
- Technical details and code patterns
|
||||
- Testing strategy and verification
|
||||
|
||||
When brainstorm output exists, `/workflows:plan` should detect it and use it as input, skipping its own idea refinement phase.
|
||||
When brainstorm output exists, `/ce:plan` should detect it and use it as input, skipping its own idea refinement phase.
|
||||
|
||||
@@ -36,7 +36,7 @@ Score the document against these criteria:
|
||||
| **Specificity** | Concrete enough for next step (brainstorm → can plan, plan → can implement) |
|
||||
| **YAGNI** | No hypothetical features, simplest approach chosen |
|
||||
|
||||
If invoked within a workflow (after `/workflows:brainstorm` or `/workflows:plan`), also check:
|
||||
If invoked within a workflow (after `/ce:brainstorm` or `/ce:plan`), also check:
|
||||
- **User intent fidelity** — Document reflects what was discussed, assumptions validated
|
||||
|
||||
## Step 4: Identify the Critical Improvement
|
||||
|
||||
@@ -185,7 +185,7 @@ Work logs serve as:
|
||||
|
||||
| Trigger | Flow | Tool |
|
||||
|---------|------|------|
|
||||
| Code review | `/workflows:review` → Findings → `/triage` → Todos | Review agent + skill |
|
||||
| Code review | `/ce: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 |
|
||||
|
||||
@@ -38,8 +38,8 @@ git worktree add .worktrees/feature-name -b feature-name main
|
||||
|
||||
Use this skill in these scenarios:
|
||||
|
||||
1. **Code Review (`/workflows:review`)**: If NOT already on the target branch (PR branch or requested 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 (`/ce:review`)**: If NOT already on the target branch (PR branch or requested branch), offer worktree for isolated review
|
||||
2. **Feature Work (`/ce: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
|
||||
|
||||
@@ -47,7 +47,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 `/ce:review` and `/ce:work` commands:
|
||||
|
||||
```
|
||||
# For review: offers worktree if not on PR branch
|
||||
@@ -204,7 +204,7 @@ bash ${CLAUDE_PLUGIN_ROOT}/skills/git-worktree/scripts/worktree-manager.sh clean
|
||||
|
||||
## Integration with Workflows
|
||||
|
||||
### `/workflows:review`
|
||||
### `/ce:review`
|
||||
|
||||
Instead of always creating a worktree:
|
||||
|
||||
@@ -217,7 +217,7 @@ Instead of always creating a worktree:
|
||||
- no → proceed with PR diff on current branch
|
||||
```
|
||||
|
||||
### `/workflows:work`
|
||||
### `/ce:work`
|
||||
|
||||
Always offer choice:
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ disable-model-invocation: true
|
||||
|
||||
# Compound Engineering Setup
|
||||
|
||||
Interactive setup for `compound-engineering.local.md` — configures which agents run during `/workflows:review` and `/workflows:work`.
|
||||
Interactive setup for `compound-engineering.local.md` — configures which agents run during `/ce:review` and `/ce:work`.
|
||||
|
||||
## Step 1: Check Existing Config
|
||||
|
||||
@@ -145,7 +145,7 @@ plan_review_agents: [{computed plan agent list}]
|
||||
# Review Context
|
||||
|
||||
Add project-specific review instructions here.
|
||||
These notes are passed to all review agents during /workflows:review and /workflows:work.
|
||||
These notes are passed to all review agents during /ce:review and /ce:work.
|
||||
|
||||
Examples:
|
||||
- "We use Turbo Frames heavily — check for frame-busting issues"
|
||||
|
||||
Reference in New Issue
Block a user