| name | development |
| description | Unified orchestrator for all development tasks. ALWAYS execute when invoked — never skip for 'straightforward' tasks. Phases adapt based on detected task characteristics rather than predetermined types. Use for any development work that modifies code. |
| user-invocable | true |
Development Orchestrator
Unified workflow for all development tasks — bug fixes, enhancements, and new features. Phases activate based on context and analysis findings, not predetermined task types.
Initialization
BEFORE executing any phase, you MUST complete these steps:
Step 0: Session-reminder conflict resolution (decide ONCE)
Before doing anything else, settle this policy now and do not re-litigate it at any gate:
→ **MANDATORY GATE** / → MANDATORY GATE markers fire regardless of session-reminders, permission mode, or prior approval patterns. None of the following exempt you from invoking ask_user at a gate — they apply only to your discretionary clarifications:
- Auto / acceptEdits / bypassPermissions permission modes
- Session reminders saying "work without stopping", "continue without asking", or "minimize clarifying questions"
- Compaction summaries showing the user approving every prior gate
If you find yourself reasoning "the user has been approving everything, so I can skip this gate" or "auto-mode is on, so I should minimize questions" — that reasoning IS the failure mode. STOP and fire the gate.
Full framework rule: ../orchestrator-framework/references/orchestrator-patterns.md
- section "Phase Gate Behavior"
- section "Resolving session-reminder conflicts"
Step 1: Load Framework Patterns
Read the framework reference file NOW using the Read tool:
../orchestrator-framework/references/orchestrator-patterns.md - Delegation rules, interactive mode, state schema, initialization, context passing, issue resolution
Step 2: Detect Research Context
If argument is a research folder path (matches .flowbit/tasks/research/*):
- Auto-detect research folder, extract task description from
research_context.research_question
- Read research artifacts (see Research-Based Development section below)
- Set
research_reference in state automatically
If --research=<path> flag provided:
- Read research artifacts from specified path
- Copy to
analysis/research-context/
- Set
research_reference in state
Step 3: Initialize Workflow
- Create Task Items: Use
TaskCreate for all phases (see Phase Configuration), then set dependencies with TaskUpdate addBlockedBy
- Create Task Directory:
.flowbit/tasks/development/YYYY-MM-DD-task-name/
- Initialize State: Create
orchestrator-state.yml with task info and research reference
- Discover project documentation: Read
.flowbit/docs/INDEX.md (if exists), extract ALL file paths from the "Project Documentation" section. This includes predefined docs (vision, roadmap, tech-stack, architecture) AND any user-added project docs (e.g., deployment.md, api-strategy.md). Store complete list as project_context.project_doc_paths in state.
Output:
🚀 Development Orchestrator Started
Task: [description]
Directory: [task-path]
Starting Phase 1: Codebase Analysis...
When to Use
Use for all development tasks: bug fixes, enhancements, new features, and any work that modifies code.
DO NOT use for: Performance optimization, security remediation, migrations, documentation-only, pure refactoring (use specialized orchestrators).
Phase Configuration
| Phase | content | activeForm | Activation |
|---|
| 1 | "Analyze codebase & clarify requirements" | "Analyzing codebase & clarifying" | Always |
| 2 | "Analyze gaps & clarify scope" | "Analyzing gaps & clarifying scope" | Always |
| 3 | "Write failing test (TDD Red)" | "Writing failing test" | When has_reproducible_defect |
| 4 | "Generate UI mockups" | "Generating UI mockups" | When ui_heavy |
| 5 | "Gather requirements & create specification" | "Gathering requirements & creating specification" | Always |
| 6 | "Audit specification" | "Auditing specification" | Always (conditional) |
| 7 | "Plan implementation" | "Planning implementation" | Always |
| 8 | "Execute implementation" | "Executing implementation" | Always |
| 9 | "Verify test passes (TDD Green)" | "Verifying test passes" | When Phase 3 was executed |
| 10 | "Prompt verification options" | "Prompting verification options" | Always |
| 11 | "Verify implementation & resolve issues" | "Verifying implementation" | Always |
| 12 | "Run E2E tests" | "Running E2E tests" | When e2e_enabled |
| 13 | "Generate user documentation" | "Generating user documentation" | When user_docs_enabled |
| 14 | "Finalize workflow" | "Finalizing workflow" | Always |
Workflow Phases
Phase 1: Codebase Analysis & Clarifications
Purpose: Comprehensive codebase exploration followed by scope/requirements clarification
Execute:
- Skill tool -
flowbit-codebase-analyzer
- Update state with analysis results
- Direct - use ask_user for max 5 critical clarifying questions
- Save clarifications to
analysis/clarifications.md
Output: analysis/codebase-analysis.md, analysis/clarifications.md
State: Update task_context.risk_level, phase_summaries.codebase_analysis, task_context.clarifications_resolved
→ AUTO-CONTINUE — Do NOT end turn, do NOT prompt user. Proceed immediately to Phase 2.
Phase 2: Gap Analysis & Scope Clarification
Purpose: Compare current vs desired state, detect task characteristics, then resolve scope/approach decisions
Execute:
- Task tool -
flowbit-gap-analyzer subagent
- Extract and store structured data from gap-analyzer result:
a. Read
task_characteristics from gap-analyzer output — 5 fields: has_reproducible_defect, modifies_existing_code, creates_new_entities, involves_data_operations, ui_heavy
b. Write all 5 fields to orchestrator-state.yml at task_context.task_characteristics
c. Read risk_level from output and write to task_context.risk_level
d. Extract phase summary (1-2 sentences) and write to phase_summaries.gap_analysis
e. SELF-CHECK: "Did I read the 5 task_characteristics from the gap-analyzer output and write them to state? Let me re-read orchestrator-state.yml to verify the values match the gap-analyzer output."
⛔ DECISION GATE (mandatory — do NOT skip):
- Parse
decisions_needed from gap-analyzer output
- If
decisions_needed.critical OR decisions_needed.important is non-empty:
- MUST use
ask_user — one question per critical decision, batch important decisions into a single sequential single-select questions (one per option)
- If both are empty: Note "No scope decisions needed" in state
SELF-CHECK before continuing: "Did the gap-analyzer return decisions_needed items? If yes, did I invoke ask_user? If I skipped this, STOP and go back."
- Save scope clarifications to
analysis/scope-clarifications.md
- Set optional phase defaults based on detected characteristics:
- If
task_characteristics.ui_heavy: true → set options.e2e_enabled: true, options.user_docs_enabled: true
- If
task_characteristics.creates_new_entities: true → set options.user_docs_enabled: true
- Command flags (
--e2e, --no-e2e, --user-docs, --no-user-docs) override these defaults
Output: analysis/gap-analysis.md, analysis/scope-clarifications.md (conditional)
State: Update task_context.task_characteristics, task_context.scope_expanded, options.e2e_enabled, options.user_docs_enabled, phase_summaries.gap_analysis
Context to pass: Risk level, codebase summary, key files, clarifications, project_doc_paths (from state)
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ANTI-PATTERN — DO NOT DO THIS:
- ❌ "The UI change is small/simple, skipping Phase 4..." — STOP. If
ui_heavy is true, Phase 4 runs. The gap-analyzer made this assessment, not you.
- ❌ "No new screens needed, just a component..." — STOP.
ui_heavy is a signal from the gap-analyzer. Do NOT override it with your own complexity judgment.
ask_user - Display executive summary before asking. Read analysis/gap-analysis.md and extract: task type detected, risk level, key characteristics enabled (TDD gates, UI mockups, E2E, user docs), scope decisions made (if any). Then read task_context.task_characteristics from orchestrator-state.yml and determine the next phase:
- If
has_reproducible_defect is true → ask "Continue to Phase 3: TDD Red Gate?"
- If
ui_heavy is true → ask "Continue to Phase 4: UI Mockup Generation?"
- Otherwise → ask "Continue to Phase 5: Technical Approach, Requirements & Specification?"
Phase 3: TDD Red Gate (Conditional)
Phase entry self-check: Before executing this phase, locate the ask_user tool call from Phase 2 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Write a failing test that reproduces the defect
Execute: Direct - write test, verify it FAILS
Output: implementation/tdd-red-gate.md, failing test file
State: Update tdd_red_passed: true
Skip if: task_characteristics.has_reproducible_defect is false (not set by gap-analyzer)
Critical: Test MUST fail before implementation (proves defect exists)
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - "TDD red gate complete. Continue to Phase 4?"
Phase 4: UI Mockup Generation (Conditional)
Phase entry self-check: Before executing this phase, locate the ask_user tool call from the preceding phase in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Generate ASCII mockups showing UI integration
Execute: Task tool - flowbit-ui-mockup-generator subagent
Output: analysis/ui-mockups.md
State: Update phase_summaries.ui_mockups
Skip if: task_characteristics.ui_heavy is false
Context to pass: Gap analysis, scope decisions, component choices
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - "UI mockups complete. Continue to Phase 5?"
Phase 5: Technical Approach, Requirements & Specification
Phase entry self-check: Before executing this phase, locate the ask_user tool call from the preceding phase in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
⛔ ROUTING GUARD: Read task_context.task_characteristics from orchestrator-state.yml. If has_reproducible_defect is true and Phase 3 is NOT in completed_phases → STOP, execute Phase 3 first. If ui_heavy is true and Phase 4 is NOT in completed_phases → STOP, execute Phase 4 first.
Purpose: Resolve technical decisions, gather specification requirements, then create comprehensive specification
Execute:
Part A — Technical & Architecture Clarification (inline, conditional):
- If complex task with multiple approaches: Direct - use ask_user for 3-5 technical questions
- If multiple valid architectural approaches exist: Present 2-3 approaches via ask_user. The chosen approach is passed to specification-creator so the spec is written with the decided architecture.
- Save to
analysis/technical-clarifications.md (conditional)
Skip technical clarification if: Simple task, risk_level = low, no multiple approaches detected
Part B — Requirements Gathering (inline):
3. Direct - use ask_user for specification requirements:
- Adaptive question count based on description length:
- Brief (<30 words): 6-8 questions
- Standard (30-100 words): 4-6 questions
- Detailed (>100 words): 2-3 focused questions
- Frame as confirmable assumptions: "I assume X, is that correct?"
- REQUIRED questions (always include):
- User Journey: How will users discover/access this? Which personas? How fits existing workflows?
- Existing Code Reuse: Similar features, UI components, backend patterns to reference?
- Visual Assets: Any mockups, wireframes, screenshots? Place in
analysis/visuals/
- Check for visual assets in
analysis/visuals/ (even if user says none)
- If found: note for subagent context
- If not found and non-UI task: skip visual asset processing
- Save gathered requirements to
analysis/requirements.md with: initial description, Q&A from all rounds, similar features identified, visual assets and insights, functional requirements summary, reusability opportunities, scope boundaries, technical considerations
Part C — Specification Creation (subagent):
ANTI-PATTERN — DO NOT DO THIS:
- ❌ "Let me create the specification..." — STOP. Delegate to specification-creator.
- ❌ "I'll write the spec based on requirements..." — STOP. Delegate to specification-creator.
- ❌ "The task is simple enough to spec inline..." — STOP. Simplicity is NOT a reason to skip delegation.
INVOKE NOW — Task tool call:
- Task tool -
flowbit-specification-creator subagent
Context to pass to subagent: task_path, task_description, task_characteristics, requirements_path (analysis/requirements.md), project_context_paths (INDEX.md + project_doc_paths from state — all discovered project docs), risk_level, phase_summaries (codebase_analysis, gap_analysis, clarifications, scope_clarifications, ui_mockups), research_context (if any)
SELF-CHECK: Did you just invoke the Task tool with flowbit-specification-creator? Or did you start writing spec.md yourself? If the latter, STOP immediately and invoke the Task tool instead.
Output: analysis/technical-clarifications.md (conditional), analysis/requirements.md, implementation/spec.md
State: Update task_context.tech_clarified, task_context.architecture_decision, phase_summaries.specification
Part D — Diagram Refinement (Skill, content-preserving):
7. Invoke Skill tool: flowbit-diagrams-mermaid to refine implementation/spec.md
8. Add diagrams that clarify scope and communication (without replacing prose):
flowchart for primary functional path,sequenceDiagram for key component interaction,- optionally
C4Component if internal module structure is required by scope.
- If required context is missing, add explicit open questions/assumptions section instead of inventing entities.
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - Display executive summary before asking. Read implementation/spec.md and extract: spec title, scope boundaries (what's included and excluded), number of key requirements, architecture approach chosen (if any), assumptions made. Format as brief overview then "Continue to specification audit?"
Phase 6: Specification Audit (Recommended)
Phase entry self-check: Before executing this phase, locate the ask_user tool call from Phase 5 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Independent review of specification before implementation
Execute: Task tool - flowbit-spec-auditor subagent
Output: verification/spec-audit.md
State: Update options.spec_audit_enabled
Recommended: Always. Present spec audit as the recommended default. User can skip if they choose.
ask_user - "Run specification audit? (Recommended)" with "Yes, run audit (Recommended)" as first option
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - Display executive summary before asking. Read verification/spec-audit.md and extract: overall verdict (pass/pass-with-concerns/fail), issue counts by severity, top 1-2 critical findings if any. Format as brief overview then "Continue to implementation planning?"
Phase 7: Implementation Planning
Phase entry self-check: Before executing this phase, locate the ask_user tool call from Phase 6 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Break specification into implementation steps
ANTI-PATTERN — DO NOT DO THIS:
- ❌ "Let me create the implementation plan..." — STOP. Delegate to implementation-planner.
- ❌ "I'll break this into steps..." — STOP. Delegate to implementation-planner.
- ❌ "This is simple enough to plan inline..." — STOP. Simplicity is NOT a reason to skip delegation.
INVOKE NOW — Task tool call:
Execute: Task tool - flowbit-implementation-planner subagent
Output: implementation/implementation-plan.md
State: Update task groups and dependencies
Context to pass to subagent: task_path, task_description, task_characteristics, phase_summaries (specification, gap_analysis, codebase_analysis), research_context (if any)
SELF-CHECK: Did you just invoke the Task tool with flowbit-implementation-planner? Or did you start writing implementation-plan.md yourself? If the latter, STOP immediately and invoke the Task tool instead.
Post-plan diagram refinement (Skill, content-preserving):
- Invoke Skill tool:
flowbit-diagrams-mermaid for implementation/implementation-plan.md
- Add a compact execution diagram (task-group dependency flow or phase/state view).
- Keep implementation steps authoritative; diagrams are explanatory, not a replacement for task descriptions.
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - Display executive summary before asking. Read implementation/implementation-plan.md and extract: number of task groups, total implementation steps, key dependencies between groups, estimated complexity. Format as brief overview then "Continue to implementation?"
Phase 8: Implementation
Phase entry self-check: Before executing this phase, locate the ask_user tool call from Phase 7 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Execute the implementation plan
ANTI-PATTERN — DO NOT DO THIS:
- ❌ "Let me implement this directly..." — STOP. Delegate to implementation-plan-executor.
- ❌ "This is simple enough to code inline..." — STOP. Simplicity is NOT a reason to skip delegation.
INVOKE NOW — Skill tool call:
Execute: Skill tool - flowbit-implementation-plan-executor
Output: Implemented code, implementation/work-log.md
State: Update implementation progress, extract phase_summaries.implementation
SELF-CHECK: Did you just invoke the Skill tool with flowbit-implementation-plan-executor? Or did you start writing code yourself? If the latter, STOP immediately and invoke the Skill tool instead.
⚠️ POST-IMPLEMENTATION CONTINUATION — After the skill completes and returns control:
- Read
orchestrator-state.yml to confirm you are the orchestrator
- Update state: add Phase 8 to
completed_phases
- Evaluate conditional: if
task_characteristics.has_reproducible_defect AND Phase 3 in completed_phases → Phase 9, else → Phase 10
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - Display executive summary before asking. Extract from phase_summaries.implementation and implementation/work-log.md: task groups completed, files changed, test results from incremental runs, any known issues or deferred items. Format as brief overview then "Continue to verification?"
Phase 9: TDD Green Gate (Conditional)
Phase entry self-check: Before executing this phase, locate the ask_user tool call from Phase 8 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Verify the failing test now passes
Execute: Direct - run the test written in Phase 3
Output: implementation/tdd-green-gate.md
State: Update tdd_green_passed: true
Skip if: Phase 3 was not executed
Critical: Test MUST pass (proves defect is fixed)
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - "TDD gate passed. Continue to Phase 10?"
Phase 10: Verification Options Prompt
Phase entry self-check: Before executing this phase, locate the ask_user tool call from the preceding phase in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Determine which verification checks to run using tiered decision matrix
Execute: Direct - display plan, confirm/adjust via ask_user
Output: Updated state with all verification options
State: Set options.code_review_enabled, options.pragmatic_review_enabled, options.reality_check_enabled, options.production_check_enabled, options.e2e_enabled, options.user_docs_enabled
Auto-set: skip_test_suite: true (full test suite already passed during implementation phase; cleared before re-verification if fixes are applied)
Step 1: Display the verification plan:
Verification Plan:
Obligatory (always run):
✓ Completeness check
✓ Test suite (skipped — passed during implementation; re-enabled after fixes)
Recommended (adjustable):
✓ Code review — quality and security analysis
✓ Pragmatic review — detects over-engineering
✓ Reality check — validates work solves the problem
✓ Production readiness — deployment readiness checks
Conditional:
[✓/—] E2E browser testing — [reason]
[✓/—] User documentation — [reason]
Step 2 (3 questions):
Q1 (always): ask_user (sequential single-select) — "Which standard verifications to run?"
Options: "Code review (Recommended)", "Pragmatic review (Recommended)", "Reality check (Recommended)", "Production readiness (Recommended)". All pre-selected.
Q2 (SKIP if options.e2e_enabled: false and no --e2e flag): ask_user — "Enable E2E browser verification?" Options: "Yes (Recommended)", "No, skip".
Q3 (SKIP if options.user_docs_enabled: false and no --user-docs flag): ask_user — "Generate user documentation?" Options: "Yes (Recommended)", "No, skip".
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
Phase 11: Verification & Issue Resolution
Phase entry self-check: Before executing this phase, locate the ask_user tool call from Phase 10 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Comprehensive implementation verification with fix-then-reverify cycles
Output: verification/implementation-verification.md, optional code-review/pragmatic/reality reports, updated implementation/work-log.md
State: Update verification results, verification_context
Execute:
Step 1: Invoke Skill tool - flowbit-implementation-verifier
Step 2: Display detailed issue breakdown grouped by category and severity:
Verification Results:
Critical ([N]):
- [category]: [description] — [file:line] [fixable/manual]
...
Warning ([N]):
- [category]: [description] — [file:line] [fixable/manual]
...
Info ([N]):
- [description] (listed for awareness, not actionable)
Step 3: Gate on verification status:
status: passed → skip to Post-Verification Continuationstatus: passed_with_issues or failed → enter user-driven fix loop (Step 4)
Step 4: User-driven fix loop (max 3 iterations):
- Present all critical + warning issues as a numbered list
- ask_user — "Which issues should I fix?" with options:
- "Fix all fixable issues" (convenience default)
- "Let me choose specific issues" (user picks by number)
- "Skip fixes, proceed as-is"
- Fix selected issues, log each to
verification_context.fixes_applied
- After fixes applied: set
skip_test_suite: false (code changed, tests must re-run)
- ask_user — "Re-run verification to check fixes?" with options:
- "Yes, re-run verification" → re-invoke
flowbit-implementation-verifier → return to Step 2
- "No, proceed to next phase"
- Update
verification_context.reverify_count
Exit conditions:
- No critical issues remain → proceed
- User explicitly chooses "Skip fixes, proceed as-is" or "No, proceed to next phase" → proceed with issues logged
- Max 3 iterations reached → ask_user: "Proceed with known issues?" / "Stop workflow"
- MUST NOT proceed with unresolved critical issues unless user explicitly approves
⚠️ POST-VERIFICATION CONTINUATION — After issue resolution completes:
- Read
orchestrator-state.yml to confirm you are the orchestrator
- Update state: add Phase 11 to
completed_phases
- Proceed to Phase 12
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - Display executive summary: total issues found, issues fixed, issues remaining by severity. Then "Continue to Phase 12?"
Phase 12: E2E Testing (Optional)
Phase entry self-check: Before executing this phase, locate the ask_user tool call from Phase 11 in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Runtime browser verification with screenshots (via Playwright MCP tools, not test file generation)
Execute: Task tool - flowbit-e2e-test-verifier subagent
Prompt must include: task_path (absolute), spec_path, base_url. Report saves to {task_path}/verification/e2e-verification-report.md.
Output: verification/e2e-verification-report.md, screenshots
State: Update E2E results
Skip if: options.e2e_enabled = false
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - "E2E complete. Continue to Phase 13?"
Phase 13: User Documentation (Optional)
Phase entry self-check: Before executing this phase, locate the ask_user tool call from the preceding phase in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Generate user-facing documentation with screenshots
Execute: Task tool - flowbit-user-docs-generator subagent
Prompt must include: task_path (absolute), spec_path, base_url. Guide saves to {task_path}/documentation/user-guide.md.
Output: documentation/user-guide.md, screenshots
State: Update docs generation status
Skip if: options.user_docs_enabled = false
→ MANDATORY GATE — fires regardless of permission mode, session-reminders, or prior approval patterns. Invoke ask_user now. Proceeding without a user response is a protocol violation (orchestrator-patterns.md — section "Phase Gate Behavior" / section "Resolving session-reminder conflicts").
ask_user - "Documentation complete. Continue to Phase 14?"
Phase 14: Finalization
Phase entry self-check: Before executing this phase, locate the ask_user tool call from the preceding phase in this conversation. If you cannot point to its call ID, STOP and fire that gate now. State updates (completed_phases, TaskUpdate) without a corresponding ask_user call are protocol violations — never paper over a missed gate by updating state.
Purpose: Complete workflow and provide next steps
Execute: Direct - create summary, update state, guide commit
Output: Workflow summary
State: Set task.status: completed
Process:
- Create workflow summary
- Update task status to "completed"
- Provide commit message template
- Guide next steps (code review, PR, deployment)
→ End of workflow
Domain Context (State Extensions)
Development-specific fields in orchestrator-state.yml:
orchestrator:
options:
spec_audit_enabled: true
skip_test_suite: true
e2e_enabled: null
user_docs_enabled: null
code_review_enabled: true
pragmatic_review_enabled: true
reality_check_enabled: true
production_check_enabled: true
task_context:
risk_level: null
clarifications_resolved: null
scope_expanded: null
architecture_decision: null
task_characteristics:
has_reproducible_defect: false
modifies_existing_code: false
creates_new_entities: false
involves_data_operations: false
ui_heavy: false
research_reference:
path: null
research_question: null
research_type: null
confidence_level: null
phase_summaries:
research: {summary: null, key_findings: [], recommended_approach: null}
codebase_analysis: {key_files: [], primary_language: null, summary: null}
clarifications: []
gap_analysis: {integration_points: [], summary: null}
scope_clarifications: {scope_expanded: null, summary: null}
ui_mockups: {components_designed: [], summary: null}
specification: {summary: null}
architecture_decision: {decision: null, summary: null}
Task Structure
.flowbit/tasks/development/YYYY-MM-DD-task-name/
├── orchestrator-state.yml
├── analysis/
│ ├── research-context/ # If --research provided
│ ├── codebase-analysis.md # Phase 1
│ ├── clarifications.md # Phase 1
│ ├── gap-analysis.md # Phase 2
│ ├── scope-clarifications.md # Phase 2 (conditional)
│ ├── technical-clarifications.md # Phase 5 (conditional)
│ └── ui-mockups.md # Phase 4 (conditional)
├── implementation/
│ ├── spec.md # Phase 5
│ ├── requirements.md # Phase 5
│ ├── implementation-plan.md # Phase 7
│ ├── work-log.md # Phase 8
│ ├── tdd-red-gate.md # Phase 3 (conditional)
│ └── tdd-green-gate.md # Phase 9 (conditional)
├── verification/
│ ├── spec-audit.md # Phase 6 (recommended)
│ ├── implementation-verification.md # Phase 11
│ └── e2e-verification-report.md # Phase 12 (optional)
└── documentation/
└── user-guide.md # Phase 13 (optional)
Auto-Recovery
| Phase | Max Attempts | Strategy |
|---|
| 1 | 2 | Expand search, prompt user |
| 2 | 2 | Re-analyze, ask user |
| 3 | 2 | Rewrite test, skip TDD with doc |
| 5 | 2 | Regenerate spec |
| 7 | 2 | Regenerate plan |
| 8 | 5 | Fix syntax, imports, tests |
| 9 | 3 | Return to implementation |
| 11 | 3 | Fix tests, re-run |
Command Flags
| Flag | Effect |
|---|
--from=PHASE | Start from specific phase |
--research=PATH | Link to completed research task |
--audit / --no-audit | Force/skip specification audit |
--e2e / --no-e2e | Force/skip E2E testing |
--user-docs / --no-user-docs | Force/skip user documentation |
Research-Based Development
When starting development from a completed research task, the orchestrator loads research context to INFORM all phases.
Invocation Methods
Method 1: Research folder as sole argument (recommended)
/flowbit-development .flowbit/tasks/research/2026-01-12-oauth-research
The orchestrator auto-detects this is a research folder and:
- Extracts task description from
research_context.research_question
- Reads all research artifacts
- Sets
research_reference in state
Method 2: Explicit --research flag
/flowbit-development "Implement OAuth" --research=.flowbit/tasks/research/2026-01-12-oauth-research
Research Artifacts (Standard List)
When research context is detected, read these files from the research folder:
| Artifact | Path | Purpose |
|---|
| State | orchestrator-state.yml | research_type, confidence_level |
| Report | outputs/research-report.md | Main findings and conclusions |
| Solution Exploration | outputs/solution-exploration.md | Alternatives and trade-offs (input to Phase 5) |
| High-Level Design | outputs/high-level-design.md | C4 architecture (input to Phase 5) |
| Decision Log | outputs/decision-log.md | ADR decisions (input to Phase 5) |
How Research Informs Each Phase
Research INFORMS phases, never SKIPS them. Research context passes to ALL phases via task_context.phase_summaries.research. No phases are skipped.
| Phase | How Research Context is Used |
|---|
| Phase 1 | Codebase analyzer receives research findings as search guidance |
| Phase 2 | Gap analyzer uses research recommendations for comparison |
| Phase 5 | Specification creator uses high-level-design.md as INPUT (still creates full spec). Architecture decisions use research report AND decision-log.md (lighter when ADRs comprehensive) |
| Phase 7 | Implementation planner references research approach for task grouping |
Command Integration
Invoked via:
/flowbit-development [description] [--e2e] [--user-docs] [--research=PATH] (new)/flowbit-development [task-path] [--from=PHASE] [--reset-attempts] (resume)
TDD Gate Rules
Phase 3 (Red Gate): Test MUST FAIL before implementation (activated when gap-analyzer detects reproducible defect)
Phase 9 (Green Gate): Test MUST PASS after implementation (activated when Phase 3 was executed)
