docs(epic-execute): add dependency and setup documentation
Add INIT.md documenting: - Required dependencies (bash, git, claude CLI) - Recommended dependencies (yq, jq, xmllint) - Project-specific test runners - Quick setup script for dependency checking - Environment variables reference - Directory structure and path configuration - Path resolution explanation for target projects Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Caleb
parent
51e31ada91
commit
efc0bdd56f
|
|
@ -0,0 +1,306 @@
|
|||
# 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).
|
||||
|
||||
```bash
|
||||
# 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](https://github.com/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.
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
#!/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/
|
||||
├── core/
|
||||
│ └── tasks/
|
||||
│ └── workflow.xml # Core workflow executor
|
||||
└── modules/
|
||||
└── bmm/
|
||||
└── workflows/
|
||||
└── 4-implementation/
|
||||
├── dev-story/ # Dev phase workflow
|
||||
│ ├── workflow.yaml
|
||||
│ ├── instructions.xml
|
||||
│ └── checklist.md
|
||||
├── code-review/ # Review phase workflow
|
||||
│ ├── workflow.yaml
|
||||
│ ├── instructions.xml
|
||||
│ └── checklist.md
|
||||
└── 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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/modules/bmm/workflows/4-implementation/dev-story/"
|
||||
ls -la "$BMAD_PATH/src/modules/bmm/workflows/4-implementation/code-review/"
|
||||
ls -la "$BMAD_PATH/src/core/tasks/workflow.xml"
|
||||
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
Loading…
Reference in New Issue