maister

# 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 containing bundled plugins for AI-driven SDLC workflows. The main plugin is `maister` which provides structured development workflows.

## IMPORTANT: Never Edit Generated Files

**NEVER directly modify files under `plugins/maister-copilot/`** — those are auto-generated by the `make` command. Always edit the source files in `plugins/maister/` instead. Changes to `maister-copilot/` will be overwritten.

## Structure

```
.claude-plugin/marketplace.json    # Marketplace manifest (lists all plugins)
plugins/
└── maister/                       # Main plugin
    ├── .claude-plugin/plugin.json # Plugin manifest
    ├── CLAUDE.md                  # Detailed plugin documentation (READ THIS)
    ├── agents/                    # Subagent definitions (*.md)
    ├── commands/                  # Slash commands (organized by workflow type)
    ├── skills/                    # Skills with SKILL.md entry points
    └── .mcp.json                  # MCP server configuration
docs/                              # User-facing documentation and guides
```

## Key Files

- **`@plugins/maister/CLAUDE.md`**: Comprehensive plugin documentation with all skills, commands, agents, and workflow principles. Read this when working on plugin internals.
- **`README.md`**: User-facing documentation for plugin consumers.

## Plugin Development

### Adding a New Skill

1. Create directory: `plugins/maister/skills/[skill-name]/`
2. Create `SKILL.md` with workflow phases and execution instructions
3. Optionally add `references/` directory for supporting documentation
4. Document in `@plugins/maister/CLAUDE.md` under "Available Skills"

### Adding a New Command

1. Create markdown file: `plugins/maister/commands/[category]/[command].md`
2. Commands are thin wrappers that invoke skills
3. Document in `plugins/maister/CLAUDE.md` under "Available Commands"

### Adding a New Agent

1. Create markdown file: `plugins/maister/agents/[agent-name].md`
2. Define agent purpose, tools, and workflow
3. Document in `plugins/maister/CLAUDE.md` under "Available Subagents"

## Documentation Principles

This plugin follows specific documentation guidelines (see @plugins/maister/CLAUDE.md section "Plugin Documentation Principles"):

- Trust Claude to reason—provide principles, not prescriptive implementations
- Commands are thin wrappers; orchestration logic lives in skills
- Reference files guide implementation, not provide complete code
- Single source of truth: technical details in `SKILL.md`, not scattered across files

## Beta Branch Management

The `beta` branch is used for developing and testing new features before they reach `master`.

### Branch Conventions

- **master**: Stable releases. Marketplace name: `maister-plugins`, versions: `X.Y.Z`
- **beta**: Pre-release testing. Marketplace name: `maister-plugins-beta`, versions: `X.Y.Z-beta.N`

### Merging beta to master (squash workflow)

1. **Sync beta with master**: `git checkout beta && git merge master`
2. **Squash-merge to master**: `git checkout master && git merge --squash beta`
3. **Fix versions before committing**: Restore master's marketplace name (`maister-plugins`) and set the new release version (not beta version) in all three manifest files
4. **Commit the feature**: `git commit -m "Feature description"`
5. **Bump version**: Separate commit for the version bump
6. **Reset beta**: `git checkout beta && git reset --hard master` — required because squash-merge doesn't track merge parents
7. **Set beta version**: Update manifests to next beta version (e.g., `X.Y.Z-beta.1`) with marketplace name `maister-plugins-beta`, commit
8. **Push both**: `git push origin master beta`

### Why reset beta after squash?

After `git merge --squash`, git doesn't record that beta's commits were merged. A regular `git merge master` back to beta would try to replay all old commits, causing conflicts. `reset --hard master` is safe because all beta work is preserved on master.

### Manifest files to update

These three files need version/name changes during the merge workflow:
- `.claude-plugin/marketplace.json` — name + version + descriptions
- `plugins/maister/.claude-plugin/plugin.json` — version + description
- `plugins/maister-copilot/.claude-plugin/plugin.json` — version + description

## Testing Changes

1. Navigate to a test project
2. Run `/maister:init` to initialize the framework
3. Test commands like `/maister:development "test feature"`
4. Test workflows with different task types and complexity levels