@dv.nghiem/flowdeck 0.3.1 → 0.3.3

package/docs/commands.md

@@ -7,18 +7,20 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 | Command | Arguments | Description |
 |---------|-----------|-------------|
 | `/fd-new-project` | `[project-name]` | Initialize project with planning structure and default config |
+| `/fd-new-feature` | `[feature-description]` | Define a new feature and initialize feature context |
 | `/fd-discuss` | `[topic]` | Structured Q&A to capture decisions for a phase |
 | `/fd-plan` | `[--phase=N]` | Generate detailed implementation plan from decisions |
-| `/fd-new-feature` | `[feature-description]` | Full feature implementation with parallel agents |
+| `/fd-execute` | `[--phase=N] [--override]` | Implement feature with TDD pipeline and parallel agents |
+| `/fd-verify` | `[--phase=N] [--env=staging\|production]` | Verify feature completion: tests, review, security, deploy check |
 | `/fd-fix-bug` | `[bug-description]` | Debug, fix, and verify bug with regression test |
 | `/fd-deploy-check` | `[--check=deploy,review,analysis]` | Pre-deploy checks, code review, or pre-change analysis |
-| `/fd-status` | `[--roadmap | --workspace | --phase=N]` | Combined status, roadmap, and workspace view |
+| `/fd-status` | `[--roadmap \| --workspace \| --phase=N]` | Combined status, roadmap, and workspace view |
 | `/fd-resume` | `[--yes]` | Reload STATE.md and PLAN.md to continue interrupted session |
 | `/fd-checkpoint` | — | Persist current state to STATE.md |
 | `/fd-reflect` | `[--mode=reflect,learn]` | Post-session reflection or capture skill from session |
 | `/fd-map-codebase` | `[--incremental]` | Map codebase into structured `.codebase/` files |
 | `/fd-write-docs` | `[--scope=path]` | Explore APIs and generate documentation |
-| `/fd-multi-repo` | `[list | add <path> [name] | remove <name> | status]` | Multi-repo orchestration |
+| `/fd-multi-repo` | `[list \| add <path> [name] \| remove <name> \| status]` | Multi-repo orchestration |
 | `/fd-translate-intent` | `[vague intent]` | Convert vague request into ranked implementation options |
 | `/fd-ask` | `[question]` | Route question to specialist agent (architect, security, etc.) |
 | `/fd-quick` | `[task description]` | Quick focused task with automatic agent selection |
@@ -47,12 +49,38 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 ```
 
 **What Next?**
-1. Run `/fd-discuss` to begin structured discovery
+1. Run `/fd-new-feature` to define your first feature
 2. Run `/fd-map-codebase` if this is an existing codebase
 3. Edit `.planning/config.json` directly to change settings
 
 ---
 
+## /fd-new-feature
+
+**Description:** Define a new feature and initialize feature context. This is the first step of the feature workflow after project setup.
+
+**Arguments:**
+- `[feature-description]` — name or short description of the feature
+
+**What it does:**
+1. Reads `.planning/STATE.md` to determine current phase
+2. Creates `.planning/phases/phase-N/FEATURE.md` with feature context
+3. Updates STATE.md with feature definition
+4. Displays the workflow steps ahead: discuss → plan → execute → verify
+
+**Example:**
+```
+/fd-new-feature user authentication
+```
+
+**What Next?**
+1. Run `/fd-discuss` to capture requirements
+2. Run `/fd-plan` to create implementation plan
+3. Run `/fd-execute` to implement with TDD
+4. Run `/fd-verify` to confirm all checks pass
+
+---
+
 ## /fd-discuss
 
 **Description:** Opens a structured Q&A session to capture decisions for a phase. Saves decisions to `.planning/phases/phase-N/DISCUSS.md` with D-XX numbering.
@@ -61,14 +89,14 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 - `[topic]` — optional topic to focus the discussion
 
 **What it does:**
-1. Loads `.planning/PROJECT.md` and `.planning/STATE.md` for project context
+1. Loads `.planning/FEATURE.md` and `.planning/STATE.md` for context
 2. Invokes `@discusser` agent which asks targeted questions one at a time
 3. Records decisions with D-XX numbering (D-01, D-02, …)
 4. Saves to `.planning/phases/phase-N/DISCUSS.md`
 
 **Example:**
 ```
-/fd-discuss user authentication
+/fd-discuss
 ```
 
 **What Next?**
@@ -93,19 +121,84 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 
 **Example:**
 ```
+/fd-plan
 /fd-plan --phase=1
 ```
 
 **What Next?**
-1. Run `/fd-new-feature` to implement
+1. Run `/fd-execute` to implement the plan
 2. Run `/fd-plan --phase=2` for next phase
 
 ---
 
-## /fd-new-feature
+## /fd-execute
+
+**Description:** Implement the current phase's plan using TDD discipline with parallel agents. This is the execution step after planning is confirmed.
+
+**Arguments:**
+- `[--phase=N]` — target specific phase
+- `[--override]` — bypass guards and proceed anyway
+
+**What it does:**
+1. Reads `.planning/phases/phase-N/PLAN.md` for implementation steps
+2. For each step, enforces TDD cycle: BEHAVIOR → RED → GREEN → REFACTOR
+3. `@tester` writes failing tests first
+4. `@coder` implements minimum to pass
+5. `@reviewer` confirms quality
+6. Updates `STATE.md` with completed steps
+7. Waves execute in order, with parallel tasks within each wave
+
+**Example:**
+```
+/fd-execute
+/fd-execute --phase=1
+```
+
+**What Next?**
+1. Run `/fd-verify` to confirm all checks pass
+2. Commit changes and create pull request
+3. Run `/fd-checkpoint` to save session state
+
+---
+
+## /fd-verify
+
+**Description:** Verify feature completion with full test suite, code review, security scan, and deploy check.
+
+**Arguments:**
+- `[--phase=N]` — target specific phase
+- `[--env=staging|production]` — environment for deploy check (default: staging)
+
+**What it does:**
+1. Runs test suite — all tests must pass
+2. Runs code review — `@reviewer` checks quality, security, conventions
+3. Runs security scan — `@security-auditor` checks for vulnerabilities
+4. Runs deploy check — build verification, CVE audit, readiness
+5. Aggregates all findings into a verification report
+6. Updates STATE.md if all checks pass
+
+**Example:**
+```
+/fd-verify
+/fd-verify --phase=1 --env=production
+```
+
+**Verdict:**
+- ✅ **VERIFIED** — all checks pass, feature is ready
+- ❌ **NOT VERIFIED** — one or more checks failed; review report and fix issues
+
+**What Next?**
+1. If VERIFIED: merge changes, deploy, or move to next phase
+2. If NOT VERIFIED: fix issues and run `/fd-verify` again
+
+---
+
+## /fd-new-feature (old — now use /fd-execute)
 
 **Description:** Implements a new feature end-to-end using TDD discipline with parallel agents. Reads active PLAN.md for context.
 
+**DEPRECATED:** Use `/fd-execute` instead. The `/fd-new-feature` command is now the entry point for defining features (step 1 of 6).
+
 **Arguments:**
 - `[feature-description]` — plain-language description of the feature
 
@@ -118,7 +211,7 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 
 **Example:**
 ```
-/fd-new-feature "user authentication with JWT"
+/fd-execute "user authentication with JWT"
 ```
 
 ---

package/docs/quick-start.md

@@ -71,12 +71,28 @@ All subsequent agents read these files for context. Skip this step for brand-new
 
 ---
 
-## Step 4: Start a Discussion
+## Step 4: Define a New Feature
 
-Requirements gathering comes before planning. Run:
+Before discussing requirements, initialize the feature:
 
 ```
-/fd-discuss 1
+/fd-new-feature user authentication
+```
+
+`@orchestrator` creates `.planning/phases/phase-1/FEATURE.md` and updates `STATE.md`. This establishes the feature context and shows you the next steps in the workflow:
+1. /fd-discuss
+2. /fd-plan
+3. /fd-execute
+4. /fd-verify
+
+---
+
+## Step 5: Start a Discussion
+
+Requirements gathering comes next. Run:
+
+```
+/fd-discuss
 ```
 
 `@discusser` asks structured questions about your goals, constraints, and success criteria — one question at a time. Each answer is numbered and tracked as a decision (`D-01`, `D-02`, …).
@@ -90,17 +106,17 @@ When you finish answering, the decisions are saved to `.planning/phases/phase-1/
 
 ---
 
-## Step 5: Create an Implementation Plan
+## Step 6: Create an Implementation Plan
 
 With requirements captured, generate the plan:
 
 ```
-/fd-plan 1
+/fd-plan
 ```
 
 `@planner` reads `DISCUSS.md` and produces a wave-structured `PLAN.md` in `.planning/phases/phase-1/`. Then `@plan-checker` reviews it for quality — checking that task sizes are reasonable, success criteria are specific, and wave dependencies are correct.
 
-You are shown the plan and prompted for confirmation. **Type `CONFIRMED` to allow execution to proceed.** Review carefully before confirming:
+You are shown the plan and prompted for confirmation. **Type `CONFIRM` to allow execution to proceed.** Review carefully before confirming:
 
 - Are success criteria observable and specific?
 - Are individual tasks sized to 1–3 hours?
@@ -108,40 +124,45 @@ You are shown the plan and prompted for confirmation. **Type `CONFIRMED` to allo
 
 ---
 
-## Step 6: Execute a Feature
+## Step 7: Execute the Feature
 
 Once the plan is confirmed, start implementation:
 
 ```
-/fd-new-feature "user authentication with JWT"
+/fd-execute
 ```
 
-`@orchestrator` reads `STATE.md` and `PLAN.md`, then delegates work to specialist agents in wave order:
+`@orchestrator` reads `STATE.md` and `PLAN.md`, then delegates work to specialist agents in wave order via a TDD cycle (RED → GREEN → REFACTOR):
 
-1. **Wave 1** — `@architect` designs the component structure and API contracts
-2. **Wave 2** — `@coder` and `@researcher` implement in parallel (independent tasks)
-3. **Wave 3** — `@tester` writes and runs tests against the completed implementation
-4. **Wave 4** — `@reviewer` reviews the full changeset
+1. **Behavior** — Define acceptance cases from PLAN.md
+2. **RED** — Write failing tests covering each behavior
+3. **GREEN** — Implement minimum code to pass tests
+4. **REFACTOR** — Clean up code while tests remain green
+5. **Review** — `@reviewer` checks code quality and TDD discipline
 
-You see progress updates as each wave completes. Independent tasks within a wave run simultaneously via OpenCode's multi-agent capabilities.
+You see progress updates as each task completes. Independent tasks within a wave run simultaneously.
 
 ---
 
-## Step 7: Review the Code
+## Step 8: Verify Feature Completion
 
-After implementation, run the review phase against staged changes:
+After implementation, run the full verification pipeline:
 
 ```
-/fd-review-code staged
+/fd-verify
 ```
 
-`@reviewer`, `@security-auditor`, and `@tester` run in parallel. Their findings are aggregated into a single report ranked by severity: Critical → High → Medium → Pass.
+This runs four checks in parallel:
+- **Tests** — Full test suite must pass
+- **Code Review** — `@reviewer` checks quality, security, conventions
+- **Security Scan** — `@security-auditor` checks for vulnerabilities
+- **Deploy Check** — Build verification, CVE audit, readiness assessment
 
-Address any Critical or High findings before merging.
+If all checks pass, the phase is marked **VERIFIED**. If any check fails, the report shows what needs fixing.
 
 ---
 
-## Step 8: Save State
+## Step 9: Review the Results
 
 Before closing OpenCode, checkpoint your progress:
 
@@ -161,13 +182,13 @@ This writes the current execution state to `.planning/STATE.md`. To reload conte
 
 ## Tips
 
-> **Check status at any time** — `/fd-progress` prints the current state, active plan, and a summary of recent results without modifying anything.
+> **Check status at any time** — `/fd-status` prints the current state, active plan, and a summary of recent results without modifying anything.
 
 > **Context after a restart** — always run `/fd-resume` at the start of a new OpenCode session on a project that was previously active. Agents have no memory between sessions without it.
 
-> **Follow the "What Next?" prompt** — after each FlowDeck command completes, the orchestrating agent presents a set of suggested next steps. Reading these keeps you on the intended workflow path.
+> **Follow the workflow order** — the cycle `/fd-new-feature → /fd-discuss → /fd-plan → /fd-execute → /fd-verify` ensures requirements are captured before implementation and verification happens at the end.
 
-> **Skip steps for small tasks** — for a quick bug fix, you do not need to run `/fd-discuss` and `/fd-plan`. Use `/fd-fix-bug` directly and let `@debug-specialist` handle the full cycle.
+> **Skip to execute for small tasks** — for a quick bug fix, you do not need to run `/fd-discuss` and `/fd-plan`. Use `/fd-fix-bug` directly and let `@debug-specialist` handle the full cycle.
 
 ---
 

package/docs/workflows.md

@@ -15,20 +15,20 @@ FlowDeck commands are the single entry point for all operations. Each command em
 ```
 /fd-new-project
      ↓
- /fd-discuss  →  .planning/phases/phase-N/DISCUSS.md  (locked decisions)
+/fd-new-feature  →  .planning/phases/phase-N/FEATURE.md  (feature defined)
      ↓
- /fd-plan     →  .planning/phases/phase-N/PLAN.md     (confirmed plan)
+/fd-discuss      →  .planning/phases/phase-N/DISCUSS.md  (locked decisions)
      ↓
- /fd-new-feature  →  implemented, tested, reviewed code
+/fd-plan         →  .planning/phases/phase-N/PLAN.md     (confirmed plan)
      ↓
- /fd-review-code  →  review report (CRITICAL/HIGH/MEDIUM/PASS)
+/fd-execute      →  implemented, tested, reviewed code (via TDD)
      ↓
- /fd-deploy-check →  GO / NO-GO decision
+/fd-verify       →  verification report (tests, review, security, deploy check)
      ↓
- /fd-checkpoint   →  .planning/STATE.md saved
+/fd-checkpoint   →  .planning/STATE.md saved
 ```
 
-Each step gates the next. `/fd-plan` will not proceed without a confirmed `DISCUSS.md`. `/fd-new-feature` will not execute without a confirmed `PLAN.md`.
+Each step gates the next. `/fd-discuss` requires a defined feature. `/fd-plan` requires confirmed decisions from `DISCUSS.md`. `/fd-execute` requires a confirmed `PLAN.md`. `/fd-verify` confirms all checks pass before marking the feature as complete.
 
 ---
 
@@ -39,12 +39,14 @@ Each step gates the next. `/fd-plan` will not proceed without a confirmed `DISCU
 | `/fd-new-project` | Bootstrap a new project | @orchestrator |
 | `/fd-map-codebase` | Analyse and index the codebase | @mapper (×6 parallel) |
 | `/fd-settings` | Configure FlowDeck settings | @orchestrator |
+| `/fd-new-feature` | Initialize a new feature | @orchestrator |
 | `/fd-discuss` | Pre-planning discussion | @discusser |
 | `/fd-plan` | Generate a phase plan | @planner, @plan-checker |
 | `/fd-roadmap` | View / update project roadmap | @orchestrator |
 | `/fd-dashboard` | Visual progress dashboard | — |
 | `/fd-ask` | Smart agent dispatch | various |
-| `/fd-new-feature` | Implement a new feature | @coder, @tester, @reviewer |
+| `/fd-execute` | Implement feature via TDD | @orchestrator, @coder, @tester, @reviewer |
+| `/fd-verify` | Verify feature completion | @tester, @reviewer, @security-auditor |
 | `/fd-fix-bug` | Fix a bug with TDD | @debug-specialist, @tester, @coder |
 | `/fd-review-code` | Code review | @reviewer, @researcher, @tester |
 | `/fd-write-docs` | Generate documentation | @writer, @reviewer |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",

package/src/commands/fd-execute.md

@@ -0,0 +1,192 @@
+---
+description: Execute feature implementation from PLAN.md — TDD pipeline with coder, tester, reviewer, and STATE.md update
+argument-hint: [--phase=N] [--override]
+---
+
+# Execute
+
+Implement the current phase's plan using the full FlowDeck TDD agent pipeline.
+
+**Input:** $ARGUMENTS — optional `--phase=N` to target a specific phase, `--override` to bypass guards
+
+## Pre-flight
+
+1. Check `.planning/` exists — if not, error: "Run /fd-new-project first."
+2. Check `plan_confirmed: true` in STATE.md — if not, error: "Confirm plan first with /fd-plan."
+3. Read `.planning/phases/phase-<N>/PLAN.md` to get implementation steps.
+4. Read `.codebase/ARCHITECTURE.md` if it exists — pass as context.
+
+## TDD Cycle Per Step
+
+Each plan step follows the TDD cycle:
+
+```
+BEHAVIOR → RED → GREEN → REFACTOR → next step
+   ↑_________|        |
+   (loop if needed)  Only if GREEN
+```
+
+## Process
+
+### 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-execute --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
+```
+
+## Completion
+
+Report: feature implemented, tests status, reviewer findings, files changed. Suggest running `/fd-verify`.