Flow Builder

Execute implementation work following Flow framework patterns. This skill guides the build phase: verify readiness → start implementation → execute action items → verify completion → mark complete.

When to Use This Skill

Activate when the user wants to start coding:

•"Let's implement this"
•"Start coding"
•"Build the feature"
•"Time to write code"
•"Ready to implement"
•"Execute the action items"
•"Begin implementation"

Implementation Philosophy

Flow's Core Principle: Design before code. Implementation happens AFTER brainstorming is complete (if needed) and pre-implementation tasks are done.

Key Gates:

•Pre-Implementation Gate: Brainstorming must be ✅ COMPLETE (if iteration had brainstorming)
•Pre-Tasks Gate: All pre-implementation tasks must be ✅ COMPLETE
•Verification Gate: All action items done, tests passing, ready for next work

Implementation Pattern: Start → Execute → Verify → Complete

Pre-Implementation Gate Check

Before starting ANY implementation, verify readiness:

Check 1: Brainstorming Status (if applicable)

code

IF iteration has brainstorming section:
    IF brainstorming status ≠ ✅ COMPLETE:
        ❌ BLOCK implementation
        SUGGEST: "Brainstorming must be completed first. Use `/flow-next-subject` to continue brainstorming."
    ELSE:
        ✅ PASS gate
ELSE:
    ✅ PASS gate (no brainstorming needed)

Check 2: Pre-Implementation Tasks (if applicable)

code

IF iteration has "Pre-Implementation Tasks" section:
    IF any pre-task status ≠ ✅ COMPLETE:
        ❌ BLOCK implementation
        LIST incomplete pre-tasks
        SUGGEST: "Complete pre-tasks first, then use `/flow-implement-start`"
    ELSE:
        ✅ PASS gate
ELSE:
    ✅ PASS gate (no pre-tasks)

Check 3: Iteration Status

code

IF iteration status = 🚧 IN PROGRESS:
    ✅ PASS (already implementing)
IF iteration status = 🎨 READY or ⏳ PENDING:
    SUGGEST: "Use `/flow-implement-start` to begin implementation"

Implementation Workflow

Step 1: Start Implementation

Command: /flow-implement-start

What it does:

•Marks iteration 🚧 IN PROGRESS
•Creates "Implementation" section in task file
•Updates DASHBOARD.md current work

When to suggest: User is ready to code and gates passed

Step 2: Execute Action Items

Sequential Execution:

•Read action items from iteration (or brainstorming Type D subjects)
•Execute each action item in order
•Check off items as completed: - [x] Action item
•Document progress in "Implementation Notes"

Parallel Execution (when safe):

•If action items are independent (no dependencies)
•Example: Creating multiple unrelated files
•Still check off sequentially for tracking

Handling Blockers:

code

IF encounter blocker during implementation:
    DOCUMENT blocker in Implementation Notes
    ASSESS severity:
        - Minor (< 15 min fix): Handle and continue
        - Major (> 15 min, out of scope): STOP and notify user
        - Blocking (cannot proceed): Mark iteration ❌ BLOCKED, notify user

Step 3: Verify Completion

Before marking iteration complete, verify:

Verification Checklist:

• All action items checked off (✅)
• Code compiles/runs without errors
• Tests passing (if applicable)
• Files modified documented
• Implementation notes updated
• No unresolved blockers

Testing Strategy (from PLAN.md):

•Follow Testing Strategy section in PLAN.md
•Run tests according to project conventions
•Document test results in Implementation Notes

Step 4: Complete Implementation

Command: /flow-implement-complete

What it does:

•Marks iteration ✅ COMPLETE
•Updates completion date
•Updates DASHBOARD.md progress
•Advances to next iteration

When to suggest: All verification criteria met

Implementation Slash Commands

`/flow-implement-start`

Use when: Starting implementation for current iteration

Prerequisites:

•Brainstorming ✅ COMPLETE (if applicable)
•Pre-tasks ✅ COMPLETE (if applicable)
•Iteration status = 🎨 READY or ⏳ PENDING

Effect:

•Changes iteration status to 🚧 IN PROGRESS
•Creates implementation section in task file
•Updates DASHBOARD.md

`/flow-implement-complete`

Use when: All action items done and verified

Prerequisites:

•All action items checked off
•Verification criteria met
•No unresolved blockers

Effect:

•Marks iteration ✅ COMPLETE
•Updates completion date
•Advances to next iteration or task

Action Item Execution Patterns

Pattern 1: Sequential Implementation

Use when: Action items depend on each other

markdown

Action Items:
- [x] Create database schema
- [x] Implement data access layer (depends on schema)
- [x] Add service layer (depends on DAL)
- [x] Create API endpoints (depends on service)

Approach:

•Complete item 1
•Verify item 1 works
•Move to item 2
•Repeat until all done

Pattern 2: Parallel Implementation

Use when: Action items are independent

markdown

Action Items:
- [ ] Create logger utility
- [ ] Create validator utility
- [ ] Create formatter utility

Approach:

•Create all three files
•Verify each works independently
•Check off all items

Pattern 3: Incremental Verification

Use when: Complex implementation with multiple steps

markdown

Action Items:
- [x] Implement basic authentication (VERIFY: can login)
- [x] Add JWT token generation (VERIFY: tokens valid)
- [x] Add token refresh (VERIFY: refresh works)
- [x] Add logout (VERIFY: tokens invalidated)

Approach:

•Complete one action item
•Test/verify immediately
•Document verification in notes
•Move to next item

Pre-Implementation Tasks Pattern

What Are Pre-Implementation Tasks?

Small blocking tasks (< 30 min) that must be completed BEFORE main iteration work starts.

Examples:

•Refactor interface to support new pattern
•Update enum with missing values
•Fix bug in legacy code
•Rename file to match convention

When to Complete Pre-Tasks

code

IF iteration has "Pre-Implementation Tasks" section:
    FOR EACH pre-task:
        Complete pre-task
        Mark ✅ COMPLETE with date
        Document changes in pre-task section
    ONLY AFTER ALL PRE-TASKS DONE:
        Run /flow-implement-start for main iteration

Pre-Task Structure

markdown

#### Pre-Implementation Tasks

##### ⏳ Pre-Task 1: Update ErrorHandler to support async

**Why Blocking**: Retry logic requires async error handling

**Scope** (< 30 min):
- Update ErrorHandler.ts with async support
- Add retryAsync() method
- Update 3 call sites

**Files**:
- src/utils/ErrorHandler.ts

---

##### ✅ Pre-Task 1: Update ErrorHandler to support async

**Completed**: 2025-10-30

**Changes Made**:
- Added async support to ErrorHandler class
- Implemented retryAsync() method with exponential backoff
- Updated call sites in BillingService, PaymentService, OrderService
- Added unit tests for async error handling

**Files Modified**:
- src/utils/ErrorHandler.ts (+42 lines)
- tests/utils/ErrorHandler.test.ts (+28 lines)

Verification Best Practices

What to Verify

Code Quality:

• No syntax errors
• No linting errors
• Follows project conventions
• Code is readable and well-structured

Functionality:

• Feature works as intended
• Edge cases handled
• Error handling implemented
• No regressions introduced

Testing:

• Unit tests pass
• Integration tests pass (if applicable)
• Manual testing done (if no automated tests)

Documentation:

• Implementation notes updated
• Files modified list complete
• Verification results documented

When to Mark ❌ BLOCKED

Mark iteration ❌ BLOCKED when:

•External dependency not available
•Blocker requires > 1 hour to resolve
•Need user decision before proceeding
•Technical limitation discovered

Blocked Pattern:

markdown

### ❌ Iteration 2: Error Handling

**Status**: ❌ BLOCKED

**Blocker**: Stripe SDK doesn't support custom retry logic in v12

**Options**:
A) Downgrade to Stripe SDK v11 (supports custom retry)
B) Wait for v13 release (eta 2 weeks)
C) Implement wrapper around SDK calls

**Waiting for**: User decision on approach

Detailed Verification Guidance

For comprehensive guidance on verification, testing patterns, completion criteria, bug documentation, and decision-making, see VERIFICATION.md.

That resource includes:

•Testing Patterns: Unit testing, integration testing, manual testing checklists, and TDD patterns with complete code examples
•What "Done" Looks Like: 6 detailed completion criteria with examples
•When to Document Bugs and Issues: Bug documentation templates, severity levels, and fix-immediately vs defer guidance
•Deciding: ❌ BLOCKED vs Continue: Decision flowchart, 8 scenarios with examples, and real-world case studies

Scope Boundary Rules

When You Discover New Work

During implementation, if you discover issues NOT in current action items:

•
STOP - Don't make assumptions
•
ASSESS - Categorize the issue:
- •Syntax error in file you're editing? Fix and document
- •Missing functionality? Discuss with user
- •New feature idea? Defer to future iteration
- •Blocking bug? Propose pre-implementation task
•
NOTIFY user with structured options:
- •Option A: Create pre-implementation task (< 30 min, blocking)
- •Option B: Add as new brainstorming subject (design needed)
- •Option C: Handle immediately (if user approves)
- •Option D: Defer to separate iteration (after current work)
•
AWAIT user decision before proceeding

Example: Scope Boundary Alert

code

⚠️ SCOPE BOUNDARY ALERT

During implementation of Iteration 2 (Error Handling), discovered:

**Issue**: PaymentService.ts uses deprecated error format that conflicts with new retry logic

**Impact**: Cannot complete current action item without addressing this

**Options**:
A) Create pre-implementation task (estimated 20 min):
   - Update PaymentService error format
   - Update 2 call sites
   - Add to Pre-Implementation Tasks section

B) Add as brainstorming subject:
   - Need to design error format standard across all services
   - Affects more than just PaymentService

C) Handle immediately:
   - Fix PaymentService.ts now as part of current work
   - Document change in Implementation Notes

D) Defer to separate iteration:
   - Work around issue for now
   - Create new iteration for error format standardization

Which approach would you prefer?

🧾 UNPAIRED REQUEST CAPTURE + PLAN INSERTION RULE (CRITICAL)

Definition (unpaired request): Any user request (or sub-request) that is NOT explicitly mapped to:

•a recognized Flow slash command (/flow-...), and/or
•a recognized skill invocation / skill-owned workflow

Required behavior (always):

•Do not drop it. Capture it immediately so it becomes part of official planning.
•Do not derail the current run. Continue executing the currently selected flow command/skill as the primary task unless the user explicitly asks to switch.

A) Immediate capture (during the run)

Capture each unpaired request into the most relevant location:

•Future work / out-of-scope / “later” → append to .flow/BACKLOG.md.
•Needs design/discussion → add to the current iteration’s “Subjects to Discuss” list in phase-N/task-M.md (same format as /flow-brainstorm-subject).
•Concrete action to plan → append to .flow/USER_NOTES.md under ## Action Items (or ## Decisions if it’s a decision), as intake material for formalization.

B) End-of-run plan insertion (after completing the primary task)

After finishing the current command/skill output, promote each captured unpaired request into the active Flow plan artifacts (planning-only; do not start implementation).

Navigation (required):

•Use dashboard-first: read .flow/DASHBOARD.md → find current Phase/Task/Iteration → locate phase-N/task-M.md.

Promotion targets (choose exactly one per item):

•
Belongs in the current iteration as work to do →
- •Add as an unchecked checkbox under the current iteration’s single #### Action Items section.
•
Belongs in the current iteration but needs design first →
- •Add as a new ⏳ entry in Subjects to Discuss (brainstorming), per /flow-brainstorm-subject format.
•
Too large for current iteration; should be a new iteration under the current task →
- •Add a new ⏳ iteration using the /flow-iteration-add structure (update both task file + DASHBOARD iteration counts/listing, but do not change “Current Work” pointer).
•
A distinct new task under the current phase →
- •Add a new task using /flow-task-add structure (create phase-N/task-M.md + update DASHBOARD, but do not change “Current Work” pointer).
•
Explicitly deferred beyond current scope/version →
- •Ensure it is represented in .flow/BACKLOG.md (and referenced from PLAN only if the user explicitly wants V2/V3 tracked there).

End-of-run reporting (mandatory)

At the end of the response/run, include a short section:

Captured & Added to Plan:

•[Item] → captured in [file/section] → promoted to [DASHBOARD/Task/Iteration/Action Items/Backlog location]

Common Implementation Patterns

Pattern: Feature Implementation

code

User: "Let's implement the authentication system"

AI Response:
I'll help you implement the authentication system. Let me check readiness:

✅ Brainstorming Session - COMPLETE (4 subjects resolved)
✅ Pre-Implementation Tasks - COMPLETE (updated User model)
✅ Iteration Status - 🎨 READY

Ready to implement! Use `/flow-implement-start` to begin.

Action items from brainstorming:
1. Create AuthService class
2. Implement login/logout methods
3. Add JWT token generation
4. Integrate with API endpoints
5. Add authentication middleware

Estimated time: 3-4 hours

Should I start implementation?

Pattern: Handling Blockers

code

User: "Start implementing the payment integration"

AI Response:
I'll help you implement payment integration. Let me check readiness:

❌ Pre-Implementation Tasks - INCOMPLETE

Found 2 incomplete pre-tasks:
1. ⏳ Pre-Task 1: Refactor PaymentConfig interface
2. ⏳ Pre-Task 2: Update environment variables

These tasks must be completed before main implementation. Should I help you complete them now?

Pattern: Verification Before Completion

code

User: "Are we done with this iteration?"

AI Response:
Let me verify completion criteria:

✅ All action items checked off (5/5)
✅ Code compiles without errors
✅ Tests passing (unit: 12/12, integration: 3/3)
✅ Files modified documented (4 files)
✅ Implementation notes updated
✅ No unresolved blockers

Verification complete! All criteria met.

Use `/flow-implement-complete` to mark this iteration done and move to the next one.

Pattern: Incremental Progress

code

User: "How's the implementation going?"

AI Response:
Implementation progress for Iteration 2: Error Handling

Completed (3/5):
- [x] Create RetryPolicy class
- [x] Implement exponential backoff algorithm
- [x] Add configuration for max retries

In Progress (1/5):
- [ ] Integrate with StripeClient ← CURRENT (60% done)

Pending (1/5):
- [ ] Add tests for retry scenarios

Estimated completion: 1 hour

Working on integrating RetryPolicy with StripeClient.ts. Will move to tests next.

Examples

Example 1: Starting Implementation After Brainstorming

code

User: "Let's start building the retry logic"

AI Process:
1. Read current iteration from task file
2. Check brainstorming status: ✅ COMPLETE (4 subjects resolved)
3. Check pre-tasks: ✅ COMPLETE (updated ErrorHandler.ts)
4. Verify iteration status: 🎨 READY

AI Response:
"Ready to start implementation! All gates passed:
✅ Brainstorming complete (4 subjects resolved)
✅ Pre-tasks complete (ErrorHandler updated)
✅ Iteration status: READY

Action items from brainstorming (Type D):
- [ ] Create RetryPolicy class
- [ ] Implement exponential backoff algorithm
- [ ] Add configuration for max retries
- [ ] Integrate with StripeClient
- [ ] Add tests for retry scenarios

Use `/flow-implement-start` to begin, then I'll execute these action items."

Example 2: Handling Incomplete Pre-Tasks

code

User: "Start implementing the payment flow"

AI Process:
1. Read current iteration from task file
2. Check brainstorming: ✅ COMPLETE
3. Check pre-tasks: Found 2 incomplete pre-tasks

AI Response:
"Cannot start implementation yet. Pre-tasks must be completed first:

❌ Pre-Implementation Tasks - INCOMPLETE

Blocking tasks:
1. ⏳ Pre-Task 1: Update PaymentStatus enum - Add PENDING_RETRY and FAILED_PERMANENT states
2. ⏳ Pre-Task 2: Refactor PaymentService.process() - Extract validation logic to separate method

These must be done BEFORE main implementation. Should I complete these pre-tasks now?"

User: "Yes, complete them"

AI Process:
1. Complete Pre-Task 1 (update enum, update switch statements)
2. Mark Pre-Task 1 ✅ COMPLETE with date and changes
3. Complete Pre-Task 2 (extract validation method)
4. Mark Pre-Task 2 ✅ COMPLETE with date and changes
5. Verify all pre-tasks done

AI Response:
"All pre-tasks completed:
✅ Pre-Task 1: PaymentStatus enum updated (4 files modified)
✅ Pre-Task 2: Validation logic extracted (2 files modified)

Now ready for main implementation. Use `/flow-implement-start` to begin."

Example 3: Verification Before Marking Complete

code

User: "I think we're done with this iteration"

AI Process:
1. Read current iteration action items
2. Check completion status
3. Verify each completion criterion

AI Response:
"Let me verify completion criteria:

✅ Action Items (5/5):
  - [x] Create RetryPolicy class
  - [x] Implement exponential backoff algorithm
  - [x] Add configuration for max retries
  - [x] Integrate with StripeClient
  - [x] Add tests for retry scenarios

✅ Code Quality:
  - No syntax errors
  - Linting passed
  - Follows project conventions

✅ Tests:
  - Unit tests: 8/8 passing
  - Integration tests: 2/2 passing

✅ Documentation:
  - Files modified documented (4 files)
  - Implementation notes updated

All verification criteria met! Use `/flow-implement-complete` to mark this iteration complete."

Example 4: Scope Boundary During Implementation

code

User: [AI is implementing action items]

AI Process:
1. Working on "Integrate RetryPolicy with StripeClient"
2. Discovers PaymentService.ts uses deprecated error format
3. Realizes this is out of scope

AI Response:
"⚠️ SCOPE BOUNDARY ALERT

While integrating RetryPolicy with StripeClient, I discovered:

**Issue**: PaymentService.ts uses deprecated error format that conflicts with new retry logic

**Impact**: Current action item can continue, but this will cause issues when we add retry to PaymentService later

**Options**:
A) Create pre-implementation task for NEXT iteration:
   - Estimated: 20-30 minutes
   - Update PaymentService error format
   - Update 3 call sites

B) Add as new brainstorming subject:
   - Design error format standard across all services
   - Affects PaymentService, BillingService, OrderService

C) Handle immediately (expand current scope):
   - Fix PaymentService.ts now
   - Document as scope expansion

D) Defer to separate iteration:
   - Work around for now (document workaround)
   - Create new task for error format standardization

I recommend Option A (pre-task for next iteration) as it's small and blocking for future work. Which approach would you prefer?"

Interaction with Other Flow Skills

Design Stage (flow-designer Skill):

•/flow-brainstorm-start - Design decisions
•/flow-brainstorm-complete - Generate action items

Build Stage (This Skill):

•/flow-implement-start - Begin work ← YOU ARE HERE
•/flow-implement-complete - Finish iteration ← YOU ARE HERE

Navigation Stage (flow-navigator Skill):

•/flow-status - Check progress
•/flow-next - What to do next

References

•Implementation Pattern: DEVELOPMENT_FRAMEWORK.md lines 1798-1836
•Status Markers: DEVELOPMENT_FRAMEWORK.md lines 1872-1968
•Brainstorming Pattern: DEVELOPMENT_FRAMEWORK.md lines 1167-1797
•Pre-Implementation Tasks: DEVELOPMENT_FRAMEWORK.md lines 1683-1723
•Scope Boundary Rules: DEVELOPMENT_FRAMEWORK.md lines 339-540

Implementation Gate Checklist

Before implementing, verify ALL gates passed:

code

[ ] Brainstorming complete (if applicable)
[ ] Pre-implementation tasks complete (if applicable)
[ ] Current iteration status = 🎨 READY or ⏳ PENDING
[ ] User confirmed ready to implement

If ALL checked → Use /flow-implement-start

If ANY unchecked → Address blockers first

Completion Checklist

Before marking complete, verify ALL criteria met:

code

[ ] All action items checked off
[ ] Code compiles/runs
[ ] Tests passing
[ ] Files modified documented
[ ] Implementation notes updated
[ ] No unresolved blockers
[ ] Verification completed

If ALL checked → Use /flow-implement-complete

If ANY unchecked → Continue implementation