Autonomous Development Loops

To use BMad in an autonomous development loop, use the bmad-dev-auto skill. It is like Quick Dev, but designed to keep moving without human interaction. You can use it in an interactive session, but its main purpose is to be used by an orchestrator.

bmad-dev-auto performs one unattended development-loop iteration:

1. Clarify the incoming intent
2. Create (or find and resume) a spec file
3. Implement the change
4. Review the result
5. Finish by writing a terminal status to the spec file or fallback result artifact.

This skill relies on an ability to run subagents. If subagents are unavailable, the workflow halts blocked with no subagents. If you invoke the skill itself in a subagent session, e.g. “hey, Claude, implement stories 2-10, using a subagent running bmad-dev-auto skill for each story”, that session will need to spawn its own subagents.

Version control, while optional, is strongly recommended. If it’s present, there must be no uncommitted changes.

The main input is the invocation prompt. bmad-dev-auto treats that prompt as workflow input, not as a finished implementation plan.

Supported intent shapes include:

• A short free-form change request
• A ticket, issue, or story identifier
• A path to an intent file
• A path to an existing spec file generated by this workflow

If the invocation points to an existing spec file with one of the known status values in the frontmatter, the workflow resumes from that state:

Spec status	Entry point
draft	plan
ready-for-dev	implement
in-progress	implement
in-review	review
done	review again as a fresh follow-up pass
blocked	halt immediately

On activation, the workflow resolves:

• _bmad/bmm/config.yaml
• Any configured workflow customizations from customize.toml, team overrides, and user overrides
• Persistent facts listed in workflow config
• project-context.md files, if present

It may also look at:

• BMAD planning artifacts
• A cached or newly compiled epic context file for epic-based work
• The most recent completed prior-story spec from the same epic for continuity

The spec frontmatter status is the main machine-readable state for orchestration:

Spec Status	Meaning
draft	Spec exists but has not passed ready-for-dev validation
ready-for-dev	Spec is complete enough to implement
in-progress	Implementation is underway
in-review	Review/triage is underway
done	Workflow completed successfully
blocked	Workflow cannot safely continue unattended

On successful completion, the workflow writes or updates the spec with:

• Final status: done
• An Auto Run Result section containing:
  • Summary of implemented change
  • Files changed
  • Review findings breakdown
  • Verification performed
  • Residual risks
• followup_review_recommended flag. True if LLM decided another review pass seems worthwhile. It’s a suggestion, not a must. Simplest way to give it a second review pass is to re-run the skill pointing it at the spec file.
• baseline_revision and final_revision — HEAD before implementation and after the final commit. Together they bracket the run’s commits: git log baseline_revision..final_revision lists exactly what it produced, and equal values mean no commits were made. Both are NO_VCS when version control is unavailable.

If version control is available, the workflow commits the change. It does not push.

On blocked completion, the workflow writes:

• Final status: blocked when a spec exists
• A blocking condition
• Supporting detail in the spec or fallback result artifact

Typical blocking conditions include:

• unclear intent
• intent gaps
• no subagents
• missing spec_file before implementation
• implementation verification failed
• intent gap in intent contract
• review repair loop exceeded 5 iterations (non-convergence)

The workflow always tries to leave behind a durable artifact describing what happened.

For new work, the workflow creates:

{implementation_artifacts}/spec-<slug>.md

That spec is the contract between planning, implementation, and review. It contains:

• Frontmatter status
• The immutable <intent-contract> block
• Code map
• Tasks and acceptance criteria
• Spec change log
• Review triage log
• Verification notes

If the workflow halts before it has a valid spec_file, it writes:

{implementation_artifacts}/bmad-dev-auto-result-<slug-or-timestamp>.md

This records the terminal status and blocking condition.

Depending on the route, the workflow may also write:

• {implementation_artifacts}/epic-<N>-context.md
• {implementation_artifacts}/deferred-work.md

An orchestrator integrating bmad-dev-auto should:

• Pass one coherent intent at a time
• Prefer passing a spec path when resuming prior work
• Monitor the produced spec file or fallback result file for terminal state
• Read status, blocking condition, and followup_review_recommended rather than inferring success from chat output alone
• Use baseline_revision..final_revision to identify the commits the run produced, rather than inferring them from git state
• Expect autonomous file changes and possibly a local commit
• Handle blocked as a routing signal, not just a failure signal

In practice, blocked usually means the workflow ran into a situation where unattended execution would be unsafe. That is often the point where a higher-level orchestrator, another workflow, or a human should take over.

After resolving a blocked run, the orchestrator should usually start a fresh bmad-dev-auto run. If it reuses prior work, it should pass an explicit known-good spec path rather than relying on implicit discovery.