jfl 0.8.1 → 0.9.1

package/template/CLAUDE.md

@@ -19,79 +19,51 @@ Don't make users fill out forms before they can build. Let them start immediatel
 
 ---
 
-## CRITICAL: Session Sync (MUST READ)
+## Session Startup
 
-**Context loss is unacceptable.** Before starting ANY work, verify repos are synced.
+**Two runtimes, two paths.** JFL works in both Pi (with the JFL extension) and Claude Code (without it). The startup behavior depends on which runtime you're in.
 
-### At Session Start - ALWAYS Do (BEFORE RESPONDING TO USER):
+### Path A: Pi with JFL Extension (you receive a `jfl-session-init` message)
 
-**Complete ALL steps before saying anything to the user.**
+**The extension already handled everything.** When you see a message with `customType: "jfl-session-init"`, it means:
+- Session sync, doctor check, and Context Hub are done
+- Auto-commit daemon is running
+- Full project context (journals, knowledge docs, code headers) is injected into your system prompt
+- The user already saw a boot animation while all this loaded
+
+**DO NOT run any startup commands:**
+- ❌ `./scripts/session/session-sync.sh`
+- ❌ `./scripts/session/jfl-doctor.sh`
+- ❌ `jfl_context` or `context_get`
+- ❌ `cat .jfl/journal/*.jsonl`
+- ❌ `/hud`
+
+**Just greet the user naturally (3-5 lines):**
+- What was worked on recently (from context already in your system prompt)
+- Current phase and any blockers
+- A suggested next action
+
+No tool calls. No setup noise. Just talk.
+
+### Path B: Claude Code / No Extension (you do NOT receive a `jfl-session-init` message)
+
+**You need to initialize manually.** Complete these steps before responding:
 
 **1. Run session sync:**
 ```bash
 ./scripts/session/session-sync.sh
 ```
 
-**2. Run doctor check (ONLY for existing projects):**
-
-**IMPORTANT: Skip doctor for fresh projects.** Detect fresh project:
+**2. Run doctor check:**
 ```bash
-# Fresh project indicators:
-# - No git commits yet: git rev-list --count HEAD returns 0 or error
-# - Empty knowledge docs: VISION.md has template text
-# - No journal entries: .jfl/journal/ is empty
-
-# Check if fresh
-COMMIT_COUNT=$(git rev-list --count HEAD 2>/dev/null || echo "0")
-if [[ "$COMMIT_COUNT" -gt "5" ]]; then
-    # Existing project - run doctor
-    ./scripts/session/jfl-doctor.sh
-    # Ask user before continuing
-    # If warnings: "Doctor found issues: [list]. Want me to fix these?"
-    # If clean: "Doctor check passed. Ready to continue?"
-    # STOP AND WAIT for user response
-    # If approved: ./scripts/session/jfl-doctor.sh --fix
-else
-    # Fresh project - skip doctor
-    echo "Fresh project detected, skipping doctor check."
-fi
+./scripts/session/jfl-doctor.sh
 ```
 
-**For existing projects:** After running doctor, you MUST ask the user before continuing.
-**For fresh projects:** Skip directly to step 3.
-
-**3. Get unified context via MCP (REQUIRED):**
+**3. Get unified context:**
 ```
 Call: mcp__jfl-context__context_get
 ```
-
-This single call returns:
-- Recent journal entries (what happened across sessions)
-- Knowledge docs (vision, roadmap, narrative, thesis)
-- Code file headers (@purpose tags)
-
-**CRITICAL: Filter cross-project context pollution.**
-
-Context Hub may return results from OTHER projects on the machine. ALWAYS verify context matches the current project:
-
-1. Check the project path in journal entries
-2. If journal paths don't match current directory, IGNORE them
-3. If knowledge docs look like templates, this is a FRESH project
-4. For fresh projects: Skip context_get entirely, start foundation questions
-
-**Example of cross-project pollution (IGNORE THIS):**
-```
-Journal from: /Users/alectaggart/gatcha-toilet/.jfl/journal/...
-Current project: /Users/alectaggart/case
-→ THESE DON'T MATCH. Ignore the journal entry.
-```
-
-**For fresh projects (no commits, empty docs):**
-- Skip context_get
-- Skip doctor check
-- Go straight to foundation questions (VISION, ROADMAP, etc.)
-
-**DO NOT read individual markdown files.** The context MCP tool aggregates everything. This is why we built Context Hub.
+This returns recent journal entries, knowledge docs, and code headers.
 
 **4. Show recent journal entries:**
 ```bash
@@ -103,105 +75,75 @@ cat .jfl/journal/*.jsonl 2>/dev/null | tail -10
 Invoke: /hud skill
 ```
 
-This displays the full status, pipeline, tasks, and guides next action.
-
 **ONLY AFTER completing all 5 steps**, respond to the user with the HUD output.
 
-If you need to search for something specific later:
-```
-Call: mcp__jfl-context__context_search with query="your search"
-```
+### How to Tell Which Path You're On
 
-## Session Management
+- **Got a `jfl-session-init` message?** → Path A (extension handled it, just greet)
+- **No such message?** → Path B (manual startup required)
 
-JFL automatically manages session isolation. You don't need to worry about worktrees or CD commands - it's handled for you.
+### Automatic Tool Invocation (DURING the session, not at startup)
 
-### How It Works
+**When the user asks questions, AUTOMATICALLY use the right tool:**
 
-- **Single session**: You work directly on your branch (simple, fast)
-- **Multiple sessions**: JFL creates isolated worktrees automatically (prevents conflicts)
-- **Auto-commit**: Work is saved every 2 minutes (prevents data loss)
-- **Auto-merge**: When you finish, work merges to your working branch automatically
+| User Question | Auto-Invoke | Don't Ask |
+|---------------|-------------|-----------|
+| "What did we decide about X?" | `memory_search: X` | Just do it |
+| "When did we implement Y?" | `memory_search: Y` | Just do it |
+| "Why did we choose Z?" | `memory_search: Z decision` | Just do it |
+| "Search for pricing" | `memory_search: pricing` | Just do it |
+| "Show me database features" | `memory_search: database + type=feature` | Just do it |
+| "What files have X?" | `context_search: X` | Just do it |
+| "Find code about Y" | `context_search: Y` | Just do it |
 
-### Session Branch
+**The user should NEVER have to type tool names.** You detect the intent and invoke automatically.
 
-Sessions branch from your working branch (default: `main`, configurable in `.jfl/config.json`):
+**Tool Selection Logic:**
 
-```json
-{
-  "working_branch": "develop"
-}
 ```
+if question contains ("decide", "decided", "choice", "why we"):
+    → memory_search with type="decision"
 
-Session branches are named: `session-<user>-<date>-<time>-<random>`
+if question contains ("when did we", "implemented", "built", "added"):
+    → memory_search with type="feature"
 
-### Ending a Session
-
-When user says "done", "that's it", or "/end":
-- Run the `/end` skill to clean up properly
-- This commits, merges, and pushes your work
+if question contains ("bug", "fix", "error"):
+    → memory_search with type="fix"
 
-If session crashes, uncommitted work is auto-saved via background auto-commit.
+if question contains ("learn", "insight", "discovery"):
+    → memory_search (check learned field)
 
----
+if question about "files" or "code":
+    → context_search
 
-This syncs:
-- jfl-gtm (this repo)
-- jfl-platform (product symlink target)
-- All submodules
+if question about "current" or "now":
+    → context_get
 
-### Why This Matters
+if question about "status" or "dashboard":
+    → /hud
 
-The `product/` directory is a **symlink** to `../jfl-platform`. If jfl-platform gets out of sync with GitHub:
-- Files appear "deleted" when they exist on GitHub
-- Work done in previous sessions is invisible
-- User loses trust in the system
-
-**This has happened multiple times. Do not skip the sync.**
-
-### Verify Context is Intact
-
-```bash
-./scripts/session/test-context-preservation.sh
+else:
+    → memory_search (general - hybrid search finds relevant)
 ```
 
-This checks:
-- Critical knowledge files exist (VISION.md, BRAND_DECISIONS.md, etc.)
-- Product specs exist (PLATFORM_SPEC.md, TEMPLATE_SPEC.md, CONTEXT_GRAPH_SPEC.md)
-- Git repos are in sync with remotes
-- No uncommitted changes in knowledge/
-
-**If tests fail, do not proceed until fixed.**
-
-### Auto-Push on Session End
-
-Hooks in `.claude/settings.json` automatically:
-- Commit changes on Stop/PreCompact
-- Push to origin
-
-### Continuous Auto-Commit (RECOMMENDED)
+## Session Management
 
-**Problem:** Stop/PreCompact hooks only run if session ends cleanly. If session crashes, terminal closes, or you switch away → files can be lost.
+JFL automatically manages session isolation. You don't need to worry about worktrees or CD commands — it's handled for you.
 
-**Solution:** Run continuous auto-commit in background:
+### How It Works
 
-```bash
-# In a separate terminal, run:
-./scripts/session/auto-commit.sh start
+- **Single session**: You work directly on your branch (simple, fast)
+- **Multiple sessions**: JFL creates isolated worktrees automatically (prevents conflicts)
+- **Auto-commit**: Work is saved every 2 minutes (prevents data loss)
+- **Auto-merge**: When you finish, work merges to your working branch automatically
 
-# Or with custom interval (default 120s):
-./scripts/session/auto-commit.sh start 60
-```
+### Ending a Session
 
-This commits every 2 minutes to:
-- knowledge/
-- previews/
-- content/
-- suggestions/
-- CLAUDE.md
-- .jfl/
+When user says "done", "that's it", or "/end":
+- Run the `/end` skill to clean up properly
+- This commits, merges, and pushes your work
 
-**Start this at every session.** It's the only way to guarantee no work is lost.
+If session crashes, uncommitted work is auto-saved via background auto-commit.
 
 ---