Flow Builder

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)

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)

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

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:

1. Read action items from iteration (or brainstorming Type D subjects)
2. Execute each action item in order
3. Check off items as completed: - [x] Action item
4. 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:

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

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:

1. Complete item 1
2. Verify item 1 works
3. Move to item 2
4. Repeat until all done

Pattern 2: Parallel Implementation

Use when: Action items are independent

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

Approach:

1. Create all three files
2. Verify each works independently
3. Check off all items

Pattern 3: Incremental Verification

Use when: Complex implementation with multiple steps

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:

1. Complete one action item
2. Test/verify immediately
3. Document verification in notes
4. 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

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

#### 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:

### ❌ 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:

1. STOP - Don't make assumptions

2. 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

3. 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)

4. AWAIT user decision before proceeding

Example: Scope Boundary Alert

⚠️ 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?

Common Implementation Patterns

Pattern: Feature Implementation

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

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

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

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

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

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

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

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:

[ ] 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:

[ ] 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