@dv.nghiem/flowdeck 0.3.8 → 0.4.0

package/docs/reference/rules.md

@@ -0,0 +1,109 @@
+# Language Rules
+
+FlowDeck agents follow coding standards defined in `src/rules/`. Rules are loaded automatically at startup — no manual configuration required. They are injected into OpenCode's instructions as language-agnostic and language-specific guidance.
+
+## 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`
+
+## Common Rules (All Languages)
+
+Language-agnostic rules are in `src/rules/common/`:
+
+| File | Description |
+|------|-------------|
+| `common/agent-orchestration.md` | When to use each FlowDeck agent and parallel execution patterns |
+| `common/coding-style.md` | Immutability, KISS/DRY/YAGNI, file organization, error handling, naming |
+| `common/testing.md` | TDD workflow, coverage thresholds, test types, AAA pattern |
+| `common/security.md` | Pre-commit security checklist, secret management, OWASP Top 10 |
+| `common/git-workflow.md` | Conventional commits, branch naming, PR workflow, rebase vs merge |
+| `common/behavioral.md` | Agent behavioral expectations and interaction patterns |
+
+---
+
+## TypeScript / JavaScript
+
+**Location:** `src/rules/typescript/`
+
+**Framework conventions:** API response format, custom hooks, repository pattern, Result types.
+
+| File | Description |
+|------|-------------|
+| `typescript/patterns.md` | TypeScript API response format, custom hooks, repository pattern, Result types |
+
+FlowDeck TypeScript rules apply to all `.ts` and `.tsx` files in your project.
+
+---
+
+## Python
+
+**Location:** `src/rules/python/`
+
+**Framework conventions:** Pythonic patterns, typing, async conventions.
+
+| File | Description |
+|------|-------------|
+| `python/patterns.md` | Pythonic API design, typing, async patterns |
+
+FlowDeck Python rules apply to all `.py` files in your project.
+
+---
+
+## Go
+
+**Location:** `src/rules/golang/`
+
+**Framework conventions:** Go idiom conventions, error handling, concurrency patterns.
+
+| File | Description |
+|------|-------------|
+| `golang/patterns.md` | Go idioms, error wrapping, goroutine patterns, module layout |
+
+FlowDeck Go rules apply to all `.go` files in your project.
+
+---
+
+## Rust
+
+**Location:** `src/rules/rust/`
+
+**Framework conventions:** Rust idiom conventions, ownership, lifetimes, Result types.
+
+| File | Description |
+|------|-------------|
+| `rust/patterns.md` | Rust idioms, ownership model, error handling with `Result`, lifetime annotations |
+
+FlowDeck Rust rules apply to all `.rs` files in your project.
+
+---
+
+## Java
+
+**Location:** `src/rules/java/`
+
+**Framework conventions:** Java idiom conventions, OOP patterns, exception handling.
+
+| File | Description |
+|------|-------------|
+| `java/patterns.md` | Java idioms, OOP conventions, exception handling, package layout |
+
+FlowDeck Java rules apply to all `.java` files in your project.
+
+---
+
+## Overriding Default Rules
+
+To load only specific rules, add them to the `instructions` array in `opencode.json`:
+
+```json
+{
+  "instructions": [
+    "node_modules/@dv.nghiem/flowdeck/src/rules/common/coding-style.md",
+    "node_modules/@dv.nghiem/flowdeck/src/rules/typescript/patterns.md"
+  ]
+}
+```

package/docs/skills/code-review.md

@@ -0,0 +1,47 @@
+# Code Quality Skills
+
+These skills enforce FlowDeck's "working code only" guarantee — systematic review, test-driven discipline, and coverage enforcement that catches real problems before they reach production.
+
+---
+
+## code-review
+
+Systematic review with security checklist and severity-ranked findings.
+
+Reviews only changed code, reports only confirmed issues (80%+ confidence), and provides actionable fixes for every finding. Findings are ranked Critical then High then Medium then Pass. Security checklist runs first — SQL injection, XSS, hardcoded credentials, path traversal — before quality and performance checks.
+
+---
+
+## tdd-workflow
+
+Red-green-refactor discipline with 80%+ coverage enforcement.
+
+Tests before code. Always. The workflow: write a failing test (Red), write minimum code to pass (Green), then refactor while keeping tests green. Coverage threshold is 80% line coverage — non-negotiable. Unit tests for every function, integration tests for every API route, E2E only for critical paths.
+
+---
+
+## test-coverage
+
+Coverage enforcement with pass/fail thresholds and actionable failure output.
+
+Drives the write-test-then-implement cycle. Enforces 80% minimum line coverage. When coverage drops below threshold or a gap is found, the report identifies exact uncovered lines with file and line number so the agent knows exactly what to add.
+
+---
+
+## test-gap-detector
+
+Identifies uncovered edge cases and suggests minimum viable test sets.
+
+Runs before implementing a feature or fix. Checks whether modified files have test counterparts, scans for untested if/else/catch branches, flags integration gaps for external calls (db, fetch, email), and cross-references `.codebase/FAILURES.json` for regression risk. Output is a ranked gap list and 3-5 suggested test skeletons.
+
+---
+
+## refactor-guide
+
+Safe refactoring one transformation at a time — tests must stay green throughout.
+
+One transformation per commit. No features in refactor commits. If any test breaks, undo and try a smaller step. Applies the extract-function, extract-variable, and rename patterns. Danger signs that stop the refactor immediately: tests breaking during refactor, adding features during refactor, renaming and moving in the same commit.
+
+---
+
+Source: `src/skills/<name>/SKILL.md` in the project repository.

package/docs/skills/index.md

@@ -0,0 +1,148 @@
+# Skills
+
+Skills are reusable workflow patterns that encode FlowDeck's best practices into automated agents. Each skill is a self-contained unit with activation triggers, core principles, and step-by-step workflows.
+
+## How to Activate
+
+Skills activate in two ways:
+
+- **Slash command**: Type `/<skill-name>` (e.g., `/fd-plan`, `/fd-code-review`)
+- **Auto-trigger**: FlowDeck hooks can invoke skills automatically based on context (e.g., `code-review` triggers after every code write, `deploy-check` before any deploy)
+
+## Skill Taxonomy
+
+### Planning & Requirements
+
+| Skill | Description |
+|-------|-------------|
+| `plan-task` | Wave-structured task breakdown for multi-file features |
+| `confidence-aware-planning` | Uncertainty-aware estimates — asks clarifying questions when confidence is low |
+| `intent-translator` | Converts vague requests ("make it faster") into ranked implementation options with tradeoffs |
+| `decision-trace` | Records why changes were made, what evidence was used, and what assumptions were made |
+
+Source files live in `src/skills/<name>/SKILL.md` in the project repository.
+
+### Architecture
+
+| Skill | Description |
+|-------|-------------|
+| `clean-architecture` | Layered architecture with independent use cases |
+| `hexagonal-architecture` | Ports-and-adapters pattern for testable business logic |
+| `layered-architecture` | Traditional UI / business logic / data layer separation |
+| `ddd-architecture` | Domain-driven design with bounded contexts and aggregates |
+| `saga-architecture` | Distributed transaction pattern for microservices |
+| `event-driven-architecture` | Event-based decoupling between services |
+| `cqrs` | Command-query responsibility segregation for read/write optimization |
+
+### Code Quality
+
+| Skill | Description |
+|-------|-------------|
+| `code-review` | Systematic review with security checklist and severity-ranked findings |
+| `tdd-workflow` | Red-green-refactor discipline with 80%+ coverage enforcement |
+| `test-coverage` | Coverage enforcement with pass/fail thresholds |
+| `test-gap-detector` | Identifies uncovered edge cases and suggests minimum viable test sets |
+| `refactor-guide` | Safe refactoring patterns — one transformation per commit, tests stay green |
+
+Source files live in `src/skills/<name>/SKILL.md` in the project repository.
+
+### Security
+
+| Skill | Description |
+|-------|-------------|
+| `security-scan` | Scans for OWASP vulnerabilities, injection risks, and credential leakage |
+| `patch-trust-score` | Scores patch reliability based on changelog, age, and publisher reputation |
+| `arch-constraint-guard` | Enforces architectural constraints at commit time |
+| `self-healing-policies` | Automatic rollback and recovery policies for failed deployments |
+
+### Deployment
+
+| Skill | Description |
+|-------|-------------|
+| `deploy-check` | Pre-deploy safety verification — runs tests, checks coverage, validates config |
+| `git-release` | Semantic version tagging and CHANGELOG generation for releases |
+
+### Performance
+
+| Skill | Description |
+|-------|-------------|
+| `performance-profiling` | Identifies hot paths and memory bottlenecks from profiling data |
+| `volatility-map` | Maps codebase areas by change frequency to predict impact zones |
+| `blast-radius-preview` | Estimates blast radius of a proposed change before it is merged |
+| `dependency-audit` | Scans for outdated, vulnerable, or circular dependencies |
+
+### Frontend
+
+| Skill | Description |
+|-------|-------------|
+| `frontend-pattern` | General frontend implementation patterns |
+| `ui-design` | Component-level UI design patterns |
+| `landing-page-design` | Landing page layout and conversion patterns |
+| `dashboard-design` | Dashboard layout and data visualization patterns |
+| `design-tokens` | Design tokens for consistent theming |
+| `app-shell-design` | Application shell and navigation patterns |
+| `wireframe-planning` | Low-fidelity wireframe to structured layout planning |
+| `design-audit` | Design consistency and accessibility review |
+| `ui-ux-planning` | Full UI/UX planning from user flow to component specs |
+| `responsive-review` | Responsive design verification across breakpoints |
+| `frontend-handoff` | Design-to-code handoff specification |
+
+### Backend
+
+| Skill | Description |
+|-------|-------------|
+| `backend-patterns` | General backend service patterns |
+| `golang-patterns` | Go-specific patterns (goroutines, channels, error handling) |
+| `java-patterns` | Java/JVM patterns (Spring, concurrency) |
+| `python-patterns` | Python patterns (async, dataclasses, typing) |
+| `rust-patterns` | Rust patterns (ownership, traits, concurrency) |
+| `postgres-patterns` | PostgreSQL schema, query, and indexing patterns |
+| `django-patterns` | Django-specific patterns (ORM, views, middleware) |
+| `django-tdd` | Django test-driven development workflow |
+
+### Intelligence
+
+| Skill | Description |
+|-------|-------------|
+| `failure-replay-engine` | Replays past failures to understand root causes |
+| `regression-prediction` | Predicts which files are likely to break from a given change |
+| `repo-memory-graph` | Builds a semantic graph of codebase knowledge |
+| `decision-trace` | Records decision rationale for future review |
+| `volatility-map` | Maps change frequency to identify stable vs. volatile areas |
+
+### Workflow
+
+| Skill | Description |
+|-------|-------------|
+| `git-workflow` | Git branch strategy, commit conventions, and PR workflow |
+| `agent-harness-construction` | How to construct and wire agents together |
+| `context-load` | Strategies for loading context efficiently |
+| `debug-flow` | Systematic debugging workflow |
+| `documentation-writer` | Generates documentation from code structure |
+| `human-review-routing` | Routes review requests to appropriate reviewers |
+
+### More
+
+Additional skills: `api-design`, `codebase-mapping`, `codebase-onboarding`, `code-tour`, `design-system-definition`, `multi-repo`.
+
+## Skill File Structure
+
+Each skill lives in `src/skills/<name>/SKILL.md` with YAML frontmatter:
+
+```yaml
+---
+name: skill-name
+description: One-line description of what the skill does
+origin: FlowDeck
+---
+
+# Skill Title
+
+Step-by-step workflow description...
+```
+
+## Adding New Skills
+
+1. Create `src/skills/<name>/SKILL.md` with frontmatter
+2. Add the skill path to the OpenCode plugin config in `src/index.ts`
+3. Skills become available immediately — no rebuild required

package/docs/skills/planning.md

@@ -0,0 +1,39 @@
+# Planning Skills
+
+These skills handle the "thinking before coding" phase — turning vague requests into concrete, executable plans with verifiable success criteria.
+
+---
+
+## plan-task
+
+Wave-structured task breakdown for multi-file features.
+
+Breaks complex features into phased wave-based plans. Each step maps to a file, has a verification check, and fits within a working session. Foundation-first ordering: types then data then services then routes then UI.
+
+---
+
+## confidence-aware-planning
+
+Uncertainty-aware estimates that signal low confidence instead of guessing.
+
+Adjusts planning behavior based on how certain the agent is. HIGH confidence proceeds normally. MEDIUM confidence surfaces explicit assumptions and risks. LOW confidence stops and asks clarifying questions before writing a plan.
+
+---
+
+## intent-translator
+
+Converts vague requests into ranked implementation options with tradeoffs.
+
+Takes input like "make checkout faster" and produces a ranked menu of 3-5 concrete options with file scope, effort estimates, risk ratings, and explicit tradeoffs — before any code is written. Stops and asks clarifying questions when intent is genuinely ambiguous.
+
+---
+
+## decision-trace
+
+Records why the agent changed something, what evidence was used, and what assumptions were made.
+
+Creates an append-only audit trail in `.codebase/DECISIONS.jsonl` for every non-trivial edit. Code reviewers can query decisions for any file in the diff and immediately understand the "why" without asking the author. Rationale answers "why this approach and not the obvious alternative?"
+
+---
+
+Source: `src/skills/<name>/SKILL.md` in the project repository.

package/package.json

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

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

@@ -89,7 +89,7 @@ Required fixes before deploy:
 - [ ] [fix 1]
 - [ ] [fix 2]
 
-Run /deploy-check again after fixing.
+Run /fd-deploy-check again after fixing.
 ```
 
 ## No-go conditions (automatic)
@@ -102,7 +102,7 @@ Any of these → automatic NO-GO:
 
 ### Step 4: Code Review Scope (--check=review)
 
-If `/deploy-check --check=review [scope]` provided: review files matching scope.
+If `/fd-deploy-check --check=review [scope]` provided: review files matching scope.
 If no scope: review all files changed since last commit.
 
 ```bash

package/src/commands/fd-discuss.md

@@ -11,16 +11,90 @@ Run a structured requirements discussion session and capture decisions.
 
 ## Pre-flight
 
-1. Check `.planning/STATE.md` exists — if not, return error: "Run /fd-new-project first."
+1. Check `.planning/STATE.md` exists — if not, return error: "No active feature. Run `/fd-map-codebase` then `/fd-new-feature` to start a feature."
 2. Read current phase from STATE.md.
 3. Create `.planning/phases/phase-<N>/` directory if it does not exist.
 
 ## Process
 
+### Step 0: CodeGraph Intelligence Check
+
+**Before any exploration**, check if codegraph provides existing code understanding:
+
+```
+codegraph action=check
+```
+
+- **If codegraph is installed and indexed (fresh)**: Use codegraph MCP tools to answer architecture, structure, and pattern questions directly. Prefer `codegraph_context`, `codegraph_search`, `codegraph_explore` over file reads.
+  - Log: "codegraph available — using code intelligence index for preflight exploration"
+- **If codegraph index is stale or has changed files**: Log "codegraph index may be stale — prefer direct verification for recent changes"
+- **If codegraph is not installed or not indexed**: Log "codegraph not available — will explore via @code-explorer"
+
+Use codegraph status to decide how Step 0 autonomous exploration is performed.
+
+### Step 0b: Autonomous Codebase Exploration
+
+**Before asking the user any question**, explore the repository to gather evidence.
+
+**If codegraph is available (indexed and fresh):**
+Use codegraph MCP tools directly for:
+1. **Project structure** — `codegraph_context` to map entry points and module layout
+2. **Tech stack detection** — `codegraph_files` and `codegraph_explore` on package manifests
+3. **Implementation patterns** — `codegraph_explore` on `src/` for service/component patterns
+4. Skip or minimally use @code-explorer — codegraph already provides the index
+
+**If codegraph is NOT available:**
+Invoke `@code-explorer` to inspect:
+1. **Project files** — `.planning/PROJECT.md` (goals, tech stack, constraints)
+2. **Session state** — `.planning/STATE.md` (current phase, prior decisions)
+3. **Prior discussions** — `.planning/phases/*/DISCUSS.md` (already-captured decisions)
+4. **Tech stack** — `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`
+5. **Implementation patterns** — `src/` directory structure (services, components, api, etc.)
+6. **AGENTS.md / rules** — any project-level constraints or conventions
+7. **Relevant source files** — files matching keywords in `$ARGUMENTS`
+
+In both cases, read:
+- `.planning/phases/*/DISCUSS.md` for prior decisions
+- `.codebase/CODEGRAPH.md` for codegraph index metadata if available
+
+Store exploration findings in the discussion context. These will be used to:
+- Skip questions whose answers are already known from the codebase
+- Inform the `@discusser` agent with concrete evidence
+- Prevent worker agents from emitting questions to the user
+
+
+1. **Project files** — `.planning/PROJECT.md` (goals, tech stack, constraints)
+2. **Session state** — `.planning/STATE.md` (current phase, prior decisions)
+3. **Prior discussions** — `.planning/phases/*/DISCUSS.md` (already-captured decisions)
+4. **Tech stack** — `package.json`, `go.mod`, `Cargo.toml`, `pyproject.toml`
+5. **Implementation patterns** — `src/` directory structure (services, components, api, etc.)
+6. **AGENTS.md / rules** — any project-level constraints or conventions
+7. **Relevant source files** — files matching keywords in `$ARGUMENTS`
+
+Store exploration findings in the discussion context. These will be used to:
+- Skip questions whose answers are already known from the codebase
+- Inform the `@discusser` agent with concrete evidence
+- Prevent worker agents from emitting questions to the user
+
+### Question suppression rule
+
+After exploration, apply the question guard before each `@discusser` question:
+
+> A `@discusser` question is skipped if:
+> 1. The answer already exists in `PROJECT.md`, `STATE.md`, or prior `DISCUSS.md` files
+> 2. The answer is determinable from the tech stack / implementation patterns
+> 3. The question was already answered in a prior session for this phase
+
+If a question is suppressed, record it in the DISCUSS.md `## Suppressed Questions` section
+with the evidence that answered it.
+
 ### Step 1: Load Context
 
 Read `.planning/PROJECT.md` to understand the project vision and goals.
 Read `.planning/STATE.md` to determine the current phase and context.
+Read any prior `.planning/phases/phase-<N>/DISCUSS.md` for existing decisions.
+
+Use exploration findings (from Step 0) to populate the discusser's starting context.
 
 ### Step 2: Determine Phase
 
@@ -32,11 +106,31 @@ Decisions will be saved to `.planning/phases/phase-{N}/DISCUSS.md`.
 Spawn @discusser agent with:
 - Project context (from PROJECT.md)
 - Current phase number
-- Instructions to ask ONE question per turn
+- **Preflight exploration findings** — the full ExplorationResult from Step 0, including:
+  - `techStack`: detected tech stack (e.g. ["Node.js / JavaScript / TypeScript"])
+  - `availableAgents`: list of registered agents
+  - `availableCommands`: list of available commands
+  - `implementationPatterns`: detected patterns (e.g. ["service layer", "agent architecture"])
+  - `evidenceItems`: evidence that can answer common questions
+  - `hasPriorDiscussions`: whether prior DISCUSS.md files exist
+- Instructions to ask ONE question per turn using the RecommendedQuestion format
+- Instructions to skip questions already answered by exploration evidence
 
 ### Step 4: Q&A Loop
 
-The @discusser agent asks one question at a time.
+The @discusser agent asks one question at a time using the RecommendedQuestion format.
+
+Before each question:
+1. Question guard check:
+   - If the question can be answered from exploration evidence → skip it, record as suppressed
+   - If the question was already asked in a prior session for this phase → skip it
+   - Otherwise → proceed to validation
+2. Recommendation validation:
+   - Parse the question block with `parseQuestionBlocks()`
+   - Validate with `validateRecommendedQuestion()`
+   - If validation fails (bare question, missing fields) → return a rewrite hint to @discusser
+   - If validation passes → format with `formatRecommendedQuestion()` and present to the user
+
 After each user response:
 - Assign D-XX number to any new decision
 - Record: topic, choice, rationale
@@ -44,7 +138,7 @@ After each user response:
 
 Continue until all required topics are covered or user says to stop early.
 
-Structure the discussion:
+Structure the discussion (skip topics already answered by exploration):
 
 1. **Scope** — What exactly needs to be built/changed? What is out of scope?
 2. **Constraints** — Technical constraints, deadlines, dependencies?
@@ -53,6 +147,7 @@ Structure the discussion:
 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.
+Do not ask about things the codebase already reveals.
 
 ## Decision Recording
 
@@ -65,12 +160,35 @@ After the discussion, write `.planning/phases/phase-<N>/DISCUSS.md`:
 **Date:** <timestamp>
 **Topic:** <topic>
 
+## Preflight Evidence Used
+
+- Tech stack: <detected stack>
+- Prior decisions loaded: <yes/no>
+- Questions suppressed by evidence: <N>
+
 ## Decisions
 
 D-01: [Topic] — [Decision] ([Rationale])
 D-02: [Topic] — [Decision] ([Rationale])
 ...
 
+## Answered Recommendations
+
+RQ-01: [question]
+  Recommendation: [the recommended answer]
+  User choice: [what they said]
+  Rationale: [why the system recommended it]
+  Asked by: discusser
+  Stage: discuss
+  Timestamp: <ISO 8601>
+...
+
+## Suppressed Questions
+
+(Questions that were answered by repo evidence and not asked of the user)
+- "<question>" → answered by: <evidence source>
+...
+
 ## Open Questions
 
 - <any unresolved items>
@@ -83,19 +201,22 @@ D-02: [Topic] — [Decision] ([Rationale])
 ## D-05 Compliance
 
 - Loads PROJECT.md + current phase STATE.md
-- Invokes @discusser agent
+- **Performs codebase exploration before any question is asked (Step 0)**
+- Invokes @discusser agent with full exploration context
 - Saves decisions with D-XX numbering to DISCUSS.md
 - One question at a time (no compound questions)
+- Questions suppressed when answered by evidence
 
 ## Completion
 
-Report: decisions captured, file path, and suggest running `/fd-plan`.
+Report: decisions captured, questions suppressed, file path, and suggest running `/fd-plan`.
 If UI-heavy, also suggest running `/fd-design --mode=draft` before `/fd-execute`.
 
 ## Error Handling
 
 D-03: Fail fast with clear error
-- If PROJECT.md not found: error with "Run /fd-new-project first"
+- If PROJECT.md not found: proceed without it (PROJECT.md is optional in the new flow; codebase context is provided by `.codebase/`)
 - If STATE.md not found: error with "Project not initialized"
 - If @discusser fails: error with "Discusser agent unavailable"
+- If @code-explorer fails during preflight: proceed with reduced evidence (log warning)
 - No partial state saved on error