# Planning Board Mode Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add a user-toggleable planning board mode where Flow behaves like a normal Kanban/Jira-style planner and never starts implementation from typed prompts or board moves.

**Architecture:** Persist a runtime `planningBoardModeEnabled` setting, resolve it through the existing ZoneGaze feature settings, and enforce it in the shared editor/start hooks. Prompt refinement stays deterministic and local for safe board creation; agent prompts also receive planning-mode guidance so Cline/upstream agents refine board items instead of implementing.

**Tech Stack:** TypeScript, React, Vitest, existing Flow runtime config and board-state helpers.

---

### Task 1: Persist Planning Board Mode

**Files:**
- Modify: `flow/contracts/src/api-contract.ts`
- Modify: `flow/runtime/src/config/runtime-config.ts`
- Modify: `flow/web/src/runtime/zonegaze-feature-settings.ts`
- Modify: `flow/web/src/components/runtime-settings-dialog.tsx`
- Test: `test/runtime/config/runtime-config.test.ts`
- Test: `flow/web/src/runtime/zonegaze-feature-settings.test.ts`

- [ ] **Step 1: Write failing config tests**

Assert `planningBoardModeEnabled` defaults to false, saves true when requested, and resolves false when ZoneGaze Flow features are disabled.

- [ ] **Step 2: Implement config schema and settings UI**

Add the optional save field, response field, runtime config normalization, settings state, dirty check, save payload, and a ZoneGaze settings switch labeled `Planning board mode`.

- [ ] **Step 3: Verify**

Run: `npm test -- test/runtime/config/runtime-config.test.ts flow/web/src/runtime/zonegaze-feature-settings.test.ts`

### Task 2: Refine Prompts Into Board Items

**Files:**
- Create: `flow/web/src/utils/planning-board-refinement.ts`
- Create: `flow/web/src/utils/planning-board-refinement.test.ts`
- Modify: `flow/web/src/hooks/use-task-editor.ts`
- Modify: `flow/web/src/hooks/use-task-editor.test.tsx`

- [ ] **Step 1: Write failing refinement tests**

Assert plain prompts become detailed task cards, list prompts become multiple task cards, and hierarchy-enabled prompts create an Epic -> Story -> Task -> Subtask chain with implementation-ready handoff text.

- [ ] **Step 2: Hook into task creation**

When `planningBoardModeEnabled` is true, create refined cards with `autoReviewEnabled: false`, no agent overrides, and no implementation start metadata. Preserve parent/dependency links.

- [ ] **Step 3: Verify**

Run: `npm --prefix flow/web test -- src/utils/planning-board-refinement.test.ts src/hooks/use-task-editor.test.tsx`

### Task 3: Prevent Implementation Starts In Planning Mode

**Files:**
- Modify: `flow/web/src/hooks/use-board-interactions.ts`
- Modify: `flow/web/src/App.tsx`
- Modify: `flow/web/src/components/task-create-dialog.tsx`
- Modify: `flow/web/src/components/task-inline-create-card.tsx`
- Test: `flow/web/src/hooks/use-board-interactions.test.tsx`
- Test: `flow/web/src/components/task-create-dialog.test.tsx`

- [ ] **Step 1: Write failing start-suppression tests**

Assert create-and-start controls are absent/disabled in planning mode and dragging or bulk-moving Backlog cards to In Progress only changes status without calling `startTaskSession`.

- [ ] **Step 2: Enforce the gate**

Hide start buttons and agent/model fields, pass no start handlers from `App`, skip auto-pick, and make drag/bulk In Progress transitions normal board moves when `planningBoardModeEnabled` is true.

- [ ] **Step 3: Verify**

Run focused component and hook tests, then run the Flow web test suite.

### Task 4: Agent Prompt Guard

**Files:**
- Modify: `flow/runtime/src/prompts/append-system-prompt.ts`
- Test: `test/runtime/append-system-prompt.test.ts`

- [ ] **Step 1: Write failing prompt test**

Assert planning board mode adds guidance that the agent must refine/create board items and must not start tasks or implement.

- [ ] **Step 2: Add prompt guidance**

Thread `planningBoardModeEnabled` through task and home-agent launch prompt options.

- [ ] **Step 3: Verify**

Run: `npm test -- test/runtime/append-system-prompt.test.ts`
