@dv.nghiem/flowdeck 0.3.3 → 0.3.5

package/docs/agents.md

@@ -6,7 +6,7 @@ Agents are specialized AI personas installed into OpenCode. Each agent has a foc
 
 ```
 @architect Design the database schema for a multi-tenant SaaS app
-@coder Implement the UserRepository class following the interface in src/interfaces/
+@backend-coder Implement the UserRepository class following the interface in src/interfaces/
 @reviewer Review src/auth/jwt.ts for security issues
 ```
 
@@ -21,8 +21,11 @@ Agents are installed to `~/.config/opencode/agent/`. OpenCode loads them automat
 | [@architect](#architect) | Designs system architecture, creates ADRs, defines interface contracts | New modules, API design, schema changes, cross-cutting concerns |
 | [@build-error-resolver](#build-error-resolver) | Diagnoses and fixes build failures, type errors, and dependency issues | Broken builds, type mismatches, missing modules |
 | [@code-explorer](#code-explorer) | Reads and maps unfamiliar codebases systematically | Understanding unknown code before modifying it |
-| [@coder](#coder) | Implements features and fixes following confirmed plans | All code implementation tasks |
+| [@backend-coder](#backend-coder) | Implements backend features and fixes following confirmed plans | API, service, data-layer implementation |
+| [@frontend-coder](#frontend-coder) | Implements frontend features and fixes following confirmed plans | UI components, client state, interaction behavior |
+| [@devops](#devops) | Implements infrastructure and delivery changes following confirmed plans | CI/CD, deployment, infra and operations |
 | [@debug-specialist](#debug-specialist) | Root cause analysis via hypothesis-driven investigation | Deep bugs that require systematic tracing |
+| [@design](#design) | Runs design-first UI workflow with structured handoff artifacts | Landing pages, dashboards, admin panels, app screens, UX-heavy features |
 | [@discusser](#discusser) | Structured requirements Q&A, one question at a time | Starting new projects, defining feature scope |
 | [@doc-updater](#doc-updater) | Keeps documentation in sync with code changes | Post-implementation doc maintenance |
 | [@plan-checker](#plan-checker) | Validates plans before execution for completeness and feasibility | Quality gate before running a plan |
@@ -30,7 +33,6 @@ Agents are installed to `~/.config/opencode/agent/`. OpenCode loads them automat
 | [@mapper](#mapper) | Maps codebase to `.codebase/` structured documentation | Producing STACK.md, ARCHITECTURE.md, CONVENTIONS.md, and more |
 | [@multi-repo-coordinator](#multi-repo-coordinator) | Cross-repo dependency graphs, change propagation, ordered CHANGE PLANs | Features spanning multiple microservices |
 | [@orchestrator](#orchestrator) | Coordinates multi-agent workflows, phase gating, go/no-go decisions | End-to-end feature delivery |
-| [@parallel-coordinator](#parallel-coordinator) | Wave-based parallel execution with WAVE TABLE format and merge protocol | Maximizing throughput on complex tasks |
 | [@performance-optimizer](#performance-optimizer) | Profiling-first bottleneck identification and targeted fixes | Slow endpoints, N+1 queries, bundle bloat |
 | [@planner](#planner) | Implementation planning with explicit user confirmation before execution | Planning any multi-file feature |
 | [@refactor-guide](#refactor-guide) | Safe refactoring with test-first guarantees, preserves external behavior | Cleanup, extraction, debt reduction |
@@ -43,13 +45,33 @@ Agents are installed to `~/.config/opencode/agent/`. OpenCode loads them automat
 
 ---
 
+### @design
+
+The design agent is a dedicated UI/UX specialist that runs before implementation on UI-heavy tasks. It outputs structured design artifacts covering discovery, UX flow, wireframe layout, visual system direction, and frontend handoff checklist. For existing implementations, it performs design fidelity review and reports hierarchy, spacing, responsiveness, accessibility, and state-coverage gaps.
+
+**Best for:**
+- Classifying user-facing task types (landing page, dashboard, admin panel, app screen)
+- Producing implementation-ready UI handoff before coding starts
+- Reviewing UI output against approved design artifacts during verification
+- Defining reusable token/component guidance for consistency
+
+**Example usage:**
+```
+@design Run design-first workflow for: redesign onboarding dashboard.
+        Output structured handoff artifact with approval checklist.
+```
+
+**Works with:** `@backend-coder` (consumes handoff artifact), `@reviewer` (code-quality + design-fidelity checks), `@orchestrator` (enforces design gate before implementation)
+
+---
+
 ## Detailed Agent Profiles
 
 ### @architect
 
 The architect designs systems before anyone writes code. It reads existing architecture documents and conventions first, then proposes decisions in writing — as ADRs and TypeScript interface contracts — before any implementation begins. It applies principles like "no speculative abstraction" (only abstract when there are 3+ concrete use cases) and surfaces conflicts with existing decisions rather than resolving them silently.
 
-**Model:** `anthropic/claude-opus-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Designing database schemas, API boundaries, and service interfaces for new features
@@ -63,7 +85,7 @@ The architect designs systems before anyone writes code. It reads existing archi
            Read .codebase/ARCHITECTURE.md first. Save the ADR to .planning/adr/.
 ```
 
-**Works with:** `@coder` (consumes interface contracts), `@planner` (uses ADRs as planning input), `@multi-repo-coordinator` (defines contract-first change specs)
+**Works with:** `@backend-coder` (consumes interface contracts), `@planner` (uses ADRs as planning input), `@multi-repo-coordinator` (defines contract-first change specs)
 
 ---
 
@@ -71,7 +93,7 @@ The architect designs systems before anyone writes code. It reads existing archi
 
 The build error resolver collects all build errors before touching a single file. It runs the full diagnostic suite (`tsc --noEmit`, build, lint, tests) and reads the complete output — never skims — because the first error is almost always the root cause and later errors are cascades. It applies the minimum fix to resolve the root cause, then re-runs to confirm no cascades remain.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Diagnosing TypeScript type errors, missing modules, and circular imports
@@ -85,7 +107,7 @@ The build error resolver collects all build errors before touching a single file
                       and fix the root cause with minimal changes.
 ```
 
-**Works with:** `@coder` (applies fixes identified by the resolver), `@orchestrator` (escalates build failures during plan execution), `@reviewer` (verifies fix quality)
+**Works with:** `@backend-coder` (applies fixes identified by the resolver), `@orchestrator` (escalates build failures during plan execution), `@reviewer` (verifies fix quality)
 
 ---
 
@@ -93,13 +115,13 @@ The build error resolver collects all build errors before touching a single file
 
 The code explorer maps unfamiliar code before anyone modifies it. It is read-only by design — it reports what it finds, not what it expects. Starting from the top-level directory, it traces entry points and call paths, identifies key abstractions and data models, and documents conventions in use. Its output gives other agents the context they need to make surgical changes.
 
-**Model:** `anthropic/claude-haiku-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Understanding a new module or service before making changes to it
 - Tracing a specific flow end-to-end (e.g., HTTP request to database to response)
 - Identifying where in the codebase a task-relevant piece of logic lives
-- Feeding structural context to `@architect` or `@coder` before implementation
+- Feeding structural context to `@architect` or `@backend-coder` before implementation
 
 **Example usage:**
 ```
@@ -107,28 +129,57 @@ The code explorer maps unfamiliar code before anyone modifies it. It is read-onl
               route handler to the database query. Identify the session management approach.
 ```
 
-**Works with:** `@architect` (provides structural context for design decisions), `@coder` (surfaces conventions to match), `@mapper` (complements deeper .codebase/ documentation)
+**Works with:** `@architect` (provides structural context for design decisions), `@backend-coder` (surfaces conventions to match), `@mapper` (complements deeper .codebase/ documentation)
 
 ---
 
-### @coder
+### @backend-coder
 
-The coder implements features and fixes following a confirmed plan. It reads conventions and architecture docs before touching any source file, matches existing patterns precisely, and makes only the changes the task requires — no drive-by refactors. Functions stay under 50 lines. Every external input is validated at the boundary. If the plan is unclear or technically infeasible, it stops and asks rather than guessing.
+The backend-coder implements features and fixes following a confirmed plan. It reads conventions and architecture docs before touching any source file, matches existing patterns precisely, and makes only the changes the task requires — no drive-by refactors. Functions stay under 50 lines. Every external input is validated at the boundary. If the plan is unclear or technically infeasible, it stops and asks rather than guessing.
 
-**Model:** `anthropic/claude-opus-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
-- Implementing any feature step once a plan has been confirmed
-- Applying fixes identified by `@debug-specialist` or `@build-error-resolver`
-- Executing a single wave of a parallel execution plan
-- Making surgical changes to existing code with minimal diff surface area
+- Implementing API handlers, services, repositories, and data-model changes
+- Applying backend fixes identified by `@debug-specialist` and `@build-error-resolver`
+- Delivering plan-scoped server-side functionality with minimal diffs
 
 **Example usage:**
 ```
-@coder Implement the UserRepository class defined in contracts/user-repository.ts.
+@backend-coder Implement the UserRepository class defined in contracts/user-repository.ts.
        Follow patterns in src/repositories/order-repository.ts. No new dependencies.
 ```
 
+**Works with:** `@tester` (verifies implementation), `@reviewer` (reviews the diff), `@architect` (provides interface contracts)
+
+---
+
+### @frontend-coder
+
+The frontend-coder implements frontend features and fixes following a confirmed plan. It focuses on user-facing behavior, component architecture, state transitions, accessibility, and visual consistency with existing patterns.
+
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
+
+---
+
+### @devops
+
+The devops agent implements infrastructure and operational changes from confirmed plans. It focuses on CI/CD workflows, build and deploy automation, runtime configuration, and safe rollout practices.
+
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
+
+**Best for:**
+- Implementing CI/CD workflow changes, deployment config updates, and environment setup
+- Applying infra and runtime remediations identified by `@debug-specialist` or `@build-error-resolver`
+- Automating release pipelines and operational scripts with minimal blast radius
+- Managing build/deploy reliability improvements and rollback-safe changes
+
+**Example usage:**
+```
+@devops Update the deployment workflow to add smoke tests before production release.
+        Keep rollback steps explicit and preserve existing release gates.
+```
+
 **Works with:** `@tester` (verifies implementation), `@reviewer` (reviews the diff), `@architect` (consumes interface contracts)
 
 ---
@@ -137,7 +188,7 @@ The coder implements features and fixes following a confirmed plan. It reads con
 
 The debug specialist finds root causes through systematic investigation — never by guessing. It reads the full stack trace from top to bottom, traces execution backward from the point of failure, and identifies the earliest point in the call chain where invariants are violated. For regressions, it uses `git bisect` to identify the culprit commit. It produces a structured debug report before any fix is proposed.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Diagnosing intermittent failures, race conditions, and memory leaks
@@ -151,7 +202,7 @@ The debug specialist finds root causes through systematic investigation — neve
                   alongside a loyalty credit. Trace the calculation path and identify the root cause.
 ```
 
-**Works with:** `@tester` (writes the regression test once root cause is confirmed), `@coder` (applies the minimal fix), `@build-error-resolver` (handles compile-time failures the debug specialist doesn't cover)
+**Works with:** `@tester` (writes the regression test once root cause is confirmed), `@backend-coder` (applies the minimal fix), `@build-error-resolver` (handles compile-time failures the debug specialist doesn't cover)
 
 ---
 
@@ -159,7 +210,7 @@ The debug specialist finds root causes through systematic investigation — neve
 
 The discusser extracts clear requirements through focused, one-at-a-time questioning. It never asks two questions in a single turn. Every decision is numbered (D-01, D-02, ...) and recorded with its rationale. If a new answer conflicts with a previous decision, it flags the conflict immediately and presents options. All decisions are saved to `.planning/phases/phase-N/DISCUSS.md` in a format that `@planner` can trace back to individual tasks.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Defining the scope of a new project or feature phase before planning begins
@@ -181,7 +232,7 @@ The discusser extracts clear requirements through focused, one-at-a-time questio
 
 The doc updater synchronizes documentation with the current implementation after code changes. It targets README installation instructions, API reference function signatures, inline comments on complex algorithms, and changelog entries under `## Unreleased`. It verifies that every example it writes actually compiles and runs. Dead links and dead examples are removed, not left behind.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Updating API reference docs after function signatures change
@@ -203,7 +254,7 @@ The doc updater synchronizes documentation with the current implementation after
 
 The plan checker reviews a PLAN.md before execution and returns a scored PASS or FAIL verdict. It checks three dimensions: completeness (all requirements from DISCUSS.md are covered, every task has a defined scope and success criteria), feasibility (no task exceeds 3 hours, no circular dependencies, no assumed capabilities that don't exist), and testability (each success criterion is observable, edge cases are addressed, verification commands are specified). A score of 8–10 earns PASS, 6–7 earns PASS_WITH_NOTES, and 0–5 earns FAIL.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Catching vague success criteria before they cause ambiguous execution
@@ -223,13 +274,13 @@ The plan checker reviews a PLAN.md before execution and returns a scored PASS or
 
 The mapper produces factual codebase documentation for the `.codebase/` directory. In a parallel run of 6 instances, each mapper is assigned one output file: `STACK.md`, `ARCHITECTURE.md`, `STRUCTURE.md`, `CONVENTIONS.md`, `TESTING.md`, or `CONCERNS.md`. It reads source files directly and reports only what it can verify — any gap is marked `UNKNOWN — needs verification` rather than filled with assumptions. Every claim is traceable to a specific file path.
 
-**Model:** `google/gemini-2.5-flash`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Generating `.codebase/CONVENTIONS.md` with real naming patterns backed by file:line examples
 - Producing `STACK.md` with exact pinned versions from manifest files
 - Populating `CONCERNS.md` by grepping for `TODO`, `FIXME`, and `HACK` markers
-- Running in parallel with 5 other mapper instances via `@parallel-coordinator`
+- Running in parallel with 5 other mapper instances via `@orchestrator`
 
 **Example usage:**
 ```
@@ -245,7 +296,7 @@ The mapper produces factual codebase documentation for the `.codebase/` director
 
 The multi-repo coordinator manages change propagation across a microservice architecture. It reads the sub-repo registry from `.planning/config.json`, builds a dependency graph (upstream-api → downstream-consumer → gateway order), detects conflicts between concurrent service changes, and produces a per-repo CHANGE PLAN ordered by that graph. API contracts are defined first; implementation follows in dependency order so upstream services always deploy before their consumers.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Coordinating a feature that requires changes across two or more services
@@ -260,7 +311,7 @@ The multi-repo coordinator manages change propagation across a microservice arch
                         an ordered CHANGE PLAN.
 ```
 
-**Works with:** `@architect` (defines contract-first change specs), `@coder` (implements changes per repo), `@tester` (verifies cross-repo integration)
+**Works with:** `@architect` (defines contract-first change specs), `@backend-coder` (implements changes per repo), `@tester` (verifies cross-repo integration)
 
 ---
 
@@ -268,7 +319,7 @@ The multi-repo coordinator manages change propagation across a microservice arch
 
 The orchestrator coordinates multi-agent execution for feature delivery. At startup it reads STATE.md and the active PLAN.md, identifies the first incomplete step, delegates it to the appropriate specialist, waits for completion, marks progress, and advances to the next step. It enforces phase gating — execution only proceeds when DISCUSS.md and PLAN.md are confirmed. If a delegated agent fails after one retry, it escalates to the user with specific options rather than continuing silently.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Running `/fd-new-feature` to drive an end-to-end feature delivery cycle
@@ -282,37 +333,16 @@ The orchestrator coordinates multi-agent execution for feature delivery. At star
               phase. Delegate incomplete steps in order and mark each complete.
 ```
 
-**Works with:** `@orchestrator` (executes plan steps), `@plan-checker` (validates plans before execution), `@parallel-coordinator` (delegates parallel waves)
+**Works with:** `@plan-checker` (validates plans before execution), `@task-splitter` (decomposes work into safe parallel waves), `@backend-coder`/`@frontend-coder`/`@devops` (executes routed implementation tasks)
 
 ---
 
-### @parallel-coordinator
-
-The parallel coordinator maximizes throughput by running independent work simultaneously in waves. At the start of every job it emits a WAVE TABLE — a formatted table showing every agent slot and its wave dependencies. It delegates agents by wave, waits for each wave to complete before advancing, and runs a merge protocol when parallel tracks touch overlapping areas. The standard wave structure is: Wave 1 (research + exploration), Wave 2 (architecture, serial), Wave 3 (implementation + tests), Wave 4 (review + security).
-
-**Model:** `anthropic/claude-sonnet-4-5`
-
-**Best for:**
-- Executing a plan where multiple tasks are provably independent of each other
-- Running `@researcher` and `@code-explorer` simultaneously before `@architect` begins
-- Running `@coder` and `@tester` in parallel from `@architect`'s contracts
-- Resolving merge conflicts when two implementation tracks touched the same file
-
-**Example usage:**
-```
-@parallel-coordinator Execute the PLAN.md using wave-based parallel execution.
-                      Emit the WAVE TABLE first, then delegate agents wave by wave.
-```
-
-**Works with:** `@orchestrator` (delegates parallel waves to this agent), `@task-splitter` (produces the wave breakdown this agent executes), `@coder` + `@tester` (run in parallel in Wave 3)
-
----
 
 ### @performance-optimizer
 
 The performance optimizer identifies and fixes performance bottlenecks using data, never intuition. It always measures before optimizing: Node.js profiler, `webpack-bundle-analyzer`, `EXPLAIN ANALYZE`, or Lighthouse depending on the target. It reports findings as before/after numbers. It never proposes a speculative optimization — only improvements justified by profiling output. It targets Core Web Vitals thresholds (LCP < 2.5s, FID < 100ms) and common patterns like N+1 queries and O(n²) algorithms.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Diagnosing slow API endpoints using `EXPLAIN ANALYZE` on the database queries
@@ -326,7 +356,7 @@ The performance optimizer identifies and fixes performance bottlenecks using dat
                        queries and identify the bottleneck. Show before/after numbers.
 ```
 
-**Works with:** `@coder` (implements optimizations once bottleneck is confirmed), `@tester` (writes benchmarks to verify improvement), `@reviewer` (checks that optimizations don't introduce bugs)
+**Works with:** `@backend-coder` (implements optimizations once bottleneck is confirmed), `@tester` (writes benchmarks to verify improvement), `@reviewer` (checks that optimizations don't introduce bugs)
 
 ---
 
@@ -334,13 +364,13 @@ The performance optimizer identifies and fixes performance bottlenecks using dat
 
 The planner creates detailed, file-level implementation plans with an explicit user confirmation gate before any code is written. It reads ARCHITECTURE.md and existing conventions first, extracts both explicit and implicit requirements, orders steps by dependency (data models → schema → repository → service → API → tests → UI → docs), and flags risks. After presenting the plan it pauses and waits for the user to confirm before execution begins.
 
-**Model:** `anthropic/claude-opus-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Planning any feature that spans more than two files before writing code
 - Identifying architecture conflicts and unknowns that would block implementation
 - Ordering implementation steps so foundation code is in place before dependent code
-- Generating a plan that feeds directly into `@coder`'s execution
+- Generating a plan that feeds directly into `@backend-coder`'s execution
 
 **Example usage:**
 ```
@@ -349,7 +379,7 @@ The planner creates detailed, file-level implementation plans with an explicit u
          Pause for my confirmation before we proceed.
 ```
 
-**Works with:** `@architect` (provides interface contracts and ADRs that feed the plan), `@coder` (executes the confirmed plan), `@planner` (alternative for structured FlowDeck plan format)
+**Works with:** `@architect` (provides interface contracts and ADRs that feed the plan), `@backend-coder` (executes the confirmed plan), `@planner` (alternative for structured FlowDeck plan format)
 
 ---
 
@@ -357,7 +387,7 @@ The planner creates detailed, file-level implementation plans with an explicit u
 
 The refactor guide changes code structure without changing observable behavior. It requires a green test suite before starting and verifies the suite stays green after every single transformation. Each transformation is committed independently with a `refactor:` prefix — never batched. It stops immediately if a test breaks and looks for a smaller step. It covers extract-function, rename, move-module, inline-variable, and similar low-risk catalog transforms, ordered from lowest to highest risk.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Extracting functions from files over 50 lines or 800 lines
@@ -372,7 +402,7 @@ The refactor guide changes code structure without changing observable behavior.
                 One commit per transformation.
 ```
 
-**Works with:** `@tester` (confirms suite is green before and after each step), `@coder` (applies transformations), `@mapper` (identifies refactoring candidates across the codebase)
+**Works with:** `@tester` (confirms suite is green before and after each step), `@backend-coder` (applies transformations), `@mapper` (identifies refactoring candidates across the codebase)
 
 ---
 
@@ -380,10 +410,10 @@ The refactor guide changes code structure without changing observable behavior.
 
 The researcher finds accurate, cited information before anyone writes code. It searches Context7 first for up-to-date library documentation, then vendor docs, then package registries. Every fact is paired with its source URL. It never cites StackOverflow as a primary source and never fabricates API documentation — if it cannot find an authoritative source, it says so explicitly. Output follows a structured format covering "what it is", "how to use it", and "gotchas".
 
-**Model:** `openai/gpt-4o`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
-- Documenting an unfamiliar library's API before `@coder` uses it
+- Documenting an unfamiliar library's API before `@backend-coder` uses it
 - Comparing two libraries (e.g., `zod` vs `joi`) with concrete tradeoffs cited from official sources
 - Finding the correct pagination API, error response format, or auth flow for an external service
 - Identifying breaking changes between library versions that affect the implementation plan
@@ -394,7 +424,7 @@ The researcher finds accurate, cited information before anyone writes code. It s
             webhook event types, and how to handle failed payments. Cite official Stripe docs.
 ```
 
-**Works with:** `@coder` (receives research output before implementation), `@architect` (uses library capability research to inform interface design), `@parallel-coordinator` (runs in parallel with `@code-explorer` in Wave 1)
+**Works with:** `@backend-coder` (receives research output before implementation), `@architect` (uses library capability research to inform interface design), `@orchestrator` (runs in parallel with `@code-explorer` in Wave 1)
 
 ---
 
@@ -402,7 +432,7 @@ The researcher finds accurate, cited information before anyone writes code. It s
 
 The reviewer checks code for correctness, security, and adherence to project conventions. It reads full files — not just the diff — to understand call context. It applies an 80% confidence threshold before flagging an issue: speculation is not a finding. Findings are classified as CRITICAL, HIGH, MEDIUM, or PASS. It checks for hardcoded credentials, SQL injection, XSS, missing auth middleware, improper error handling, and convention violations.
 
-**Model:** `google/gemini-2.5-flash`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Reviewing a pull request before it is merged
@@ -416,15 +446,15 @@ The reviewer checks code for correctness, security, and adherence to project con
           missing auth middleware, and convention adherence. Report by severity.
 ```
 
-**Works with:** `@security-auditor` (runs in parallel for deeper security coverage), `@orchestrator` (receives review verdict and decides whether to advance phase), `@coder` (receives actionable findings and applies fixes)
+**Works with:** `@security-auditor` (runs in parallel for deeper security coverage), `@orchestrator` (receives review verdict and decides whether to advance phase), `@backend-coder` (receives actionable findings and applies fixes)
 
 ---
 
 ### @security-auditor
 
-The security auditor performs deep security audits against the OWASP Top 10. It checks for injection vulnerabilities (SQL, NoSQL, command, LDAP, template), broken access control (missing ownership checks, role bypasses), cryptographic failures (MD5/SHA1 for passwords, plaintext secrets), and dependency risks (known CVEs). It produces a PASS/FAIL report with severity classification and specific remediation steps. It does not apply fixes — that is `@coder`'s responsibility.
+The security auditor performs deep security audits against the OWASP Top 10. It checks for injection vulnerabilities (SQL, NoSQL, command, LDAP, template), broken access control (missing ownership checks, role bypasses), cryptographic failures (MD5/SHA1 for passwords, plaintext secrets), and dependency risks (known CVEs). It produces a PASS/FAIL report with severity classification and specific remediation steps. It does not apply fixes — that is `@backend-coder`'s responsibility.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Auditing authentication and authorization code before merging security-sensitive PRs
@@ -438,18 +468,18 @@ The security auditor performs deep security audits against the OWASP Top 10. It
                   and A02 (cryptographic failures). Return PASS or FAIL with severity classification.
 ```
 
-**Works with:** `@reviewer` (parallel review partner), `@coder` (applies remediations after audit findings), `@orchestrator` (aggregates audit result into go/no-go decision)
+**Works with:** `@reviewer` (parallel review partner), `@backend-coder` (applies remediations after audit findings), `@orchestrator` (aggregates audit result into go/no-go decision)
 
 ---
 
 ### @task-splitter
 
-The task splitter decomposes complex tasks into independent parallel workstreams. It reads a feature description or PLAN.md, builds a dependency graph, groups tasks into waves where each wave's work is provably independent, and emits a structured parallel execution plan that `@parallel-coordinator` can execute directly. Each track includes: assigned agent, target files, specific task, and a verifiable completion criterion.
+The task splitter decomposes complex tasks into independent parallel workstreams. It reads a feature description or PLAN.md, builds a dependency graph, groups tasks into waves where each wave's work is provably independent, and emits a structured parallel execution plan that `@orchestrator` can execute directly. Each track includes: assigned agent, target files, specific task, and a verifiable completion criterion.
 
-**Model:** `anthropic/claude-sonnet-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
-- Breaking a large feature into parallel workstreams before handing off to `@parallel-coordinator`
+- Breaking a large feature into parallel workstreams before handing off to `@orchestrator`
 - Identifying which tasks must be serial (dependency gates) versus truly independent
 - Sizing and scoping tasks so each fits within a single agent session
 - Producing a wave plan when `@planner` is unavailable or overkill
@@ -461,7 +491,7 @@ The task splitter decomposes complex tasks into independent parallel workstreams
                Produce a WAVE TABLE with agent assignments.
 ```
 
-**Works with:** `@parallel-coordinator` (executes the wave plan produced by this agent), `@orchestrator` (uses task breakdown to coordinate execution), `@planner` (complementary — planner creates PLAN.md format, splitter focuses on parallelization)
+**Works with:** `@orchestrator` (executes the wave plan produced by this agent), `@orchestrator` (uses task breakdown to coordinate execution), `@planner` (complementary — planner creates PLAN.md format, splitter focuses on parallelization)
 
 ---
 
@@ -469,11 +499,11 @@ The task splitter decomposes complex tasks into independent parallel workstreams
 
 The tester writes tests that drive implementation using strict Red-Green-Refactor TDD. Tests are written before the code that makes them pass. Every test follows the Arrange-Act-Assert (AAA) pattern. It covers unit tests for isolated logic, integration tests for database and service interactions, and end-to-end tests for user-facing flows. For bug fixes, it writes a failing regression test before any fix is applied so the bug cannot silently recur.
 
-**Model:** `anthropic/claude-haiku-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
-- Writing a failing regression test to capture a reported bug before `@coder` fixes it
-- Implementing the test suite for a new feature in parallel with `@coder` from interface contracts
+- Writing a failing regression test to capture a reported bug before `@backend-coder` fixes it
+- Implementing the test suite for a new feature in parallel with `@backend-coder` from interface contracts
 - Running the full test suite as a verification step after `@refactor-guide` transforms
 - Identifying coverage gaps and writing tests for uncovered paths
 
@@ -484,7 +514,7 @@ The tester writes tests that drive implementation using strict Red-Green-Refacto
         Use the AAA pattern with vitest.
 ```
 
-**Works with:** `@coder` (implements code to make tests pass), `@debug-specialist` (writes regression test after root cause is identified), `@refactor-guide` (verifies green suite before and after each transformation)
+**Works with:** `@backend-coder` (implements code to make tests pass), `@debug-specialist` (writes regression test after root cause is identified), `@refactor-guide` (verifies green suite before and after each transformation)
 
 ---
 
@@ -492,7 +522,7 @@ The tester writes tests that drive implementation using strict Red-Green-Refacto
 
 The writer drafts technical documentation that developers will actually read. It reads every source file it documents — never documents from memory. It favors accuracy over comprehensiveness, examples over prose, and active voice throughout. Documentation types covered: README.md (with standard section order), API reference (per-function with parameters, return types, and usage examples), changelogs (Keep a Changelog format), and ADRs. It marks anything it cannot verify as `UNKNOWN` rather than guessing.
 
-**Model:** `anthropic/claude-haiku-4-5`
+**Model:** *(uses your active OpenCode model — override in `flowdeck.json`)*
 
 **Best for:**
 - Writing a README.md from scratch for a new project or module

package/docs/best-practices.md

@@ -15,7 +15,7 @@ Maximize the efficiency and safety of your AI-driven development by following th
 
 When faced with ambiguity, don't rely on a single agent.
 - Use `/fd-council` for high-level design choices.
-- The synthesis provided by the council often catches security or performance risks that a single "coder" agent might miss.
+- The synthesis provided by the council often catches security or performance risks that a role-based implementation agents might miss.
 
 ## 3. Grounding with Hierarchical Context
 

package/docs/commands/fd-ask.md

@@ -21,10 +21,10 @@ Route a free-form task to the best specialized agent automatically.
 | performance, bottleneck, slow | `@performance-optimizer` |
 | debug, error, crash, exception | `@debug-specialist` |
 | test, coverage, spec, TDD | `@tester` |
-| refactor, cleanup, simplify | `@coder` |
+| refactor, cleanup, simplify | `@backend-coder` / `@frontend-coder` / `@devops` |
 | document, docs, README | `@writer` |
 | explain, query, find, explore | `@code-explorer` |
-| deploy, release, migration | `@reviewer` |
+| deploy, release, migration | `@devops` |
 | plan, roadmap, breakdown | `@planner` |
 | (anything else) | `@orchestrator` |
 

package/docs/commands/fd-fix-bug.md

@@ -1,5 +1,5 @@
 ---
-description: Debug and fix a bug — scope analysis, mini-plan, coder fix, regression test, reviewer confirmation
+description: Debug and fix a bug — scope analysis, mini-plan, implementation-agent fix, regression test, reviewer confirmation
 argument-hint: "[bug description or issue number]"
 ---
 
@@ -9,7 +9,7 @@ Systematically debug and fix a bug using FlowDeck's structured approach.
 1. Reads `.codebase/` for architecture context
 2. Delegates to `@debug-specialist` to locate the root cause
 3. Creates a mini-plan (fix + regression test)
-4. Delegates fix to `@coder`
+4. Delegates fix to `@backend-coder`, `@frontend-coder`, or `@devops` based on scope
 5. Delegates regression test writing to `@tester`
 6. Verifies the fix via `@reviewer`
 7. Writes a brief post-mortem to `.planning/bugs/`

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

@@ -1,12 +1,12 @@
 ---
-description: Execute feature implementation workflow — orchestrator + parallel coder/researcher + reviewer + tester
+description: Execute feature implementation workflow — orchestrator + role-routed implementation/researcher + reviewer + tester
 argument-hint: "[feature-description]"
 ---
 
 Execute a new feature using FlowDeck's multi-agent workflow.
 
 **What this does:**
-1. If a confirmed PLAN.md exists: delegates steps to `@coder` in order
+1. If a confirmed PLAN.md exists: delegates each step to `@backend-coder`, `@frontend-coder`, or `@devops` based on scope
 2. If no plan: first runs discuss → plan → confirm, then executes
 3. Runs `@researcher` in parallel for any external APIs or docs needed
 4. Runs `@reviewer` after each significant step to catch issues early

package/docs/commands/fd-quick.md

@@ -11,7 +11,9 @@ Execute a focused task without the full workflow. Analyzes the request, selects
 
 | Task Type | Agent |
 |-----------|-------|
-| Write/edit code | @coder |
+| Backend code | @backend-coder |
+| Frontend code | @frontend-coder |
+| DevOps/infra code | @devops |
 | Explore/understand | @code-explorer |
 | Review code | @reviewer |
 | Security review | @security-auditor |

package/docs/commands.md

@@ -10,6 +10,7 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 | `/fd-new-feature` | `[feature-description]` | Define a new feature and initialize feature context |
 | `/fd-discuss` | `[topic]` | Structured Q&A to capture decisions for a phase |
 | `/fd-plan` | `[--phase=N]` | Generate detailed implementation plan from decisions |
+| `/fd-design` | `[--mode=draft\|review\|system] [task-description]` | Run design-first stages, UI review, or design-system guidance for UI-heavy tasks |
 | `/fd-execute` | `[--phase=N] [--override]` | Implement feature with TDD pipeline and parallel agents |
 | `/fd-verify` | `[--phase=N] [--env=staging\|production]` | Verify feature completion: tests, review, security, deploy check |
 | `/fd-fix-bug` | `[bug-description]` | Debug, fix, and verify bug with regression test |
@@ -126,8 +127,34 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 ```
 
 **What Next?**
-1. Run `/fd-execute` to implement the plan
-2. Run `/fd-plan --phase=2` for next phase
+1. If UI-heavy, run `/fd-design --mode=draft` first
+2. Run `/fd-execute` to implement the plan
+3. Run `/fd-plan --phase=2` for next phase
+
+---
+
+## /fd-design
+
+**Description:** Design-first workflow for UI-heavy tasks. Supports planning (`draft`), fidelity review (`review`), and design system updates (`system`).
+
+**Arguments:**
+- `[--mode=draft|review|system]` — default is `draft`
+- `[task-description]` — UI task or review scope
+- `[--override]` — explicit override path when skipping design gate
+
+**What it does:**
+1. Detects UI-heavy task types (landing page, dashboard, admin panel, app screen, etc.)
+2. Runs structured design stages: discovery → UX planning → wireframe/layout → visual system → approval → handoff
+3. Persists structured design artifact in planning state for downstream implementation
+4. In `review` mode, reports design fidelity gaps against approved artifacts
+5. In `system` mode, generates or updates token and component guidance
+
+**Example:**
+```
+/fd-design --mode=draft redesign dashboard onboarding
+/fd-design --mode=review phase-2 dashboard implementation
+/fd-design --mode=system app shell tokens
+```
 
 ---
 
@@ -141,9 +168,10 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 
 **What it does:**
 1. Reads `.planning/phases/phase-N/PLAN.md` for implementation steps
-2. For each step, enforces TDD cycle: BEHAVIOR → RED → GREEN → REFACTOR
+2. If UI-heavy and design-first is enabled, requires approved design handoff before coding
+3. For each step, enforces TDD cycle: BEHAVIOR → RED → GREEN → REFACTOR
 3. `@tester` writes failing tests first
-4. `@coder` implements minimum to pass
+4. Implementation agent (`@backend-coder` / `@frontend-coder` / `@devops`) implements minimum to pass
 5. `@reviewer` confirms quality
 6. Updates `STATE.md` with completed steps
 7. Waves execute in order, with parallel tasks within each wave
@@ -205,7 +233,7 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 **What it does:**
 1. Enforces TDD cycle: BEHAVIOR → RED → GREEN → REFACTOR
 2. `@tester` writes failing tests first
-3. `@coder` implements minimum to pass
+3. Implementation agent (`@backend-coder` / `@frontend-coder` / `@devops`) implements minimum to pass
 4. `@reviewer` confirms quality
 5. Updates `STATE.md` with completed steps
 
@@ -226,7 +254,7 @@ Commands are slash commands registered in OpenCode. Run them by typing `/command
 **What it does:**
 1. `@researcher` investigates and isolates root cause
 2. `@tester` writes regression test that fails (RED)
-3. `@coder` implements minimum fix (GREEN)
+3. Implementation agent (`@backend-coder` / `@frontend-coder` / `@devops`) implements minimum fix (GREEN)
 4. `@reviewer` confirms fix (REFACTOR)
 5. Records in `.codebase/FAILURES.json`
 
@@ -464,7 +492,9 @@ Comprehensive pre-change analysis: impact radar, blast radius, regression predic
 
 | Task Type | Agent |
 |-----------|-------|
-| Write/edit code | @coder |
+| Backend code | @backend-coder |
+| Frontend code | @frontend-coder |
+| DevOps/infra code | @devops |
 | Explore/understand | @code-explorer |
 | Review code | @reviewer |
 | Security review | @security-auditor |