ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/scripts/epic-execute-lib/INIT.md

9.3 KiB
Raw Blame History

Epic Execute - Dependencies & Setup

This document describes the required and optional dependencies for running the epic-execute.sh script and its library modules.

Required Dependencies

Core Requirements

Package Purpose Installation
bash Shell interpreter (v4.0+) Pre-installed on macOS/Linux
git Version control operations Pre-installed or brew install git
claude Claude Code CLI for AI-powered execution npm install -g @anthropic-ai/claude-code

Required CLI Tools

Tool Purpose macOS Linux (Debian/Ubuntu)
timeout Command timeout handling brew install coreutils (use gtimeout) Pre-installed
sed Text processing Pre-installed (BSD) Pre-installed (GNU)
grep Pattern matching Pre-installed Pre-installed
awk Text processing Pre-installed Pre-installed
date Timestamp generation Pre-installed Pre-installed
wc Character/line counting Pre-installed Pre-installed

Recommended Dependencies

These tools enhance functionality but have fallback behavior if missing:

yq (YAML Processing)

Strongly Recommended - Used for YAML file manipulation (metrics, story status updates).

# macOS (Homebrew)
brew install yq

# Linux (Go version - recommended)
go install github.com/mikefarah/yq/v4@latest

# Linux (snap)
snap install yq

# Linux (wget binary)
wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
chmod +x /usr/local/bin/yq

Important: The script expects the mikefarah/yq Go version (v4+), NOT the Python yq (kislyuk/yq). The Python version has different syntax and will trigger fallback mode.

Without yq:

  • YAML updates use sed fallback (less reliable)
  • Metrics updates may be deferred
  • Story status updates may fail silently

jq (JSON Processing)

Recommended - Used for JSON output parsing from Claude responses.

# macOS
brew install jq

# Linux (Debian/Ubuntu)
apt-get install jq

# Linux (RHEL/CentOS)
yum install jq

Without jq:

  • JSON parsing falls back to regex patterns (less accurate)
  • Some structured output extraction may fail

xmllint (XML Validation)

Optional - Used for validating XML workflow files.

# macOS
# Pre-installed as part of libxml2

# Linux (Debian/Ubuntu)
apt-get install libxml2-utils

# Linux (RHEL/CentOS)
yum install libxml2

Without xmllint:

  • XML validation uses basic pattern matching
  • Invalid XML may not be detected until runtime

Project-Specific Test Runners

The regression gate module auto-detects project type and requires the appropriate test runner:

Project Type Detection File Required Tool
Node.js/TypeScript package.json npm (with test script)
Rust Cargo.toml cargo
Go go.mod go
Python requirements.txt or pyproject.toml pytest

Quick Setup Script

Run this to check and install all dependencies on macOS:

#!/bin/bash
# epic-execute-setup.sh

echo "Checking epic-execute dependencies..."

# Check required tools
for tool in git bash; do
    if command -v $tool >/dev/null 2>&1; then
        echo "✓ $tool installed"
    else
        echo "✗ $tool NOT FOUND - please install"
    fi
done

# Check Claude CLI
if command -v claude >/dev/null 2>&1; then
    echo "✓ claude CLI installed"
else
    echo "✗ claude CLI NOT FOUND"
    echo "  Install with: npm install -g @anthropic-ai/claude-code"
fi

# Check yq (Go version)
if command -v yq >/dev/null 2>&1; then
    if yq --version 2>&1 | grep -qE "(mikefarah|version.*v4)"; then
        echo "✓ yq (Go version) installed"
    else
        echo "⚠ yq installed but may be Python version - recommend Go version"
        echo "  Install with: brew install yq"
    fi
else
    echo "⚠ yq NOT FOUND - YAML updates will use sed fallback"
    echo "  Install with: brew install yq"
fi

# Check jq
if command -v jq >/dev/null 2>&1; then
    echo "✓ jq installed"
else
    echo "⚠ jq NOT FOUND - JSON parsing will use regex fallback"
    echo "  Install with: brew install jq"
fi

# Check xmllint
if command -v xmllint >/dev/null 2>&1; then
    echo "✓ xmllint installed"
else
    echo "⚠ xmllint NOT FOUND - XML validation will be limited"
fi

# Check timeout (coreutils on macOS)
if command -v timeout >/dev/null 2>&1 || command -v gtimeout >/dev/null 2>&1; then
    echo "✓ timeout command available"
else
    echo "⚠ timeout NOT FOUND"
    echo "  Install with: brew install coreutils"
fi

echo ""
echo "Dependency check complete."

Environment Variables

The script respects these environment variables:

Variable Default Purpose
CLAUDE_TIMEOUT 600 Timeout in seconds for Claude invocations
MAX_PROMPT_SIZE 150000 Maximum prompt size in bytes
RETRY_MAX_ATTEMPTS 3 Max retry attempts for transient failures
RETRY_INITIAL_DELAY 5 Initial retry delay in seconds
RETRY_MAX_DELAY 60 Maximum retry delay in seconds
PROTECTED_BRANCHES main master Branches that block direct commits
VERBOSE false Enable verbose logging

Directory Structure & Path Configuration

The epic-execute.sh script expects specific directory structures in your project. Before running, inspect your repository and ensure paths are configured correctly.

BMAD-METHOD Repository Structure

The script sources BMAD workflows from these locations relative to the script:

BMAD-METHOD/
├── scripts/
│   ├── epic-execute.sh              # Main script
│   └── epic-execute-lib/            # Library modules
│       ├── utils.sh
│       ├── json-output.sh
│       ├── decision-log.sh
│       ├── design-phase.sh
│       ├── tdd-flow.sh
│       └── regression-gate.sh
└── src/
    ├── bmm-skills/                          # Upstream skill-based workflows (v6.1+)
    │   └── 4-implementation/
    │       ├── bmad-dev-story/             # Dev phase skill
    │       │   ├── SKILL.md
    │       │   └── checklist.md
    │       └── bmad-code-review/           # Review phase skill
    │           ├── SKILL.md
    │           └── steps/
    └── bmm/                                 # Our automation workflows
        └── workflows/
            └── 4-implementation/
                └── epic-execute/            # Quality gate steps
                    ├── steps/
                    │   ├── step-02b-arch-compliance.md
                    │   ├── step-03b-test-quality.md
                    │   ├── step-03c-traceability.md
                    │   └── step-04-generate-uat.md
                    └── templates/
                        └── uat-template.md

Target Project Structure

The script expects your target project (where stories are implemented) to have:

your-project/
├── docs/
│   ├── stories/           # Story markdown files (e.g., 1-1-feature.md)
│   ├── epics/             # Epic definition files
│   ├── sprints/           # Sprint planning files
│   ├── sprint-artifacts/  # Generated metrics, checkpoints, decision logs
│   │   ├── metrics/
│   │   ├── traceability/
│   │   └── test-specs/
│   └── uat/               # Generated UAT documents
└── bmad/                  # Optional: local BMAD configuration

Path Resolution

The script determines paths as follows:

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"    # Two levels up from script
BMAD_SRC_DIR="$SCRIPT_DIR/.."                       # One level up (scripts parent)

Important: If you install BMAD-METHOD differently (e.g., as a submodule, npm package, or symlink), you may need to adjust PROJECT_ROOT detection in epic-execute.sh lines 104-106.

Inspecting Your Setup

Before first run, verify your paths:

# From your target project root, check BMAD-METHOD location
ls -la ./node_modules/bmad-method/scripts/ 2>/dev/null || \
ls -la ./bmad-method/scripts/ 2>/dev/null || \
echo "BMAD-METHOD not found - check installation"

# Verify workflow files exist
BMAD_PATH="<path-to-bmad-method>"
ls -la "$BMAD_PATH/src/bmm-skills/4-implementation/bmad-dev-story/SKILL.md"
ls -la "$BMAD_PATH/src/bmm-skills/4-implementation/bmad-code-review/SKILL.md"
ls -la "$BMAD_PATH/src/bmm/workflows/4-implementation/epic-execute/"

# Verify your project has required directories
ls -la ./docs/stories/
ls -la ./docs/epics/

Creating Missing Directories

If your project doesn't have the expected structure:

# Create required directories
mkdir -p docs/{stories,epics,sprints,sprint-artifacts,uat}
mkdir -p docs/sprint-artifacts/{metrics,traceability,test-specs}

Verification

After installing dependencies, verify the setup:

# Run the script with --dry-run to verify setup
./scripts/epic-execute.sh <epic-id> --dry-run --verbose

The verbose output will show:

  • Platform detection
  • yq availability and version
  • Protected branch configuration
  • Workflow file validation results
  • Missing workflow files (if any)