Skip to the content.

HOWTO β€” From /init to /finalize with BMAD, driven by Claude Code (MCP)

This guide runs a whole CLike project from a Claude Code session, through MCP, with the BMAD methodology: each phase is guided by the BMAD role that owns it, and CLike keeps the governance (contracts, locked tests, regression, gate, promotion). The setup of the MCP servers is in howto-mcp-project.md; the picture of the whole is in clike-at-a-glance.md.

The sequence

# Phase Tool (clike-ext) BMAD role What it produces
0 INIT harper_init β€” docs/harper/, .clike/, runs/, templates (existing files kept)
1 IDEA harper_run_phase {phase: "idea", methodology: "bmad", agent: "analyst", attachments: [...]} analyst docs/harper/IDEA.md (+ docs/harper/bmad/idea/ brief, assumptions)
2 SPEC harper_run_phase {phase: "spec", methodology: "bmad", agent: "pm"} pm docs/harper/SPEC.md (+ PRD, epics, acceptance model)
3 UX (optional) harper_run_phase {phase: "spec", methodology: "bmad", agent: "ux"} ux docs/harper/ux/ journeys, states, design β€” SPEC untouched
4 PLAN harper_run_phase {phase: "plan", methodology: "bmad", agent: "architect"} architect docs/harper/PLAN.md, plan.json (the REQs), lane guides
5 per REQ: KIT harper_run_phase {phase: "kit", req_id, methodology: "bmad", agent: "developer"} developer runs/kit/<REQ>/ code, tests, eval profile
6 per REQ: EVAL eval_run {req_id, fix: true} (CLike) the verdict; failures repaired, tests locked
7 per REQ: GATE gate_check {req_id} (CLike only) PASS β†’ promoted into src/, test/, root files
8 FINALIZE harper_run_phase {phase: "finalize", methodology: "bmad", agent: "tech-writer"} tech-writer solution running and configured, FINALIZE_REPORT.md, setup/start scripts

Roles allowed per phase: idea β†’ analyst; spec β†’ pm, ux; plan β†’ architect, pm; kit β†’ developer; finalize β†’ tech-writer; /idea --extend β†’ analyst, pm (default), architect, ux. The gate is CLike’s alone: no methodology there.

Step by step

0. Prepare (once per project)

  1. Create an empty folder under CLIKE_PROJECTS_DIR (e.g. ~/dev/projects/pingboard) and open it in VS Code with the CLike extension active and clike.mcp.extensionServerEnabled on.
  2. Copy the .mcp.json of howto-mcp-project.md (servers clike and clike-ext) into the folder; export CLIKE_API_TOKEN and CLIKE_EXT_MCP_TOKEN.
  3. Start claude in that folder and check both servers with /mcp.

1. Init

Ask Claude: β€œInitialize this folder as a CLike project with harper_init.” CLike creates the Harper structure in place and keeps any file already there.

2. Inputs

Put the requirement documents in docs/inputs/ (for a later release: docs/inputs/v2/), UI material in docs/harper/ux/, background in docs/reference/. Claude can write or copy them there; they are read-only for the phases.

3. Documents with BMAD

harper_run_phase {phase: "idea", methodology: "bmad", agent: "analyst", attachments: ["docs/inputs/brief.docx"]}
harper_run_phase {phase: "spec", methodology: "bmad", agent: "pm"}
harper_run_phase {phase: "spec", methodology: "bmad", agent: "ux"}          # optional, UI projects
harper_run_phase {phase: "plan", methodology: "bmad", agent: "architect"}

Each call returns a run_id; a long phase answers status: running β€” poll harper_run_status {run_id}. Read the results with the clike tools (harper_plan_read, harper_req_list, harper_doc_read) or ask Claude to open the files.

4. The REQ loop

harper_next_action                                   # in-progress REQ, else first open REQ with dependencies done
harper_run_phase {phase: "kit", req_id: "REQ-001", methodology: "bmad", agent: "developer"}
eval_run {req_id: "REQ-001", fix: true}              # repair loop, tests locked
gate_check {req_id: "REQ-001"}                       # PASS β†’ promoted; verdict reused if nothing changed

Repeat until harper_next_action answers finalize_only. If it answers blocked, the open REQs wait for dependencies that are not done: finish those first.

5. Finalize

harper_run_phase {phase: "finalize", methodology: "bmad", agent: "tech-writer"}

With REQs not promoted, it stops and says so; confirm: true runs it anyway. The developer then reads docs/harper/FINALIZE_REPORT.md and starts the solution with scripts/start_solution_local.

6. Next release

harper_run_phase {phase: "idea", extend: true, release: "v2", methodology: "bmad", agent: "analyst", dry_run: true}
harper_run_phase {phase: "idea", extend: true, release: "v2", methodology: "bmad", agent: "analyst"}

then steps 4 and 5 for the new REQs.

One instruction for Claude Code

Use the clike-ext MCP tools to deliver this project with BMAD. Run harper_init. Then idea (analyst, attach every file in docs/inputs/), spec (pm), plan (architect); show me the REQ list and wait for my OK. Then, for each REQ from harper_next_action: kit (developer), eval_run with fix, gate_check; poll harper_run_status for long runs; if a gate fails twice, stop and report the failures. When harper_next_action says finalize_only, run finalize (tech-writer) and summarize FINALIZE_REPORT.md.

Keeping a human check after PLAN is deliberate: the REQs decide everything that follows.

Good to know

Troubleshooting: see howto-mcp-project.md.