workflow - ondatra-ai/flow-test GitHub Wiki

REQUIREMENTS-DRIVEN DEVELOPMENT WORKFLOW

Core Principle: Requirements drive code. Requirements.md is the single source of truth.

WORKFLOW PHASES

flowchart LR
    A[Phase 1:<br/>FILL TASK INFO] --> B[Phase 2:<br/>PLAN REQUIREMENTS] --> C[Phase 3:<br/>PLAN EXECUTION] --> D[Phase 4:<br/>EXECUTE] --> E[Phase 5:<br/>FINALIZE]
    
    C -.->|Requirements unclear| B
    D -.->|Replan - 1st time| C
    D -.->|Replan failed - 2nd time| B
    
    style A fill:#ff0000,color:#ffffff,stroke:#ff0000,stroke-width:2px
    style E fill:#ffffff,color:#ff0000,stroke:#ff0000,stroke-width:2px
Loading

PHASE 1: FILL TASK INFO

Input: Task description
Output: task.md (section: TASK INFO)

  1. Create task.md from template
  2. Fill TASK INFO section with task details
  3. Initialize TASK PROGRESS section

Human Gate:

User Response Action Next Step
approve Approve task info → Phase 2
clarify Need clarification → Revise

PHASE 2: PLAN REQUIREMENTS

Input: task.md with TASK INFO
Output: task.md (sections: TASK PROGRESS, REQUIREMENT UPDATES)

  1. Compare task with current requirements.md
  2. Document what requirements need to:
    • ADD (new features)
    • MODIFY (changed behavior)
    • REMOVE (deprecated)
    • CLARIFY (ambiguous)
  3. Define success criteria

Human Gate:

User Response Action Next Step
approve Approve requirements plan → Phase 3
revise Changes needed → Retry
clarify Need more information → Gather

PHASE 3: PLAN EXECUTION

Input: Approved task.md with requirements
Output: Implementation plan in task.md (section: EXECUTION PLAN)

  1. Break down into implementation steps
  2. List files to create/modify/delete
  3. Define execution order
  4. Plan requirements.md updates

Human Gate:

User Response Action Next Step
approve Approve execution plan → Phase 4
revise Plan needs changes → Retry
bad-requirements Requirements unclear → Phase 2

PHASE 4: EXECUTE

Input: Approved plan
Output: Updated requirements + implemented code

  1. Update requirements.md FIRST (desired end state)
  2. Implement code changes per plan
  3. Track progress in task.md (including replan count)
  4. Validate against success criteria

Human Gate:

User Response Action Next Step
approve Implementation complete → Phase 5
fix Implementation needs fixes → Retry
replan Bad plan (check replan count) → Phase 3 (1st time) or Phase 2 (2nd time)
bad-requirements Requirements issue → Phase 2

PHASE 5: FINALIZE

Input: Working implementation
Output: Completed task with updated requirements

  1. Save all requirements to requirements.md (ensure persistent state)
  2. Validate ALL requirements (not just new ones)
  3. Verify implementation matches requirements
  4. Mark task complete in task.md

Result: Task done, requirements saved, ready for next

Human Gate: None (final phase)

KEY RULES

  1. Requirements First: Always update requirements.md BEFORE coding
  2. Human Approval: Required at each phase before proceeding to next phase
  3. Loop Back: Return to earlier phases when issues found
  4. Single Truth: requirements.md defines the system
  5. Replan Limit: After ONE failed replan attempt, MUST go to Phase 2 to replan requirements

FILES

  • requirements.md - Project requirements (persistent)
  • task.md - Current task analysis/plan (per task)

QUICK START

  1. New Project: Create requirements.md
  2. New Task: Start at Phase 1 (FILL TASK INFO)
  3. Follow Gates: Get approval before proceeding
  4. Loop When Needed: Go back if issues found
⚠️ **GitHub.com Fallback** ⚠️