@dv.nghiem/flowdeck 0.3.1 → 0.3.3

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

package/src/commands/fd-verify.md

@@ -0,0 +1,126 @@
+---
+description: Verify feature completion — run full test suite, reviewer, and deploy check against the current phase
+argument-hint: [--phase=N] [--env=staging|production]
+---
+
+# Verify
+
+Run the full verification pipeline for the current feature: tests, code review, and deploy check.
+
+**Input:** $ARGUMENTS — optional `--phase=N` to target a specific phase, `--env` for deploy check environment
+
+## Pre-flight
+
+1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
+2. Read current phase N from STATE.md.
+3. Confirm `steps_complete` in STATE.md is non-empty — if empty, warn: "No steps completed yet. Run /fd-execute first."
+
+## Process
+
+### Step 1: Gather Scope
+
+Collect files changed in the current feature:
+```bash
+git diff --name-only HEAD
+```
+
+If no changed files, use all files in the current phase directory as scope.
+
+### Step 2: Run Checks in Parallel
+
+Launch all four checks simultaneously:
+
+**Check A: Full Test Suite (@tester)**
+```bash
+npm test
+```
+All tests must pass. No failures, no unexplained skips.
+
+**Check B: Code Review (@reviewer)**
+Review all changed files:
+- Security: secrets, injection vulnerabilities, auth gaps
+- Quality: critical bugs, missing error handling, TDD discipline
+- Conventions: naming, patterns, import style
+- Test coverage >= 80% for changed files — flag as HIGH if below
+
+**Check C: Security Scan (@security-auditor)**
+- No hardcoded secrets
+- Input validation at trust boundaries
+- Auth/authz on all protected routes
+- No CRITICAL or HIGH vulnerabilities
+
+**Check D: Deploy Check**
+Run pre-deployment suite:
+```bash
+npm audit --audit-level=high
+npm run build
+```
+No HIGH/CRITICAL CVEs. Build must succeed.
+
+### Step 3: Aggregate Results
+
+Present consolidated report:
+
+```
+════════════════════════════════════════════════════
+VERIFICATION: Phase <N> — <feature name>
+════════════════════════════════════════════════════
+
+| Check         | Status           | Details              |
+|---------------|------------------|----------------------|
+| Tests         | ✅ PASS / ❌ FAIL | N/N passed           |
+| Code Review   | ✅ PASS / ❌ FAIL | [findings summary]   |
+| Security      | ✅ PASS / ❌ FAIL | [findings summary]   |
+| CVE Audit     | ✅ PASS / ❌ FAIL | [vulnerabilities]    |
+| Build         | ✅ PASS / ❌ FAIL | [errors]             |
+
+────────────────────────────────────────────────────
+Verdict: ✅ VERIFIED | ❌ NOT VERIFIED
+════════════════════════════════════════════════════
+```
+
+### Step 4: Go / No-Go
+
+**✅ VERIFIED** — all checks pass:
+- Update STATE.md: set `status` to `verified`, `last_action` to `"Phase N verified"`
+- Report next steps (deploy, increment phase, etc.)
+
+**❌ NOT VERIFIED** — one or more checks failed:
+```
+Verdict: NOT VERIFIED
+
+Required fixes:
+- [ ] [fix 1]
+- [ ] [fix 2]
+
+Run /fd-verify again after fixing.
+```
+Do NOT update STATE.md to verified status.
+
+## No-Go Conditions (automatic)
+
+Any of these → automatic NOT VERIFIED:
+- Test failures
+- CRITICAL security vulnerability
+- HIGH/CRITICAL CVE unpatched
+- Build error
+- Code review CRITICAL finding
+
+## State Update on Success
+
+```yaml
+status: verified
+last_action: "Phase N verified — all checks passed"
+verified_at: "<timestamp>"
+```
+
+## Error Handling
+
+- If `.planning/` not found: error "Run /fd-new-project first."
+- If STATE.md not found: error "Project not initialized."
+- If test runner not found: error with remediation (e.g., "No test script in package.json")
+- No partial state update on error.
+
+## Completion
+
+Report: verification result, check statuses, any required fixes, and suggested next step.

package/src/rules/common/agent-orchestration.md

@@ -15,7 +15,7 @@ FlowDeck provides 23 specialist agents. Each has a specific role. Using the righ
 | `@discusser` | Extract requirements via Q&A | Starting a new feature or phase |
 | `@doc-updater` | Update docs after code changes | After implementation completes |
 | `@plan-checker` | Review PLAN.md before execution | Before executing any plan |
-| `@mapper` | Map codebase to .codebase/ docs | Running /map-codebase |
+| `@mapper` | Map codebase to .codebase/ docs | Running /fd-map-codebase |
 | `@orchestrator` | Coordinate multi-agent execution | Managing a full feature delivery |
 | `@parallel-coordinator` | Run parallel agent workstreams | When tasks can run simultaneously |
 | `@performance-optimizer` | Profile and fix performance issues | When app is slow or before release |
@@ -76,9 +76,9 @@ discuss → plan → execute → review
 
 | Phase | Agent | Command |
 |-------|-------|---------|
-| discuss | `@discusser` | `/discuss` |
-| plan | `@planner` → `@plan-checker` | `/plan` |
-| execute | `@orchestrator` → `@coder`, `@tester`, etc. | `/new-feature` |
-| review | `@reviewer` + `@security-auditor` | `/review-code` |
+| discuss | `@discusser` | `/fd-discuss` |
+| plan | `@planner` → `@plan-checker` | `/fd-plan` |
+| execute | `@orchestrator` → `@coder`, `@tester`, etc. | `/fd-new-feature` |
+| review | `@reviewer` + `@security-auditor` | `/fd-review-code` |
 
 Do not skip phases. The orchestrator enforces phase gating automatically.

package/src/rules/common/coding-style.md

@@ -2,6 +2,23 @@
 
 Language-agnostic coding conventions followed by all FlowDeck agents.
 
+## Core Principles
+
+| # | Rule | Description |
+|---|------|-------------|
+| 1 | **No Redundant Code** | No redundant arguments, methods, or attributes. Each piece of code must serve a purpose. |
+| 2 | **Simplicity** | Code should be simple and easy to understand. Prefer clarity over cleverness. |
+| 3 | **Clear Commands** | Code should have clear, explicit commands. No ambiguity in intent. |
+| 4 | **Extensibility** | Code must be easily extendable. Design for growth, not just current needs. |
+| 5 | **Documentation** | Code must have clear documentation at the beginning of every file. |
+| 6 | **Information Security** | Comply with information security best practices. No secrets, no injections, no XSS. |
+| 7 | **Memory Optimization** | Optimize memory usage to the minimum possible. Avoid unnecessary allocations. |
+| 8 | **Speed** | Process speed should be as fast as possible. Prefer efficient algorithms and data structures. |
+| 9 | **Single Responsibility** | Each function/class does one thing well. Easier to test, debug, and extend. |
+| 10 | **Testability** | Code should be easy to test in isolation. Avoid hidden dependencies and global state. |
+| 11 | **Consistency** | Follow existing patterns in the codebase. Consistency over personal preference. |
+| 12 | **Resource Cleanup** | Always release resources (connections, file handles, timers). Use try-finally or defer. |
+
 ## Immutability
 
 Always create new objects and arrays. Never mutate parameters.