Skip to content

CLAUDE.md

Latest commit

 

History

History
100 lines (69 loc) · 4.73 KB

CLAUDE.md

File metadata and controls

100 lines (69 loc) · 4.73 KB

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 four 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
  • package.json — version (name stays maister-opencode on both branches; auto-generated by make build-opencode)

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