@dv.nghiem/flowdeck 0.3.6 → 0.3.8

package/docs/notifications.md

@@ -8,7 +8,7 @@ FlowDeck fires desktop notifications when commands that require your attention c
 
 When an interactive command finishes (one that either asks questions or produces output you need to approve), FlowDeck sends a desktop notification through the OS notification system. Notification urgency depends on the command:
 
-- **Critical-level (urgent):** `/fd-discuss`, `/fd-plan`, `/fd-review-code`, `/fd-deploy-check`, `/fd-new-project`  
+- **Critical-level (urgent):** `/fd-discuss`, `/fd-plan`, `/fd-verify`, `/fd-deploy-check`, `/fd-new-project`  
   These commands present questions or decisions that block further progress. The notification is sent at high urgency so it appears even in Do Not Disturb mode on some systems.
 
 - **Info-level:** `/fd-new-feature`, `/fd-fix-bug`, `/fd-write-docs`, `/fd-checkpoint`  
@@ -97,7 +97,7 @@ $toast = [Windows.UI.Notifications.ToastNotification]::new($template)
 |---------|-------|------|
 | `/fd-discuss` | `FlowDeck: /fd-discuss` | Your input is needed — please check OpenCode |
 | `/fd-plan` | `FlowDeck: /fd-plan` | Your input is needed — please check OpenCode |
-| `/fd-review-code` | `FlowDeck: /fd-review-code` | Your input is needed — please check OpenCode |
+| `/fd-verify` | `FlowDeck: /fd-verify` | Your input is needed — please check OpenCode |
 | `/fd-deploy-check` | `FlowDeck: /fd-deploy-check` | Your input is needed — please check OpenCode |
 | `/fd-new-project` | `FlowDeck: /fd-new-project` | Your input is needed — please check OpenCode |
 | `/fd-new-feature` | `FlowDeck: /fd-new-feature complete` | Review the output and choose your next step |

package/docs/quick-start.md

@@ -45,7 +45,7 @@ This creates the `.planning/` directory at your project root with the following
 .planning/
 ├── PROJECT.md       # Project context: name, goals, constraints, tech stack
 ├── STATE.md         # Current execution state, tracked by all agents
-├── ROADMAP.md       # Phase definitions and milestones
+├── ROADMAP.md       # Phase definitions and features
 └── config.json      # FlowDeck project configuration
 ```
 
@@ -190,6 +190,8 @@ This writes the current execution state to `.planning/STATE.md`. To reload conte
 
 > **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.
 
+> **Let `/fd-quick` drive the whole workflow** — instead of manually calling each command in sequence, run `/fd-quick <your task>` and the system classifies the task, selects the correct workflow (feature, bug fix, UI-heavy, docs), and runs all stages autonomously. It pauses only when your explicit input is needed (e.g., plan CONFIRM, approval gates). Existing commands remain fully usable standalone.
+
 ---
 
 ← [Back to Index](index.md)

package/docs/skills.md

@@ -335,7 +335,7 @@ Creates consistent releases with semantic versioning, changelog generation from
         Collect merged PRs since the last tag and generate the changelog entry.
 ```
 
-**When to use:** When a milestone is complete and ready to ship, or when a hotfix needs a patch release.
+**When to use:** When a release is ready to ship, or when a hotfix needs a patch release.
 
 ---
 

package/docs/workflows.md

@@ -56,7 +56,7 @@ Each step gates the next. `/fd-discuss` requires a defined feature. `/fd-plan` r
 | `/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 | @backend-coder/@frontend-coder/@devops or selected specialist |
+| `/fd-quick` | Autonomous workflow launcher — classifies task, runs correct stage sequence end-to-end | @supervisor, @orchestrator, and all workflow agents |
 | `/fd-reflect` | Post-session reflection and skill capture | @auto-learner |
 | `/fd-doctor` | Installation and environment diagnostics | @orchestrator |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dv.nghiem/flowdeck",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",
@@ -45,16 +45,16 @@
   },
   "homepage": "https://github.com/DVNghiem/FlowDeck#readme",
   "dependencies": {
-    "@opencode-ai/plugin": "^1.4.0"
+    "@opencode-ai/plugin": "^1.14.49"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
-    "bun-types": "^1.3.13",
-    "ejs": "^3.1.9",
-    "typescript": "^5.7.0",
-    "vitest": "^2.0.0"
+    "@types/node": "^25.7.0",
+    "bun-types": "^1.3.14",
+    "ejs": "^5.0.2",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
   },
   "peerDependencies": {
-    "@opencode-ai/sdk": "^1.4.0"
+    "@opencode-ai/sdk": "^1.14.49"
   }
 }

package/src/commands/fd-discuss.md

@@ -95,7 +95,7 @@ If UI-heavy, also suggest running `/fd-design --mode=draft` before `/fd-execute`
 ## Error Handling
 
 D-03: Fail fast with clear error
-- If PROJECT.md not found: error with "Run /new-project first"
+- If PROJECT.md not found: error with "Run /fd-new-project first"
 - If STATE.md not found: error with "Project not initialized"
 - If @discusser fails: error with "Discusser agent unavailable"
 - No partial state saved on error

package/src/commands/fd-multi-repo.md

@@ -16,14 +16,14 @@ Orchestrates a feature or fix that spans multiple repositories in a microservice
 - A shared library is being upgraded with a breaking change
 - You need a coordinated rollout across services
 
-Do not use for single-repo work. Use `/new-feature` instead.
+Do not use for single-repo work. Use `/fd-new-feature` instead.
 
 ## Prerequisites
 
 Before running this flow:
 1. `.planning/config.json` has a `sub_repos` array with the relevant repos registered
 2. All `path` values in the registry resolve to actual directories on disk
-3. A description of the intended change is available (from `/discuss` or passed directly)
+3. A description of the intended change is available (from `/fd-discuss` or passed directly)
 
 If the registry is empty or not set up, run `/multi-repo --add` first.
 

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

@@ -71,7 +71,6 @@ Initialize FlowDeck planning structure for the current workspace.
 ```markdown
 ---
 flowdeck_state_version: 1.0
-milestone: v1.0
 last_updated: "<current timestamp>"
 progress:
   total_phases: 1

package/src/commands/fd-plan.md

@@ -17,7 +17,7 @@ D-06: Verify DISCUSS.md exists and is confirmed.
 
 If no DISCUSS.md found:
 ```
-Error: DISCUSS.md not found. Run /discuss [topic] first.
+Error: DISCUSS.md not found. Run /fd-discuss [topic] first.
 ```
 
 If DISCUSS.md exists but not confirmed:

package/src/commands/fd-quick.md

@@ -1,63 +1,248 @@
 ---
-description: Quick task execution — analyze, implement, review, or investigate a specific piece of work without the full discuss -> plan -> execute workflow
+description: Autonomous workflow launcher — classifies the task, selects the correct existing workflow, and runs the full stage sequence (discuss → plan → execute → verify and variants) end-to-end with minimal user input
 argument-hint: [task description]
 ---
 
-# Quick Task
+# Quick — Autonomous Workflow Launcher
 
-Execute a focused task without the full workflow. Analyzes the request, selects the best specialist agent, and returns the result directly.
+Run the correct FlowDeck workflow automatically for any task. This command:
+- Classifies the task type
+- Selects the appropriate existing workflow and stage sequence
+- Routes all clarifying questions through `@supervisor`
+- Executes each stage in order using the existing registered commands
+- Stops only when blocked, awaiting approval, or fully verified
 
 **Input:** $ARGUMENTS — what you need done
 
-## Analysis
-
-Parse `$ARGUMENTS` to determine:
-
-1. **Type of task** — what kind of work is it?
-2. **Scope** — single file, directory, or whole codebase?
-3. **Required capability** — what must the agent be able to do?
-
-## Agent Selection Matrix
-
-| Task Type | Signal Keywords | Agent |
-|-----------|-----------------|-------|
-| Backend code implementation | api, server, service, database, migration, endpoint, repository | `@backend-coder` |
-| Frontend code implementation | ui, frontend, component, page, css, style, react, screen | `@frontend-coder` |
-| DevOps and infra implementation | ci, cd, deploy, pipeline, workflow, docker, kubernetes, terraform | `@devops` |
-| Explore and understand | trace, map, find, explore, understand, what does | `@code-explorer` |
-| Review code quality | review, check, audit, analyze | `@reviewer` |
-| Security review | security, auth, vulnerability, injection, OWASP | `@security-auditor` |
-| UI design-first planning | landing page, dashboard, admin panel, onboarding UX, app screen, wireframe, design system | `@design` |
-| Design or architecture | design, architect, schema, API, structure | `@architect` |
-| Write tests | test, coverage, regression, TDD | `@tester` |
-| Documentation | docs, README, document, write | `@writer` |
-| Research | research, find, look up, how to use, compare | `@researcher` |
-| Debug | debug, trace, root cause, why is, fix error | `@debug-specialist` |
-| Performance | performance, slow, optimize, bottleneck | `@performance-optimizer` |
-| Build error | build error, compile, types, missing import | `@build-error-resolver` |
-| Refactoring | refactor, extract, rename, restructure | `@refactor-guide` |
-| Write/update docs | document, write docs, update README | `@doc-updater` |
-
-**Default:** If unclear or mixed, use `@orchestrator`.
-
-## Execution
-
-1. Select the best agent from the matrix above.
-2. Construct a focused prompt with:
-   - The task from `$ARGUMENTS`
-   - Relevant context (file paths, architecture info, existing code)
-   - Clear success criteria
-3. Execute directly — no intermediate steps.
-
-## Output
-
-Return the agent's output with:
-- Which agent was used
-- The result (be direct, no padding)
-- If the task is partial or incomplete, note what still needs doing
-
-## Guardrails
-
-- **Small tasks only** — if the task would require more than ~15 minutes of work, suggest `/fd-new-feature` instead.
-- **Single scope** — do not attempt multi-file refactors or cross-repo changes via this command.
-- **No workflow overhead** — skip STATE.md updates, phase transitions, and plan markers.
+---
+
+## Step 1: Pre-flight State Check
+
+1. Check `.planning/STATE.md` exists — if not, error: "Run /fd-new-project first."
+2. Read `.planning/STATE.md` to determine if a `quick_run` entry already exists for this session.
+   - If `quick_run.outcome` is `running` or `blocked`: **resume from the last completed stage** (skip to Step 5).
+   - Otherwise: proceed to Step 2.
+
+---
+
+## Step 2: Classify the Task
+
+Parse `$ARGUMENTS` using the signal table below to determine task type and required stage sequence.
+
+### Signal Classification Table
+
+| Task Type | Strong Signal Keywords | Stage Sequence |
+|-----------|------------------------|----------------|
+| **bugfix** | fix, bug, broken, not working, error, crash, regression, debug, exception, failing, root cause, why is, stack trace | `discuss → fix-bug → verify` |
+| **ui-feature** | landing page, dashboard, admin panel, app screen, onboarding, wireframe, design system, ux flow, web app, website, responsive layout, navbar, modal, sidebar, frontend page | `discuss → design → plan → execute → verify` |
+| **docs** | docs, documentation, readme, api docs, usage guide, write docs, document, changelog, tutorial, docstring | `discuss → write-docs → verify` |
+| **simple** | rename, move file, minor, typo, update constant, update config, bump version, one-liner | `execute → verify` |
+| **feature** | (substantive description, 8+ words, no above signals) | `discuss → plan → execute → verify` |
+| **ambiguous** | (short, vague, or unclear input) | *(clarify first — see Step 3)* |
+
+### Classification Rules
+
+1. **Bug signals dominate**: if the description contains "fix", "bug", "error", "crash", "exception", "broken", or "regression", classify as `bugfix` even if it also mentions UI elements.
+2. **UI signals for design-first**: if 1+ UI-heavy signal is present and no dominant bug signal, classify as `ui-feature`.
+3. **Docs signals**: if "docs", "documentation", "readme", or "write docs" is present without implementation signals, classify as `docs`.
+4. **Simple**: if "rename", "typo", "minor", or "move file" is present and description is a single, scoped operation.
+5. **Feature**: substantive description (8+ words) with no specific signal type.
+6. **Ambiguous**: description is too short (<5 words) or matches a bare imperative with no object (e.g., "improve", "add", "make it better").
+
+Record the classification result:
+```yaml
+quick_run:
+  taskDescription: "$ARGUMENTS"
+  taskType: <feature|ui-feature|bugfix|docs|simple|ambiguous>
+  requiresDesign: <true|false>
+  requiresTDD: <true|false>
+  stageSequence: [<ordered stage names>]
+  completedStages: []
+  currentStage: <first stage name>
+  supervisorDecisions: {}
+  startedAt: <ISO timestamp>
+  outcome: running
+```
+
+---
+
+## Step 3: Supervisor-Gated Clarification (when needed)
+
+**Only proceed to Step 4 when classification confidence is sufficient.**
+
+If classification is `ambiguous` OR confidence is low (description < 5 words or no clear signal):
+
+1. Invoke `@supervisor` (preflight review of `fd-quick` command) with the partial task description.
+2. Present the supervisor's single clarifying question to the user. **Ask ONE question only.**
+3. Wait for the user's answer.
+4. Re-classify using the combined original description + the user's answer.
+5. If confidence is still low after one clarification round, route to `feature` with a note in STATE.md.
+
+**All clarification goes through `@supervisor`. Do not have specialist agents ask questions directly.**
+
+Example supervisor clarification questions (the supervisor selects the most relevant):
+- "Is this a new feature, a bug fix, or a documentation task?"
+- "Does this involve building or changing a user-facing UI (page, dashboard, component)?"
+- "Can you describe the specific bug — what is the expected vs actual behavior?"
+- "Is the scope a single file change, or does it span multiple modules?"
+
+---
+
+## Step 4: Confirm Stage Sequence
+
+Present the classification and planned stage sequence to the user before proceeding:
+
+```
+Task classified as: <task type>
+Stage sequence:     <stage-1> → <stage-2> → ... → <stage-N>
+Requires design:    <yes / no>
+Requires TDD:       <yes / no>
+
+Running /fd-quick autonomously. I will proceed through each stage and pause only
+if I need approval, encounter a blocker, or complete the full sequence.
+```
+
+Proceed automatically — do not wait for additional input unless approval is explicitly required by a stage.
+
+---
+
+## Step 5: Execute Stage Sequence Autonomously
+
+For **each stage** in the sequence (in order), execute the following loop:
+
+### 5a. Announce Stage Start
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Stage: <stage-name>  Command: /<command>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### 5b. Supervisor Preflight Review
+
+Before executing the stage, invoke `@supervisor` (preflight) on the stage's command:
+- Pass: `taskDescription`, `currentPhase` (= current stage name), `prerequisitesMet`, `designApprovalPresent`, `regressionTestPresent` as known from STATE.md.
+
+**Handle supervisor decision:**
+
+| Decision | Action |
+|----------|--------|
+| `approve` | Proceed to 5c immediately |
+| `revise` | Resolve the listed `requiredChanges` (e.g., confirm PLAN.md, run preceding step) then re-run the stage |
+| `block` | Stop. Report why. Show what is blocked. Ask user for the specific missing input or approval. Update `quick_run.outcome = blocked` in STATE.md. |
+| `escalate` | Pause. Present the escalation reason to the user. Request explicit approval. On approval: continue. On denial: stop and summarize. |
+
+### 5c. Execute the Stage
+
+Execute the stage using its existing command with full context:
+
+**Stage → Command Mapping:**
+
+| Stage | Command | Key Behavior |
+|-------|---------|--------------|
+| `discuss` | `/fd-discuss` | Runs `@discusser` structured Q&A. Saves `DISCUSS.md`. One question at a time. |
+| `design` | `/fd-design --mode=draft` | Runs design-first pipeline. Required for `ui-feature` tasks. Produces design artifact + approval. |
+| `plan` | `/fd-plan` | Creates `PLAN.md` from `DISCUSS.md` decisions. **Pauses for user CONFIRM before saving.** |
+| `execute` | `/fd-execute` | TDD pipeline: BEHAVIOR → RED → GREEN → REFACTOR per step. Delegates to appropriate coder agents. |
+| `fix-bug` | `/fd-fix-bug` | TDD bugfix: explore → RED regression test → GREEN fix → REFACTOR → record in FAILURES.json. |
+| `write-docs` | `/fd-write-docs` | Explore APIs → `@writer` drafts → `@reviewer` accuracy check → finalize. |
+| `verify` | `/fd-verify` | Full verification: tests + code review + security scan + deploy check. Reports verdict. |
+
+### 5d. Stage Completion Check
+
+After the stage command completes:
+1. Invoke `@supervisor` (post-stage) to confirm the stage output is valid.
+2. If supervisor returns `approve` or `revise` with fixable issues: mark the stage complete.
+3. If supervisor returns `block`: halt, report, update state.
+4. Update STATE.md:
+   ```yaml
+   quick_run:
+     completedStages: [<all completed stage names>]
+     currentStage: <next stage name or null>
+     supervisorDecisions:
+       <stage-name>:
+         decision: <decision>
+         reasons: [...]
+         timestamp: <ISO>
+   ```
+5. Proceed to next stage.
+
+### 5e. Approval Gate (plan stage only)
+
+The `plan` stage requires explicit user CONFIRM per the `/fd-plan` command's D-06 rule.
+`/fd-quick` does NOT bypass this gate. Present the plan to the user and wait for CONFIRM.
+
+---
+
+## Step 6: Completion
+
+When all stages complete:
+
+1. Update STATE.md:
+   ```yaml
+   quick_run:
+     completedStages: [<all stages>]
+     currentStage: null
+     outcome: complete
+   ```
+
+2. Present final summary:
+   ```
+   ════════════════════════════════════════════════
+   /fd-quick Complete — <task type>
+   ════════════════════════════════════════════════
+   Task:      $ARGUMENTS
+   Workflow:  <stage-1> → ... → <stage-N>
+   Outcome:   ✅ COMPLETE
+   ────────────────────────────────────────────────
+   Verify result: /fd-verify
+   Save state:    /fd-checkpoint
+   ════════════════════════════════════════════════
+   ```
+
+---
+
+## Step 7: Block / Failure Handling
+
+If execution cannot continue at any stage:
+
+1. Update STATE.md: `quick_run.outcome = blocked`
+2. Report:
+   ```
+   ════════════════════════════════════════════════
+   /fd-quick Blocked
+   ════════════════════════════════════════════════
+   Stage reached:    <stage-name>
+   Why stopped:      <clear reason>
+   Blocked at:       <command name>
+   What is needed:   <exact missing input or approval>
+   ────────────────────────────────────────────────
+   To resume:        /fd-quick $ARGUMENTS
+     (will continue from <next-stage-name>)
+   To fix manually:  /<blocked-command> [args]
+   ════════════════════════════════════════════════
+   ```
+
+---
+
+## Workflow Discipline (Non-Negotiable)
+
+These gates from the existing workflow system are **never bypassed by /fd-quick**:
+
+- **Design-first**: `ui-feature` tasks MUST complete the `design` stage (with `@design` approval and handoff) before `execute` can begin. No `--override` unless user explicitly requests it.
+- **TDD**: `execute` and `fix-bug` stages enforce RED → GREEN → REFACTOR. `/fd-quick` does not skip tests.
+- **Plan CONFIRM**: The `plan` stage requires explicit user CONFIRM. `/fd-quick` presents the plan and waits.
+- **Regression test**: `fix-bug` requires a failing regression test before implementation (per `/fd-fix-bug`).
+- **Verify**: All workflows end with `/fd-verify` to confirm all checks pass before marking complete.
+
+---
+
+## Existing Commands Remain Independent
+
+`/fd-quick` is a workflow launcher. The commands it invokes (`/fd-discuss`, `/fd-plan`, etc.) remain fully operational as standalone commands. Running `/fd-quick` does not lock out any other command.
+
+---
+
+## State Visibility
+
+All routing and execution progress is recorded in `.planning/STATE.md` under the `quick_run` key. Use `/fd-status` to inspect current state. Use `/fd-resume` to reload context after a session break.

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

@@ -79,6 +79,6 @@ discuss → plan → execute → review
 | discuss | `@discusser` | `/fd-discuss` |
 | plan | `@planner` → `@plan-checker` | `/fd-plan` |
 | execute | `@orchestrator` → `@backend-coder`, `@tester`, etc. | `/fd-new-feature` |
-| review | `@reviewer` + `@security-auditor` | `/fd-review-code` |
+| review | `@reviewer` + `@security-auditor` | `/fd-verify` |
 
 Do not skip phases. The orchestrator enforces phase gating automatically.

package/src/skills/blast-radius-preview/SKILL.md

@@ -6,7 +6,7 @@ origin: FlowDeck
 
 # Blast Radius Preview
 
-Before committing to a change, map every system that could break. Run `/blast-radius` with a change description.
+Before committing to a change, map every system that could break. Activate this skill by providing a change description to the agent.
 
 ## When to Activate
 

package/src/skills/change-impact-radar/SKILL.md

@@ -6,7 +6,7 @@ origin: FlowDeck
 
 # Change Impact Radar
 
-Predicts blast surface before the AI touches a single file. Run `/impact-radar` with a description of the intended change.
+Predicts blast surface before the AI touches a single file. Activate this skill by providing the intended change description to the agent.
 
 ## When to Activate
 
@@ -58,6 +58,6 @@ Activate before:
 
 ## Guidance
 
-- If MEMORY.json does not exist, run `/map-codebase` first to build the graph.
+- If MEMORY.json does not exist, run `/fd-map-codebase` first to build the graph.
 - If a file has no test coverage and is indirectly impacted, flag it as "coverage gap".
 - Never proceed with a HIGH impact change without human confirmation.

package/src/skills/confidence-aware-planning/SKILL.md

@@ -33,7 +33,7 @@ Before planning ANY task:
 2. Scan affected files for context
 3. Estimate confidence level
 4. Act based on level:
-   - HIGH: proceed to `/plan`
+   - HIGH: proceed to `/fd-plan`
    - MEDIUM: write explicit assumptions at the top of PLAN.md, flag 3 highest risks
    - LOW: stop, ask clarifying questions, do not write PLAN.md until answered
 

package/src/skills/context-load/SKILL.md

@@ -60,4 +60,4 @@ After loading context, produce this briefing:
 **Key Conventions**: [2-3 most important patterns]
 ```
 
-If any file is missing, note it: "STATE.md not found — run `/new-project` to initialize."
+If any file is missing, note it: "STATE.md not found — run `/fd-new-project` to initialize."