From 5dea83ba44be1933400f35c325d5b2c5fc6b6379 Mon Sep 17 00:00:00 2001 From: Clawd Date: Fri, 27 Feb 2026 22:08:46 -0800 Subject: Remove duplicate PLAN.md, keep plan.md as canonical --- PLAN.md | 258 ------------------------------------------------------ package-lock.json | 4 +- 2 files changed, 2 insertions(+), 260 deletions(-) delete mode 100644 PLAN.md diff --git a/PLAN.md b/PLAN.md deleted file mode 100644 index de6e333..0000000 --- a/PLAN.md +++ /dev/null @@ -1,258 +0,0 @@ -# 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 diff --git a/package-lock.json b/package-lock.json index 087a4e1..74bac1f 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,11 +1,11 @@ { - "name": "minimal-electron-bsql", + "name": "minimal-electron-vite-react-better-sqlite", "version": "1.0.0", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "minimal-electron-bsql", + "name": "minimal-electron-vite-react-better-sqlite", "version": "1.0.0", "hasInstallScript": true, "dependencies": { -- cgit v1.2.3