@dv.nghiem/flowdeck 0.1.0

package/src/workflows/execute-flow.md

@@ -0,0 +1,233 @@
+---
+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

@@ -0,0 +1,142 @@
+---
+name: execute-phase
+description: "Orchestrates /execute-phase [N] — delegates to flowdeck-executor 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: delegate_to_executor
+    agent: "@flowdeck-executor"
+    action: Spawn flowdeck-executor agent to execute plan atomically
+  - name: checkpoint_protocol
+    agent: "@flowdeck-executor"
+    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 flowdeck-executor 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: Delegate to flowdeck-executor
+
+Spawn flowdeck-executor agent with full context.
+
+Agent will:
+1. Execute each task in the plan
+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)
+5. Create SUMMARY.md after all tasks complete
+
+### 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`
+- Executor 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 |
+|-------|-------|---------|
+| flowdeck-executor | Sonnet 4.6 | Executes plan with atomic commits |
+
+## 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

@@ -0,0 +1,210 @@
+---
+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

@@ -0,0 +1,92 @@
+---
+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