path: root/PLAN.md

# 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)

---

## Decisions Made

1. **Claude Agent SDK**: Using the SDK (`@anthropic-ai/claude-agent-sdk`) — provides hooks, session management, and streaming.

2. **Artifact storage**: Files in `.claude-flow/` directory (research.md, plan.md). Editable in any editor, visible in git.

3. **Session context**: SDK auto-compacts when context fills. UI will show token usage so users can see context size.

4. **Code review**: Out of scope — this tool enforces the *generation* workflow. Review stays in git.

---

## 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