wayfind 0.0.1 → 2.0.0

package/templates/global.md

@@ -0,0 +1,79 @@
+# Global State — Index
+
+Last updated: YYYY-MM-DD
+
+## Preferences
+
+### Working style
+- [Communication tone — e.g. "direct, no filler, skip pleasantries"]
+- [Draft preference — e.g. "draft all external comms to me first; flag what to leave OUT"]
+- [Review step — e.g. "I review important comms with [name] before sending — always include that step"]
+
+### Technical preferences
+- [Tool/language defaults — e.g. "always TypeScript strict mode"]
+- [Commit style — e.g. "imperative mood, explain why not what"]
+- [Build/deploy habits — e.g. "never touch production before local repro"]
+
+### Team context
+<!--
+This section is where the real leverage lives. Record relationship dynamics so the AI
+handles people correctly without being re-briefed every session. Examples:
+
+- "Sarah (Design): prefers async feedback via Figma, not Slack. 24h heads-up for scope changes."
+- "Jordan (co-founder): peer, not a report. Keep informed; Jordan manages their own workload."
+- "Engineering team: mostly PST, decisions async in Notion."
+-->
+- [Name (role): key dynamic, communication preference, anything the AI should know]
+
+### Decision frameworks
+<!--
+Record how you actually think about recurring decision types. Examples:
+
+- "Pricing questions: always segment paid vs. free before drawing conclusions."
+- "Build vs. buy: default buy for non-core infra unless vendor creates lock-in risk."
+- "Vendor disputes: frame in writing first, negotiate specifics live."
+-->
+- [Decision type: your default approach or framework]
+
+## Active Projects
+<!-- AUTO-GENERATED by `wayfind status --write`. Do not edit manually. -->
+
+| Project | Repo | Updated | Status | Next |
+|---------|------|---------|--------|------|
+
+## Manual Projects
+<!-- Non-repo items (admin, vendor tasks, etc.). Edit freely — not auto-generated. -->
+
+| Project | Status | Next |
+|---------|--------|------|
+
+## Memory Files (load on demand)
+
+Load these from `~/.ai-memory/memory/` when the session topic matches:
+
+| File | When to load | Summary |
+|------|-------------|---------|
+| `example-topic.md` | Keywords that trigger loading | One-line summary of what's inside |
+
+## State Files (per-repo)
+
+| Location | Covers |
+|----------|--------|
+| `~/.ai-memory/state.md` | Admin work, non-repo tasks |
+| `~/repos/org/repo/.ai-memory/state.md` | What this repo is about |
+
+## Session Protocol
+
+**Start:**
+1. Read this file + the repo's `.ai-memory/state.md`
+2. Check Memory Files table — load any that match this session's topic
+3. Summarize current state, then ask: **"What's the goal for this session? What does success look like?"**
+
+**Mid-session drift check:** If work diverges from the stated goal, flag it gently and ask whether to stay the course or pivot.
+
+**End (on "stop" / "done" / "pause" / "tomorrow"):**
+1. Update the repo's `.ai-memory/state.md`
+2. Do NOT update this file's Active Projects table — it is rebuilt automatically by `wayfind status`.
+3. Create/update topic memory files for any significant new cross-repo context
+4. Append to `~/.ai-memory/memory/journal/YYYY-MM-DD.md`
+5. Confirm: **"State saved. Say 'let's continue' next time."**

package/templates/memory-file.md

@@ -0,0 +1,18 @@
+# [Topic Name]
+
+> Load this file when: [keywords that indicate this context is relevant]
+
+## Context
+[What is this? Why does it exist as a memory file?]
+
+## Current State
+[What's the situation right now?]
+
+## Key Details
+[The actual content — decisions, strategies, data, email threads, whatever makes this worth preserving]
+
+## Next Step
+[What action is pending, if any]
+
+## History
+[Brief log of how this evolved — useful for understanding why things are the way they are]

package/templates/personal-state.md

@@ -0,0 +1,14 @@
+# [Repo Name] — Personal State
+
+Last updated: YYYY-MM-DD
+
+(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 -->

package/templates/personas.json

@@ -0,0 +1,28 @@
+{
+  "personas": [
+    {
+      "id": "product",
+      "name": "Product",
+      "description": "Decides what to build, for whom, and in what order. Produces intent, priorities, and success criteria. Consumes shipping status, discoveries, and design rationale.",
+      "autopilot": true
+    },
+    {
+      "id": "design",
+      "name": "Design",
+      "description": "Decides how the product is experienced. Produces design rationale, UX trade-offs, and rejected alternatives. Consumes product intent, engineering constraints, and usage data.",
+      "autopilot": true
+    },
+    {
+      "id": "engineering",
+      "name": "Engineering",
+      "description": "Decides how to build it and implementation trade-offs. Produces decisions, discoveries, and drift signals. Consumes product context, design rationale, and strategic constraints.",
+      "autopilot": true
+    },
+    {
+      "id": "strategy",
+      "name": "Strategy",
+      "description": "Decides where next, technology bets, and team enablement. Produces research outcomes, prototypes, and direction. Consumes cross-team patterns, drift trends, and capability gaps.",
+      "autopilot": true
+    }
+  ]
+}

package/templates/product-state.md

@@ -0,0 +1,41 @@
+# [Repo/Area] — Product State
+<!-- Default template for the "Product" persona. Rename or adapt if your team
+     uses different personas (see: wayfind personas). -->
+
+Last updated: YYYY-MM-DD
+Source: [PM name, or "relayed by [name]", or "self — wearing product hat"]
+
+## What We're Building
+<!-- The feature or capability in user/customer terms.
+     Not "API endpoint returns JSON" — "users can export their data as CSV from settings."
+     If this repo covers multiple features, list the active ones. -->
+
+## Why This, Why Now
+<!-- Customer problem, strategic rationale, or business driver.
+     What evidence supports this priority? (customer conversations, data, strategic bet)
+     Link to source material if it exists (Notion doc, research, Slack thread). -->
+
+## Success Criteria
+<!-- Observable outcomes in user or business terms. Not implementation milestones.
+     "Support team resolves X-type tickets without engineering help" not "function deployed."
+     Include how we'll measure it if possible. -->
+
+## Scope & Constraints
+<!-- What's in. What's explicitly out. Product decisions that constrain implementation.
+     Include the "why" — engineers will push back on constraints they don't understand.
+     Example: "No batch mode in v1 — we need to validate the single-record UX first." -->
+
+## Open Questions
+<!-- Unresolved product decisions. Engineering may add to this list during sessions
+     when they discover things that need PM input.
+     Format: Question — Who should answer — Urgency (blocking / soon / backlog) -->
+
+## Customer Signal
+<!-- What users are saying about this area. Bugs, requests, complaints, praise.
+     Include source and date so the signal can be traced back.
+     Example: "2026-02-15 — Intercom #4521 — 'We need to export by date range, not just all'" -->
+
+## Decisions Log
+<!-- Product decisions that have been made, with date and rationale. Prevents re-litigating.
+     Format: YYYY-MM-DD — Decision — Rationale
+     Example: "2026-02-10 — CSV only, no Excel — 80% of users import into Google Sheets anyway" -->

package/templates/prompts-readme.md

@@ -0,0 +1,19 @@
+# Team Prompts
+
+Shared, version-controlled prompts for common workflows. Anyone on the team can add or improve these.
+
+## How to use
+
+Copy-paste from here into your AI assistant, or reference by name when asking the Wayfind bot:
+> @wayfind show me the code-review prompt
+
+## How to contribute
+
+1. Create a new `.md` file in this directory
+2. Use a clear, descriptive filename (e.g. `code-review.md`, `bug-triage.md`)
+3. Start with a brief description of when to use this prompt
+4. Commit and push — the team will see it immediately
+
+## Available Prompts
+
+<!-- This list is auto-maintained by the file listing below -->

package/templates/repo-state.md

@@ -0,0 +1,18 @@
+# [Repo Name] — Project State
+
+Last updated: YYYY-MM-DD
+
+## Current Branch
+main
+
+## Current Status
+[What's the current state of play? What has been done recently? Be specific enough that a fresh session can orient immediately.]
+
+## What's Next
+[Concrete next action. Not a list of options — the one thing to pick up from.]
+
+## Blockers
+[Anything waiting on someone else, a decision, or an external dependency.]
+
+## Gotchas
+[Repo-specific things the AI should know: quirks, non-obvious patterns, traps to avoid, decisions that were made and why.]

package/templates/session-protocol-fragment.md

@@ -0,0 +1,46 @@
+# Session State Protocol
+## (Add this to your AI tool's system prompt or project instructions file)
+
+---
+
+## Session State Protocol
+
+**Memory directory:** `~/.ai-memory/` (global) and `.ai-memory/` (per-repo)
+
+**At session start (REQUIRED):**
+1. Read `~/.ai-memory/global.md` — preferences, active projects table, memory file manifest
+2. Read `.ai-memory/state.md` in the current repo — branch, progress, next steps, gotchas
+3. If persona state files exist (e.g. `.ai-memory/product-state.md`, `.ai-memory/strategy-state.md`), read them — these capture intent, success criteria, and constraints from your configured personas. Keep them in mind during the session.
+4. Check the "Memory Files" table in global.md — load any files from `~/.ai-memory/memory/` whose keywords match this session's topic
+5. Summarize the current state of the project, then ask: **"What's the goal for this session? What does success look like?"**
+
+**Mid-session:**
+If the session appears to be diverging from the stated goal (new tangent, scope creep), gently flag it:
+> *"Quick check — we set out to [goal]. This feels like it's moving toward [tangent]. Want to stay the course, or deliberately pivot?"*
+If the user pivots, update the goal. This is a nudge, not a gate — the user always decides.
+
+**At session end (when user says "stop", "done", "pause", "tomorrow", "wrap up"):**
+1. Update `.ai-memory/state.md` in the current repo: what was done, what's next, blockers, gotchas
+2. Do NOT update `~/.ai-memory/global.md` Active Projects table — it is rebuilt automatically by `wayfind status`.
+3. If significant new cross-repo context was created (patterns, strategies, decisions), create or update a file in `~/.ai-memory/memory/` and add it to the Memory Files manifest
+4. Append to `~/.ai-memory/memory/journal/YYYY-MM-DD.md`:
+
+```
+## [Repo or context] — [Brief title]
+**Why:** [The stated goal]
+**What:** [Bullet list of what was done]
+**Outcome:** [Did we hit the goal? Key deliverables]
+**On track?:** [Focused or drift? What caused drift?]
+**Lessons:** [Worth remembering cross-session]
+**Discovery:** [Optional — things learned that challenge assumptions, create new options,
+  or need PM/CTO attention. Skip if nothing notable. Include who should see this and why.]
+```
+
+5. If the session surfaced items that belong in a persona state file (e.g. open questions for the product owner, strategic discoveries for the CTO), add them to the relevant persona state file.
+6. Confirm: **"State saved. Say 'let's continue' next time."**
+
+**Rules:**
+- Use the Edit tool to update files in place — don't append new sections
+- Keep `global.md` under 80 lines. Detail goes in topic files.
+- Per-repo state stays focused on that repo. Cross-repo context goes in `~/.ai-memory/memory/`
+- Do NOT use proprietary memory CLI tools for state storage. Plain markdown files only.

package/templates/slack-app-manifest.json

@@ -0,0 +1,27 @@
+{
+  "display_information": {
+    "name": "Wayfind",
+    "description": "Team context layer — persona digests from engineering journals and signal channels.",
+    "background_color": "#1a1a2e"
+  },
+  "features": {
+    "bot_user": {
+      "display_name": "Wayfind",
+      "always_online": false
+    }
+  },
+  "oauth_config": {
+    "scopes": {
+      "bot": [
+        "channels:history",
+        "groups:history",
+        "incoming-webhook"
+      ]
+    }
+  },
+  "settings": {
+    "org_deploy_enabled": false,
+    "socket_mode_enabled": false,
+    "is_hosted": false
+  }
+}

package/templates/statusline.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Wayfind status line for Claude Code
+# Shows Wayfind-specific data: decision quality from last session.
+# Installed by: wayfind init / wayfind update
+
+input=$(cat)
+
+STATS_FILE="$HOME/.claude/team-context/session-stats.json"
+
+if [ -f "$STATS_FILE" ] && command -v jq &>/dev/null; then
+  DECISIONS=$(jq -r '.decisions // 0' "$STATS_FILE" 2>/dev/null)
+  RICH=$(jq -r '.rich // 0' "$STATS_FILE" 2>/dev/null)
+  THIN=$(jq -r '.thin // 0' "$STATS_FILE" 2>/dev/null)
+  DATE=$(jq -r '.session_date // ""' "$STATS_FILE" 2>/dev/null)
+  if [ "$DECISIONS" -gt 0 ] 2>/dev/null; then
+    echo "Wayfind | last: ${DECISIONS} decisions (${RICH} rich, ${THIN} thin) ${DATE}"
+  else
+    echo "Wayfind"
+  fi
+else
+  echo "Wayfind"
+fi

package/templates/strategy-state.md

@@ -0,0 +1,39 @@
+# Strategy State
+<!-- Default template for the "Strategy" persona. Rename or adapt if your team
+     uses different personas (see: wayfind personas). -->
+
+Last updated: YYYY-MM-DD
+
+## Current Direction
+<!-- What's the strategic thesis right now? What are we betting on and why?
+     This is the "north star" that product and engineering decisions should align to. -->
+
+## Active Research
+<!-- What's being investigated. Include the hypothesis being tested.
+     Format: Topic — Hypothesis — Status — Repo (if applicable)
+     Example: "AI extraction accuracy — Can we hit 95% on room rates? — Testing — ~/repos/research" -->
+
+## Prototype Outcomes
+<!-- What's been built, what it proved or disproved, and what to do with it.
+     This is the CTO → PM/Engineering handoff point. Be explicit about what
+     the prototype means for the product and who needs to act on it. -->
+
+| Prototype | Repo | What it proves | Status | Handoff |
+|---|---|---|---|---|
+<!-- Example row:
+| Extraction pipeline | ~/repos/research | AI extracts room rates at 95% accuracy | Complete | April: spec the support-facing UI; Nick: production-grade the pipeline |
+-->
+
+## Technology Bets
+<!-- What we're betting on, the thesis behind each bet, and what would make us reconsider.
+     Example: "Azure Container Apps for batch jobs — cheaper than Functions at scale,
+     but if cold start > 30s we'll revisit." -->
+
+## Constraints & Guardrails
+<!-- Strategic decisions that constrain product and engineering. The "we will not" list.
+     Example: "No vendor lock-in on data storage — customer must be able to export everything." -->
+
+## Patterns I'm Watching
+<!-- Cross-team observations, market signals, recurring issues. Things that aren't
+     urgent but shape where we're heading.
+     Example: "Third repo this quarter where the data model assumed 1:1 but reality is 1:many." -->

package/templates/team-state.md

@@ -0,0 +1,55 @@
+# [Repo Name] — Team State
+
+Last updated: YYYY-MM-DD
+
+## Product Context
+<!-- What is this repo building, for whom, and why? One paragraph.
+     If a product-state.md exists, summarize it here and point to it for detail.
+     Engineers: read this before starting a session. It's why your work matters. -->
+
+## 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" -->
+
+## Signal Routing
+<!-- Where do external signals for this repo come from, and where should
+     discoveries go? This helps the AI route information correctly.
+     Adapt the entries below to match your configured personas
+     (see: wayfind personas).
+
+     Bugs & feedback: [tool — e.g. Intercom, GitHub Issues]
+     Persona contacts: [name — who to flag questions to for each persona]
+     QA process: [how testing works for this repo] -->
+
+## Elicitation Prompts
+
+<!-- These prompts guide the AI to capture richer context at decision moments.
+     The AI should ask AT MOST ONE of these when a significant decision is stated
+     without reasoning. Do not ask during routine implementation — only at moments
+     where a choice was made between alternatives.
+
+     The answers aren't for you (you already know) — they're for your teammates
+     who will read the digest tomorrow. -->
+
+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.
+
+Elicitation intensity: normal
+<!-- Options: low (only ask when reasoning is completely absent), normal (default),
+     high (ask on every non-trivial decision even if some reasoning is present).
+     Team admins can adjust this to improve overall decision context quality. -->
+
+## Shared Gotchas
+<!-- Hard-won lessons. What surprised us. What NOT to do. -->

package/uninstall.sh

@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+# Wayfind — Uninstaller
+# Removes installed hooks, commands, and settings fragments.
+# NEVER deletes your memory content (global-state.md, memory/ directory).
+#
+# Usage: bash uninstall.sh [--tool claude-code]
+
+set -euo pipefail
+
+TOOL="${1:-}"
+[[ "${1:-}" == "--tool" ]] && TOOL="${2:-}"
+[[ "${1:-}" == "--tool="* ]] && TOOL="${1#--tool=}"
+
+GREEN='\033[0;32m'; YELLOW='\033[1;33m'; RED='\033[0;31m'; RESET='\033[0m'
+log()  { echo -e "${GREEN}✓${RESET} $1"; }
+warn() { echo -e "${YELLOW}⚠${RESET}  $1"; }
+info() { echo "  $1"; }
+err()  { echo -e "${RED}✗${RESET} $1"; exit 1; }
+
+echo ""
+echo "Wayfind — Uninstall"
+echo ""
+warn "This will remove hooks, commands, and settings fragments."
+warn "Your memory files (global-state.md, memory/) will NOT be deleted."
+echo ""
+read -rp "Continue? [y/N] " confirm
+[[ "$confirm" =~ ^[Yy]$ ]] || { echo "Aborted."; exit 0; }
+
+# Remove hook
+HOOK="$HOME/.claude/hooks/check-global-state.sh"
+if [ -f "$HOOK" ]; then
+    rm "$HOOK"
+    log "Removed $HOOK"
+fi
+
+# Remove commands
+CMD="$HOME/.claude/commands/init-memory.md"
+if [ -f "$CMD" ]; then
+    rm "$CMD"
+    log "Removed $CMD"
+fi
+
+DOCTOR_CMD="$HOME/.claude/commands/doctor.md"
+if [ -f "$DOCTOR_CMD" ]; then
+    rm "$DOCTOR_CMD"
+    log "Removed $DOCTOR_CMD"
+fi
+
+# Remove hook from settings.json
+SETTINGS="$HOME/.claude/settings.json"
+if [ -f "$SETTINGS" ] && grep -q "check-global-state" "$SETTINGS" 2>/dev/null; then
+    python3 - "$SETTINGS" <<'PYEOF'
+import json, sys
+path = sys.argv[1]
+with open(path) as f:
+    settings = json.load(f)
+hooks = settings.get("hooks", {})
+for event in ("SessionStart", "Stop"):
+    groups = hooks.get(event, [])
+    if not isinstance(groups, list):
+        continue
+    cleaned = []
+    for group in groups:
+        if not isinstance(group, dict):
+            continue
+        # Correct format: {matcher, hooks: [...]}
+        if "hooks" in group and isinstance(group["hooks"], list):
+            group["hooks"] = [h for h in group["hooks"]
+                              if not ("check-global-state" in h.get("command", "")
+                                      or "session-end" in h.get("command", ""))]
+            if group["hooks"]:
+                cleaned.append(group)
+        # Legacy flat format: {type, command}
+        elif "type" in group:
+            cmd = group.get("command", "")
+            if "check-global-state" not in cmd and "session-end" not in cmd:
+                cleaned.append(group)
+    if cleaned:
+        hooks[event] = cleaned
+    elif event in hooks:
+        del hooks[event]
+if not hooks:
+    del settings["hooks"]
+with open(path, "w") as f:
+    json.dump(settings, f, indent=2)
+    f.write("\n")
+PYEOF
+    log "Removed hook from $SETTINGS"
+fi
+
+# Remove installed kit copy
+KIT_DEST="$HOME/.claude/team-context"
+if [ -d "$KIT_DEST" ]; then
+    rm -rf "$KIT_DEST"
+    log "Removed $KIT_DEST"
+fi
+
+echo ""
+log "Uninstall complete."
+echo ""
+info "Your memory files are preserved:"
+info "  ~/.claude/global-state.md"
+info "  ~/.claude/memory/"
+info ""
+info "To reinstall: curl -fsSL https://raw.githubusercontent.com/leizerowicz/meridian/main/install.sh | bash"

package/README.md

@@ -1,4 +0,0 @@
-# wayfind
-Team context layer for AI-assisted engineering.
-
-Coming soon. https://usewayfind.ai