@dv.nghiem/flowdeck 0.3.4 → 0.3.5

package/docs/configuration.md

@@ -147,9 +147,9 @@ Each FlowDeck project stores its settings in `.planning/config.json`. This file
 
 ---
 
-## flowdeck.json (Agent Model Overrides)
+## flowdeck.json (Agent and Governance Config)
 
-The `flowdeck.json` file lets you assign specific AI models to individual FlowDeck agents. This is useful when you want the `@planner` to use a more capable model while lighter agents like `@tester` use a faster, cheaper one.
+The `flowdeck.json` file controls two things: per-agent model overrides and the governance layer. **No model is hardcoded** — if an agent is not listed, it uses whatever model is currently selected in OpenCode.
 
 ### Locations
 
@@ -160,7 +160,7 @@ The `flowdeck.json` file lets you assign specific AI models to individual FlowDe
 
 Project config takes precedence over global config.
 
-### Schema
+### Full schema
 
 ```json
 {
@@ -168,61 +168,91 @@ Project config takes precedence over global config.
     "<agent-name>": {
       "model": "<provider>/<model-id>"
     }
+  },
+  "designFirst": {
+    "enabled": true,
+    "enforcement": "strict",
+    "requireApprovalBeforeImplementation": true,
+    "modelOverrides": {
+      "design": "anthropic/claude-sonnet-4"
+    },
+    "defaultSkillsByTaskType": {
+      "landing-page": ["landing-page-design", "wireframe-planning", "design-system-definition", "frontend-handoff"]
+    }
+  },
+  "governance": {
+    "validator": {
+      "mode": "advisory"
+    },
+    "delegationBudget": {
+      "maxToolCalls": 200,
+      "maxDelegatedAgents": 30,
+      "maxRetries": 10,
+      "maxDepth": 8,
+      "maxSameStepRetries": 3
+    },
+    "deadlockDetection": {
+      "enabled": true,
+      "bounceThreshold": 3,
+      "stageStallMinutes": 30,
+      "autoStop": false
+    },
+    "scorecard": {
+      "enabled": true
+    }
   }
 }
 ```
 
-### Supported Agents
-
-| Agent | Default Model | Override Example |
-|-------|--------------|-----------------|
-| `@architect` | `claude-opus-4-5` | `anthropic/claude-opus-4-5` |
-| `@build-error-resolver` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@code-explorer` | `claude-haiku-4-5` | `anthropic/claude-haiku-4-5` |
-| `@coder` | `claude-opus-4-5` | `anthropic/claude-opus-4-5` |
-| `@debug-specialist` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@discusser` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@doc-updater` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@orchestrator` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@plan-checker` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@planner` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@mapper` | `gemini-2.5-flash` | `google/gemini-2.5-flash` |
-| `@multi-repo-coordinator` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@orchestrator` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@parallel-coordinator` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@performance-optimizer` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@planner` | `claude-opus-4-5` | `anthropic/claude-opus-4-5` |
-| `@refactor-guide` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@researcher` | `gpt-4o` | `openai/gpt-4o` |
-| `@reviewer` | `gemini-2.5-flash` | `google/gemini-2.5-flash` |
-| `@security-auditor` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@task-splitter` | `claude-sonnet-4-5` | `anthropic/claude-sonnet-4-5` |
-| `@tester` | `claude-haiku-4-5` | `anthropic/claude-haiku-4-5` |
-| `@writer` | `claude-haiku-4-5` | `anthropic/claude-haiku-4-5` |
-
-### Example
+### Agent model overrides
+
+All agents default to the model currently selected in OpenCode. Only list agents you want to override:
 
 ```json
 {
   "agents": {
-    "planner": {
-      "model": "anthropic/claude-opus-4-5"
-    },
-    "orchestrator": {
-      "model": "anthropic/claude-sonnet-4-5"
-    },
-    "tester": {
-      "model": "anthropic/claude-haiku-4-5"
-    }
+    "planner":      { "model": "anthropic/claude-opus-4" },
+    "orchestrator": { "model": "anthropic/claude-sonnet-4" },
+    "tester":       { "model": "openai/gpt-4o-mini" },
+    "reviewer":     { "model": "google/gemini-2.5-flash" }
   }
 }
 ```
 
-### Notes
-
-- If an agent is not listed in `agents`, it uses the model currently selected in OpenCode.
-- Only list agents you want to override — omitted agents inherit the session default.
-- Model strings must match the format `provider/model-id` (e.g., `anthropic/claude-sonnet-4-5`).
+Model strings must use the format `provider/model-id`. Common examples:
+
+| Provider | Example model string |
+|----------|---------------------|
+| Anthropic | `anthropic/claude-opus-4`, `anthropic/claude-sonnet-4`, `anthropic/claude-haiku-4` |
+| OpenAI | `openai/gpt-4o`, `openai/gpt-4o-mini` |
+| Google | `google/gemini-2.5-flash`, `google/gemini-2.5-pro` |
+| GitHub Copilot | `github-copilot/sonnet-4.6` |
+| Minimax | `minimax/minimax-m2.7-highspeed` |
+
+Agents with no entry in `agents` inherit the session model selected in OpenCode's model picker.
+
+### Governance config
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `governance.validator.mode` | `"advisory"` | `"off"` — disabled; `"advisory"` — warn but never block; `"strict"` — block on contract violations |
+| `governance.delegationBudget.maxToolCalls` | `200` | Total tool calls allowed per workflow run before escalation |
+| `governance.delegationBudget.maxDelegatedAgents` | `30` | Maximum number of sub-agent delegations per run |
+| `governance.delegationBudget.maxRetries` | `10` | Total retries allowed across all steps |
+| `governance.delegationBudget.maxDepth` | `8` | Maximum delegation nesting depth |
+| `governance.delegationBudget.maxSameStepRetries` | `3` | Retries allowed on a single failing step before escalation |
+| `governance.deadlockDetection.enabled` | `true` | Enable deadlock and loop detection |
+| `governance.deadlockDetection.bounceThreshold` | `3` | Agent-pair invocations before bounce is flagged |
+| `governance.deadlockDetection.stageStallMinutes` | `30` | Minutes without stage progress before stall is flagged |
+| `governance.deadlockDetection.autoStop` | `false` | Stop automatically on detection; `false` emits warning only |
+| `governance.scorecard.enabled` | `true` | Generate a quality scorecard after every run |
+
+### Design-first defaults
+
+- `designFirst.enabled`: defaults to `true`
+- `designFirst.enforcement`: defaults to `strict` (`advisory` supported)
+- `designFirst.requireApprovalBeforeImplementation`: defaults to `true`
+- UI-heavy tasks are blocked from implementation until design handoff is approved, unless explicit override is recorded.
 
 ---
 

package/docs/design-first-workflow.md

@@ -0,0 +1,94 @@
+# Design-First Workflow
+
+FlowDeck enforces a design-first path for UI-heavy tasks by default.
+
+## Trigger Conditions
+
+Design-first is triggered when tasks mention user-facing work such as:
+- landing page
+- dashboard
+- admin panel
+- website redesign
+- onboarding UX
+- app screen/mobile UI
+
+Backend-only or infra-only tasks skip design-first.
+
+## Workflow
+
+```text
+task intake
+→ task classification
+→ design discovery
+→ UX structure
+→ wireframe/layout planning
+→ visual system definition
+→ design review/approval
+→ implementation handoff
+→ frontend implementation
+→ QA/review
+```
+
+## Commands
+
+- `/fd-design --mode=draft`: produce design artifact and handoff
+- `/fd-design --mode=review`: compare implementation to approved design artifact
+- `/fd-design --mode=system`: create/update token and component consistency guidance
+
+## Design Artifact Schema
+
+Each design run should persist:
+- `task_type`
+- `user_goals`
+- `target_audience`
+- `core_user_flows`
+- `page_map_or_screen_map`
+- `section_structure`
+- `layout_plan`
+- `component_list`
+- `state_list`
+- `responsive_behavior_notes`
+- `visual_direction`
+- `design_tokens_guidance`
+- `accessibility_notes`
+- `implementation_handoff_checklist`
+- `approval_status`
+
+## Example: Landing Page
+
+```yaml
+task_type: landing-page
+user_goals:
+  - understand value in <10 seconds
+  - complete signup CTA
+core_user_flows:
+  - hero -> social-proof -> pricing -> CTA
+layout_plan:
+  - hero_section: headline, subheadline, primary_cta, secondary_cta
+  - proof_section: logos, testimonials
+  - pricing_section: tier_cards, comparison_table
+state_list: [loading, empty, error, success]
+approval_status: approved
+```
+
+## Example: App Screen Redesign
+
+```yaml
+task_type: app-screen
+target_audience:
+  - returning mobile users
+core_user_flows:
+  - home -> quick-action -> detail -> completion
+section_structure:
+  - top_nav
+  - summary_cards
+  - task_list
+  - persistent_action_bar
+responsive_behavior_notes:
+  - compact_nav_on_small_screens
+  - collapse_secondary_panels_under_768
+design_tokens_guidance:
+  - spacing_scale: [4, 8, 12, 16, 24, 32]
+  - text_scale: [12, 14, 16, 20, 24]
+approval_status: approved
+```

package/docs/feature-integration-architecture.md

@@ -11,7 +11,7 @@ This layer adds 8 capabilities behind the existing command architecture without
 | Capability | Implementation | Data File |
 |---|---|---|
 | Patch Trust Engine | `src/hooks/patch-trust.ts` | `.codebase/DECISIONS.jsonl` |
-| Adaptive Model Router | `src/services/model-router.ts` | `.codebase/MODEL_ROUTER.json` |
+| Agent Performance Memory | `src/services/agent-performance.ts` | `.codebase/AGENT_PERF.json` |
 | Approval-Aware Execution | `src/services/approval-manager.ts` + `src/hooks/approval-hook.ts` | `.codebase/APPROVALS.json` |
 | Workflow Replay + Diff | `src/services/run-trace.ts` | `.codebase/RUNS.jsonl` |
 | Agent Performance Memory | `src/services/agent-performance.ts` | `.codebase/AGENT_PERF.json` |
@@ -63,27 +63,6 @@ isSensitivePath(filePath) → boolean
 
 **Approval TTL:** 30 minutes. Sensitive path patterns: auth, payment, secrets, migrations, infra, production config.
 
-### model-router.ts
-Routes task types to the best available model.
-
-```typescript
-routeModel(dir, task_type, risk_score?) → RoutedModel
-buildAgentConfig(dir, agents) → AgentConfig[]
-getRouterConfig(dir) → ModelRouterConfig
-```
-
-**Default routing:**
-| Task | Primary | High-Risk Override |
-|---|---|---|
-| planning | claude-sonnet-4-5 | — |
-| implementation | claude-opus-4-5 | claude-opus-4-5 |
-| debugging | claude-sonnet-4-5 | claude-opus-4-5 |
-| review | gemini-2.5-flash | — |
-| testing | claude-haiku-4-5 | — |
-| security | claude-opus-4-5 | claude-opus-4-5 |
-
-Override by creating `.codebase/MODEL_ROUTER.json` with `{ "task_type": { "primary": "model-name" } }`.
-
 ### agent-performance.ts
 Tracks success rates, costs, and durations per agent+model+task combination.
 
@@ -94,7 +73,7 @@ getBestAgentForTask(dir, task_type) → AgentRecommendation | null
 getAgentLeaderboard(dir) → AgentRecommendation[]
 ```
 
-Requires ≥ 3 runs per combination before making routing recommendations.
+Requires ≥ 3 runs per combination before making routing recommendations. Model is tracked from the actual call — no hardcoded model list.
 
 ---
 
@@ -122,7 +101,6 @@ Emits `tool.call` events for all tool invocations. Lightweight — never blocks.
 
 ### /fd-new-feature
 - Calls `startTrace()` on entry → `run_id` included in config
-- Calls `buildAgentConfig()` from model-router → no hardcoded models
 - Emits `command.start` telemetry event with risk score and phase
 
 ### /fd-fix-bug
@@ -175,12 +153,7 @@ The dashboard at `http://localhost:<port>` now includes:
 
 ### AGENT_PERF.json
 ```json
-{"entries":[{"agent":"coder","model":"claude-opus-4-5","task_type":"implementation","runs":12,"successes":11,"failures":1,"total_duration_ms":60000,"total_cost":0.48,"last_run":"ISO","last_status":"success"}],"updated_at":"ISO"}
-```
-
-### MODEL_ROUTER.json (optional override)
-```json
-{"implementation":{"primary":"claude-sonnet-4-5","temperature":0.2},"review":{"primary":"claude-haiku-4-5"}}
+{"entries":[{"agent":"backend-coder","model":"<user-configured>","task_type":"implementation","runs":12,"successes":11,"failures":1,"total_duration_ms":60000,"total_cost":0.48,"last_run":"ISO","last_status":"success"}],"updated_at":"ISO"}
 ```
 
 ---
@@ -189,7 +162,6 @@ The dashboard at `http://localhost:<port>` now includes:
 
 No new required config. Optional per-repo overrides:
 
-- `.codebase/MODEL_ROUTER.json` — override model routing per task type
 - `.codebase/POLICIES.json` — runtime policy rules (existing, enhanced)
 - `.codebase/CONSTRAINTS.md` — architectural constraints (existing)
 

package/docs/index.md

@@ -1,6 +1,6 @@
 # FlowDeck Documentation
 
-FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orchestration to your development sessions. It coordinates specialist agents through a four-phase cycle — discuss, plan, execute, review — with persistent state stored in your project's `.planning/` directory.
+FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orchestration to your development sessions. It coordinates specialist agents through a gated workflow — discuss, plan, design (UI-heavy), execute, review — with persistent state stored in your project's `.planning/` directory.
 
 ---
 
@@ -18,12 +18,14 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 
 | Document | Description |
 |----------|-------------|
-| [Agents](agents.md) | All specialist agents — names, roles, models, and when to invoke each one |
+| [Agents](agents.md) | All specialist agents — names, roles, and when to invoke each one |
 | [Skills](skills.md) | Reusable skill patterns for common tasks |
 | [Commands](commands.md) | All 18 slash commands — syntax, arguments, and what each command triggers |
 | [Workflows](workflows.md) | Built-in workflows for common scenarios |
+| [Design-First Workflow](design-first-workflow.md) | UI-heavy workflow gates from design discovery to implementation handoff |
 | [Rules](rules.md) | Language and common rule files — what they enforce and how to activate them |
 | [Intelligence Features](intelligence.md) | AI-safety features for pre-change analysis and risk assessment |
+| [Governance Layer](configuration.md#governance-config) | Agent contracts, validator, trace graph, budget, deadlock detection, and scorecards |
 | [Memory System](memory.md) | Persistent memory — recall past sessions, tool executions, and context across sessions |
 
 ---
@@ -53,6 +55,7 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 | `/fd-new-project <name>` | Initialize project with planning structure and default config |
 | `/fd-discuss <topic>` | Run structured requirements Q&A to capture decisions |
 | `/fd-plan [--phase=N]` | Generate implementation plan from decisions (requires CONFIRM) |
+| `/fd-design [--mode=draft\|review\|system]` | Run design-first planning and UI fidelity review for UI-heavy tasks |
 | `/fd-new-feature "<description>"` | Execute full feature workflow with TDD discipline |
 | `/fd-fix-bug "<description>"` | Diagnose and fix a bug with regression test |
 | `/fd-deploy-check [--check=deploy,review,analysis]` | Pre-deploy checks, code review, or pre-change analysis |

package/docs/intelligence.md

@@ -252,12 +252,103 @@ Manages `.codebase/POLICIES.json` — self-healing editing rules that update aft
 | `VOLATILITY.json` | JSON | Per-file churn and stability metrics |
 | `POLICIES.json` | JSON | Self-healing editing rule set |
 | `CONSTRAINTS.md` | Markdown | Forbidden path list for Arch Constraint Guard |
+| `AGENT_SPANS.jsonl` | Newline-delimited JSON | Inter-agent trace graph (governance) |
+| `BUDGETS.json` | JSON | Per-run delegation budget state (governance) |
+| `DEADLOCK_SIGNALS.jsonl` | Newline-delimited JSON | Detected loops and deadlocks (governance) |
+| `SCORECARDS.jsonl` | Newline-delimited JSON | 10-dimension workflow quality scores (governance) |
 
 > **Tip:** All `.codebase/` files should be committed to version control so the intelligence layer improves over time.
 
 ---
 
-## Skills
+## Governance Layer
+
+The governance layer makes multi-agent execution trustworthy and debuggable. It runs automatically as internal runtime services — no commands or manual wiring needed.
+
+### Agent Contracts
+
+Every major agent has an explicit contract defining:
+
+- **Allowed tools** — tools the agent may invoke
+- **Forbidden actions** — things the agent must never do (e.g. `@reviewer` may not write files)
+- **Required inputs** — what context must be present before the agent runs
+- **Escalation conditions** — when to surface to human review
+- **Success criteria** — what a good output looks like
+
+Contracts are defined in `src/services/agent-contract-registry.ts` and cover: orchestrator, planner, plan-checker, design, backend-coder, frontend-coder, devops, tester, reviewer, security-auditor, researcher, architect, writer, and doc-updater.
+
+### Agent Validator
+
+Before and after each agent invocation, the validator checks the execution context against the agent's contract. Configure the enforcement mode in `flowdeck.json`:
+
+| Mode | Behaviour |
+|------|-----------|
+| `off` | Validation disabled |
+| `advisory` | Validate and warn; never block execution (default) |
+| `strict` | Block on contract violations of severity `block` |
+
+Violations are emitted as `contract.violation` telemetry events and attached to the agent span.
+
+### Inter-Agent Trace Graph
+
+Every delegation opens a **span** in the trace graph. Spans record:
+
+- Invoker → agent direction
+- Trace ID and parent span ID (causal chain)
+- Tools used and outputs
+- Contract violations attached to the span
+- Latency and delegation depth
+
+Spans are stored in `.codebase/AGENT_SPANS.jsonl`. The trace graph is dashboard-ready and can be rendered as a timeline, causality graph, or per-agent drilldown.
+
+### Delegation Budget
+
+Each workflow run has a budget tracked in `.codebase/BUDGETS.json`:
+
+| Limit | Default | Config key |
+|-------|---------|------------|
+| Max tool calls | 200 | `governance.delegationBudget.maxToolCalls` |
+| Max delegated agents | 30 | `governance.delegationBudget.maxDelegatedAgents` |
+| Max retries (total) | 10 | `governance.delegationBudget.maxRetries` |
+| Max delegation depth | 8 | `governance.delegationBudget.maxDepth` |
+| Max retries per step | 3 | `governance.delegationBudget.maxSameStepRetries` |
+
+When a limit is exceeded the system escalates to human review or (if `autoStop: true`) stops safely and summarises what was completed.
+
+### Deadlock and Loop Detector
+
+The detector runs four independent pattern checks after each agent invocation:
+
+| Pattern | Trigger |
+|---------|---------|
+| `agent_bounce` | Same agent pair invoked ≥ N times without resolution |
+| `step_retry_loop` | Same stage retried beyond the per-step limit |
+| `circular_delegation` | DFS detects a cycle in the delegation graph — always triggers `auto_stop` |
+| `stage_stall` | Workflow stage makes no progress within the stall window |
+
+Signals are written to `.codebase/DEADLOCK_SIGNALS.jsonl`. Duplicate signals for the same trace and pattern are suppressed. A recovery action recommendation is attached to each signal.
+
+### Workflow Scorecard
+
+After every completed or failed run, a scorecard is generated and appended to `.codebase/SCORECARDS.jsonl`. Ten dimensions are scored and combined into a weighted 0–100 score:
+
+| Dimension | Weight |
+|-----------|--------|
+| Stage compliance | 15% |
+| TDD compliance | 15% |
+| Design-first compliance | 10% |
+| Approval compliance | 10% |
+| Review quality | 10% |
+| Handoff quality | 10% |
+| Budget efficiency | 10% |
+| Tool reliability | 10% |
+| Policy compliance | 5% |
+| Override frequency | 5% |
+
+Scorecards support trend analysis over time. Use `getScorecardTrend(dir, command)` and `computeAverageScore(dir)` from `src/services/workflow-scorecard.ts` to query them programmatically.
+
+---
+
 
 Each intelligence feature also has a corresponding skill that gives the OpenCode agent detailed workflow instructions. Skills are installed automatically by `install.sh`.
 

package/docs/multi-repo.md

@@ -180,7 +180,7 @@ The `multi-repo-flow` workflow orchestrates the full end-to-end process:
 1. **Analyze** — `@code-explorer` runs in each registered repo and builds a combined dependency graph
 2. **Classify** — `@multi-repo-coordinator` identifies which changes are breaking vs non-breaking and determines service change order
 3. **Plan** — produces a CHANGE PLAN per repo in dependency order
-4. **Execute** — `@coder` is invoked per repo in order; `@tester` runs per repo in parallel with `@coder` (using that repo's test suite)
+4. **Execute** — role-routed implementation agent (`@backend-coder`/`@frontend-coder`/`@devops`) is invoked per repo in order; `@tester` runs per repo in parallel with the selected implementation agent (using that repo's test suite)
 5. **Verify** — `@reviewer` and `@security-auditor` run per repo after implementation; integration tests are run across the full service mesh in staging before any production rollout
 
 Each step produces output files in `.planning/fd-multi-repo/` so the entire process is auditable.

package/docs/rules.md

@@ -111,7 +111,7 @@ Governs how FlowDeck agents are selected and coordinated.
 - **Run `@task-splitter` before `/fd-new-feature` on large scope.** If a feature description spans more than a few hours of work, invoke `@task-splitter` first to break it into independent sub-features. Attempting to implement large scope in one `/fd-new-feature` call produces lower-quality output.
 - **`@reviewer` is mandatory before merge.** Every code-producing command (`/fd-new-feature`, `/fd-fix-bug`) must be followed by at least one `@reviewer` pass. This is enforced when guard mode is enabled in `.planning/config.json`.
 - **`@security-auditor` is mandatory for auth, payment, and PII code.** Any change to authentication flows, payment processing, or code that stores or transmits personally identifiable information must be audited by `@security-auditor` before merge — regardless of the change size.
-- **Wave gates are not optional.** In parallel execution, Wave 3 (`@coder` + `@tester`) must not begin until Wave 2 (`@architect`) has produced its output. Starting implementation before design is complete produces rework.
+- **Wave gates are not optional.** In parallel execution, Wave 3 (`@backend-coder` + `@tester`) must not begin until Wave 2 (`@architect`) has produced its output. Starting implementation before design is complete produces rework.
 
 ---
 

package/docs/skills.md

@@ -26,21 +26,30 @@ For example: `@tester use the tdd-workflow skill to add tests for the payments m
 | `context-load` | Efficient session start: load STATE.md, PLAN.md, PROJECT.md | Any agent at session start |
 | `debug-flow` | 6-step debug sequence: reproduce → trace → test → fix → verify | `@debug-specialist`, `@tester` |
 | `dependency-audit` | CVE scanning, license compliance, outdated package detection | `@security-auditor`, `@reviewer` |
+| `design-audit` | UI fidelity audit against approved design artifacts | `@design`, `@reviewer` |
+| `ui-ux-planning` | UX flow and structure planning before implementation | `@design` |
+| `wireframe-planning` | Wireframe-level layout and section planning | `@design` |
+| `design-system-definition` | Token and component behavior guidance | `@design`, `@backend-coder` |
+| `frontend-handoff` | Convert design outputs into implementation checklist | `@design`, `@backend-coder` |
+| `responsive-review` | Responsive behavior and breakpoint review | `@design`, `@reviewer` |
+| `dashboard-design` | Dashboard-specific hierarchy and data-density patterns | `@design` |
+| `landing-page-design` | Conversion-oriented landing page structure | `@design` |
+| `app-shell-design` | App shell and navigation model design | `@design` |
 | `deploy-check` | Pre-deployment go/no-go checklist | `@orchestrator`, `@security-auditor` |
 | `documentation-writer` | Technical writing standards for READMEs, API docs, changelogs | `@writer`, `@doc-updater` |
 | `git-release` | Semantic versioning, changelog generation, release tagging | `@writer`, `@orchestrator` |
-| `git-workflow` | Conventional commits, branching strategy, PR standards | `@coder`, `@orchestrator` |
-| `golang-patterns` | Idiomatic Go: error handling, goroutines, interfaces, testing | `@coder`, `@reviewer` |
-| `java-patterns` | Modern Java 17+: records, Spring Boot, JPA, CompletableFuture | `@coder`, `@reviewer` |
+| `git-workflow` | Conventional commits, branching strategy, PR standards | `@backend-coder`, `@orchestrator` |
+| `golang-patterns` | Idiomatic Go: error handling, goroutines, interfaces, testing | `@backend-coder`, `@reviewer` |
+| `java-patterns` | Modern Java 17+: records, Spring Boot, JPA, CompletableFuture | `@backend-coder`, `@reviewer` |
 | `multi-repo` | Cross-repo dependency graphs, contract-first changes, ordered rollouts | `@multi-repo-coordinator`, `@architect` |
-| `parallel-execute` | Wave-based parallel task coordination and merge protocol | `@parallel-coordinator`, `@task-splitter` |
+| `parallel-execute` | Wave-based parallel task coordination and merge protocol | `@orchestrator`, `@task-splitter` |
 | `performance-profiling` | Profiling methodology, bottleneck identification, before/after measurement | `@performance-optimizer` |
 | `plan-task` | Wave-structured task planning with dependency graph and success criteria | `@planner`, `@planner` |
-| `python-patterns` | Python 3.10+: type hints, dataclasses, asyncio, pytest | `@coder`, `@reviewer` |
-| `refactor-guide` | Safe refactoring: tests-first, one transformation per commit | `@refactor-guide`, `@coder` |
-| `rust-patterns` | Ownership, traits, async/Tokio, error handling, smart pointers | `@coder`, `@reviewer` |
+| `python-patterns` | Python 3.10+: type hints, dataclasses, asyncio, pytest | `@backend-coder`, `@reviewer` |
+| `refactor-guide` | Safe refactoring: tests-first, one transformation per commit | `@refactor-guide`, `@backend-coder` |
+| `rust-patterns` | Ownership, traits, async/Tokio, error handling, smart pointers | `@backend-coder`, `@reviewer` |
 | `security-scan` | OWASP-based scanning, severity classification, PASS/FAIL verdict | `@security-auditor`, `@reviewer` |
-| `tdd-workflow` | Red-Green-Refactor cycle, AAA pattern, 80% coverage target | `@tester`, `@coder` |
+| `tdd-workflow` | Red-Green-Refactor cycle, AAA pattern, 80% coverage target | `@tester`, `@backend-coder` |
 | `test-coverage` | Coverage gap analysis, TDD enforcement, write-test-first cycle | `@tester`, `@reviewer` |
 
 ---
@@ -178,7 +187,7 @@ Idiomatic Python 3.10+ patterns for production code: type hints with `TypeVar` a
 
 **Example invocation:**
 ```
-@coder Use the python-patterns skill to implement the data pipeline.
+@backend-coder Use the python-patterns skill to implement the data pipeline.
        Prefer dataclasses for the value objects and asyncio for IO operations.
 ```
 
@@ -192,7 +201,7 @@ Idiomatic Go for production services: explicit error handling with wrapped error
 
 **Example invocation:**
 ```
-@coder Use the golang-patterns skill to implement the worker pool.
+@backend-coder Use the golang-patterns skill to implement the worker pool.
        Use proper goroutine lifecycle management and context cancellation.
 ```
 
@@ -206,7 +215,7 @@ Modern Java 17+ patterns for production applications: records for immutable valu
 
 **Example invocation:**
 ```
-@coder Use the java-patterns skill to implement the OrderService.
+@backend-coder Use the java-patterns skill to implement the OrderService.
        Use records for the command objects and constructor injection for dependencies.
 ```
 
@@ -220,7 +229,7 @@ Safe, idiomatic Rust: ownership and borrowing mental model (own vs borrow vs bor
 
 **Example invocation:**
 ```
-@coder Use the rust-patterns skill to implement the async HTTP client.
+@backend-coder Use the rust-patterns skill to implement the async HTTP client.
        Use Tokio and ensure proper error propagation with the ? operator.
 ```
 
@@ -308,7 +317,7 @@ Branching strategy (feature branches from `main`, naming convention `feat/`, `fi
 
 **Example invocation:**
 ```
-@coder Use the git-workflow skill to commit the authentication changes.
+@backend-coder Use the git-workflow skill to commit the authentication changes.
        Write a conventional commit message and create the PR.
 ```
 
@@ -380,8 +389,8 @@ Coordinates parallel agent execution for independent workstreams. Provides the W
 
 **Example invocation:**
 ```
-@parallel-coordinator Use the parallel-execute skill to run Wave 3 of the current plan.
-                      @coder and @tester are independent — start both simultaneously.
+@orchestrator Use the parallel-execute skill to run Wave 3 of the current plan.
+                      @backend-coder and @tester are independent — start both simultaneously.
 ```
 
 **When to use:** When a plan has tasks that can run simultaneously. The skill makes independence explicit so merge conflicts are caught before they occur.

package/docs/workflows.md

@@ -20,7 +20,9 @@ FlowDeck commands are the single entry point for all operations. Each command em
 /fd-discuss      →  .planning/phases/phase-N/DISCUSS.md  (locked decisions)
      ↓
 /fd-plan         →  .planning/phases/phase-N/PLAN.md     (confirmed plan)
-     ↓
+    ↓
+/fd-design       →  design artifact + approval + handoff (UI-heavy tasks only)
+    ↓
 /fd-execute      →  implemented, tested, reviewed code (via TDD)
      ↓
 /fd-verify       →  verification report (tests, review, security, deploy check)
@@ -28,7 +30,7 @@ FlowDeck commands are the single entry point for all operations. Each command em
 /fd-checkpoint   →  .planning/STATE.md saved
 ```
 
-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.
+Each step gates the next. `/fd-discuss` requires a defined feature. `/fd-plan` requires confirmed decisions from `DISCUSS.md`. `/fd-design` is mandatory for UI-heavy tasks unless explicitly overridden. `/fd-execute` requires a confirmed `PLAN.md` and (for UI-heavy tasks) approved design handoff. `/fd-verify` confirms all checks pass before marking the feature as complete.
 
 ---
 
@@ -41,10 +43,11 @@ Each step gates the next. `/fd-discuss` requires a defined feature. `/fd-plan` r
 | `/fd-new-feature` | Initialize a new feature | @orchestrator |
 | `/fd-discuss` | Pre-planning discussion | @discusser |
 | `/fd-plan` | Generate a phase plan | @planner, @plan-checker |
+| `/fd-design` | Run design-first planning/review/system modes | @design |
 | `/fd-ask` | Smart agent dispatch | various |
-| `/fd-execute` | Implement feature via TDD | @orchestrator, @coder, @tester, @reviewer |
+| `/fd-execute` | Implement feature via TDD | @orchestrator, @backend-coder/@frontend-coder/@devops, @tester, @reviewer |
 | `/fd-verify` | Verify feature completion | @tester, @reviewer, @security-auditor |
-| `/fd-fix-bug` | Fix a bug with TDD | @debug-specialist, @tester, @coder |
+| `/fd-fix-bug` | Fix a bug with TDD | @debug-specialist, @tester, @backend-coder/@frontend-coder/@devops |
 | `/fd-write-docs` | Generate documentation | @writer, @reviewer |
 | `/fd-deploy-check` | Pre-deploy safety check | @tester, @security-auditor, @reviewer |
 | `/fd-status` | View project progress | — |
@@ -53,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 | @coder or selected specialist |
+| `/fd-quick` | Fast focused task execution | @backend-coder/@frontend-coder/@devops or selected specialist |
 | `/fd-reflect` | Post-session reflection and skill capture | @auto-learner |
 | `/fd-doctor` | Installation and environment diagnostics | @orchestrator |
 
@@ -115,7 +118,9 @@ argument-hint: [args]
 |-------|---------|
 | @orchestrator | Coordinates multi-step workflows |
 | @planner | Creates implementation plans |
-| @coder | Implements code changes |
+| @backend-coder | Implements backend code changes |
+| @frontend-coder | Implements frontend code changes |
+| @devops | Implements infrastructure and operations changes |
 | @tester | Writes and runs tests |
 | @reviewer | Reviews code quality |
 | @researcher | Investigates and provides context |

package/package.json

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

package/src/commands/fd-ask.md

@@ -15,6 +15,7 @@ Analyze `$ARGUMENTS` to determine the best specialist:
 
 | Keywords / Topic | Agent |
 |-----------------|-------|
+| ui, ux, wireframe, landing page, dashboard, admin panel, app screen, design system | **@design** |
 | design, architecture, structure, system, component, API | **@architect** |
 | security, auth, vulnerability, token, permission, injection | **@security-auditor** |
 | performance, speed, slow, optimize, latency, cache, memory | **@performance** |