docs: add editable plan card design spec

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/superpowers/specs/2026-04-12-editable-plan-card-design.md

@@ -0,0 +1,164 @@
+# Editable Plan Card Design Spec
+
+**Date:** 2026-04-12
+**Status:** Approved
+
+## Problem
+
+The plan card in the planning review gate is read-only. Users can only approve or reject the entire plan. There is no way to:
+- Edit individual field values before approving
+- Add notes or comments about the plan
+- Ask a specific agent to help fill or refine a field
+- Save partial edits and continue chatting before re-triggering a plan
+
+## Solution
+
+Extend the existing inline plan card with per-field editing, an "Ask Agent" button per field, a notes text area, dual score display, and a third "Save & Continue" action button.
+
+## Design
+
+### 1. Per-Field Editing
+
+Each plan field displays two icon buttons next to its value:
+
+**Edit icon (pencil)** — toggles the value between read-only text and an editable input:
+- `part_name`, `material`, `axis_recommendation` — text input
+- `dimensions` — group of number inputs (width/height/depth in mm)
+- `features`, `constraints`, `machining_notes` — comma-separated text input (parsed back to list)
+
+**Ask Agent icon** — sends a pre-formatted, mention-targeted message to the chat. The message includes current plan context for agent awareness:
+- Template: `@{agent} Regarding the plan for "{part_name}": {field-specific question}`
+- Example: `@engineering Regarding the plan for "mounting_bracket": What material do you recommend given the current constraints: [min wall 3mm]?`
+
+When the user edits a field, the plan card's local state updates immediately (no API call). Edited values are sent on Approve or Save & Continue.
+
+**Agent-to-field mapping** (configurable in `config.yaml` under `planning.field_agents`):
+
+| Field | Agent | Question |
+|-------|-------|----------|
+| `part_name` | design | What should this part be called? |
+| `material` | engineering | What material do you recommend? |
+| `dimensions` | engineering | What dimensions are appropriate? |
+| `features` | design | What features should this part have? |
+| `constraints` | cnc | What manufacturing constraints should we consider? |
+| `axis_recommendation` | cnc | What axis strategy do you recommend? |
+| `machining_notes` | cnc | Any machining notes to consider? |
+
+### 2. Notes Area
+
+A text area at the bottom of the plan card, above the action buttons.
+- Placeholder text: "Add notes about this plan..."
+- Stored in the plan object as a new `notes: str` field on `DesignPlan`
+- Passed to agents as additional context when the plan is approved (appended to the `render_approved()` output)
+- Persisted in `designState` on Save & Continue
+
+### 3. Dual Score Display
+
+Replaces the current single score display with two scores side by side:
+- **Original** — the score when the plan was generated (static)
+- **Current** — recalculated live as fields are edited, using the existing frontend `computeScore()` logic
+
+Display format: `Original: 8/8 → Current: 6/8`
+
+Current score is color-coded:
+- Green if >= threshold (default 8)
+- Yellow/red if below threshold
+
+### 4. Action Buttons
+
+Three buttons replace the current two:
+
+- **Approve** (green) — sends the edited plan (with field changes + notes) to `POST /api/plan/approve`. Sets `phase = "approved"`. Auto-sends "Generate the approved design" to chat.
+- **Save & Continue** (secondary/blue) — merges edited field values back into `designState`, saves notes, sets `phase = "exploring"`, removes the plan card from DOM. User can keep chatting; edits preserved for the next plan trigger. Frontend-only operation (no API call), updates `designState` in localStorage.
+- **Reject** (secondary/red) — discards all edits made in the plan card. Sets `phase = "exploring"`, `plan = null`.
+
+### 5. Ask Agent Chat Integration
+
+When the user clicks "Ask Agent" on a field:
+
+1. Frontend constructs a mention-targeted message using the existing `sendMessage()` function with current plan context.
+2. Chat tab activates automatically (if user is on wizard tab).
+3. User reads the agent response in chat, then scrolls up to the plan card and edits the field manually.
+
+No new API endpoints — reuses existing `POST /api/chat` with `@mentions` routing.
+
+## Data Model Changes
+
+### `DesignPlan` (`agents/design_state.py`)
+
+Add field:
+```python
+notes: str = ""
+```
+
+Update `render_approved()` to include notes:
+```
+## USER NOTES
+{self.notes}
+```
+
+### `config.yaml`
+
+Add under `planning`:
+```yaml
+planning:
+  field_agents:
+    material: engineering
+    dimensions: engineering
+    features: design
+    constraints: cnc
+    axis_recommendation: cnc
+    machining_notes: cnc
+    part_name: design
+```
+
+### `PlanningConfig` (`config/settings.py`)
+
+Add field:
+```python
+field_agents: dict[str, str] = {
+    "material": "engineering",
+    "dimensions": "engineering",
+    "features": "design",
+    "constraints": "cnc",
+    "axis_recommendation": "cnc",
+    "machining_notes": "cnc",
+    "part_name": "design",
+}
+```
+
+## Backend Changes
+
+- `POST /api/plan/approve` — already accepts full plan object. Add `notes` field handling: merge into `DesignState`, include in `render_approved()`.
+- `POST /api/plan/reject` — no change.
+- No new endpoint for Save & Continue (frontend-only operation).
+
+## Frontend Changes (`web/index.html`)
+
+### `renderPlanCard(plan)`
+- Each `wizard-review-field` value gets pencil icon + agent icon buttons
+- Pencil toggles between `<span>` and `<input>` for the value
+- Agent icon calls `askAgentForField(fieldName)`
+- Notes `<textarea>` added before action buttons
+- Score area shows original + current side by side
+- Three action buttons: Approve, Save & Continue, Reject
+
+### New functions
+- `toggleFieldEdit(fieldName)` — switches field between view/edit mode
+- `askAgentForField(fieldName)` — constructs mention-targeted message, calls `sendMessage()`, switches to chat tab
+- `savePlanAndContinue()` — merges edited values into `designState`, saves to localStorage, removes plan card, resets phase to exploring
+- `recalcPlanScore()` — reads current field values from plan card inputs, runs `computeScore()`, updates current score display
+
+### Modified functions
+- `approvePlanCard()` — reads edited field values + notes from plan card inputs before sending to API
+- `computeScore()` — no logic change, just called by `recalcPlanScore()`
+
+## Testing
+
+- Verify field toggling between view/edit mode for all field types
+- Verify Ask Agent sends correct mention-targeted message with plan context
+- Verify notes persist through Save & Continue and appear in agent context on Approve
+- Verify dual score: original stays static, current recalculates on field edit
+- Verify Save & Continue preserves edits in designState and resets phase
+- Verify Reject discards all edits
+- Verify Approve sends edited values (not original values)