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

Reference

+
+

Resources

+ +

On This Page

+
+

Resources

+ +

On This Page

diff --git a/plugins/compounding-engineering/docs/pages/mcp-servers.html b/plugins/compounding-engineering/docs/pages/mcp-servers.html index 08f6678..6a796fe 100644 --- a/plugins/compounding-engineering/docs/pages/mcp-servers.html +++ b/plugins/compounding-engineering/docs/pages/mcp-servers.html @@ -34,11 +34,17 @@

Reference

+
+

Resources

+ +

On This Page

+
+

Resources

+ +

On This Page