diff --git a/.gitignore b/.gitignore
index a25ea7ec8..236738d20 100644
--- a/.gitignore
+++ b/.gitignore
@@ -34,7 +34,6 @@ Thumbs.db
 _bmad*/.cursor/
 
 # AI assistant files
-CLAUDE.md
 .ai/*
 cursor
 .gemini
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..6cb2aeccc
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+BMad Method is an AI-driven agile development framework built on BMad Core (Collaboration Optimized Reflection Engine). It provides specialized AI agents and guided workflows for software development lifecycle management.
+
+**Key Modules:**
+- **Core** (`src/core/`) - Universal framework with shared agents, tasks, and workflows
+- **BMM** (`src/modules/bmm/`) - BMad Method for agile software development (flagship module)
+- **BMB** (`src/modules/bmb/`) - BMad Builder for creating custom agents/workflows
+- **BMGD** (`src/modules/bmgd/`) - Game development workflows
+- **CIS** (`src/modules/cis/`) - Creative Intelligence Suite
+
+## Common Commands
+
+```bash
+# Run all tests (schemas, installation, validation, lint, markdown lint, format check)
+npm test
+
+# Run specific test suites
+npm run test:schemas          # Agent YAML schema validation tests
+npm run test:install          # Installation component tests
+npm run validate:schemas      # Validate all *.agent.yaml files against schema
+
+# Code quality
+npm run lint                  # ESLint with YAML support
+npm run lint:fix              # Auto-fix linting issues
+npm run lint:md               # Markdown linting
+npm run format:check          # Check Prettier formatting
+npm run format:fix            # Auto-fix formatting
+
+# Test coverage
+npm run test:coverage         # Generate coverage report with c8
+
+# CLI integration tests
+./test/test-cli-integration.sh
+```
+
+## Architecture
+
+### Module Structure
+Each module in `src/modules/` follows this pattern:
+```
+module/
+├── module.yaml           # Module configuration and installer prompts
+├── agents/               # Agent definitions (*.agent.yaml)
+├── workflows/            # Workflow definitions with workflow.yaml files
+├── data/                 # Data files used by workflows
+├── teams/                # Team configurations (agent groupings)
+└── _module-installer/    # Module-specific installation logic
+```
+
+### Agent YAML Schema
+Agent files (`*.agent.yaml`) are validated by `tools/schema/agent.js` using Zod. Key rules:
+- Required fields: `id`, `name`, `title`, `icon`, `persona`, `menu`
+- Module agents must have `module` field matching their path (e.g., `bmm` for files in `src/modules/bmm/agents/`)
+- Menu triggers must be kebab-case or compound format (`TS or fuzzy match on tech-spec`)
+- Test fixtures in `test/fixtures/agent-schema/` demonstrate valid/invalid patterns
+
+### CLI Tools
+- `tools/cli/bmad-cli.js` - Main CLI entry point
+- `tools/bmad-npx-wrapper.js` - NPX wrapper (`npx bmad-method install`)
+- `tools/validate-agent-schema.js` - Schema validation CLI wrapper
+
+### Workflow System
+Workflows are YAML files that guide multi-step processes. Located in module `workflows/` directories with:
+- `workflow.yaml` - Workflow definition and steps
+- Supporting data files and templates
+
+## Development Notes
+
+### Adding New Agents
+1. Create `*.agent.yaml` in appropriate `src/modules/*/agents/` directory
+2. Follow schema in `tools/schema/agent.js`
+3. Validate with `npm run validate:schemas`
+4. Add test fixtures if introducing new validation patterns
+
+### Modifying Validation
+Schema changes go in `tools/schema/agent.js`. Test fixtures in `test/fixtures/agent-schema/` must cover all validation paths (100% coverage required).
+
+### PR Guidelines
+- Submit to `main` branch for critical fixes only
+- Keep PRs under 800 lines; split larger changes
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
+- Validate YAML schemas before committing: `npm run validate:schemas`