@dv.nghiem/flowdeck 0.3.9 → 0.4.0

package/docs/reference/hooks.md

@@ -0,0 +1,176 @@
+# System Hooks Reference
+
+FlowDeck implements deep system hooks that react to OpenCode lifecycle events. These hooks maintain session state, inject environment context, monitor resource usage, and send notifications without requiring any explicit commands.
+
+---
+
+## Hooks Overview
+
+| Hook | Fires On | Purpose |
+|------|----------|---------|
+| `session-start` | `session.created` | Loads and injects prior planning state into the new session |
+| `compaction` | `experimental.session.compacting` | Preserves planning context before context window compaction |
+| `shell-env` | Every `bash` tool execution | Injects FlowDeck environment variables |
+| `context-window-monitor` | `message.updated`, `tool.execute.after` | Warns when context usage exceeds 70% of the token limit |
+| `session-idle` | `session.idle` (when files edited) | Desktop notification and edits summary logging |
+| `notifications` | Various | Desktop notification dispatch |
+| `file-tracker` | During session | Tracks edited file paths across agent turns |
+
+---
+
+## `session-start` Hook
+
+**File:** `src/hooks/session-start.ts`
+
+**Fires:** `session.created` — when a new OpenCode session starts.
+
+**What it does:**
+
+Reads `.planning/STATE.md` from the workspace and injects the following context keys:
+
+| Context Key | Source | Description |
+|------------|--------|-------------|
+| `flowdeck_phase` | `current_phase.phase` in STATE.md | Current planning phase or `null` if fresh |
+| `flowdeck_status` | `current_phase.status` in STATE.md | Phase status or `null` |
+| `flowdeck_steps_pending` | `current_phase.steps_pending` in STATE.md | Pending steps or `null` |
+| `flowdeck_last_action` | `current_phase.last_action` in STATE.md | Last executed action or `null` |
+| `flowdeck_has_codebase` | — | Whether `.codebase/` directory exists |
+| `flowdeck_workspace_root` | `opencode.json` workspace config | Workspace root if multi-repo detected |
+| `flowdeck_sub_repos` | `opencode.json` workspace config | List of sub-repositories |
+| `flowdeck_workspace_mode` | `opencode.json` workspace config | Workspace mode |
+
+**State read:**
+- `.planning/STATE.md`
+- `.codebase/` (existence check only)
+- `opencode.json` (workspace config, if present)
+
+**Errors:** If the state file is unreadable, the hook returns with `flowdeck_status: "error"` and a warning message — it does not block session startup.
+
+---
+
+## `compaction` Hook
+
+**File:** `src/hooks/compaction-hook.ts`
+
+**Fires:** `experimental.session.compacting` — when OpenCode triggers context window compaction.
+
+**What it does:**
+
+Injects a structured 8-section summary into the compaction context so the LLM summarization preserves FlowDeck-specific state:
+
+1. **Planning State** — First 1500 characters of `.planning/STATE.md`
+2. **Codebase Index** — First 800 characters of `.planning/CODEBASE_INDEX.md` (if present)
+3. **Recently Edited Files** — Up to 20 files from `SessionFileTracker`
+
+Then replaces the default summarization prompt with a structured template that requires the summary to include:
+- User requests (verbatim)
+- Final goal
+- Work completed
+- Remaining tasks
+- Active working context
+- Explicit constraints (verbatim)
+- Verification state
+- Delegated agent sessions (with `session_id` for resume)
+
+**State read:**
+- `.planning/STATE.md`
+- `.planning/CODEBASE_INDEX.md`
+- In-memory `SessionFileTracker` (edited paths ring buffer)
+
+---
+
+## `shell-env` Hook
+
+**File:** `src/hooks/shell-env-hook.ts`
+
+**Fires:** Every `bash` tool execution.
+
+**What it does:**
+
+Injects the following environment variables into every bash tool execution:
+
+| Env Var | Source | Description |
+|---------|--------|-------------|
+| `FLOWDECK_VERSION` | `package.json` | Installed FlowDeck version |
+| `FLOWDECK_PLUGIN` | `"true"` (constant) | Plugin activation flag |
+| `PROJECT_ROOT` | `worktree` or `directory` | Resolved project root |
+| `PACKAGE_MANAGER` | Detected lockfile | `npm`, `yarn`, `pnpm`, or `bun` |
+| `DETECTED_LANGUAGES` | Marker files scan | Comma-separated list (e.g., `typescript,python`) |
+| `PRIMARY_LANGUAGE` | Marker files scan | First detected language |
+| `FLOWDECK_PHASE` | `STATE.md` phase field | Current FlowDeck planning phase |
+
+Language detection uses marker files: `tsconfig.json` (TypeScript), `go.mod` (Go), `pyproject.toml`/`requirements.txt` (Python), `Cargo.toml` (Rust), `build.gradle`/`pom.xml` (Java).
+
+**State read:** `package.json`, lockfiles, marker files, `.planning/STATE.md`
+
+---
+
+## `context-window-monitor` Hook
+
+**File:** `src/hooks/context-window-monitor.ts`
+
+**Fires:** `message.updated` (assistant messages with token info), `tool.execute.after`.
+
+**What it does:**
+
+Tracks token usage per session. When input token usage exceeds 70% of `FLOWDECK_CONTEXT_LIMIT` (default: 200,000 tokens), appends a warning to the next tool output:
+
+```
+[FlowDeck Context Monitor]
+Context: 71.4% used (142,800/200,000 tokens), 28.6% remaining.
+You still have context remaining — do NOT rush or skip tasks. Work thoroughly.
+```
+
+The warning fires once per session (tracked by `sessionID`).
+
+**Token limit override:** Set `FLOWDECK_CONTEXT_LIMIT` env var (e.g., `FLOWDECK_CONTEXT_LIMIT=150000`).
+
+**State read:** Per-session token cache from `message.updated` events.
+
+---
+
+## `session-idle` Hook
+
+**File:** `src/hooks/session-idle-hook.ts`
+
+**Fires:** `session.idle` — when OpenCode's session becomes idle after a task is completed.
+
+**Fires only when:** At least one file has been edited during the session (empty idle events are ignored).
+
+**What it does:**
+
+1. Sends a desktop notification via `notifySessionIdle()`
+2. Logs a session summary via `client.app.log` (up to 10 edited files, then `… and N more`)
+
+**State read:** In-memory `SessionFileTracker` (edited paths ring buffer).
+
+---
+
+## `file-tracker`
+
+**File:** `src/hooks/file-tracker.ts`
+
+**When it runs:** Continuously during session, tracking every file path edited by agents.
+
+**What it does:**
+
+Maintains a ring buffer of edited file paths. Consumed by the `compaction` hook (recently edited files) and `session-idle` hook (edited summary).
+
+Implements a windowed snapshot of edited paths per session — consumed by compaction hook and idle hook.
+
+---
+
+## Other Hooks
+
+| Hook | File | Purpose |
+|------|------|---------|
+| `approval-hook` | `approval-hook.ts` | Phase/project-level approval gates |
+| `orchestrator-guard-hook` | `orchestrator-guard-hook.ts` | Guarding orchestrator delegation patterns |
+| `decision-trace-hook` | `decision-trace-hook.ts` | Decision audit trail |
+| `telemetry-hook` | `telemetry-hook.ts` | Workflow telemetry |
+| `patch-trust` | `patch-trust.ts` | AI safety: patch trust scoring |
+| `tool-guard` | `tool-guard.ts` | Tool usage guardrails |
+| `auto-learn-hook` | `auto-learn-hook.ts` | Runtime policy learning |
+| `todo-hook` | `todo-hook.ts` | Todo tracking integration |
+
+These hooks are internal governance and safety mechanisms. The five hooks described above are the ones users interact with most directly.

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.9",
+  "version": "0.4.0",
   "description": "FlowDeck — structured planning and execution workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",

package/src/commands/fd-discuss.md

@@ -11,17 +11,57 @@ 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: Autonomous Codebase Exploration
+### 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)
@@ -66,17 +106,30 @@ Decisions will be saved to `.planning/phases/phase-{N}/DISCUSS.md`.
 Spawn @discusser agent with:
 - Project context (from PROJECT.md)
 - Current phase number
-- **Preflight exploration findings** (tech stack, patterns, existing decisions)
-- 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.
-Before each question, the question guard is checked:
-- 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 → ask the user
+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
@@ -119,6 +172,17 @@ 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)
@@ -151,7 +215,7 @@ 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)