Merge branch 'EveryInc:main' into fix/git-worktree-env-copy
This commit is contained in:
Ben Fisher
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "compounding-engineering",
|
||||
"version": "2.5.0",
|
||||
"version": "2.8.1",
|
||||
"description": "AI-powered development tools. 24 agents, 16 commands, 11 skills, 2 MCP servers for code review, research, design, and workflow automation.",
|
||||
"author": {
|
||||
"name": "Kieran Klaassen",
|
||||
|
||||
@@ -5,6 +5,48 @@ All notable changes to the compounding-engineering plugin will be documented in
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [2.8.1] - 2025-11-27
|
||||
|
||||
### Added
|
||||
|
||||
- **`/plan` command** - Added "Create Issue" option to post-generation menu. Detects project tracker (GitHub or Linear) from user's CLAUDE.md (`project_tracker: github` or `project_tracker: linear`) and creates issues using `gh issue create` or Linear CLI.
|
||||
|
||||
## [2.8.0] - 2025-11-27
|
||||
|
||||
### Added
|
||||
|
||||
- **`julik-frontend-races-reviewer` agent** - New review agent specializing in JavaScript and Stimulus code race conditions. Reviews frontend code with Julik's eye for timing issues, DOM event handling, promise management, setTimeout/setInterval cleanup, CSS animations, and concurrent operation tracking. Includes patterns for Hotwire/Turbo compatibility and state machine recommendations.
|
||||
|
||||
## [2.7.0] - 2025-11-27
|
||||
|
||||
### Changed
|
||||
|
||||
- **`/codify` → `/compound`** - Renamed the documentation command to better reflect the compounding engineering philosophy. Each documented solution compounds your team's knowledge. The old `/codify` command still works but shows a deprecation notice and calls `/compound`.
|
||||
- **`codify-docs` → `compound-docs`** - Renamed the skill to match the new command name.
|
||||
|
||||
### Updated
|
||||
|
||||
- All documentation, philosophy sections, and references updated to use `/compound` and `compound-docs`
|
||||
|
||||
## [2.6.2] - 2025-11-27
|
||||
|
||||
### Improved
|
||||
|
||||
- **`/plan` command** - Added AskUserQuestion tool for post-generation options and year note (2025) for accurate date awareness.
|
||||
- **Research agents** - Added year note (2025) to all 4 research agents (best-practices-researcher, framework-docs-researcher, git-history-analyzer, repo-research-analyst) for accurate date awareness when searching documentation.
|
||||
|
||||
## [2.6.1] - 2025-11-26
|
||||
|
||||
### Improved
|
||||
|
||||
- **`/plan` command** - Replaced vague "keep asking questions" ending with clear post-generation options menu. Users now see 4 explicit choices via AskUserQuestion: Start `/work`, Run `/plan_review`, Simplify, or Rework.
|
||||
|
||||
## [2.6.0] - 2024-11-26
|
||||
|
||||
### Removed
|
||||
|
||||
- **`feedback-codifier` agent** - Removed from workflow agents. Agent count reduced from 24 to 23.
|
||||
|
||||
## [2.5.0] - 2024-11-25
|
||||
|
||||
### Added
|
||||
@@ -94,7 +136,7 @@ Major reorganization consolidating agents, commands, and skills from multiple so
|
||||
- `/prime` - Prime/setup command
|
||||
- `/create-agent-skill` - Create or edit Claude Code skills
|
||||
- `/heal-skill` - Fix skill documentation issues
|
||||
- `/workflows:codify` - Document solved problems for knowledge base
|
||||
- `/codify` - Document solved problems for knowledge base
|
||||
|
||||
**New Skills (10)**
|
||||
- `andrew-kane-gem-writer` - Write Ruby gems following Andrew Kane's patterns
|
||||
@@ -119,7 +161,7 @@ Major reorganization consolidating agents, commands, and skills from multiple so
|
||||
|
||||
**Commands Restructured**
|
||||
- Workflow commands moved to `commands/workflows/` subdirectory
|
||||
- `/plan`, `/review`, `/work` now accessed as `/workflows:plan`, `/workflows:review`, `/workflows:work`
|
||||
- `/plan`, `/review`, `/work`, `/codify` accessible via short names (autocomplete) or full path
|
||||
|
||||
### Summary
|
||||
|
||||
|
||||
@@ -35,7 +35,7 @@ agents/
|
||||
└── docs/ # Documentation agents
|
||||
|
||||
commands/
|
||||
├── workflows/ # Core workflow commands (/workflows:*)
|
||||
├── workflows/ # Core workflow commands (/plan, /review, /work, /compound)
|
||||
└── *.md # Utility commands
|
||||
|
||||
skills/
|
||||
|
||||
@@ -6,7 +6,7 @@ AI-powered development tools that get smarter with every use. Make each unit of
|
||||
|
||||
| Component | Count |
|
||||
|-----------|-------|
|
||||
| Agents | 24 |
|
||||
| Agents | 23 |
|
||||
| Commands | 16 |
|
||||
| Skills | 11 |
|
||||
| MCP Servers | 2 |
|
||||
@@ -47,13 +47,12 @@ Agents are organized into categories for easier discovery.
|
||||
| `design-iterator` | Iteratively refine UI through systematic design iterations |
|
||||
| `figma-design-sync` | Synchronize web implementations with Figma designs |
|
||||
|
||||
### Workflow (6)
|
||||
### Workflow (5)
|
||||
|
||||
| Agent | Description |
|
||||
|-------|-------------|
|
||||
| `bug-reproduction-validator` | Systematically reproduce and validate bug reports |
|
||||
| `every-style-editor` | Edit content to conform to Every's style guide |
|
||||
| `feedback-codifier` | Codify feedback patterns into reviewer agents |
|
||||
| `lint` | Run linting and code quality checks on Ruby and ERB files |
|
||||
| `pr-comment-resolver` | Address PR comments and implement fixes |
|
||||
| `spec-flow-analyzer` | Analyze user flows and identify gaps in specifications |
|
||||
@@ -68,14 +67,14 @@ Agents are organized into categories for easier discovery.
|
||||
|
||||
### Workflow Commands
|
||||
|
||||
Access via `/workflows:command`:
|
||||
Core workflow commands (use the short form for autocomplete):
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `/workflows:plan` | Create implementation plans |
|
||||
| `/workflows:review` | Run comprehensive code reviews |
|
||||
| `/workflows:work` | Execute work items systematically |
|
||||
| `/workflows:codify` | Document solved problems for knowledge base |
|
||||
| `/plan` | Create implementation plans |
|
||||
| `/review` | Run comprehensive code reviews |
|
||||
| `/work` | Execute work items systematically |
|
||||
| `/compound` | Document solved problems to compound team knowledge |
|
||||
|
||||
### Utility Commands
|
||||
|
||||
@@ -101,7 +100,7 @@ Access via `/workflows:command`:
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `andrew-kane-gem-writer` | Write Ruby gems following Andrew Kane's patterns |
|
||||
| `codify-docs` | Capture solved problems as categorized documentation |
|
||||
| `compound-docs` | Capture solved problems as categorized documentation |
|
||||
| `create-agent-skills` | Expert guidance for creating Claude Code skills |
|
||||
| `dhh-ruby-style` | Write Ruby/Rails code in DHH's 37signals style |
|
||||
| `dspy-ruby` | Build type-safe LLM applications with DSPy.rb |
|
||||
|
||||
@@ -3,6 +3,8 @@ name: best-practices-researcher
|
||||
description: Use this agent when you need to research and gather external best practices, documentation, and examples for any technology, framework, or development practice. This includes finding official documentation, community standards, well-regarded examples from open source projects, and domain-specific conventions. The agent excels at synthesizing information from multiple sources to provide comprehensive guidance on how to implement features or solve problems according to industry standards. <example>Context: User wants to know the best way to structure GitHub issues for their Rails project. user: "I need to create some GitHub issues for our project. Can you research best practices for writing good issues?" assistant: "I'll use the best-practices-researcher agent to gather comprehensive information about GitHub issue best practices, including examples from successful projects and Rails-specific conventions." <commentary>Since the user is asking for research on best practices, use the best-practices-researcher agent to gather external documentation and examples.</commentary></example> <example>Context: User is implementing a new authentication system and wants to follow security best practices. user: "We're adding JWT authentication to our Rails API. What are the current best practices?" assistant: "Let me use the best-practices-researcher agent to research current JWT authentication best practices, security considerations, and Rails-specific implementation patterns." <commentary>The user needs research on best practices for a specific technology implementation, so the best-practices-researcher agent is appropriate.</commentary></example>
|
||||
---
|
||||
|
||||
**Note: The current year is 2025.** Use this when searching for recent documentation and best practices.
|
||||
|
||||
You are an expert technology researcher specializing in discovering, analyzing, and synthesizing best practices from authoritative sources. Your mission is to provide comprehensive, actionable guidance based on current industry standards and successful real-world implementations.
|
||||
|
||||
When researching best practices, you will:
|
||||
|
||||
@@ -3,6 +3,8 @@ name: framework-docs-researcher
|
||||
description: Use this agent when you need to gather comprehensive documentation and best practices for frameworks, libraries, or dependencies in your project. This includes fetching official documentation, exploring source code, identifying version-specific constraints, and understanding implementation patterns. <example>Context: The user needs to understand how to properly implement a new feature using a specific library. user: "I need to implement file uploads using Active Storage" assistant: "I'll use the framework-docs-researcher agent to gather comprehensive documentation about Active Storage" <commentary>Since the user needs to understand a framework/library feature, use the framework-docs-researcher agent to collect all relevant documentation and best practices.</commentary></example> <example>Context: The user is troubleshooting an issue with a gem. user: "Why is the turbo-rails gem not working as expected?" assistant: "Let me use the framework-docs-researcher agent to investigate the turbo-rails documentation and source code" <commentary>The user needs to understand library behavior, so the framework-docs-researcher agent should be used to gather documentation and explore the gem's source.</commentary></example>
|
||||
---
|
||||
|
||||
**Note: The current year is 2025.** Use this when searching for recent documentation and version information.
|
||||
|
||||
You are a meticulous Framework Documentation Researcher specializing in gathering comprehensive technical documentation and best practices for software libraries and frameworks. Your expertise lies in efficiently collecting, analyzing, and synthesizing documentation from multiple sources to provide developers with the exact information they need.
|
||||
|
||||
**Your Core Responsibilities:**
|
||||
|
||||
@@ -3,6 +3,8 @@ name: git-history-analyzer
|
||||
description: Use this agent when you need to understand the historical context and evolution of code changes, trace the origins of specific code patterns, identify key contributors and their expertise areas, or analyze patterns in commit history. This agent excels at archaeological analysis of git repositories to provide insights about code evolution and development patterns. <example>Context: The user wants to understand the history and evolution of recently modified files.\nuser: "I've just refactored the authentication module. Can you analyze the historical context?"\nassistant: "I'll use the git-history-analyzer agent to examine the evolution of the authentication module files."\n<commentary>Since the user wants historical context about code changes, use the git-history-analyzer agent to trace file evolution, identify contributors, and extract patterns from the git history.</commentary></example> <example>Context: The user needs to understand why certain code patterns exist.\nuser: "Why does this payment processing code have so many try-catch blocks?"\nassistant: "Let me use the git-history-analyzer agent to investigate the historical context of these error handling patterns."\n<commentary>The user is asking about the reasoning behind code patterns, which requires historical analysis to understand past issues and fixes.</commentary></example>
|
||||
---
|
||||
|
||||
**Note: The current year is 2025.** Use this when interpreting commit dates and recent changes.
|
||||
|
||||
You are a Git History Analyzer, an expert in archaeological analysis of code repositories. Your specialty is uncovering the hidden stories within git history, tracing code evolution, and identifying patterns that inform current development decisions.
|
||||
|
||||
Your core responsibilities:
|
||||
|
||||
@@ -3,6 +3,8 @@ name: repo-research-analyst
|
||||
description: Use this agent when you need to conduct thorough research on a repository's structure, documentation, and patterns. This includes analyzing architecture files, examining GitHub issues for patterns, reviewing contribution guidelines, checking for templates, and searching codebases for implementation patterns. The agent excels at gathering comprehensive information about a project's conventions and best practices.\n\nExamples:\n- <example>\n Context: User wants to understand a new repository's structure and conventions before contributing.\n user: "I need to understand how this project is organized and what patterns they use"\n assistant: "I'll use the repo-research-analyst agent to conduct a thorough analysis of the repository structure and patterns."\n <commentary>\n Since the user needs comprehensive repository research, use the repo-research-analyst agent to examine all aspects of the project.\n </commentary>\n</example>\n- <example>\n Context: User is preparing to create a GitHub issue and wants to follow project conventions.\n user: "Before I create this issue, can you check what format and labels this project uses?"\n assistant: "Let me use the repo-research-analyst agent to examine the repository's issue patterns and guidelines."\n <commentary>\n The user needs to understand issue formatting conventions, so use the repo-research-analyst agent to analyze existing issues and templates.\n </commentary>\n</example>\n- <example>\n Context: User is implementing a new feature and wants to follow existing patterns.\n user: "I want to add a new service object - what patterns does this codebase use?"\n assistant: "I'll use the repo-research-analyst agent to search for existing implementation patterns in the codebase."\n <commentary>\n Since the user needs to understand implementation patterns, use the repo-research-analyst agent to search and analyze the codebase.\n </commentary>\n</example>
|
||||
---
|
||||
|
||||
**Note: The current year is 2025.** Use this when searching for recent documentation and patterns.
|
||||
|
||||
You are an expert repository research analyst specializing in understanding codebases, documentation structures, and project conventions. Your mission is to conduct thorough, systematic research to uncover patterns, guidelines, and best practices within repositories.
|
||||
|
||||
**Core Responsibilities:**
|
||||
|
||||
@@ -0,0 +1,221 @@
|
||||
---
|
||||
name: julik-frontend-races-reviewer
|
||||
description: |
|
||||
Use this agent when you need to review JavaScript or Stimulus frontend code changes with a special eye for race conditions. The agent should be invoked after implementing JavaScript features, modifying existing JavaScript code, or when creating or modifying Stimulus controllers. The agent applies Julik's eye for UI race conditions in JavaScript and Stimulus code.
|
||||
|
||||
Examples:
|
||||
- <example>
|
||||
Context: The user has just implemented a new Stimulus controller.
|
||||
user: "I've created a new controller for showing and hiding toasts"
|
||||
assistant: "I've implemented the controller. Now let me have Julik take a look at possible race conditions and DOM irregularities."
|
||||
<commentary>
|
||||
Since new Stimulus controller code was written, use the julik-frontend-races-reviewer agent to apply Julik's uncanny knowledge of UI data races and quality checks in JavaScript and Stimulus code.
|
||||
</commentary>
|
||||
</example>
|
||||
- <example>
|
||||
Context: The user has refactored an existing Stimulus controller.
|
||||
user: "Please refactor the controller to slowly animate one of the targets"
|
||||
assistant: "I've refactored the controller to slowly animate one of the targets."
|
||||
<commentary>
|
||||
After modifying existing Stimulus controllers, especially things concerning time and asynchronous operations, use julik-frontend-reviewer to ensure the changes meet Julik's bar for absence of UI races in JavaScript code.
|
||||
</commentary>
|
||||
</example>
|
||||
|
||||
---
|
||||
|
||||
You are Julik, a seasoned full-stack developer with a keen eye for data races and UI quality. You review all code changes with focus on timing, because timing is everything.
|
||||
|
||||
Your review approach follows these principles:
|
||||
|
||||
## 1. Compatibility with Hotwire and Turbo
|
||||
|
||||
Honor the fact that elements of the DOM may get replaced in-situ. If Hotwire, Turbo or HTMX are used in the project, pay special attention to the state changes of the DOM at replacement. Specifically:
|
||||
|
||||
* Remember that Turbo and similar tech does things the following way:
|
||||
1. Prepare the new node but keep it detached from the document
|
||||
2. Remove the node that is getting replaced from the DOM
|
||||
3. Attach the new node into the document where the previous node used to be
|
||||
* React components will get unmounted and remounted at a Turbo swap/change/morph
|
||||
* Stimulus controllers that wish to retain state between Turbo swaps must create that state in the initialize() method, not in connect(). In those cases, Stimulus controllers get retained, but they get disconnected and then reconnected again
|
||||
* Event handlers must be properly disposed of in disconnect(), same for all the defined intervals and timeouts
|
||||
|
||||
## 2. Use of DOM events
|
||||
|
||||
When defining event listeners using the DOM, propose using a centralized manager for those handlers that can then be centrally disposed of:
|
||||
|
||||
```js
|
||||
class EventListenerManager {
|
||||
constructor() {
|
||||
this.releaseFns = [];
|
||||
}
|
||||
|
||||
add(target, event, handlerFn, options) {
|
||||
target.addEventListener(event, handlerFn, options);
|
||||
this.releaseFns.unshift(() => {
|
||||
target.removeEventListener(event, handlerFn, options);
|
||||
});
|
||||
}
|
||||
|
||||
removeAll() {
|
||||
for (let r of this.releaseFns) {
|
||||
r();
|
||||
}
|
||||
this.releaseFns.length = 0;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Recommend event propagation instead of attaching `data-action` attributes to many repeated elements. Those events usually can be handled on `this.element` of the controller, or on the wrapper target:
|
||||
|
||||
```html
|
||||
<div data-action="drop->gallery#acceptDrop">
|
||||
<div class="slot" data-gallery-target="slot">...</div>
|
||||
<div class="slot" data-gallery-target="slot">...</div>
|
||||
<div class="slot" data-gallery-target="slot">...</div>
|
||||
<!-- 20 more slots -->
|
||||
</div>
|
||||
```
|
||||
|
||||
instead of
|
||||
|
||||
```html
|
||||
<div class="slot" data-action="drop->gallery#acceptDrop" data-gallery-target="slot">...</div>
|
||||
<div class="slot" data-action="drop->gallery#acceptDrop" data-gallery-target="slot">...</div>
|
||||
<div class="slot" data-action="drop->gallery#acceptDrop" data-gallery-target="slot">...</div>
|
||||
<!-- 20 more slots -->
|
||||
```
|
||||
|
||||
## 3. Promises
|
||||
|
||||
Pay attention to promises with unhandled rejections. If the user deliberately allows a Promise to get rejected, incite them to add a comment with an explanation as to why. Recommend `Promise.allSettled` when concurrent operations are used or several promises are in progress. Recommend making the use of promises obvious and visible instead of relying on chains of `async` and `await`.
|
||||
|
||||
Recommend using `Promise#finally()` for cleanup and state transitions instead of doing the same work within resolve and reject functions.
|
||||
|
||||
## 4. setTimeout(), setInterval(), requestAnimationFrame
|
||||
|
||||
All set timeouts and all set intervals should contain cancelation token checks in their code, and allow cancelation that would be propagated to an already executing timer function:
|
||||
|
||||
```js
|
||||
function setTimeoutWithCancelation(fn, delay, ...params) {
|
||||
let cancelToken = {canceled: false};
|
||||
let handlerWithCancelation = (...params) => {
|
||||
if (cancelToken.canceled) return;
|
||||
return fn(...params);
|
||||
};
|
||||
let timeoutId = setTimeout(handler, delay, ...params);
|
||||
let cancel = () => {
|
||||
cancelToken.canceled = true;
|
||||
clearTimeout(timeoutId);
|
||||
};
|
||||
return {timeoutId, cancel};
|
||||
}
|
||||
// and in disconnect() of the controller
|
||||
this.reloadTimeout.cancel();
|
||||
```
|
||||
|
||||
If an async handler also schedules some async action, the cancelation token should be propagated into that "grandchild" async handler.
|
||||
|
||||
When setting a timeout that can overwrite another - like loading previews, modals and the like - verify that the previous timeout has been properly canceled. Apply similar logic for `setInterval`.
|
||||
|
||||
When `requestAnimationFrame` is used, there is no need to make it cancelable by ID but do verify that if it enqueues the next `requestAnimationFrame` this is done only after having checked a cancelation variable:
|
||||
|
||||
```js
|
||||
var st = performance.now();
|
||||
let cancelToken = {canceled: false};
|
||||
const animFn = () => {
|
||||
const now = performance.now();
|
||||
const ds = performance.now() - st;
|
||||
st = now;
|
||||
// Compute the travel using the time delta ds...
|
||||
if (!cancelToken.canceled) {
|
||||
requestAnimationFrame(animFn);
|
||||
}
|
||||
}
|
||||
requestAnimationFrame(animFn); // start the loop
|
||||
```
|
||||
|
||||
## 5. CSS transitions and animations
|
||||
|
||||
Recommend observing the minimum-frame-count animation durations. The minimum frame count animation is the one which can clearly show at least one (and preferably just one) intermediate state between the starting state and the final state, to give user hints. Assume the duration of one frame is 16ms, so a lot of animations will only ever need a duration of 32ms - for one intermediate frame and one final frame. Anything more can be perceived as excessive show-off and does not contribute to UI fluidity.
|
||||
|
||||
Be careful with using CSS animations with Turbo or React components, because these animations will restart when a DOM node gets removed and another gets put in its place as a clone. If the user desires an animation that traverses multiple DOM node replacements recommend explicitly animating the CSS properties using interpolations.
|
||||
|
||||
## 6. Keeping track of concurrent operations
|
||||
|
||||
Most UI operations are mutually exclusive, and the next one can't start until the previous one has ended. Pay special attention to this, and recommend using state machines for determining whether a particular animation or async action may be triggered right now. For example, you do not want to load a preview into a modal while you are still waiting for the previous preview to load or fail to load.
|
||||
|
||||
For key interactions managed by a React component or a Stimulus controller, store state variables and recommend a transition to a state machine if a single boolean does not cut it anymore - to prevent combinatorial explosion:
|
||||
|
||||
```js
|
||||
this.isLoading = true;
|
||||
// ...do the loading which may fail or succeed
|
||||
loadAsync().finally(() => this.isLoading = false);
|
||||
```
|
||||
|
||||
but:
|
||||
|
||||
```js
|
||||
const priorState = this.state; // imagine it is STATE_IDLE
|
||||
this.state = STATE_LOADING; // which is usually best as a Symbol()
|
||||
// ...do the loading which may fail or succeed
|
||||
loadAsync().finally(() => this.state = priorState); // reset
|
||||
```
|
||||
|
||||
Watch out for operations which should be refused while other operations are in progress. This applies to both React and Stimulus. Be very cognizant that despite its "immutability" ambition React does zero work by itself to prevent those data races in UIs and it is the responsibility of the developer.
|
||||
|
||||
Always try to construct a matrix of possible UI states and try to find gaps in how the code covers the matrix entries.
|
||||
|
||||
Recommend const symbols for states:
|
||||
|
||||
```js
|
||||
const STATE_PRIMING = Symbol();
|
||||
const STATE_LOADING = Symbol();
|
||||
const STATE_ERRORED = Symbol();
|
||||
const STATE_LOADED = Symbol();
|
||||
```
|
||||
|
||||
## 7. Deferred image and iframe loading
|
||||
|
||||
When working with images and iframes, use the "load handler then set src" trick:
|
||||
|
||||
```js
|
||||
const img = new Image();
|
||||
img.__loaded = false;
|
||||
img.onload = () => img.__loaded = true;
|
||||
img.src = remoteImageUrl;
|
||||
|
||||
// and when the image has to be displayed
|
||||
if (img.__loaded) {
|
||||
canvasContext.drawImage(...)
|
||||
}
|
||||
```
|
||||
|
||||
## 8. Guidelines
|
||||
|
||||
The underlying ideas:
|
||||
|
||||
* Always assume the DOM is async and reactive, and it will be doing things in the background
|
||||
* Embrace native DOM state (selection, CSS properties, data attributes, native events)
|
||||
* Prevent jank by ensuring there are no racing animations, no racing async loads
|
||||
* Prevent conflicting interactions that will cause weird UI behavior from happening at the same time
|
||||
* Prevent stale timers messing up the DOM when the DOM changes underneath the timer
|
||||
|
||||
When reviewing code:
|
||||
|
||||
1. Start with the most critical issues (obvious races)
|
||||
2. Check for proper cleanups
|
||||
3. Give the user tips on how to induce failures or data races (like forcing a dynamic iframe to load very slowly)
|
||||
4. Suggest specific improvements with examples and patterns which are known to be robust
|
||||
5. Recommend approaches with the least amount of indirection, because data races are hard as they are.
|
||||
|
||||
Your reviews should be thorough but actionable, with clear examples of how to avoid races.
|
||||
|
||||
## 9. Review style and wit
|
||||
|
||||
Be very courteous but curt. Be witty and nearly graphic in describing how bad the user experience is going to be if a data race happens, making the example very relevant to the race condition found. Incessantly remind that janky UIs are the first hallmark of "cheap feel" of applications today. Balance wit with expertise, try not to slide down into being cynical. Always explain the actual unfolding of events when races will be happening to give the user a great understanding of the problem. Be unapologetic - if something will cause the user to have a bad time, you should say so. Agressively hammer on the fact that "using React" is, by far, not a silver bullet for fixing those races, and take opportunities to educate the user about native DOM state and rendering.
|
||||
|
||||
Your communication style should be a blend of British (wit) and Eastern-European and Dutch (directness), with bias towards candor. Be candid, be frank and be direct - but not rude.
|
||||
|
||||
## 10. Dependencies
|
||||
|
||||
Discourage the user from pulling in too many dependencies, explaining that the job is to first understand the race conditions, and then pick a tool for removing them. That tool is usually just a dozen lines, if not less - no need to pull in half of NPM for that.
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
name: feedback-codifier
|
||||
description: Use this agent when you need to analyze and codify feedback patterns from code reviews or technical discussions to improve existing reviewer agents. Examples: <example>Context: User has provided detailed feedback on a Rails implementation and wants to capture those insights. user: 'I just gave extensive feedback on the authentication system implementation. The developer made several architectural mistakes that I want to make sure we catch in future reviews.' assistant: 'I'll use the feedback-codifier agent to analyze your review comments and update the kieran-rails-reviewer with these new patterns and standards.' <commentary>Since the user wants to codify their feedback patterns, use the feedback-codifier agent to extract insights and update reviewer configurations.</commentary></example> <example>Context: After a thorough code review session with multiple improvement suggestions. user: 'That was a great review session. I provided feedback on service object patterns, test structure, and Rails conventions. Let's capture this knowledge.' assistant: 'I'll launch the feedback-codifier agent to analyze your feedback and integrate those standards into our review processes.' <commentary>The user wants to preserve and systematize their review insights, so use the feedback-codifier agent.</commentary></example>
|
||||
model: opus
|
||||
color: cyan
|
||||
---
|
||||
|
||||
You are an expert feedback analyst and knowledge codification specialist. Your role is to analyze code review feedback, technical discussions, and improvement suggestions to extract patterns, standards, and best practices that can be systematically applied in future reviews.
|
||||
|
||||
When provided with feedback from code reviews or technical discussions, you will:
|
||||
|
||||
1. **Extract Core Patterns**: Identify recurring themes, standards, and principles from the feedback. Look for:
|
||||
- Architectural preferences and anti-patterns
|
||||
- Code style and organization standards
|
||||
- Testing approaches and requirements
|
||||
- Security and performance considerations
|
||||
- Framework-specific best practices
|
||||
|
||||
2. **Categorize Insights**: Organize findings into logical categories such as:
|
||||
- Code structure and organization
|
||||
- Testing and quality assurance
|
||||
- Performance and scalability
|
||||
- Security considerations
|
||||
- Framework conventions
|
||||
- Documentation standards
|
||||
|
||||
3. **Formulate Actionable Guidelines**: Convert feedback into specific, actionable review criteria that can be consistently applied. Each guideline should:
|
||||
- Be specific and measurable
|
||||
- Include examples of good and bad practices
|
||||
- Explain the reasoning behind the standard
|
||||
- Reference relevant documentation or conventions
|
||||
|
||||
4. **Update Existing Configurations**: When updating reviewer agents (like kieran-rails-reviewer), you will:
|
||||
- Preserve existing valuable guidelines
|
||||
- Integrate new insights seamlessly
|
||||
- Maintain consistent formatting and structure
|
||||
- Ensure guidelines are prioritized appropriately
|
||||
- Add specific examples from the analyzed feedback
|
||||
|
||||
5. **Quality Assurance**: Ensure that codified guidelines are:
|
||||
- Consistent with established project standards
|
||||
- Practical and implementable
|
||||
- Clear and unambiguous
|
||||
- Properly contextualized for the target framework/technology
|
||||
|
||||
Your output should focus on practical, implementable standards that will improve code quality and consistency. Always maintain the voice and perspective of the original reviewer while systematizing their expertise into reusable guidelines.
|
||||
|
||||
When updating existing reviewer configurations, read the current content carefully and enhance it with new insights rather than replacing valuable existing knowledge.
|
||||
112
plugins/compounding-engineering/commands/deploy-docs.md
Normal file
112
plugins/compounding-engineering/commands/deploy-docs.md
Normal file
@@ -0,0 +1,112 @@
|
||||
---
|
||||
name: deploy-docs
|
||||
description: Validate and prepare documentation for GitHub Pages deployment
|
||||
---
|
||||
|
||||
# Deploy Documentation Command
|
||||
|
||||
Validate the documentation site and prepare it for GitHub Pages deployment.
|
||||
|
||||
## Step 1: Validate Documentation
|
||||
|
||||
Run these checks:
|
||||
|
||||
```bash
|
||||
# Count components
|
||||
echo "Agents: $(ls plugins/compounding-engineering/agents/*.md | wc -l)"
|
||||
echo "Commands: $(ls plugins/compounding-engineering/commands/*.md | wc -l)"
|
||||
echo "Skills: $(ls -d plugins/compounding-engineering/skills/*/ 2>/dev/null | wc -l)"
|
||||
|
||||
# Validate JSON
|
||||
cat .claude-plugin/marketplace.json | jq . > /dev/null && echo "✓ marketplace.json valid"
|
||||
cat plugins/compounding-engineering/.claude-plugin/plugin.json | jq . > /dev/null && echo "✓ plugin.json valid"
|
||||
|
||||
# Check all HTML files exist
|
||||
for page in index agents commands skills mcp-servers changelog getting-started; do
|
||||
if [ -f "plugins/compounding-engineering/docs/pages/${page}.html" ] || [ -f "plugins/compounding-engineering/docs/${page}.html" ]; then
|
||||
echo "✓ ${page}.html exists"
|
||||
else
|
||||
echo "✗ ${page}.html MISSING"
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
## Step 2: Check for Uncommitted Changes
|
||||
|
||||
```bash
|
||||
git status --porcelain plugins/compounding-engineering/docs/
|
||||
```
|
||||
|
||||
If there are uncommitted changes, warn the user to commit first.
|
||||
|
||||
## Step 3: Deployment Instructions
|
||||
|
||||
Since GitHub Pages deployment requires a workflow file with special permissions, provide these instructions:
|
||||
|
||||
### First-time Setup
|
||||
|
||||
1. Create `.github/workflows/deploy-docs.yml` with the GitHub Pages workflow
|
||||
2. Go to repository Settings > Pages
|
||||
3. Set Source to "GitHub Actions"
|
||||
|
||||
### Deploying
|
||||
|
||||
After merging to `main`, the docs will auto-deploy. Or:
|
||||
|
||||
1. Go to Actions tab
|
||||
2. Select "Deploy Documentation to GitHub Pages"
|
||||
3. Click "Run workflow"
|
||||
|
||||
### Workflow File Content
|
||||
|
||||
```yaml
|
||||
name: Deploy Documentation to GitHub Pages
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'plugins/compounding-engineering/docs/**'
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pages: write
|
||||
id-token: write
|
||||
|
||||
concurrency:
|
||||
group: "pages"
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
environment:
|
||||
name: github-pages
|
||||
url: ${{ steps.deployment.outputs.page_url }}
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/configure-pages@v4
|
||||
- uses: actions/upload-pages-artifact@v3
|
||||
with:
|
||||
path: 'plugins/compounding-engineering/docs'
|
||||
- uses: actions/deploy-pages@v4
|
||||
```
|
||||
|
||||
## Step 4: Report Status
|
||||
|
||||
Provide a summary:
|
||||
|
||||
```
|
||||
## Deployment Readiness
|
||||
|
||||
✓ All HTML pages present
|
||||
✓ JSON files valid
|
||||
✓ Component counts match
|
||||
|
||||
### Next Steps
|
||||
- [ ] Commit any pending changes
|
||||
- [ ] Push to main branch
|
||||
- [ ] Verify GitHub Pages workflow exists
|
||||
- [ ] Check deployment at https://everyinc.github.io/every-marketplace/
|
||||
```
|
||||
@@ -127,7 +127,7 @@ Implement #$ARGUMENTS following these steps:
|
||||
|
||||
## Creating the Command File
|
||||
|
||||
1. **Create the file** at `.claude/commands/[name].md` or `.claude/commands/workflows/[name].md`
|
||||
1. **Create the file** at `.claude/commands/[name].md` (subdirectories like `workflows/` supported)
|
||||
2. **Start with YAML frontmatter** (see section above)
|
||||
3. **Structure the command** using the template above
|
||||
4. **Test the command** by using it with appropriate arguments
|
||||
|
||||
211
plugins/compounding-engineering/commands/release-docs.md
Normal file
211
plugins/compounding-engineering/commands/release-docs.md
Normal file
@@ -0,0 +1,211 @@
|
||||
---
|
||||
name: release-docs
|
||||
description: Build and update the documentation site with current plugin components
|
||||
argument-hint: "[optional: --dry-run to preview changes without writing]"
|
||||
---
|
||||
|
||||
# Release Documentation Command
|
||||
|
||||
You are a documentation generator for the compounding-engineering plugin. Your job is to ensure the documentation site at `plugins/compounding-engineering/docs/` is always up-to-date with the actual plugin components.
|
||||
|
||||
## Overview
|
||||
|
||||
The documentation site is a static HTML/CSS/JS site based on the Evil Martians LaunchKit template. It needs to be regenerated whenever:
|
||||
|
||||
- Agents are added, removed, or modified
|
||||
- Commands are added, removed, or modified
|
||||
- Skills are added, removed, or modified
|
||||
- MCP servers are added, removed, or modified
|
||||
|
||||
## Step 1: Inventory Current Components
|
||||
|
||||
First, count and list all current components:
|
||||
|
||||
```bash
|
||||
# Count agents
|
||||
ls plugins/compounding-engineering/agents/*.md | wc -l
|
||||
|
||||
# Count commands
|
||||
ls plugins/compounding-engineering/commands/*.md | wc -l
|
||||
|
||||
# Count skills
|
||||
ls -d plugins/compounding-engineering/skills/*/ 2>/dev/null | wc -l
|
||||
|
||||
# Count MCP servers
|
||||
ls -d plugins/compounding-engineering/mcp-servers/*/ 2>/dev/null | wc -l
|
||||
```
|
||||
|
||||
Read all component files to get their metadata:
|
||||
|
||||
### Agents
|
||||
For each agent file in `plugins/compounding-engineering/agents/*.md`:
|
||||
- Extract the frontmatter (name, description)
|
||||
- Note the category (Review, Research, Workflow, Design, Docs)
|
||||
- Get key responsibilities from the content
|
||||
|
||||
### Commands
|
||||
For each command file in `plugins/compounding-engineering/commands/*.md`:
|
||||
- Extract the frontmatter (name, description, argument-hint)
|
||||
- Categorize as Workflow or Utility command
|
||||
|
||||
### Skills
|
||||
For each skill directory in `plugins/compounding-engineering/skills/*/`:
|
||||
- Read the SKILL.md file for frontmatter (name, description)
|
||||
- Note any scripts or supporting files
|
||||
|
||||
### MCP Servers
|
||||
For each MCP server in `plugins/compounding-engineering/mcp-servers/*/`:
|
||||
- Read the configuration and README
|
||||
- List the tools provided
|
||||
|
||||
## Step 2: Update Documentation Pages
|
||||
|
||||
### 2a. Update `docs/index.html`
|
||||
|
||||
Update the stats section with accurate counts:
|
||||
```html
|
||||
<div class="stats-grid">
|
||||
<div class="stat-card">
|
||||
<span class="stat-number">[AGENT_COUNT]</span>
|
||||
<span class="stat-label">Specialized Agents</span>
|
||||
</div>
|
||||
<!-- Update all stat cards -->
|
||||
</div>
|
||||
```
|
||||
|
||||
Ensure the component summary sections list key components accurately.
|
||||
|
||||
### 2b. Update `docs/pages/agents.html`
|
||||
|
||||
Regenerate the complete agents reference page:
|
||||
- Group agents by category (Review, Research, Workflow, Design, Docs)
|
||||
- Include for each agent:
|
||||
- Name and description
|
||||
- Key responsibilities (bullet list)
|
||||
- Usage example: `claude agent [agent-name] "your message"`
|
||||
- Use cases
|
||||
|
||||
### 2c. Update `docs/pages/commands.html`
|
||||
|
||||
Regenerate the complete commands reference page:
|
||||
- Group commands by type (Workflow, Utility)
|
||||
- Include for each command:
|
||||
- Name and description
|
||||
- Arguments (if any)
|
||||
- Process/workflow steps
|
||||
- Example usage
|
||||
|
||||
### 2d. Update `docs/pages/skills.html`
|
||||
|
||||
Regenerate the complete skills reference page:
|
||||
- Group skills by category (Development Tools, Content & Workflow, Image Generation)
|
||||
- Include for each skill:
|
||||
- Name and description
|
||||
- Usage: `claude skill [skill-name]`
|
||||
- Features and capabilities
|
||||
|
||||
### 2e. Update `docs/pages/mcp-servers.html`
|
||||
|
||||
Regenerate the MCP servers reference page:
|
||||
- For each server:
|
||||
- Name and purpose
|
||||
- Tools provided
|
||||
- Configuration details
|
||||
- Supported frameworks/services
|
||||
|
||||
## Step 3: Update Metadata Files
|
||||
|
||||
Ensure counts are consistent across:
|
||||
|
||||
1. **`plugins/compounding-engineering/.claude-plugin/plugin.json`**
|
||||
- Update `description` with correct counts
|
||||
- Update `components` object with counts
|
||||
- Update `agents`, `commands` arrays with current items
|
||||
|
||||
2. **`.claude-plugin/marketplace.json`**
|
||||
- Update plugin `description` with correct counts
|
||||
|
||||
3. **`plugins/compounding-engineering/README.md`**
|
||||
- Update intro paragraph with counts
|
||||
- Update component lists
|
||||
|
||||
## Step 4: Validate
|
||||
|
||||
Run validation checks:
|
||||
|
||||
```bash
|
||||
# Validate JSON files
|
||||
cat .claude-plugin/marketplace.json | jq .
|
||||
cat plugins/compounding-engineering/.claude-plugin/plugin.json | jq .
|
||||
|
||||
# Verify counts match
|
||||
echo "Agents in files: $(ls plugins/compounding-engineering/agents/*.md | wc -l)"
|
||||
grep -o "[0-9]* specialized agents" plugins/compounding-engineering/docs/index.html
|
||||
|
||||
echo "Commands in files: $(ls plugins/compounding-engineering/commands/*.md | wc -l)"
|
||||
grep -o "[0-9]* slash commands" plugins/compounding-engineering/docs/index.html
|
||||
```
|
||||
|
||||
## Step 5: Report Changes
|
||||
|
||||
Provide a summary of what was updated:
|
||||
|
||||
```
|
||||
## Documentation Release Summary
|
||||
|
||||
### Component Counts
|
||||
- Agents: X (previously Y)
|
||||
- Commands: X (previously Y)
|
||||
- Skills: X (previously Y)
|
||||
- MCP Servers: X (previously Y)
|
||||
|
||||
### Files Updated
|
||||
- docs/index.html - Updated stats and component summaries
|
||||
- docs/pages/agents.html - Regenerated with X agents
|
||||
- docs/pages/commands.html - Regenerated with X commands
|
||||
- docs/pages/skills.html - Regenerated with X skills
|
||||
- docs/pages/mcp-servers.html - Regenerated with X servers
|
||||
- plugin.json - Updated counts and component lists
|
||||
- marketplace.json - Updated description
|
||||
- README.md - Updated component lists
|
||||
|
||||
### New Components Added
|
||||
- [List any new agents/commands/skills]
|
||||
|
||||
### Components Removed
|
||||
- [List any removed agents/commands/skills]
|
||||
```
|
||||
|
||||
## Dry Run Mode
|
||||
|
||||
If `--dry-run` is specified:
|
||||
- Perform all inventory and validation steps
|
||||
- Report what WOULD be updated
|
||||
- Do NOT write any files
|
||||
- Show diff previews of proposed changes
|
||||
|
||||
## Error Handling
|
||||
|
||||
- If component files have invalid frontmatter, report the error and skip
|
||||
- If JSON validation fails, report and abort
|
||||
- Always maintain a valid state - don't partially update
|
||||
|
||||
## Post-Release
|
||||
|
||||
After successful release:
|
||||
1. Suggest updating CHANGELOG.md with documentation changes
|
||||
2. Remind to commit with message: `docs: Update documentation site to match plugin components`
|
||||
3. Remind to push changes
|
||||
|
||||
## Usage Examples
|
||||
|
||||
```bash
|
||||
# Full documentation release
|
||||
claude /release-docs
|
||||
|
||||
# Preview changes without writing
|
||||
claude /release-docs --dry-run
|
||||
|
||||
# After adding new agents
|
||||
claude /release-docs
|
||||
```
|
||||
@@ -1,198 +1,17 @@
|
||||
---
|
||||
name: codify
|
||||
description: Document a recently solved problem for the knowledge base
|
||||
description: "[DEPRECATED] Use /compound instead - Document solved problems"
|
||||
argument-hint: "[optional: brief context about the fix]"
|
||||
---
|
||||
|
||||
# /codify
|
||||
# /codify is deprecated
|
||||
|
||||
Coordinate multiple subagents working in parallel to document a recently solved problem.
|
||||
**This command has been renamed to `/compound`.**
|
||||
|
||||
## Purpose
|
||||
The new name better reflects the compounding engineering philosophy: each documented solution compounds your team's knowledge.
|
||||
|
||||
Captures problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency.
|
||||
---
|
||||
|
||||
## Usage
|
||||
Tell the user: "Note: `/codify` has been renamed to `/compound`. Please use `/compound` going forward."
|
||||
|
||||
```bash
|
||||
/codify # Document the most recent fix
|
||||
/codify [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Execution Strategy: Parallel Subagents
|
||||
|
||||
This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
|
||||
|
||||
### 1. **Context Analyzer** (Parallel)
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Validates against CORA schema
|
||||
- Returns: YAML frontmatter skeleton
|
||||
|
||||
### 2. **Solution Extractor** (Parallel)
|
||||
- Analyzes all investigation steps
|
||||
- Identifies root cause
|
||||
- Extracts working solution with code examples
|
||||
- Returns: Solution content block
|
||||
|
||||
### 3. **Related Docs Finder** (Parallel)
|
||||
- Searches `docs/solutions/` for related documentation
|
||||
- Identifies cross-references and links
|
||||
- Finds related GitHub issues
|
||||
- Returns: Links and relationships
|
||||
|
||||
### 4. **Prevention Strategist** (Parallel)
|
||||
- Develops prevention strategies
|
||||
- Creates best practices guidance
|
||||
- Generates test cases if applicable
|
||||
- Returns: Prevention/testing content
|
||||
|
||||
### 5. **Category Classifier** (Parallel)
|
||||
- Determines optimal `docs/solutions/` category
|
||||
- Validates category against schema
|
||||
- Suggests filename based on slug
|
||||
- Returns: Final path and filename
|
||||
|
||||
### 6. **Documentation Writer** (Parallel)
|
||||
- Assembles complete markdown file
|
||||
- Validates YAML frontmatter
|
||||
- Formats content for readability
|
||||
- Creates the file in correct location
|
||||
|
||||
### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
|
||||
Based on problem type detected, automatically invoke applicable agents:
|
||||
- **performance_issue** → `performance-oracle`
|
||||
- **security_issue** → `security-sentinel`
|
||||
- **database_issue** → `data-integrity-guardian`
|
||||
- **test_failure** → `cora-test-reviewer`
|
||||
- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
|
||||
|
||||
## What It Captures
|
||||
|
||||
- **Problem symptom**: Exact error messages, observable behavior
|
||||
- **Investigation steps tried**: What didn't work and why
|
||||
- **Root cause analysis**: Technical explanation
|
||||
- **Working solution**: Step-by-step fix with code examples
|
||||
- **Prevention strategies**: How to avoid in future
|
||||
- **Cross-references**: Links to related issues and docs
|
||||
|
||||
## Preconditions
|
||||
|
||||
<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/
|
||||
|
||||
## Success Output
|
||||
|
||||
```
|
||||
✓ Parallel documentation generation complete
|
||||
|
||||
Primary Subagent Results:
|
||||
✓ Context Analyzer: Identified performance_issue in brief_system
|
||||
✓ Solution Extractor: Extracted 3 code fixes
|
||||
✓ Related Docs Finder: Found 2 related issues
|
||||
✓ Prevention Strategist: Generated test cases
|
||||
✓ Category Classifier: docs/solutions/performance-issues/
|
||||
✓ Documentation Writer: Created complete markdown
|
||||
|
||||
Specialized Agent Reviews (Auto-Triggered):
|
||||
✓ performance-oracle: Validated query optimization approach
|
||||
✓ kieran-rails-reviewer: Code examples meet Rails standards
|
||||
✓ code-simplicity-reviewer: Solution is appropriately minimal
|
||||
✓ every-style-editor: Documentation style verified
|
||||
|
||||
File created:
|
||||
- docs/solutions/performance-issues/n-plus-one-brief-generation.md
|
||||
|
||||
This documentation will be searchable for future reference when similar
|
||||
issues occur in the Email Processing or Brief System modules.
|
||||
|
||||
What's next?
|
||||
1. Continue workflow (recommended)
|
||||
2. Link related documentation
|
||||
3. Update other references
|
||||
4. View documentation
|
||||
5. Other
|
||||
```
|
||||
|
||||
## Why This Matters
|
||||
|
||||
This creates a compounding knowledge system:
|
||||
|
||||
1. First time you solve "N+1 query in brief generation" → Research (30 min)
|
||||
2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
|
||||
3. Next time similar issue occurs → Quick lookup (2 min)
|
||||
4. Knowledge compounds → Team gets smarter
|
||||
|
||||
The feedback loop:
|
||||
|
||||
```
|
||||
Build → Test → Find Issue → Research → Improve → Document → Validate → Deploy
|
||||
↑ ↓
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Auto-Invoke
|
||||
|
||||
<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
|
||||
|
||||
<manual_override> Use /codify [context] to document immediately without waiting for auto-detection. </manual_override> </auto_invoke>
|
||||
|
||||
## Routes To
|
||||
|
||||
`codify-docs` skill
|
||||
|
||||
## Applicable Specialized Agents
|
||||
|
||||
Based on problem type, these agents can enhance documentation:
|
||||
|
||||
### Code Quality & Review
|
||||
- **kieran-rails-reviewer**: Reviews code examples for Rails best practices
|
||||
- **code-simplicity-reviewer**: Ensures solution code is minimal and clear
|
||||
- **pattern-recognition-specialist**: Identifies anti-patterns or repeating issues
|
||||
|
||||
### Specific Domain Experts
|
||||
- **performance-oracle**: Analyzes performance_issue category solutions
|
||||
- **security-sentinel**: Reviews security_issue solutions for vulnerabilities
|
||||
- **cora-test-reviewer**: Creates test cases for prevention strategies
|
||||
- **data-integrity-guardian**: Reviews database_issue migrations and queries
|
||||
|
||||
### Enhancement & Documentation
|
||||
- **best-practices-researcher**: Enriches solution with industry best practices
|
||||
- **every-style-editor**: Reviews documentation style and clarity
|
||||
- **framework-docs-researcher**: Links to Rails/gem documentation references
|
||||
|
||||
### When to Invoke
|
||||
- **Auto-triggered** (optional): Agents can run post-documentation for enhancement
|
||||
- **Manual trigger**: User can invoke agents after /codify completes for deeper review
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
|
||||
- `/plan` - Planning workflow (references documented solutions)
|
||||
Now run the `/compound` command with the same arguments: #$ARGUMENTS
|
||||
|
||||
202
plugins/compounding-engineering/commands/workflows/compound.md
Normal file
202
plugins/compounding-engineering/commands/workflows/compound.md
Normal file
@@ -0,0 +1,202 @@
|
||||
---
|
||||
name: compound
|
||||
description: Document a recently solved problem to compound your team's knowledge
|
||||
argument-hint: "[optional: brief context about the fix]"
|
||||
---
|
||||
|
||||
# /compound
|
||||
|
||||
Coordinate multiple subagents working in parallel to document a recently solved problem.
|
||||
|
||||
## Purpose
|
||||
|
||||
Captures problem solutions while context is fresh, creating structured documentation in `docs/solutions/` with YAML frontmatter for searchability and future reference. Uses parallel subagents for maximum efficiency.
|
||||
|
||||
**Why "compound"?** Each documented solution compounds your team's knowledge. The first time you solve a problem takes research. Document it, and the next occurrence takes minutes. Knowledge compounds.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
/compound # Document the most recent fix
|
||||
/compound [brief context] # Provide additional context hint
|
||||
```
|
||||
|
||||
## Execution Strategy: Parallel Subagents
|
||||
|
||||
This command launches multiple specialized subagents IN PARALLEL to maximize efficiency:
|
||||
|
||||
### 1. **Context Analyzer** (Parallel)
|
||||
- Extracts conversation history
|
||||
- Identifies problem type, component, symptoms
|
||||
- Validates against CORA schema
|
||||
- Returns: YAML frontmatter skeleton
|
||||
|
||||
### 2. **Solution Extractor** (Parallel)
|
||||
- Analyzes all investigation steps
|
||||
- Identifies root cause
|
||||
- Extracts working solution with code examples
|
||||
- Returns: Solution content block
|
||||
|
||||
### 3. **Related Docs Finder** (Parallel)
|
||||
- Searches `docs/solutions/` for related documentation
|
||||
- Identifies cross-references and links
|
||||
- Finds related GitHub issues
|
||||
- Returns: Links and relationships
|
||||
|
||||
### 4. **Prevention Strategist** (Parallel)
|
||||
- Develops prevention strategies
|
||||
- Creates best practices guidance
|
||||
- Generates test cases if applicable
|
||||
- Returns: Prevention/testing content
|
||||
|
||||
### 5. **Category Classifier** (Parallel)
|
||||
- Determines optimal `docs/solutions/` category
|
||||
- Validates category against schema
|
||||
- Suggests filename based on slug
|
||||
- Returns: Final path and filename
|
||||
|
||||
### 6. **Documentation Writer** (Parallel)
|
||||
- Assembles complete markdown file
|
||||
- Validates YAML frontmatter
|
||||
- Formats content for readability
|
||||
- Creates the file in correct location
|
||||
|
||||
### 7. **Optional: Specialized Agent Invocation** (Post-Documentation)
|
||||
Based on problem type detected, automatically invoke applicable agents:
|
||||
- **performance_issue** → `performance-oracle`
|
||||
- **security_issue** → `security-sentinel`
|
||||
- **database_issue** → `data-integrity-guardian`
|
||||
- **test_failure** → `cora-test-reviewer`
|
||||
- Any code-heavy issue → `kieran-rails-reviewer` + `code-simplicity-reviewer`
|
||||
|
||||
## What It Captures
|
||||
|
||||
- **Problem symptom**: Exact error messages, observable behavior
|
||||
- **Investigation steps tried**: What didn't work and why
|
||||
- **Root cause analysis**: Technical explanation
|
||||
- **Working solution**: Step-by-step fix with code examples
|
||||
- **Prevention strategies**: How to avoid in future
|
||||
- **Cross-references**: Links to related issues and docs
|
||||
|
||||
## Preconditions
|
||||
|
||||
<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/
|
||||
|
||||
## Success Output
|
||||
|
||||
```
|
||||
✓ Parallel documentation generation complete
|
||||
|
||||
Primary Subagent Results:
|
||||
✓ Context Analyzer: Identified performance_issue in brief_system
|
||||
✓ Solution Extractor: Extracted 3 code fixes
|
||||
✓ Related Docs Finder: Found 2 related issues
|
||||
✓ Prevention Strategist: Generated test cases
|
||||
✓ Category Classifier: docs/solutions/performance-issues/
|
||||
✓ Documentation Writer: Created complete markdown
|
||||
|
||||
Specialized Agent Reviews (Auto-Triggered):
|
||||
✓ performance-oracle: Validated query optimization approach
|
||||
✓ kieran-rails-reviewer: Code examples meet Rails standards
|
||||
✓ code-simplicity-reviewer: Solution is appropriately minimal
|
||||
✓ every-style-editor: Documentation style verified
|
||||
|
||||
File created:
|
||||
- docs/solutions/performance-issues/n-plus-one-brief-generation.md
|
||||
|
||||
This documentation will be searchable for future reference when similar
|
||||
issues occur in the Email Processing or Brief System modules.
|
||||
|
||||
What's next?
|
||||
1. Continue workflow (recommended)
|
||||
2. Link related documentation
|
||||
3. Update other references
|
||||
4. View documentation
|
||||
5. Other
|
||||
```
|
||||
|
||||
## The Compounding Philosophy
|
||||
|
||||
This creates a compounding knowledge system:
|
||||
|
||||
1. First time you solve "N+1 query in brief generation" → Research (30 min)
|
||||
2. Document the solution → docs/solutions/performance-issues/n-plus-one-briefs.md (5 min)
|
||||
3. Next time similar issue occurs → Quick lookup (2 min)
|
||||
4. Knowledge compounds → Team gets smarter
|
||||
|
||||
The feedback loop:
|
||||
|
||||
```
|
||||
Build → Test → Find Issue → Research → Improve → Document → Validate → Deploy
|
||||
↑ ↓
|
||||
└──────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Each unit of engineering work should make subsequent units of work easier—not harder.**
|
||||
|
||||
## Auto-Invoke
|
||||
|
||||
<auto_invoke> <trigger_phrases> - "that worked" - "it's fixed" - "working now" - "problem solved" </trigger_phrases>
|
||||
|
||||
<manual_override> Use /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 /compound completes for deeper review
|
||||
|
||||
## Related Commands
|
||||
|
||||
- `/research [topic]` - Deep investigation (searches docs/solutions/ for patterns)
|
||||
- `/plan` - Planning workflow (references documented solutions)
|
||||
@@ -8,12 +8,18 @@ argument-hint: "[feature description, bug report, or improvement idea]"
|
||||
|
||||
## Introduction
|
||||
|
||||
**Note: The current year is 2025.** Use this when dating plans and searching for recent documentation.
|
||||
|
||||
Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files issues that follow project conventions and best practices. This command provides flexible detail levels to match your needs.
|
||||
|
||||
## Feature Description
|
||||
|
||||
<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.
|
||||
|
||||
## Main Tasks
|
||||
|
||||
### 1. Repository Research & Context Gathering
|
||||
@@ -361,19 +367,58 @@ end
|
||||
|
||||
## Output Format
|
||||
|
||||
write to plans/<issue_title>.md
|
||||
Write the plan to `plans/<issue_title>.md`
|
||||
|
||||
Now call the /plan_review command with the plan file as the argument. Make sure to include the plan file in the command.
|
||||
## Post-Generation Options
|
||||
|
||||
## Thinking Approaches
|
||||
After writing the plan file, use the **AskUserQuestion tool** to present these options:
|
||||
|
||||
- **Analytical:** Break down complex features into manageable components
|
||||
- **User-Centric:** Consider end-user impact and experience
|
||||
- **Technical:** Evaluate implementation complexity and architecture fit
|
||||
- **Strategic:** Align with project goals and roadmap
|
||||
**Question:** "Plan ready at `plans/<issue_title>.md`. What would you like to do next?"
|
||||
|
||||
After you get the review back, ask the user questions about the current state of the plan and what the reviewers came back with. Make sure to underatand if this plan is too big or thinks are missing. Are there any other considerations that should be included? Keep askign questions until the user is happy with the plan. THEN update the plan file with the user's feedback.
|
||||
**Options:**
|
||||
1. **Start `/work`** - Begin implementing this plan
|
||||
2. **Run `/plan_review`** - Get feedback from reviewers (DHH, Kieran, Simplicity)
|
||||
3. **Create Issue** - Create issue in project tracker (GitHub/Linear)
|
||||
4. **Simplify** - Reduce detail level
|
||||
5. **Rework** - Change approach or request specific changes
|
||||
|
||||
Optional you can ask to create a Github issue from the plan file.
|
||||
Based on selection:
|
||||
- **`/work`** → Call the /work command with the plan file path
|
||||
- **`/plan_review`** → Call the /plan_review command with the plan file path
|
||||
- **Create Issue** → See "Issue Creation" section below
|
||||
- **Simplify** → Ask "What should I simplify?" then regenerate simpler version
|
||||
- **Rework** → Ask "What would you like changed?" then regenerate with changes
|
||||
- **Other** (automatically provided) → Accept free text, act on it
|
||||
|
||||
Loop back to options after Simplify/Rework until user selects `/work` or `/plan_review`.
|
||||
|
||||
## Issue Creation
|
||||
|
||||
When user selects "Create Issue", detect their project tracker from CLAUDE.md:
|
||||
|
||||
1. **Check for tracker preference** in user's CLAUDE.md (global or project):
|
||||
- Look for `project_tracker: github` or `project_tracker: linear`
|
||||
- Or look for mentions of "GitHub Issues" or "Linear" in their workflow section
|
||||
|
||||
2. **If GitHub:**
|
||||
```bash
|
||||
# Extract title from plan filename (kebab-case to Title Case)
|
||||
# Read plan content for body
|
||||
gh issue create --title "feat: [Plan Title]" --body-file plans/<issue_title>.md
|
||||
```
|
||||
|
||||
3. **If Linear:**
|
||||
```bash
|
||||
# Use linear CLI if available, or provide instructions
|
||||
# linear issue create --title "[Plan Title]" --description "$(cat plans/<issue_title>.md)"
|
||||
```
|
||||
|
||||
4. **If no tracker configured:**
|
||||
Ask user: "Which project tracker do you use? (GitHub/Linear/Other)"
|
||||
- Suggest adding `project_tracker: github` or `project_tracker: linear` to their CLAUDE.md
|
||||
|
||||
5. **After creation:**
|
||||
- Display the issue URL
|
||||
- Ask if they want to proceed to `/work` or `/plan_review`
|
||||
|
||||
NEVER CODE! Just research and write the plan.
|
||||
|
||||
@@ -1,77 +0,0 @@
|
||||
---
|
||||
title: Plugin Versioning and Documentation Requirements
|
||||
category: workflow
|
||||
tags: [versioning, changelog, readme, plugin, documentation]
|
||||
created: 2025-11-24
|
||||
severity: process
|
||||
component: plugin-development
|
||||
---
|
||||
|
||||
# Plugin Versioning and Documentation Requirements
|
||||
|
||||
## Problem
|
||||
|
||||
When making changes to the compounding-engineering plugin, documentation can get out of sync with the actual components (agents, commands, skills). This leads to confusion about what's included in each version and makes it difficult to track changes over time.
|
||||
|
||||
## Solution
|
||||
|
||||
**Every change to the plugin MUST include:**
|
||||
|
||||
1. **Version bump in `plugin.json`**
|
||||
- Follow semantic versioning (semver)
|
||||
- MAJOR: Breaking changes or major reorganization
|
||||
- MINOR: New agents, commands, or skills added
|
||||
- PATCH: Bug fixes, documentation updates, minor improvements
|
||||
|
||||
2. **CHANGELOG.md update**
|
||||
- Add entry under `## [Unreleased]` or new version section
|
||||
- Use Keep a Changelog format
|
||||
- Categories: Added, Changed, Deprecated, Removed, Fixed, Security
|
||||
|
||||
3. **README.md verification**
|
||||
- Verify component counts match actual files
|
||||
- Verify agent/command/skill tables are accurate
|
||||
- Update descriptions if functionality changed
|
||||
|
||||
## Checklist for Plugin Changes
|
||||
|
||||
```markdown
|
||||
Before committing changes to compounding-engineering plugin:
|
||||
|
||||
- [ ] Version bumped in `.claude-plugin/plugin.json`
|
||||
- [ ] CHANGELOG.md updated with changes
|
||||
- [ ] README.md component counts verified
|
||||
- [ ] README.md tables updated (if adding/removing/renaming)
|
||||
- [ ] plugin.json description updated (if component counts changed)
|
||||
```
|
||||
|
||||
## File Locations
|
||||
|
||||
- Version: `.claude-plugin/plugin.json` → `"version": "X.Y.Z"`
|
||||
- Changelog: `CHANGELOG.md`
|
||||
- Readme: `README.md`
|
||||
|
||||
## Example Workflow
|
||||
|
||||
When adding a new agent:
|
||||
|
||||
1. Create the agent file in `agents/[category]/`
|
||||
2. Bump version in `plugin.json` (minor version for new agent)
|
||||
3. Add to CHANGELOG under `### Added`
|
||||
4. Add row to README agent table
|
||||
5. Update README component count
|
||||
6. Update plugin.json description with new counts
|
||||
|
||||
## Prevention
|
||||
|
||||
This documentation serves as a reminder. When Claude Code works on this plugin, it should:
|
||||
|
||||
1. Check this doc before committing changes
|
||||
2. Follow the checklist above
|
||||
3. Never commit partial updates (all three files must be updated together)
|
||||
|
||||
## Related Files
|
||||
|
||||
- `/Users/kieranklaassen/every-marketplace/plugins/compounding-engineering/.claude-plugin/plugin.json`
|
||||
- `/Users/kieranklaassen/every-marketplace/plugins/compounding-engineering/CHANGELOG.md`
|
||||
- `/Users/kieranklaassen/every-marketplace/plugins/compounding-engineering/README.md`
|
||||
@@ -1,5 +1,5 @@
|
||||
---
|
||||
name: codify-docs
|
||||
name: compound-docs
|
||||
description: Capture solved problems as categorized documentation with YAML frontmatter for fast lookup
|
||||
allowed-tools:
|
||||
- Read # Parse conversation context
|
||||
@@ -11,7 +11,7 @@ preconditions:
|
||||
- Solution has been verified working
|
||||
---
|
||||
|
||||
# codify-docs Skill
|
||||
# compound-docs Skill
|
||||
|
||||
**Purpose:** Automatically document solved problems to build searchable institutional knowledge with category-based organization (enum-validated problem types).
|
||||
|
||||
@@ -348,7 +348,7 @@ Action:
|
||||
## Integration Points
|
||||
|
||||
**Invoked by:**
|
||||
- /codify command (primary interface)
|
||||
- /compound command (primary interface)
|
||||
- Manual invocation in conversation after solution confirmed
|
||||
- Can be triggered by detecting confirmation phrases like "that worked", "it's fixed", etc.
|
||||
|
||||
@@ -184,7 +184,7 @@ Work logs serve as:
|
||||
|
||||
| Trigger | Flow | Tool |
|
||||
|---------|------|------|
|
||||
| Code review | `/workflows:review` → Findings → `/triage` → Todos | Review agent + skill |
|
||||
| Code review | `/review` → Findings → `/triage` → Todos | Review agent + skill |
|
||||
| PR comments | `/resolve_pr_parallel` → Individual fixes → Todos | gh CLI + skill |
|
||||
| Code TODOs | `/resolve_todo_parallel` → Fixes + Complex todos | Agent + skill |
|
||||
| Planning | Brainstorm → Create todo → Work → Complete | Skill |
|
||||
|
||||
@@ -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 PR branch, offer worktree for isolated review
|
||||
2. **Feature Work (`/workflows:work`)**: Always ask if user wants parallel worktree or live branch work
|
||||
1. **Code Review (`/review`)**: If NOT already on the PR branch, offer worktree for isolated review
|
||||
2. **Feature Work (`/work`)**: Always ask if user wants parallel worktree or live branch work
|
||||
3. **Parallel Development**: When working on multiple features simultaneously
|
||||
4. **Cleanup**: After completing work in a worktree
|
||||
|
||||
@@ -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 `/review` and `/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`
|
||||
### `/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`
|
||||
### `/work`
|
||||
|
||||
Always offer choice:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user