ajianaz/codomate/bmad-project-setup

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

BMAD Skill Codes Reference

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