wayfind 0.0.1 → 2.0.0

package/specializations/claude-code/CLAUDE.md-global-fragment.md

@@ -0,0 +1,53 @@
+
+## Session State Protocol (Wayfind)
+
+**Memory system:** Hierarchical plain-markdown files. No CLI tools, no databases.
+
+### File Hierarchy
+
+```
+~/.claude/
+  global-state.md          # Thin index — ALWAYS load at session start
+  state.md                 # Admin/non-repo work
+  memory/                  # Topic files — load on demand
+    <topic>.md
+    journal/YYYY-MM-DD.md  # Daily log
+
+<repo>/.claude/
+  team-state.md            # Shared team context — committed to git
+  personal-state.md        # Personal context — gitignored
+```
+
+### Session Start (REQUIRED)
+
+1. Read `~/.claude/global-state.md`
+2. Read `.claude/team-state.md` (shared team context) and `.claude/personal-state.md` (your personal context) in the current repo, if they exist. Fall back to `.claude/state.md` for older repos not yet migrated. (Or `~/.claude/state.md` if in home dir.)
+3. Check the Memory Files table in global-state.md — load any `~/.claude/memory/` files whose keywords match this session's topic
+4. Summarize current state, then ask: **"What's the goal for this session? What does success look like?"**
+
+### Mid-Session
+
+If work drifts from the stated goal, flag it: *"Quick check — we set out to [goal]. This feels like [tangent]. Stay the course or pivot?"*
+
+### Session End (on "stop" / "done" / "pause" / "tomorrow")
+
+1. Update `.claude/team-state.md` with shared changes and `.claude/personal-state.md` with personal changes. (For older repos not yet migrated, update `.claude/state.md` as before.)
+2. Do NOT update `~/.claude/global-state.md` — its Active Projects table is rebuilt automatically by `wayfind status`.
+3. Create/update topic files in `~/.claude/memory/` for significant new cross-repo context
+4. Append to `~/.claude/memory/journal/YYYY-MM-DD.md`:
+   ```
+   ## [Repo] — [Title]
+   **Why:** [Stated goal]
+   **What:** [What was done]
+   **Outcome:** [Did we hit it?]
+   **On track?:** [Focused or drift?]
+   **Lessons:** [Cross-session learnings]
+   ```
+5. Confirm: **"State saved. Say 'let's continue' next time."**
+
+### Rules
+
+- Keep `global-state.md` under 80 lines. Detail goes in `~/.claude/memory/` files.
+- Per-repo `state.md` stays focused on that repo only.
+- New cross-repo topics get new files in `~/.claude/memory/`, not appended to global-state.md.
+- Do NOT use external memory databases or CLI tools for state storage. Use plain markdown files only.

package/specializations/claude-code/CLAUDE.md-repo-fragment.md

@@ -0,0 +1,16 @@
+
+## Session State Protocol
+
+**At session start (REQUIRED):**
+1. Read `~/.claude/global-state.md` — preferences, active projects, memory file manifest
+2. Read `.claude/team-state.md` in this repo — shared team context (architecture decisions, conventions, sprint focus, gotchas)
+3. Read `.claude/personal-state.md` in this repo — your personal context (current focus, working notes, opinions)
+4. Check the Memory Files table in global-state.md — load any `~/.claude/memory/` files relevant to this session's topic
+
+**At session end (when user says stop/done/pause/tomorrow):**
+1. Update `.claude/team-state.md` with shared context: architecture decisions, conventions, gotchas the whole team should know
+2. Update `.claude/personal-state.md` with personal context: your next steps, working notes, opinions
+3. Do NOT update `~/.claude/global-state.md` — its Active Projects table is rebuilt automatically by `wayfind status`.
+4. If significant new cross-repo context was created (patterns, strategies, decisions), create or update a file in `~/.claude/memory/` and add it to the Memory Files manifest in global-state.md
+
+**Do NOT use external memory databases or CLI tools for state storage.** Use plain markdown files only.

package/specializations/claude-code/README.md

@@ -0,0 +1,99 @@
+# Claude Code Specialization
+
+This directory contains everything needed to wire Wayfind into Claude Code specifically.
+
+## What's Different About Claude Code
+
+Claude Code reads a `CLAUDE.md` file at the root of every repo (and `~/.claude/CLAUDE.md` globally) as persistent instructions. It also supports:
+- **Hooks** — shell scripts that run on session start/end, file edits, commands
+- **Custom slash commands** — markdown files in `.claude/commands/` become `/command-name` shortcuts
+- **Settings** — `~/.claude/settings.json` controls hooks and behavior
+
+The memory directory for Claude Code is `~/.claude/` (not `~/.ai-memory/`).
+
+## File Map
+
+| File | Install to | Purpose |
+|------|-----------|---------|
+| `CLAUDE.md-global-fragment.md` | Append to `~/.claude/CLAUDE.md` | Tells Claude to load memory files at session start |
+| `CLAUDE.md-repo-fragment.md` | Append to `<repo>/CLAUDE.md` | Repo-level session protocol |
+| `settings.json` | Merge into `~/.claude/settings.json` | Registers the anti-drift hook |
+| `hooks/check-global-state.sh` | Copy to `~/.claude/hooks/` | Warns when global index is stale |
+| `commands/init-memory.md` | Copy to `~/.claude/commands/` | Adds `/init-memory` slash command |
+| `commands/init-team.md` | Copy to `~/.claude/commands/` | Adds `/init-team` slash command |
+| `commands/journal.md` | Copy to `~/.claude/commands/` | Adds `/journal` slash command |
+| `commands/doctor.md` | Copy to `~/.claude/commands/` | Adds `/doctor` slash command |
+
+The `setup.sh` at the kit root handles all of this automatically.
+
+## Manual Install
+
+```bash
+# 1. Create directories
+mkdir -p ~/.claude/hooks ~/.claude/commands ~/.claude/memory/journal
+
+# 2. Copy the global CLAUDE.md fragment
+cat specializations/claude-code/CLAUDE.md-global-fragment.md >> ~/.claude/CLAUDE.md
+
+# 3. Install hook script
+cp specializations/claude-code/hooks/check-global-state.sh ~/.claude/hooks/
+chmod +x ~/.claude/hooks/check-global-state.sh
+
+# 4. Install init-memory command
+cp specializations/claude-code/commands/init-memory.md ~/.claude/commands/
+
+# 5. Merge settings.json
+# If ~/.claude/settings.json doesn't exist:
+cp specializations/claude-code/settings.json ~/.claude/settings.json
+# If it already exists, manually add the "hooks" block from settings.json
+
+# 6. Copy global state template
+cp ../../templates/global.md ~/.claude/global-state.md
+# Edit it to add your preferences and projects
+```
+
+## Per-Repo Setup
+
+For each repo you work in:
+
+```bash
+cd ~/repos/your-org/your-repo
+mkdir -p .claude
+
+# Copy repo state templates
+cp ~/.claude/team-context/templates/repo-state.md .claude/team-state.md    # Shared team context (committed)
+cp ~/.claude/team-context/templates/repo-state.md .claude/personal-state.md # Personal context (gitignored)
+
+# Add session protocol to repo CLAUDE.md
+cat ~/.claude/team-context/specializations/claude-code/CLAUDE.md-repo-fragment.md >> CLAUDE.md
+
+# Add gitignore entries (IMPORTANT — see note below)
+echo ".claude/personal-state.md" >> .gitignore
+echo ".claude/settings.local.json" >> .gitignore
+echo ".claude/memory.db" >> .gitignore
+```
+
+Or just run `/init-memory` inside Claude Code after setup.
+
+## Gitignore Warning
+
+**Never add `.claude/` to `.gitignore` as a whole directory.**
+
+Claude Code stores skills, commands, and settings in `.claude/` that should be tracked in git. If you ignore the whole directory, git won't track those files — and negation rules like `!.claude/commands/` won't rescue them (git doesn't descend into ignored directories).
+
+**Correct pattern:**
+```gitignore
+# Claude Code — local only, don't track
+.claude/personal-state.md
+.claude/settings.local.json
+.claude/memory.db
+```
+
+**Wrong:**
+```gitignore
+.claude/          ← this breaks skills and commands
+```
+
+## Memory Directory Note
+
+Claude Code uses `~/.claude/` as its home. This kit uses that same directory rather than `~/.ai-memory/` so that Claude's native file loading works correctly. The file paths in your `global-state.md` will reference `~/.claude/memory/` accordingly.

package/specializations/claude-code/commands/doctor.md

@@ -0,0 +1,31 @@
+---
+description: Run Wayfind health check — validates hooks, state files, backup status, and memory file sizes.
+---
+
+# Wayfind — Doctor
+
+Run a health check on the memory system.
+
+## Step 1: Check if doctor.sh is available
+
+Look for `~/.claude/team-context/doctor.sh`. If found, run it:
+```bash
+bash ~/.claude/team-context/doctor.sh
+```
+
+If not found, perform the checks manually:
+
+## Step 2: Manual checks
+
+1. **Hook registered?** — Does `~/.claude/settings.json` contain "check-global-state"?
+2. **Global state current?** — Read `~/.claude/global-state.md`. When was it last updated?
+3. **Backup status** — Check `~/.claude/.backup-last-push` and `~/.claude/.backup-last-error`
+4. **Repos** — Scan `~/repos`, `~/code`, `~/dev` for `.claude/state.md` files
+5. **Memory files** — List files in `~/.claude/memory/`, flag any over 8KB
+
+## Step 3: Report findings
+
+Report in this format:
+- ✓ items that are working correctly
+- ⚠ items that need attention (not broken, but worth knowing)
+- ✗ items that are broken (with how to fix)

package/specializations/claude-code/commands/init-memory.md

@@ -0,0 +1,154 @@
+---
+description: Initialize Wayfind for the current repo. Creates .claude/team-state.md (tracked in git) and .claude/personal-state.md (gitignored), ensures correct .gitignore entries, appends session protocol to CLAUDE.md, and registers the repo in the global index. Safe to run multiple times (idempotent).
+---
+
+# Initialize Memory System for Current Repo
+
+Run these steps in order. Skip any step that's already done (this command is idempotent).
+
+## Step 0: Detect and Migrate Old Protocol
+
+Read the repo's `CLAUDE.md` (if it exists). If it contains "Update the project's row in" or "Update the Active Projects row", this repo has the old session protocol that writes to global-state.md.
+
+**Migration:** Replace the matching Session End step with:
+> 3. Do NOT update `~/.claude/global-state.md` — its Active Projects table is rebuilt automatically by `wayfind status`.
+
+Report: "Migrated session protocol — sessions no longer write to global-state.md."
+
+If the old protocol is not detected, skip this step silently.
+
+## Step 1: Detect Context
+
+- Determine the current working directory
+- Check if it's a git repo (`ls .git` or `git rev-parse --show-toplevel`)
+- Read `~/.claude/global-state.md` to check if this repo is already registered
+
+## Step 2: Create state files (if missing)
+
+This repo uses TWO state files with different visibility:
+
+**`.claude/team-state.md`** — committed to git (shared team context)
+
+If `.claude/team-state.md` does not exist, create it:
+
+```markdown
+# [Repo Name] — Team State
+
+Last updated: [today's date]
+
+## Architecture & Key Decisions
+<!-- Decisions the whole team should know. Include the "why" not just the "what". -->
+
+## Conventions
+<!-- Patterns, naming, tooling choices that apply across the team. -->
+
+## Current Sprint Focus
+<!-- Team-level "what are we working on right now" -->
+
+## Elicitation Prompts
+
+<!-- These prompts guide the AI to capture richer context at decision moments.
+     The answers aren't for you — they're for your teammates who read the digest. -->
+
+When a technical or product decision is made without stated reasoning, ask one of:
+- "What alternatives did you consider?"
+- "What constraint or requirement drove this choice?"
+- "What would need to change for you to reverse this decision?"
+- "Who else on the team does this affect, and how?"
+- "What's the risk if this assumption is wrong?"
+
+Do not ask if the decision already includes reasoning, tradeoffs, or constraints.
+Do not ask more than once per decision. Do not ask during routine implementation.
+
+## Shared Gotchas
+<!-- Hard-won lessons. What surprised us. What NOT to do. -->
+```
+
+**`.claude/personal-state.md`** — gitignored (your personal context)
+
+If `.claude/personal-state.md` does not exist, create it:
+
+```markdown
+# [Repo Name] — Personal State
+
+Last updated: [today's date]
+
+(This file is gitignored. It's yours — context you wouldn't want teammates reading as objective fact.)
+
+## My Current Focus
+<!-- Your personal next steps -->
+
+## Personal Context
+<!-- Working notes, opinions, relationship dynamics for this repo -->
+
+## What I'm Watching
+<!-- Open questions, things to follow up on -->
+```
+
+## Step 3: Fix `.gitignore`
+
+Check `.gitignore`. Ensure these lines are present:
+
+```
+.claude/personal-state.md
+.claude/state.md
+.claude/settings.local.json
+.claude/memory.db
+.claude/wayfind.json
+```
+
+**Do NOT add `.claude/` as a whole directory.** That breaks skills and commands. Only add the specific files above. Note that `team-state.md` is intentionally NOT gitignored — it is meant to be committed and shared with your team. The `.claude/state.md` entry covers legacy repos that use a single state file instead of the two-file model.
+
+If any of those lines are missing, append them. If `.claude/` (as a directory) is already in `.gitignore`, remove it and replace with the four file-level entries above.
+
+## Step 4: Append Session Protocol to CLAUDE.md
+
+Read the repo's `CLAUDE.md`. If it does NOT already contain "Session State Protocol", append this:
+
+```markdown
+
+## Session State Protocol
+
+**At session start (REQUIRED):**
+1. Read `~/.claude/global-state.md` — preferences, active projects, memory file manifest
+2. Read `.claude/team-state.md` in this repo — shared team context: architecture decisions, conventions, sprint focus, gotchas
+3. Read `.claude/personal-state.md` in this repo — your personal context: current focus, working notes, opinions
+4. Check the Memory Files table in global-state.md — load any `~/.claude/memory/` files relevant to this session's topic
+
+**At session end (when user says stop/done/pause/tomorrow):**
+1. Update `.claude/team-state.md` with shared context: architecture decisions, conventions, gotchas the team should know
+2. Update `.claude/personal-state.md` with personal context: your next steps, working notes, opinions
+3. Do NOT update `~/.claude/global-state.md` — its Active Projects table is rebuilt automatically by `wayfind status`.
+4. If significant new cross-repo context was created (patterns, strategies, decisions), create or update a file in `~/.claude/memory/` and add it to the Memory Files manifest in global-state.md
+
+**Do NOT use ruvector/claude-flow memory CLI for state storage.** Use plain markdown files only.
+```
+
+If `CLAUDE.md` doesn't exist, create a minimal one with the repo name as a heading and the block above.
+
+## Step 5: Register State Files in Global Index
+
+Read `~/.claude/global-state.md`. The Active Projects table is auto-generated by `wayfind status --write` — do NOT add rows to it manually.
+
+Add the repo's state files to the State Files table if missing:
+
+```
+| `[full path]/.claude/team-state.md` | Shared team context for this repo |
+| `[full path]/.claude/personal-state.md` | Personal context for this repo (gitignored) |
+```
+
+## Step 6: Report
+
+Tell the user:
+- `.claude/team-state.md` — created or already existed (committed to git, shared with team)
+- `.claude/personal-state.md` — created or already existed (gitignored, personal only)
+- `.gitignore` — updated or already correct
+- `CLAUDE.md` — protocol appended or already present
+- `global-state.md` — repo registered or already listed
+
+**If they haven't set up team context yet**, mention:
+"Run `/init-team` to set up team-level context sharing — shared journals, weekly digests
+(Slack + Notion), and persona state files for your configured personas."
+
+**Mention persona configuration:**
+"Run `wayfind personas` to see and customize your team's personas (defaults: Product, Design, Engineering, Strategy)."