@dv.nghiem/flowdeck 0.3.3 → 0.3.5

package/docs/rules.md

@@ -1,47 +1,20 @@
 # FlowDeck Rules
 
-Rules are coding standard documents that you load into OpenCode's context. They give the AI consistent style, testing, security, and language-specific guidelines to follow across all sessions.
+Rules are coding standards used by FlowDeck agents for style, testing, security, and language-specific guidance.
 
-## How to Use Rules
+## How Rules Load
 
-### Method 1 — Project-level (recommended)
+FlowDeck loads all markdown files under `src/rules/` automatically through plugin startup. You do not need to manually copy or symlink rule files.
 
-Add the rules you want to your project's `opencode.json`. This ensures every OpenCode session in the project automatically picks them up:
+## Precedence
 
-```json
-{
-  "instructions": [
-    ".flowdeck-rules/common/coding-style.md",
-    ".flowdeck-rules/common/testing.md",
-    ".flowdeck-rules/common/security.md",
-    ".flowdeck-rules/typescript/patterns.md"
-  ]
-}
-```
-
-Where `.flowdeck-rules/` is a symlink or copy of the FlowDeck rules directory:
-
-```bash
-ln -s ~/.config/opencode/node_modules/@dv.nghiem/flowdeck/rules .flowdeck-rules
-```
-
-### Method 2 — Per-session
-
-Reference a rule file directly in your prompt:
+When guidance conflicts, precedence is:
 
-```
-Follow the rules in ~/.config/opencode/node_modules/@dv.nghiem/flowdeck/rules/typescript/patterns.md
-```
-
-### Method 3 — Copy to project
-
-Copy the rules directory into your project for version-controlled standards:
-
-```bash
-cp -r ~/.config/opencode/node_modules/@dv.nghiem/flowdeck/rules ./flowdeck-rules
-```
+1. `AGENTS.md` and `CLAUDE.md` in the repository
+2. FlowDeck plugin rules in `src/rules/**`
+3. Runtime policy rules in `.codebase/POLICIES.json`
 
-Then commit `flowdeck-rules/` to your repository so the entire team uses the same standards.
+This keeps repository-specific conventions authoritative and lets policy learning add guardrails without overriding project intent.
 
 ---
 
@@ -138,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.
 
 ---
 
@@ -38,36 +40,36 @@ Each step gates the next. `/fd-discuss` requires a defined feature. `/fd-plan` r
 |---------|---------|------------|
 | `/fd-new-project` | Bootstrap a new project | @orchestrator |
 | `/fd-map-codebase` | Analyse and index the codebase | @mapper (×6 parallel) |
-| `/fd-settings` | Configure FlowDeck settings | @orchestrator |
 | `/fd-new-feature` | Initialize a new feature | @orchestrator |
 | `/fd-discuss` | Pre-planning discussion | @discusser |
 | `/fd-plan` | Generate a phase plan | @planner, @plan-checker |
-| `/fd-roadmap` | View / update project roadmap | @orchestrator |
-| `/fd-dashboard` | Visual progress dashboard | — |
+| `/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-review-code` | Code review | @reviewer, @researcher, @tester |
+| `/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-progress` | View project progress | — |
+| `/fd-status` | View project progress | — |
 | `/fd-checkpoint` | Save a session checkpoint | — |
 | `/fd-resume` | Resume from checkpoint | — |
 | `/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-reflect` | Post-session reflection and skill capture | @auto-learner |
+| `/fd-doctor` | Installation and environment diagnostics | @orchestrator |
 
 ---
 
 ## Analysis Commands
 
-These umbrella commands combine multiple analysis modules:
+Analysis workflows are currently exposed through:
 
 | Command | Purpose | Flags |
 |---------|---------|-------|
-| `/fd-analyze-change` | Combined impact analysis | `--impact`, `--blast-radius`, `--regression`, `--test-gap`, `--volatility` |
-| `/fd-guarded-edit` | Edit gate decision | auto/confirm/review/block |
-| `/fd-evaluate-risk` | Standalone risk assessment | — |
 | `/fd-translate-intent` | Intent to concrete options | `assumptions`, `recommended_option` |
+| `/fd-suggest` | Suggest feature opportunities from volatility, failures, and decisions | `--category`, `--limit` |
 
 ---
 
@@ -116,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.3",
+  "version": "0.3.5",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,7 +29,9 @@
     "postinstall": "node postinstall.mjs",
     "prepublishOnly": "bun run clean && bun run build",
     "test": "bun test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "validate:skills": "node scripts/validate-skills.mjs",
+    "validate:docs": "node scripts/validate-docs.mjs"
   },
   "keywords": ["opencode", "plugin", "ai", "workflow", "planning"],
   "author": "DVNghiem",

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** |

package/src/commands/fd-design.md

@@ -0,0 +1,64 @@
+---
+description: Design-first workflow for UI-heavy tasks — draft design artifacts, review implementation fidelity, or define design system rules
+argument-hint: [--mode=draft|review|system] [task-description] [--override]
+---
+
+# Design
+
+Run design-first workflow stages for user-facing tasks.
+
+**Input:** $ARGUMENTS — supports `--mode=draft|review|system` (default `draft`)
+
+## Mode: draft
+
+Use when creating/updating UI before implementation.
+
+### Required Stages
+
+1. discovery
+2. UX planning
+3. wireframe/layout planning
+4. visual system definition
+5. design approval
+6. implementation handoff
+
+### Process
+
+1. Classify task as UI-heavy (landing page, dashboard, admin panel, app screen, website/app UX)
+2. Delegate to `@design` agent for structured artifacts
+3. Persist outputs in planning state under `design_artifact`
+4. Mark:
+   - `requires_design_first: true`
+   - `design_stage: handoff_complete`
+   - `design_approved: true` only when approval criteria are met
+5. Record any bypass with explicit `design_override_reason`
+
+## Mode: review
+
+Use to review implemented UI against approved design artifact.
+
+### Process
+
+1. Load approved design artifact and changed UI files
+2. Delegate to `@design` with `design-audit` + `responsive-review`
+3. Report:
+   - design mismatches
+   - hierarchy/spacing issues
+   - CTA flow weaknesses
+   - responsive/accessibility concerns
+   - missing empty/error/loading/success states
+
+## Mode: system
+
+Use to generate/update design tokens and component behavior rules.
+
+### Process
+
+1. Delegate to `@design` with `design-system-definition`
+2. Generate/update token guidance and component rules
+3. Save summary in planning state `design_artifact.design_tokens_guidance`
+
+## Enforcement Notes
+
+- UI-heavy tasks must complete design approval before `/fd-execute`, unless `--override` is explicitly provided and logged.
+- Backend-only/infrastructure-only tasks skip this command.

package/src/commands/fd-discuss.md

@@ -50,6 +50,7 @@ Structure the discussion:
 2. **Constraints** — Technical constraints, deadlines, dependencies?
 3. **Acceptance criteria** — How will we know it's done?
 4. **Risks** — What could go wrong? Any known issues?
+5. **UI classification** — Is this task user-facing and UI-heavy (website/app/dashboard/admin/landing/onboarding)?
 
 Ask questions one at a time. Wait for answers before proceeding.
 
@@ -89,6 +90,7 @@ D-02: [Topic] — [Decision] ([Rationale])
 ## Completion
 
 Report: decisions captured, file path, and suggest running `/fd-plan`.
+If UI-heavy, also suggest running `/fd-design --mode=draft` before `/fd-execute`.
 
 ## Error Handling
 

package/src/commands/fd-execute.md

@@ -1,5 +1,5 @@
 ---
-description: Execute feature implementation from PLAN.md — TDD pipeline with coder, tester, reviewer, and STATE.md update
+description: Execute feature implementation from PLAN.md — TDD pipeline with backend-coder, frontend-coder, devops, tester, reviewer, and STATE.md update
 argument-hint: [--phase=N] [--override]
 ---
 
@@ -35,6 +35,10 @@ Verify prerequisites:
 - `.codebase/` directory exists
 - `STATE.md` has `plan_confirmed: true`
 - `PLAN.md` exists in current phase directory
+- If `requires_design_first: true`, require:
+  - `design_stage: handoff_complete`
+  - `design_approved: true`
+  - OR explicit `--override` with logged reason
 
 Initialize TDD state:
 ```yaml
@@ -79,7 +83,7 @@ Run failing tests:
 
 ### Step 7: Implement Minimum (GREEN)
 
-Spawn `@coder` to implement:
+Spawn the implementation agent selected by scope (`@backend-coder`, `@frontend-coder`, or `@devops`) to implement:
 - **Minimum code** to make failing tests pass
 - No speculative features
 - No over-engineering
@@ -160,7 +164,7 @@ User can override with `/fd-execute --override`:
 
 D-03: Fail fast with clear error
 - If guard check fails: abort with clear error and remediation
-- If @coder fails: report failure, offer retry or skip
+- If implementation agent fails: report failure, offer retry or skip
 - If @reviewer finds critical issues: return to Step 7 for fixes
 - No partial state saved on error
 

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

@@ -66,7 +66,7 @@ Confirm test fails. If it passes, the bug may already be fixed or the test is wr
 
 ### Step 7: GREEN — Implement Fix
 
-- **@coder**: Implement the minimum code change that makes the regression test pass
+- **Implementation agent (`@backend-coder` / `@frontend-coder` / `@devops`)**: Implement the minimum code change that makes the regression test pass
 - Do not refactor yet
 
 **GUARD: Do NOT proceed if test does not pass GREEN.**
@@ -101,7 +101,7 @@ Append entry to `.codebase/FAILURES.json`:
 
 ## Error Handling
 
-- **GUARD VIOLATION**: If coder attempts to skip RED or GREEN phase, block and return to correct phase
+- **GUARD VIOLATION**: If implementation agent attempts to skip RED or GREEN phase, block and return to correct phase
 - **Override mechanism**: User can override with `/fd-fix-bug --override` but every override is logged in `override_log`
 - If root cause unclear: spawn `@debug-specialist` for deeper analysis
 - If fix breaks tests: revert, reassess root cause, never suppress error

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

@@ -101,13 +101,13 @@ If any circular dependency is detected, the flow stops and reports the cycle. Ci
 
 Changes execute in dependency order. For each repo:
 
-1. `@coder` implements the changes in that repo
+1. Implementation agent (`@backend-coder`, `@frontend-coder`, or `@devops`) implements the changes in that repo based on scope
 2. `@tester` writes and runs tests for that repo's changes
 3. No downstream repo starts until the upstream repo's changes pass tests
 
-For non-breaking changes, `@coder` and `@tester` for a given repo run in parallel. For breaking changes, `@tester` must verify the upstream before `@coder` starts on any downstream.
+For non-breaking changes, implementation agent and `@tester` for a given repo run in parallel. For breaking changes, `@tester` must verify the upstream before downstream implementation starts.
 
-If a repo's `@coder` or `@tester` fails, that repo and all downstream repos in the dependency chain are paused. Upstream repos that completed are not rolled back — they remain deployed. The flow resumes once the failing repo is fixed.
+If a repo's implementation agent or `@tester` fails, that repo and all downstream repos in the dependency chain are paused. Upstream repos that completed are not rolled back — they remain deployed. The flow resumes once the failing repo is fixed.
 
 ### Step 5: Verify Integration
 

package/src/commands/fd-plan.md

@@ -82,6 +82,8 @@ Update STATE.md:
 - Set plan_file to path of saved PLAN.md
 - Set plan_confirmed: true
 - Update last_action to "Plan confirmed"
+- If task is UI-heavy, set `requires_design_first: true` and `design_stage: pending`
+- Suggest running `/fd-design --mode=draft` immediately after plan confirmation
 
 ## D-06 Compliance
 

package/src/commands/fd-quick.md

@@ -21,10 +21,13 @@ Parse `$ARGUMENTS` to determine:
 
 | Task Type | Signal Keywords | Agent |
 |-----------|-----------------|-------|
-| Write or edit code | implement, add, create, fix, refactor, update | `@coder` |
+| 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` |

package/src/commands/fd-verify.md

@@ -42,6 +42,12 @@ Review all changed files:
 - Quality: critical bugs, missing error handling, TDD discipline
 - Conventions: naming, patterns, import style
 - Test coverage >= 80% for changed files — flag as HIGH if below
+- If task is UI-heavy, include design fidelity review against approved design artifact
+
+**Check B2: UI Design Review (@design) — UI-heavy only**
+- Compare implemented UI to approved design artifact
+- Report hierarchy, spacing, CTA flow, responsiveness, accessibility, and missing state coverage gaps
+- Fail verification when severe design fidelity mismatch exists
 
 **Check C: Security Scan (@security-auditor)**
 - No hardcoded secrets

package/src/rules/README.md

@@ -6,6 +6,16 @@ Coding standards for projects using FlowDeck. These define conventions that Flow
 
 Rules are loaded **automatically** by the FlowDeck plugin. No manual configuration is needed — when FlowDeck is installed, all rule files in this directory are injected into OpenCode's `instructions` at startup.
 
+## Rule Precedence
+
+When guidance conflicts, FlowDeck resolves precedence in this order:
+
+1. Repository governance files (`AGENTS.md`, `CLAUDE.md`)
+2. FlowDeck plugin rules from `src/rules/**`
+3. Runtime policies from `.codebase/POLICIES.json`
+
+This keeps repository-specific expectations authoritative while still allowing runtime policy learning.
+
 ## Selective Rules (Optional)
 
 If you want to override the default set and load only specific rules, add them to `opencode.json` under `instructions`:

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

@@ -10,14 +10,14 @@ FlowDeck provides 23 specialist agents. Each has a specific role. Using the righ
 | `@build-error-resolver` | Fix build failures and type errors | Immediately when build fails |
 | `@build-resolver` | Diagnose and fix build/compile failures | When build breaks and cause is unclear |
 | `@code-explorer` | Map unfamiliar codebase structure | Before modifying unfamiliar code |
-| `@coder` | Implement features and fixes | All code implementation |
+| `@backend-coder` | Implement features and fixes | All code implementation |
 | `@debug-specialist` | Root cause analysis for bugs | When a bug needs deep investigation |
 | `@discusser` | Extract requirements via Q&A | Starting a new feature or phase |
 | `@doc-updater` | Update docs after code changes | After implementation completes |
 | `@plan-checker` | Review PLAN.md before execution | Before executing any plan |
 | `@mapper` | Map codebase to .codebase/ docs | Running /fd-map-codebase |
 | `@orchestrator` | Coordinate multi-agent execution | Managing a full feature delivery |
-| `@parallel-coordinator` | Run parallel agent workstreams | When tasks can run simultaneously |
+| `@task-splitter` | Decompose parallel workstreams | When tasks can run simultaneously |
 | `@performance-optimizer` | Profile and fix performance issues | When app is slow or before release |
 | `@planner` | Create detailed implementation plans | Any multi-file feature |
 | `@refactor-guide` | Safe code restructuring | Reducing technical debt |
@@ -34,7 +34,7 @@ These situations should trigger agent use automatically:
 
 | Situation | Agent |
 |-----------|-------|
-| Complex feature spanning 3+ files | `@planner` first, then `@coder` |
+| Complex feature spanning 3+ files | `@planner` first, then `@backend-coder` |
 | Code was just written | `@reviewer` |
 | Build fails | `@build-error-resolver` |
 | Bug reported | `@debug-specialist` |
@@ -50,11 +50,11 @@ Independent agents can run simultaneously. Examples:
 ```
 Wave 1 (parallel):
   @researcher — research the library API
-  @coder     — implement the model and types
+  @backend-coder     — implement the model and types
   @tester    — write test cases
 
 Wave 2 (after Wave 1):
-  @coder     — implement service using Wave 1 research
+  @backend-coder     — implement service using Wave 1 research
   @reviewer  — review Wave 1 implementation
 ```
 
@@ -78,7 +78,7 @@ discuss → plan → execute → review
 |-------|-------|---------|
 | discuss | `@discusser` | `/fd-discuss` |
 | plan | `@planner` → `@plan-checker` | `/fd-plan` |
-| execute | `@orchestrator` → `@coder`, `@tester`, etc. | `/fd-new-feature` |
+| execute | `@orchestrator` → `@backend-coder`, `@tester`, etc. | `/fd-new-feature` |
 | review | `@reviewer` + `@security-auditor` | `/fd-review-code` |
 
 Do not skip phases. The orchestrator enforces phase gating automatically.

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

@@ -9,8 +9,8 @@ Language-agnostic coding conventions followed by all FlowDeck agents.
 | 1 | **No Redundant Code** | No redundant arguments, methods, or attributes. Each piece of code must serve a purpose. |
 | 2 | **Simplicity** | Code should be simple and easy to understand. Prefer clarity over cleverness. |
 | 3 | **Clear Commands** | Code should have clear, explicit commands. No ambiguity in intent. |
-| 4 | **Extensibility** | Code must be easily extendable. Design for growth, not just current needs. |
-| 5 | **Documentation** | Code must have clear documentation at the beginning of every file. |
+| 4 | **Extensibility** | Prefer minimal designs for current requirements. Add extension points only when required by active scope. |
+| 5 | **Documentation** | Add comments when needed to explain non-obvious tradeoffs or constraints; avoid boilerplate file headers. |
 | 6 | **Information Security** | Comply with information security best practices. No secrets, no injections, no XSS. |
 | 7 | **Memory Optimization** | Optimize memory usage to the minimum possible. Avoid unnecessary allocations. |
 | 8 | **Speed** | Process speed should be as fast as possible. Prefer efficient algorithms and data structures. |

package/src/rules/typescript/patterns.md

@@ -102,7 +102,7 @@ class UserService {
 
 ## Result Types for Error Handling
 
-Never throw in business logic. Use Result types.
+Prefer explicit error contracts (Result types or typed exceptions) for business logic. Use one pattern consistently within a module.
 
 ```typescript
 type Ok<T> = { ok: true; value: T };

package/src/skills/app-shell-design/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: app-shell-design
+description: Define app shell structure, navigation model, and reusable surface patterns for web/mobile apps
+origin: FlowDeck
+---
+
+# App Shell Design Skill
+
+Standardizes navigation and page frame behavior across app surfaces.
+
+## When to Activate
+
+- New app or major app redesign
+- Task includes navigation, shell, or global layout work
+
+## Required Inputs
+
+- Core product flows
+- Platform targets (web/mobile)
+
+## Output Format
+
+- shell_structure
+- navigation_model
+- route_grouping
+- persistent_ui_regions
+- global_state_requirements
+
+## Example
+
+Use for: "Design app shell and navigation for a kanban productivity app."

package/src/skills/backend-patterns/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: backend-patterns
+description: Backend architecture patterns for services, APIs, data access, and middleware design.
+origin: FlowDeck
+---
+
 # backend-patterns
 
 ## When to Activate

package/src/skills/clean-architecture/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: clean-architecture
+description: Apply Clean Architecture boundaries to keep domain logic isolated from frameworks and infrastructure.
+origin: FlowDeck
+---
+
 # clean-architecture
 
 ## When to Activate

package/src/skills/cqrs/SKILL.md

@@ -1,3 +1,9 @@
+---
+name: cqrs
+description: Command Query Responsibility Segregation patterns for separating write and read models.
+origin: FlowDeck
+---
+
 # CQRS (Command Query Responsibility Segregation)
 
 ## When to Activate