@dv.nghiem/flowdeck 0.3.8 → 0.4.0

package/docs/commands/fd-reflect.md

@@ -1,23 +1,91 @@
----
-description: Post-session reflection and skill capture — analyse artifacts, propose improvements, capture session patterns
-argument-hint: [--mode=reflect,learn]
----
+# /fd-reflect
 
-# Reflect
+**Purpose:** Post-session reflection and skill capture — analyze session artifacts, propose improvements to FlowDeck's knowledge base, and optionally capture reusable skills from patterns discovered during the session.
 
-Post-session reflection to analyse artifacts and propose improvements, or capture learnings as reusable skills.
+## Usage
 
-## Modes
+/fd-reflect [--mode=reflect,learn]
 
-### Reflect (default)
-Analyzes session artifacts, proposes skills/policies/workflow changes.
+## What Happens
 
-### Learn (`--mode=learn`)
-Captures a repeatable pattern as a reusable FlowDeck skill.
+### Reflect Mode (default)
+
+1. **Gather artifacts.** Call the `reflect` tool to collect session artifacts and generate reflection context.
+
+2. **Analyze the session.**
+   - Which tools were called most often? Any redundant calls?
+   - Which decisions were made? Do they reveal a repeatable pattern?
+   - Were there failures? What caused them?
+   - What knowledge was absent and had to be worked out from scratch?
+
+3. **Produce improvement proposals.**
+   - **New skill** → call `create-skill` to capture it in `src/skills/`
+   - **Policy** → propose a new entry in `.codebase/POLICIES.json` for user review
+   - **Workflow change** → note it clearly for user to decide
+
+4. **Execute skill creation** for any new skills identified.
+
+5. **Final report.** Provide:
+   - What was captured (new skills created)
+   - What requires human review (policy proposals, workflow changes)
+   - 3-5 bullet summary of the session's most impactful learnings
+
+### Learn Mode (`--mode=learn`)
+
+1. **Identify worth capturing.** Look for:
+   - Novel problems requiring non-obvious solutions
+   - Patterns that needed human guidance to resolve
+   - Workflows or sequences that would save time if remembered
+   - Pitfalls that were hit and corrected
+
+   If nothing significant was found, reply: "No new patterns to capture from this session." and stop.
+
+2. **Draft the skill.** Structure as:
+   - `## When to Activate` — concrete triggers (e.g., "when X file pattern exists", "when user asks about Y")
+   - `## Steps` — ordered, concrete steps to apply the skill
+   - `## Examples` — at least one short concrete example
+   - `## Pitfalls` — common mistakes to avoid
+
+3. **Choose a name.** Use `$ARGUMENTS` if provided as skill name; otherwise derive a kebab-case name from the pattern.
+
+4. **Write the skill** using the `create-skill` tool with:
+   - `name`: kebab-case identifier
+   - `description`: one sentence summary
+   - `content`: full Markdown body
+   - `tags`: 2-4 relevant tags
+
+5. **Report** what was captured, why it is useful, and remind the user to restart OpenCode to activate it.
+
+## Output / State
+
+Files created (Learn mode):
+- `src/skills/<name>.md` — new skill file
+
+Files modified (Reflect mode):
+- `.codebase/POLICIES.json` — proposed policy entries (user review needed)
 
 ## Examples
 
 ```
 /fd-reflect
-/fd-reflect --mode=learn auth-pattern
-```
+```
+
+Run post-session reflection and produce improvement proposals.
+
+```
+/fd-reflect --mode=learn
+```
+
+Capture the most significant pattern from this session as a reusable skill.
+
+```
+/fd-reflect --mode=learn api-error-handling
+```
+
+Capture the session pattern as a skill named "api-error-handling".
+
+## Related Commands
+
+- `/fd-map-codebase` — map the codebase before starting a feature
+- `/fd-execute` — run implementation (reflection happens after)
+- `/fd-checkpoint` — save state before ending a session

package/docs/commands/fd-resume.md

@@ -1,10 +1,67 @@
----
-description: Resume from last checkpoint — reloads STATE.md and PLAN.md context
----
-Run the FlowDeck resume workflow to reload project context and continue from where you stopped.
+# /fd-resume
 
-## What Next?
+**Purpose:** Reload STATE.md, PLAN.md, and DISCUSS.md to continue an interrupted session — brief the user, PAUSE for confirmation, then resume from where work stopped.
 
-1. **Continue feature work** → `/fd-new-feature [description]`
-2. **View progress** → `/fd-progress`
-3. **Check dashboard** → `/fd-dashboard`
+## Usage
+
+/fd-resume [--yes]
+
+## What Happens
+
+1. **Pre-flight check.**
+   - Verify `.planning/STATE.md` exists — error if not ("No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature.")
+
+2. **Read and parse STATE.md.** Extract phase, status, last_updated, plan_confirmed.
+
+3. **Read PLAN.md** (`.planning/phases/phase-<N>/PLAN.md`) if it exists — show preview (first 20 lines).
+
+4. **Read DISCUSS.md** (`.planning/phases/phase-<N>/DISCUSS.md`) if it exists — show decision count.
+
+5. **Present session summary:**
+
+```
+═══════════════════════════════════════════════
+RESUMING SESSION
+═══════════════════════════════════════════════
+Phase: <N>  |  Status: <status>
+Last updated: <timestamp>
+Plan confirmed: <yes/no>
+Decisions: <X> from DISCUSS.md
+
+Plan preview:
+<first 10 lines of PLAN.md>
+───────────────────────────────────────────────
+Type CONFIRM to resume execution from this point.
+═══════════════════════════════════════════════
+```
+
+6. **PAUSE for confirmation** (unless `--yes` is passed). Wait for user to type CONFIRM.
+
+7. **After confirmation:**
+   - If `plan_confirmed: true` and PLAN.md has uncompleted steps → proceed with implementation
+   - If no plan exists → suggest running `/fd-plan`
+   - Brief the user on what the next step is before starting
+
+## Output / State
+
+No new files created. Resumes from existing STATE.md and PLAN.md.
+
+## Examples
+
+```
+/fd-resume
+```
+
+Show session summary and wait for CONFIRM before resuming.
+
+```
+/fd-resume --yes
+```
+
+Skip confirmation and immediately resume from the last checkpoint.
+
+## Related Commands
+
+- `/fd-checkpoint` — save a checkpoint before closing a session
+- `/fd-plan` — create a plan if no PLAN.md exists to resume
+- `/fd-execute` — continue implementation (auto-triggered after CONFIRM)

package/docs/commands/fd-status.md

@@ -1,31 +1,99 @@
----
-description: View project status — combined status, roadmap, workspace overview, and progress
-argument-hint: [--roadmap | --workspace | --phase=N]
----
+# /fd-status
 
-# Status
+**Purpose:** View project progress, roadmap phase statuses, and workspace overview — combined status display with optional detailed flags.
 
-View project status combining progress, roadmap, and workspace overview.
+## Usage
 
-## Modes
+/fd-status [--roadmap | --workspace | --phase=N]
+
+## What Happens
 
 ### Default (no flags)
-Show current phase status summary from STATE.md.
+
+Reads `.planning/STATE.md` and displays:
+```
+Phase: <N>  |  Status: <status>  |  Updated: <timestamp>
+────────────────────────────────────────────────────────────
+Plan: <X> steps (<Y> complete)
+Plan confirmed: <yes/no>
+```
 
 ### Roadmap (`--roadmap`)
-Display project roadmap with phase statuses.
+
+Reads `.planning/ROADMAP.md` and `.planning/STATE.md` and displays:
+```
+═══════════════════════════════════════
+PROJECT ROADMAP
+═══════════════════════════════════════
+  ✅ Phase 1: <name> — completed
+  🔄 Phase 2: <name> — in progress  ← current
+  ⏳ Phase 3: <name> — planned
+═══════════════════════════════════════
+```
 
 ### Workspace (`--workspace`)
-Display overview of all registered repositories.
+
+Reads `.planning/config.json` for registered repositories and each repo's STATE.md, displaying:
+```
+════════════════════════════════════════════════════
+WORKSPACE OVERVIEW
+════════════════════════════════════════════════════
+  frontend   — Phase 2 | in_progress  | Plan: ✅ | Updated: <time>
+  backend    — Phase 3 | completed    | Plan: ✅ | Updated: <time>
+  shared     — Phase 1 | planned      | Plan: ❌ | Updated: <time>
+────────────────────────────────────────────────────
+Total: 3 repos | 1 in progress | 1 completed | 1 planned
+════════════════════════════════════════════════════
+```
 
 ### Phase Detail (`--phase=N`)
-Show detailed progress for a specific phase.
+
+Reads the specific phase's STATE.md and PLAN.md (if exists) and displays:
+```
+Phase <N> Detail
+Status: <status>
+Plan file: <path>
+Plan confirmed: <yes/no>
+
+Steps:
+  ✅ Step 1: <name> — completed
+  🔄 Step 2: <name> — in progress
+  ⬜ Step 3: <name> — pending
+  ⬜ Step 4: <name> — pending
+```
+
+## Output / State
+
+No files modified. Read-only display command.
 
 ## Examples
 
 ```
 /fd-status
+```
+
+Show current phase summary.
+
+```
 /fd-status --roadmap
+```
+
+Show full project roadmap with all phase statuses.
+
+```
 /fd-status --workspace
+```
+
+Show overview of all registered repositories in the workspace.
+
+```
 /fd-status --phase=2
-```
+```
+
+Show detailed progress for phase 2.
+
+## Related Commands
+
+- `/fd-map-codebase` — map the codebase (required before starting a feature)
+- `/fd-execute` — advance phase status by implementing steps
+- `/fd-verify` — update phase status to `verified` after full pipeline pass

package/docs/commands/fd-suggest.md

@@ -0,0 +1,114 @@
+# /fd-suggest
+
+**Purpose:** Analyze the codebase and suggest high-value feature opportunities with implementation guidance.
+
+## Usage
+
+/fd-suggest [--category=TYPE] [--limit=N]
+
+## Arguments
+
+- `--category=TYPE` (optional) — focus on specific type: `tools`, `hooks`, `agents`, or `skills`
+- `--limit=N` (optional) — number of suggestions to return (default: 5)
+
+## What Happens
+
+### 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 or TODO 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).
+
+## Output / State
+
+```
+# Feature Suggestions
+
+Found N suggestions ranked by impact:
+
+[Suggestions 1-N]
+
+---
+Run /fd-discuss [topic] to start a discussion on any suggestion.
+```
+
+## Examples
+
+**Get 5 feature suggestions (default):**
+```
+/fd-suggest
+```
+
+**Get 10 suggestions:**
+```
+/fd-suggest --limit=10
+```
+
+**Focus on tool gaps only:**
+```
+/fd-suggest --category=tools
+```
+
+**Find agent-related opportunities:**
+```
+/fd-suggest --category=agents
+```
+
+## Related Commands
+
+- `/fd-discuss` — explore any suggestion in depth
+- `/fd-plan` — plan implementation of a selected suggestion
+- `/fd-translate-intent` — convert a vague request into concrete options

package/docs/commands/fd-translate-intent.md

@@ -1,17 +1,77 @@
----
-description: Intent-to-Change Translator — convert vague requests into 3–5 concrete, ranked implementation options with tradeoffs
-argument-hint: [vague intent, e.g. "make checkout faster"]
----
+# /fd-translate-intent
 
-# Translate Intent
+**Purpose:** Convert vague requests into ranked concrete implementation options with tradeoffs.
 
-Convert a vague or high-level request into concrete ranked implementation options with tradeoffs.
+## Usage
+
+/fd-translate-intent [vague intent, e.g. "make checkout faster"]
+
+## What Happens
+
+Run two agents in parallel:
+
+- **@architect**: Decomposes the input into 3-5 concrete implementation options. For each option provides:
+  - **Name**: short label
+  - **Description**: what exactly would be changed
+  - **Files affected**: list of files/modules that would change
+  - **Effort**: S (hours) / M (days) / L (week+)
+  - **Risk**: low / medium / high
+  - **Tradeoffs**: pros and cons
+
+- **@researcher**: For each option, fetches relevant codebase context — finds existing patterns, prior art, and constraints that apply
+
+## Output / State
+
+Report format:
+```
+════════════════════════════════════════════
+INTENT TRANSLATION: "$ARGUMENTS"
+════════════════════════════════════════════
+
+Option 1 (Recommended): <name>
+  Description: <what changes>
+  Files: <list>
+  Effort: <S|M|L> | Risk: <low|med|high>
+  Pros: <pros>
+  Cons: <cons>
+
+Option 2: <name>
+  ...
+
+Option 3: <name>
+  ...
+
+────────────────────────────────────────────
+Clarifying Questions:
+  1. <question about unclear aspect>
+  2. <question>
+
+Assumptions Made:
+  - <assumption>
+════════════════════════════════════════════
+```
+
+The command presents all options and asks: "Which option would you like to proceed with?"
 
 ## Examples
 
+**Convert a vague request:**
+```
+/fd-translate-intent "make checkout faster"
 ```
-/fd-translate-intent make checkout faster
-/fd-translate-intent improve auth security
+
+**Translate a high-level request:**
 ```
+/fd-translate-intent "improve auth security"
+```
+
+**Clarify a feature direction:**
+```
+/fd-translate-intent "add mobile support"
+```
+
+## Related Commands
 
-Returns 3-5 options with description, files affected, effort, risk, and tradeoffs.
+- `/fd-discuss` — explore the problem space before translating intent
+- `/fd-plan` — plan the selected implementation option
+- `/fd-execute` — execute the chosen implementation

package/docs/commands/fd-verify.md

@@ -1,18 +1,75 @@
----
-description: Review code quality, security, and conventions — runs parallel @reviewer + @security-auditor agents
-argument-hint: "[file-pattern|dir|stage number]"
----
+# /fd-verify
 
-Run the FlowDeck code review workflow. Reviews can target:
-- **Specific files or directories** — `fd-verify src/services/`
-- **Git staged changes** — `fd-verify staged`
-- **Full project** — `fd-verify`
+**Purpose:** Full verification pipeline after feature implementation — runs tests, code review, security scan, and deploy check; updates STATE.md to `verified` on full pass.
 
-## What Next?
+## Usage
 
-1. **Fix issues found** → `/fd-fix-bug [issue]`
-2. **Create deployment checkpoint** → `/fd-checkpoint`
-3. **Deploy to production** → `/fd-deploy-check`
-4. **View project dashboard** → `/fd-dashboard`
+/fd-verify [--phase=N] [--env=staging|production]
 
-Type the number or command to proceed.
+## What Happens
+
+1. **Pre-flight checks.**
+   - Verify `.planning/` and STATE.md exist
+   - Read current phase N from STATE.md
+   - Warn if `steps_complete` is empty (no steps executed yet)
+
+2. **Gather scope.**
+   - Collect changed files via `git diff --name-only HEAD`
+   - If no changes, use all files in the current phase directory
+   - Run `codegraph action=check` — if available, use `codegraph_impact` on changed files to surface dependent modules not caught by `git diff`
+
+3. **Run four checks in parallel:**
+
+   - **Tests (@tester):** `npm test` — all tests must pass, no failures or unexplained skips
+   
+   - **Code Review (@reviewer):** Review all changed files — security (secrets, injection, auth gaps), quality (critical bugs, error handling, TDD discipline), conventions (naming, patterns, import style), >= 80% test coverage for changed files. If UI-heavy: design fidelity review against approved design artifact
+   
+   - **UI Design Review (@design):** If UI-heavy — compare implemented UI to approved design artifact, report on hierarchy, spacing, CTA flow, responsiveness, accessibility, and missing state coverage. Fail verification on severe design fidelity mismatch
+   
+   - **Security Scan (@security-auditor):** No hardcoded secrets, input validation at trust boundaries, auth/authz on all protected routes, no CRITICAL/HIGH vulnerabilities
+   
+   - **Deploy Check:** `npm audit --audit-level=high` and `npm run build` — no HIGH/CRITICAL CVEs, build must succeed
+
+4. **Aggregate results.** Present consolidated table with pass/fail status for each check.
+
+5. **Go/No-Go decision.**
+
+   **VERIFIED (all checks pass):**
+   - Update STATE.md: `status: verified`, `last_action: "Phase N verified — all checks passed"`, `verified_at: <timestamp>`
+   - Report next steps (deploy, increment phase, etc.)
+
+   **NOT VERIFIED (one or more checks fail):**
+   - List required fixes
+   - Do NOT update STATE.md to verified status
+   - Report suggested next step (run `/fd-execute` for fixes, then `/fd-verify` again)
+
+6. **No-Go conditions (automatic NOT VERIFIED):** test failures, CRITICAL security vulnerability, unpatched HIGH/CRITICAL CVE, build error, CRITICAL code review finding.
+
+## Output / State
+
+STATE.md on verified:
+```yaml
+status: verified
+last_action: "Phase N verified — all checks passed"
+verified_at: "<timestamp>"
+```
+
+## Examples
+
+```
+/fd-verify
+```
+
+Run full verification pipeline for the current phase.
+
+```
+/fd-verify --phase=2 --env=staging
+```
+
+Verify phase 2 and run deploy check against staging environment.
+
+## Related Commands
+
+- `/fd-execute` — implement the feature before verification
+- `/fd-plan` — create the plan that was verified against
+- `/fd-resume` — reload state after making fixes