@dv.nghiem/flowdeck 0.2.2 → 0.2.4

package/src/workflows/execute-flow.md

@@ -1,233 +0,0 @@
----
-name: execute-flow
-description: "TDD-enforced feature execution: behavior checklist → RED (failing tests) → GREEN (minimum impl) → REFACTOR → review"
-triggers:
-  - /new-feature
-steps:
-  - name: guard_check
-    agent: "@orchestrator"
-    priority: first
-    action: Verify .planning/ and .codebase/ exist, plan is confirmed; Initialize TDD state (stage=behavior)
-  - name: load_plan
-    agent: "@orchestrator"
-    action: Read active PLAN.md from current phase directory
-  - name: define_behaviors
-    agent: "@orchestrator"
-    action: "Generate behavior checklist from PLAN.md: list all acceptance cases, edge cases, and expected behaviors"
-  - name: identify_next_step
-    agent: "@orchestrator"
-    action: Find first incomplete step (not in steps_complete); Check TDD stage for that step
-  - name: write_behavior_tests
-    agent: "@tester"
-    action: "TDD RED: Write failing tests for the behavior. Tests MUST fail before implementation."
-  - name: confirm_red
-    agent: "@tester"
-    action: "Run failing tests — confirm they fail for expected reasons. Do NOT proceed until tests fail."
-  - name: implement_minimum
-    agent: "@coder"
-    action: "TDD GREEN: Implement minimum code to make failing tests pass. No speculative features."
-  - name: confirm_green
-    agent: "@tester"
-    action: "Run tests — confirm they pass. Do NOT proceed until tests pass."
-  - name: refactor_step
-    agent: "@coder"
-    action: "TDD REFACTOR: Clean up code for this step while preserving passing tests. Only if GREEN."
-  - name: verify_step
-    agent: "@tester"
-    action: "Run full test suite for this step. Confirm all pass after refactoring."
-  - name: review_step
-    agent: "@reviewer"
-    action: "Run @reviewer on completed step work; Check TDD discipline, test coverage, no test omissions"
-  - name: update_state
-    agent: "@orchestrator"
-    action: "Mark step complete via planning-state tool; Update TDD stage"
-  - name: loop_or_complete
-    agent: "@orchestrator"
-    action: "If more steps, return to identify_next_step; If all done, update phase status to complete"
----
-
-# Execute Flow (TDD-Enforced)
-
-## Purpose
-
-Orchestrates execution of a confirmed PLAN.md following strict Red-Green-Refactor TDD cycle.
-
-## Prerequisites
-
-Before executing, verify:
-1. `.planning/` exists (project initialized)
-2. `.codebase/` exists (codebase mapped)
-3. `PLAN.md` is confirmed (via /plan phase)
-
-If any prerequisite fails, abort with clear error.
-
-## TDD Cycle Per Step
-
-Each plan step follows the TDD cycle:
-
-```
-BEHAVIOR → RED → GREEN → REFACTOR → next step
-   ↑_________|        |
-   (loop if needed)  Only if GREEN
-```
-
-## Step Definitions
-
-### Step 1: Guard Check
-
-Verify prerequisites:
-- `.planning/` directory exists
-- `.codebase/` directory exists
-- `STATE.md` has `plan_confirmed: true`
-- `PLAN.md` exists in current phase directory
-
-Initialize TDD state:
-```yaml
-tdd:
-  stage: behavior
-  cycle: 1
-  behaviors: []
-  regression_test_links: []
-```
-
-### Step 2: Load Plan
-
-Read the active PLAN.md from the current phase directory.
-Parse the tasks list and identify which steps are complete.
-
-### Step 3: Define Behaviors
-
-Spawn `@orchestrator` to generate behavior checklist from PLAN.md:
-- Acceptance cases for each step
-- Edge cases to test
-- Expected behaviors
-
-Store in TDD state.
-
-### Step 4: Identify Next Step
-
-From PLAN.md, find the first step NOT in `steps_complete`.
-Check TDD stage — only proceed if stage is appropriate for the step.
-
-### Step 5: Write Failing Tests (RED)
-
-Spawn `@tester` to write tests for the step's behavior:
-- **Tests MUST fail** before implementation
-- Cover acceptance cases and edge cases
-- Use AAA pattern (Arrange-Act-Assert)
-
-### Step 6: Confirm RED
-
-Run failing tests:
-- **GUARD: Do NOT proceed to Step 7 until tests fail**
-- If tests pass unexpectedly, tests don't correctly describe behavior
-
-### Step 7: Implement Minimum (GREEN)
-
-Spawn `@coder` to implement:
-- **Minimum code** to make failing tests pass
-- No speculative features
-- No over-engineering
-
-### Step 8: Confirm GREEN
-
-Run tests:
-- **GUARD: Do NOT proceed to Step 9 until tests pass**
-- If tests fail, return to Step 7
-
-### Step 9: Refactor (REFACTOR)
-
-Only if GREEN:
-- Clean up code for this step
-- Remove dead code
-- Improve readability
-- **GUARD: Do not refactor if not GREEN**
-
-### Step 10: Verify
-
-Run full test suite:
-- All tests must pass
-- If any fails, revert refactoring
-
-### Step 11: Review Step
-
-Spawn `@reviewer` to check:
-- Code quality, security, conventions
-- TDD discipline followed
-- Test coverage >= 80%
-- No missing or weak tests (flag as major finding)
-
-### Step 12: Update State
-
-Mark step complete via planning-state tool:
-```yaml
-steps_complete: [N, ...]
-last_action: "Step N complete via TDD: [behavior]"
-tdd:
-  stage: behavior  # Ready for next step
-```
-
-### Step 13: Loop or Complete
-
-If more steps pending:
-- Return to Step 3 (define behaviors for next step)
-
-If all steps complete:
-- Update phase status to "complete"
-- Update ROADMAP.md progress
-- Present completion summary
-
-## Wave-Based Execution
-
-WF-03 respects wave structure from PLAN.md:
-- Wave 1 steps execute first (with TDD cycle per step)
-- Wave 2 steps execute after Wave 1 completes
-- Wave 3 steps execute after Wave 2 completes
-- No intra-wave dependencies (parallel execution)
-
-## Guards Summary
-
-| Transition | Guard | If Violated |
-|-----------|-------|-------------|
-| behavior → red | Test written and fails | Block until test fails |
-| red → green | Test exists and fails | Block until test passes |
-| green → refactor | Tests are green | Block until green |
-| refactor → verify | All tests pass | Block until all pass |
-
-## Override Mechanism
-
-User can override with `/fd-new-feature --override`:
-- Every override is logged in `override_log`
-- Surface override in next review
-- Flag in deploy check
-
-## Error Handling
-
-D-03: Fail fast with clear error
-- If guard check fails: abort with clear error and remediation
-- If @coder fails: report failure, offer retry or skip
-- If @reviewer finds critical issues: return to Step 7 for fixes
-- No partial state saved on error
-
-## State Updates
-
-STATE.md updates after each step:
-```yaml
-steps_complete: [1, 2]      # Added after step 2
-steps_pending: [3, 4, 5]   # Removed step 2
-last_action: "Step 2 TDD complete: [behavior] (RED→GREEN→REFACTOR)"
-tdd:
-  stage: behavior
-  cycle: 2
-  behaviors_completed: 2
-```
-
-Full phase completion:
-```yaml
-status: complete
-last_action: "Phase N TDD complete — all steps finished"
-tdd:
-  stage: complete
-  cycles_used: N
-  behaviors_completed: M
-```

package/src/workflows/execute-phase.md

@@ -1,145 +0,0 @@
----
-name: execute-phase
-description: "Orchestrates /execute-phase [N] — delegates to orchestrator with checkpoint protocol"
-triggers:
-  - /execute-phase
-steps:
-  - name: verify_prerequisites
-    agent: "@orchestrator"
-    action: Check .planning/, .codebase/, plan_confirmed flag
-  - name: load_context
-    agent: "@orchestrator"
-    action: Load PLAN.md, STATE.md, PROJECT.md
-  - name: execute_tasks
-    agent: "@orchestrator"
-    action: Delegate each task to appropriate specialist (@coder, @tester, etc.)
-  - name: checkpoint_protocol
-    agent: "@orchestrator"
-    action: After each task, checkpoint state via planning-state tool
-  - name: present_results
-    agent: "@orchestrator"
-    action: Present execution summary
-  - name: update_state
-    agent: "@orchestrator"
-    action: Mark phase complete in STATE.md and ROADMAP.md
----
-
-# Execute Phase Workflow
-
-## Purpose
-
-Execute `/execute-phase [N]` to implement a phase plan using the orchestrator agent.
-
-## Prerequisites
-
-Before executing, verify:
-1. `.planning/` exists
-2. `.codebase/` exists
-3. `.planning/phases/phase-N/PLAN.md` exists and is confirmed
-
-## Process
-
-### Step 1: Verify Prerequisites
-
-Guard check:
-- `.planning/` directory must exist
-- `.codebase/` directory must exist
-- `STATE.md` has `plan_confirmed: true`
-- `PLAN.md` exists in `.planning/phases/phase-N/`
-
-If any check fails, abort with clear error and remediation steps.
-
-### Step 2: Load Context
-
-Read into execution context:
-- `.planning/PROJECT.md` (project goals and tech stack)
-- `.planning/STATE.md` (current phase and progress)
-- `.planning/phases/phase-N/PLAN.md` (implementation plan)
-- `.codebase/ARCHITECTURE.md` (if exists)
-- `.codebase/CONVENTIONS.md` (if exists)
-
-### Step 3: Execute Tasks
-
-Orchestrator delegates each task to appropriate specialist agents:
-- @coder for implementation
-- @tester for tests
-- @researcher for research tasks
-- etc.
-
-Each task:
-1. Execute via delegated agent
-2. Run verification tests for each task
-3. Commit atomically with message: `feat(phase-N): task description`
-4. Handle deviations (document, pause for approval if checkpoint)
-
-### Step 4: Checkpoint Protocol
-
-After each task:
-- Call `planning-state.update_planning_state()` with current progress
-- Update `steps_complete`, `last_action`, `next_action`
-- Append to session history (never overwrite)
-
-If session interrupted:
-- User can resume with `/resume`
-- Orchestrator will pick up from last checkpoint
-
-### Step 5: Present Results
-
-On completion, present:
-```
-## Phase [N] Execution Complete
-
-**Executed:** [date]
-**Tasks:** [N] completed
-**Duration:** [time]
-
-### What Was Built
-[Summary of deliverables]
-
-### Key Decisions
-- [D-XX]: [decision made during execution]
-
-### Deviations
-- [Any deviations from original plan]
-
-### Verification
-- [x] Criterion 1
-- [x] Criterion 2
-```
-
-### Step 6: Update State
-
-Update STATE.md:
-- Set `status: complete` for current phase
-- Update `last_action` to "Phase N complete"
-- Append to session history
-
-Update ROADMAP.md:
-- Mark phase N as "complete"
-
-## Agent Configuration
-
-| Agent | Model | Purpose |
-|-------|-------|---------|
-| orchestrator | Sonnet 4.6 | Coordinates plan execution via delegation |
-
-## Output Files
-
-- `.planning/phases/phase-N/SUMMARY.md` — execution summary
-- `.planning/phases/phase-N/RESULT.md` — final outcome (legacy)
-- STATE.md — updated with phase completion
-
-## Deviation Handling
-
-If implementation requires deviating from plan:
-1. Document the deviation in SUMMARY.md
-2. If at checkpoint: pause and get user approval
-3. If minor: continue and document
-4. Update PLAN.md with adjusted approach
-
-## Error Handling
-
-- If task fails: stop at checkpoint, preserve state
-- User can run `/fix-bug` or manually fix
-- Resume picks up from last successful checkpoint
-- Never leave partial state on error

package/src/workflows/fix-bug-flow.md

@@ -1,210 +0,0 @@
----
-name: fix-bug-flow
-description: "TDD-enforced bug fix: reproduce → isolate → RED (failing regression test) → GREEN (minimum fix) → REFACTOR → verify"
-triggers:
-  - /fix-bug
-steps:
-  - name: load_context
-    agent: "@orchestrator"
-    action: Read STATE.md, ARCHITECTURE.md, CONVENTIONS.md; Initialize TDD state (stage=behavior)
-  - name: define_behaviors
-    agent: "@orchestrator"
-    action: "Generate behavior checklist: what behaviors does this bug break? List acceptance cases."
-  - name: reproduce
-    agent: "@debug-specialist"
-    action: Reproduce the bug with minimal case; document inputs and expected vs actual
-  - name: isolate
-    agent: "@researcher"
-    action: Researcher investigates root cause; traces stack, reads related code
-  - name: write_failing_test
-    agent: "@tester"
-    action: "TDD RED: Write a failing regression test that reproduces the bug. Test MUST fail before proceeding."
-  - name: confirm_red
-    agent: "@tester"
-    action: "Run failing test — confirm it fails for the expected reason. Record RED state. Do NOT proceed until test fails."
-  - name: implement_fix
-    agent: "@coder"
-    action: "TDD GREEN: Implement minimum code change to make the failing test pass. No over-engineering."
-  - name: confirm_green
-    agent: "@tester"
-    action: "Run regression test — confirm it passes. Record GREEN state. Do NOT proceed until test passes."
-  - name: refactor
-    agent: "@coder"
-    action: "TDD REFACTOR: Clean up implementation while preserving passing tests. Only if tests are GREEN."
-  - name: verify_refactor
-    agent: "@tester"
-    action: "Run full test suite — confirm all tests pass after refactoring."
-  - name: review
-    agent: "@reviewer"
-    action: "Reviewer checks: fix is correct, no regressions, TDD discipline followed, no missing tests."
-  - name: update_state
-    agent: "@orchestrator"
-    action: "Update STATE.md: record bug, fix, test name, TDD stage=complete, regression test link"
----
-
-# Fix Bug Flow (TDD-Enforced)
-
-## Purpose
-
-Fix a reported bug following strict Red-Green-Refactor TDD cycle with mandatory regression test.
-
-## Prerequisites
-
-- `.planning/` initialized
-- Bug description or reproduction steps available
-
-## TDD Cycle
-
-The workflow enforces the TDD cycle with guards at each transition:
-
-```
-BEHAVIOR → RED → GREEN → REFACTOR → complete
-   ↑______________|         |
-   (loop if needed)         |
-                     Only if GREEN
-```
-
-## Step Definitions
-
-### Step 1: Load Context
-
-Read:
-- `.planning/STATE.md` — current phase, TDD state
-- `.codebase/ARCHITECTURE.md` — system structure
-- `.codebase/CONVENTIONS.md` — coding standards
-
-Initialize TDD state:
-```yaml
-tdd:
-  stage: behavior
-  cycle: 1
-  behaviors: []
-  regression_test_links: []
-```
-
-### Step 2: Define Behaviors
-
-Spawn `@orchestrator` to generate a behavior checklist:
-- What behaviors does this bug break?
-- What are the acceptance cases for "fixed"?
-- What edge cases should be tested?
-
-Store behaviors in TDD state.
-
-### Step 3: Reproduce
-
-Identify minimal reproduction:
-- What inputs trigger the bug?
-- What is expected behavior?
-- What is actual behavior?
-
-Document in comment or issue before touching code.
-
-### Step 4: Isolate Root Cause
-
-Spawn `@researcher` to investigate:
-- Trace the execution path
-- Read stack trace completely
-- Check recent changes: `git log --oneline -20 -- <file>`
-- Identify root cause (not symptom)
-
-### Step 5: Write Failing Test (RED)
-
-Spawn `@tester` to write regression test:
-- **Test MUST fail on current code** (this is the RED phase)
-- Named: `test('should <expected> when <condition>')`
-- Tests the bug scenario exactly
-- Use AAA pattern (Arrange-Act-Assert)
-
-### Step 6: Confirm RED
-
-Run the failing test:
-- Confirm it fails for the expected reason
-- **GUARD: Do NOT proceed to Step 7 until test fails**
-- If test passes unexpectedly, the test is not correctly reproducing the bug
-
-### Step 7: Implement Fix (GREEN)
-
-Spawn `@coder` to implement fix:
-- Fix the root cause identified in Step 4
-- **Minimum code change** that makes regression test pass
-- Do NOT add unrelated functionality
-- Do NOT over-engineer
-
-### Step 8: Confirm GREEN
-
-Run regression test:
-- **GUARD: Do NOT proceed to Step 9 until test passes**
-- If test fails, the fix is incomplete — return to Step 7
-
-### Step 9: Refactor (REFACTOR)
-
-Only if tests are GREEN:
-- Clean up implementation
-- Remove dead code introduced during green phase
-- Improve readability without changing behavior
-- **GUARD: Do not refactor if tests are not green**
-
-### Step 10: Verify Refactor
-
-Run full test suite:
-- All tests must pass
-- If any test fails, revert refactoring and return to Step 9
-
-### Step 11: Review
-
-Spawn `@reviewer` to check:
-- Fix is correct and complete
-- No regressions introduced
-- TDD discipline followed (RED before GREEN, minimum impl)
-- Missing tests are flagged as major findings
-- No suspicious test omissions
-
-### Step 12: Update State
-
-Update STATE.md:
-- Record bug description and root cause
-- Record fix applied (file:line)
-- Record regression test name and path
-- Update TDD stage to "complete"
-- Update `last_action` to "Bug fixed: [description]"
-
-## Error Handling
-
-- **GUARD VIOLATION**: If coder attempts to skip RED or GREEN phase, block and return to correct phase
-- **Override mechanism**: User can override with `/fd-fix-bug --override` but every override is logged in `override_log`
-- If root cause unclear: spawn `@debug-specialist` for deeper analysis
-- If fix breaks tests: revert, reassess root cause, never suppress error
-
-## Override Protocol
-
-If user requests bypass of TDD stages:
-1. Log the override: `logTDDOverride(dir, stage, reason, override_by="user")`
-2. Surface override in next review check
-3. Flag in deploy check as "TDD override used"
-
-## Output
-
-```
-## Bug Fix Complete (TDD-Enforced)
-
-**Bug:** [description]
-**Root cause:** [what caused it]
-**Behaviors tested:** [N behaviors]
-**TDD Stage:** complete
-**Cycle:** [N cycles used]
-
-**Regression test:** [test name] @ [path]
-**Test result:** ✅ PASS
-
-**Override used:** [yes/no]
-```
-
-## Guards Summary
-
-| Transition | Guard | If Violated |
-|-----------|-------|-------------|
-| behavior → red | Test written and fails | Block until test fails |
-| red → green | Test exists and fails | Block until test passes |
-| green → refactor | Tests are green | Block until green |
-| refactor → complete | All tests pass | Block until all pass |

package/src/workflows/map-codebase-flow.md

@@ -1,92 +0,0 @@
----
-name: map-codebase-flow
-description: "Orchestrates codebase mapping (parallel mappers → wait for all → synthesize → write .codebase/ docs)"
-triggers:
-  - /map-codebase
-steps:
-  - name: check_existing
-    agent: "@orchestrator"
-    priority: first
-    action: Check if .codebase/ already exists; warn and require confirmation if present
-  - name: initialize_worktrees
-    agent: "@orchestrator"
-    action: Create individual worktrees for each mapper agent (one per doc: STACK, ARCHITECTURE, STRUCTURE, CONVENTIONS, TESTING, CONCERNS)
-  - name: invoke_mappers
-    agent: "@mapper"
-    action: Spawn 6 @mapper agents in parallel, each writing to its assigned doc file
-  - name: wait_for_mappers
-    agent: "@orchestrator"
-    action: Wait for all mapper agents to complete
-  - name: cleanup_worktrees
-    agent: "@orchestrator"
-    action: Remove worktrees after all mappers complete (success or error)
-  - name: verify_output
-    agent: "@orchestrator"
-    action: Verify all 6 .codebase/ doc files exist and contain non-empty content
----
-
-# Map Codebase Flow
-
-## Purpose
-
-Maps an existing codebase to documentation via parallel analysis. Produces STACK.md, ARCHITECTURE.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md in `.codebase/`.
-
-## Process
-
-### Step 1: Check Existing
-
-If `.codebase/` directory already exists:
-```
-Warning: .codebase/ already exists. Running /map-codebase will overwrite existing docs.
-Continue? (y/n)
-```
-If user declines, abort. If user confirms, proceed.
-
-### Step 2: Initialize Worktrees
-
-D-04: Each mapper runs in its own isolated worktree to prevent conflicts.
-Create worktrees:
-- `flowdeck-mapper-stack`
-- `flowdeck-mapper-arch`
-- `flowdeck-mapper-structure`
-- `flowdeck-mapper-conventions`
-- `flowdeck-mapper-testing`
-- `flowdeck-mapper-concerns`
-
-### Step 3: Invoke Mappers
-
-Spawn 6 @mapper agents in parallel:
-- @mapper → STACK.md (tech stack, dependencies, versions)
-- @mapper → ARCHITECTURE.md (system design, components, data flow)
-- @mapper → STRUCTURE.md (file organization, directory layout)
-- @mapper → CONVENTIONS.md (coding standards, naming, patterns)
-- @mapper → TESTING.md (test strategy, coverage, frameworks)
-- @mapper → CONCERNS.md (known issues, technical debt, risks)
-
-Each mapper:
-- Reads source files directly (no guessing)
-- Outputs factual analysis only
-- Writes to assigned .codebase/ doc file
-
-### Step 4: Wait for Completion
-
-Wait for all 6 mapper agents to complete. If any fails:
-- Log the failure
-- Continue with remaining mappers
-- Report which docs were not generated
-
-### Step 5: Cleanup
-
-Remove all worktrees regardless of outcome (D-04: cleanup happens after all agents complete).
-
-### Step 6: Verify
-
-Check that all 6 .codebase/ doc files exist and contain non-empty content.
-If any are missing or empty, report which ones need regeneration.
-
-## Error Handling
-
-D-03: Fail fast with clear error
-- If .codebase/ check fails: show clear error with remediation
-- If worktree creation fails: report which worktree failed
-- Do NOT save partial state on error