@dv.nghiem/flowdeck 0.2.4 → 0.3.1

package/docs/configuration.md

@@ -269,7 +269,11 @@ These are enabled by default. If you have API keys (e.g., `CONTEXT7_API_KEY`, `E
 | `FLOWDECK_CONTEXT_LIMIT` | `200000` | Token limit used by the Context Window Monitor to warn when context usage exceeds 70% |
 | `FLOWDECK_DISABLE_MCP` | (empty) | Comma-separated list of remote MCPs to disable. Valid options: `context7`, `websearch`, `grep_app` |
 | `FLOWDECK_ORCHESTRATOR_GUARD` | `off` | Enable the orchestrator guard hook. When `on`, the orchestrator session cannot use write/bash tools directly and must delegate all implementation work. |
-| `TELEMETRY_ENABLED` | `false` | Enable telemetry events from `run-parallel` and hooks. When `true`, events are written to `.codebase/TELEMETRY.jsonl`. |
+| `FLOWDECK_PATCH_TRUST_HIGH_RISK_ENABLED` | `off` | Enable blocking of high-risk AI-generated edits (score < 40). When `true` or `1`, the patch trust hook blocks edits flagged as high-risk. When `false`, `0`, or unset (default), high-risk edits are allowed without blocking. |
+| `FLOWDECK_GUARD_RAILS_ENABLED` | `off` | Enable the guard rails hook. When `on`, write/edit tools are warned/blocked based on plan confirmation state, .codebase/ existence, and execution mode. |
+| `FLOWDECK_TOOL_GUARD_ENABLED` | `off` | Enable the tool guard hook. When `on`, blocks dangerous bash commands (rm -rf), access to secret files (.env, .pem, .key), writes to node_modules, arch-constraint violations, and premature phase writes. |
+| `FLOWDECK_APPROVAL_HOOK_ENABLED` | `off` | Enable the approval hook. When `on`, blocks write/edit on sensitive files (auth/payment/secrets/infra) unless a recent approval exists. |
+| `TELEMETRY_ENABLED` | `false` | Enable telemetry events from hooks. When `true`, events are written to `.codebase/TELEMETRY.jsonl`. |
 
 ---
 
@@ -280,7 +284,6 @@ When the `@dv.nghiem/flowdeck` plugin is loaded, six tools become available to e
 | `planning-state` | Read and write `.planning/` state files (`STATE.md`, `PLAN.md`, `DISCUSS.md`, `config.json`). Used by every agent that needs project context. |
 | `codebase-state` | Read `.codebase/` documentation files generated by `@mapper`. Gives agents access to `STACK.md`, `ARCHITECTURE.md`, and `CONVENTIONS.md`. |
 | `workspace-state` | Read workspace and multi-repo metadata. Returns the current project config, sub-repo list, and active phase. |
-| `run-parallel` | Fan out a set of independent agent tasks simultaneously. Used by `@parallel-coordinator` to execute wave tasks concurrently. |
 | `run-pipeline` | Execute a sequence of agent tasks in strict order, passing each step's output as input to the next. Used by `@orchestrator` for ordered workflows. |
 | `delegate` | Invoke a specific named agent with a given prompt and context. The core primitive used by orchestration agents to hand off work. |
 | `hash-edit` | Reliable file editing with content verification. Takes target content and its expected hash to prevent edits on stale versions. |

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 29 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 four-phase cycle — discuss, plan, execute, review — with persistent state stored in your project's `.planning/` directory.
 
 ---
 
@@ -18,12 +18,13 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 
 | Document | Description |
 |----------|-------------|
-| [Agents](agents.md) | All 29 agents — names, roles, models, and when to invoke each one |
-| [Skills](skills.md) | All 24 skills — what each skill does and example prompts that activate it |
-| [Commands](commands.md) | All 27 slash commands — syntax, arguments, and what each command triggers |
-| [Workflows](workflows.md) | All 15 built-in workflows — flow diagrams, inputs, outputs, and agent involvement |
+| [Agents](agents.md) | All specialist agents — names, roles, models, 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 |
 | [Rules](rules.md) | Language and common rule files — what they enforce and how to activate them |
-| [Intelligence Features](intelligence.md) | 15 AI-safety features: impact radar, patch trust, blast radius, decision trace, and more |
+| [Intelligence Features](intelligence.md) | AI-safety features for pre-change analysis and risk assessment |
+| [Memory System](memory.md) | Persistent memory — recall past sessions, tool executions, and context across sessions |
 
 ---
 
@@ -31,7 +32,6 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 
 | Document | Description |
 |----------|-------------|
-| [Parallel Execution](parallel-execution.md) | How FlowDeck fans out independent tasks across multiple agents simultaneously |
 | [Multi-Repo](multi-repo.md) | Coordinating changes across two or more repositories in a single session |
 | [Notifications](notifications.md) | Desktop and system alerts for long-running task completion |
 
@@ -50,26 +50,20 @@ FlowDeck is an OpenCode plugin that brings structured, multi-agent workflow orch
 
 | Command | What it does |
 |---------|--------------|
-| `/fd-new-project <name>` | Initialize `.planning/` directory structure for a new project |
-| `/fd-discuss <phase>` | Run structured requirements Q&A with `@discusser` |
-| `/fd-plan <phase>` | Generate a wave-structured `PLAN.md` (requires `CONFIRMED` to execute) |
-| `/fd-new-feature "<description>"` | Execute full feature workflow via `@orchestrator` |
-| `/fd-review-code [staged\|branch]` | Parallel review by `@reviewer`, `@security-auditor`, `@tester` |
+| `/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-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 |
+| `/fd-status [--roadmap\|--workspace\|--phase=N]` | Combined status, roadmap, and workspace view |
 | `/fd-checkpoint` | Save current state — safe to close the session after this |
-| `/fd-resume` | Reload `STATE.md` and `PLAN.md` context in a new session |
-| `/fd-progress` | Print current state, active plan, and recent results |
-| `/fd-map-codebase` | Generate `.codebase/` documentation from source analysis |
-| `/fd-roadmap` | View or update phase statuses and milestones |
-| `/fd-dashboard` | Open the project dashboard with phase progress and blockers |
-| `/fd-deploy-check` | Run pre-deployment checks and produce a go/no-go verdict |
-| `/fd-write-docs` | Generate or update project documentation |
-| `/fd-multi-repo` | Coordinate a change across multiple registered repositories |
-| `/fd-settings` | View or update FlowDeck model assignments and configuration |
-| `/fd-impact-radar` | Predict affected files/APIs/tests before editing |
-| `/fd-blast-radius` | Show downstream consequences and hidden dependencies of a change |
-| `/fd-translate-intent` | Convert vague request into ranked concrete implementation options |
-| `/fd-volatility-map` | Show unstable code zones by churn and hotfix frequency |
-| `/fd-regression-predict` | Estimate likely regression categories before making a change |
-| `/fd-test-gap` | Identify weakly-tested areas in a proposed change |
-| `/fd-review-route` | Route risky patches to security, backend, infra, or domain reviewers |
+| `/fd-resume [--yes]` | Reload STATE.md and PLAN.md to continue interrupted session |
+| `/fd-reflect [--mode=reflect,learn]` | Post-session reflection or capture skill from session |
+| `/fd-map-codebase [--incremental]` | Generate `.codebase/` documentation |
+| `/fd-write-docs [--scope=path]` | Generate documentation from public APIs |
+| `/fd-multi-repo <list\|add\|remove\|status>` | Manage multi-repo configuration |
+| `/fd-translate-intent "<vague request>"` | Convert vague request into ranked implementation options |
+| `/fd-ask "<question>"` | Route question to specialist agent |
+| `/fd-quick "<task>"` | Quick focused task with automatic agent selection |
+| `/fd-doctor` | Check FlowDeck installation and environment health |

package/docs/memory.md

@@ -0,0 +1,69 @@
+# Memory System
+
+FlowDeck includes a persistent memory system that stores tool executions, assistant messages, and session summaries. This helps agents recall what was worked on in previous sessions.
+
+## How It Works
+
+Memory is automatically captured during sessions:
+
+1. **Session Start** — Session is registered with project directory
+2. **Tool Execution** — Every tool call (Read, Write, Edit, Bash, etc.) is stored
+3. **Assistant Messages** — Agent responses are captured
+4. **Session Compact/Summary** — End-of-session summaries are stored
+
+## Storage
+
+- **Location**: `~/.flowdeck-memory/memory.db`
+- **Format**: SQLite database (using `bun:sqlite`)
+- **Tables**:
+  - `sessions` — Session metadata (project, directory, timestamps)
+  - `observations` — Tool executions and messages
+  - `summaries` — Session summaries
+
+## Using Memory
+
+### Search Tool
+
+Use the `memory-search` tool to query past observations:
+
+```
+tool: memory-search
+args: { query: "authentication", limit: 5 }
+```
+
+**Arguments:**
+- `query` (optional) — Search text for tool names, inputs, and outputs
+- `session_id` (optional) — Retrieve all observations from a specific session
+- `limit` (optional) — Max results (default: 10)
+
+### Example Queries
+
+```javascript
+// Search for specific work
+tool: memory-search
+args: { query: "Redis cache" }
+
+// Get recent sessions
+tool: memory-search
+args: { limit: 10 }
+
+// Get all observations from a session
+tool: memory-search
+args: { session_id: "abc-123" }
+```
+
+## Context Injection
+
+When a new session starts in the same directory, FlowDeck can optionally inject relevant context from previous sessions. This helps maintain continuity across sessions.
+
+## Privacy
+
+- Memory is stored per-user at `~/.flowdeck-memory/`
+- Each project directory has its own session tracking
+- Use session.delete event to remove specific sessions
+
+## Configuration
+
+No configuration required — memory is enabled by default.
+
+To disable memory tracking for a project, you would need to modify the session tracking hooks in the FlowDeck plugin configuration.

package/docs/quick-start.md

@@ -123,7 +123,7 @@ Once the plan is confirmed, start implementation:
 3. **Wave 3** — `@tester` writes and runs tests against the completed implementation
 4. **Wave 4** — `@reviewer` reviews the full changeset
 
-You see progress updates as each wave completes. Independent tasks within a wave run simultaneously via the `run-parallel` tool.
+You see progress updates as each wave completes. Independent tasks within a wave run simultaneously via OpenCode's multi-agent capabilities.
 
 ---
 

package/package.json

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

package/src/commands/fd-deploy-check.md

@@ -1,13 +1,30 @@
 ---
-description: Parallel tester + reviewer + researcher CVE check — orchestrator go/no-go deploy decision
-argument-hint: [--env=staging|production]
+description: Pre-deployment checks, code review, and pre-change analysis — all-in-one quality gate
+argument-hint: [--env=staging|production] [--check=deploy,review,analysis] [--scope=path]
 ---
 
 # Deploy Check
 
-Run a comprehensive pre-deployment check suite before releasing to production.
+Run comprehensive checks before deployment or review code changes.
 
-**Input:** $ARGUMENTS — optional `--env=staging|production` (default: staging)
+**Input:** $ARGUMENTS
+
+## Check Types
+
+### Deploy Check (`--check=deploy` or default)
+Run full pre-deployment suite. See Steps 1-3 below.
+
+### Code Review (`--check=review`)
+Run parallel reviewer + researcher + tester on changed files. See Steps 4-6 below.
+
+### Pre-Change Analysis (`--check=analysis`)
+Run comprehensive pre-change analysis. See Step 7 below.
+
+## Common Pre-flight
+
+1. If `--scope` provided: use that path
+2. If no scope with `--check=review`: use files changed since last commit
+3. If no scope with `--check=deploy`: use all changed files since last commit
 
 ## Process
 
@@ -83,11 +100,114 @@ Any of these → automatic NO-GO:
 - HIGH/CRITICAL CVE unpatched
 - Build error
 
-## Agent Configuration
+### Step 4: Code Review Scope (--check=review)
+
+If `/deploy-check --check=review [scope]` provided: review files matching scope.
+If no scope: review all files changed since last commit.
+
+```bash
+git diff --name-only HEAD~1
+```
+
+If no changes found, report: "Nothing to review."
+
+### Step 5: Parallel Review
+
+Spawn three agents simultaneously:
+
+**@reviewer**
+- Security: secrets, injection, auth, XSS
+- Quality: function size, nesting, error handling
+- Conventions: naming, import style, patterns
+
+**@researcher**
+- Look up best practices for flagged patterns
+- Check if flagged patterns are known vulnerabilities
+- Provide context for MEDIUM findings
+
+**@tester**
+- Check coverage for changed files
+- Identify untested paths
+- Run existing tests
+
+### Step 6: Aggregate Review Results
+
+Merge all findings by severity:
+
+```
+## Code Review: <scope>
+
+### 🔴 CRITICAL (block merge)
+- [finding with file:line and fix]
+
+### 🟠 HIGH (strongly recommend fix)
+- [finding]
+
+### 🟡 MEDIUM (consider fixing)
+- [finding]
+
+### 🟢 LOW (optional)
+- [finding]
+
+### Coverage
+- Changed files: N%
+- Untested paths: [list]
+
+### Verdict: PASS | FAIL | PASS_WITH_NOTES
+```
+
+### Step 7: Pre-Change Analysis (--check=analysis)
+
+Run all analyses in parallel:
+
+1. **Impact Radar** — which files/APIs/tests are affected
+2. **Blast Radius** — downstream consequences and hidden couplings
+3. **Regression Predict** — most likely regression categories
+4. **Test Gap** — coverage gaps to fill before implementing
+5. **Volatility** — check hotspot scores on affected files
+6. **Review Route** — who should review this change
+
+## Consolidated Analysis Report
+
+```
+════════════════════════════════════════════════════
+PRE-CHANGE ANALYSIS: "$ARGUMENTS"
+════════════════════════════════════════════════════
+
+IMPACT (<N> files affected)
+  - <top 5 affected files with reason>
+
+BLAST RADIUS (risk: <low|medium|high>)
+  - <key downstream risks>
+
+REGRESSIONS (top 3 risks)
+  🔴 <category> — <reason>
+  🟠 <category> — <reason>
+
+TEST GAPS (<N> gaps found)
+  - CRITICAL: <gap>
+  - HIGH: <gap>
+
+VOLATILITY
+  Hot zones touched: <list or "none">
+
+REVIEW ROUTING
+  → <reviewer type> (<reason>)
+
+────────────────────────────────────────────────────
+RECOMMENDATION: <proceed | add tests first | redesign | review required>
+
+Next steps:
+  1. <most important action>
+  2. <second action>
+════════════════════════════════════════════════════
+```
+
+## Severity Classification
 
-| Agent | Purpose |
-|-------|---------|
-| @tester | Run test suite |
-| @security-auditor | Security vulnerability scan |
-| @researcher | CVE research and context |
-| @reviewer | Code quality review |
+| Severity | Meaning | Action |
+|----------|---------|--------|
+| CRITICAL | Security vulnerability or data loss risk | **BLOCK** - Must fix before merge |
+| HIGH | Bug or significant quality issue | **WARN** - Should fix before merge |
+| MEDIUM | Maintainability concern | **INFO** - Consider fixing |
+| LOW | Style or minor suggestion | **NOTE** - Optional |

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

@@ -98,6 +98,19 @@ confirmed_at: none
 
 3. Also create `.planning/phases/phase-1/` directory.
 
-4. Report success with the list of files created and next steps:
+4. Create `.planning/config.json` with default settings:
+
+```json
+{
+  "model_profile": "balanced",
+  "tdd_enforced": true,
+  "approval_required": false,
+  "volatility_threshold": 0.7,
+  "default_agent": "orchestrator"
+}
+```
+
+5. Report success with the list of files created and next steps:
    - Run `/fd-discuss` to capture project decisions
    - Run `/fd-plan` to create an implementation plan
+   - Edit `.planning/config.json` directly to change settings

package/src/commands/fd-quick.md

@@ -0,0 +1,60 @@
+---
+description: Quick task execution — analyze, implement, review, or investigate a specific piece of work without the full discuss -> plan -> execute workflow
+argument-hint: [task description]
+---
+
+# Quick Task
+
+Execute a focused task without the full workflow. Analyzes the request, selects the best specialist agent, and returns the result directly.
+
+**Input:** $ARGUMENTS — what you need done
+
+## Analysis
+
+Parse `$ARGUMENTS` to determine:
+
+1. **Type of task** — what kind of work is it?
+2. **Scope** — single file, directory, or whole codebase?
+3. **Required capability** — what must the agent be able to do?
+
+## Agent Selection Matrix
+
+| Task Type | Signal Keywords | Agent |
+|-----------|-----------------|-------|
+| Write or edit code | implement, add, create, fix, refactor, update | `@coder` |
+| 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` |
+| Design or architecture | design, architect, schema, API, structure | `@architect` |
+| Write tests | test, coverage, regression, TDD | `@tester` |
+| Documentation | docs, README, document, write | `@writer` |
+| Research | research, find, look up, how to use, compare | `@researcher` |
+| Debug | debug, trace, root cause, why is, fix error | `@debug-specialist` |
+| Performance | performance, slow, optimize, bottleneck | `@performance-optimizer` |
+| Build error | build error, compile, types, missing import | `@build-error-resolver` |
+| Refactoring | refactor, extract, rename, restructure | `@refactor-guide` |
+| Write/update docs | document, write docs, update README | `@doc-updater` |
+
+**Default:** If unclear or mixed, use `@orchestrator`.
+
+## Execution
+
+1. Select the best agent from the matrix above.
+2. Construct a focused prompt with:
+   - The task from `$ARGUMENTS`
+   - Relevant context (file paths, architecture info, existing code)
+   - Clear success criteria
+3. Execute directly — no intermediate steps.
+
+## Output
+
+Return the agent's output with:
+- Which agent was used
+- The result (be direct, no padding)
+- If the task is partial or incomplete, note what still needs doing
+
+## Guardrails
+
+- **Small tasks only** — if the task would require more than ~15 minutes of work, suggest `/fd-new-feature` instead.
+- **Single scope** — do not attempt multi-file refactors or cross-repo changes via this command.
+- **No workflow overhead** — skip STATE.md updates, phase transitions, and plan markers.

package/src/commands/fd-reflect.md

@@ -1,11 +1,22 @@
 ---
-description: Post-session reflection — analyse artifacts and propose self-improvement actions
+description: Post-session reflection and skill capture — analyse artifacts, propose improvements, capture session patterns
+argument-hint: [--mode=reflect,learn]
 ---
 
-# Reflect: Self-Improvement Analysis
+# Reflect
 
 Analyse session artifacts and propose concrete improvements to FlowDeck's knowledge base.
 
+**Input:** $ARGUMENTS — optional `--mode=reflect` (default) or `--mode=learn`
+
+## Modes
+
+### Reflect (default)
+Post-session self-improvement analysis. See Steps below.
+
+### Learn (`--mode=learn`)
+Capture a repeatable pattern from this session as a reusable FlowDeck skill.
+
 ## Steps
 
 1. Call the `reflect` tool to gather session artifacts and generate the reflection context.
@@ -28,3 +39,31 @@ Analyse session artifacts and propose concrete improvements to FlowDeck's knowle
    - What was captured (new skills created)
    - What requires human review (policy proposals, workflow changes)
    - 3–5 bullet summary of this session's most impactful learnings
+
+## Learn Mode
+
+When `--mode=learn`:
+
+1. **Identify what is worth capturing.** Look for:
+   - A novel problem that required figuring out a non-obvious solution
+   - A pattern that required human guidance or clarification to resolve
+   - A workflow or sequence that would save significant time if remembered
+   - A pitfall that was hit and corrected
+
+   If nothing significant was discovered, reply: "No new patterns to capture from this session." and stop.
+
+2. **Draft the skill.** Structure it as:
+   - `## When to Activate` — concrete triggers (e.g., "when X file pattern exists", "when the user asks about Y")
+   - `## Steps` — ordered, concrete steps to apply the skill
+   - `## Examples` — at least one short, concrete example
+   - `## Pitfalls` — common mistakes to avoid
+
+3. **Choose the skill name.** Use `$ARGUMENTS` if provided as skill name, otherwise derive a kebab-case name from the pattern.
+
+4. **Write the skill** using the `create-skill` tool with:
+   - `name`: kebab-case identifier
+   - `description`: one sentence summarising what the skill does
+   - `content`: the full Markdown body from step 2
+   - `tags`: 2–4 relevant tags
+
+5. **Report** what was captured, why it is useful, and remind the user to restart OpenCode to activate it.

package/src/commands/fd-status.md

@@ -0,0 +1,84 @@
+---
+description: View project status — combined status, roadmap, workspace overview, and progress
+argument-hint: [--roadmap | --workspace | --phase=N]
+---
+
+# Status
+
+View project status combining progress, roadmap, and workspace overview.
+
+**Input:** $ARGUMENTS — optional flags
+
+## Modes
+
+### Default (no flags)
+
+Read `.planning/STATE.md` and display combined status:
+
+```
+════════════════════════════════════════════════════════════
+Phase: <N>  |  Status: <status>  |  Updated: <timestamp>
+────────────────────────────────────────────────────────────
+Plan: <X> steps (<Y> complete)
+Plan confirmed: <yes/no>
+════════════════════════════════════════════════════════════
+```
+
+### Roadmap (`--roadmap`)
+
+Display project roadmap with phase statuses:
+
+```
+═══════════════════════════════════════
+PROJECT ROADMAP
+═══════════════════════════════════════
+  ✅ Phase 1: <name> — completed
+  🔄 Phase 2: <name> — in progress  ← current
+  ⏳ Phase 3: <name> — planned
+═══════════════════════════════════════
+```
+
+Read from `.planning/ROADMAP.md` and `.planning/STATE.md`.
+
+### Workspace (`--workspace`)
+
+Display overview of all registered repositories:
+
+```
+════════════════════════════════════════════════════
+WORKSPACE OVERVIEW
+════════════════════════════════════════════════════
+  frontend   — Phase 2 | in_progress  | Plan: ✅ | Updated: <time>
+  backend    — Phase 3 | completed    | Plan: ✅ | Updated: <time>
+  shared     — Phase 1 | planned      | Plan: ❌ | Updated: <time>
+────────────────────────────────────────────────────
+Total: 3 repos | 1 in progress | 1 completed | 1 planned
+════════════════════════════════════════════════════
+```
+
+Read from `.planning/config.json` for repo list, each repo's STATE.md for phase/status.
+
+### Phase Detail (`--phase=N`)
+
+Show detailed progress for a specific phase:
+
+```
+════════════════════════════════════════════════════════════
+PHASE <N> DETAIL
+════════════════════════════════════════════════════════════
+Status: <status>
+Plan file: <path>
+Plan confirmed: <yes/no>
+
+Steps:
+  ✅ Step 1: <name> — completed
+  🔄 Step 2: <name> — in progress
+  ⬜ Step 3: <name> — pending
+  ⬜ Step 4: <name> — pending
+════════════════════════════════════════════════════════════
+```
+
+## Error Handling
+
+- If `.planning/STATE.md` not found: "No active project. Run /fd-new-project first."
+- If `--phase` requested but phase directory doesn't exist: "Phase N not found."

package/src/rules/README.md

@@ -2,22 +2,23 @@
 
 Coding standards for projects using FlowDeck. These define conventions that FlowDeck agents follow automatically.
 
-## How to Use
+## How It Works
 
-Add a rule file to `opencode.json` under `instructions`:
+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.
+
+## Selective Rules (Optional)
+
+If you want to override the default set and load only specific rules, add them to `opencode.json` under `instructions`:
 
 ```json
 {
   "instructions": [
-    ".flowdeck/rules/common/coding-style.md",
-    ".flowdeck/rules/common/security.md",
-    ".flowdeck/rules/typescript/patterns.md"
+    "node_modules/@dv.nghiem/flowdeck/src/rules/common/coding-style.md",
+    "node_modules/@dv.nghiem/flowdeck/src/rules/typescript/patterns.md"
   ]
 }
 ```
 
-Agents will read these files and follow the conventions defined in them.
-
 ## Available Rules
 
 ### Common Rules (language-agnostic)