Menu
THE dev loop — handles both greenfield (analyst → discovery → build) and brownfield (deep project immersion → lean spec → build). Replaces work-loop as the single entry point for all Hermes dev work.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Progress-aware error resolution with web research escalation and solution learning. Fixes lint/TS/build errors without arbitrary iteration limits. Called by work-loop and vibe-loop.
Accumulated debugging patterns learned from real failures. Consulted by health-fix before attempting fixes.
Auto-detect project software stack and write a machine-readable stack context block into AGENTS.md. Runs during work-loop health check so Pi always knows the correct test runner, build tool, and conventions.
| name | vibe-loop |
| description | THE dev loop — handles both greenfield (analyst → discovery → build) and brownfield (deep project immersion → lean spec → build). Replaces work-loop as the single entry point for all Hermes dev work. |
| version | 2.0.0 |
| metadata | {"hermes":{"tags":["autonomous","vibe-coding","idea-to-code","pipeline","brownfield","greenfield"],"related_skills":["dev-team/work-loop","dev-team/escalation-handler"]}} |
Autonomous pipeline for both greenfield and brownfield development. Single entry point for all Hermes dev work.
The key difference: brownfield mode becomes intimate with the project before writing a single line. It reads project context, understands working patterns, and only creates new code when no existing pattern can be reused.
hermes chat -s dev-team/vibe-loop --yolo -q "Build a meal prep timer with React and Express"hermes chat -s dev-team/vibe-loop --yolo -q "Add social sharing to Crispi"hermes chat -s dev-team/vibe-loop then describe the idea or task/vibe Build a ... or /vibe Add feature X to ProjectY| Variable | Default | Description |
|---|---|---|
VIBE_SKIP_ANALYST | false | Force-skip market research even for greenfield (brownfield auto-skips regardless) |
VIBE_AUTO_SCAFFOLD | true | Auto-create project structure for greenfield |
HERMES_MAX_PARALLEL | 1 | Max concurrent Pi subagent sessions in Phase 10 |
These rules apply to ALL phases, especially during implementation (Phase 10). No exceptions.
NEVER default to greenfield approaches when working in an existing project.
Before writing ANY new code, Pi and all subagents must:
_output/pattern-scan.md (generated in Phase 2 for brownfield) for existing patternsgrep, glob for related services/components)When reusing patterns: adapt, don't copy-paste. Follow the existing code's style exactly — same naming, same error handling, same response format.
NEVER refactor, rename, reorganize, or "improve" existing code without explicit user permission.
If existing code needs refactoring to support the new feature, file a separate Beads issue describing the refactor and why it's needed. Let the user decide.
New features should be additive — extend the existing system, don't reshape it:
Pi subagents (tdd-coder, quinn-validator) do NOT read this SKILL.md, project-context.md, or pattern-scan.md. Project knowledge reaches Pi through TWO channels:
Channel 1 — AGENTS.md (always read by Pi):
<!-- BEGIN PROJECT RULES --> block into AGENTS.mdChannel 2 — Story file Dev Notes (read per-story):
## Coding Rules section into every brownfield story's Dev NotesBoth channels are required. AGENTS.md provides project-wide rules; story Dev Notes provide task-specific guidance with concrete file paths.
Every phase has both a number (for backward compat) and a BMAD agent name (for human readability). Both work in prompts — "start at dev" and "start at phase 10" mean the same thing.
| Number | BMAD Name | Agent Role | Greenfield | Brownfield |
|---|---|---|---|---|
| Phase 0 | analyst | Mary — market research & validation | runs | auto-skipped |
| Phase 1 | brief-capture | PM — captures idea/task statement | runs | runs |
| Phase 2 | immersion | Architect — deep project immersion + pattern scan | scaffold | brownfield deep dive |
| Phase 3 | product-brief | PM — writes brief | product-brief | feature-brief (lean) |
| Phase 4 | prd | PM — writes spec | full PRD | feature spec (lean) |
| Phase 5 | architecture | Architect — designs solution | full architecture | integration architecture |
| Phase 6 | epics | SM — breaks into epics & stories | runs | runs |
| Phase 7a | story-specs | SM — writes story specs with AC, tasks, dev notes | runs | runs + Coding Rules injection |
| Phase 7b | tdd | QA — writes failing TDD test files from specs | runs | runs |
| Phase 8 | beads-filing | SM — files beads issues with deps | runs | runs |
| Phase 9 | checkpoint | SM — checkpoint & handoff to dev | runs | runs |
| Phase 10 | dev | Pi — codes to make tests pass (work-loop) | runs | runs |
| Phase 10b | pattern-capture | Brownfield-enforcer — updates project-context.md | skipped | runs |
| Phase 10c | quinn-review | QA — adversarial review (MANDATORY HARD GATE) | runs | runs |
| Phase 11 | e2e-validation | QA — end-to-end validation | runs | runs + integration check |
| Phase 12 | deploy | DevOps — deploy to Railway | runs | preview deploy |
| Phase 13 | report | Tech-writer — completion report | runs | runs |
Prompt examples using BMAD names:
hermes chat -s dev-team/vibe-loop --yolo -q "Add X to Crispi. Start at dev."hermes chat -s dev-team/vibe-loop --yolo -q "Build X. Start at tdd."hermes chat -s dev-team/vibe-loop --yolo -q "Build X. Start at architecture."hermes chat -s dev-team/vibe-loop --yolo -q "Run quinn-review on current branch."You are NOT done until Phase 10c / quinn-review has run. This is a hard gate, not a suggestion. Implementation alone (Phase 10) is NOT completion. The pipeline minimum is:
dev (Phase 10) → pattern-capture (Phase 10b) → quinn-review (Phase 10c)
If you are about to output a final summary or declare the task complete, STOP and check:
git diff main...HEAD and invoke the three Quinn review layers?If the answer to ANY of these is NO, you are not done. Continue to quinn-review (Phase 10c) before responding.
This gate applies in ALL modes: interactive, -q single-query, --yolo, and Telegram. No exceptions.
⚠ CRITICAL RULE — READ THIS BEFORE EVERY PHASE TRANSITION:
When invoked with --yolo, the entire pipeline runs end-to-end with ZERO human gates. Do NOT pause between phases to ask "want to continue?" or "ready to proceed?" or present a summary and wait. Do NOT end your turn with a question. Do NOT output a summary and stop. After completing any phase, IMMEDIATELY call your next tool to begin the next phase. The only acceptable halts in yolo mode are:
VIOLATION EXAMPLES (never do these in --yolo):
Everything else flows continuously: discovery → implementation → validation → deploy. If you are about to output text without a tool call after it, and you are NOT at an acceptable halt condition above, you are violating this rule.
Before starting any phase (except Phase 0/1), validate the previous phase's output:
_output/pipeline.log: [timestamp] Phase N → Phase N+1 | artifacts: {list}This prevents cascading failures from partial writes or crashes mid-phase.
At every phase transition:
_output/pipeline.log:
[{ISO timestamp}] Phase {N} complete → Phase {N+1} | artifacts: {comma-separated file list}
Vibe Loop [{project}] — Phase {N} complete: {phase title}
Next: Phase {N+1} — {next phase title}
Elapsed: {time since start}
--yolo passthrough: When vibe-loop is invoked with --yolo, Phase 10 inherits this flag — work-loop runs fully autonomously (no approval prompts for commits/pushes).
Before each phase, check if its output artifacts already exist from a previous run or manual creation. If they do:
| Situation | Action |
|---|---|
_output/hunt-results.md exists when analyst (Phase 0) hunt starts | Ask: "Hunt results already exist ({N} candidates). Pick from existing / Re-run hunt?" In --yolo mode: present existing results for selection (still halts for pick). |
_output/analyst-report.md exists when analyst (Phase 0) starts | Ask: "Analyst report already exists. Use existing / Re-run research / Skip to brief-capture?" |
_output/idea-statement.md exists when brief-capture (Phase 1) starts | Ask: "Idea statement already exists. Use existing / Revise?" |
package.json + AGENTS.md + .beads/ exist when immersion (Phase 2) starts | Auto-detect brownfield — skip scaffold |
_output/product-brief.md or _output/feature-brief.md exists when product-brief (Phase 3) starts | Ask: "Brief already exists. Use existing / Regenerate?" |
_output/prd.md or _output/feature-spec.md exists when prd (Phase 4) starts | Ask: "Spec already exists. Use existing / Regenerate?" |
_output/architecture.md exists when architecture (Phase 5) starts | Ask: "Architecture doc already exists. Use existing / Regenerate?" |
_output/epics.md exists when epics (Phase 6) starts | Ask: "Epics already exist. Use existing / Regenerate?" |
| Story spec files exist when story-specs (Phase 7a) starts | Ask: "Story specs already exist ({N} stories). Use existing / Regenerate all / Generate missing only?" |
| Test files exist when tdd (Phase 7b) starts | Ask: "TDD test files already exist ({M} tests). Use existing / Regenerate all / Generate missing only?" |
| Beads issues with matching labels exist when beads-filing (Phase 8) starts | Ask: "Found {N} existing Beads issues with label '{prefix}'. Use existing / Wipe and reimport?" |
| Discovery commit exists in git log when checkpoint (Phase 9) starts | Auto-skip commit (already pushed). Proceed to dev (Phase 10). |
bd ready returns issues when dev (Phase 10) starts | Auto-resume work-loop from where it left off. No prompt needed. |
In --yolo mode: Auto-select "Use existing" for all redundancy prompts — never regenerate unless the artifact is missing or corrupted. This keeps autonomous runs fast when resuming.
Relevance check: When reusing an existing artifact, read its first 200 characters and compare against the current idea statement. If the content appears to be about a completely different product (different name, different domain), warn: "Existing {artifact} appears to be for a different project. Use anyway / Regenerate?" In --yolo mode, regenerate if relevance check fails.
Key principle: Never redo work that's already done. If the user already wrote a PRD by hand or with a BMAD agent, the vibe loop should pick it up and keep going.
Act as Mary (strategic business analyst). This phase has two modes depending on what the user provides.
Skip conditions (checked in order):
"Brownfield detected — skipping analyst, entering deep project immersion (Phase 2)." Jump to Phase 1.VIBE_SKIP_ANALYST is true → skip directly to Phase 1 (manual override for greenfield).Brownfield projects do not need market research or idea validation — the project already exists. The analyst front-end is exclusively for greenfield where you're deciding WHAT to build.
Mode detection:
Go foraging for product ideas using web search. The goal is to find real pain points that people are expressing right now.
Step 0-hunt-a: Source Scanning
Search these sources (or user-specified sources) for unmet needs and pain points:
Source and domain filtering:
Step 0-hunt-b: Idea Extraction
From the scan, extract 5-7 candidate ideas. For each:
Step 0-hunt-c: Scoring & Ranking
Score each candidate on 3 dimensions (1-5 each):
Rank by total score. Present the top 3 to the user:
Vibe Loop — Idea Hunting Results
1. [Score: 13/15] {Idea Name}
Pain: {1-sentence pain point with source}
Concept: {1-sentence product idea}
Why it wins: {differentiation angle}
2. [Score: 11/15] {Idea Name}
...
3. [Score: 10/15] {Idea Name}
...
Which idea should we build? (1/2/3/none/refine/more)
Write the full candidate list and scores to _output/hunt-results.md before presenting to the user. This enables resumption if the pipeline crashes after hunting but before selection.
HALT and wait for user selection. If running via Telegram and no response after 24 hours, send a reminder: "Still waiting for your idea pick. Reply 1/2/3 to continue."
After selection, flow continues into validation (Step 0a) with the chosen idea, then into Phase 1.
Step 0a: Market Landscape Scan (Validation Mode — runs when an idea is provided or selected from hunting)
Using web search, research:
Produce a competitive snapshot: for each competitor, note name, pricing model, key strength, key weakness.
Step 0b: Idea Validation
Score the idea across 3 dimensions (1-5 each):
Validation gate:
Do NOT halt on a low score — build it anyway, but carry the risks forward so the PRD can scope defensively.
Step 0c: Brainstorm Expansion
Before locking the idea, push past the obvious:
Step 0d: Analyst Report
Compile everything into _output/analyst-report.md:
# Analyst Report: {Idea Name}
## Market Landscape
{Competitive snapshot — 3-5 competitors with strengths/weaknesses}
## Validation Score: {N}/15
- Problem severity: {score}/5 — {rationale}
- Solution differentiation: {score}/5 — {rationale}
- Feasibility: {score}/5 — {rationale}
## Key Risks
{Bullet list of concerns from validation}
## Brainstorm Highlights
### Consider for MVP
{3-5 strongest feature ideas from brainstorm}
### Defer to V2
{Remaining interesting ideas}
## Recommendation
{1-2 sentence go/caution/pivot recommendation with reasoning}
Output: _output/analyst-report.md
Parse the user's input query combined with the analyst report (if Phase 0 ran) as the product idea.
If Phase 0 ran: Incorporate the validation score, key risks, and MVP-candidate features from the analyst report into the idea statement. The analyst report becomes input context for all downstream phases.
If the idea is clear (names a product, describes core functionality, implies a tech stack):
If the idea is too vague (e.g., "build something cool"):
Output: _output/idea-statement.md — 1 paragraph + tech stack note + analyst context (if available).
Detect whether this is greenfield (new project) or brownfield (existing project).
Pre-flight: Verify required tools are installed before proceeding:
command -v bd >/dev/null 2>&1 || { echo "ERROR: bd (beads) CLI not found. Install it first."; exit 1; }
command -v git >/dev/null 2>&1 || { echo "ERROR: git not found."; exit 1; }
command -v npm >/dev/null 2>&1 || { echo "ERROR: npm not found."; exit 1; }
If any tool is missing, Telegram alert and halt.
Brownfield detection: Check if current working directory has:
package.json or equivalent project manifestAGENTS.md file.beads/ directorypackage.json name field or git remote URL if availableIf brownfield (existing project) — Deep Project Immersion:
The goal is to know this project as well as a senior dev who's been on it for months BEFORE writing any new code. This phase is the foundation everything else builds on.
Step 2a. Create a feature branch: Derive slug from idea: lowercase, replace spaces/symbols with hyphens, strip non-alphanumeric, max 50 chars.
git checkout -b vibe/{idea-slug}
# e.g., "Add Social Sharing!" → vibe/add-social-sharing
All commits go on this branch. User merges to main when satisfied.
Step 2b. Load project context:
Read ALL project context docs (in this order — each builds on the previous):
AGENTS.md — stack, conventions, Pi instructions, stack-detect blockCLAUDE.md — project rules, beads workflow, landing protocol_bmad-output/project-context.md — implementation rules, gotchas, anti-patterns:
date: in frontmatter) → regenerate via bmad-generate-project-contextbmad-generate-project-contextpackage.json — deps, scripts, versions_bmad-output/ (prior PRDs, architecture docs, pattern scans)docs/ directory — any architecture docs, story templates, QA docsExtract and carry forward into all subsequent phases:
<!-- BEGIN STACK DETECT --> block)Step 2c. Deep pattern scan — understand HOW this project works:
This is NOT a surface grep. Read actual source files to understand the project's working patterns:
Services — Read 2-3 representative service files end-to-end (e.g., the most recently modified ones in src/server/services/). Extract:
Routes — Read 2-3 representative route files in src/server/routes/. Extract:
Tests — Read 2-3 representative test files in src/server/__tests__/. Extract:
Middleware — Understand the middleware stack order and what each piece does (read src/server/index.ts route registration)
Database — Read 1-2 migration files and the DB config. Understand:
Task-specific scan — Search for existing code that touches the same domain as the current task:
grep and glob for related service names, route paths, config patternsStep 2d. Produce the Pattern Playbook (_output/pattern-scan.md):
This is a reuse-first playbook — structured so downstream phases know exactly what to reuse and how:
# Pattern Playbook — {Project Name}
## How This Project Works
{3-5 sentences capturing the essence: stack, architecture, patterns, key gotchas}
## Reusable Patterns (MUST use these — do not reinvent)
| Pattern | Example File | Structure | How to Reuse |
|---------|-------------|-----------|--------------|
| Service class | {actual path} | {class Name, singleton export, constructor pattern} | Copy structure, adapt methods |
| Route handler | {actual path} | {router, middleware chain, response format} | Copy chain, add new routes |
| Jest test | {actual path} | {mock setup, describe/it structure} | Copy mock boilerplate, adapt assertions |
| DB migration | {actual path} | {up/down, column naming} | Copy structure, new table/columns |
| Middleware | {actual path} | {pattern description} | Import and chain, don't recreate |
## Existing Code Relevant to This Task
- {file path} — {what it does, how the new work should interact with or extend it}
- {file path} — {reusable utility/helper that applies}
## Critical Rules (verbatim from project-context.md)
{Paste the "Critical Don't-Miss Rules" section — route registration order, security requirements, DB gotchas, build/deploy rules}
## Anti-Patterns (NEVER do these)
{Paste the "Anti-Patterns to Avoid" section verbatim}
## Task-Specific Findings
{What the domain-specific search found — existing implementations, related services, files to modify}
If the scan finds no reusable patterns (bare project with minimal code):
# Pattern Playbook — {Project Name}
No existing patterns found. This is effectively a greenfield codebase within a brownfield project structure.
New code should establish conventions that future features will follow.
Step 2e. Inject project rules into AGENTS.md:
Add a <!-- BEGIN PROJECT RULES --> block to AGENTS.md (same injection pattern as stack-detect). This ensures Pi reads the rules automatically since Pi always reads AGENTS.md:
<!-- BEGIN PROJECT RULES -->
## Critical Project Rules (auto-injected from project-context.md)
> Auto-generated by vibe-loop Phase 2. Do not edit manually.
> Source: _bmad-output/project-context.md
> Last updated: {date}
### Route Registration Order
{from project-context.md}
### Security — Non-Negotiable
{from project-context.md}
### Database Gotchas
{from project-context.md}
### Anti-Patterns
{from project-context.md}
### Build & Deploy Rules
{from project-context.md}
<!-- END PROJECT RULES -->
If a <!-- BEGIN PROJECT RULES --> block already exists, replace it. Never duplicate.
Step 2f. Skip scaffold creation. Proceed to Phase 3.
If greenfield (new project) and VIBE_AUTO_SCAFFOLD is true:
mkdir -p {project-name} && cd {project-name}git initnpm init -y, install deps (Express, React, etc.), tsconfig.json with strict modepython -m venv venv, pip install framework (Flask, FastAPI, Django), create requirements.txtgo mod init {module}, create main.go skeletonnpm install --save-dev jest @types/jest ts-jestpip install pytesttesting package (no install needed)bd init --prefix {ProjectName}AGENTS.md with:
# {ProjectName} — Agent Context
## What This Project Is
{idea statement}
## Architecture
- **Backend:** {from idea}
- **Frontend:** {from idea}
- **Database:** {from idea or TBD}
- **Testing:** Jest (unit/integration)
- **Task tracking:** Beads (bd CLI, prefix: {ProjectName})
## Conventions
- Services: singleton pattern, `class FooService { } export const fooService = new FooService()`
- Tests: Jest, `__tests__/` dirs colocated with source
- Routes: `const router = express.Router()` → `export default router`
- Response format: `{ success: boolean, data?: T, error?: string }`
## Current Work
- Stories: `docs/stories/*.md`
- Tests: `src/**/__tests__/*.test.ts`
npm run build or npx tsc --noEmit (should exit 0)python -c "import {main_module}" or pytest --collect-onlygo build ./...git add -A && git commit -m "feat: project scaffold"Output: Working, verified project directory with git, package.json, AGENTS.md, Beads initialized.
Greenfield → Product Brief. Act as a product manager. Full product brief. Brownfield → Feature Brief. Lean scope focused on what's being added/changed.
_output/analyst-report.md exists, read it — incorporate competitive landscape, validation risks, and brainstormed features_output/product-brief.md containing:
_output/product-brief-distillate.md — dense, token-efficient version for downstream phases_output/pattern-scan.md (produced in Phase 2) — understand what already exists_output/feature-brief.md — a lean feature brief focused on the CHANGE:
_output/feature-brief-distillate.md — dense version for downstream phases:
Output: _output/product-brief.md (greenfield) or _output/feature-brief.md (brownfield) + corresponding distillate
Greenfield → Full PRD. Complete product requirements document. Brownfield → Feature Spec. Focused on the change, integration points, and what to reuse.
_output/analyst-report.md exists, read it for competitive context and risks_output/prd.md with these sections:
stepsCompleted: [...]_output/pattern-scan.md — carry forward reuse requirements_output/feature-spec.md — lean and focused:
| Existing File | Change Type | What Changes |
|---|---|---|
| {path} | Modify | {description} |
| {path} | Extend | {description} |
| {new path} | Create | {description} |
| What | File | Why Reuse |
|---|---|---|
| {service/pattern} | {path} | {it already does X} |
Quality gate: Every functional requirement must be testable. Every modified file must be justified (why touch it?).
Output: _output/prd.md (greenfield) or _output/feature-spec.md (brownfield)
Greenfield → Full architecture. Design the system from scratch. Brownfield → Integration architecture. "How does this fit?" — only document what's NEW.
_output/architecture.md with:
The existing architecture is already defined in project-context.md and AGENTS.md. This phase only documents NEW decisions required by the feature/migration.
_output/feature-spec.md)_output/pattern-scan.md) — this is the existing architectureConstraint: The existing stack is NOT up for debate. Do not propose new frameworks, ORMs, state management libraries, or testing tools. Work within what exists. If something truly cannot be done with the existing stack, document it as a risk and propose the minimal addition.
_output/architecture.md with ONLY:
| Pattern | Source File | How It's Used in This Work |
|---|---|---|
| {pattern} | {path} | {how this work reuses it} |
Output: _output/architecture.md
Consume PRD + architecture. Break into implementable work.
Process:
_output/epics.md with:
Quality gate:
Output: _output/epics.md
Agent: SM (Scrum Master / Story Writer)
For each story in epics.md, the SM writes a story spec file. No test files yet — those come in Phase 7b.
Story spec format (in docs/stories/{slug}.md):
# Story {X.Y}: {Title}
**Epic:** {N} - {Epic Name}
**Story:** {X.Y}
**Status:** Ready for Development
**Created:** {today's date}
**Priority:** {P0|P1|P2}
---
## Story
**As a** {persona}, **I want** {action}, **So that** {value}.
## Prerequisites
{What must exist first — reference other stories}
## Acceptance Criteria
{Checkbox list with Given/When/Then from epics.md}
## Tasks
{Implementation tasks with hour estimates}
## Dev Notes
- **Test file:** {path to test file}
- **Key files to modify:** {list}
- **Patterns to follow:** {reference architecture.md patterns}
Brownfield MANDATORY addition — Coding Rules in Dev Notes:
Pi does NOT read project-context.md or pattern-scan.md. The ONLY way project knowledge reaches Pi is through the story file (which Pi reads via AGENTS.md context + story content). Therefore, for brownfield projects, EVERY story's Dev Notes section MUST include a ## Coding Rules block with concrete, actionable rules specific to that story:
## Coding Rules (auto-injected from project context)
### Patterns to Follow
- Service pattern: copy structure from {actual file path from pattern-scan.md}
- Route pattern: copy middleware chain from {actual file path}
- Test pattern: copy mock setup from {actual file path}
### Reuse These (do NOT recreate)
- {service/utility name} at {file path} — {what it does, why to reuse it}
- {helper/config} at {file path} — {what it does}
### Do NOT
- {relevant anti-patterns from project-context.md for this story's domain}
- {e.g., "Do NOT use raw SQL — use Knex query builder (db('table').where(...))"}
- {e.g., "Do NOT create a new ORM — use existing Knex at src/server/config/database.ts"}
### Route Registration (if adding routes)
- {middleware stack order from project-context.md}
- {specific registration rules, e.g., "Mount BEFORE recipeRoutes"}
### Security (if adding endpoints)
- {auth requirements — authenticateToken middleware}
- {CSRF rules}
- {validation requirements — express-validator or Joi}
### Database (if touching DB)
- {Knex patterns — db('table').where(...)}
- {Column naming — snake_case}
- {Migration naming convention}
### Testing
- {Mock setup — what's globally mocked (DB, Redis) via setup.ts}
- {Test file location convention}
- {Naming convention}
Only include sections relevant to the story. A story that doesn't touch routes doesn't need the Route Registration section. A story that doesn't touch the DB doesn't need the Database section. But the Patterns/Reuse/Do-NOT sections are ALWAYS required for brownfield.
This is how project intimacy flows to Pi — through the story file, with concrete file paths, not vague references.
Post-write validation (7a): After generating all story files, verify each story has a corresponding story file. Log missing specs to _output/phase7a-validation.log. Proceed to Phase 7b.
Output (7a): N story files in docs/stories/
Agent: QA (Quinn / Test Writer)
QA reads each story spec from Phase 7a and writes failing TDD test files that define the contract. Code does not exist yet — tests will fail until dev (Phase 10) implements it. This is the correct starting state.
TDD test format — use the test framework and language chosen in Phase 5 / architecture. Example for TypeScript/Jest:
/**
* Epic {N}: {Epic Name}
* Story {X.Y}: {Title}
* TDD Tests — these define the contract. Code does not exist yet.
*/
// Imports will fail until Pi implements the code
import { ServiceName } from '../../path/to/service';
describe('ServiceName', () => {
// Tests derived from acceptance criteria
// Import things that DON'T EXIST YET — correct for TDD
});
For Python/pytest:
# Epic {N}: {Epic Name} — Story {X.Y}: {Title}
# TDD Tests — code does not exist yet.
from app.services.service_name import ServiceName # Will fail until implemented
def test_service_does_thing():
...
Adapt the format to match whatever stack Phase 5 selected.
Rules:
Post-write validation (7b): After generating all test files, verify each story spec has a corresponding test file (except doc-only stories like architecture spikes). If any test file is missing, regenerate it before proceeding. Log mismatches to _output/phase7b-validation.log.
Output (7b): N test files in src/**/__tests__/
Convert stories into Beads issues with full dependency tracking.
Process:
docs/stories/beads-import.md in Beads batch import format:
# Epic 1: {Name}
## Story-1.1: {Title}
- type: feature
- priority: P0
- labels: epic-1, lane-a, {project-prefix}
- notes: story_file=docs/stories/{slug}.md | test_file=src/server/__tests__/{dir}/{name}.test.ts
{Description}
bd create --file docs/stories/beads-import.mdbd update {id} --priority {N} --type feature --set-labels {labels}bd dep add {blocked} {blocker} for:
bd ready — only the first story in the dependency chain should be readyOutput: Beads issues with priorities, labels, and dependency chain.
Discovery is complete. Prepare for implementation.
Process:
git add _output/ docs/stories/
# Add test files for any language (handles spaces in paths)
find src -name "*.test.*" -o -name "*_test.*" -o -name "test_*" | xargs -d '\n' git add 2>/dev/null
git commit -m "feat: discovery complete — {N} stories, {M} test files"
bd sync
git push || { git pull --rebase && git push; }
Vibe Loop — Discovery Complete
Project: {name}
Epics: {count}
Stories: {count}
Test files: {count}
Beads issues: {count}
Starting implementation...
--yolo mode the pipeline is continuous — discovery flows directly into implementation with zero human gates. Even in interactive mode, proceed unless the user explicitly said to stop after discovery. ⚠ RE-READ "Yolo Mode — No Human Gates" section NOW before outputting anything. If your next action is text without a tool call, you are about to violate the yolo rule.Pre-check: Before starting, verify the work-loop skill exists:
ls ~/.hermes/skills/dev-team/work-loop/SKILL.md
If missing: Telegram alert "Vibe loop dev (Phase 10) halted — dev-team/work-loop skill not found. Install it and re-run." Then halt. Do NOT attempt to implement stories without the work-loop orchestration.
Hands-off rule: During Phase 10, Hermes orchestrates but NEVER edits source or test files directly. All code changes flow through Pi subagents. If tests fail due to environment issues, classify as INFRA and escalate — do not edit tests to work around the problem.
Execute the standard dev-team work-loop. This phase follows the EXACT same steps as the dev-team/work-loop skill:
bd ready --json — pick up to HERMES_MAX_PARALLEL issuesbd update {id} --claimWhen all stories are closed (or only escalated stories remain), proceed to Phase 10b.
If stories are blocked on escalations, proceed to Phase 10b anyway with what's complete — partial apps can still be validated and deployed.
⚠ COMPLETION GATE: Do NOT declare the task done, output a final summary, or exit after dev (Phase 10). You MUST continue through pattern-capture (10b) → quinn-review (10c) → e2e-validation (11). quinn-review is mandatory — skipping it is a bug in your execution, not a valid shortcut. This applies even in -q mode.
Skip if greenfield. Greenfield projects establish patterns — brownfield projects need to record new patterns so the NEXT session inherits them.
After work-loop execution completes, scan what was created during this session:
Identify new files created:
git diff --name-only --diff-filter=A HEAD~{N}..HEAD
(where N = number of commits from this session)
Classify new patterns:
Update project-context.md if new patterns were established:
/health must return 200 with { status: 'ok' }")date: field in frontmatterUpdate pattern-scan.md with new reusable patterns:
If NO new patterns were established (only extended existing ones):
date: field only (so staleness check stays current)Commit the updated docs:
git add _bmad-output/project-context.md _output/pattern-scan.md
git commit -m "chore: update project context after vibe-loop session"
This is NOT optional. This is a HARD GATE — the pipeline cannot complete without it. If you are in -q mode and about to return your response: you are not done until this phase runs. Pi's code passes tests, but tests only validate what was anticipated. Quinn catches what wasn't — omissions, dead code, composition errors, security issues, spec deviations. Tests and adversarial review are complementary; neither replaces the other.
Trigger: All stories in Phase 10 are closed (or only escalated stories remain). Runs ONCE after the full implementation, not per-story.
Why mandatory: Pi writes both tests and code. When the same agent writes both, they share the same blind spots. The test suite validates "does what's here work?" — Quinn asks "what's missing? what breaks at scale? what doesn't match the spec?" These are fundamentally different questions.
Process:
Step 1 — Collect the diff:
git diff main...HEAD --stat
git diff main...HEAD
This captures everything the vibe-loop session produced.
Step 2 — Collect spec context:
Gather all story files from docs/stories/ that were part of this session (match by beads labels or epic tag). These provide the acceptance criteria Quinn reviews against.
Step 3 — Invoke bmad-code-review skill with three parallel review layers:
Hermes invokes the code review skill (or runs the review layers directly if the skill is unavailable):
bmad-review-adversarial-general.bmad-review-edge-case-hunter.Step 4 — Triage findings:
Classify each finding:
quinn-reviewquinn-reviewquinn-reviewStep 5 — Fix loop:
If P0 or P1 findings were filed:
bd ready --json — Quinn review issues are now in the queuequinn-review issue:
quinn-review P0/P1 issues are closedP2 findings remain open for future sessions — they're real but not blocking.
Step 6 — Report:
Quinn Adversarial Review — Complete
Findings: {total} ({critical} critical, {high} high, {medium} medium, {low} low)
Fixed this session: {fixed_count}
Deferred (P2): {deferred_count}
Dismissed: {dismissed_count}
Why not per-story: Running three adversarial reviewers per story is expensive and catches less — many composition errors only appear when multiple stories interact. Running once after the full implementation sees the complete picture, like we just demonstrated with the Railway migration review.
All stories are implemented and adversarially reviewed. Now verify the whole app works as a system, not just individual stories.
Process:
Full test suite + build check:
{test_cmd} 2>&1 # Use test_cmd from stack-detect (e.g., CI=true npx jest). NEVER bare npm test.
npm run build 2>&1
If failures, invoke the dev-team/health-fix skill with:
error_source: "test-suite+build"error_list: the failure outputscope: "all"Health-fix handles progress-based fixing, research, and learning.
PASS → all clear, proceedPARTIAL → classify remaining: critical (auth, data integrity, payment) → halt. Non-critical → proceed to deployment.Build verification:
npm run build # or equivalent for the stack
The app must compile/build without errors. Build warnings are acceptable.
Smoke test (if server app):
docker-compose up -d first. If external deps are unavailable and required, skip smoke test with log: "Smoke test skipped — external services unavailable."Integration check (brownfield only):
Report:
Vibe Loop — E2E Validation
Test suite: {passed}/{total} ({failures} failures)
Build: {pass/fail}
Smoke test: {pass/skip/fail}
Integration: {pass/skip/fail}
Ready for deployment: {yes/no}
Output: _output/e2e-validation.md with full results.
Deploy the completed app. This phase adapts based on greenfield vs brownfield.
Skip condition: If the project has no Railway configuration (railway.toml, Dockerfile.railway, or Railway CLI not installed), skip deployment and report: "No Railway config found. Manual deployment needed."
Greenfield deployment:
Verify Railway CLI is available:
command -v railway >/dev/null 2>&1
If missing, skip with Telegram: "Railway CLI not installed. Run npm i -g @railway/cli && railway login then re-run deploy (Phase 12)."
Check for existing Railway project:
railway status 2>/dev/null
If a project already exists, use it (don't create a duplicate). If not, run railway init.
Provision database FIRST (if needed):
railway add --plugin postgresqlConfigure environment variables:
src/server/config/env.ts or equivalent.env.example defaults--yolo mode.railway variables set KEY=VALUE to configureDeploy:
railway up
Post-deploy verification:
Brownfield deployment:
railway statusrailway up
Deployment report:
Vibe Loop — Deployed
URL: {railway deployment URL}
Health: {pass/fail}
Database: {provisioned/existing/none}
Branch: {branch name}
Status: {live/preview}
Output: _output/deployment.md with URL, status, and any manual steps remaining.
Final report:
Vibe Loop — Complete
Project: {name}
Stories completed: {N}/{total}
Stories escalated: {M}
Quinn review: {findings_total} findings ({fixed} fixed, {deferred} deferred)
E2E validation: {pass/partial/fail}
Deployment: {deployed to {URL} / skipped / failed}
Stories per epic: {epic breakdown}
Duration: {time}
Branch: {branch name} (merge to main when ready)
If stories remain open (escalated or blocked), log remaining work:
bd list --status=open -l {project-prefix} --json
And report via Telegram what's left.
| Error | Action |
|---|---|
| Web search tool not configured | Skip analyst, proceed to brief-capture (Phase 1) with warning in idea statement |
| Web search rate-limited or network error | Retry with 30s backoff, up to 3 attempts. If still failing, skip analyst with warning |
| Market research returns no results | Proceed with empty competitive snapshot, note "no data found" in analyst report |
| Idea hunt finds zero candidates | Telegram: "Hunt found no viable ideas for '{domain}'. Try a different domain." HALT for user redirect |
| All hunt candidates score below 6 | Present them anyway with warning: "All candidates scored low. Pick one to explore or refine the search." |
| Validation score < 6 | Proceed anyway — carry risks forward, do NOT halt |
| Error | Action |
|---|---|
| Idea too vague after clarification | Telegram alert, halt pipeline |
| Scaffold fails (npm, git) | Telegram with diagnostic, halt |
| Brief/PRD/Architecture generation fails | Checkpoint to _output/, retry once, then Telegram + halt |
| Story/test file write fails | Retry, then Telegram + halt |
| Beads import partially fails | Count existing issues (bd list -l {prefix} --json), delete duplicates (bd close {dup} --reason "duplicate from partial import"), retry remaining with individual bd create |
| Beads import fully fails | Retry with individual bd create per story, then Telegram + halt |
Standard work-loop error handling applies:
.result marker file as fallbackbd CLI fails: log error, skip issue, continuegit pull --rebase, then Telegram alert| Error | Action |
|---|---|
| Test suite has failures | File Beads issues per failure, attempt one fix round, proceed anyway |
| Build fails | Diagnose error, attempt fix, retry. If still failing, Telegram alert + halt |
| Railway CLI not installed | Skip Phase 12, report "manual deployment needed" |
railway up fails | Telegram with error output, halt. User must fix Railway config |
| Health check fails post-deploy | Retry after 60s. If still failing, Telegram with URL + logs |
| Database migration fails on Railway | Telegram with migration error, halt. Do NOT proceed with broken DB |
If the pipeline is interrupted (crash or manual stop):
_output/ for existing artifacts — resume from the last incomplete phase_output/e2e-validation.md exists, skip to deploy (Phase 12)_output/deployment.md exists, skip to report (Phase 13)bd CLI, git, npm/npx, file operations, terminal, web search (for Phase 0)tdd-coder.md, quinn-validator.md, failure-classifier.md (in ~/.pi/agents/)beads-checkpoint.ts, budget-enforcer.ts, auto-committer.tsdev-team/work-loop (Phase 10), dev-team/health-fix (Phase 11 error resolution), dev-team/escalation-handler (failure routing)bmad-generate-project-context (Phase 2 brownfield context generation)model-tier-classifier (model selection)