From 399b03824c9970a7072f9632945282ff85ada1a0 Mon Sep 17 00:00:00 2001
From: Clawd <ai@clawd.bot>
Date: Fri, 27 Feb 2026 21:51:02 -0800
Subject: Address review comments: clarify decisions, add context indicator

---
 PLAN.md     | 10 ++++-----
 plan.md     | 73 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 research.md |  4 +++-
 3 files changed, 80 insertions(+), 7 deletions(-)

diff --git a/PLAN.md b/PLAN.md
index 4495134..de6e333 100644
--- a/PLAN.md
+++ b/PLAN.md
@@ -239,15 +239,15 @@ If you encounter issues not covered by the plan, stop and ask.
 
 ---
 
-## Open Questions
+## Decisions Made
 
-1. **Claude Code SDK vs CLI**: Need to verify SDK capabilities. Fallback to spawning CLI if needed.
+1. **Claude Agent SDK**: Using the SDK (`@anthropic-ai/claude-agent-sdk`) — provides hooks, session management, and streaming.
 
-2. **Artifact storage**: Store in SQLite (current plan) or as actual files in project directory?
+2. **Artifact storage**: Files in `.claude-flow/` directory (research.md, plan.md). Editable in any editor, visible in git.
 
-3. **Session context**: How much conversation history to include? Compaction strategy?
+3. **Session context**: SDK auto-compacts when context fills. UI will show token usage so users can see context size.
 
-4. **Multi-file editing**: How to handle plans that span many files? Tree view of changes?
+4. **Code review**: Out of scope — this tool enforces the *generation* workflow. Review stays in git.
 
 ---
 
diff --git a/plan.md b/plan.md
index ff71487..cf6ea0b 100644
--- a/plan.md
+++ b/plan.md
@@ -40,6 +40,7 @@ claude-flow/
 │       │   ├── Message.tsx           # Single message bubble
 │       │   ├── ArtifactPane.tsx      # Markdown editor for plan/research
 │       │   ├── PhaseBar.tsx          # Phase indicator + controls
+│       │   ├── ContextIndicator.tsx  # Token usage / context size display
 │       │   └── Settings.tsx          # API key, preferences
 │       ├── hooks/
 │       │   ├── useProjects.ts
@@ -1036,7 +1037,76 @@ export function PhaseBar({ session, onPhaseChange, onPermissionModeChange }: Pha
 }
 ```
 
-### 4.6 Chat (`renderer/src/components/Chat.tsx`)
+### 4.6 ContextIndicator (`renderer/src/components/ContextIndicator.tsx`)
+
+```typescript
+import React from "react";
+
+interface ContextIndicatorProps {
+  inputTokens: number;
+  outputTokens: number;
+  cacheHits?: number;
+}
+
+export function ContextIndicator({ inputTokens, outputTokens, cacheHits }: ContextIndicatorProps) {
+  const totalTokens = inputTokens + outputTokens;
+  const maxTokens = 200000; // Claude's context window
+  const usagePercent = Math.min((totalTokens / maxTokens) * 100, 100);
+
+  const getColor = () => {
+    if (usagePercent > 80) return "#ef4444"; // red
+    if (usagePercent > 50) return "#f59e0b"; // amber
+    return "#10b981"; // green
+  };
+
+  return (
+    <div className="context-indicator">
+      <div className="context-bar">
+        <div
+          className="context-fill"
+          style={{ width: `${usagePercent}%`, backgroundColor: getColor() }}
+        />
+      </div>
+      <span className="context-label">
+        {(totalTokens / 1000).toFixed(1)}k / 200k tokens
+        {cacheHits ? ` (${(cacheHits / 1000).toFixed(1)}k cached)` : ""}
+      </span>
+    </div>
+  );
+}
+```
+
+Add styles to `globals.css`:
+
+```css
+/* Context Indicator */
+.context-indicator {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 0 16px;
+}
+
+.context-bar {
+  width: 100px;
+  height: 6px;
+  background: #333;
+  border-radius: 3px;
+  overflow: hidden;
+}
+
+.context-fill {
+  height: 100%;
+  transition: width 0.3s ease;
+}
+
+.context-label {
+  font-size: 12px;
+  color: #888;
+}
+```
+
+### 4.7 Chat (`renderer/src/components/Chat.tsx`)
 
 ```typescript
 import React, { useState, useEffect, useRef } from "react";
@@ -1475,6 +1545,7 @@ function ensureArtifactDir(projectPath: string) {
 - [ ] Implement `renderer/src/App.tsx`
 - [ ] Implement `renderer/src/components/Sidebar.tsx`
 - [ ] Implement `renderer/src/components/PhaseBar.tsx`
+- [ ] Implement `renderer/src/components/ContextIndicator.tsx`
 - [ ] Implement `renderer/src/components/Chat.tsx`
 - [ ] Update `renderer/src/main.tsx`
 
diff --git a/research.md b/research.md
index 0496f29..b7d0897 100644
--- a/research.md
+++ b/research.md
@@ -111,7 +111,7 @@ for await (const message of query({
 
 **Critical for our workflow:**
 - **Research/Plan/Annotate phases**: Use `plan` mode or restrict `allowedTools` to read-only
-- **Implement phase**: Use `acceptEdits` or `bypassPermissions`
+- **Implement phase**: Use `acceptEdits` or `bypassPermissions` // REVIEW: make a user toggle
 
 ### System Prompts
 
@@ -307,6 +307,7 @@ const enforcePhaseHook: HookCallback = async (input, toolUseID, { signal }) => {
 - Con: More complex, may lose SDK internal state
 
 **Recommendation:** Use **Option A** (SDK persistence) with session ID in SQLite. We can still store messages for display/search, but rely on SDK for actual context.
+// REVIEW: option a
 
 ### Artifact Management
 
@@ -318,6 +319,7 @@ The blog workflow uses `research.md` and `plan.md` as persistent artifacts.
 3. **Both** — Files as source of truth, sync to SQLite for search
 
 **Recommendation:** Store as **files in the project directory** (e.g., `.claude-flow/research.md`, `.claude-flow/plan.md`). This matches the blog workflow where the human edits the plan.md directly.
+// REVIEW: recommendation is great
 
 ### IPC Architecture
 
-- 
cgit v1.2.3