CLAUDE.md · git:20260924.72c544d · 2026-09-24 · sha256 d0d9365e6aa0ea4d

CLAUDE.md git:20260924.72c544dA

Immutable. This exact content never changes and is served at /api/v1/blob/d0d9365e6aa0ea4d.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is a **Claude Code Plugin Marketplace** repository that contains specialized agent definitions for DevOps and software engineering workflows. The repository follows the Claude Code plugin ecosystem structure, providing reusable agents that can be proactively activated based on context.

## Architecture

### Marketplace Structure
```
.claude-plugin/
└── marketplace.json          # Marketplace definition and plugin registry

plugins/
├── devops-infrastructure/    # Infrastructure & operations agents
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── agents/               # Agent definitions (5 agents)
│   └── skills/               # Skills (1 skill)
│                             # (no .mcp.json — declares no MCP servers)
│
├── software-engineering/     # General engineering workflows
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── agents/               # Agent definitions (8 agents)
│   ├── skills/               # Skills (18 skills)
│   ├── assets/               # Templates shared by skills
│   └── .mcp.json             # MCP server integration (context7)
│
├── go-specialist/            # Go language expertise
│   ├── .claude-plugin/
│   │   └── plugin.json
│   ├── agents/               # Agent definitions (1 agent)
│   ├── skills/               # Skills (11 skills)
│   ├── assets/               # Templates shared by skills
│   └── .mcp.json             # MCP server integration (context7)
│
└── bash-specialist/          # Bash scripting expertise
    ├── .claude-plugin/
    │   └── plugin.json
    ├── agents/               # Agent definitions (1 agent)
    ├── skills/               # Skills (1 skill)
    └── .mcp.json             # MCP server integration (context7)
```

### Agent Architecture

Agents are defined in **markdown files with YAML frontmatter** in `plugins/*/agents/`. Each agent follows this structure:

**Frontmatter fields:**
- `name`: Agent identifier (required)
- `description`: When to use this agent (required, shown in Claude Code UI)
- `model`: LLM model to use (sonnet/opus/haiku/inherit)
- `tools`: Optional tool restrictions (agents use `tools`, not `allowed-tools`)
- `color`: UI color (red/blue/green/yellow/purple/orange/pink/cyan)
- `effort`: Optional effort level override (low/medium/high/max)
- `maxTurns`: Optional max turns before agent must complete
- `skills`: Optional skill references for specialized workflows

**Content sections:**
1. **Proactive Triggers**: Automatic activation conditions based on file patterns or keywords
2. **Core Capabilities**: Domain expertise and technical knowledge
3. **Implementation Patterns**: Best practices and approach
4. **Deliverables**: Expected outputs and artifacts
5. **Multi-Agent Coordination**: Collaboration patterns with other agents (in body, not frontmatter)

### Available Plugins & Agents

#### devops-infrastructure
Infrastructure, deployment, and operations specialists.

| Agent | Purpose | Proactive Activation |
|-------|---------|---------------------|
| `aws-specialist` | AWS cloud architecture, Well-Architected Framework, cost optimization | .tf (AWS), cloudformation, "aws", ARNs |
| `cicd-specialist` | CI/CD pipelines (GitHub Actions, GitLab CI, Forgejo Actions via `fgj`) | .github/workflows, .gitlab-ci.yml, .forgejo/workflows, pipeline terms |
| `database-specialist` | Schema design, query optimization, migrations | .sql files, "slow query", "index" |
| `devops-specialist` | Infrastructure as Code (Terraform, Ansible, CloudFormation) | .tf, .yml files, cloud terms |
| `postgresql-specialist` | PostgreSQL 16+ advanced features, query optimization, replication | .sql, migrations, "postgresql", slow query |

#### software-engineering
General development workflows and best practices.

| Agent | Purpose | Proactive Activation |
|-------|---------|---------------------|
| `code-review-enforcer` | Code quality, security, best practices review | After file modifications |
| `debugger` | Root cause analysis, error resolution | Errors, test failures |
| `diagram-architect` | Software & infrastructure architecture diagrams via d2 + icons.terrastruct.com | .d2 files, "diagram", "architecture diagram", "sequence diagram" |
| `docs-architect` | Long-form technical documentation generation | Documentation requests (uses Opus model) |
| `html-first-frontend` | HTMX, Alpine.js, Bootstrap | HTML/CSS without frameworks |
| `license-specialist` | Open source license compliance for SaaS | Dependency files, license terms |
| `payment-integrator` | Stripe, PayPal, subscription billing | Payment SDKs, checkout flows |
| `security-auditor` | Security vulnerability detection, OWASP compliance, auth/crypto review | After auth/crypto/API changes |

#### go-specialist
Go language expertise and optimization.

| Agent | Purpose | Proactive Activation |
|-------|---------|---------------------|
| `golang-pro` | Go 1.25+ development, concurrency, performance | .go files, go.mod |

#### bash-specialist
Production-quality bash scripting and terminal UX.

| Agent | Purpose | Proactive Activation |
|-------|---------|---------------------|
| `bash-pro` | Bash scripts, shellcheck compliance, error handling, gum-based terminal UX | .sh files, "bash script", shell automation |

## Development Commands

### Task Runner (Task)
This project uses [Task](https://taskfile.dev) for automation:

```bash
# List all available tasks
task

# Validate plugin structure
task check
```

### Plugin Validation

```bash
# Validate individual plugin
cd plugins/<plugin-name> && claude plugin validate .

# Validate marketplace
claude plugin validate .claude-plugin/marketplace.json
```

### Plugin Installation (End Users)

Add this marketplace to Claude Code:
```bash
/plugin marketplace add sgaunet/claude-plugins
```

Or link locally for development:
```bash
/plugin marketplace add ./path/to/claude-plugins
```

## Working with Agents

### Creating New Agents

1. Choose appropriate plugin:
   - `devops-infrastructure` for infrastructure/operations agents
   - `software-engineering` for general development workflows
   - `go-specialist` for Go-specific expertise
   - `bash-specialist` for bash scripting expertise
2. Create `plugins/<plugin-name>/agents/<name>.md`
3. Add YAML frontmatter with required fields
4. Structure content with clear sections:
   - Proactive Triggers (for automatic activation)
   - Core Capabilities
   - Implementation patterns or approach
   - Expected deliverables or output format
5. Validate: `cd plugins/<plugin-name> && claude plugin validate .`

### Agent Design Principles

1. **Proactive Activation**: Define clear file patterns and keyword triggers so agents activate automatically
2. **Scoped Expertise**: Each agent should have a focused domain (DevOps, database, payments, etc.)
3. **Actionable Outputs**: Specify concrete deliverables (code, configs, documentation)
4. **Tool Restrictions**: Use `tools` field for agents, `allowed-tools` for skills
5. **Model Selection**: Use `sonnet` for code/speed, `opus` for complex analysis/documentation, `haiku` for fast/simple tasks
6. **Multi-Agent Coordination**: Document collaboration patterns in the markdown body (not frontmatter) so they reach the agent's system prompt

### Agent Frontmatter Examples

**Basic:**
```yaml
---
name: example-agent
description: What this agent does and when to use it
model: sonnet
---
```

**With tool restrictions:**
```yaml
---
name: review-agent
description: Code review specialist
tools: Read, Grep, Glob, Bash
model: sonnet
color: purple
---
```

See existing agents in `plugins/*/agents/*.md` for advanced patterns (multi-agent coordination, skills, effort).

## Plugin Manifest Schema

- **marketplace.json**: See `.claude-plugin/marketplace.json` for complete schema
- **plugin.json**: See `plugins/*/.claude-plugin/plugin.json` for examples

**Note**: Include keywords and MCP server lists in plugin description field for discoverability.

## File Locations

- **Marketplace metadata**: `.claude-plugin/marketplace.json`
- **Plugin metadata**: `plugins/*/\.claude-plugin/plugin.json`
- **Agent definitions**: `plugins/*/agents/*.md` (15 total agents)
- **Skills**: `plugins/*/skills/<name>/SKILL.md` (31 total skills)
- **Skill assets**: `plugins/*/assets/` (`go-specialist`, `software-engineering`)
- **MCP config**: `plugins/*/.mcp.json` (only `bash-specialist`, `go-specialist`, `software-engineering`; `devops-infrastructure` has none)

## Design Patterns

### Multi-Agent Collaboration
Agents can work together:
- `code-review-enforcer` reviews after `golang-pro` implements features
- `license-specialist` audits dependencies chosen by `devops-specialist`
- `docs-architect` documents architecture designed by `cicd-specialist`

### Proactive vs Reactive
- **Proactive**: Agent activates automatically based on triggers (preferred)
- **Reactive**: User explicitly invokes agent by name

Most agents in this collection are designed for proactive activation to reduce friction.

## 2026 Feature Adoption

This marketplace implements modern Claude Code best practices for enhanced reliability and discoverability:

### Multi-Agent Coordination
Agents document collaboration patterns in a `## Multi-Agent Coordination` body section (not frontmatter) so the content reaches the agent's system prompt:
- **code-review-enforcer**: Shares quality standards with other agents
- **debugger**: Shares diagnostic findings with implementing agents
- **golang-pro**: Documents skill invocation patterns

### Enhanced Discoverability
Plugin descriptions include inline keywords and MCP server lists for better search and documentation:
```json
{
  "description": "Infrastructure as Code (Terraform, Ansible), CI/CD pipelines. MCP: context7",
  "repository": "https://github.com/..."
}
```

### Correct Tool Field Names
Agents and skills use **different** field names per the official spec:
- **Agents** use `tools` (per [sub-agents spec](https://code.claude.com/docs/en/sub-agents))
- **Skills** use `allowed-tools` (per [skills spec](https://code.claude.com/docs/en/skills))

### MCP Integration
`context7` (library documentation lookup) is the only MCP server actually declared, in the
`.mcp.json` of `bash-specialist`, `go-specialist`, and `software-engineering`. The
`devops-infrastructure` plugin declares no MCP server (it has no `.mcp.json`).

GitHub, GitLab, and Forgejo operations use the `gh`, `glab`, and `fgj` CLIs instead of MCP servers. Platform-aware skills route via the `detect-repo-host` skill, which maps `git.sylvlab.fr` remotes to Forgejo (`fgj`).

## Skills vs Agents

### Skills
Claude Code merged custom slash commands into skills, so every workflow in this marketplace lives
in `plugins/<plugin>/skills/<name>/SKILL.md` (31 total) — there are no `commands/` directories.
A skill is invoked as `/<plugin>:<name>` and may also be auto-invoked by Claude unless it sets
`disable-model-invocation: true`.

**Frontmatter** (per the [skills spec](https://code.claude.com/docs/en/skills)): `name`,
`description`, `argument-hint`, `allowed-tools`, `user-invocable`, `disable-model-invocation`.
The directory name must equal `name`. Skills use `allowed-tools`, never `tools`.

**Invocation control convention:**
- State-changing or interactive skills (`commit`, `create-issue`, `feature-flow`, `feature-flow-w`,
  `upd-project-description`, `auto-mr`, every `gen-*`) set `disable-model-invocation: true` so they
  run only when explicitly invoked.
- Read-mostly skills (`analyze-pr`, `analyze-and-create-issue`, `audit-codebase`,
  `check-claude-md-tokens`, `analyze-db-performance`, `go-tdd`) stay model-invocable.
- Background knowledge skills (`detect-repo-host`, `go-blackbox`, `go-bulma`, `go-tool`) set
  `user-invocable: false` — Claude only.

**devops-infrastructure**: `analyze-db-performance`

**go-specialist**: `gen-forgejo-dir`, `gen-github-dir`, `gen-gitlab-ci`, `gen-goreleaser`,
`gen-linter`, `gen-taskfiles`, `go-blackbox`, `go-bulma`, `go-structure`, `go-tdd`, `go-tool`

**software-engineering**: `analyze-and-create-issue`, `analyze-pr`, `audit-codebase`, `auto-mr`,
`check-claude-md-tokens`, `commit`, `create-issue`, `detect-repo-host`, `feature-flow`,
`feature-flow-w`, `gen-claude`, `gen-diagram`, `gen-readme-diagram`, `gen-vhs-demo`, `run-lint`,
`run-tests`, `upd-project-description`, `vscode-settings`

**bash-specialist**: `gum-beautify`

Templates a skill writes into a project live in `plugins/<plugin>/assets/` and are referenced as
`${CLAUDE_PLUGIN_ROOT}/assets/...` — plugin-level rather than skill-local because several skills
share them (`detection-functions.md`, `mise/mise.toml`, `github-workflows/`).

The go-specialist CI generators (`/gen-github-dir`, `/gen-forgejo-dir`, `/gen-gitlab-ci`) are **mise-based**: workflows install tools via mise (`jdx/mise-action` on GitHub/Forgejo, the `jdx/mise` image on GitLab) and run `task …`. Tool versions live in a shared `mise.toml` (asset: `plugins/go-specialist/assets/mise/mise.toml`) so local dev and CI stay in sync. `mise.toml` is owned canonically by `/gen-taskfiles` and auto-created (when missing) by the CI generators.

Platform-aware skills (`/create-issue`, `/analyze-and-create-issue`, `/feature-flow`, `/feature-flow-w`, `/analyze-pr`, `/upd-project-description`) detect the host via `detect-repo-host` and route to `gh` (GitHub), `glab` (GitLab), or `fgj` (Forgejo, `git.sylvlab.fr`).

### Agents
Proactive specialists in `plugins/*/agents/` that auto-activate based on context:
- File patterns (.go, .tf, .sql)
- Keywords (payment, authentication, slow query)
- Events (file modifications, test failures)
- User requests (debugging, code review)