bmad-project-setup

name	bmad-project-setup
description	Initialize a new project with BMAD methodology — pull docs from Outline Cloud, setup _bmad structure, generate epics and stories, commit to develop branch. Reusable for any new product going through BMAD analysis.
tags	["bmad","planning","epics","stories","sprint-planning","project-init"]

BMAD Project Setup Workflow

Standard workflow for initializing a new project with BMAD (Business Model Analysis & Design) methodology. Covers: Outline Cloud doc sync, BMAD structure setup, epic/story generation, and git branch configuration.

Prerequisites

• GitHub repo exists with docs (or Outline Cloud collection with project docs)
• BMAD skills installed globally at ${BMAD_SKILLS_DIR}/
• A coding agent CLI available at ${CODING_AGENT_PATH} (for scaffolding tasks)
• Outline API key in ${ENV_FILE} as OUTLINE_API_KEY=***

Step 1: Pull Docs from Outline Cloud

Outline Cloud is the single source of truth for project documentation. Always pull latest before generating planning artifacts.

→ See references/outline-api-integration.md for full API code and configuration.

Step 2: Setup _bmad Directory Structure

BMAD skills need _bmad/ with access to global skill files, and _bmad-output/ for generated artifacts.

cd ${PROJECT_DIR}

# Create _bmad with symlinks to global BMAD
mkdir -p _bmad
ln -s ${BMAD_SKILLS_DIR} _bmad/scripts
ln -s ${BMAD_CORE_DIR} _bmad/core
ln -s ${BMAD_CONFIG_DIR} _bmad/_config
mkdir -p _bmad/custom
touch _bmad/custom/.gitignore

# Create output directories
mkdir -p _bmad-output/planning-artifacts
mkdir -p _bmad-output/implementation-artifacts

⚠️ CRITICAL: Symlinks are NOT portable and must be gitignored. Only commit _bmad-output/ (the artifacts), NOT _bmad/ (the tooling symlinks).

# BMAD local symlinks (global BMAD installed at ~/.agents/)
_bmad/

Step 3: Generate Epics & Stories (BMAD CE)

Generate epics & stories directly in the agent. Read planning artifacts, then write the epics file. Large doc generation tasks may timeout in coding agents — use the planning agent for document generation.

Epics file format (_bmad-output/planning-artifacts/epics-<module>.md):

• Scope definition (in/out) + dependency graph between epics
• Each epic: goal, effort estimate, priority, stories
• Each story: as-a/I-want/so-that, acceptance criteria (- [ ] AC1: ...), priority (P0/P1/P2), tech notes
• Effort summary table + sprint plan suggestion + API endpoints summary

Step 4: Git Branch Setup

Default Branch = develop

All new projects use develop as default branch (not main). All merges require PR.

git checkout -b develop
git push -u origin develop

# Set as default on GitHub
GITHUB_TOKEN=$(grep OUTLINE_API_KEY ${ENV_FILE} | cut -d= -f2) \
  ${GH_CLI_PATH} repo edit --default-branch develop

CODEOWNERS for PR Enforcement

GitHub Free plan does not support branch protection API (returns 403). Use CODEOWNERS as workaround.

mkdir -p .github
cat > .github/CODEOWNERS << 'EOF'
* ${GITHUB_USERNAME}
/internal/ ${GITHUB_USERNAME}
/web/ ${GITHUB_USERNAME}
EOF

This auto-requests reviews but doesn't block merges. Soft enforcement only on Free plan.

Step 5: Commit & Push

git add .gitignore .github/CODEOWNERS _bmad-output/
git commit -m "feat: add BMAD planning artifacts and <module> epics"
git push origin develop

Workflow: Branch → PR → Merge (always)

feature/xxx → create PR → review → merge to develop
develop → create PR → review → merge to main (release)

NEVER push directly to develop or main. Always via PR.

Step 6: Go Workspace Scaffold

→ See references/go-scaffold-via-coding-agent.md for full scaffold instructions.

Task → Tool Matrix

Task	Tool	Why
Epic/story generation	Planning agent (direct)	Large doc output; coding agents may timeout
Sprint planning	Planning agent (direct)	Planning doc, not code
Code scaffold	Coding agent (background)	Code generation strength
Code review	Coding agent	Code analysis
Outline doc push	Planning agent (direct)	API calls + content

BMAD Skill Codes Reference

Code	Name	Purpose
CE	bmad-create-epics-and-stories	Generate epics & stories from artifacts
CA	bmad-create-architecture	Architecture design
IR	bmad-check-implementation-readiness	Pre-implementation checklist
SP	bmad-sprint-planning	Sprint planning from stories
CS	bmad-create-story	Create individual story
DS	bmad-dev-story	Implement a story
QQ	bmad-quick-dev	Quick development task
GPC	bmad-generate-project-context	Generate project context summary

Related Skills

• github-pr-workflow — PR lifecycle, branch protection, CODEOWNERS
• writing-plans — Tech spec and implementation planning
• plan — Inspect context and write spec before large tasks