Immutable. This exact content is served forever at /api/v1/blob/cc81bbee4454f4ec.
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Repository Architecture
This is the **Claude Code Arsenal** - a professional collection of skills for development workflow automation. All components are now **skills** (migrated from the legacy commands format in v2.0.0).
### Core Components
- **Skills** (`skills/`): 22 skills covering development, documentation, git, jira, claude utilities, browser automation, project planning, and skill discovery
- **Scripts** (`scripts/`): Professional Python utilities for installation, configuration, and code generation
- **Commands** (`commands/`): Legacy commands kept for backward compatibility (skills take precedence)
## Installation
### Plugin System (Recommended)
This is the primary installation method for all users. Register this repository as a Claude Code Plugin marketplace:
```bash
/plugin marketplace add mgiovani/cc-arsenal
```
Then, to install a specific plugin set:
1. Select **Browse and install plugins**
2. Select **cc-arsenal-marketplace**
3. Select one of:
- **cc-arsenal** - Complete toolkit (all 22 skills)
- **cc-arsenal-dev** - Development skills only (implement-feature, fix-bug, review-security, inject-nextjs-docs, project-planner)
- **cc-arsenal-docs** - Documentation skills only (ADR, RFC, diagrams, init, check, update)
- **cc-arsenal-git** - Git workflow skills only (commit, create-pr)
- **cc-arsenal-skills** - Specialty skills only (agent-browser, jira-cli, create-skill, find-skills)
- **cc-arsenal-teams** - Spec-driven team orchestration (team-implement)
4. Select **Install now**
Alternatively, directly install via:
```bash
/plugin install cc-arsenal@cc-arsenal-marketplace
```
For local development, add a local marketplace instead:
```bash
/plugin marketplace add /path/to/cc-arsenal
```
**Benefits:**
- Clean, managed installation
- Automatic updates
- Easy to enable/disable
- No system-wide symlinks
**Plugin Variants Pattern:**
This repository uses a "plugin variants" architecture where multiple installation options are provided from a single source repository. All variants point to the same codebase (`"source": "./"`) but expose different subsets of skills:
| Plugin | Skills Loaded | Use Case |
|--------|--------------|----------|
| `cc-arsenal` | All 22 skills | Full toolkit for complete workflow automation |
| `cc-arsenal-dev` | implement-feature, fix-bug, review-security, inject-nextjs-docs, project-planner | Development workflows with subagents |
| `cc-arsenal-docs` | docs-adr, docs-check, docs-diagram, docs-init, docs-rfc, docs-update | Documentation generation only |
| `cc-arsenal-git` | git-commit, git-create-pr | Git workflow automation |
| `cc-arsenal-skills` | agent-browser, jira-cli, create-skill, find-skills | Specialty model-invoked capabilities |
| `cc-arsenal-teams` | team-implement | Spec-driven team orchestration (experimental) |
**How It Works:**
- Single repository with all skills in `skills/` directory
- Marketplace manifest (`.claude-plugin/marketplace.json`) defines multiple "plugins"
- Each plugin entry specifies which skills to load via the `skills` field
- Users install only what they need without duplicating code
**When to Use Each Variant:**
- **Full installation** (`cc-arsenal`): Development teams wanting complete automation
- **Selective installation** (variant plugins): Minimalist setups, focused workflows, or avoiding namespace pollution
- **Custom combinations**: Install multiple variants (e.g., `cc-arsenal-git` + `cc-arsenal-docs`)
**Troubleshooting Plugin Updates:**
If plugin updates from a local marketplace don't show new components:
```bash
# Clear the plugin cache to force reload
rm -rf ~/.claude/plugins/cache/cc-arsenal-marketplace/
# Then update the plugin in Claude Code
/plugin → Update now
```
This happens when the cache contains an older version and doesn't detect local changes.
### Development Installation (Symlink Method)
**Only use this if you're developing cc-arsenal itself.** Regular users should use the plugin system above.
This method creates symlinks to `~/.claude/` for immediate file updates during development:
```bash
# Install Python dependencies
uv sync --extra dev
# Install to ~/.claude directory (creates symlinks)
uv run python -m scripts.setup.install
# Configure components (optional)
uv run python -m scripts.setup.configure
# Quick start with preview
make dry-run
make install
make configure
```
**Benefits:**
- Immediate file updates (no reinstall needed)
- Better for development and testing
- Direct access to source code
### Team Configuration
For automatic installation across team members, add to `.claude/settings.json`:
```json
{
"extraKnownMarketplaces": {
"cc-arsenal": {
"source": {
"source": "github",
"repo": "mgiovani/cc-arsenal"
}
}
},
"enabledPlugins": ["cc-arsenal"]
}
```
When team members trust the repository folder, Claude Code automatically installs the marketplace and plugin.
### Selective Installation (Advanced)
By default, `make install` installs **all components** by symlinking everything to `~/.claude/`. If you want to selectively install only specific components, use the interactive configuration wizard:
```bash
# Interactive configuration - choose specific components to symlink
make configure
```
**What it does:**
- Discovers all available skills from the repository
- Shows skills organized by category
- Lets you interactively select which items to symlink
- **Never modifies** your `~/.claude/settings.json` file
- Creates symlinks only for selected components
**When to use:**
- You only want specific skills (e.g., just git skills, not docs)
- Testing individual components without installing everything
- Creating a lightweight installation with minimal disk usage
- For full installation, use `make install` instead
**Note:** This is separate from the plugin system. Plugin installation uses the variant definitions from marketplace.json. Use `make configure` when you want granular control over which files are symlinked.
## Development Commands
The repository uses a **modular Makefile architecture** with focused command sets:
- **Core Makefile** (19 commands): Essential development, testing, and installation
- **Feature Makefiles**: Optional tools with their own command sets
- `scripts/claude/statusline/Makefile` (9 commands): Statusline management
- `scripts/claude-hi/Makefile` (12 commands): Session scheduler and automation
### Core Development Workflow
```bash
# Development Environment
make dev # Set up development with all dependencies
make pre-commit-install # Install pre-commit hooks
make pre-commit-run # Run pre-commit on all files
# Code Quality
make check # Run all checks (lint + type-check)
make lint # Run ruff linting
make format # Format code with ruff
make type-check # Run pyright type checking
# Testing
make test # Run unit tests
make coverage # Tests with coverage report
# Installation
make install # Install all components to ~/.claude
make dry-run # Preview installation
make configure # Interactive: choose specific skills to enable
# Utilities
make clean # Clean caches and build artifacts
make info # Show repository statistics
make validate-structure # Validate repository structure
make validate-plugins # Validate plugin manifests
```
### Optional Features
```bash
# Statusline Management
make install-statusline # Install statusline (delegates to feature Makefile)
make uninstall-statusline # Uninstall statusline (delegates to feature Makefile)
make -C scripts/claude/statusline help # Show all statusline commands
make -C scripts/claude/statusline status # Show statusline configuration
make -C scripts/claude/statusline test # Test statusline
make -C scripts/claude/statusline list-backups # List backups
# Session Scheduler (Claude Hi)
make -C scripts/claude-hi help # Show all scheduler commands
make -C scripts/claude-hi standard # Set up 9am/2pm/7pm schedule
make -C scripts/claude-hi status # Check current schedule
make -C scripts/claude-hi remove # Remove schedule
make -C scripts/claude-hi now # Send 'hi' immediately
```
## Available Skills (22 total)
All components are skills with progressive disclosure (SKILL.md + optional references/scripts/assets directories).
### Development (5 skills)
- **implement-feature**: Feature implementation with senior staff engineer best practices, parallel subagent orchestration, and Task Management System integration
- **fix-bug**: Test-driven debugging with strict sequential task chain and dependency enforcement
- **review-security**: OWASP Top 10 2025 security analysis with parallel scanning agents
- **inject-nextjs-docs**: Run Next.js agents-md codemod to inject framework docs
- **project-planner**: Break down large projects into dependency-aware tasks with Mermaid visualization
### Documentation (6 skills)
- **docs-adr**: Architecture Decision Records creation and management
- **docs-check**: Documentation validation and health scoring
- **docs-diagram**: Architecture diagrams generation (Mermaid)
- **docs-init**: Documentation structure initialization
- **docs-rfc**: Request for Comments documentation
- **docs-update**: Documentation sync with codebase state
### Git Operations (2 skills)
- **git-commit**: Conventional commit message generation
- **git-create-pr**: Pull request creation with standardized formats
### Jira Integration (2 skills)
- **jira-daily**: Smart standup report generator with activity analysis
- **jira-todo**: Smart daily work planner with intelligent prioritization
### Claude Utilities (2 skills)
- **create-command**: Create new skills (slash commands) from templates
- **create-rule**: Create CLAUDE.md rules and memory guidelines
### Teams (1 skill)
- **team-implement**: Spec-driven team orchestration — adaptive development team scaling from 3 to 11 agents based on complexity. Accepts plain text, Jira tickets, GitHub issues, PRs, files, or URLs. Requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` for full mode.
### Specialty Skills (4 skills)
- **agent-browser**: AI-optimized browser automation with 93% less context overhead than Playwright MCP
- **find-skills**: Discover and install third-party agent skills from skills.sh
- **create-skill**: Specification-driven skill creation with live documentation fetching and interactive planning
- **jira-cli**: Interactive command-line tool for Atlassian Jira
## Development Patterns
### Understanding Skills
All components in cc-arsenal are **skills**. Skills come in two flavors:
- **User-invoked skills** (`disable-model-invocation: true`): Explicit slash commands that users run directly
- Examples: `/git-commit`, `/docs-adr`, `/project-planner`
- Best for: Git operations, documentation generation, project planning
- Can still be invoked with `/` slash commands
- 16 user-invoked skills available
- **Model-invoked skills** (`disable-model-invocation: false` or unset): Capabilities Claude automatically loads when relevant
- Examples: implement-feature, fix-bug, agent-browser, jira-cli, create-skill, find-skills
- Claude detects context automatically (e.g., "let's implement X" or "fix this bug")
- No confirmation dialogs - users can abort with natural language if needed
- Best for: Feature implementation, bug fixing, domain expertise, tool integrations
- 6 model-invoked skills available
### Skills Architecture
Skills are modular capabilities organized with this structure:
```
skill-name/
├── SKILL.md (required)
│ ├── YAML frontmatter (name, description, allowed-tools, etc.)
│ └── Markdown instructions
└── Bundled Resources (optional)
├── scripts/ - Executable code (Python/Bash/etc.)
├── references/ - Documentation loaded as needed
└── assets/ - Files used in output (templates, etc.)
```
### Progressive Disclosure
Skills use a three-level loading system:
1. **Metadata** (name + description) - Always in context (~100 words)
2. **SKILL.md body** - Loaded when skill activates (<5k words)
3. **Bundled resources** - Loaded only when Claude needs them
### Local Development Cache Management
**CRITICAL: When developing with a local directory marketplace, you must manually clear the cache after any changes.**
Local directory marketplaces (`"source": "directory"`) do NOT support auto-update or version detection. After creating new skills or bumping versions:
```bash
# Clear the plugin cache to force reload
rm -rf ~/.claude/plugins/cache/cc-arsenal-marketplace/
# Then update the plugin in Claude Code
/plugin → Update now
```
**Why this is needed:**
- Claude Code caches the marketplace.json metadata on first install
- Changes to local files don't trigger cache invalidation
- Auto-update and manual "Update now" only work for remote GitHub sources
- Without clearing cache, new components won't appear
**Alternative:** Use GitHub remote marketplace for automatic updates (recommended for production use).
### Documentation Guidelines
**IMPORTANT: No README files in component directories**
Do not add README.md files inside the `skills/` directory. Claude Code will incorrectly detect them as actual components.
Instead:
- All documentation goes in the `docs/` folder
- Reference documentation in the main project README.md if needed
- Use CLAUDE.md for development guidance
- Individual skills use SKILL.md as their native format
### Quality Assurance
All code changes should go through integrated quality gates:
- Code quality enforcement via pre-commit hooks
- Comprehensive testing and validation
- Documentation requirements
- **CHANGELOG updates**: Update CHANGELOG.md after big changes or when opening PRs
### Technology Stack
- **Python 3.12+** with UV package management
- **Rich CLI interfaces** with progress indicators
- **Pydantic** for data validation and settings
- **Type hints** required for all functions
- **Comprehensive testing** with pytest and >90% coverage
## File Organization
```
cc-arsenal/
├── skills/ # All 22 skills (primary component type)
│ ├── implement-feature/ # Feature implementation with subagents
│ ├── fix-bug/ # Test-driven debugging
│ ├── review-security/ # OWASP security analysis
│ ├── inject-nextjs-docs/ # Next.js docs injection
│ ├── docs-adr/ # Architecture Decision Records
│ ├── docs-check/ # Documentation validation
│ ├── docs-diagram/ # Architecture diagrams
│ ├── docs-init/ # Documentation initialization
│ ├── docs-rfc/ # Request for Comments
│ ├── docs-update/ # Documentation updates
│ ├── git-commit/ # Conventional commits
│ ├── git-create-pr/ # Pull request creation
│ ├── jira-daily/ # Daily standup reports
│ ├── jira-todo/ # Work prioritization
│ ├── create-command/ # Create new skills
│ ├── create-rule/ # Create memory rules
│ ├── agent-browser/ # Browser automation
│ ├── find-skills/ # Third-party skill discovery
│ ├── create-skill/ # Specification-driven skill creation
│ ├── jira-cli/ # Jira CLI integration
│ └── team-implement/ # Spec-driven team orchestration
├── commands/ # Legacy commands (backward compatibility)
│ ├── dev/ # Development commands
│ ├── docs/ # Documentation commands
│ ├── git/ # Git commands
│ ├── claude/ # Claude utility commands
│ └── jira/ # Jira commands
├── resources/ # Templates and assets
│ └── templates/ # ADR, RFC, and doc templates
├── scripts/ # Installation and utilities
│ ├── setup/ # install.py, configure.py
│ ├── generators/ # Code generation utilities
│ ├── claude/ # Claude Code utilities (statusline)
│ └── claude-hi/ # Session management and scheduling
```