# CLAUDE.md

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

## Repository Overview

This is the **Cloud-Kinetix enhanced fork** of BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development), an AI-powered framework that provides specialized AI agents for every Agile team role.

**Key Package**: `@cloudkinetix/bmad-enhanced` v1.10.0 (based on upstream BMAD v4.31.0)

## Key Architecture & Concepts

### Directory Structure (Layered Architecture)

- **bmad-core/** - Core framework components (upstream)
  - `agents/` - Individual AI agent definitions with YAML front matter
  - `agent-teams/` - Pre-configured combinations of agents
  - `templates/` - Document templates (PRD, Architecture, Stories)
  - `workflows/` - Structured development processes
  - `tasks/` - Reusable task definitions
  - `checklists/` - Quality checklists
  - `data/` - Knowledge base
- **ck-layer/** - Cloud-Kinetix code enhancements
  - `bin/` - Enhanced CLI entry points (bmad-ck.js, bmad-enhanced.js)
  - `lib/` - Enterprise features (installer, backup manager, IDE setup)
  - `config/` - CK configuration files
  - `scripts/` - Build and release scripts
  - `docs/` - Technical documentation (LAYERED_ARCHITECTURE.md)
- **docs-ck/** - Cloud-Kinetix user documentation (exception #1: at root for accessibility)
- **expansion-packs/** - All expansion packs in one location (exception #2)
  - `ck-jira-integration/` - JIRA bidirectional sync (CK)
  - `ck-ai-agent-dev/` - AI agent development toolkit (CK)
  - `ck-parallel-dev/` - Parallel story development (CK)
  - `ck-gitlab-cicd-automation/` - GitLab CI/CD automation (CK)
  - `bmad-2d-phaser-game-dev/` - Game development (upstream)
  - `bmad-infrastructure-devops/` - DevOps tools (upstream)
  - `bmad-creator-tools/` - Creator tools (upstream)
- **test/** - Test suites (52 high-value integration/E2E tests)
- **dist/** - Pre-built bundles for web use
- **tools/** - Build tools and CLI utilities

### Single Package Structure

- One `package.json` at root - simplified from previous multi-package approach
- Direct publishing from root directory
- All dependencies in one place
- Simplified testing and development
- Easier upstream sync without file duplication

## Common Commands & Scripts

### Installation & Usage

```bash
# Install Cloud-Kinetix enhanced version (interactive)
npx @cloudkinetix/bmad-enhanced install

# Install with specific teams
npx @cloudkinetix/bmad-enhanced install --team fullstack

# Install with expansion packs
npx @cloudkinetix/bmad-enhanced install --expansion-packs ck-jira-integration,ck-ai-agent-dev

# Add expansion pack to existing installation
npx @cloudkinetix/bmad-enhanced install --expansion-only --expansion-packs ck-jira-integration

# Non-interactive installation for CI/CD
npx @cloudkinetix/bmad-enhanced install --full --directory . --ide cursor

# Check installation status (local dev)
node ck-layer/bin/bmad-enhanced.js status
```

### Development & Testing

```bash
# Build commands
npm run build                    # Build all agents and teams
npm run build:agents             # Build agents only
npm run build:teams              # Build teams only
node tools/cli.js build --agent <name>  # Build specific agent
node tools/cli.js build --team <name>   # Build specific team

# Code quality
npm run format                   # Format all markdown files
npm run validate                 # Validate agent YAML files
node tools/cli.js validate       # Alternative validation

# Testing
npm test                         # Run full test suite (saves to test-results/)
npm run test:watch              # Run tests in watch mode
npm run test:smoke              # Quick smoke tests
npm run test:integration        # Integration tests only
npm run test:open-reports       # Open test results in browser
npm run test:clean              # Clean test results directory

# Test installations
npm run test:install            # Test local installation
npm run test:install:npm:beta   # Test NPM beta installation
npm run test:install:npm:stable # Test NPM stable installation
npm run test:install:all        # Run all installation tests

# Non-interactive installation testing
npm run test:install:non-interactive      # Test local non-interactive install
npm run test:install:non-interactive:npm  # Test NPM beta non-interactive install
npm run test:install:clean               # Clean up all test installation directories

# Debugging test failures
jest test/installer/installer.test.js  # Run specific test file
jest --testNamePattern="should install"  # Run tests matching pattern

# Pre-release checks
bash ck-layer/scripts/03-pre-publish-validation.sh  # Pre-publish validation

# List commands
node tools/cli.js list:agents    # List available agents
node tools/cli.js list:expansions # List expansion packs
node ck-layer/bin/bmad-enhanced.js list:teams  # List agent teams
```

### Release Process (Simplified!)

```bash
# 1. Update version
npm version minor  # or patch/major as needed

# 2. Commit changes
git add -A
git commit -m "feat: release v1.8.0 with new features"

# 3. Publish to NPM
npm publish

# 4. Tag and push
git tag v1.8.0
git push origin develop --tags  # or main for stable
```

### Automated Release (via semantic-release)

```bash
# Test semantic release (dry run)
npm run release:test

# Beta releases (develop branch) - automated via conventional commits
git commit -m "feat: add new feature"
git push origin develop
# Triggers: version bump, NPM publish, GitHub release, all docs updated

# Stable releases (main branch) - automated via conventional commits
git commit -m "feat: add new feature"
git push origin main
# Triggers: version bump, NPM publish, GitHub release, all docs updated
```

## Documentation Path Configuration

**IMPORTANT**: When using BMAD agents to create documentation:

- Use `/docs-ck` for all Cloud-Kinetix specific user documentation
- Create epics and stories in `/docs-ck/epics/`
- Create architecture documentation in `/docs-ck/architecture/`
- Technical documentation about the layered architecture goes in `/ck-layer/docs/`
- This separation allows Cloud-Kinetix documentation to coexist with standard BMAD docs

## Cloud-Kinetix Specific Features

### Enhanced Capabilities

- **8 IDE Support**: Auto-detects Cursor, Claude Code, Windsurf, Roo, Cline, Gemini CLI, VS Code Copilot, Trae
- **JIRA Integration**: Bidirectional sync with natural language commands
- **Professional Installer**: Interactive CLI with backup/recovery
- **Expansion Pack System**: Add features without reinstalling core
- **Focused Testing**: Integration and E2E tests only (52 high-value tests)

### Expansion Pack Documentation Guidelines

**IMPORTANT**: Each expansion pack should maintain only TWO documentation files:

1. **README.md** - Comprehensive guide including:
   - Overview and features
   - Quick start/installation
   - Usage examples
   - Configuration
   - Troubleshooting
   - API/Task reference

2. **CHANGELOG.md** - Version history including:
   - Release notes
   - Breaking changes
   - New features
   - Bug fixes

**Consolidation Rule**: Any other documentation (QUICK_START.md, GUIDE.md, etc.) should be consolidated into README.md to:

- Reduce maintenance burden
- Provide single source of truth
- Improve user experience
- Simplify updates

### Branch Strategy

- **develop**: Beta releases and active development
- **main**: Stable releases and production
- **feature/**: Feature branches (merge to develop)
- **Upstream sync**: Simplified sync with upstream BMAD-METHOD

### Version Management

- Single package.json with Cloud-Kinetix version (e.g., 1.8.0)
- Metadata tracks upstream version (`basedOnUpstream` field)
- Git tags: `v{version}` format
- Semantic release for automated releases (develop → beta, main → stable)
- Manual release via `npm version` and `npm publish` also supported

### Upstream Sync Process

With the simplified single-package structure:

1. Direct git merge from upstream without intermediate file syncing
2. Conflicts are resolved at the git level, not file duplication level
3. Manual review ensures Cloud-Kinetix enhancements are preserved
4. See [docs/UPSTREAM-SYNC.md](docs/UPSTREAM-SYNC.md) for detailed process

### Quick Sync Commands

```bash
# Add upstream remote
git remote add upstream https://github.com/bmadcode/BMAD-METHOD.git

# Fetch and merge upstream changes
git fetch upstream main
git checkout -b sync-upstream-$(date +%Y%m%d)
git merge upstream/main

# Resolve conflicts favoring CK enhancements
# Test and create PR
```

### Conventional Commits

- `feat:` New features (minor bump)
- `fix:` Bug fixes (patch bump)
- `feat!:` Breaking changes (major bump)
- `docs:` Documentation (no bump)
- `chore:` Maintenance (no bump)

## IDE Support

The installer automatically configures for:

- `cursor` - @agent commands with manual rules
- `claude-code` - /agent commands
- `windsurf` - @agent commands with YAML headers
- `roo` - Custom modes in .roomodes
- `cline` - Rules integration
- `gemini-cli` - @agent commands
- `vs-code-copilot` - Chat modes in .github/chatmodes
- `trae` - Project rules in .trae/rules/project_rules.md

## Troubleshooting

### Common Issues

1. **Version conflicts**: Use manual release process
2. **Tag conflicts**: Delete local tags, use manual process
3. **NPM auth**: Check `.env` for `NPM_TOKEN`
4. **Test failures**: Run `npm test` before releasing

### Useful Commands

```bash
# Check NPM versions
npm view @cloudkinetix/bmad-enhanced versions --json

# Check installation status
node ck-layer/bin/bmad-enhanced.js status

# List available resources
node ck-layer/bin/bmad-enhanced.js list              # All agents
node ck-layer/bin/bmad-enhanced.js list:expansions   # Available expansion packs
node ck-layer/bin/bmad-enhanced.js list:teams        # Agent teams

# Version management
npm run version:patch    # Bump patch version (1.10.0 → 1.10.1)
npm run version:minor    # Bump minor version (1.10.0 → 1.11.0)
npm run version:major    # Bump major version (1.10.0 → 2.0.0)
npm run version:all      # Update all component versions

# Debugging installations
node ck-layer/bin/bmad-enhanced.js install --help    # Show all install options
node ck-layer/bin/bmad-enhanced.js install --dry-run # Preview installation

# Working with expansion packs
node tools/cli.js build:expansions                   # Build all expansion packs
node tools/cli.js validate --expansion <name>        # Validate specific pack

# Git operations
npm run sync-upstream    # Sync with upstream BMAD-METHOD
```

## Key Files for Release

- `.releaserc.json` - Semantic release config
- `ck-layer/scripts/04-npm-publish-beta.sh` - Beta NPM publishing
- `ck-layer/scripts/05-test-published-beta.sh` - Test published beta
- `ck-layer/scripts/06-npm-publish-stable.sh` - Stable NPM publishing
- `tools/semantic-release-*.js` - Custom release plugins
- `package.json` - Single source of truth for all dependencies

## High-Level Architecture Understanding

### Agent System Architecture

The BMAD agent system uses a multi-layered approach:

1. **Agent Definitions** (`bmad-core/agents/*.md`):
   - YAML front matter defines agent metadata and capabilities
   - Markdown body contains the agent's instructions and behavior
   - Agents are compiled into web bundles for IDE consumption

2. **Task System** (`bmad-core/tasks/`):
   - Reusable task definitions that agents can execute
   - Tasks can be composed and referenced by agents
   - Each task has input/output specifications

3. **Workflow Orchestration** (`bmad-core/workflows/`):
   - Defines multi-agent collaboration patterns
   - Coordinates handoffs between agents (e.g., PM → Architect → Dev)
   - Story files act as the communication medium between agents

4. **IDE Integration** (`ck-layer/lib/ide-setup.js`):
   - Auto-detects 7 different IDEs
   - Configures each IDE with appropriate agent commands
   - Maps agent files to IDE-specific formats (.cursorrules, .roomodes, etc.)

### Expansion Pack Architecture

Expansion packs extend BMAD with domain-specific capabilities:

1. **Structure**: Each pack in `expansion-packs/` contains:
   - `agents/` - Domain-specific agents
   - `tasks/` - Specialized tasks
   - `templates/` - Domain templates
   - `README.md` and `CHANGELOG.md` only (consolidated docs)

2. **Integration**: Packs are installed via the enhanced installer:
   - Detected automatically during installation
   - Can be added post-installation with `--expansion-only`
   - Integrated into IDE configurations

### Cloud-Kinetix Enhancement Layer

The CK layer (`ck-layer/`) adds enterprise features without modifying upstream:

1. **Enhanced Installer** (`ck-layer/lib/installer.js`):
   - Interactive CLI with progress tracking
   - Backup and recovery system
   - Multi-IDE detection and setup

2. **Enterprise Features**:
   - JIRA integration for bidirectional sync
   - Parallel story development
   - GitLab CI/CD automation
   - Professional error handling and logging

3. **Upstream Compatibility**:
   - All enhancements are isolated in `ck-layer/`
   - Upstream changes merge cleanly without conflicts
   - Version tracking maintains compatibility

### Story-Driven Development Flow

The core innovation of BMAD is the story file as a communication medium:

1. **Planning Phase** (Web UI):
   - Analyst + PM + Architect collaborate to create PRD
   - Architecture document defines technical approach
   - Plans are detailed and context-rich

2. **Story Generation** (SM Agent):
   - Transforms PRD + Architecture into detailed story files
   - Each story contains full context, not just tasks
   - Stories include implementation details and architectural guidance

3. **Development Cycle** (IDE):
   - Dev agent reads story file with complete context
   - Implements according to embedded specifications
   - QA agent validates against story acceptance criteria
   - Story file updated with implementation notes

This eliminates context loss between planning and implementation.