From 44836512e73615e71049bc15e175b0714067cf9f Mon Sep 17 00:00:00 2001
From: Wang-tianhao <110560187+Wang-tianhao@users.noreply.github.com>
Date: Sat, 30 Aug 2025 20:10:02 -0700
Subject: [PATCH 01/12] Update dev.md (#491)

To avoid AI creating new folder for a new story tasks
---
 bmad-core/agents/dev.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/bmad-core/agents/dev.md b/bmad-core/agents/dev.md
index f04c438c..6362a303 100644
--- a/bmad-core/agents/dev.md
+++ b/bmad-core/agents/dev.md
@@ -49,6 +49,7 @@ persona:
 
 core_principles:
   - CRITICAL: Story has ALL info you will need aside from what you loaded during the startup commands. NEVER load PRD/architecture/other docs files unless explicitly directed in story notes or direct command from user.
+  - CRITICAL: ALWAYS check current folder structure before starting your story tasks, don't create new working directory if it already exists. Create new one when you're sure it's a brand new project.
   - CRITICAL: ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
   - CRITICAL: FOLLOW THE develop-story command when the user tells you to implement the story
   - Numbered Options - Always use numbered lists when presenting choices to the user

From f054d68c29430035a66a3dc207416f3021646200 Mon Sep 17 00:00:00 2001
From: Piatra Automation <68414156+piatra-automation@users.noreply.github.com>
Date: Sun, 31 Aug 2025 13:14:52 +1000
Subject: [PATCH 02/12] fix: correct dependency path format in bmad-master
 agent (#495)

- Change 'Dependencies map to root/type/name' to 'Dependencies map to {root}/{type}/{name}'
- Fixes path resolution issue where 'root' was treated as literal directory name
- Ensures proper variable interpolation for dependency file loading
- Resolves agent inability to find core-config.yaml and other project files
---
 bmad-core/agents/bmad-master.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/bmad-core/agents/bmad-master.md b/bmad-core/agents/bmad-master.md
index 3aeb3b63..7dcb19fc 100644
--- a/bmad-core/agents/bmad-master.md
+++ b/bmad-core/agents/bmad-master.md
@@ -11,16 +11,16 @@ CRITICAL: Read the full YAML BLOCK that FOLLOWS IN THIS FILE to understand your
 ```yaml
 IDE-FILE-RESOLUTION:
   - FOR LATER USE ONLY - NOT FOR ACTIVATION, when executing commands that reference dependencies
-  - Dependencies map to root/type/name
+  - Dependencies map to {root}/{type}/{name}
   - type=folder (tasks|templates|checklists|data|utils|etc...), name=file-name
-  - Example: create-doc.md → root/tasks/create-doc.md
+  - Example: create-doc.md → {root}/tasks/create-doc.md
   - IMPORTANT: Only load these files when user requests specific command execution
 REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
   - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
-  - STEP 3: Load and read bmad-core/core-config.yaml (project configuration) before any greeting
-  - STEP 4: Greet user with your name/role and immediately run *help to display available commands
+  - STEP 3: Load and read `bmad-core/core-config.yaml` (project configuration) before any greeting
+  - STEP 4: Greet user with your name/role and immediately run `*help` to display available commands
   - DO NOT: Load any other agent files during activation
   - ONLY load dependency files when user selects them for execution via command or request of a task
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions

From 052e84dd4a3b84d49ef2fd2beec77a8a82329dba Mon Sep 17 00:00:00 2001
From: Bragatte <marcelobragatte@gmail.com>
Date: Sun, 31 Aug 2025 00:15:31 -0300
Subject: [PATCH 03/12] feat: implement fork-friendly CI/CD with opt-in
 mechanism (#476)

- CI/CD disabled by default in forks to conserve resources
- Users can enable via ENABLE_CI_IN_FORK repository variable
- Added comprehensive Fork Guide documentation
- Updated README with Contributing section
- Created automation script for future implementations

Benefits:
- Saves GitHub Actions minutes across 1,600+ forks
- Cleaner fork experience for contributors
- Full control for fork owners
- PR validation still runs automatically

BREAKING CHANGE: CI/CD no longer runs automatically in forks.
Fork owners must set ENABLE_CI_IN_FORK=true to enable workflows.

Co-authored-by: Brian <bmadcode@gmail.com>
Co-authored-by: PinkyD <paulbeanjr@gmail.com>
---
 .github/FORK_GUIDE.md                 | 104 ++++++++++++
 .github/workflows/discord.yaml        |   1 +
 .github/workflows/format-check.yaml   |   2 +
 .github/workflows/manual-release.yaml |   1 +
 README.md                             |  20 +++
 implement-fork-friendly-ci.sh         | 229 ++++++++++++++++++++++++++
 6 files changed, 357 insertions(+)
 create mode 100644 .github/FORK_GUIDE.md
 create mode 100755 implement-fork-friendly-ci.sh

diff --git a/.github/FORK_GUIDE.md b/.github/FORK_GUIDE.md
new file mode 100644
index 00000000..073d9c29
--- /dev/null
+++ b/.github/FORK_GUIDE.md
@@ -0,0 +1,104 @@
+# Fork Guide - CI/CD Configuration
+
+## CI/CD in Forks
+
+By default, CI/CD workflows are **disabled in forks** to conserve GitHub Actions resources and provide a cleaner fork experience.
+
+### Why This Approach?
+
+- **Resource efficiency**: Prevents unnecessary GitHub Actions usage across 1,600+ forks
+- **Clean fork experience**: No failed workflow notifications in your fork
+- **Full control**: Enable CI/CD only when you actually need it
+- **PR validation**: Your changes are still fully tested when submitting PRs to the main repository
+
+## Enabling CI/CD in Your Fork
+
+If you need to run CI/CD workflows in your fork, follow these steps:
+
+1. Navigate to your fork's **Settings** tab
+2. Go to **Secrets and variables** → **Actions** → **Variables**
+3. Click **New repository variable**
+4. Create a new variable:
+   - **Name**: `ENABLE_CI_IN_FORK`
+   - **Value**: `true`
+5. Click **Add variable**
+
+That's it! CI/CD workflows will now run in your fork.
+
+## Disabling CI/CD Again
+
+To disable CI/CD workflows in your fork, you can either:
+
+- **Delete the variable**: Remove the `ENABLE_CI_IN_FORK` variable entirely, or
+- **Set to false**: Change the `ENABLE_CI_IN_FORK` value to `false`
+
+## Alternative Testing Options
+
+You don't always need to enable CI/CD in your fork. Here are alternatives:
+
+### Local Testing
+
+Run tests locally before pushing:
+
+```bash
+# Install dependencies
+npm ci
+
+# Run linting
+npm run lint
+
+# Run format check
+npm run format:check
+
+# Run validation
+npm run validate
+
+# Build the project
+npm run build
+```
+
+### Pull Request CI
+
+When you open a Pull Request to the main repository:
+- All CI/CD workflows automatically run
+- You get full validation of your changes
+- No configuration needed
+
+### GitHub Codespaces
+
+Use GitHub Codespaces for a full development environment:
+- All tools pre-configured
+- Same environment as CI/CD
+- No local setup required
+
+## Frequently Asked Questions
+
+### Q: Will my PR be tested even if CI is disabled in my fork?
+
+**A:** Yes! When you open a PR to the main repository, all CI/CD workflows run automatically, regardless of your fork's settings.
+
+### Q: Can I selectively enable specific workflows?
+
+**A:** The `ENABLE_CI_IN_FORK` variable enables all workflows. For selective control, you'd need to modify individual workflow files.
+
+### Q: Do I need to enable CI in my fork to contribute?
+
+**A:** No! Most contributors never need to enable CI in their forks. Local testing and PR validation are sufficient for most contributions.
+
+### Q: Will disabling CI affect my ability to merge PRs?
+
+**A:** No! PR merge requirements are based on CI runs in the main repository, not your fork.
+
+### Q: Why was this implemented?
+
+**A:** With over 1,600 forks of BMAD-METHOD, this saves thousands of GitHub Actions minutes monthly while maintaining code quality standards.
+
+## Need Help?
+
+- Join our [Discord Community](https://discord.gg/gk8jAdXWmj) for support
+- Check the [Contributing Guide](../README.md#contributing) for more information
+- Open an issue if you encounter any problems
+
+---
+
+> 💡 **Pro Tip**: This fork-friendly approach is particularly valuable for projects using AI/LLM tools that create many experimental commits, as it prevents unnecessary CI runs while maintaining code quality standards.
\ No newline at end of file
diff --git a/.github/workflows/discord.yaml b/.github/workflows/discord.yaml
index 0d3eda6f..d66903a7 100644
--- a/.github/workflows/discord.yaml
+++ b/.github/workflows/discord.yaml
@@ -14,6 +14,7 @@ name: Discord Notification
 jobs:
   notify:
     runs-on: ubuntu-latest
+    if: github.event.repository.fork != true || vars.ENABLE_CI_IN_FORK == 'true'
     steps:
       - name: Notify Discord
         uses: sarisia/actions-status-discord@v1
diff --git a/.github/workflows/format-check.yaml b/.github/workflows/format-check.yaml
index 78525659..1b9b319d 100644
--- a/.github/workflows/format-check.yaml
+++ b/.github/workflows/format-check.yaml
@@ -7,6 +7,7 @@ name: format-check
 jobs:
   prettier:
     runs-on: ubuntu-latest
+    if: github.event.repository.fork != true || vars.ENABLE_CI_IN_FORK == 'true'
     steps:
       - name: Checkout
         uses: actions/checkout@v4
@@ -25,6 +26,7 @@ jobs:
 
   eslint:
     runs-on: ubuntu-latest
+    if: github.event.repository.fork != true || vars.ENABLE_CI_IN_FORK == 'true'
     steps:
       - name: Checkout
         uses: actions/checkout@v4
diff --git a/.github/workflows/manual-release.yaml b/.github/workflows/manual-release.yaml
index f5df668a..fc03a100 100644
--- a/.github/workflows/manual-release.yaml
+++ b/.github/workflows/manual-release.yaml
@@ -20,6 +20,7 @@ permissions:
 jobs:
   release:
     runs-on: ubuntu-latest
+    if: github.event.repository.fork != true || vars.ENABLE_CI_IN_FORK == 'true'
     steps:
       - name: Checkout
         uses: actions/checkout@v4
diff --git a/README.md b/README.md
index 41060958..135a2937 100644
--- a/README.md
+++ b/README.md
@@ -212,6 +212,26 @@ The generated XML file contains your project's text-based source files in a stru
 
 📋 **[Read CONTRIBUTING.md](CONTRIBUTING.md)** - Complete guide to contributing, including guidelines, process, and requirements
 
+### Working with Forks
+
+When you fork this repository, CI/CD workflows are **disabled by default** to save resources. This is intentional and helps keep your fork clean.
+
+#### Need CI/CD in Your Fork?
+
+See our [Fork CI/CD Guide](.github/FORK_GUIDE.md) for instructions on enabling workflows in your fork.
+
+#### Contributing Workflow
+
+1. **Fork the repository** - Click the Fork button on GitHub
+2. **Clone your fork** - `git clone https://github.com/YOUR-USERNAME/BMAD-METHOD.git`
+3. **Create a feature branch** - `git checkout -b feature/amazing-feature`
+4. **Make your changes** - Test locally with `npm test`
+5. **Commit your changes** - `git commit -m 'feat: add amazing feature'`
+6. **Push to your fork** - `git push origin feature/amazing-feature`
+7. **Open a Pull Request** - CI/CD will run automatically on the PR
+
+Your contributions are tested when you submit a PR - no need to enable CI in your fork!
+
 ## License
 
 MIT License - see [LICENSE](LICENSE) for details.
diff --git a/implement-fork-friendly-ci.sh b/implement-fork-friendly-ci.sh
new file mode 100755
index 00000000..da8e61b0
--- /dev/null
+++ b/implement-fork-friendly-ci.sh
@@ -0,0 +1,229 @@
+#!/bin/bash
+
+# Fork-Friendly CI/CD Implementation Script
+# Usage: ./implement-fork-friendly-ci.sh
+# 
+# This script automates the implementation of fork-friendly CI/CD
+# by adding fork detection conditions to all GitHub Actions workflows
+
+set -e
+
+echo "🚀 Implementing Fork-Friendly CI/CD..."
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# 1. Check if .github/workflows directory exists
+if [ ! -d ".github/workflows" ]; then
+    echo -e "${RED}✗${NC} No .github/workflows directory found"
+    echo "This script must be run from the repository root"
+    exit 1
+fi
+
+# 2. Backup existing workflows
+echo "📦 Backing up workflows..."
+backup_dir=".github/workflows.backup.$(date +%Y%m%d_%H%M%S)"
+cp -r .github/workflows "$backup_dir"
+echo -e "${GREEN}✓${NC} Workflows backed up to $backup_dir"
+
+# 3. Count workflow files and jobs
+WORKFLOW_COUNT=$(ls -1 .github/workflows/*.yml .github/workflows/*.yaml 2>/dev/null | wc -l)
+echo "📊 Found ${WORKFLOW_COUNT} workflow files"
+
+# 4. Process each workflow file
+UPDATED_FILES=0
+MANUAL_REVIEW_NEEDED=0
+
+for file in .github/workflows/*.yml .github/workflows/*.yaml; do
+    if [ -f "$file" ]; then
+        filename=$(basename "$file")
+        echo -n "Processing ${filename}... "
+        
+        # Create temporary file
+        temp_file="${file}.tmp"
+        
+        # Track if file needs manual review
+        needs_review=0
+        
+        # Process the file with awk
+        awk '
+        BEGIN {
+            in_jobs = 0
+            job_count = 0
+            modified = 0
+        }
+        
+        /^jobs:/ { 
+            in_jobs = 1
+            print
+            next
+        }
+        
+        # Match job definitions (2 spaces + name + colon)
+        in_jobs && /^  [a-z][a-z0-9_-]*:/ {
+            job_name = $0
+            print job_name
+            job_count++
+            
+            # Look ahead for existing conditions
+            getline next_line
+            
+            # Check if next line is already an if condition
+            if (next_line ~ /^    if:/) {
+                # Job already has condition - combine with fork detection
+                existing_condition = next_line
+                sub(/^    if: /, "", existing_condition)
+                
+                # Check if fork condition already exists
+                if (existing_condition !~ /github\.event\.repository\.fork/) {
+                    print "    # Fork-friendly CI: Combined with existing condition"
+                    print "    if: (" existing_condition ") && (github.event.repository.fork != true || vars.ENABLE_CI_IN_FORK == '\''true'\'')"
+                    modified++
+                } else {
+                    # Already has fork detection
+                    print next_line
+                }
+            } else if (next_line ~ /^    runs-on:/) {
+                # No condition exists, add before runs-on
+                print "    if: github.event.repository.fork != true || vars.ENABLE_CI_IN_FORK == '\''true'\''"
+                print next_line
+                modified++
+            } else {
+                # Some other configuration, preserve as-is
+                print next_line
+            }
+            next
+        }
+        
+        # Reset when leaving jobs section
+        /^[a-z]/ && in_jobs {
+            in_jobs = 0
+        }
+        
+        # Print all other lines
+        { 
+            if (!in_jobs) print 
+        }
+        
+        END {
+            if (modified > 0) {
+                exit 0  # Success - file was modified
+            } else {
+                exit 1  # No modifications needed
+            }
+        }
+        ' "$file" > "$temp_file"
+        
+        # Check if modifications were made
+        if [ $? -eq 0 ]; then
+            mv "$temp_file" "$file"
+            echo -e "${GREEN}✓${NC} Updated"
+            ((UPDATED_FILES++))
+        else
+            rm -f "$temp_file"
+            echo -e "${YELLOW}○${NC} No changes needed"
+        fi
+        
+        # Check for complex conditions that might need manual review
+        if grep -q "needs:" "$file" || grep -q "strategy:" "$file"; then
+            echo "  ⚠️  Complex workflow detected - manual review recommended"
+            ((MANUAL_REVIEW_NEEDED++))
+        fi
+    fi
+done
+
+echo -e "${GREEN}✓${NC} Updated ${UPDATED_FILES} workflow files"
+
+# 5. Create Fork Guide if it doesn't exist
+if [ ! -f ".github/FORK_GUIDE.md" ]; then
+    echo "📝 Creating Fork Guide documentation..."
+    cat > .github/FORK_GUIDE.md << 'EOF'
+# Fork Guide - CI/CD Configuration
+
+## CI/CD in Forks
+
+By default, CI/CD workflows are **disabled in forks** to conserve GitHub Actions resources.
+
+### Enabling CI/CD in Your Fork
+
+If you need to run CI/CD workflows in your fork:
+
+1. Navigate to **Settings** → **Secrets and variables** → **Actions** → **Variables**
+2. Click **New repository variable**
+3. Create variable:
+   - **Name**: `ENABLE_CI_IN_FORK`
+   - **Value**: `true`
+4. Click **Add variable**
+
+### Disabling CI/CD Again
+
+Either:
+- Delete the `ENABLE_CI_IN_FORK` variable, or
+- Set its value to `false`
+
+### Alternative Testing Options
+
+- **Local testing**: Run tests locally before pushing
+- **Pull Request CI**: Workflows automatically run when you open a PR
+- **GitHub Codespaces**: Full development environment
+EOF
+    echo -e "${GREEN}✓${NC} Fork Guide created"
+else
+    echo "ℹ️  Fork Guide already exists"
+fi
+
+# 6. Validate YAML files (if yamllint is available)
+if command -v yamllint &> /dev/null; then
+    echo "🔍 Validating YAML syntax..."
+    VALIDATION_ERRORS=0
+    for file in .github/workflows/*.yml .github/workflows/*.yaml; do
+        if [ -f "$file" ]; then
+            filename=$(basename "$file")
+            if yamllint -d relaxed "$file" &>/dev/null; then
+                echo -e "  ${GREEN}✓${NC} ${filename}"
+            else
+                echo -e "  ${RED}✗${NC} ${filename} - YAML validation failed"
+                ((VALIDATION_ERRORS++))
+            fi
+        fi
+    done
+    
+    if [ $VALIDATION_ERRORS -gt 0 ]; then
+        echo -e "${YELLOW}⚠${NC}  ${VALIDATION_ERRORS} files have YAML errors"
+    fi
+else
+    echo "ℹ️  yamllint not found - skipping YAML validation"
+    echo "  Install with: pip install yamllint"
+fi
+
+# 7. Summary
+echo ""
+echo "═══════════════════════════════════════"
+echo "       Fork-Friendly CI/CD Summary"
+echo "═══════════════════════════════════════"
+echo "  📁 Files updated: ${UPDATED_FILES}"
+echo "  📊 Total workflows: ${WORKFLOW_COUNT}"
+echo "  📝 Fork Guide: .github/FORK_GUIDE.md"
+if [ $MANUAL_REVIEW_NEEDED -gt 0 ]; then
+    echo "  ⚠️  Files needing review: ${MANUAL_REVIEW_NEEDED}"
+fi
+echo ""
+echo "Next steps:"
+echo "1. Review the changes: git diff"
+echo "2. Test workflows locally (if possible)"
+echo "3. Commit changes: git commit -m 'feat: implement fork-friendly CI/CD'"
+echo "4. Push and create PR"
+echo ""
+echo "Remember to update README.md with fork information!"
+echo "═══════════════════════════════════════"
+
+# Exit with appropriate code
+if [ $UPDATED_FILES -gt 0 ]; then
+    exit 0
+else
+    echo "No files were updated - workflows may already be fork-friendly"
+    exit 1
+fi
\ No newline at end of file

From 05736fa06903275567c885aa4492f6b03dea7b26 Mon Sep 17 00:00:00 2001
From: Jonathan Borgwing <jon@learnvig.com>
Date: Sun, 31 Aug 2025 18:48:03 -0400
Subject: [PATCH 04/12] feat(installer): add Codex CLI + Codex Web modes,
 generate AGENTS.md, inject npm scripts, and docs (#529)

---
 README.md                                  |  16 ++
 docs/user-guide.md                         |  26 +++
 tools/installer/bin/bmad.js                |   2 +-
 tools/installer/config/install.config.yaml |  22 +++
 tools/installer/lib/ide-setup.js           | 175 +++++++++++++++++++++
 5 files changed, 240 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 135a2937..c22292f6 100644
--- a/README.md
+++ b/README.md
@@ -243,3 +243,19 @@ BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved
 [![Contributors](https://contrib.rocks/image?repo=bmadcode/bmad-method)](https://github.com/bmadcode/bmad-method/graphs/contributors)
 
 <sub>Built with ❤️ for the AI-assisted development community</sub>
+
+#### Codex (CLI & Web)
+
+- Two modes are supported:
+  - Codex (local only): `npx bmad-method install -f -i codex -d .` — keeps `.bmad-core/` ignored via `.gitignore` for local development.
+  - Codex Web Enabled: `npx bmad-method install -f -i codex-web -d .` — ensures `.bmad-core/` is tracked (not ignored) so it can be committed for Codex Web.
+- For Codex Web, commit both `.bmad-core/` and `AGENTS.md` to the repository.
+- Codex CLI: run `codex` at your project root; reference agents naturally, e.g., “As dev, implement …”.
+- Codex Web: open your repo in Codex and prompt the same way — it reads `AGENTS.md` automatically.
+- Refresh after changes: rerun the appropriate install command (`codex` or `codex-web`) to regenerate the BMAD section inside `AGENTS.md`.
+
+If a `package.json` exists in your project, the installer will add helpful scripts:
+
+- `bmad:refresh` → `bmad-method install -f -i codex`
+- `bmad:list` → `bmad-method list:agents`
+- `bmad:validate` → `bmad-method validate`
diff --git a/docs/user-guide.md b/docs/user-guide.md
index 43c2daf6..117b08b4 100644
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -187,6 +187,32 @@ If you want to do the planning on the web with Claude (Sonnet 4 or Opus), Gemini
 npx bmad-method install
 ```
 
+### Codex (CLI & Web)
+
+BMAD integrates with OpenAI Codex via `AGENTS.md` and committed core agent files.
+
+- Two installation modes:
+  - Codex (local only): keeps `.bmad-core/` ignored for local dev.
+    - `npx bmad-method install -f -i codex -d .`
+  - Codex Web Enabled: ensures `.bmad-core/` is tracked so you can commit it for Codex Web.
+    - `npx bmad-method install -f -i codex-web -d .`
+
+- What gets generated:
+  - `AGENTS.md` at the project root with a BMAD section containing
+    - How-to-use with Codex (CLI & Web)
+    - Agent Directory (Title, ID, When To Use)
+    - Detailed per‑agent sections with source path, when-to-use, activation phrasing, and YAML
+    - Tasks with quick usage notes
+  - If a `package.json` exists, helpful scripts are added:
+    - `bmad:refresh`, `bmad:list`, `bmad:validate`
+
+- Using Codex:
+  - CLI: run `codex` in the project root and prompt naturally, e.g., “As dev, implement …”.
+  - Web: commit `.bmad-core/` and `AGENTS.md`, then open the repo in Codex and prompt the same way.
+
+- Refresh after changes:
+  - Re-run the appropriate install mode (`codex` or `codex-web`) to update the BMAD block in `AGENTS.md`.
+
 ## Special Agents
 
 There are two BMad agents — in the future they'll be consolidated into a single BMad-Master.
diff --git a/tools/installer/bin/bmad.js b/tools/installer/bin/bmad.js
index b8272c14..ce8ded5a 100755
--- a/tools/installer/bin/bmad.js
+++ b/tools/installer/bin/bmad.js
@@ -49,7 +49,7 @@ program
   .option('-d, --directory <path>', 'Installation directory')
   .option(
     '-i, --ide <ide...>',
-    'Configure for specific IDE(s) - can specify multiple (cursor, claude-code, windsurf, trae, roo, kilo, cline, gemini, qwen-code, github-copilot, other)',
+    'Configure for specific IDE(s) - can specify multiple (cursor, claude-code, windsurf, trae, roo, kilo, cline, gemini, qwen-code, github-copilot, codex, codex-web, other)',
   )
   .option(
     '-e, --expansion-packs <packs...>',
diff --git a/tools/installer/config/install.config.yaml b/tools/installer/config/install.config.yaml
index 43013550..e929b722 100644
--- a/tools/installer/config/install.config.yaml
+++ b/tools/installer/config/install.config.yaml
@@ -121,3 +121,25 @@ ide-configurations:
       # 2. It concatenates all agent files into a single QWEN.md file.
       # 3. Simply mention the agent in your prompt (e.g., "As *dev, ...").
       # 4. The Qwen Code CLI will automatically have the context for that agent.
+
+  codex:
+    name: Codex CLI
+    format: project-memory
+    file: AGENTS.md
+    instructions: |
+      # To use BMAD agents with Codex CLI:
+      # 1. The installer updates/creates AGENTS.md at your project root with BMAD agents and tasks.
+      # 2. Run `codex` in your project. Codex automatically reads AGENTS.md as project memory.
+      # 3. Mention agents in your prompt (e.g., "As dev, please implement ...") or reference tasks.
+      # 4. You can further customize global Codex behavior via ~/.codex/config.toml.
+
+  codex-web:
+    name: Codex Web Enabled
+    format: project-memory
+    file: AGENTS.md
+    instructions: |
+      # To enable BMAD agents for Codex Web (cloud):
+      # 1. The installer updates/creates AGENTS.md and ensures `.bmad-core` is NOT ignored by git.
+      # 2. Commit `.bmad-core/` and `AGENTS.md` to your repository.
+      # 3. Open the repo in Codex Web and reference agents naturally (e.g., "As dev, ...").
+      # 4. Re-run this installer to refresh agent sections when the core changes.
diff --git a/tools/installer/lib/ide-setup.js b/tools/installer/lib/ide-setup.js
index b6944ad1..2dd33302 100644
--- a/tools/installer/lib/ide-setup.js
+++ b/tools/installer/lib/ide-setup.js
@@ -74,6 +74,12 @@ class IdeSetup extends BaseIdeSetup {
       case 'qwen-code': {
         return this.setupQwenCode(installDir, selectedAgent);
       }
+      case 'codex': {
+        return this.setupCodex(installDir, selectedAgent, { webEnabled: false });
+      }
+      case 'codex-web': {
+        return this.setupCodex(installDir, selectedAgent, { webEnabled: true });
+      }
       default: {
         console.log(chalk.yellow(`\nIDE ${ide} not yet supported`));
         return false;
@@ -81,6 +87,175 @@ class IdeSetup extends BaseIdeSetup {
     }
   }
 
+  async setupCodex(installDir, selectedAgent, options) {
+    options = options ?? { webEnabled: false };
+    // Codex reads AGENTS.md at the project root as project memory (CLI & Web).
+    // Inject/update a BMAD section with guidance, directory, and details.
+    const filePath = path.join(installDir, 'AGENTS.md');
+    const startMarker = '<!-- BEGIN: BMAD-AGENTS -->';
+    const endMarker = '<!-- END: BMAD-AGENTS -->';
+
+    const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
+    const tasks = await this.getAllTaskIds(installDir);
+
+    // Build BMAD section content
+    let section = '';
+    section += `${startMarker}\n`;
+    section += `# BMAD-METHOD Agents and Tasks\n\n`;
+    section += `This section is auto-generated by BMAD-METHOD for Codex. Codex merges this AGENTS.md into context.\n\n`;
+    section += `## How To Use With Codex\n\n`;
+    section += `- Codex CLI: run \`codex\` in this project. Reference an agent naturally, e.g., "As dev, implement ...".\n`;
+    section += `- Codex Web: open this repo and reference roles the same way; Codex reads \`AGENTS.md\`.\n`;
+    section += `- Commit \`.bmad-core\` and this \`AGENTS.md\` file to your repo so Codex (Web/CLI) can read full agent definitions.\n`;
+    section += `- Refresh this section after agent updates: \`npx bmad-method install -f -i codex\`.\n\n`;
+
+    section += `### Helpful Commands\n\n`;
+    section += `- List agents: \`npx bmad-method list:agents\`\n`;
+    section += `- Reinstall BMAD core and regenerate AGENTS.md: \`npx bmad-method install -f -i codex\`\n`;
+    section += `- Validate configuration: \`npx bmad-method validate\`\n\n`;
+
+    // Agents directory table
+    section += `## Agents\n\n`;
+    section += `### Directory\n\n`;
+    section += `| Title | ID | When To Use |\n|---|---|---|\n`;
+    const agentSummaries = [];
+    for (const agentId of agents) {
+      const agentPath = await this.findAgentPath(agentId, installDir);
+      if (!agentPath) continue;
+      const raw = await fileManager.readFile(agentPath);
+      const yamlMatch = raw.match(/```ya?ml\r?\n([\s\S]*?)```/);
+      const yamlBlock = yamlMatch ? yamlMatch[1].trim() : null;
+      const title = await this.getAgentTitle(agentId, installDir);
+      const whenToUse = yamlBlock?.match(/whenToUse:\s*"?([^\n"]+)"?/i)?.[1]?.trim() || '';
+      agentSummaries.push({ agentId, title, whenToUse, yamlBlock, raw, path: agentPath });
+      section += `| ${title} | ${agentId} | ${whenToUse || '—'} |\n`;
+    }
+    section += `\n`;
+
+    // Detailed agent sections
+    for (const { agentId, title, whenToUse, yamlBlock, raw, path: agentPath } of agentSummaries) {
+      const relativePath = path.relative(installDir, agentPath).replaceAll('\\', '/');
+      section += `### ${title} (id: ${agentId})\n`;
+      section += `Source: ${relativePath}\n\n`;
+      if (whenToUse) section += `- When to use: ${whenToUse}\n`;
+      section += `- How to activate: Mention "As ${agentId}, ..." or "Use ${title} to ..."\n\n`;
+      if (yamlBlock) {
+        section += '```yaml\n' + yamlBlock + '\n```\n\n';
+      } else {
+        section += '```md\n' + raw.trim() + '\n```\n\n';
+      }
+    }
+
+    // Tasks
+    if (tasks && tasks.length > 0) {
+      section += `## Tasks\n\n`;
+      section += `These are reusable task briefs you can reference directly in Codex.\n\n`;
+      for (const taskId of tasks) {
+        const taskPath = await this.findTaskPath(taskId, installDir);
+        if (!taskPath) continue;
+        const raw = await fileManager.readFile(taskPath);
+        const relativePath = path.relative(installDir, taskPath).replaceAll('\\', '/');
+        section += `### Task: ${taskId}\n`;
+        section += `Source: ${relativePath}\n`;
+        section += `- How to use: "Use task ${taskId} with the appropriate agent" and paste relevant parts as needed.\n\n`;
+        section += '```md\n' + raw.trim() + '\n```\n\n';
+      }
+    }
+
+    section += `${endMarker}\n`;
+
+    // Write or update AGENTS.md
+    let finalContent = '';
+    if (await fileManager.pathExists(filePath)) {
+      const existing = await fileManager.readFile(filePath);
+      if (existing.includes(startMarker) && existing.includes(endMarker)) {
+        // Replace existing BMAD block
+        const pattern = String.raw`${startMarker}[\s\S]*?${endMarker}`;
+        const replaced = existing.replace(new RegExp(pattern, 'm'), section);
+        finalContent = replaced;
+      } else {
+        // Append BMAD block to existing file
+        finalContent = existing.trimEnd() + `\n\n` + section;
+      }
+    } else {
+      // Create fresh AGENTS.md with a small header and BMAD block
+      finalContent += '# Project Agents\n\n';
+      finalContent += 'This file provides guidance and memory for Codex CLI.\n\n';
+      finalContent += section;
+    }
+
+    await fileManager.writeFile(filePath, finalContent);
+    console.log(chalk.green('✓ Created/updated AGENTS.md for Codex CLI integration'));
+    console.log(
+      chalk.dim(
+        'Codex reads AGENTS.md automatically. Run `codex` in this project to use BMAD agents.',
+      ),
+    );
+
+    // Optionally add helpful npm scripts if a package.json exists
+    try {
+      const pkgPath = path.join(installDir, 'package.json');
+      if (await fileManager.pathExists(pkgPath)) {
+        const pkgRaw = await fileManager.readFile(pkgPath);
+        const pkg = JSON.parse(pkgRaw);
+        pkg.scripts = pkg.scripts || {};
+        const updated = { ...pkg.scripts };
+        if (!updated['bmad:refresh']) updated['bmad:refresh'] = 'bmad-method install -f -i codex';
+        if (!updated['bmad:list']) updated['bmad:list'] = 'bmad-method list:agents';
+        if (!updated['bmad:validate']) updated['bmad:validate'] = 'bmad-method validate';
+        const changed = JSON.stringify(updated) !== JSON.stringify(pkg.scripts);
+        if (changed) {
+          const newPkg = { ...pkg, scripts: updated };
+          await fileManager.writeFile(pkgPath, JSON.stringify(newPkg, null, 2) + '\n');
+          console.log(chalk.green('✓ Added npm scripts: bmad:refresh, bmad:list, bmad:validate'));
+        }
+      }
+    } catch {
+      console.log(
+        chalk.yellow('⚠︎ Skipped adding npm scripts (package.json not writable or invalid)'),
+      );
+    }
+
+    // Adjust .gitignore behavior depending on Codex mode
+    try {
+      const gitignorePath = path.join(installDir, '.gitignore');
+      const ignoreLines = ['# BMAD (local only)', '.bmad-core/', '.bmad-*/'];
+      const exists = await fileManager.pathExists(gitignorePath);
+      if (options.webEnabled) {
+        if (exists) {
+          let gi = await fileManager.readFile(gitignorePath);
+          // Remove lines that ignore BMAD dot-folders
+          const updated = gi
+            .split(/\r?\n/)
+            .filter((l) => !/^\s*\.bmad-core\/?\s*$/.test(l) && !/^\s*\.bmad-\*\/?\s*$/.test(l))
+            .join('\n');
+          if (updated !== gi) {
+            await fileManager.writeFile(gitignorePath, updated.trimEnd() + '\n');
+            console.log(chalk.green('✓ Updated .gitignore to include .bmad-core in commits'));
+          }
+        }
+      } else {
+        // Local-only: add ignores if missing
+        let base = exists ? await fileManager.readFile(gitignorePath) : '';
+        const haveCore = base.includes('.bmad-core/');
+        const haveStar = base.includes('.bmad-*/');
+        if (!haveCore || !haveStar) {
+          const sep = base.endsWith('\n') || base.length === 0 ? '' : '\n';
+          const add = [!haveCore || !haveStar ? ignoreLines.join('\n') : '']
+            .filter(Boolean)
+            .join('\n');
+          const out = base + sep + add + '\n';
+          await fileManager.writeFile(gitignorePath, out);
+          console.log(chalk.green('✓ Added .bmad-core/* to .gitignore for local-only Codex setup'));
+        }
+      }
+    } catch {
+      console.log(chalk.yellow('⚠︎ Could not update .gitignore (skipping)'));
+    }
+
+    return true;
+  }
+
   async setupCursor(installDir, selectedAgent) {
     const cursorRulesDir = path.join(installDir, '.cursor', 'rules', 'bmad');
     const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);

From fb70c200671786a31dedbec6f6ed8c4d96b6e4b0 Mon Sep 17 00:00:00 2001
From: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
Date: Sun, 31 Aug 2025 20:30:52 -0500
Subject: [PATCH 05/12] feat: add PR validation workflow and contribution
 checks

---
 .github/FORK_GUIDE.md                         |  4 +-
 .github/workflows/pr-validation.yaml          | 55 +++++++++++++++++++
 CONTRIBUTING.md                               | 41 ++++++++++++++
 bmad-core/workflows/brownfield-fullstack.yaml |  4 +-
 bmad-core/workflows/brownfield-service.yaml   |  4 +-
 bmad-core/workflows/brownfield-ui.yaml        |  4 +-
 bmad-core/workflows/greenfield-fullstack.yaml |  8 +--
 bmad-core/workflows/greenfield-service.yaml   |  4 +-
 bmad-core/workflows/greenfield-ui.yaml        |  6 +-
 package.json                                  |  3 +
 tools/setup-hooks.sh                          | 37 +++++++++++++
 11 files changed, 154 insertions(+), 16 deletions(-)
 create mode 100644 .github/workflows/pr-validation.yaml
 create mode 100755 tools/setup-hooks.sh

diff --git a/.github/FORK_GUIDE.md b/.github/FORK_GUIDE.md
index 073d9c29..d7ed2bd4 100644
--- a/.github/FORK_GUIDE.md
+++ b/.github/FORK_GUIDE.md
@@ -60,6 +60,7 @@ npm run build
 ### Pull Request CI
 
 When you open a Pull Request to the main repository:
+
 - All CI/CD workflows automatically run
 - You get full validation of your changes
 - No configuration needed
@@ -67,6 +68,7 @@ When you open a Pull Request to the main repository:
 ### GitHub Codespaces
 
 Use GitHub Codespaces for a full development environment:
+
 - All tools pre-configured
 - Same environment as CI/CD
 - No local setup required
@@ -101,4 +103,4 @@ Use GitHub Codespaces for a full development environment:
 
 ---
 
-> 💡 **Pro Tip**: This fork-friendly approach is particularly valuable for projects using AI/LLM tools that create many experimental commits, as it prevents unnecessary CI runs while maintaining code quality standards.
\ No newline at end of file
+> 💡 **Pro Tip**: This fork-friendly approach is particularly valuable for projects using AI/LLM tools that create many experimental commits, as it prevents unnecessary CI runs while maintaining code quality standards.
diff --git a/.github/workflows/pr-validation.yaml b/.github/workflows/pr-validation.yaml
new file mode 100644
index 00000000..5bacb4f0
--- /dev/null
+++ b/.github/workflows/pr-validation.yaml
@@ -0,0 +1,55 @@
+name: PR Validation
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, synchronize, reopened]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork != true || vars.ENABLE_CI_IN_FORK == 'true'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run validation
+        run: npm run validate
+
+      - name: Check formatting
+        run: npm run format:check
+
+      - name: Run linter
+        run: npm run lint
+
+      - name: Run tests (if available)
+        run: npm test --if-present
+
+      - name: Comment on PR if checks fail
+        if: failure()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body: `❌ **PR Validation Failed**
+              
+              This PR has validation errors that must be fixed before merging:
+              - Run \`npm run validate\` to check agent/team configs
+              - Run \`npm run format:check\` to check formatting (fix with \`npm run format\`)
+              - Run \`npm run lint\` to check linting issues (fix with \`npm run lint:fix\`)
+              
+              Please fix these issues and push the changes.`
+            })
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index fe988154..2ad976dc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,6 +17,47 @@ Also note, we use the discussions feature in GitHub to have a community to discu
 
 By participating in this project, you agree to abide by our Code of Conduct. Please read it before participating.
 
+## Before Submitting a PR
+
+**IMPORTANT**: All PRs must pass validation checks before they can be merged.
+
+### Required Checks
+
+Before submitting your PR, run these commands locally:
+
+```bash
+# Run all validation checks
+npm run pre-release
+
+# Or run them individually:
+npm run validate     # Validate agent/team configs
+npm run format:check # Check code formatting
+npm run lint        # Check for linting issues
+```
+
+### Fixing Issues
+
+If any checks fail, use these commands to fix them:
+
+```bash
+# Fix all issues automatically
+npm run fix
+
+# Or fix individually:
+npm run format      # Fix formatting issues
+npm run lint:fix    # Fix linting issues
+```
+
+### Setup Git Hooks (Optional but Recommended)
+
+To catch issues before committing:
+
+```bash
+# Run this once after cloning
+chmod +x tools/setup-hooks.sh
+./tools/setup-hooks.sh
+```
+
 ## How to Contribute
 
 ### Reporting Bugs
diff --git a/bmad-core/workflows/brownfield-fullstack.yaml b/bmad-core/workflows/brownfield-fullstack.yaml
index 6a7d7d87..a696b0a8 100644
--- a/bmad-core/workflows/brownfield-fullstack.yaml
+++ b/bmad-core/workflows/brownfield-fullstack.yaml
@@ -160,7 +160,7 @@ workflow:
         - Dev Agent (New Chat): Address remaining items
         - Return to QA for final approval
 
-    - repeat_development_cycle:
+    - step: repeat_development_cycle
       action: continue_for_all_stories
       notes: |
         Repeat story cycle (SM → Dev → QA) for all epic stories
@@ -177,7 +177,7 @@ workflow:
         - Validate epic was completed correctly
         - Document learnings and improvements
 
-    - workflow_end:
+    - step: workflow_end
       action: project_complete
       notes: |
         All stories implemented and reviewed!
diff --git a/bmad-core/workflows/brownfield-service.yaml b/bmad-core/workflows/brownfield-service.yaml
index e2af23de..6c8148cd 100644
--- a/bmad-core/workflows/brownfield-service.yaml
+++ b/bmad-core/workflows/brownfield-service.yaml
@@ -106,7 +106,7 @@ workflow:
         - Dev Agent (New Chat): Address remaining items
         - Return to QA for final approval
 
-    - repeat_development_cycle:
+    - step: repeat_development_cycle
       action: continue_for_all_stories
       notes: |
         Repeat story cycle (SM → Dev → QA) for all epic stories
@@ -123,7 +123,7 @@ workflow:
         - Validate epic was completed correctly
         - Document learnings and improvements
 
-    - workflow_end:
+    - step: workflow_end
       action: project_complete
       notes: |
         All stories implemented and reviewed!
diff --git a/bmad-core/workflows/brownfield-ui.yaml b/bmad-core/workflows/brownfield-ui.yaml
index 4a9ffd76..9e249f4e 100644
--- a/bmad-core/workflows/brownfield-ui.yaml
+++ b/bmad-core/workflows/brownfield-ui.yaml
@@ -113,7 +113,7 @@ workflow:
         - Dev Agent (New Chat): Address remaining items
         - Return to QA for final approval
 
-    - repeat_development_cycle:
+    - step: repeat_development_cycle
       action: continue_for_all_stories
       notes: |
         Repeat story cycle (SM → Dev → QA) for all epic stories
@@ -130,7 +130,7 @@ workflow:
         - Validate epic was completed correctly
         - Document learnings and improvements
 
-    - workflow_end:
+    - step: workflow_end
       action: project_complete
       notes: |
         All stories implemented and reviewed!
diff --git a/bmad-core/workflows/greenfield-fullstack.yaml b/bmad-core/workflows/greenfield-fullstack.yaml
index 1425d9f2..1fa8a6a8 100644
--- a/bmad-core/workflows/greenfield-fullstack.yaml
+++ b/bmad-core/workflows/greenfield-fullstack.yaml
@@ -65,12 +65,12 @@ workflow:
       condition: po_checklist_issues
       notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
 
-    - project_setup_guidance:
+    - step: project_setup_guidance
       action: guide_project_structure
       condition: user_has_generated_ui
       notes: "If user generated UI with v0/Lovable: For polyrepo setup, place downloaded project in separate frontend repo alongside backend repo. For monorepo, place in apps/web or packages/frontend directory. Review architecture document for specific guidance."
 
-    - development_order_guidance:
+    - step: development_order_guidance
       action: guide_development_sequence
       notes: "Based on PRD stories: If stories are frontend-heavy, start with frontend project/directory first. If backend-heavy or API-first, start with backend. For tightly coupled features, follow story sequence in monorepo setup. Reference sharded PRD epics for development order."
 
@@ -138,7 +138,7 @@ workflow:
         - Dev Agent (New Chat): Address remaining items
         - Return to QA for final approval
 
-    - repeat_development_cycle:
+    - step: repeat_development_cycle
       action: continue_for_all_stories
       notes: |
         Repeat story cycle (SM → Dev → QA) for all epic stories
@@ -155,7 +155,7 @@ workflow:
         - Validate epic was completed correctly
         - Document learnings and improvements
 
-    - workflow_end:
+    - step: workflow_end
       action: project_complete
       notes: |
         All stories implemented and reviewed!
diff --git a/bmad-core/workflows/greenfield-service.yaml b/bmad-core/workflows/greenfield-service.yaml
index c30c0132..c8339678 100644
--- a/bmad-core/workflows/greenfield-service.yaml
+++ b/bmad-core/workflows/greenfield-service.yaml
@@ -114,7 +114,7 @@ workflow:
         - Dev Agent (New Chat): Address remaining items
         - Return to QA for final approval
 
-    - repeat_development_cycle:
+    - step: repeat_development_cycle
       action: continue_for_all_stories
       notes: |
         Repeat story cycle (SM → Dev → QA) for all epic stories
@@ -131,7 +131,7 @@ workflow:
         - Validate epic was completed correctly
         - Document learnings and improvements
 
-    - workflow_end:
+    - step: workflow_end
       action: project_complete
       notes: |
         All stories implemented and reviewed!
diff --git a/bmad-core/workflows/greenfield-ui.yaml b/bmad-core/workflows/greenfield-ui.yaml
index 2b3e5f46..14678458 100644
--- a/bmad-core/workflows/greenfield-ui.yaml
+++ b/bmad-core/workflows/greenfield-ui.yaml
@@ -64,7 +64,7 @@ workflow:
       condition: po_checklist_issues
       notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
 
-    - project_setup_guidance:
+    - step: project_setup_guidance
       action: guide_project_structure
       condition: user_has_generated_ui
       notes: "If user generated UI with v0/Lovable: For polyrepo setup, place downloaded project in separate frontend repo. For monorepo, place in apps/web or frontend/ directory. Review architecture document for specific guidance."
@@ -133,7 +133,7 @@ workflow:
         - Dev Agent (New Chat): Address remaining items
         - Return to QA for final approval
 
-    - repeat_development_cycle:
+    - step: repeat_development_cycle
       action: continue_for_all_stories
       notes: |
         Repeat story cycle (SM → Dev → QA) for all epic stories
@@ -150,7 +150,7 @@ workflow:
         - Validate epic was completed correctly
         - Document learnings and improvements
 
-    - workflow_end:
+    - step: workflow_end
       action: project_complete
       notes: |
         All stories implemented and reviewed!
diff --git a/package.json b/package.json
index 3bbd7627..8033b6a8 100644
--- a/package.json
+++ b/package.json
@@ -27,6 +27,7 @@
     "build": "node tools/cli.js build",
     "build:agents": "node tools/cli.js build --agents-only",
     "build:teams": "node tools/cli.js build --teams-only",
+    "fix": "npm run format && npm run lint:fix",
     "flatten": "node tools/flattener/main.js",
     "format": "prettier --write \"**/*.{js,cjs,mjs,json,md,yaml}\"",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,md,yaml}\"",
@@ -34,12 +35,14 @@
     "lint": "eslint . --ext .js,.cjs,.mjs,.yaml --max-warnings=0",
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "list:agents": "node tools/cli.js list:agents",
+    "pre-release": "npm run validate && npm run format:check && npm run lint",
     "prepare": "husky",
     "preview:release": "node tools/preview-release-notes.js",
     "release:major": "gh workflow run \"Manual Release\" -f version_bump=major",
     "release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
     "release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
     "release:watch": "gh run watch",
+    "setup:hooks": "chmod +x tools/setup-hooks.sh && ./tools/setup-hooks.sh",
     "validate": "node tools/cli.js validate",
     "version:all": "node tools/bump-all-versions.js",
     "version:all:major": "node tools/bump-all-versions.js major",
diff --git a/tools/setup-hooks.sh b/tools/setup-hooks.sh
new file mode 100755
index 00000000..f8838508
--- /dev/null
+++ b/tools/setup-hooks.sh
@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# Setup script for git hooks
+echo "Setting up git hooks..."
+
+# Install husky
+npm install --save-dev husky
+
+# Initialize husky
+npx husky init
+
+# Create pre-commit hook
+cat > .husky/pre-commit << 'EOF'
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+# Run validation checks before commit
+echo "Running pre-commit checks..."
+
+npm run validate
+npm run format:check
+npm run lint
+
+if [ $? -ne 0 ]; then
+  echo "❌ Pre-commit checks failed. Please fix the issues before committing."
+  echo "   Run 'npm run format' to fix formatting issues"
+  echo "   Run 'npm run lint:fix' to fix some lint issues"
+  exit 1
+fi
+
+echo "✅ Pre-commit checks passed!"
+EOF
+
+chmod +x .husky/pre-commit
+
+echo "✅ Git hooks setup complete!"
+echo "Now commits will be validated before they're created."
\ No newline at end of file

From e2e8d44e5dca1aa5c88dd7a4e770a5d591351c00 Mon Sep 17 00:00:00 2001
From: Brian <bmadcode@gmail.com>
Date: Sun, 31 Aug 2025 20:34:39 -0500
Subject: [PATCH 06/12] test: trigger PR validation (#533)

Co-authored-by: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
---
 test.md | 1 +
 1 file changed, 1 insertion(+)
 create mode 100644 test.md

diff --git a/test.md b/test.md
new file mode 100644
index 00000000..8ae05696
--- /dev/null
+++ b/test.md
@@ -0,0 +1 @@
+# Test

From 0a6cbd72cc3d6d014bd330b2313b05603597aed4 Mon Sep 17 00:00:00 2001
From: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
Date: Sun, 31 Aug 2025 21:45:21 -0500
Subject: [PATCH 07/12] chore: bump version to 4.42.0 for release

- Update main package.json to 4.42.0
- Update installer package.json to 4.42.0
- Add PR validation workflow and contribution checks
- Add pre-release and fix scripts
- Update CONTRIBUTING.md with validation requirements
---
 package.json                 | 2 +-
 tools/installer/package.json | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/package.json b/package.json
index 8033b6a8..e672eebd 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "4.40.1",
+  "version": "4.42.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
diff --git a/tools/installer/package.json b/tools/installer/package.json
index fd5da503..ee94b2e6 100644
--- a/tools/installer/package.json
+++ b/tools/installer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.39.1",
+  "version": "4.42.0",
   "description": "BMad Method installer - AI-powered Agile development framework",
   "keywords": [
     "bmad",

From b9bc196e7f3cd2628fbfa7961a8c1cbe9ca1533b Mon Sep 17 00:00:00 2001
From: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
Date: Sun, 31 Aug 2025 21:57:39 -0500
Subject: [PATCH 08/12] chore: sync version to 4.42.1 after release

- Update package.json to match published npm version
- Update installer package.json to match
---
 package-lock.json                 | 4 ++--
 package.json                      | 2 +-
 tools/installer/package-lock.json | 4 ++--
 tools/installer/package.json      | 2 +-
 4 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index cc948733..0c8df958 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "4.40.1",
+  "version": "4.42.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "4.40.1",
+      "version": "4.42.1",
       "license": "MIT",
       "dependencies": {
         "@kayvan/markdown-tree-parser": "^1.6.1",
diff --git a/package.json b/package.json
index e672eebd..16fd5ec2 100644
--- a/package.json
+++ b/package.json
@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "4.42.0",
+  "version": "4.42.1",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
diff --git a/tools/installer/package-lock.json b/tools/installer/package-lock.json
index 0c18278e..f4fb6a02 100644
--- a/tools/installer/package-lock.json
+++ b/tools/installer/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "4.37.0-beta.4",
+  "version": "4.42.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "4.37.0-beta.4",
+      "version": "4.42.1",
       "license": "MIT",
       "dependencies": {
         "chalk": "^4.1.2",
diff --git a/tools/installer/package.json b/tools/installer/package.json
index ee94b2e6..50d85ac0 100644
--- a/tools/installer/package.json
+++ b/tools/installer/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.42.0",
+  "version": "4.42.1",
   "description": "BMad Method installer - AI-powered Agile development framework",
   "keywords": [
     "bmad",

From 384e17ff2b3656f5e489b02d60be63dbff969fde Mon Sep 17 00:00:00 2001
From: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
Date: Sun, 31 Aug 2025 22:05:29 -0500
Subject: [PATCH 09/12] docs: remove misplaced Codex section from README

- Remove IDE-specific Codex documentation from end of README
- This content was oddly placed after the footer
- IDE-specific docs should be in separate documentation
---
 README.md | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/README.md b/README.md
index c22292f6..135a2937 100644
--- a/README.md
+++ b/README.md
@@ -243,19 +243,3 @@ BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved
 [![Contributors](https://contrib.rocks/image?repo=bmadcode/bmad-method)](https://github.com/bmadcode/bmad-method/graphs/contributors)
 
 <sub>Built with ❤️ for the AI-assisted development community</sub>
-
-#### Codex (CLI & Web)
-
-- Two modes are supported:
-  - Codex (local only): `npx bmad-method install -f -i codex -d .` — keeps `.bmad-core/` ignored via `.gitignore` for local development.
-  - Codex Web Enabled: `npx bmad-method install -f -i codex-web -d .` — ensures `.bmad-core/` is tracked (not ignored) so it can be committed for Codex Web.
-- For Codex Web, commit both `.bmad-core/` and `AGENTS.md` to the repository.
-- Codex CLI: run `codex` at your project root; reference agents naturally, e.g., “As dev, implement …”.
-- Codex Web: open your repo in Codex and prompt the same way — it reads `AGENTS.md` automatically.
-- Refresh after changes: rerun the appropriate install command (`codex` or `codex-web`) to regenerate the BMAD section inside `AGENTS.md`.
-
-If a `package.json` exists in your project, the installer will add helpful scripts:
-
-- `bmad:refresh` → `bmad-method install -f -i codex`
-- `bmad:list` → `bmad-method list:agents`
-- `bmad:validate` → `bmad-method validate`

From fbd8f1fd73988843418231d836d5e463bca28a15 Mon Sep 17 00:00:00 2001
From: Brian Madison <brianmadison@Brians-MacBook-Pro.local>
Date: Sun, 31 Aug 2025 22:15:40 -0500
Subject: [PATCH 10/12] Expansion pack doc correction

---
 docs/expansion-packs.md | 86 ++---------------------------------------
 1 file changed, 3 insertions(+), 83 deletions(-)

diff --git a/docs/expansion-packs.md b/docs/expansion-packs.md
index 69b94b4e..9a7897c3 100644
--- a/docs/expansion-packs.md
+++ b/docs/expansion-packs.md
@@ -18,7 +18,7 @@ Each expansion pack provides deep, specialized knowledge without bloating the co
 
 Anyone can create and share expansion packs, fostering a ecosystem of AI-powered solutions across all industries and interests.
 
-## Technical Expansion Packs
+## Technical Expansion Packs (Examples of possible expansions to come)
 
 ### Game Development Pack
 
@@ -191,90 +191,10 @@ Research acceleration tools:
 
 ## Creating Your Own Expansion Pack
 
-### Step 1: Define Your Domain
-
-What expertise are you capturing? What problems will it solve?
-
-### Step 2: Design Your Agents
-
-Each agent should have:
-
-- Clear expertise area
-- Specific personality traits
-- Defined capabilities
-- Knowledge boundaries
-
-### Step 3: Create Tasks
-
-Tasks should be:
-
-- Step-by-step procedures
-- Reusable across scenarios
-- Clear and actionable
-- Domain-specific
-
-### Step 4: Build Templates
-
-Templates need:
-
-- Structured output format
-- Embedded LLM instructions
-- Placeholders for customization
-- Professional formatting
-
-### Step 5: Test & Iterate
-
-- Use with real scenarios
-- Gather user feedback
-- Refine agent responses
-- Improve task clarity
-
-### Step 6: Package & Share
-
-- Create clear documentation
-- Include usage examples
-- Add to expansion-packs directory
-- Share with community
-
-## The Future of Expansion Packs
-
-### Marketplace Potential
-
-Imagine a future where:
-
-- Professional expansion packs are sold
-- Certified packs for regulated industries
-- Community ratings and reviews
-- Automatic updates and improvements
-
-### AI Agent Ecosystems
-
-Expansion packs could enable:
-
-- Cross-pack agent collaboration
-- Industry-standard agent protocols
-- Interoperable AI workflows
-- Universal agent languages
-
-### Democratizing Expertise
-
-Every expansion pack:
-
-- Makes expert knowledge accessible
-- Reduces barriers to entry
-- Enables solo entrepreneurs
-- Empowers small teams
-
-## Getting Started
-
-1. **Browse existing packs**: Check `expansion-packs/` directory
-2. **Install what you need**: Use the installer's expansion pack option
-3. **Create your own**: Use the expansion-creator pack
-4. **Share with others**: Submit PRs with new packs
-5. **Build the future**: Help shape AI-assisted work
+The next major release will include a new agent and expansion pack builder and a new expansion format.
 
 ## Remember
 
-The BMad Method is more than a development framework - it's a platform for structuring human expertise into AI-accessible formats. Every expansion pack you create makes specialized knowledge more accessible to everyone.
+The BMad Method is more than a Software Development Agile Framework! Every expansion pack makes specialized knowledge and workflows more accessible to everyone.
 
 **What expertise will you share with the world?**

From 6919049eae9cc03e37f36fb356dbd73ec237b2c3 Mon Sep 17 00:00:00 2001
From: Mikhail Romanov <42250412+Ribas160@users.noreply.github.com>
Date: Tue, 2 Sep 2025 20:13:00 +0300
Subject: [PATCH 11/12] fix: Codex options missing from the IDE selection menu
 (#535)

---
 tools/installer/bin/bmad.js | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tools/installer/bin/bmad.js b/tools/installer/bin/bmad.js
index ce8ded5a..fba56533 100755
--- a/tools/installer/bin/bmad.js
+++ b/tools/installer/bin/bmad.js
@@ -406,6 +406,8 @@ async function promptInstallation() {
           { name: 'Qwen Code', value: 'qwen-code' },
           { name: 'Crush', value: 'crush' },
           { name: 'Github Copilot', value: 'github-copilot' },
+          { name: 'Codex CLI', value: 'codex' },
+          { name: 'Codex Web', value: 'codex-web' },
         ],
       },
     ]);

From 155f9591eabd089f2a7bf0b1822d4dd169669eed Mon Sep 17 00:00:00 2001
From: Hau Vo <hau.vophuoc@gmail.com>
Date: Wed, 3 Sep 2025 00:16:26 +0700
Subject: [PATCH 12/12] feat: Add Auggie CLI (Augment Code) Integration (#520)

* feat: add Augment Code IDE support with multi-location installation options

- Add Augment Code to supported IDE list in installer CLI and interactive prompts
- Configure multi-location setup for Augment Code commands:
  - User Commands: ~/.augment/commands/bmad/ (global, user-wide)
  - Workspace Commands: ./.augment/commands/bmad/ (project-specific, team-shared)
- Update IDE configuration with proper location handling and tilde expansion
- Add interactive prompt for users to select installation locations
- Update documentation in bmad-kb.md to include Augment Code in supported IDEs
- Implement setupAugmentCode method with location selection and file installation

This enables BMAD Method integration with Augment Code's custom command system,
allowing users to access BMad agents via /agent-name slash commands in both
global and project-specific contexts.

* Added options to choose the rule locations

* Update instruction to match with namespace for commands

* Update instruction to match with namespace for commands

* Renamed Augment Code to Auggie CLI (Augment Code)

---------

Co-authored-by: Hau Vo <hauvo@Haus-Mac-mini.local>
Co-authored-by: Brian <bmadcode@gmail.com>
---
 bmad-core/data/bmad-kb.md                  |  1 +
 tools/installer/bin/bmad.js                | 35 +++++++-
 tools/installer/config/install.config.yaml | 19 +++++
 tools/installer/lib/ide-setup.js           | 93 ++++++++++++++++++++++
 tools/installer/lib/installer.js           |  7 +-
 5 files changed, 153 insertions(+), 2 deletions(-)

diff --git a/bmad-core/data/bmad-kb.md b/bmad-core/data/bmad-kb.md
index 04d3b5f9..47d5cb6c 100644
--- a/bmad-core/data/bmad-kb.md
+++ b/bmad-core/data/bmad-kb.md
@@ -102,6 +102,7 @@ npx bmad-method install
   - **Cline**: VS Code extension with AI features
   - **Roo Code**: Web-based IDE with agent support
   - **GitHub Copilot**: VS Code extension with AI peer programming assistant
+  - **Auggie CLI (Augment Code)**: AI-powered development environment
 
 **Note for VS Code Users**: BMAD-METHOD™ assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMad agents. The installer includes built-in support for Cline and Roo.
 
diff --git a/tools/installer/bin/bmad.js b/tools/installer/bin/bmad.js
index fba56533..f121417b 100755
--- a/tools/installer/bin/bmad.js
+++ b/tools/installer/bin/bmad.js
@@ -49,7 +49,7 @@ program
   .option('-d, --directory <path>', 'Installation directory')
   .option(
     '-i, --ide <ide...>',
-    'Configure for specific IDE(s) - can specify multiple (cursor, claude-code, windsurf, trae, roo, kilo, cline, gemini, qwen-code, github-copilot, codex, codex-web, other)',
+    'Configure for specific IDE(s) - can specify multiple (cursor, claude-code, windsurf, trae, roo, kilo, cline, gemini, qwen-code, github-copilot, codex, codex-web, auggie-cli, other)',
   )
   .option(
     '-e, --expansion-packs <packs...>',
@@ -406,6 +406,7 @@ async function promptInstallation() {
           { name: 'Qwen Code', value: 'qwen-code' },
           { name: 'Crush', value: 'crush' },
           { name: 'Github Copilot', value: 'github-copilot' },
+          { name: 'Auggie CLI (Augment Code)', value: 'auggie-cli' },
           { name: 'Codex CLI', value: 'codex' },
           { name: 'Codex Web', value: 'codex-web' },
         ],
@@ -476,6 +477,38 @@ async function promptInstallation() {
     answers.githubCopilotConfig = { configChoice };
   }
 
+  // Configure Auggie CLI (Augment Code) immediately if selected
+  if (ides.includes('auggie-cli')) {
+    console.log(chalk.cyan('\n📍 Auggie CLI Location Configuration'));
+    console.log(chalk.dim('Choose where to install BMad agents for Auggie CLI access.\n'));
+
+    const { selectedLocations } = await inquirer.prompt([
+      {
+        type: 'checkbox',
+        name: 'selectedLocations',
+        message: 'Select Auggie CLI command locations:',
+        choices: [
+          {
+            name: 'User Commands (Global): Available across all your projects (user-wide)',
+            value: 'user',
+          },
+          {
+            name: 'Workspace Commands (Project): Stored in repository, shared with team',
+            value: 'workspace',
+          },
+        ],
+        validate: (selected) => {
+          if (selected.length === 0) {
+            return 'Please select at least one location';
+          }
+          return true;
+        },
+      },
+    ]);
+
+    answers.augmentCodeConfig = { selectedLocations };
+  }
+
   // Ask for web bundles installation
   const { includeWebBundles } = await inquirer.prompt([
     {
diff --git a/tools/installer/config/install.config.yaml b/tools/installer/config/install.config.yaml
index e929b722..0444813a 100644
--- a/tools/installer/config/install.config.yaml
+++ b/tools/installer/config/install.config.yaml
@@ -122,6 +122,25 @@ ide-configurations:
       # 3. Simply mention the agent in your prompt (e.g., "As *dev, ...").
       # 4. The Qwen Code CLI will automatically have the context for that agent.
 
+  auggie-cli:
+    name: Auggie CLI (Augment Code)
+    format: multi-location
+    locations:
+      user:
+        name: User Commands (Global)
+        rule-dir: ~/.augment/commands/bmad/
+        description: Available across all your projects (user-wide)
+      workspace:
+        name: Workspace Commands (Project)
+        rule-dir: ./.augment/commands/bmad/
+        description: Stored in your repository and shared with your team
+    command-suffix: .md
+    instructions: |
+      # To use BMad agents in Auggie CLI (Augment Code):
+      # 1. Type /bmad:agent-name (e.g., "/bmad:dev", "/bmad:pm", "/bmad:architect")
+      # 2. The agent will adopt that persona for the conversation
+      # 3. Commands are available based on your selected location(s)
+
   codex:
     name: Codex CLI
     format: project-memory
diff --git a/tools/installer/lib/ide-setup.js b/tools/installer/lib/ide-setup.js
index 2dd33302..a0ff58c7 100644
--- a/tools/installer/lib/ide-setup.js
+++ b/tools/installer/lib/ide-setup.js
@@ -74,6 +74,9 @@ class IdeSetup extends BaseIdeSetup {
       case 'qwen-code': {
         return this.setupQwenCode(installDir, selectedAgent);
       }
+      case 'auggie-cli': {
+        return this.setupAuggieCLI(installDir, selectedAgent, spinner, preConfiguredSettings);
+      }
       case 'codex': {
         return this.setupCodex(installDir, selectedAgent, { webEnabled: false });
       }
@@ -1611,6 +1614,96 @@ tools: ['changes', 'codebase', 'fetch', 'findTestFiles', 'githubRepo', 'problems
     console.log(chalk.dim(''));
     console.log(chalk.dim('You can modify these settings anytime in .vscode/settings.json'));
   }
+
+  async setupAuggieCLI(installDir, selectedAgent, spinner = null, preConfiguredSettings = null) {
+    const os = require('node:os');
+    const inquirer = require('inquirer');
+    const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
+
+    // Get the IDE configuration to access location options
+    const ideConfig = await configLoader.getIdeConfiguration('auggie-cli');
+    const locations = ideConfig.locations;
+
+    // Use pre-configured settings if provided, otherwise prompt
+    let selectedLocations;
+    if (preConfiguredSettings && preConfiguredSettings.selectedLocations) {
+      selectedLocations = preConfiguredSettings.selectedLocations;
+      console.log(
+        chalk.dim(
+          `Using pre-configured Auggie CLI (Augment Code) locations: ${selectedLocations.join(', ')}`,
+        ),
+      );
+    } else {
+      // Pause spinner during location selection to avoid UI conflicts
+      let spinnerWasActive = false;
+      if (spinner && spinner.isSpinning) {
+        spinner.stop();
+        spinnerWasActive = true;
+      }
+
+      // Clear any previous output and add spacing to avoid conflicts with loaders
+      console.log('\n'.repeat(2));
+      console.log(chalk.blue('📍 Auggie CLI Location Configuration'));
+      console.log(chalk.dim('Choose where to install BMad agents for Auggie CLI access.'));
+      console.log(''); // Add extra spacing
+
+      const response = await inquirer.prompt([
+        {
+          type: 'checkbox',
+          name: 'selectedLocations',
+          message: 'Select Auggie CLI command locations:',
+          choices: Object.entries(locations).map(([key, location]) => ({
+            name: `${location.name}: ${location.description}`,
+            value: key,
+          })),
+          validate: (selected) => {
+            if (selected.length === 0) {
+              return 'Please select at least one location';
+            }
+            return true;
+          },
+        },
+      ]);
+      selectedLocations = response.selectedLocations;
+
+      // Restart spinner if it was active before prompts
+      if (spinner && spinnerWasActive) {
+        spinner.start();
+      }
+    }
+
+    // Install to each selected location
+    for (const locationKey of selectedLocations) {
+      const location = locations[locationKey];
+      let commandsDir = location['rule-dir'];
+
+      // Handle tilde expansion for user directory
+      if (commandsDir.startsWith('~/')) {
+        commandsDir = path.join(os.homedir(), commandsDir.slice(2));
+      } else if (commandsDir.startsWith('./')) {
+        commandsDir = path.join(installDir, commandsDir.slice(2));
+      }
+
+      await fileManager.ensureDirectory(commandsDir);
+
+      for (const agentId of agents) {
+        // Find the agent file
+        const agentPath = await this.findAgentPath(agentId, installDir);
+
+        if (agentPath) {
+          const agentContent = await fileManager.readFile(agentPath);
+          const mdPath = path.join(commandsDir, `${agentId}.md`);
+          await fileManager.writeFile(mdPath, agentContent);
+          console.log(chalk.green(`✓ Created command: ${agentId}.md in ${location.name}`));
+        }
+      }
+
+      console.log(chalk.green(`\n✓ Created Auggie CLI commands in ${commandsDir}`));
+      console.log(chalk.dim(`  Location: ${location.name} - ${location.description}`));
+    }
+
+    return true;
+  }
 }
 
 module.exports = new IdeSetup();
diff --git a/tools/installer/lib/installer.js b/tools/installer/lib/installer.js
index e709b4cf..8b7e9d8d 100644
--- a/tools/installer/lib/installer.js
+++ b/tools/installer/lib/installer.js
@@ -408,7 +408,12 @@ class Installer {
     if (ides.length > 0) {
       for (const ide of ides) {
         spinner.text = `Setting up ${ide} integration...`;
-        const preConfiguredSettings = ide === 'github-copilot' ? config.githubCopilotConfig : null;
+        let preConfiguredSettings = null;
+        if (ide === 'github-copilot') {
+          preConfiguredSettings = config.githubCopilotConfig;
+        } else if (ide === 'auggie-cli') {
+          preConfiguredSettings = config.augmentCodeConfig;
+        }
         await ideSetup.setup(ide, installDir, config.agent, spinner, preConfiguredSettings);
       }
     }