feat: Plannr Platform — Planner, Ideation, Forge, Mull, Cultivate, Portfolio-Core, Tend

.claude/agents/flow.md

@@ -0,0 +1,188 @@
+---
+name: flow
+description: When user mentions features, requirements, planning, or asks "what should I build next", proactively show feature status and suggest next actions. Entry point for all flow-* skills.
+tools: Read, Write, Glob, Grep, Bash, TaskCreate, TaskUpdate, TaskList, TaskGet
+skills:
+  - flow-schema
+  - flow-discover
+  - flow-brainstorm
+  - flow-planner
+  - flow-feature
+  - flow-ui-ux-validation
+  - flow-test-designer
+  - flow-change-request
+  - flow-visualize
+  - flow-tasks
+---
+
+You have all flow skills preloaded. Use them to manage the feature lifecycle.
+
+**Schema**: See `flow-schema.md` for data structures.
+
+## Critical Rule: Always Persist
+
+**NEVER just summarize in chat.** All feature information MUST be written to `docs/flow/` files:
+- `docs/flow/catalog.json` - project index with components and features
+- `docs/flow/features/<slug>.json` - feature details
+
+If files don't exist, create them. If they exist, update them.
+
+## Output Rule
+
+After completing ANY workflow that creates or modifies features:
+1. **Write** results to docs/flow/ files (catalog.json, feature files)
+2. **Visualize** using flow-visualize to show current state
+3. **Suggest** next action based on incomplete sections
+
+## Purpose
+
+Central entry point for all flow skills:
+- Show project/feature status
+- Suggest next actions based on current state
+- Route to appropriate sub-skill
+- Detect requirement changes
+
+## Usage
+
+| Command | Action |
+|---------|--------|
+| `/flow` | Show status + suggest next action |
+| `/flow status` | Status only (compact view) |
+| `/flow visualize` | ASCII diagram of feature state |
+| `/flow visualize dag` | Dependency graph view |
+| `/flow discover` | Analyze codebase → create features |
+| `/flow brainstorm` | New feature from rough idea |
+| `/flow planner` | Create implementation plan |
+| `/flow tasks` | Create executable tasks from plan |
+| `/flow feature` | Document user flow |
+| `/flow validate` | Validate UI/UX |
+| `/flow test` | Design test coverage |
+| `/flow change` | Handle requirement changes |
+| `/flow <intent>` | Detect appropriate skill from input |
+
+## Intent Detection
+
+When user provides `/flow <text>`, detect appropriate skill:
+
+| User intent patterns | Route to |
+|---------------------|----------|
+| "status", "show", "visualize", "diagram" | flow-visualize |
+| "dag", "dependencies", "blocking", "what's blocking" | flow-visualize (DAG view) |
+| "analyze", "map", "discover", "what exists", "traverse" | flow-discover |
+| "plan", "implement", "how to build" | flow-planner |
+| "tasks", "tasks", "ready to build", "let's build" | flow-tasks |
+| "flow", "steps", "behavior", "what happens when" | flow-feature |
+| "validate", "check UI", "test the UI", "looks like" | flow-ui-ux-validation |
+| "test", "coverage", "test cases" | flow-test-designer |
+| "change", "update", "modify", "actually we need" | flow-change-request |
+| "new feature", "add feature", "idea" | flow-brainstorm |
+
+If unclear, ask: "Which would you like to do?" + list options.
+
+## Choosing Discover vs Brainstorm
+
+| Situation | Use |
+|-----------|-----|
+| Existing codebase, no flow docs | flow-discover |
+| New project, starting from idea | flow-brainstorm |
+| Adding features to documented project | flow-brainstorm |
+| "What features exist?" | flow-discover |
+| "I want to build X" | flow-brainstorm |
+
+## Section Ownership
+
+| Section | Skill | Purpose |
+|---------|-------|---------|
+| `summary` | flow-brainstorm/flow-discover | What the feature is |
+| `understanding` | Any agent (as needed) | Agent observations during ideation |
+| `context` | Any agent (as needed) | Formalized decisions by role |
+| `design_spec` | flow-ui-ux-designer | How it looks (views, components) |
+| `user_flow` | flow-feature | How it behaves (for testing) |
+| `plan_implementation` | flow-planner | How to build it (steps + specification) |
+| `plan_tests` | flow-test-designer | Test design/coverage |
+| `validation_uiux` | flow-ui-ux-validation | UI/UX validation results |
+| `audit` | flow-audit | Implementation verification |
+
+**Note**: `understanding` and `context` can be added by any skill when observations or decisions are made. They're not exclusive to one skill.
+
+## Understanding and Context
+
+These sections capture knowledge during the workflow:
+
+**Understanding** = Agent observations during ideation (keyed by role)
+- What patterns apply? What questions need answers? What concerns exist?
+- Common roles: architect, designer, tester, security, modeler
+
+**Context** = Formalized decisions by role (freeform key-value)
+- Tech stack choices, design decisions, testing strategies
+- Feature-level context can extend project-level `catalog.design_system`
+
+**Specification** = Step-level technical details in `plan_implementation.steps`
+- Architecture patterns, design choices, security requirements
+- Freeform: any domain (architecture, design, model, testing, security)
+
+## Status Check
+
+Read `docs/flow/catalog.json` and `docs/flow/features/*.json`.
+Use flow-visualize to render status.
+
+## Suggest Next Action
+
+Use feature DAG (dependencies + priority) to determine work order:
+1. Find **unblocked** features (no dependencies, or all dependencies complete)
+2. Sort by **priority** (critical > high > medium > low)
+3. Suggest highest priority unblocked feature with incomplete sections
+
+| State | Suggestion |
+|-------|------------|
+| No catalog | "Run /flow discover (existing project) or /flow brainstorm (new project)" |
+| Features missing summary | "Complete /flow brainstorm or /flow discover" |
+| Features with plan but no tasks | "Create tasks with /flow tasks" |
+| Unblocked features missing sections | "Next: [feature] (priority: X) - needs [section]" |
+| All unblocked complete, blocked remain | "Blocked features: X, Y depend on Z" |
+| All sections complete | "All features complete. Review or publish." |
+
+## Skill Order
+
+```
+discover ──┐
+           ├──→ planner ──→ tasks ──→ [implement]
+brainstorm ┘        │
+     │              │
+     └───→ feature ─┴─→ ui-ux-validation
+               │
+               └──→ test-designer
+```
+
+- **discover** or **brainstorm** first (creates catalog + summaries + initial understanding/context)
+- **planner** creates implementation steps with specifications
+- **tasks** creates executable tasks with PRE/IMPL/POST/VERIFY/DOC
+- **feature** can run in parallel with planner
+- **ui-ux-designer** populates design_spec and context.designer
+- **ui-ux-validation** and **test-designer** require user_flow
+- All can be re-run via **change-request** if requirements change
+
+## Detect Change Requests
+
+If input suggests changes to existing features:
+→ "This sounds like a requirement change. Run /flow change?"
+
+Indicators: "actually we need...", "change X to Y", "add/remove requirement"
+
+## Plan Immutability
+
+- Plans are immutable once approved
+- If implementation diverges → use `/flow change-request`
+- Never silently modify approved plans
+- Progress is tracked in tasks, not in plan files
+
+## Rules
+
+- **Always write to docs/flow/** - never just chat summaries
+- **Always visualize after changes** - show what happened
+- **Capture understanding** - note observations during ideation
+- **Record context** - persist decisions for future reference
+- Status: ≤5 lines for quick checks
+- Suggestions: single sentence each
+- Don't switch skills without user confirmation
+- If unsure which skill, ask

.claude/hooks/guard-git.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+# Guard against destructive git commands.
+# Claude Code PreToolUse hook for the Bash tool.
+#
+# Exit 0 = allow
+# Exit 2 = block (stderr shown as reason)
+#
+# Receives JSON on stdin: { "tool_name": "Bash", "tool_input": { "command": "..." } }
+
+set -euo pipefail
+
+# Extract the command from JSON stdin
+CMD=$(jq -r '.tool_input.command // empty' 2>/dev/null)
+
+if [[ -z "$CMD" ]]; then
+  exit 0
+fi
+
+# --- Pattern checks ---
+
+# 1. rm targeting .git (any flags, any path containing .git)
+if echo "$CMD" | grep -qE '\brm\b.*\.(git|git/|git\b)'; then
+  echo "BLOCKED: Deleting .git is catastrophic. This destroyed the repo on Feb 13. Never again." >&2
+  exit 2
+fi
+
+# 2. git init (reinitializing destroys worktree links and history)
+if echo "$CMD" | grep -qE '\bgit\s+init\b'; then
+  echo "BLOCKED: 'git init' destroys existing repo state. This is what caused the Feb 13 disaster." >&2
+  exit 2
+fi
+
+# 3. git reset --hard (destroys uncommitted work)
+if echo "$CMD" | grep -qE '\bgit\s+reset\s+--hard\b'; then
+  echo "BLOCKED: 'git reset --hard' causes permanent data loss. Use Edit tool to undo changes manually." >&2
+  exit 2
+fi
+
+# 4. git clean -f (deletes untracked files permanently)
+if echo "$CMD" | grep -qE '\bgit\s+clean\s+-[a-zA-Z]*f'; then
+  echo "BLOCKED: 'git clean -f' permanently deletes untracked files. Review with 'git clean -n' first and delete manually." >&2
+  exit 2
+fi
+
+# 5. git push --force / -f (can overwrite remote history)
+if echo "$CMD" | grep -qE '\bgit\s+push\s+.*(-f\b|--force\b|--force-with-lease\b)'; then
+  echo "BLOCKED: Force push can destroy remote history. Get explicit user confirmation first." >&2
+  exit 2
+fi
+
+# 6. git checkout . (discard ALL working tree changes)
+if echo "$CMD" | grep -qE '\bgit\s+checkout\s+\.\s*$'; then
+  echo "BLOCKED: 'git checkout .' discards all uncommitted changes. Use Edit tool to undo specific changes." >&2
+  exit 2
+fi
+
+# 7. git restore . (discard ALL working tree changes)
+if echo "$CMD" | grep -qE '\bgit\s+restore\s+\.\s*$'; then
+  echo "BLOCKED: 'git restore .' discards all uncommitted changes. Use Edit tool to undo specific changes." >&2
+  exit 2
+fi
+
+# 8. git branch -D (force delete branch, may lose commits)
+if echo "$CMD" | grep -qE '\bgit\s+branch\s+-D\b'; then
+  echo "BLOCKED: 'git branch -D' force-deletes branches and may lose commits. Use -d (lowercase) for safe delete." >&2
+  exit 2
+fi
+
+# 9. git stash drop / git stash clear (lose stashed work)
+if echo "$CMD" | grep -qE '\bgit\s+stash\s+(drop|clear)\b'; then
+  echo "BLOCKED: Dropping/clearing stashes loses work. Show stash contents first and get user confirmation." >&2
+  exit 2
+fi
+
+# 10. Deleting remote branches via push
+if echo "$CMD" | grep -qE '\bgit\s+push\s+\S+\s+:'; then
+  echo "BLOCKED: Deleting remote branches. Get explicit user confirmation first." >&2
+  exit 2
+fi
+
+# 11. rm -rf targeting any directory that could be catastrophic
+if echo "$CMD" | grep -qE '\brm\s+-rf\s+/'; then
+  echo "BLOCKED: 'rm -rf /' pattern detected. Use 'trash' command instead of rm." >&2
+  exit 2
+fi
+
+# All checks passed
+exit 0

.claude/rules/agent-relay.md

@@ -0,0 +1,90 @@
+# Agent-Relay Patterns
+
+## spawn() vs RelayClient
+
+Critical distinction for this project:
+
+| Pattern | Use Case | Lifecycle |
+|---------|----------|-----------|
+| `spawn()` | Task-oriented CLI agents | Executes task, then exits |
+| `RelayClient` | Persistent services | Always-on, listens for messages |
+
+**PlannerLead uses `RelayClient`**, not `spawn()`. It's a persistent service that needs to remain active and respond to messages.
+
+## Non-Blocking Connection Pattern
+
+Server startup does not block on relay availability:
+- Relay connection attempted at startup but failure doesn't block
+- **Connected mode**: Real agents, full relay messaging
+- **Disconnected mode**: Mock responses, test mode fallback
+- Check connection status to determine operational mode
+
+## PlannerLead Architecture
+
+Location: `packages/server/src/relay/planner-lead.ts`
+
+- Persistent service using `RelayClient` (NOT `spawn()`)
+- Listens on `#planner` channel + individual `#plan-{uuid}` channels
+- Uses Anthropic SDK for responses (mock fallback if key missing)
+- Tool calling support: 10 tools in `planner-lead-tools/` for plan CRUD, step manipulation
+- Conversation history management per channel
+
+## Channel Membership
+
+- Agents must explicitly call `joinChannel()` before sending/receiving channel messages
+- Broadcast requires channel membership in relay daemon
+
+## Plan Channel IDs
+
+- Format: `#plan-{full-uuid}` (uses full UUID for consistency)
+- Display truncation happens in UI layer, not in channel IDs
+- Use `getPlanChannelId()` from `packages/server/src/relay/channels.ts`
+
+## Message Routing (ws-proxy)
+
+Location: `packages/server/src/relay/ws-proxy.ts`
+
+WebSocket proxy bridges browser ↔ relay communication:
+- Mounted at `/ws/relay` route
+- Direct messages: `client.sendMessage()`
+- Channel messages: `client.sendChannelMessage()`
+- Always pass `fromName` and `entityType` for proper rendering
+
+## Cross-Domain Bridges
+
+**Ideation Bridge** (`packages/server/src/relay/ideation-bridge.ts`):
+- Listens for relay messages tagged for ideation
+- Forwards to ideation service
+- Enables domain communication without direct coupling
+
+**Forge Spawner** (`packages/server/src/relay/forge-spawner.ts`):
+- Creates forge tasks when plan execution requested via relay
+- Bridges planning → execution workflow
+
+## Frontend Relay Integration
+
+Location: `packages/planner-ui/src/contexts/RelayContext.tsx`
+
+- `RelayContext` provides shared WebSocket connection
+- `useRelayConnection` manages WebSocket lifecycle (connect/reconnect/handlers)
+- `useActiveChannels` subscribes to plan channels
+- `useChannelMessages` fetches channel message history
+- **Single shared connection per app via Context** (never per-component)
+
+## Real-time Updates
+
+- `usePlanEvents` hook subscribes to SSE for plan changes
+- For persistent services like PlannerLead, don't gate subscriptions on `connectionStatus === 'connected'`—always subscribe
+
+## Connection Handling
+
+- Implement graceful fallback to mock mode when API keys are missing
+- Add debug logging for WebSocket connections, agent spawning, tool execution
+- Handle `connectionState` issues; may indicate relay daemon SQLite or performance problems
+
+## Common Mistakes
+
+- Using `spawn()` for persistent conversational agents
+- Forgetting channel membership before channel operations
+- Over-relying on `connectionStatus` for SSE subscriptions with persistent services
+- Creating per-component relay connections (use shared Context)