Ship's officer for your codebase — keeping everything shipshape.

Bosun is a Claude Code plugin that orchestrates specialized agents for code quality, security, and architecture review. It provides parallel review capabilities through isolated agents that access curated skill knowledge.

# Install globally
/plugin install --global bosun@curphey/bosun

# Run a full audit
/audit

# Fix issues (auto-fixes applied, others prompted)
/fix

# View current findings
/status

┌─────────────────────────────────────────────┐
│          BOSUN (Orchestrator)               │
│  Coordinates parallel reviews, aggregates   │
└──────────┬──────────────┬───────────────────┘
           │              │
    ┌──────▼──────┐ ┌─────▼──────┐
    │ security-   │ │ quality-   │  ← Agents (parallel, isolated)
    │ agent       │ │ agent      │
    └──────┬──────┘ └─────┬──────┘
           │              │
    ┌──────▼──────┐ ┌─────▼──────┐
    │ security    │ │ architect  │  ← Skills (knowledge packages)
    │ SKILL       │ │ SKILL      │
    └──────┬──────┘ └─────┬──────┘
           │              │
    ┌──────▼──────┐ ┌─────▼──────┐
    │ references/ │ │ references/│  ← RAG (curated knowledge)
    └─────────────┘ └────────────┘

• full — All agents (default)
• security — Security vulnerabilities, secrets, auth
• quality — Code quality, patterns, linting
• docs — Documentation completeness
• architecture — System design, dependencies
• devops — CI/CD, IaC, containers
• ux-ui — Accessibility, usability (frontend)
• testing — Test coverage, quality
• performance — Algorithms, optimization

/audit → writes .bosun/findings.json
/fix   → reads findings, applies fixes, updates status
/improve → reads findings, prioritizes, plans/executes sprints
/status → shows current summary

Agents are specialized workers that run in isolated contexts for independent analysis:

All agents have full capabilities — they can analyze, fix, refactor, and create code and documentation.

Skills are knowledge packages that agents reference for domain expertise:

Audits produce findings in .bosun/findings.json:

{
  "version": "1.0.0",
  "metadata": {
    "project": "my-project",
    "auditedAt": "2025-01-20T10:00:00Z",
    "scope": "full"
  },
  "summary": {
    "total": 8,
    "bySeverity": { "critical": 1, "high": 2, "medium": 3, "low": 2 }
  },
  "findings": [
    {
      "id": "SEC-001",
      "category": "security",
      "severity": "critical",
      "title": "Hardcoded API key",
      "location": { "file": "src/config.js", "line": 15 },
      "interactionTier": "confirm"
    }
  ]
}

When running /fix, findings are organized by interaction tier:

Use --auto to only apply auto-tier fixes, or --interactive to approve each fix individually.

Global (available in all projects):

/plugin install --global bosun@curphey/bosun

Project (available to anyone working on this repo):

/plugin install --project bosun@curphey/bosun

User (just for yourself in this project):

/plugin install bosun@curphey/bosun

Local (development/testing):

/plugin install --local .

/audit
# Spawns security, quality, and docs agents in parallel
# Outputs findings to .bosun/findings.json
# Displays summary report

/audit security
# Only security-agent runs
# Faster for targeted reviews

/fix --auto
# Applies all auto-tier fixes silently
# (formatting, linting, typos)

/fix --interactive
# Prompts for each fix individually
# Maximum control over changes

/improve --plan
# Generates prioritized sprint plan
# Shows effort vs. impact analysis

# Audit Report: my-project

**Date**: 2025-01-20
**Scope**: full
**Agents**: security-agent, quality-agent, docs-agent

## Summary

| Severity | Count |
|----------|-------|
| Critical | 1     |
| High     | 2     |
| Medium   | 3     |
| Low      | 2     |

## Critical/High Findings

1. [SEC-001] Hardcoded API key - src/config.js:15
2. [SEC-002] SQL injection risk - src/db/query.js:42
3. [QUA-001] O(n²) complexity - src/search.js:88

## Recommendations

1. Extract all secrets to environment variables
2. Use parameterized queries for database access
3. Optimize search algorithm to O(n log n)

## Next Steps

- Run `/fix` to remediate findings
- Run `/fix --auto` for auto-tier fixes only
- Run `/status` for current summary

bosun/
├── .claude-plugin/
│   └── plugin.json              # Plugin manifest
├── agents/                       # Specialized workers
│   ├── orchestrator-agent.md    # Master coordinator
│   ├── security-agent.md        # Security auditor
│   ├── quality-agent.md         # Code quality
│   ├── docs-agent.md            # Documentation
│   ├── architecture-agent.md    # System design
│   ├── devops-agent.md          # CI/CD, IaC
│   ├── ux-ui-agent.md           # Accessibility
│   ├── testing-agent.md         # Test coverage
│   └── performance-agent.md     # Optimization
├── skills/                       # Knowledge packages
│   ├── security/
│   ├── architect/
│   ├── devops/
│   ├── testing/
│   ├── performance/
│   ├── javascript/
│   ├── typescript/
│   ├── golang/
│   ├── python/
│   ├── rust/
│   ├── java/
│   ├── csharp/
│   └── ...
├── commands/                     # Slash commands
│   ├── audit.md                 # /audit
│   ├── fix.md                   # /fix
│   ├── improve.md               # /improve
│   └── status.md                # /status
├── schemas/                      # Validation
│   └── findings.schema.json     # Findings JSON schema
├── scripts/                      # Utilities
│   ├── init-project.sh          # Bootstrap projects
│   ├── audit-project.sh         # Audit configuration
│   ├── sync-upstream.sh         # Upstream sync
│   └── install-hooks.sh         # Install git hooks
├── hooks/                        # Git hooks & CI templates
│   ├── pre-commit               # Pre-commit hook script
│   ├── .pre-commit-config.yaml  # Pre-commit framework config
│   └── bosun-audit.yml          # GitHub Actions template
└── references/
    └── upstream-sources.json    # Source tracking

# Bootstrap a new project
./scripts/init-project.sh ./my-project

# Audit project configuration
./scripts/audit-project.sh ./my-project

# Check upstream for updates
./scripts/sync-upstream.sh check

# Install git hooks
./scripts/install-hooks.sh

Bosun provides hooks for automated checks in local development and CI pipelines.

Install pre-commit hooks for local security and quality checks:

# Install hooks
./scripts/install-hooks.sh

# Or manually
cp hooks/pre-commit .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

The pre-commit hook checks for:

• Hardcoded secrets and API keys
• Debug statements (console.log, debugger, etc.)
• Large files (>1MB)
• Sensitive file types (.env, .pem, .key)

For projects using the pre-commit framework:

pip install pre-commit
cp hooks/.pre-commit-config.yaml .pre-commit-config.yaml
pre-commit install

Copy the workflow template to your project:

cp hooks/bosun-audit.yml .github/workflows/bosun-audit.yml

Features:

• Runs on pull requests and pushes
• Secret detection (no API key needed)
• Full Bosun audit (requires ANTHROPIC_API_KEY secret)
• PR comments with findings summary
• Findings uploaded as artifacts

Bosun is designed as a control plane — it sits at the top of the stack and owns its data:

1. No Runtime Dependencies: Users install Bosun alone. All knowledge is self-contained.

2. Curated, Not Inherited: Knowledge is curated from best-in-class sources into owned skills:

   • Full control over content quality and consistency
   • Freedom to modify, extend, or reject upstream changes
   • Unified voice and standards across all agents

3. Parallel Review: Agents run in isolated contexts for independent, parallel analysis.

4. Single Source of Truth: For projects using Bosun, the plugin IS the standard.

Bosun implements a pull-based sync model for curating knowledge from:

• obra/superpowers — architecture patterns, workflow design
• VoltAgent/awesome-claude-code-subagents — language specialists
• Dammyjay93/claude-design-engineer — UX/UI patterns

Key principle: Upstream repos are sources of ideas, not dependencies.

Claude Code is Anthropic's CLI tool for AI-assisted development. Plugins extend Claude Code with:

• Skills — Knowledge packages that give Claude specialized expertise
• Agents — Specialized workers for isolated, parallel tasks
• Commands — Slash commands that trigger specific workflows
• Hooks — Automatic triggers based on context

To learn more, run /help or visit the Claude Code documentation.

See CONTRIBUTING.md for guidelines.

MIT License — see LICENSE for details.