bmad-story-automator-go

v0.1.4

Published

4 months ago

Install the BMAD story-automator-go workflow bundle into a BMAD project.

0High
0Medium
0Low

bma-d

bmad claude codex workflow automation

Story Automator Go

Use this to wake up to this.

Portable bundle with source for BMAD story-automator-go. If you do not know what BMaD is, you're here to early. Go read their docs, use it for a project or two and come back when you want to try automating the story-loop.

This should be run after the planning phase has finished(After all planning phases, and after running /bmad-bmm-sprint-planning)

Quickstart

Install with npx:

cd /absolute/path/to/your-bmad-project
npx bmad-story-automator-go

Then run:

claude --dangerously-skip-permissions
# inside claude
/bmad-bmm-story-automator-go

Or run from anywhere and pass the target project explicitly:

npx bmad-story-automator-go /absolute/path/to/your-bmad-project

Recommendations / expectations / rants

This is not a genie, as always, the worse your planning artifacts are, the worse your results will be. I strongly recommend to NOT automate the first epic which is usually project bootstrapping. Start automating after project foundation is sound and you've verified that the agent hasn't sneaked in or ignored random requirements.
If you're low on usage, the automator runs quite consistently using sonnet, though recently Claude Code has increased usage so much I simply use Opus for the automator as well.
Do not expect this to create bug-free code. The project always has issues after running this, but it does make progress much more easier. After running a full session spanning multiple epics, simply try running the project yourself and do an interactive session addressing issues if they exist. Additionaly, create a file full of feedback, feed it to create-epics-and-stories and then run the automator again if you're not bothered to do the interactive mode either.
Recommend to skip tests for the first epic(IF you ignored my first point and decide to automate epic 1 as well).
You can be VERY specific during agent customisation and Claude will generate the agents file for you pretty much consistenly. If you want to change things mid-automation, update the agents orchestration file in _bmad-output/story-automator/agents/. This will work mid-automation so simply edit and save. The file should be intuitive enough, just don't break the agent structure and don't try to use anything other than claude / codex / false.
If you want to start a claude session in the same directory as one that has the story-automator running, run with export STORY_AUTOMATOR_CHILD=true to ignore the stop-hook.
Complexity estimates are shite. But there's no silver bullet for this imo since it's just a script reading through the ACs and looking for keywords. Open to suggestions on how to make it better.

What This Is

This repo packages the installable workflow payload plus the Go program source for story-automator-go so another BMAD project can install it cleanly and still inspect or rebuild the binary if needed.

This bundle supports:

Claude
Codex
current BMAD layout: _bmad/bmm/4-implementation/...
legacy BMAD layout: _bmad/bmm/workflows/4-implementation/...

This bundle does not support:

other agent CLIs

Important:

retrospective child runs are Claude-only even if the main orchestration uses Codex elsewhere

How It Works

1. Entry + mode routing

flowchart TD
    A["Install into BMAD project<br/>npx bmad-story-automator-go"] --> B["Run /bmad-bmm-story-automator-go in Claude"]
    B --> C["Load BMAD config<br/>project, output folder, language, state helper"]
    C --> D{"Mode"}
    D -->|Create| E["Create flow"]
    D -->|Resume| F["Resume existing orchestration"]
    D -->|Validate| G["Validate state integrity"]
    D -->|Edit| H["Edit orchestration config"]
    B -.-> Z["bin/story-automator backs parsing, state,<br/>tmux spawning, monitoring, retries, and helpers"]

2. Create flow

flowchart TD
    A["Step 1: Initialize<br/>verify stop-hook, load rules,<br/>check existing state, check sprint status"] --> B["Step 2: Pre-flight<br/>confirm epic, parse stories,<br/>compute complexity, gather custom instructions"]
    B --> C["Step 2a: Configure<br/>execution prefs, agent plan,<br/>autonomous start, state document"]
    C --> D["Step 2b: Finalize<br/>write complexity + agents files,<br/>create marker, begin execution"]
    D --> E["Step 3: Execute build cycle"]
    E --> F["Step 3c + Step 4: Complete + Wrap-up<br/>summary, learnings, recommendations,<br/>housekeeping, finalize state, remove marker"]

3. Story execution loop

sequenceDiagram
    autonumber
    participant O as Orchestrator
    participant S as State Document
    participant T as tmux Child Session
    participant P as Sprint Status
    participant R as Retrospective Session

    loop For each story
        O->>T: Spawn create-story session
        T-->>O: Monitor result
        O->>S: Mark create-story done

        O->>T: Spawn dev-story session
        T-->>O: Monitor result
        O->>S: Mark dev-story done

        opt Skip Automate = false
            O->>T: Spawn automate session
            T-->>O: Monitor result
            O->>S: Mark automate done or skipped
        end

        loop Code-review cycles until pass or escalation
            O->>T: Spawn code-review session
            T->>P: Verify sprint status update
            P-->>O: done or incomplete
            alt 0 CRITICAL issues remain
                O->>S: Mark code-review done
            else CRITICAL issues remain
                O->>S: Record retry or escalation state
            end
        end

        O->>T: Commit story changes
        O->>P: Verify story is done
        P-->>O: done
        O->>S: Mark story complete

        alt Epic fully complete
            O->>R: Spawn Claude-only retrospective in YOLO mode
            R-->>O: complete or skip safely
            O->>S: Record retrospective status
        end
    end

    O->>S: Finalize orchestration and remove marker

4. Resume, validate, edit

sequenceDiagram
    autonumber
    participant O as Orchestrator
    participant S as State Document
    participant P as Sprint Status
    participant T as tmux Sessions

    O->>S: Load existing orchestration state
    O->>P: Verify state against sprint status
    O->>T: Inspect active sessions
    O-->>S: Present status and resume options
    O->>S: Continue execution from last safe step

flowchart TD
    A["Validate mode"] --> B["Validation Step 1<br/>state integrity, helper contract,<br/>structure + session baseline"]
    B --> C["Validation Step 2<br/>story progress consistency,<br/>final validation report"]

flowchart TD
    A["Edit mode"] --> B["Load current state"]
    B --> C["Open edit menu"]
    C --> D["Apply and save changes"]
    D --> E["Post-edit options<br/>resume, edit again, or stop"]

The practical shape is:

one orchestrator session
one state document
many short-lived tmux child sessions for create-story, dev-story, automate, code-review, and retrospective
deterministic retry + escalation around failures
done gated by the bundled story-automator-review workflow

What Gets Installed

The installer detects the target BMAD layout and installs into the matching path:

current BMAD:
- _bmad/bmm/4-implementation/bmad-story-automator-go
- _bmad/bmm/4-implementation/bmad-story-automator-review
legacy BMAD:
- _bmad/bmm/workflows/4-implementation/story-automator-go
- _bmad/bmm/workflows/4-implementation/story-automator-review

It also:

installs the correct platform binary as bin/story-automator
installs the Claude command bmad-bmm-story-automator-go
creates missing Claude dependency commands for create-story, dev-story, story-automator-review, retrospective
creates bmad-tea-testarch-automate only if a compatible automate workflow already exists in the target project

Why Story Automator Review Is Bundled

story-automator-go now depends on a dedicated story-automator-review workflow state gate.

Critical rule:

a story should move to done only when zero CRITICAL issues remain after fixes

Because of that, this package installs the bundled story-automator-review workflow alongside story-automator-go. It does not overwrite the project's generic code-review workflow.

Requirements

Host requirements:

tmux
Claude Code
macOS or Linux
amd64 or arm64

If the automate workflow is missing, install still succeeds. In that case run story-automator-go with Skip Automate = true.

How To Use It

Claude

After install:

/bmad-bmm-story-automator-go

Codex

Do not run the orchestrator using Codex. I have never tried it because Codex does not support hooks which is vital for continuation.

How To Verify A Target Install

Manual checks inside a target project:

cd /path/to/project
story_dir=$(find _bmad/bmm -maxdepth 3 -type d \( -name 'bmad-story-automator-go' -o -name 'story-automator-go' \) | head -n 1)
review_dir=$(find _bmad/bmm -maxdepth 3 -type d \( -name 'bmad-story-automator-review' -o -name 'story-automator-review' \) | head -n 1)
"$story_dir/scripts/derive-project-slug.sh"
grep -n "0 CRITICAL issues remain after fixes" "$review_dir/instructions.xml"

Expected:

JSON containing "ok": true
a matching CRITICAL issues remain line in story-automator-review/instructions.xml

Package Layout

Payload copied into target projects:

payload/_bmad/bmm/workflows/4-implementation/story-automator-go/
payload/_bmad/bmm/workflows/4-implementation/story-automator-review/

Packaged binaries:

artifacts/story-automator/bin/darwin-arm64/story-automator
artifacts/story-automator/bin/darwin-amd64/story-automator
artifacts/story-automator/bin/linux-arm64/story-automator
artifacts/story-automator/bin/linux-amd64/story-automator

Package scripts:

install.sh
bin/bmad-story-automator-go
package.json

Bundled program source:

source/go.mod
source/cmd/story-automator/

Publish To npm

The repo is now wired for npm distribution.

Publish steps:

npm adduser
npm publish

After publish, install into any BMAD project with:

cd /absolute/path/to/your-bmad-project
npx bmad-story-automator-go