From e179e4e17d8d8bf6fa8c01a7b8a2bf60380008a5 Mon Sep 17 00:00:00 2001 From: Clawd Date: Fri, 27 Feb 2026 21:36:13 -0800 Subject: Add project plan for Claude Flow --- PLAN.md | 258 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 258 insertions(+) create mode 100644 PLAN.md (limited to 'PLAN.md') 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 -- cgit v1.2.3