Add project plan for Claude Flow

1 files changed, 258 insertions, 0 deletions

diff --git a/PLAN.md b/PLAN.md
new file mode 100644
index 0000000..4495134
--- /dev/null
+++ b/PLAN.md
@@ -0,0 +1,258 @@
+# Claude Flow
+
+An opinionated coding assistant that enforces a structured workflow: research → plan → annotate → implement.
+
+Built on Electron + React + SQLite, driving Claude Code under the hood.
+
+## Core Principle
+
+**Never let Claude write code until you've reviewed and approved a written plan.**
+
+The separation of planning and execution prevents wasted effort, keeps you in control of architecture decisions, and produces better results than jumping straight to code.
+
+## Workflow Phases
+
+```
+┌──────────┐    ┌──────┐    ┌──────────┐    ┌───────────┐
+│ Research │ ─► │ Plan │ ─► │ Annotate │ ─► │ Implement │
+└──────────┘    └──────┘    └──────────┘    └───────────┘
+                                 │                 │
+                                 └────── ◄ ────────┘
+                               (iterate as needed)
+```
+
+### 1. Research
+- Deep read of relevant codebase sections
+- Output: `research.md` with detailed findings
+- System prompt enforces: "Read deeply, write findings, don't make changes"
+
+### 2. Plan
+- Detailed implementation approach with code snippets
+- Output: `plan.md` with approach, file paths, trade-offs
+- System prompt enforces: "Write detailed plan, don't implement yet"
+
+### 3. Annotate
+- Human adds inline notes directly in `plan.md`
+- Claude addresses notes and updates the document
+- Repeat 1-6 times until plan is approved
+- System prompt enforces: "Address notes, update plan, don't implement yet"
+
+### 4. Implement
+- Execute the approved plan
+- Mark tasks complete as work progresses
+- Run typecheck continuously
+- Terse feedback corrections during this phase
+
+---
+
+## Architecture
+
+### Tech Stack
+- **Electron** - Desktop app with filesystem access
+- **React** - Renderer UI
+- **better-sqlite3** - Local persistence
+- **Vite** - Fast dev builds
+- **Claude Code SDK** - AI engine (`@anthropic-ai/claude-code`)
+
+### SQLite Schema
+
+```sql
+-- Projects (a codebase you're working on)
+CREATE TABLE projects (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  path TEXT NOT NULL,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+-- Sessions (a task/feature within a project)
+CREATE TABLE sessions (
+  id TEXT PRIMARY KEY,
+  project_id TEXT NOT NULL REFERENCES projects(id),
+  name TEXT NOT NULL,
+  phase TEXT NOT NULL DEFAULT 'research',
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+
+-- Messages (conversation history per session)
+CREATE TABLE messages (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  role TEXT NOT NULL,
+  content TEXT NOT NULL,
+  created_at INTEGER NOT NULL
+);
+
+-- Artifacts (research.md, plan.md per session)
+CREATE TABLE artifacts (
+  id TEXT PRIMARY KEY,
+  session_id TEXT NOT NULL REFERENCES sessions(id),
+  type TEXT NOT NULL,
+  content TEXT NOT NULL,
+  version INTEGER NOT NULL DEFAULT 1,
+  created_at INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
+);
+```
+
+### Directory Structure
+
+```
+src/main/
+├── index.ts              # App lifecycle, window management
+├── preload.ts            # IPC bridge to renderer
+├── db/
+│   ├── index.ts          # Database connection
+│   ├── schema.ts         # Migrations
+│   ├── projects.ts       # Project CRUD
+│   └── sessions.ts       # Session CRUD
+├── claude/
+│   ├── index.ts          # Claude Code SDK wrapper
+│   └── phases.ts         # Phase-specific system prompts
+└── ipc/
+    └── handlers.ts       # IPC handler registration
+
+renderer/src/
+├── main.tsx
+├── App.tsx
+├── components/
+│   ├── Sidebar.tsx       # Projects + sessions list
+│   ├── Chat.tsx          # Message thread
+│   ├── ArtifactPane.tsx  # research.md / plan.md editor
+│   └── PhaseIndicator.tsx
+├── hooks/
+│   └── useSession.ts
+└── lib/
+    └── ipc.ts            # Typed IPC calls
+```
+
+### UI Layout
+
+```
+┌─────────────┬────────────────────────────────────┐
+│  Projects   │  [Research] [Plan] [Annotate] [Go] │
+│  └─ Proj A  ├────────────────────────────────────┤
+│    ├─ Sess1 │  ┌─────────────┬─────────────────┐ │
+│    └─ Sess2 │  │   Chat      │   Artifact      │ │
+│  └─ Proj B  │  │   pane      │   pane          │ │
+│    └─ ...   │  │             │   (plan.md)     │ │
+│             │  └─────────────┴─────────────────┘ │
+└─────────────┴────────────────────────────────────┘
+```
+
+---
+
+## Phase System Prompts
+
+### Research Phase
+```
+You are in RESEARCH mode. Your job is to deeply understand the relevant parts of the codebase.
+
+Rules:
+- Read files thoroughly, not superficially
+- Write all findings to research.md
+- DO NOT make any code changes
+- DO NOT create or modify any files except research.md
+
+When finished, summarize what you learned and wait for the next instruction.
+```
+
+### Plan Phase
+```
+You are in PLANNING mode. Your job is to write a detailed implementation plan.
+
+Rules:
+- Write the plan to plan.md
+- Include specific code snippets showing proposed changes
+- Include file paths that will be modified
+- Include trade-offs and considerations
+- DO NOT implement anything
+- DO NOT modify any source files
+
+The plan should be detailed enough that implementation becomes mechanical.
+```
+
+### Annotate Phase
+```
+You are in ANNOTATION mode. The human has added notes to plan.md.
+
+Rules:
+- Read all inline notes (marked with comments or annotations)
+- Address each note by updating the relevant section
+- DO NOT implement anything
+- DO NOT modify any source files
+- Only update plan.md
+
+When finished, summarize the changes you made to the plan.
+```
+
+### Implement Phase
+```
+You are in IMPLEMENTATION mode. The plan has been approved.
+
+Rules:
+- Follow the plan exactly
+- Mark tasks complete in plan.md as you finish them
+- Run typecheck continuously
+- Do not add unnecessary comments or jsdocs
+- Do not use `any` or `unknown` types
+- Do not stop until all tasks are complete
+
+If you encounter issues not covered by the plan, stop and ask.
+```
+
+---
+
+## Implementation Phases
+
+### Phase 1: Foundation
+- [ ] Set up directory structure
+- [ ] Implement SQLite schema and migrations
+- [ ] Create database CRUD operations
+- [ ] Set up IPC handlers skeleton
+
+### Phase 2: Core UI
+- [ ] Sidebar with project/session tree
+- [ ] Phase indicator and controls
+- [ ] Basic chat pane (messages display)
+- [ ] Artifact pane (markdown editor)
+
+### Phase 3: Claude Integration
+- [ ] Integrate Claude Code SDK
+- [ ] Implement phase-specific system prompts
+- [ ] Wire up chat to Claude
+- [ ] Handle streaming responses
+
+### Phase 4: Workflow Logic
+- [ ] Phase transitions with guards
+- [ ] Artifact versioning
+- [ ] "Don't implement yet" enforcement
+- [ ] Progress tracking during implementation
+
+### Phase 5: Polish
+- [ ] Keyboard shortcuts
+- [ ] Session search/filter
+- [ ] Export sessions
+- [ ] Settings (API key, preferences)
+
+---
+
+## Open Questions
+
+1. **Claude Code SDK vs CLI**: Need to verify SDK capabilities. Fallback to spawning CLI if needed.
+
+2. **Artifact storage**: Store in SQLite (current plan) or as actual files in project directory?
+
+3. **Session context**: How much conversation history to include? Compaction strategy?
+
+4. **Multi-file editing**: How to handle plans that span many files? Tree view of changes?
+
+---
+
+## References
+
+- [How I Use Claude Code](https://boristane.com/blog/how-i-use-claude-code/) - The workflow this is based on
+- [Claude Code SDK](https://www.npmjs.com/package/@anthropic-ai/claude-code) - NPM package
+- [Electron + better-sqlite3 template](https://github.com/ethanmick/minimal-electron-vite-react-better-sqlite) - Starting point