CLAUDE.md · diff
git:20260129.19426b4 to git:20260202.d5338bf
361 added, 34 removed. Audit A to A.
- # CLAUDE.md
+ # Jikigai Soleur - Claude Code Plugin Marketplace
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+ This repository is a Claude Code plugin marketplace that distributes the `soleur` plugin to developers building with AI-powered tools.
- ## Project Overview
+ ## Repository Structure
- Soleur is a Rust project using Edition 2024. The project is in early development with a basic Hello World entry point.
+ ```
+ soleur/
+ ├── .claude-plugin/
+ │ └── marketplace.json # Marketplace catalog (lists available plugins)
+ ├── docs/ # Documentation site (GitHub Pages)
+ │ ├── index.html # Landing page
+ │ ├── css/ # Stylesheets
+ │ ├── js/ # JavaScript
+ │ └── pages/ # Reference pages
+ └── plugins/
+ └── soleur/ # The actual plugin
+ ├── .claude-plugin/
+ │ └── plugin.json # Plugin metadata
+ ├── agents/ # 24 specialized AI agents
+ ├── commands/ # 13 slash commands
+ ├── skills/ # 11 skills
+ ├── mcp-servers/ # 2 MCP servers (playwright, context7)
+ ├── README.md # Plugin documentation
+ └── CHANGELOG.md # Version history
+ ```
- ## Build and Development Commands
+ ## Philosophy: Soleur
+ **Each unit of engineering work should make subsequent units of work easier—not harder.**
+
+ When working on this repository, follow the soleur process:
+
+ 1. **Brainstorm** → Brainstom the change first
+ 2. **Plan** → Understand the change needed and its impact
+ 3. **Delegate** → Use AI tools to help with implementation
+ 4. **Assess** → Verify changes work as expected
+ 5. **Codify** → Update this CLAUDE.md with learnings
+
+ ## Working with This Repository
+
+ ### Adding a New Plugin
+
+ 1. Create plugin directory: `plugins/new-plugin-name/`
+ 2. Add plugin structure:
+ ```
+ plugins/new-plugin-name/
+ ├── .claude-plugin/plugin.json
+ ├── agents/
+ ├── commands/
+ └── README.md
+ ```
+ 3. Update `.claude-plugin/marketplace.json` to include the new plugin
+ 4. Test locally before committing
+
+ ### Updating the Soleur Plugin
+
+ When agents, commands, or skills are added/removed, follow this checklist:
+
+ #### 1. Count all components accurately
+
```bash
- # Build
- cargo build
+ # Count agents
+ ls plugins/soleur/agents/*.md | wc -l
- # Run
- cargo run
+ # Count commands
+ ls plugins/soleur/commands/*.md | wc -l
- # Run tests
- cargo test
+ # Count skills
+ ls -d plugins/soleur/skills/*/ 2>/dev/null | wc -l
+ ```
- # Run a single test
- cargo test test_name
+ #### 2. Update ALL description strings with correct counts
- # Format code
- cargo fmt --all
+ The description appears in multiple places and must match everywhere:
- # Lint (with auto-fix)
- cargo clippy --fix --allow-dirty --allow-staged -- -D warnings
+ - [ ] `plugins/soleur/.claude-plugin/plugin.json` → `description` field
+ - [ ] `.claude-plugin/marketplace.json` → plugin `description` field
+ - [ ] `plugins/soleur/README.md` → intro paragraph
- # Lint (check only)
- cargo clippy -- -D warnings
+ Format: `"Includes X specialized agents, Y commands, and Z skill(s)."`
- # Security audit
- cargo audit
+ #### 3. Update version numbers
- # Run tests with coverage
- cargo llvm-cov --lcov --output-path lcov.info
+ When adding new functionality, bump the version in:
+
+ - [ ] `plugins/soleur/.claude-plugin/plugin.json` → `version`
+ - [ ] `.claude-plugin/marketplace.json` → plugin `version`
+
+ #### 4. Update documentation
+
+ - [ ] `plugins/soleur/README.md` → list all components
+ - [ ] `plugins/soleur/CHANGELOG.md` → document changes
+ - [ ] `CLAUDE.md` → update structure diagram if needed
+
+ #### 5. Rebuild documentation site
+
+ Run the release-docs command to update all documentation pages:
+
+ ```bash
+ claude /release-docs
```
- ## Code Quality
+ 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
- - Pre-commit hooks are managed via lefthook (see `lefthook.yml`)
- - Clippy warnings are treated as errors (`-D warnings`)
- - Coverage target: 95% for project, 90% for patches
- - Test files (`*tests.rs`, `tests/**`) are excluded from coverage metrics
+ #### 6. Validate JSON files
- ## Browser Automation
+ ```bash
+ cat .claude-plugin/marketplace.json | jq .
+ cat plugins/soleur/.claude-plugin/plugin.json | jq .
+ ```
- Use `agent-browser` for web automation:
+ #### 6. Verify before committing
- 1. `agent-browser open <url>` - Navigate to page
- 2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
- 3. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
- 4. Re-snapshot after page changes
+ ```bash
+ # Ensure counts in descriptions match actual files
+ grep -o "Includes [0-9]* specialized agents" plugins/soleur/.claude-plugin/plugin.json
+ ls plugins/soleur/agents/*.md | wc -l
+ ```
+
+ ### Marketplace.json Structure
+
+ The marketplace.json follows the official Claude Code spec:
+
+ ```json
+ {
+ "name": "marketplace-identifier",
+ "owner": {
+ "name": "Owner Name",
+ "url": "https://github.com/owner"
+ },
+ "metadata": {
+ "description": "Marketplace description",
+ "version": "1.0.0"
+ },
+ "plugins": [
+ {
+ "name": "plugin-name",
+ "description": "Plugin description",
+ "version": "1.0.0",
+ "author": { ... },
+ "homepage": "https://...",
+ "tags": ["tag1", "tag2"],
+ "source": "./plugins/plugin-name"
+ }
+ ]
+ }
+ ```
+
+ **Only include fields that are in the official spec.** Do not add custom fields like:
+
+ - `downloads`, `stars`, `rating` (display-only)
+ - `categories`, `featured_plugins`, `trending` (not in spec)
+ - `type`, `verified`, `featured` (not in spec)
+
+ ### Plugin.json Structure
+
+ Each plugin has its own plugin.json with detailed metadata:
+
+ ```json
+ {
+ "name": "plugin-name",
+ "version": "1.0.0",
+ "description": "Plugin description",
+ "author": { ... },
+ "keywords": ["keyword1", "keyword2"],
+ "components": {
+ "agents": 15,
+ "commands": 6,
+ "hooks": 2
+ },
+ "agents": {
+ "category": [
+ {
+ "name": "agent-name",
+ "description": "Agent description",
+ "use_cases": ["use-case-1", "use-case-2"]
+ }
+ ]
+ },
+ "commands": {
+ "category": ["command1", "command2"]
+ }
+ }
+ ```
+
+ ## Documentation Site
+
+ The documentation site is at `/docs` in the repository root (for GitHub Pages). 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
+ <span class="stat-number">24</span> <!-- agents -->
+ <span class="stat-number">13</span> <!-- commands -->
+ ```
+
+ 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 docs/index.html
+
+ # Or start a local server
+ cd docs
+ python -m http.server 8000
+ # Then visit http://localhost:8000
+ ```
+
+ ## Testing Changes
+
+ ### Test Locally
+
+ 1. Install the marketplace locally:
+
+ ```bash
+ claude /plugin marketplace add /Users/yourusername/every-marketplace
+ ```
+
+ 2. Install the plugin:
+
+ ```bash
+ claude /plugin install soleur
+ ```
+
+ 3. Test agents and commands:
+ ```bash
+ claude /review
+ claude agent kieran-rails-reviewer "test message"
+ ```
+
+ ### Validate JSON
+
+ Before committing, ensure JSON files are valid:
+
+ ```bash
+ cat .claude-plugin/marketplace.json | jq .
+ cat plugins/soleur/.claude-plugin/plugin.json | jq .
+ ```
+
+ ## Common Tasks
+
+ ### Adding a New Agent
+
+ 1. Create `plugins/soleur/agents/new-agent.md`
+ 2. Update plugin.json agent count and agent list
+ 3. Update README.md agent list
+ 4. Test with `claude agent new-agent "test"`
+
+ ### Adding a New Command
+
+ 1. Create `plugins/soleur/commands/new-command.md`
+ 2. Update plugin.json command count and command list
+ 3. Update README.md command list
+ 4. Test with `claude /new-command`
+
+ ### Adding a New Skill
+
+ 1. Create skill directory: `plugins/soleur/skills/skill-name/`
+ 2. Add skill structure:
+ ```
+ skills/skill-name/
+ ├── SKILL.md # Skill definition with frontmatter (name, description)
+ └── scripts/ # Supporting scripts (optional)
+ ```
+ 3. Update plugin.json description with new skill count
+ 4. Update marketplace.json description with new skill count
+ 5. Update README.md with skill documentation
+ 6. Update CHANGELOG.md with the addition
+ 7. Test with `claude skill skill-name`
+
+ **Skill file format (SKILL.md):**
+ ```markdown
+ ---
+ name: skill-name
+ description: Brief description of what the skill does
+ ---
+
+ # Skill Title
+
+ Detailed documentation...
+ ```
+
+ ### Updating Tags/Keywords
+
+ Tags should reflect the soleur philosophy:
+
+ - Use: `ai-powered`, `soleur`, `company-as-a-service`
+ - Avoid: Framework-specific tags unless the plugin is framework-specific
+
+ ## Commit Conventions
+
+ Follow these patterns for commit messages:
+
+ - `Add [agent/command name]` - Adding new functionality
+ - `Remove [agent/command name]` - Removing functionality
+ - `Update [file] to [what changed]` - Updating existing files
+ - `Fix [issue]` - Bug fixes
+ - `Simplify [component] to [improvement]` - Refactoring
+
+ Include the Claude Code footer:
+
+ ```
+ 🤖 Generated with [Claude Code](https://claude.com/claude-code)
+
+ Co-Authored-By: Claude <noreply@anthropic.com>
+ ```
+
+ ## Resources to search for when needing more information
+
+ - [Claude Code Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins)
+ - [Plugin Marketplace Documentation](https://docs.claude.com/en/docs/claude-code/plugin-marketplaces)
+ - [Plugin Reference](https://docs.claude.com/en/docs/claude-code/plugins-reference)
+
+ ## Key Learnings
+
+ _This section captures important learnings as we work on this repository._
+
+ ### 2024-11-22: Added gemini-imagegen skill and fixed component counts
+
+ Added the first skill to the plugin and discovered the component counts were wrong (said 15 agents, actually had 17). Created a comprehensive checklist for updating the plugin to prevent this in the future.
+
+ **Learning:** Always count actual files before updating descriptions. The counts appear in multiple places (plugin.json, marketplace.json, README.md) and must all match. Use the verification commands in the checklist above.
+
+ ### 2024-10-09: Simplified marketplace.json to match official spec
+
+ The initial marketplace.json included many custom fields (downloads, stars, rating, categories, trending) that aren't part of the Claude Code specification. We simplified to only include:
+
+ - Required: `name`, `owner`, `plugins`
+ - Optional: `metadata` (with description and version)
+ - Plugin entries: `name`, `description`, `version`, `author`, `homepage`, `tags`, `source`
+
+ **Learning:** Stick to the official spec. Custom fields may confuse users or break compatibility with future versions.