@dv.nghiem/flowdeck 0.3.2 → 0.3.4

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.
 
 ---
 
@@ -38,34 +38,35 @@ 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 |
 | `/fd-deploy-check` | Pre-deploy safety check | @tester, @security-auditor, @reviewer |
-| `/fd-progress` | View project progress | — |
+| `/fd-status` | View project progress | — |
 | `/fd-checkpoint` | Save a session checkpoint | — |
 | `/fd-resume` | Resume from checkpoint | — |
 | `/fd-multi-repo` | Multi-repo orchestration | @multi-repo-coordinator, @architect |
+| `/fd-translate-intent` | Convert vague requests to ranked implementation options | @architect, @researcher |
+| `/fd-suggest` | Suggest high-value feature opportunities from codebase signals | @researcher, @architect |
+| `/fd-quick` | Fast focused task execution | @coder or selected specialist |
+| `/fd-reflect` | Post-session reflection and skill capture | @auto-learner |
+| `/fd-doctor` | Installation and environment diagnostics | @orchestrator |
 
 ---
 
 ## Analysis Commands
 
-These umbrella commands combine multiple analysis modules:
+Analysis workflows are currently exposed through:
 
 | Command | Purpose | Flags |
 |---------|---------|-------|
-| `/fd-analyze-change` | Combined impact analysis | `--impact`, `--blast-radius`, `--regression`, `--test-gap`, `--volatility` |
-| `/fd-guarded-edit` | Edit gate decision | auto/confirm/review/block |
-| `/fd-evaluate-risk` | Standalone risk assessment | — |
 | `/fd-translate-intent` | Intent to concrete options | `assumptions`, `recommended_option` |
+| `/fd-suggest` | Suggest feature opportunities from volatility, failures, and decisions | `--category`, `--limit` |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,9 @@
     "postinstall": "node postinstall.mjs",
     "prepublishOnly": "bun run clean && bun run build",
     "test": "bun test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "validate:skills": "node scripts/validate-skills.mjs",
+    "validate:docs": "node scripts/validate-docs.mjs"
   },
   "keywords": ["opencode", "plugin", "ai", "workflow", "planning"],
   "author": "DVNghiem",

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

package/src/commands/fd-new-feature.md

@@ -1,192 +1,79 @@
 ---
-description: Execute feature implementation — guard check, parallel coder + researcher, reviewer, tester, STATE.md update
-argument-hint: [feature description]
+description: Start a new feature — initialize feature context in .planning/, capture description, and guide through discuss → plan → execute → verify
+argument-hint: [feature name or description]
 ---
 
 # New Feature
 
-Implement a new feature using the full FlowDeck agent pipeline.
+Initialize a new feature and guide through the full FlowDeck feature workflow.
 
-**Input:** $ARGUMENTS — description of the feature to implement
+**Input:** $ARGUMENTS — name or short description of the feature to build
 
 ## 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
-```
+2. Read `.planning/STATE.md` to determine the current phase number N.
+3. Create `.planning/phases/phase-<N>/` directory if it does not exist.
 
 ## 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)
+### Step 1: Capture Feature Description
 
-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)
+If $ARGUMENTS is empty, ask the user:
+> "What feature do you want to build? Describe it in one or two sentences."
 
-### Step 6: Confirm RED
+Use the provided description as the feature name/summary.
 
-Run failing tests:
-- **GUARD: Do NOT proceed to Step 7 until tests fail**
-- If tests pass unexpectedly, tests don't correctly describe behavior
+### Step 2: Initialize Feature Context
 
-### Step 7: Implement Minimum (GREEN)
+Create `.planning/phases/phase-<N>/FEATURE.md`:
 
-Spawn `@coder` to implement:
-- **Minimum code** to make failing tests pass
-- No speculative features
-- No over-engineering
+```markdown
+# Feature: $ARGUMENTS
 
-### Step 8: Confirm GREEN
+**Phase:** <N>
+**Created:** <current timestamp>
+**Status:** defined
 
-Run tests:
-- **GUARD: Do NOT proceed to Step 9 until tests pass**
-- If tests fail, return to Step 7
+## Description
 
-### Step 9: Refactor (REFACTOR)
+$ARGUMENTS
 
-Only if GREEN:
-- Clean up code for this step
-- Remove dead code
-- Improve readability
-- **GUARD: Do not refactor if not GREEN**
+## Acceptance Criteria
 
-### Step 10: Verify
+(to be defined in /fd-discuss)
 
-Run full test suite:
-- All tests must pass
-- If any fails, revert refactoring
+## Out of Scope
 
-### 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
+(to be defined in /fd-discuss)
 ```
 
-### 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)
+### Step 3: Update STATE.md
 
-## Guards Summary
+Update the current phase entry in STATE.md:
+- Set `feature` to the feature name/description
+- Set `status` to `defined`
+- Set `last_action` to `"Feature defined: $ARGUMENTS"`
 
-| 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 |
+### Step 4: Present Feature Workflow
 
-## Override Mechanism
+Report what was created and present the next steps clearly:
 
-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
+✅ Feature initialized: $ARGUMENTS
+   Phase: <N>
+   File: .planning/phases/phase-<N>/FEATURE.md
+
+Next steps (in order):
+  1. /fd-discuss          — capture requirements, scope, and acceptance criteria
+  2. /fd-plan             — create implementation plan from discussion decisions
+  3. /fd-execute          — run TDD pipeline to implement the plan
+  4. /fd-verify           — run full test + review + deploy-check pipeline
 ```
 
-## Completion
+## Error Handling
+
+- If `.planning/` not found: error "Run /fd-new-project first."
+- If STATE.md not found: error "Project not initialized. Run /fd-new-project first."
+- No partial state saved on error.
 
-Report: feature implemented, tests status, reviewer findings, files changed.

package/src/commands/fd-new-project.md

@@ -111,6 +111,5 @@ confirmed_at: none
 ```
 
 5. Report success with the list of files created and next steps:
-   - Run `/fd-discuss` to capture project decisions
-   - Run `/fd-plan` to create an implementation plan
+   - Run `/fd-new-feature` to define your first feature
    - Edit `.planning/config.json` directly to change settings

package/src/commands/fd-plan.md

@@ -99,4 +99,4 @@ D-03: Fail fast with clear error
 
 ## Completion
 
-Report: plan saved, decisions count, file path, next step: run `/fd-new-feature` or `/fd-fix-bug`.
+Report: plan saved, decisions count, file path, next step: run `/fd-execute` or `/fd-fix-bug`.

package/src/commands/fd-suggest.md

@@ -0,0 +1,84 @@
+---
+description: Analyze codebase and suggest new features with implementation instructions
+argument-hint: [--category=TYPE] [--limit=N]
+---
+
+# Suggest Features
+
+Analyze the codebase and generate actionable feature suggestions with implementation guidance.
+
+**Input:** $ARGUMENTS (optional --category for focus area: tools|hooks|agents|skills, --limit for number of suggestions, default 5)
+
+## Process
+
+### Step 1: Detect Environment
+
+Check if `.planning/` directory exists:
+- If it exists: Use current project context, analyze within existing architecture
+- If not: This is a standalone analysis, scan the codebase root
+
+### Step 2: Run Analysis Tools
+
+Execute tools to gather insight data:
+
+1. **Volatility Map** — `volatility-map` tool to find high-change areas (instability signals)
+2. **Decision Trace** — `decision-trace` tool to find incomplete orTODO decisions
+3. **Failure Replay** — `failure-replay` tool to find recurring failure patterns
+4. **Codebase State** — `codebase-state` tool to get overall project structure
+
+### Step 3: Scan for Gaps
+
+Analyze the codebase structure to identify gaps:
+
+- **Tools** — Are all tool categories covered? (planning, state, execution, analysis)
+- **Hooks** — Are lifecycle hooks comprehensive?
+- **Agents** — Are agent types sufficient for common tasks?
+- **Skills** — Are there skill coverage gaps for major frameworks?
+
+### Step 4: Generate Suggestions
+
+For each valid suggestion (up to --limit), produce:
+
+```
+## Suggestion N: [Feature Name]
+
+**Category:** tools|hooks|agents|skills  
+**Impact:** HIGH|MEDIUM|LOW  
+**Complexity:** HIGH|MEDIUM|LOW  
+
+### Problem Statement
+[What issue this solves, with evidence from analysis]
+
+### Proposed Solution
+[Brief description of the approach]
+
+### Implementation Steps
+1. [Step with TDD approach - write test first]
+2. [Step referencing existing patterns]
+3. [Step with integration points]
+
+### Files Affected
+- `src/tools/xxx.ts` or `src/hooks/xxx.ts` or `src/agents/xxx.ts`
+- `src/skills/xxx/SKILL.md` (if applicable)
+- `docs/xxx.md` (if applicable)
+
+### Integration
+- How this connects to existing FlowDeck tools/agents
+- Any new dependencies or configuration needed
+```
+
+### Step 5: Rank and Present
+
+Sort suggestions by impact/complexity ratio (highest first).
+
+Present:
+```
+# Feature Suggestions
+
+Found N suggestions ranked by impact:
+
+[Suggestions 1-N]
+
+---
+Run /fd-discuss [topic] to start a discussion on any suggestion.
+```