From 1b0c2a4ab40c0c8a99d50a9d628811c3b2286584 Mon Sep 17 00:00:00 2001 From: lbruton Date: Tue, 27 Oct 2026 17:30:55 -0500 Subject: [PATCH] chore(DEVS-145): deploy SessionFlow-memory library; memory block skills-deploy of library ce6718e: wrap, start, discover, spec, spec-discovery and the code-core rule read and write SessionFlow memory instead of mem0. project.json carries a memory block in place of the mem0 block, with the same values. --- .agents/rules/code-core.md | 74 ++++++------ .agents/rules/prose-core.md | 2 +- .agents/skills/codacy-analysis-cli/SKILL.md | 2 +- .agents/skills/codacy-cloud-cli/SKILL.md | 2 +- .agents/skills/codacy-code-review/SKILL.md | 2 +- .agents/skills/code-review/SKILL.md | 2 +- .agents/skills/context-drift/SKILL.md | 2 +- .agents/skills/discernment-nudge/SKILL.md | 2 +- .agents/skills/discover/SKILL.md | 40 +++---- .agents/skills/issue/SKILL.md | 2 +- .agents/skills/pr-cleanup/SKILL.md | 2 +- .agents/skills/pr-resolve/SKILL.md | 2 +- .agents/skills/receiving-code-review/SKILL.md | 2 +- .agents/skills/release/SKILL.md | 2 +- .../skills/requesting-code-review/SKILL.md | 2 +- .../skills/setup-foundation-context/SKILL.md | 2 +- .agents/skills/spec-approach/SKILL.md | 2 +- .agents/skills/spec-discovery/SKILL.md | 6 +- .agents/skills/spec-reconcile/SKILL.md | 2 +- .agents/skills/spec-requirements/SKILL.md | 2 +- .agents/skills/spec-review/SKILL.md | 2 +- .agents/skills/spec-tasks/SKILL.md | 2 +- .agents/skills/spec/SKILL.md | 6 +- .agents/skills/spec/references/Guide.md | 12 +- .agents/skills/spec/references/spec.md | 2 +- .../templates/discovery-template.md | 4 +- .../references/templates/tasks-template.md | 4 +- .agents/skills/start/SKILL.md | 53 ++++----- .agents/skills/vault-update/SKILL.md | 2 +- .../verification-before-completion/SKILL.md | 2 +- .agents/skills/wrap/SKILL.md | 107 ++++++++++------- .claude/agents/firecrawl-scraper.md | 2 +- .claude/agents/pr-discover.md | 2 +- .claude/agents/pr-thread-resolver.md | 2 +- .claude/hooks/block-pr-merge.py | 2 +- .claude/hooks/docvault-lint.py | 2 +- .claude/hooks/vale-staged.py | 2 +- .claude/hooks/worktree-safety.py | 2 +- .claude/rules/code-core.md | 74 ++++++------ .claude/rules/prose-core.md | 2 +- .claude/skills/.library-manifest | 2 +- .claude/skills/codacy-analysis-cli/SKILL.md | 2 +- .claude/skills/codacy-cloud-cli/SKILL.md | 2 +- .claude/skills/codacy-code-review/SKILL.md | 2 +- .claude/skills/context-drift/SKILL.md | 2 +- .claude/skills/discernment-nudge/SKILL.md | 2 +- .claude/skills/discover/SKILL.md | 46 ++++---- .claude/skills/issue/SKILL.md | 2 +- .claude/skills/pr-cleanup/SKILL.md | 2 +- .claude/skills/pr-resolve/SKILL.md | 2 +- .claude/skills/receiving-code-review/SKILL.md | 2 +- .claude/skills/release/SKILL.md | 2 +- .../skills/requesting-code-review/SKILL.md | 2 +- .../skills/setup-foundation-context/SKILL.md | 2 +- .claude/skills/spec-approach/SKILL.md | 2 +- .claude/skills/spec-discovery/SKILL.md | 6 +- .claude/skills/spec-reconcile/SKILL.md | 2 +- .claude/skills/spec-requirements/SKILL.md | 2 +- .claude/skills/spec-review/SKILL.md | 2 +- .claude/skills/spec-tasks/SKILL.md | 2 +- .claude/skills/spec/SKILL.md | 6 +- .claude/skills/spec/references/Guide.md | 12 +- .claude/skills/spec/references/spec.md | 2 +- .../templates/discovery-template.md | 4 +- .../references/templates/tasks-template.md | 4 +- .claude/skills/start/SKILL.md | 53 ++++----- .claude/skills/vault-update/SKILL.md | 2 +- .../verification-before-completion/SKILL.md | 2 +- .claude/skills/wrap/SKILL.md | 109 ++++++++++-------- .codex/agents/firecrawl-scraper.toml | 2 +- .codex/agents/pr-discover.toml | 2 +- .codex/agents/pr-thread-resolver.toml | 2 +- .vale/styles/Prose/README.md | 2 +- 73 files changed, 367 insertions(+), 363 deletions(-) diff --git a/.agents/rules/code-core.md b/.agents/rules/code-core.md index 0ae7279..71b5d0d 100644 --- a/.agents/rules/code-core.md +++ b/.agents/rules/code-core.md @@ -1,7 +1,7 @@ --- name: code-core description: Workflow rules shared by every code repo - DocVault, glossary, Plane, Infisical, debugging, memory, code search, editing, tests, spec gates, push rules, red flags, GitHub hygiene -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Code-core rules @@ -35,7 +35,8 @@ development practices, procedures and runbooks, specs and approvals, research an - **Public repos:** before writing to `/DocVault/`, check nothing sensitive is going in. Sensitive material goes to the private companion instead. - If a page looks stale, flag it; do not silently act on suspected bad data. -- On conflicts between DocVault and mem0, the newest information wins. Ask when it is unclear. +- On conflicts between DocVault and SessionFlow memory, the newest information wins. Ask when it is + unclear. ## Domain glossary @@ -96,10 +97,10 @@ needs no secrets. Never hard-code an Infisical project ID anywhere else; read it - Shell: always quote paths; many contain spaces (iCloud, Cowork, vault paths). - When comparing file counts against an index, use `git ls-files | wc -l`, not a raw filesystem count. Raw counts include `.venv` and `node_modules`. -- A transient MCP, Plane or mem0 failure (empty payload, temporary error, unexpected empty result for a - known object): wait about 60 seconds and retry once. If it still fails, continue with local-safe steps. - An HTTP 429 or "quota exceeded" from mem0 is not transient: do not retry, continue without mem0 reads and - tell the user. +- A transient MCP, Plane or SessionFlow failure (empty payload, temporary error, unexpected empty result + for a known object): wait about 60 seconds and retry once. If it still fails, continue with local-safe + steps. A `memory_unavailable` error means the memory store has not started: say so and continue without + memory reads; `/health` names the reason. ## Memory: coexisting layers @@ -108,49 +109,41 @@ failure mode. Each has a distinct job: | Layer | Scope | Role | |---|---|---| -| **mem0** (hosted MCP connector; the tool prefix is account-specific) | cross-session and cross-harness | **The bigger picture**: one `/wrap` session summary per session (what, when, files, issues, decisions), plus explicit decisions and handoffs | +| **SessionFlow memory** (`mcp__sessionflow__` memory tools, Postgres-backed) | cross-session and cross-harness | **The bigger picture**: one `/wrap` session summary per session (what, when, files, issues, decisions), plus explicit decisions and handoffs | | **local Codex memory** (`~/.codex/memories/`) | Codex only | **Day-to-day operating memory**: preferences, corrections, gotchas | | **`.context/`** (in-repo) | per-project, all harnesses | **Long-term foundations** needed for implementation work: architecture, conventions, standards | -| **sessionflow** (`mcp__sessionflow__*`) | all harnesses, all projects | Transcript search over verbatim past turns; the session-start recall tier | +| **SessionFlow transcripts** (`mcp__sessionflow__search_all_sessions` and friends) | all harnesses, all projects | Transcript search over verbatim past turns; the session-start recall tier | | **Plane** (`mcp__plane__*`) | per-project issues | Issue and planning state, not a memory store | -mem0 + sessionflow + git history together give the full picture of past work. Lessons ("when X, do Y") go -to local memory, not mem0. Durable foundations go to `.context/`. +SessionFlow memory, transcript search and git history together give the full picture of past work. +Lessons ("when X, do Y") go to local memory, not SessionFlow memory. Durable foundations go to `.context/`. -**Recall at session start (two sources):** +**Recall at session start:** the SessionFlow session-start hook already prints the three newest session +summaries and recent turns for the project, with session provenance. Go further only when the task needs it: -1. **sessionflow**: verbatim past turns, semantic search: +```javascript +mcp__sessionflow__list_memories({ project: "", type: "session-summary", limit: 10 }) +mcp__sessionflow__search_memories({ query: " handoff", project: "", n: 10 }) +mcp__sessionflow__search_all_sessions({ query: " ", n: 5 }) +``` - ```javascript - mcp__sessionflow__search_all_sessions({ query: "last session work decisions ", n: 5 }) - ``` - -2. **mem0**: session summaries, decisions, handoffs. The tool prefix is not fixed. - Resolve the hosted mem0 `search_memories` tool from the current tool catalog. - - ```javascript - search_memories({ query: "last session work decisions for ", limit: 10, - filters: { AND: [{ user_id: "lbruton" }, { metadata: { project: "" } }] }, - enable_graph: false }) - ``` - -**mem0 standard (DEVS-92)**: three keys on every record. +**Memory standard**: every record carries these keys. | Key | Value | Source | |---|---|---| -| `user_id` | `lbruton`, always | `project.json` → `mem0.userId` | -| `agent_id` | the harness writing: `codex` here (other harnesses write `claude-code`, `claude-cowork`, `codex`, `gemini`, `opencode` or `antigravity`) | the harness itself; never `project.json`, never a project name | -| `metadata.project` | lowercase project slug (`staktrakr`, `devops`) | `project.json` → `mem0.project`, else the lowercase `tag` | - -- **Writes:** set all three plus `metadata.type` ∈ `session-summary` / `decision` / `handoff`. Routine - writes come from `/wrap` only (one paragraph `session-summary`). Use a direct `add_memory` call - (`type: decision` or `handoff`) only for an explicit decision or handoff that must be shared before the - session ends. Never write a mem0 entry per task: commits, PRs and Plane comments record each task. -- **Reads:** filter `user_id` + `metadata.project` server-side (the match is case-sensitive). Never filter - on `agent_id`: every harness must see the others' handoffs. Run TWO searches: one project-scoped, one - user-only cross-project workflow query. -- **Quota:** the plan allows 1,000 retrieval calls per month, shared by every harness. Never page through - the store in bulk; estimate call counts before any audit. +| `user_id` | `lbruton` (the default; omit it) | `project.json` → `memory.userId` | +| `agent_id` | the harness writing: `codex` here (one of `claude-code`, `codex`, `gemini`, `opencode`, `antigravity`) | the harness itself; never `project.json`, never a project name | +| `project` | lowercase project slug (`staktrakr`, `devops`) | `project.json` → `memory.project`, else the lowercase `tag` | +| `type` | `session-summary`, `decision`, `handoff`, `fact`, `workflow`, `discovery`, `contact`, `blocker`, `preference`, `open-item`, `milestone` or `guardrail` | the kind of note | + +- **Writes:** routine writes come from `/wrap` only (one `session-summary` per session). Call + `mcp__sessionflow__add_memory` directly (`type: decision` or `handoff`) only for an explicit decision or + handoff that must be shared before the session ends. Never write a memory per task: commits, PRs and Plane + comments record each task. +- **Reads:** every memory call passes `project`; pass `"*"` for a cross-project query. Never filter on + `agent_id`: every harness must see the others' handoffs. Pass `format: "json"` when you parse the result. +- **Replace, do not duplicate:** a later `mcp__sessionflow__add_memory` with the same `topic_key` replaces that record. To + retire older notes, pass their IDs in `supersedes`. ## Code search order (cheapest first) @@ -167,8 +160,7 @@ re-add or call them. | Server | Use for | |---|---| -| `mem0` (hosted connector) | Cross-session memory, sole backend | -| `sessionflow` | Session history search: semantic retrieval over past conversation turns | +| `sessionflow` | Session history search over past turns, and the cross-session memory store: `mcp__sessionflow__add_memory`, `mcp__sessionflow__search_memories`, `mcp__sessionflow__list_memories`, `mcp__sessionflow__get_memory`, `mcp__sessionflow__update_memory`, `mcp__sessionflow__delete_memory`, `mcp__sessionflow__get_memory_context` | | `context7` | Library documentation lookup | | `chrome-devtools` | Browser-page inspection and debugging | | `infisical` | Secret inventory; fallback only, use the `infisical-agent` CLI first | diff --git a/.agents/rules/prose-core.md b/.agents/rules/prose-core.md index e672c70..a99bea2 100644 --- a/.agents/rules/prose-core.md +++ b/.agents/rules/prose-core.md @@ -1,5 +1,5 @@ --- -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Prose-core rules diff --git a/.agents/skills/codacy-analysis-cli/SKILL.md b/.agents/skills/codacy-analysis-cli/SKILL.md index d2005dd..9213c38 100644 --- a/.agents/skills/codacy-analysis-cli/SKILL.md +++ b/.agents/skills/codacy-analysis-cli/SKILL.md @@ -5,7 +5,7 @@ license: MIT metadata: author: Codacy version: 1.5.0 -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Codacy Analysis CLI diff --git a/.agents/skills/codacy-cloud-cli/SKILL.md b/.agents/skills/codacy-cloud-cli/SKILL.md index c0465ee..1e05ae5 100644 --- a/.agents/skills/codacy-cloud-cli/SKILL.md +++ b/.agents/skills/codacy-cloud-cli/SKILL.md @@ -5,7 +5,7 @@ license: MIT metadata: author: Codacy version: 1.6.1 -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Codacy Cloud CLI diff --git a/.agents/skills/codacy-code-review/SKILL.md b/.agents/skills/codacy-code-review/SKILL.md index c167de1..2c5e2d7 100644 --- a/.agents/skills/codacy-code-review/SKILL.md +++ b/.agents/skills/codacy-code-review/SKILL.md @@ -5,7 +5,7 @@ license: MIT metadata: author: Codacy version: 1.5.0 -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Codacy Code Review diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.md index 197cd89..843239c 100644 --- a/.agents/skills/code-review/SKILL.md +++ b/.agents/skills/code-review/SKILL.md @@ -3,7 +3,7 @@ name: code-review description: "Run CodeRabbit CLI reviews, retrieve saved local or GitHub PR fix prompts, and interpret CodeRabbit authentication and review output. Use for CodeRabbit review commands, committed/uncommitted or directory scopes, and CodeRabbit runbooks. Default code-review skill: also trigger for explicit code/PR/quality/security review requests or when a review is needed." metadata: version: "0.1.0" -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # CodeRabbit Code Review diff --git a/.agents/skills/context-drift/SKILL.md b/.agents/skills/context-drift/SKILL.md index ae29aa0..0a548e3 100644 --- a/.agents/skills/context-drift/SKILL.md +++ b/.agents/skills/context-drift/SKILL.md @@ -11,7 +11,7 @@ description: >- `/vault-drift` for projects migrated to `.context/` (DEVS-37). Triggers: "context drift", "vault drift", "drift audit", "drift check", "context-drift", "audit .context", "check context docs", "foundation drift", "verify foundation", "what should be in .context". -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Context Drift diff --git a/.agents/skills/discernment-nudge/SKILL.md b/.agents/skills/discernment-nudge/SKILL.md index 2cb401c..078ca8c 100644 --- a/.agents/skills/discernment-nudge/SKILL.md +++ b/.agents/skills/discernment-nudge/SKILL.md @@ -17,7 +17,7 @@ description: > to double-check, cite, or review — the skill file explains these boundaries and the exact output format. license: Complete terms in LICENSE.txt -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Discernment nudge diff --git a/.agents/skills/discover/SKILL.md b/.agents/skills/discover/SKILL.md index d9dd070..b69f8bb 100644 --- a/.agents/skills/discover/SKILL.md +++ b/.agents/skills/discover/SKILL.md @@ -8,7 +8,7 @@ description: > Triggers on "/discover", "/brainstorm", "research this issue", "explore this before we spec it". user-invocable: true -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Discover — Phase 1 Structured Brainstorm @@ -65,9 +65,9 @@ Glob `{specs-root}/{ISSUE-ID}-*/` (ignore `archive/`), where `{specs-root}` is ` ## Research fan-out (Steps 1–3) — run as a read-only Workflow -Steps 1–3 are pure read work across independent angles — the canonical use for the `Workflow` orchestration tool. When the research surface is broad (multiple subsystems, prior art *and* external docs *and* mem0 history), dispatch the sweep as a **`Workflow` fan-out**: one parallel agent per angle — +Steps 1–3 are pure read work across independent angles — the canonical use for the `Workflow` orchestration tool. When the research surface is broad (multiple subsystems, prior art *and* external docs *and* memory history), dispatch the sweep as a **`Workflow` fan-out**: one parallel agent per angle — -1. **Prior context** — mem0 + sessionflow + the project and shared vaults (Grep). +1. **Prior context** — SessionFlow memory and transcripts + the project and shared vaults (Grep). 2. **Codebase impact** — Grep/Glob structural, plus the `Explore` subagent for broad sweeps. 3. **External** — context7 + Brave (only if libraries/APIs/platform features are involved). @@ -77,16 +77,15 @@ Each agent returns structured findings; **you** synthesize them into the Discove Run these in parallel. **Record every query string used** — they go into the issue's Discovery block at Step 6 as Context Pointers so future sessions can re-hydrate deterministically. -### mem0 search -> mem0's live tool prefix is connection-specific (`mcp____*`), not the fixed -> `mcp__mem0__`. `search_memories` and `add_memory` below name capabilities; resolve the live -> tool from your catalog before calling it. +### SessionFlow memory search ``` -search_memories +mcp__sessionflow__search_memories query: "{issue title} {key terms from description}" - limit: 10 - filters: {AND: [{user_id: "lbruton"}, {metadata: {project: ""}}]} + project: "" + n: 10 + format: "json" ``` +Pass `project: "*"` as a second query when the topic spans projects. ### Vault search Search both the project vault and the shared vault. Grep for the key terms and their synonyms, then @@ -107,7 +106,7 @@ mcp__sessionflow__search_all_sessions Present any relevant past decisions, related work, or prior discussions. -**Track for Step 6:** the exact query strings and patterns used (mem0, sessionflow, vault Grep) and any Research Brief / KB / Foundation page hits — these become the Context Pointers list. +**Track for Step 6:** the exact query strings and patterns used (memory, transcripts, vault Grep) and any Research Brief / KB / Foundation page hits — these become the Context Pointers list. --- @@ -245,8 +244,8 @@ Keep it concise — summary + pointers, not transcripts. A quick-fix-only consum - [Non-blocking question] — carry forward to spec ### Context Pointers -- **mem0:** `search: ""` — [what it surfaces] -- **mem0:** `search: ""` — [what it surfaces] +- **Memory:** `mcp__sessionflow__search_memories` query `""` — [what it surfaces] +- **Memory:** `mcp__sessionflow__search_memories` query `""` — [what it surfaces] - **Research Brief:** [[Research/{topic}]] (if one exists or was created) - **KB:** [[KnowledgeBase/{page}]] — [why relevant] - **Foundation:** [[Foundation/{doc}]] — [why relevant] @@ -288,20 +287,19 @@ Show the user the brief you just wrote, so they see what landed in the issue wit ## Step 7: Hand Off -### Save discovery summary to mem0 (semantic retrieval) +### Save discovery summary to SessionFlow memory (semantic retrieval) -The issue is now authoritative — mem0 is the semantic-retrieval mirror. Keep the memory **short** since the full detail lives in the issue. +The issue is now authoritative — the memory is its searchable mirror. Keep it **short** since the full detail lives in the issue. The topic key makes a re-run of `/discover` replace the earlier decision instead of adding a second one. ``` -add_memory( +mcp__sessionflow__add_memory( text: "Discovery complete for {ISSUE-ID} — {one-sentence recommended approach}. Full brief in Plane issue. Scope: {size}.", - user_id: "lbruton", agent_id: "codex", - metadata: { - "type": "decision", + project: "", + type: "decision", + topic_key: "discover:{ISSUE-ID}", + extra: { "source": "discover", - "project": "", - "issue": "{ISSUE-ID}", "issue_url": "https://plane.lbruton.cc/lbruton/browse/{ISSUE-ID}/", "issue_uuid": "{plane issue uuid}", "category": "architecture" diff --git a/.agents/skills/issue/SKILL.md b/.agents/skills/issue/SKILL.md index 257a253..8359e17 100644 --- a/.agents/skills/issue/SKILL.md +++ b/.agents/skills/issue/SKILL.md @@ -6,7 +6,7 @@ description: > Triggers on: "create issue", "issue", "new issue", "new bug", "file a bug", "track this". user-invocable: false -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Issue Management diff --git a/.agents/skills/pr-cleanup/SKILL.md b/.agents/skills/pr-cleanup/SKILL.md index 67d6cc0..807a932 100644 --- a/.agents/skills/pr-cleanup/SKILL.md +++ b/.agents/skills/pr-cleanup/SKILL.md @@ -5,7 +5,7 @@ description: > local branches and their worktrees, pulls main fast-forward, and reports the result. Run after a PR is merged, before /wrap. Triggers: "pr-cleanup", "clean up branches", "prune worktrees", "clean after merge". -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # PR Cleanup diff --git a/.agents/skills/pr-resolve/SKILL.md b/.agents/skills/pr-resolve/SKILL.md index 9b5ce57..ba13476 100644 --- a/.agents/skills/pr-resolve/SKILL.md +++ b/.agents/skills/pr-resolve/SKILL.md @@ -1,7 +1,7 @@ --- name: pr-resolve description: PR resolve — work through open PR review threads and Codacy issues to get a PR approved and merged. -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # PR Resolve diff --git a/.agents/skills/receiving-code-review/SKILL.md b/.agents/skills/receiving-code-review/SKILL.md index 062571b..025c274 100644 --- a/.agents/skills/receiving-code-review/SKILL.md +++ b/.agents/skills/receiving-code-review/SKILL.md @@ -1,7 +1,7 @@ --- name: receiving-code-review description: Receiving code review feedback — verify before implementing, never blindly agree. -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Code Review Reception diff --git a/.agents/skills/release/SKILL.md b/.agents/skills/release/SKILL.md index 60877a1..6bcdf1a 100644 --- a/.agents/skills/release/SKILL.md +++ b/.agents/skills/release/SKILL.md @@ -1,7 +1,7 @@ --- name: release description: Release workflow — version lock, worktree, bump, commit, PR, GitHub Release. Delegates to project overrides. -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Release — Universal Version Lock Workflow diff --git a/.agents/skills/requesting-code-review/SKILL.md b/.agents/skills/requesting-code-review/SKILL.md index 2b91e7c..0720834 100644 --- a/.agents/skills/requesting-code-review/SKILL.md +++ b/.agents/skills/requesting-code-review/SKILL.md @@ -1,7 +1,7 @@ --- name: requesting-code-review description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Requesting Code Review diff --git a/.agents/skills/setup-foundation-context/SKILL.md b/.agents/skills/setup-foundation-context/SKILL.md index ec71339..c82ac79 100644 --- a/.agents/skills/setup-foundation-context/SKILL.md +++ b/.agents/skills/setup-foundation-context/SKILL.md @@ -8,7 +8,7 @@ description: >- copies. Dry-run by default. Run once per project in a fresh session. Operationalizes DEVS-37. Triggers: "/setup-foundation-context", "setup foundation context", "migrate foundation docs to .context", "onboard foundation docs", "context foundation setup". -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Setup Foundation Context diff --git a/.agents/skills/spec-approach/SKILL.md b/.agents/skills/spec-approach/SKILL.md index 47f6bdf..15b8a53 100644 --- a/.agents/skills/spec-approach/SKILL.md +++ b/.agents/skills/spec-approach/SKILL.md @@ -2,7 +2,7 @@ name: spec-approach description: "Spec Phase 3 — architecture, key decisions, file map (+ UI Contract) into approach.md. Standalone, ISSUE-first. Reads universal + per-project conventions." user-invocable: true -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-approach ISSUE diff --git a/.agents/skills/spec-discovery/SKILL.md b/.agents/skills/spec-discovery/SKILL.md index 4b92925..a65ad6e 100644 --- a/.agents/skills/spec-discovery/SKILL.md +++ b/.agents/skills/spec-discovery/SKILL.md @@ -2,7 +2,7 @@ name: spec-discovery description: "Spec Phase 2 — research the codebase + prior art into discovery.md. Standalone, ISSUE-first. Uses a read-only Workflow fan-out for the research sweep." user-invocable: true -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-discovery ISSUE @@ -28,13 +28,13 @@ Read **`.agents/skills/spec/references/conventions.md`** and the project's **`.c 3. **Research sweep — four read-only angles.** Default to inline research. If the user explicitly asks for parallel agents, use read-only `explorer` subagents for independent angles. Subagents never edit files. - **Structural** — Grep/Glob for affected modules, callers, dependencies. Grep each candidate identifier repo-wide and read the hits; that is the exhaustive path to a call list. - - **Prior decisions** — mem0 (and sessionflow if useful) for past choices on this area. Record exact query strings. + - **Prior decisions** — SessionFlow memory (`mcp__sessionflow__search_memories` with the project; transcripts too if useful) for past choices on this area. Record exact query strings. - **External** — context7 / Brave for libraries, RFCs, platform docs — only if the work involves them. Synthesize the returned findings yourself; do not let an agent write `discovery.md`. For a narrow spec where one or two angles obviously suffice, skip the Workflow and run those searches inline — match the fan-out to the surface area. 4. **Draft `discovery.md`** per the template: - Existing code/files relevant to the work (with `path:line`). - - Prior decisions (mem0/sessionflow) — cite the query strings used. + - Prior decisions (SessionFlow memory and transcripts) — cite the query strings used. - External references (libraries, RFCs, docs) with links. - **Open questions** that block `approach.md`. 5. **Save `discovery.md`.** Touch no other file. diff --git a/.agents/skills/spec-reconcile/SKILL.md b/.agents/skills/spec-reconcile/SKILL.md index b002001..6f8d4f8 100644 --- a/.agents/skills/spec-reconcile/SKILL.md +++ b/.agents/skills/spec-reconcile/SKILL.md @@ -2,7 +2,7 @@ name: spec-reconcile description: "Spec process step — classify /spec-review marks for one phase, apply them with human approval, archive the originals. ISSUE PHASE first." user-invocable: true -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-reconcile ISSUE PHASE diff --git a/.agents/skills/spec-requirements/SKILL.md b/.agents/skills/spec-requirements/SKILL.md index 281054d..7b24748 100644 --- a/.agents/skills/spec-requirements/SKILL.md +++ b/.agents/skills/spec-requirements/SKILL.md @@ -2,7 +2,7 @@ name: spec-requirements description: "Spec Phase 1 — grill the issue, then draft requirements.md in EARS. Standalone, ISSUE-first. Reads universal conventions + per-project overrides." user-invocable: true -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-requirements ISSUE diff --git a/.agents/skills/spec-review/SKILL.md b/.agents/skills/spec-review/SKILL.md index 49d8a36..88f0918 100644 --- a/.agents/skills/spec-review/SKILL.md +++ b/.agents/skills/spec-review/SKILL.md @@ -1,7 +1,7 @@ --- name: spec-review description: "Reviewer-side /spec peer review. Reviews one phase of an active spec against the codebase." -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-review diff --git a/.agents/skills/spec-tasks/SKILL.md b/.agents/skills/spec-tasks/SKILL.md index c43ddba..a034616 100644 --- a/.agents/skills/spec-tasks/SKILL.md +++ b/.agents/skills/spec-tasks/SKILL.md @@ -2,7 +2,7 @@ name: spec-tasks description: "Spec Phase 4 — break approach into a TDD sprint-cohort checklist in tasks.md. Standalone, ISSUE-first. Reads universal + per-project conventions and the tasks template." user-invocable: true -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-tasks ISSUE diff --git a/.agents/skills/spec/SKILL.md b/.agents/skills/spec/SKILL.md index 16654ca..e21e127 100644 --- a/.agents/skills/spec/SKILL.md +++ b/.agents/skills/spec/SKILL.md @@ -2,7 +2,7 @@ name: spec description: "Phased spec workflow above a quick fix. Driver for the /spec-* phase family + execution engines (run/workflow/dispatch). Phased markdown artifacts in the repo's specs root (specs.path in .claude/project.json, default DocVault/specs/)." user-invocable: true -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Spec — Phased Spec Workflow (driver) @@ -42,7 +42,7 @@ This skill is the **lifecycle driver**. The four authoring phases and the review | `run ` | **HARD GATE**, then execute tasks.md **inline**, one task at a time. | | `workflow ` | **HARD GATE**, then **in-harness subagent** conductor — `[P]` tasks run in true parallel via the Task tool. | | `dispatch ` | **HARD GATE**, then print self-contained prompt blocks to **hand off to an external terminal** (Codex / OpenCode / Antigravity / second Claude session). | -| `archive ` | Move folder to `archive/`, log mem0, mark issue Done. | +| `archive ` | Move folder to `archive/`, save a milestone memory, mark issue Done. | > **Verb history (the `dispatch` flip):** the old subcommands were `apply`/`dispatch`/`orchestrate`. Mapping: `apply→run`, `dispatch→workflow`, `orchestrate→dispatch`. **The word `dispatch` changed meaning** — it now means external-terminal handoff, not in-harness subagents. @@ -145,7 +145,7 @@ The main agent is a **conductor**: it reads `tasks.md`, generates a self-contain ### `archive` 1. After PR merges (or abandonment), move the folder to `{specs-root}/archive/YYYY-MM-DD-{ID}-{slug}/`. -2. Save a mem0 project memory: "Spec {ID} {slug} shipped {date} — outcome: {summary}". +2. Save a milestone memory with `mcp__sessionflow__add_memory`: text "Spec {ID} {slug} shipped {date} — outcome: {summary}", `project` from `project.json` (`memory.project`, else lowercase `tag`), `type: "milestone"`, `topic_key: "spec:{ID}"`, `agent_id` the harness, `extra: {"source": "spec-archive"}`. 3. If the issue is still open, mark it Done via `mcp__plane__workitem` (`action: "update"`). --- diff --git a/.agents/skills/spec/references/Guide.md b/.agents/skills/spec/references/Guide.md index 91cc2f9..cb3f71b 100644 --- a/.agents/skills/spec/references/Guide.md +++ b/.agents/skills/spec/references/Guide.md @@ -73,7 +73,7 @@ issue (DEVS-7) /spec apply ────► HARD GATE — verifies files + approval, then worktree + impl │ ▼ -/spec archive ────► moves to archive/, mem0 summary, closes issue +/spec archive ────► moves to archive/, milestone memory, closes issue ``` > **Per-phase review is the design.** A previous version of the workflow ran a single @@ -98,7 +98,7 @@ Plane readable identifier (e.g. `STRK-69`, `DEVS-12`). Phase is one of `requirem | `tasks ` | — | Phase 4 — draft tasks.md | | `reconcile ` | **required** | Classify reviewer findings, edit file on approval, archive marks | | `apply ` | — | Hard gate → worktree + implementation | -| `archive ` | — | Move to archive/, mem0 summary, close issue | +| `archive ` | — | Move to archive/, milestone memory, close issue | The canonical order through a spec is: @@ -161,7 +161,7 @@ whole point — specs don't carry risk registers or NFR matrices. ``` Fills `discovery.md`: existing relevant code (paths cited), prior decisions from -mem0/sessionflow, external references, open questions blocking approach. +SessionFlow memory and transcripts, external references, open questions blocking approach. **Pre-check:** refuses to run if `requirements.md` still has unresolved `> AGENT:` marks or `## AGENT Review` sections outside `## Review Archive`. Run @@ -299,7 +299,7 @@ Then: ``` Moves the spec folder to `specs/archive/YYYY-MM-DD-{ID}-{slug}/`, saves a -mem0 summary memory, marks the Plane issue Done. +milestone memory in SessionFlow, marks the Plane issue Done. --- @@ -336,7 +336,7 @@ You hand off via OpenCode: > /spec discovery DEVS-12 ``` -Kimi reads requirements.md, scans the API repo for existing middleware patterns, searches mem0 for prior rate-limit decisions, and writes discovery.md. Notes that there's already a `RateLimitToken` class in `lib/middleware/quota.ts` worth building on. +Kimi reads requirements.md, scans the API repo for existing middleware patterns, searches SessionFlow memory for prior rate-limit decisions, and writes discovery.md. Notes that there's already a `RateLimitToken` class in `lib/middleware/quota.ts` worth building on. Or you stay in Claude Code and run the phase yourself. The skill works the same. @@ -484,7 +484,7 @@ After PR merges: > /spec archive DEVS-12 ``` -Folder moves to `specs/archive/2026-05-07-DEVS-12-rate-limiter/`. mem0 gets a summary memory. Done. +Folder moves to `specs/archive/2026-05-07-DEVS-12-rate-limiter/`. SessionFlow memory gets a milestone record. Done. ## Multi-model orchestration patterns diff --git a/.agents/skills/spec/references/spec.md b/.agents/skills/spec/references/spec.md index 350d2a8..74bc210 100644 --- a/.agents/skills/spec/references/spec.md +++ b/.agents/skills/spec/references/spec.md @@ -30,7 +30,7 @@ The phased spec workflow (the top tier since the SpecFlow MCP was retired, DEVS- | `/spec-review ` | Per-phase peer review (standalone skill). Run after each phase. | | `/spec reconcile ` | Classify reviewer findings, ask about ambiguous items inline, edit the phase file on your approval, archive marks. Run before the next phase. | | `/spec apply ` | **HARD GATE** → worktree + implementation | -| `/spec archive ` | Move to archive, close issue, save mem0 | +| `/spec archive ` | Move to archive, close issue, save a milestone memory | ## Tier comparison diff --git a/.agents/skills/spec/references/templates/discovery-template.md b/.agents/skills/spec/references/templates/discovery-template.md index 4116619..1e68f9e 100644 --- a/.agents/skills/spec/references/templates/discovery-template.md +++ b/.agents/skills/spec/references/templates/discovery-template.md @@ -19,9 +19,9 @@ _Files and modules already in the project that this work will touch or build on. ## Prior Decisions -_Search mem0 and recent sessions for related decisions. Quote the relevant memory or commit, with date._ +_Search SessionFlow memory and recent sessions for related decisions. Quote the relevant memory or commit, with date._ -- {{DATE}} — _description of the prior decision_ (mem0 memory id or commit sha) +- {{DATE}} — _description of the prior decision_ (memory ID or commit sha) - _none found — first time touching this surface_ ## External References diff --git a/.agents/skills/spec/references/templates/tasks-template.md b/.agents/skills/spec/references/templates/tasks-template.md index c11a823..8a69df3 100644 --- a/.agents/skills/spec/references/templates/tasks-template.md +++ b/.agents/skills/spec/references/templates/tasks-template.md @@ -30,7 +30,7 @@ _Tasks in this cohort touch independent files and can be dispatched to different - [ ] **A.1 [P]** — _short imperative title_ - **File(s):** `path/to/file.ts` - **Acceptance:** _how we know this task is done — usually one or two lines tying back to a specific AC_ - - **Leverage:** _existing helpers, prior art, mem0 memory id if applicable_ + - **Leverage:** _existing helpers, prior art, memory ID if applicable_ - **Maps to:** AC-1 - [ ] **A.2 [P]** — _title_ @@ -136,7 +136,7 @@ _TDD green phase. Write the minimum code that makes all Cohort B tests pass. Tas - Note: scanners often re-post findings on each new commit. After running `/pr-resolve`, check whether new threads appeared from auto-scanners and address those before merge. - [ ] **CLOSE-9. Archive spec** (after PR merges) - - **MUST invoke `/spec archive {{ISSUE-ID}}`** as a skill — moves folder to `archive/YYYY-MM-DD-{{ISSUE-ID}}-{{SLUG}}/` and saves mem0 summary. + - **MUST invoke `/spec archive {{ISSUE-ID}}`** as a skill — moves folder to `archive/YYYY-MM-DD-{{ISSUE-ID}}-{{SLUG}}/` and saves a milestone memory. --- diff --git a/.agents/skills/start/SKILL.md b/.agents/skills/start/SKILL.md index 61aec3c..1f1d6dc 100644 --- a/.agents/skills/start/SKILL.md +++ b/.agents/skills/start/SKILL.md @@ -1,13 +1,13 @@ --- name: start description: > - Lightweight session reorientation — queries sessionflow + mem0 for recent session + Lightweight session reorientation — queries SessionFlow transcripts and memory for recent session context, checks git state and active work (worktrees, stashes, open PRs, recent remote branches, version-lock claims), and surfaces the 5 most recent open issues. Use it for continuing same-day work or resuming after a short break. No indexing, no code search, no agent dispatch. Triggers: "start", "quick start", "resume", "orient me", "where were we". -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Start @@ -16,7 +16,7 @@ Lightweight session reorientation. Use this when you're continuing recent work a need to know where you left off — not when you need a full environment boot. **Under 15 seconds.** No code indexing, no agent dispatch. One Bash sweep for active work, -one Plane list, and two fast memory calls (sessionflow + mem0). +one Plane list, and two fast SessionFlow calls (transcripts + memory). > **Harness-neutral.** One master in `Devops/skill-library/skills/start/`, deployed to > `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex). Edit the master. MCP tool @@ -56,7 +56,7 @@ suspect stale context after a force-push / external merge. The injected git block cannot see other worktrees, stashes, or work another harness or machine pushed. Codex, another Claude account, or a cloud session may have work in flight -that never reached mem0 (no `/wrap` yet) and that the Step 3 keywords would not match. +that never reached SessionFlow memory (no `/wrap` yet) and that the Step 3 keywords would not match. Run this single Bash call: ```bash @@ -132,7 +132,7 @@ If Plane returns nothing or errors, note it briefly and move on. ### Step 3 — Build targeted keywords from Steps 1, 1b and 2 -Before querying sessionflow or mem0, extract 3-5 keywords from what you already learned: +Before querying transcripts or memory, extract 3-5 keywords from what you already learned: - **Issue IDs** from active work (Step 1b) first, then open issues - **Key terms** from issue titles (e.g. `tag taxonomy`, `dual-write`, `frontmatter`) @@ -252,41 +252,34 @@ starting with `agent-a` — subagent dispatches and context compaction blobs. Pr UUID-format session IDs, but keep non-Claude provider IDs when SessionFlow returns them with a valid `provider` label. -**Pass 3 — mem0** (run in parallel with Pass 0+1): +**Pass 3 — SessionFlow memory** (run in parallel with Pass 0+1): -Take `USER` and `PROJECT` from the `project.json` read in Step 0 (DEVS-92 standard): -`USER = mem0.userId` (default `"lbruton"`), `PROJECT = mem0.project` (default: `tag`, -lowercased). - -> mem0's live tool prefix is connection-specific (`mcp____*`), not a fixed -> `mcp__mem0__`. Resolve `search_memories` from the tool catalog (Claude Code: -> `ToolSearch({query: "select:search_memories"})`) and use the identifier it returns. +Take `PROJECT` from the `project.json` read in Step 0: `memory.project` (default: `tag`, +lowercased). The session-start hook already printed the three newest session summaries; this +pass finds the summaries, decisions and handoffs that match the Step 3 keywords: ``` -search_memories( +mcp__sessionflow__search_memories( query="", - top_k=10, - filters={"AND": [{"user_id": USER}, {"metadata": {"project": PROJECT}}]} + project=PROJECT, + n=10, + format="json" ) ``` > **Never filter on `agent_id`.** It names the harness that wrote the record > (`claude-code`, `codex`, …), and `/start` must see every harness's handoffs. -> **Param shape (verified 2026-09-29, hosted connector DEVS-94):** the result count is -> `top_k`, not `limit`, and there is no `enable_graph` param. Always pass `filters` with -> at least a `user_id` clause. If the live schema differs, follow the live schema, not -> this doc. - -> **Quota:** mem0 allows 1,000 retrieval calls per month across every harness. On a -> 429 / "quota exceeded", don't retry — print `⚠ mem0 read quota exhausted — context -> from sessionflow only` and continue. +When a hit needs its session, call `mcp__sessionflow__get_memory_context(memory_id, project=PROJECT)` +instead of searching transcripts again. -Merge with sessionflow findings — mem0 adds `/wrap` session summaries, decisions and handoffs. +Merge with the transcript findings — memory adds `/wrap` session summaries, decisions and handoffs. -**Degradation:** If sessionflow unreachable, use mem0 only + warn: -`⚠ sessionflow unavailable — context from mem0 only`. -If both unavailable, note it and continue. +**Degradation:** SessionFlow serves both transcripts and memory, so check which part failed. A +`memory_unavailable` error means the memory store has not started: warn +`⚠ SessionFlow memory unavailable — context from transcripts only` and continue. If the whole +server is unreachable, use the summaries the session-start hook printed (they may be from its +cache; it says so) and note it. ## Output Format @@ -324,12 +317,12 @@ nothing active. --- -**Handoff:** +**Handoff:** --- ### Last Session -<3-5 sentence recap synthesized from sessionflow turns + mem0 memories — what was worked on, decisions made, next steps> +<3-5 sentence recap synthesized from SessionFlow turns and memories — what was worked on, decisions made, next steps> --- ``` diff --git a/.agents/skills/vault-update/SKILL.md b/.agents/skills/vault-update/SKILL.md index 44dec04..a05d08e 100644 --- a/.agents/skills/vault-update/SKILL.md +++ b/.agents/skills/vault-update/SKILL.md @@ -7,7 +7,7 @@ description: > architecture decisions are made, or project docs need updating. Triggers on: "update vault", "vault update", "docvault", "update docs", "add to vault", "vault" user-invocable: true -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Vault Update diff --git a/.agents/skills/verification-before-completion/SKILL.md b/.agents/skills/verification-before-completion/SKILL.md index 56cd2be..e59519c 100644 --- a/.agents/skills/verification-before-completion/SKILL.md +++ b/.agents/skills/verification-before-completion/SKILL.md @@ -1,7 +1,7 @@ --- name: verification-before-completion description: Run verification commands before claiming work is complete. Evidence before assertions. -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Verification Before Completion diff --git a/.agents/skills/wrap/SKILL.md b/.agents/skills/wrap/SKILL.md index e7060ca..d524ad5 100644 --- a/.agents/skills/wrap/SKILL.md +++ b/.agents/skills/wrap/SKILL.md @@ -2,11 +2,11 @@ name: wrap description: > End-of-session orchestrator — verifies session work, saves ONE detailed session summary to - mem0 (the big-picture record), writes day-to-day lessons to local memory and durable facts to - .context/, syncs docs, and reports Session Health. Run at end of any session, optionally after + SessionFlow memory (the big-picture record), writes day-to-day lessons to local memory and durable + facts to .context/, syncs docs, and reports Session Health. Run at end of any session, optionally after /pr-cleanup. Triggers: "wrap", "wrap up", "close session", "end of session", "done for the night", "finish up", "closing time". -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Wrap Session @@ -22,8 +22,7 @@ Without PR: /wrap Quick re-orient only: /start (no wrap needed) ``` -`/retro` was retired in DEVS-75 (2026-09-27): its mem0 `retro-learning` entries were never -read back by any session. Lessons now go to each harness's local memory, which it loads. +There is no `/retro`: lessons go to each harness's local memory, which that harness loads. ## Arguments @@ -38,14 +37,15 @@ Each memory layer has one job (DEVS-75, confirmed by the user 2026-09-27): | Layer | Holds | Written by /wrap as | |---|---|---| -| **mem0** | The bigger picture: what was worked on, when, where, and what was decided | ONE detailed session summary (Step 3) | +| **SessionFlow memory** | The bigger picture: what was worked on, when, where, and what was decided | ONE detailed session summary (Step 3) | | **Local agent memory** (Claude Code: auto-memory; Codex: `~/.codex/memories/`) | Active day-to-day operating memory: preferences, corrections, gotchas | Local memory entries (Step 4) | | **`.context/`** | Long-term foundational context for implementation work | Doc sync via chore PR (Step 5) | -| **SessionFlow + git** | Verbatim turns and exact history | Nothing — indexed automatically | +| **SessionFlow transcripts + git** | Verbatim turns and exact history | Nothing — indexed automatically | -mem0 + SessionFlow + git history together give the full picture. mem0 does not need to repeat -turn-level detail — it needs searchable anchors (issue IDs, file paths, PR numbers, decisions) -that let a later session find the right SessionFlow turns and commits. +The summary, the transcripts and git history together give the full picture. The summary does not +repeat turn-level detail — it needs searchable anchors (issue IDs, file paths, PR numbers, decisions) +that let a later session find the right turns and commits. Its source-session provenance links it to +this session's turns (`mcp__sessionflow__get_memory_context`). **Three rules that follow from this:** @@ -73,11 +73,11 @@ pwd git rev-parse --show-toplevel 2>/dev/null ``` -If `.claude/project.json` is missing, STOP — the mem0 summary would be tagged to the wrong +If `.claude/project.json` is missing, STOP — the session summary would be tagged to the wrong project. Warn and fix before continuing: ``` -⚠ project.json missing — mem0 project tag will be wrong +⚠ project.json missing — the memory project will be wrong cwd: git toplevel: Likely cause: dropped during merge/reset/worktree switch. @@ -86,8 +86,13 @@ project. Warn and fix before continuing: Offer to create `project.json` from a sibling template and proceed once resolved. Also warn if `pwd` is a subdir of a different git toplevel — same class of bug. -mem0 scope comes from `project.json` (DEVS-92 standard): `USER = mem0.userId` (default -`"lbruton"`), `PROJECT = mem0.project` (default: `tag`, lowercased). +The memory project comes from `project.json`: `PROJECT = memory.project` (default: `tag`, +lowercased). The user defaults to `lbruton`; pass `memory.userId` only when it differs. + +**Provenance** comes from the session-start hook context (the "SessionFlow memory" block at the +top of the session): `session_id`, `provider` and `agent_id`. Keep them as `SESSION_ID`, +`PROVIDER` and `AGENT`. When that block says the harness is unknown, or it is missing, there is +no provenance: leave those fields out. ### Step 1 — Observe (parallel) @@ -107,11 +112,11 @@ Hold the results in working memory for later steps. Do not display them yet. ### Step 2 — (retired: implementation log catch-up, DEVS-71) -### Step 3 — Session summary to mem0 (always) +### Step 3 — Session summary to SessionFlow memory (always) -Write **ONE** mem0 add call that gives a detailed prose account of the session. This is -the only routine mem0 write. Write it yourself from the conversation — never dispatch a -subagent to summarize. +Write **ONE** `mcp__sessionflow__add_memory` call that gives a detailed prose account of the +session. This is the only routine memory write. Write it yourself from the conversation — never +dispatch a subagent to summarize. **Content — include every anchor that applies** (they are what makes the record findable): @@ -125,33 +130,48 @@ subagent to summarize. non-obvious state or gotchas **Style:** as much concrete detail as the session warrants — plain prose, concrete nouns, -no headings or bullets (mem0 stores text, not markdown). mem0's dashboard instructions tell it -to keep a session summary as one memory; the goal is a broad, searchable "have we worked on X before?" -record shared across harnesses and developers, which then points into SessionFlow, git and -the code for depth. No lessons phrased as rules — those go to local memory in Step 4. +no headings or bullets. The record is stored verbatim; the goal is a broad, searchable "have we +worked on X before?" record shared across harnesses, which then points into the transcripts, git +and the code for depth. No lessons phrased as rules — those go to local memory in Step 4. Never put +a secret value in the text: the server rejects a write that matches its secret scanner. + +**Idempotency check first.** When `SESSION_ID` is known, look for this session's summary: + +``` +mcp__sessionflow__list_memories(project: PROJECT, type: "session-summary", + source_session_id: SESSION_ID, limit: 1, format: "json") +``` -> **mem0 tool prefix (DEVS-94):** mem0 is the official hosted MCP connector now — its live tool -> prefix is `mcp____*`, not a fixed `mcp__mem0__`. `add_memory` names the -> capability; resolve the live tool from your catalog before calling it. +A hit means this session was wrapped before. Write anyway: the same `topic_key` makes the new +summary replace the old one in place, so the record always holds the latest account. With no +`SESSION_ID`, list today's summaries for the project (`created_from` and `created_to` set to +today) and skip the write if one already covers this session. ``` -add_memory( +mcp__sessionflow__add_memory( text: "[ session – CT | | codex] ", - user_id: USER, agent_id: "codex", - metadata: { - "type": "session-summary", + project: PROJECT, + type: "session-summary", + topic_key: "session:" + SESSION_ID, # omit when SESSION_ID is unknown + source_session_id: SESSION_ID, # omit when unknown + source_provider: PROVIDER, # omit when unknown + source_project_root: "", + extra: { "source": "wrap", - "project": PROJECT, "date": "", + "branch": "", "issues": ["", ...], "handoff": - } + }, + format: "json" ) ``` -`agent_id` is the harness (`codex` here), never the project. The project lives in -`metadata.project` only (DEVS-92 standard). If the write fails, report it 🟡 — SessionFlow still holds the session. +`agent_id` is the harness (`codex` here), never the project. The result lists similar +memories; when one is an older summary this one replaces, mention it in the recap. If the write +fails (`memory_unavailable`, a secret-scanner rejection), report it 🟡 with the error code — +the transcripts still hold the session. ### Step 4 — Operating memory (local agent memory) @@ -166,7 +186,7 @@ memory system; report the skip instead. Save only prescriptive, reusable guidance. Descriptive session facts belong in the Step 3 summary, not in local memory. Skip this step when there is nothing new. -Local memory is **not** promoted to mem0 any more (DEVS-75 retired the old promotion step). +Local memory is never copied into SessionFlow memory. ### Step 5 — Documentation sync (MANDATORY when behavior changed — fix, don't warn) @@ -241,7 +261,7 @@ warnings, not actions. Compute the traffic-light color: - **🟢 Green** — all four checks pass - **🟡 Yellow** — one or more soft warnings (uncommitted files, stale worktrees, PR open - with passing checks, mem0 summary write failed, etc.) but nothing broken + with passing checks, session summary write failed, etc.) but nothing broken - **🔴 Red** — something is genuinely wrong (PR with failing checks, etc.) ### Step 7 — Print the recap to the user @@ -251,10 +271,10 @@ The recap is the *last* thing the user sees. ``` ## Session Wrapped 🟢 / 🟡 / 🔴 -**mem0 summary:** saved () — or "⚠ write failed" +**Session summary:** saved as (; "replaced" when a re-wrap) — or "⚠ write failed: " **Local memory:** (or "nothing new") **Docs:** <"chore PR #N (auto-merge)" | "shared vault updated (Devops )" | "no impact"> -**Handoff:** <"included in the mem0 summary" if --handoff, else "n/a"> +**Handoff:** <"included in the session summary" if --handoff, else "n/a"> @@ -300,7 +320,7 @@ Warning examples: - `⚠ PR #47 open with passing checks — not merged this session` - `⚠ Worktree .worktrees/swf-92 has uncommitted changes — left intact` - `⚠ Stale worktree .worktrees/swf-88 (branch merged) — run /pr-cleanup next session` -- `⚠ mem0 session summary write failed — SessionFlow still holds the session` +- `⚠ Session summary write failed (memory_unavailable) — the transcripts still hold the session` ### 🔴 Red — something is genuinely broken @@ -325,17 +345,16 @@ Even when red, the wrap still completes. Red is a *report*, not a halt. ## Rules (the short version) - **One flow, no gates.** No "STOP HERE", no phase banners, no mid-flow approval prompts. -- **Exactly one routine mem0 write per wrap:** the Step 3 session summary, tagged - `metadata.project` and `type: session-summary`. No `retro-learning` entries, no local-memory - promotion, no per-fact mem0 writes. -- **Lessons → local memory. Foundations → `.context/`. Big picture → mem0.** +- **Exactly one routine memory write per wrap:** the Step 3 session summary, with `project` and + `type: session-summary`. No local-memory copies, no per-fact memory writes. +- **Lessons → local memory. Foundations → `.context/`. Big picture → SessionFlow memory.** - **Run actions autonomously where the action is obvious.** Fast-forward pull when clean, docs sync. Anything that touches dirty user work becomes a warning, not an action. - **Session Health is the only place warnings appear.** - **The recap is the last thing the user sees.** No follow-up questions after it. - **No subagents for summarization.** You write the summary from your own context. -- **Idempotent.** Running `/wrap` twice should not write two summaries — search mem0 for a - `session-summary` for this project and date first, and skip if one covers this session. +- **Idempotent.** Running `/wrap` twice never leaves two summaries for one session: the + `session:` topic key replaces the earlier record (Step 3). - **Never auto-delete uncommitted work, ever.** Worktrees, branches, files, stashes — all off-limits to autonomous deletion. diff --git a/.claude/agents/firecrawl-scraper.md b/.claude/agents/firecrawl-scraper.md index 09651ef..c5032fb 100644 --- a/.claude/agents/firecrawl-scraper.md +++ b/.claude/agents/firecrawl-scraper.md @@ -2,7 +2,7 @@ name: firecrawl-scraper description: "Web scraping and research subagent. Dispatched to scrape URLs, search the web, crawl sites, and extract structured data using the self-hosted Firecrawl MCP tools. Returns distilled results to keep the main context clean." model: haiku -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- You are a web scraping specialist. You are dispatched by the orchestrator to fetch, extract, and distill web content. Your job is to do the scraping work and return only the useful results — never dump raw HTML or full page markdown back to the caller unless explicitly asked. diff --git a/.claude/agents/pr-discover.md b/.claude/agents/pr-discover.md index 032c374..a0a5288 100644 --- a/.claude/agents/pr-discover.md +++ b/.claude/agents/pr-discover.md @@ -2,7 +2,7 @@ name: pr-discover description: "PR discovery and pre-analysis agent. Gathers all PR review threads, Codacy findings, runs code review subagents, and returns a structured findings report with file-based thread clusters. Dispatched by /pr-resolve to isolate the heavy data-gathering phases from main context." model: sonnet -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # PR Discovery & Pre-Analysis Agent diff --git a/.claude/agents/pr-thread-resolver.md b/.claude/agents/pr-thread-resolver.md index 52a552e..4b0ffc9 100644 --- a/.claude/agents/pr-thread-resolver.md +++ b/.claude/agents/pr-thread-resolver.md @@ -2,7 +2,7 @@ name: pr-thread-resolver description: "Resolves a cluster of PR review threads grouped by file/topic. Dispatched in parallel by pr-resolve for independent clusters. Re-fetches thread IDs via GraphQL before acting to handle intervening rebases. Makes code fixes, generates replies, and returns results for the orchestrator to post." model: sonnet -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- You are a PR thread cluster resolver. You receive a cluster of classified review threads (all on the same file or topic) and execute the resolutions — fixing code, generating replies, or both. Multiple clusters run in parallel, but within your cluster you handle threads sequentially to avoid edit conflicts. diff --git a/.claude/hooks/block-pr-merge.py b/.claude/hooks/block-pr-merge.py index 60aa0a3..763019b 100644 --- a/.claude/hooks/block-pr-merge.py +++ b/.claude/hooks/block-pr-merge.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -# library-version: 6b4e75d9e513 +# library-version: ce6718eb297b """PreToolUse hook: force human approval for any PR merge. Merging a PR is a human-gated activity. Green CI is NOT authorization. diff --git a/.claude/hooks/docvault-lint.py b/.claude/hooks/docvault-lint.py index 3984b65..262e26a 100644 --- a/.claude/hooks/docvault-lint.py +++ b/.claude/hooks/docvault-lint.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -# library-version: 6b4e75d9e513 +# library-version: ce6718eb297b """Post-edit lint hook for DocVault vaults — markdownlint + frontmatter + wikilink checks. DEVS-78: any `*/DocVault/**` file is a vault page (project vaults in each repo, the shared diff --git a/.claude/hooks/vale-staged.py b/.claude/hooks/vale-staged.py index 9327919..0077968 100644 --- a/.claude/hooks/vale-staged.py +++ b/.claude/hooks/vale-staged.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -# library-version: 6b4e75d9e513 +# library-version: ce6718eb297b """PostToolUse hook: report Vale alerts on the lines a `git commit` added. It lints a snapshot of HEAD, so the text and line numbers match the commit, whatever the diff --git a/.claude/hooks/worktree-safety.py b/.claude/hooks/worktree-safety.py index 37d9d82..597f51e 100644 --- a/.claude/hooks/worktree-safety.py +++ b/.claude/hooks/worktree-safety.py @@ -1,5 +1,5 @@ #!/usr/bin/env python3 -# library-version: 6b4e75d9e513 +# library-version: ce6718eb297b """PreToolUse hook — warns when an Edit/Write targets a file outside the active worktree. Catches the common mistake of editing files in the main repo checkout when diff --git a/.claude/rules/code-core.md b/.claude/rules/code-core.md index a499beb..9c19f44 100644 --- a/.claude/rules/code-core.md +++ b/.claude/rules/code-core.md @@ -1,7 +1,7 @@ --- name: code-core description: Workflow rules shared by every code repo - DocVault, glossary, Plane, Infisical, debugging, memory, code search, editing, tests, spec gates, push rules, red flags, GitHub hygiene -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Code-core rules @@ -35,7 +35,8 @@ development practices, procedures and runbooks, specs and approvals, research an - **Public repos:** before writing to `/DocVault/`, check nothing sensitive is going in. Sensitive material goes to the private companion instead. - If a page looks stale, flag it; do not silently act on suspected bad data. -- On conflicts between DocVault and mem0, the newest information wins. Ask when it is unclear. +- On conflicts between DocVault and SessionFlow memory, the newest information wins. Ask when it is + unclear. ## Domain glossary @@ -97,10 +98,10 @@ needs no secrets. Never hard-code an Infisical project ID anywhere else; read it - When comparing file counts against an index, use `git ls-files | wc -l`, not a raw filesystem count. Raw counts include `.venv` and `node_modules`. - Never edit `claude_desktop_config.json` while Claude Desktop is running. Ask the user to quit the app first. -- A transient MCP, Plane or mem0 failure (empty payload, temporary error, unexpected empty result for a - known object): wait about 60 seconds and retry once. If it still fails, continue with local-safe steps. - An HTTP 429 or "quota exceeded" from mem0 is not transient: do not retry, continue without mem0 reads and - tell the user. +- A transient MCP, Plane or SessionFlow failure (empty payload, temporary error, unexpected empty result + for a known object): wait about 60 seconds and retry once. If it still fails, continue with local-safe + steps. A `memory_unavailable` error means the memory store has not started: say so and continue without + memory reads; `/health` names the reason. ## Memory: coexisting layers @@ -109,49 +110,41 @@ failure mode. Each has a distinct job: | Layer | Scope | Role | |---|---|---| -| **mem0** (hosted MCP connector; the tool prefix is account-specific) | cross-session and cross-harness | **The bigger picture**: one `/wrap` session summary per session (what, when, files, issues, decisions), plus explicit decisions and handoffs | +| **SessionFlow memory** (`mcp__sessionflow__` memory tools, Postgres-backed) | cross-session and cross-harness | **The bigger picture**: one `/wrap` session summary per session (what, when, files, issues, decisions), plus explicit decisions and handoffs | | **auto-memory** (`MEMORY.md` + per-fact files) | project-scoped, Claude Code only | **Day-to-day operating memory**: preferences, corrections, gotchas; the `MEMORY.md` index is injected at session start | | **`.context/`** (in-repo) | per-project, all harnesses | **Long-term foundations** needed for implementation work: architecture, conventions, standards | -| **sessionflow** (`mcp__sessionflow__*`) | all harnesses, all projects | Transcript search over verbatim past turns; the session-start recall tier | +| **SessionFlow transcripts** (`mcp__sessionflow__search_all_sessions` and friends) | all harnesses, all projects | Transcript search over verbatim past turns; the session-start recall tier | | **Plane** (`mcp__plane__*`) | per-project issues | Issue and planning state, not a memory store | -mem0 + sessionflow + git history together give the full picture of past work. Lessons ("when X, do Y") go -to local memory, not mem0. Durable foundations go to `.context/`. +SessionFlow memory, transcript search and git history together give the full picture of past work. +Lessons ("when X, do Y") go to local memory, not SessionFlow memory. Durable foundations go to `.context/`. -**Recall at session start (two sources):** +**Recall at session start:** the SessionFlow session-start hook already prints the three newest session +summaries and recent turns for the project, with session provenance. Go further only when the task needs it: -1. **sessionflow**: verbatim past turns, semantic search: +```javascript +mcp__sessionflow__list_memories({ project: "", type: "session-summary", limit: 10 }) +mcp__sessionflow__search_memories({ query: " handoff", project: "", n: 10 }) +mcp__sessionflow__search_all_sessions({ query: " ", n: 5 }) +``` - ```javascript - mcp__sessionflow__search_all_sessions({ query: "last session work decisions ", n: 5 }) - ``` - -2. **mem0**: session summaries, decisions, handoffs. The tool prefix is not fixed. - Resolve it with `ToolSearch({ query: "select:search_memories" })` if it is not already loaded. - - ```javascript - search_memories({ query: "last session work decisions for ", limit: 10, - filters: { AND: [{ user_id: "lbruton" }, { metadata: { project: "" } }] }, - enable_graph: false }) - ``` - -**mem0 standard (DEVS-92)**: three keys on every record. +**Memory standard**: every record carries these keys. | Key | Value | Source | |---|---|---| -| `user_id` | `lbruton`, always | `project.json` → `mem0.userId` | -| `agent_id` | the harness writing: `claude-code` here (other harnesses write `claude-code`, `claude-cowork`, `codex`, `gemini`, `opencode` or `antigravity`) | the harness itself; never `project.json`, never a project name | -| `metadata.project` | lowercase project slug (`staktrakr`, `devops`) | `project.json` → `mem0.project`, else the lowercase `tag` | - -- **Writes:** set all three plus `metadata.type` ∈ `session-summary` / `decision` / `handoff`. Routine - writes come from `/wrap` only (one paragraph `session-summary`). Use a direct `add_memory` call - (`type: decision` or `handoff`) only for an explicit decision or handoff that must be shared before the - session ends. Never write a mem0 entry per task: commits, PRs and Plane comments record each task. -- **Reads:** filter `user_id` + `metadata.project` server-side (the match is case-sensitive). Never filter - on `agent_id`: every harness must see the others' handoffs. Run TWO searches: one project-scoped, one - user-only cross-project workflow query. -- **Quota:** the plan allows 1,000 retrieval calls per month, shared by every harness. Never page through - the store in bulk; estimate call counts before any audit. +| `user_id` | `lbruton` (the default; omit it) | `project.json` → `memory.userId` | +| `agent_id` | the harness writing: `claude-code` here (one of `claude-code`, `codex`, `gemini`, `opencode`, `antigravity`) | the harness itself; never `project.json`, never a project name | +| `project` | lowercase project slug (`staktrakr`, `devops`) | `project.json` → `memory.project`, else the lowercase `tag` | +| `type` | `session-summary`, `decision`, `handoff`, `fact`, `workflow`, `discovery`, `contact`, `blocker`, `preference`, `open-item`, `milestone` or `guardrail` | the kind of note | + +- **Writes:** routine writes come from `/wrap` only (one `session-summary` per session). Call + `mcp__sessionflow__add_memory` directly (`type: decision` or `handoff`) only for an explicit decision or + handoff that must be shared before the session ends. Never write a memory per task: commits, PRs and Plane + comments record each task. +- **Reads:** every memory call passes `project`; pass `"*"` for a cross-project query. Never filter on + `agent_id`: every harness must see the others' handoffs. Pass `format: "json"` when you parse the result. +- **Replace, do not duplicate:** a later `mcp__sessionflow__add_memory` with the same `topic_key` replaces that record. To + retire older notes, pass their IDs in `supersedes`. ## Code search order (cheapest first) @@ -170,8 +163,7 @@ re-add or call them. | Server | Use for | |---|---| -| `mem0` (hosted connector) | Cross-session memory, sole backend | -| `sessionflow` | Session history search: semantic retrieval over past conversation turns | +| `sessionflow` | Session history search over past turns, and the cross-session memory store: `mcp__sessionflow__add_memory`, `mcp__sessionflow__search_memories`, `mcp__sessionflow__list_memories`, `mcp__sessionflow__get_memory`, `mcp__sessionflow__update_memory`, `mcp__sessionflow__delete_memory`, `mcp__sessionflow__get_memory_context` | | `context7` | Library documentation lookup | | `chrome-devtools` | Browser-page inspection and debugging | | `infisical` | Secret inventory; fallback only, use the `infisical-agent` CLI first | diff --git a/.claude/rules/prose-core.md b/.claude/rules/prose-core.md index e672c70..a99bea2 100644 --- a/.claude/rules/prose-core.md +++ b/.claude/rules/prose-core.md @@ -1,5 +1,5 @@ --- -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Prose-core rules diff --git a/.claude/skills/.library-manifest b/.claude/skills/.library-manifest index 468b618..ebaa632 100644 --- a/.claude/skills/.library-manifest +++ b/.claude/skills/.library-manifest @@ -1,6 +1,6 @@ # Managed by skills-deploy (DEVS-125). Entries here are overwritten or removed by --apply; # every other skill or agent in this repo is project-owned and never touched. -# library-version: 6b4e75d9e513 +# library-version: ce6718eb297b skill start skill wrap skill issue diff --git a/.claude/skills/codacy-analysis-cli/SKILL.md b/.claude/skills/codacy-analysis-cli/SKILL.md index d2005dd..9213c38 100644 --- a/.claude/skills/codacy-analysis-cli/SKILL.md +++ b/.claude/skills/codacy-analysis-cli/SKILL.md @@ -5,7 +5,7 @@ license: MIT metadata: author: Codacy version: 1.5.0 -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Codacy Analysis CLI diff --git a/.claude/skills/codacy-cloud-cli/SKILL.md b/.claude/skills/codacy-cloud-cli/SKILL.md index c0465ee..1e05ae5 100644 --- a/.claude/skills/codacy-cloud-cli/SKILL.md +++ b/.claude/skills/codacy-cloud-cli/SKILL.md @@ -5,7 +5,7 @@ license: MIT metadata: author: Codacy version: 1.6.1 -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Codacy Cloud CLI diff --git a/.claude/skills/codacy-code-review/SKILL.md b/.claude/skills/codacy-code-review/SKILL.md index c167de1..2c5e2d7 100644 --- a/.claude/skills/codacy-code-review/SKILL.md +++ b/.claude/skills/codacy-code-review/SKILL.md @@ -5,7 +5,7 @@ license: MIT metadata: author: Codacy version: 1.5.0 -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Codacy Code Review diff --git a/.claude/skills/context-drift/SKILL.md b/.claude/skills/context-drift/SKILL.md index 65023ee..65cee3a 100644 --- a/.claude/skills/context-drift/SKILL.md +++ b/.claude/skills/context-drift/SKILL.md @@ -12,7 +12,7 @@ description: >- "context-drift", "audit .context", "check context docs", "foundation drift", "verify foundation", "what should be in .context". allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Skill, Agent -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Context Drift diff --git a/.claude/skills/discernment-nudge/SKILL.md b/.claude/skills/discernment-nudge/SKILL.md index 2cb401c..078ca8c 100644 --- a/.claude/skills/discernment-nudge/SKILL.md +++ b/.claude/skills/discernment-nudge/SKILL.md @@ -17,7 +17,7 @@ description: > to double-check, cite, or review — the skill file explains these boundaries and the exact output format. license: Complete terms in LICENSE.txt -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Discernment nudge diff --git a/.claude/skills/discover/SKILL.md b/.claude/skills/discover/SKILL.md index 723b351..b52842e 100644 --- a/.claude/skills/discover/SKILL.md +++ b/.claude/skills/discover/SKILL.md @@ -16,8 +16,11 @@ allowed-tools: >- mcp__infisical__get-secret, mcp__plane__workitem, mcp__plane__state, - mcp__plane__label -library-version: 6b4e75d9e513 + mcp__plane__label, + mcp__sessionflow__search_memories, + mcp__sessionflow__add_memory, + mcp__sessionflow__search_all_sessions +library-version: ce6718eb297b --- # Discover — Phase 1 Structured Brainstorm @@ -74,9 +77,9 @@ Glob `{specs-root}/{ISSUE-ID}-*/` (ignore `archive/`), where `{specs-root}` is ` ## Research fan-out (Steps 1–3) — run as a read-only Workflow -Steps 1–3 are pure read work across independent angles — the canonical use for the `Workflow` orchestration tool. When the research surface is broad (multiple subsystems, prior art *and* external docs *and* mem0 history), dispatch the sweep as a **`Workflow` fan-out**: one parallel agent per angle — +Steps 1–3 are pure read work across independent angles — the canonical use for the `Workflow` orchestration tool. When the research surface is broad (multiple subsystems, prior art *and* external docs *and* memory history), dispatch the sweep as a **`Workflow` fan-out**: one parallel agent per angle — -1. **Prior context** — mem0 + sessionflow + the project and shared vaults (Grep). +1. **Prior context** — SessionFlow memory and transcripts + the project and shared vaults (Grep). 2. **Codebase impact** — Grep/Glob structural, plus the `Explore` subagent for broad sweeps. 3. **External** — context7 + Brave (only if libraries/APIs/platform features are involved). @@ -86,17 +89,15 @@ Each agent returns structured findings; **you** synthesize them into the Discove Run these in parallel. **Record every query string used** — they go into the issue's Discovery block at Step 6 as Context Pointers so future sessions can re-hydrate deterministically. -### mem0 search -> mem0's live tool prefix is connection-specific (`mcp____*`), not the fixed -> `mcp__mem0__`. `search_memories` and `add_memory` below name capabilities; resolve the live -> tool from your catalog before calling it. -> Claude Code: `ToolSearch({query: "select:search_memories,add_memory"})` if not already loaded. +### SessionFlow memory search ``` -search_memories +mcp__sessionflow__search_memories query: "{issue title} {key terms from description}" - limit: 10 - filters: {AND: [{user_id: "lbruton"}, {metadata: {project: ""}}]} + project: "" + n: 10 + format: "json" ``` +Pass `project: "*"` as a second query when the topic spans projects. ### Vault search Search both the project vault and the shared vault. Grep for the key terms and their synonyms, then @@ -117,7 +118,7 @@ mcp__sessionflow__search_all_sessions Present any relevant past decisions, related work, or prior discussions. -**Track for Step 6:** the exact query strings and patterns used (mem0, sessionflow, vault Grep) and any Research Brief / KB / Foundation page hits — these become the Context Pointers list. +**Track for Step 6:** the exact query strings and patterns used (memory, transcripts, vault Grep) and any Research Brief / KB / Foundation page hits — these become the Context Pointers list. --- @@ -258,8 +259,8 @@ Keep it concise — summary + pointers, not transcripts. A quick-fix-only consum - [Non-blocking question] — carry forward to spec ### Context Pointers -- **mem0:** `search: ""` — [what it surfaces] -- **mem0:** `search: ""` — [what it surfaces] +- **Memory:** `mcp__sessionflow__search_memories` query `""` — [what it surfaces] +- **Memory:** `mcp__sessionflow__search_memories` query `""` — [what it surfaces] - **Research Brief:** [[Research/{topic}]] (if one exists or was created) - **KB:** [[KnowledgeBase/{page}]] — [why relevant] - **Foundation:** [[Foundation/{doc}]] — [why relevant] @@ -301,20 +302,19 @@ Show the user the brief you just wrote, so they see what landed in the issue wit ## Step 7: Hand Off -### Save discovery summary to mem0 (semantic retrieval) +### Save discovery summary to SessionFlow memory (semantic retrieval) -The issue is now authoritative — mem0 is the semantic-retrieval mirror. Keep the memory **short** since the full detail lives in the issue. +The issue is now authoritative — the memory is its searchable mirror. Keep it **short** since the full detail lives in the issue. The topic key makes a re-run of `/discover` replace the earlier decision instead of adding a second one. ``` -add_memory( +mcp__sessionflow__add_memory( text: "Discovery complete for {ISSUE-ID} — {one-sentence recommended approach}. Full brief in Plane issue. Scope: {size}.", - user_id: "lbruton", agent_id: "claude-code", - metadata: { - "type": "decision", + project: "", + type: "decision", + topic_key: "discover:{ISSUE-ID}", + extra: { "source": "discover", - "project": "", - "issue": "{ISSUE-ID}", "issue_url": "https://plane.lbruton.cc/lbruton/browse/{ISSUE-ID}/", "issue_uuid": "{plane issue uuid}", "category": "architecture" diff --git a/.claude/skills/issue/SKILL.md b/.claude/skills/issue/SKILL.md index 257a253..8359e17 100644 --- a/.claude/skills/issue/SKILL.md +++ b/.claude/skills/issue/SKILL.md @@ -6,7 +6,7 @@ description: > Triggers on: "create issue", "issue", "new issue", "new bug", "file a bug", "track this". user-invocable: false -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Issue Management diff --git a/.claude/skills/pr-cleanup/SKILL.md b/.claude/skills/pr-cleanup/SKILL.md index 67d6cc0..807a932 100644 --- a/.claude/skills/pr-cleanup/SKILL.md +++ b/.claude/skills/pr-cleanup/SKILL.md @@ -5,7 +5,7 @@ description: > local branches and their worktrees, pulls main fast-forward, and reports the result. Run after a PR is merged, before /wrap. Triggers: "pr-cleanup", "clean up branches", "prune worktrees", "clean after merge". -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # PR Cleanup diff --git a/.claude/skills/pr-resolve/SKILL.md b/.claude/skills/pr-resolve/SKILL.md index 4d9739f..a1f499b 100644 --- a/.claude/skills/pr-resolve/SKILL.md +++ b/.claude/skills/pr-resolve/SKILL.md @@ -2,7 +2,7 @@ name: pr-resolve description: PR resolve — work through open PR review threads and Codacy issues to get a PR approved and merged. allowed-tools: Bash, Read, Write, Edit, Grep, Glob, mcp__infisical__get-secret, mcp__github__get_pull_request, mcp__github__list_pull_requests, mcp__github__get_pull_request_status, mcp__github__get_pull_request_reviews, mcp__github__get_pull_request_comments, mcp__github__get_pull_request_files -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # PR Resolve diff --git a/.claude/skills/receiving-code-review/SKILL.md b/.claude/skills/receiving-code-review/SKILL.md index 062571b..025c274 100644 --- a/.claude/skills/receiving-code-review/SKILL.md +++ b/.claude/skills/receiving-code-review/SKILL.md @@ -1,7 +1,7 @@ --- name: receiving-code-review description: Receiving code review feedback — verify before implementing, never blindly agree. -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Code Review Reception diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md index fd5869c..6094d68 100644 --- a/.claude/skills/release/SKILL.md +++ b/.claude/skills/release/SKILL.md @@ -2,7 +2,7 @@ name: release description: Release workflow — version lock, worktree, bump, commit, PR, GitHub Release. Delegates to project overrides. allowed-tools: Bash, Read, Write, Edit, Grep, Glob -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Release — Universal Version Lock Workflow diff --git a/.claude/skills/requesting-code-review/SKILL.md b/.claude/skills/requesting-code-review/SKILL.md index ad9b089..c743921 100644 --- a/.claude/skills/requesting-code-review/SKILL.md +++ b/.claude/skills/requesting-code-review/SKILL.md @@ -1,7 +1,7 @@ --- name: requesting-code-review description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Requesting Code Review diff --git a/.claude/skills/setup-foundation-context/SKILL.md b/.claude/skills/setup-foundation-context/SKILL.md index ae9e33b..6f4ce44 100644 --- a/.claude/skills/setup-foundation-context/SKILL.md +++ b/.claude/skills/setup-foundation-context/SKILL.md @@ -9,7 +9,7 @@ description: >- DEVS-37. Triggers: "/setup-foundation-context", "setup foundation context", "migrate foundation docs to .context", "onboard foundation docs", "context foundation setup". allowed-tools: Read, Write, Edit, Bash, Glob, Grep, Skill -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Setup Foundation Context diff --git a/.claude/skills/spec-approach/SKILL.md b/.claude/skills/spec-approach/SKILL.md index 77499d8..dbf6141 100644 --- a/.claude/skills/spec-approach/SKILL.md +++ b/.claude/skills/spec-approach/SKILL.md @@ -4,7 +4,7 @@ description: "Spec Phase 3 — architecture, key decisions, file map (+ UI Contr user-invocable: true allowed-tools: >- Bash, Read, Write, Edit, Glob, Grep -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-approach ISSUE diff --git a/.claude/skills/spec-discovery/SKILL.md b/.claude/skills/spec-discovery/SKILL.md index 88d842f..334e9c4 100644 --- a/.claude/skills/spec-discovery/SKILL.md +++ b/.claude/skills/spec-discovery/SKILL.md @@ -6,7 +6,7 @@ allowed-tools: >- Bash, Read, Write, Edit, Glob, Grep, Workflow, ToolSearch, mcp__context7__resolve-library-id, mcp__brave-search__brave_web_search -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-discovery ISSUE @@ -32,13 +32,13 @@ Read **`.claude/skills/spec/references/conventions.md`** and the project's **`.c 3. **Research sweep — four read-only angles.** Dispatch them as a read-only Workflow fan-out. This is pure read work across independent angles, so it's the canonical Workflow use. Run the three angles as parallel agents, each returning structured findings: - **Structural** — Grep/Glob for affected modules, callers, dependencies. Grep each candidate identifier repo-wide and read the hits; that is the exhaustive path to a call list. - - **Prior decisions** — mem0 (and sessionflow if useful) for past choices on this area. Record exact query strings. + - **Prior decisions** — SessionFlow memory (`mcp__sessionflow__search_memories` with the project; transcripts too if useful) for past choices on this area. Record exact query strings. - **External** — context7 / Brave for libraries, RFCs, platform docs — only if the work involves them. Synthesize the returned findings yourself; do not let an agent write `discovery.md`. For a narrow spec where one or two angles obviously suffice, skip the Workflow and run those searches inline — match the fan-out to the surface area. 4. **Draft `discovery.md`** per the template: - Existing code/files relevant to the work (with `path:line`). - - Prior decisions (mem0/sessionflow) — cite the query strings used. + - Prior decisions (SessionFlow memory and transcripts) — cite the query strings used. - External references (libraries, RFCs, docs) with links. - **Open questions** that block `approach.md`. 5. **Save `discovery.md`.** Touch no other file. diff --git a/.claude/skills/spec-reconcile/SKILL.md b/.claude/skills/spec-reconcile/SKILL.md index 441de6a..0e45a4e 100644 --- a/.claude/skills/spec-reconcile/SKILL.md +++ b/.claude/skills/spec-reconcile/SKILL.md @@ -4,7 +4,7 @@ description: "Spec process step — classify /spec-review marks for one phase, a user-invocable: true allowed-tools: >- Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-reconcile ISSUE PHASE diff --git a/.claude/skills/spec-requirements/SKILL.md b/.claude/skills/spec-requirements/SKILL.md index a7128cf..f3ade77 100644 --- a/.claude/skills/spec-requirements/SKILL.md +++ b/.claude/skills/spec-requirements/SKILL.md @@ -5,7 +5,7 @@ user-invocable: true allowed-tools: >- Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion, Skill, mcp__plane__workitem -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-requirements ISSUE diff --git a/.claude/skills/spec-review/SKILL.md b/.claude/skills/spec-review/SKILL.md index 1ab289d..984ccce 100644 --- a/.claude/skills/spec-review/SKILL.md +++ b/.claude/skills/spec-review/SKILL.md @@ -1,7 +1,7 @@ --- name: spec-review description: "Reviewer-side /spec peer review. Reviews one phase of an active spec against the codebase." -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-review diff --git a/.claude/skills/spec-tasks/SKILL.md b/.claude/skills/spec-tasks/SKILL.md index bb2cda3..5e5e3fc 100644 --- a/.claude/skills/spec-tasks/SKILL.md +++ b/.claude/skills/spec-tasks/SKILL.md @@ -4,7 +4,7 @@ description: "Spec Phase 4 — break approach into a TDD sprint-cohort checklist user-invocable: true allowed-tools: >- Bash, Read, Write, Edit, Glob, Grep, AskUserQuestion -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # /spec-tasks ISSUE diff --git a/.claude/skills/spec/SKILL.md b/.claude/skills/spec/SKILL.md index cf48d9b..81029fa 100644 --- a/.claude/skills/spec/SKILL.md +++ b/.claude/skills/spec/SKILL.md @@ -7,7 +7,7 @@ allowed-tools: >- mcp__plane__workitem, mcp__plane__state, mcp__plane__project -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Spec — Phased Spec Workflow (driver) @@ -47,7 +47,7 @@ This skill is the **lifecycle driver**. The four authoring phases and the review | `run ` | **HARD GATE**, then execute tasks.md **inline**, one task at a time. | | `workflow ` | **HARD GATE**, then **in-harness subagent** conductor — `[P]` tasks run in true parallel via the Task tool. | | `dispatch ` | **HARD GATE**, then print self-contained prompt blocks to **hand off to an external terminal** (Codex / OpenCode / Antigravity / second Claude session). | -| `archive ` | Move folder to `archive/`, log mem0, mark issue Done. | +| `archive ` | Move folder to `archive/`, save a milestone memory, mark issue Done. | > **Verb history (the `dispatch` flip):** the old subcommands were `apply`/`dispatch`/`orchestrate`. Mapping: `apply→run`, `dispatch→workflow`, `orchestrate→dispatch`. **The word `dispatch` changed meaning** — it now means external-terminal handoff, not in-harness subagents. @@ -152,7 +152,7 @@ The main agent is a **conductor**: it reads `tasks.md`, generates a self-contain ### `archive` 1. After PR merges (or abandonment), move the folder to `{specs-root}/archive/YYYY-MM-DD-{ID}-{slug}/`. -2. Save a mem0 project memory: "Spec {ID} {slug} shipped {date} — outcome: {summary}". +2. Save a milestone memory with `mcp__sessionflow__add_memory`: text "Spec {ID} {slug} shipped {date} — outcome: {summary}", `project` from `project.json` (`memory.project`, else lowercase `tag`), `type: "milestone"`, `topic_key: "spec:{ID}"`, `agent_id` the harness, `extra: {"source": "spec-archive"}`. 3. If the issue is still open, mark it Done via `mcp__plane__workitem` (`action: "update"`). --- diff --git a/.claude/skills/spec/references/Guide.md b/.claude/skills/spec/references/Guide.md index d5ae74b..9fdbba9 100644 --- a/.claude/skills/spec/references/Guide.md +++ b/.claude/skills/spec/references/Guide.md @@ -73,7 +73,7 @@ issue (DEVS-7) /spec apply ────► HARD GATE — verifies files + approval, then worktree + impl │ ▼ -/spec archive ────► moves to archive/, mem0 summary, closes issue +/spec archive ────► moves to archive/, milestone memory, closes issue ``` > **Per-phase review is the design.** A previous version of the workflow ran a single @@ -98,7 +98,7 @@ Plane readable identifier (e.g. `STRK-69`, `DEVS-12`). Phase is one of `requirem | `tasks ` | — | Phase 4 — draft tasks.md | | `reconcile ` | **required** | Classify reviewer findings, edit file on approval, archive marks | | `apply ` | — | Hard gate → worktree + implementation | -| `archive ` | — | Move to archive/, mem0 summary, close issue | +| `archive ` | — | Move to archive/, milestone memory, close issue | The canonical order through a spec is: @@ -161,7 +161,7 @@ whole point — specs don't carry risk registers or NFR matrices. ``` Fills `discovery.md`: existing relevant code (paths cited), prior decisions from -mem0/sessionflow, external references, open questions blocking approach. +SessionFlow memory and transcripts, external references, open questions blocking approach. **Pre-check:** refuses to run if `requirements.md` still has unresolved `> AGENT:` marks or `## AGENT Review` sections outside `## Review Archive`. Run @@ -299,7 +299,7 @@ Then: ``` Moves the spec folder to `specs/archive/YYYY-MM-DD-{ID}-{slug}/`, saves a -mem0 summary memory, marks the Plane issue Done. +milestone memory in SessionFlow, marks the Plane issue Done. --- @@ -336,7 +336,7 @@ You hand off via OpenCode: > /spec discovery DEVS-12 ``` -Kimi reads requirements.md, scans the API repo for existing middleware patterns, searches mem0 for prior rate-limit decisions, and writes discovery.md. Notes that there's already a `RateLimitToken` class in `lib/middleware/quota.ts` worth building on. +Kimi reads requirements.md, scans the API repo for existing middleware patterns, searches SessionFlow memory for prior rate-limit decisions, and writes discovery.md. Notes that there's already a `RateLimitToken` class in `lib/middleware/quota.ts` worth building on. Or you stay in Claude Code and run the phase yourself. The skill works the same. @@ -484,7 +484,7 @@ After PR merges: > /spec archive DEVS-12 ``` -Folder moves to `specs/archive/2026-05-07-DEVS-12-rate-limiter/`. mem0 gets a summary memory. Done. +Folder moves to `specs/archive/2026-05-07-DEVS-12-rate-limiter/`. SessionFlow memory gets a milestone record. Done. ## Multi-model orchestration patterns diff --git a/.claude/skills/spec/references/spec.md b/.claude/skills/spec/references/spec.md index 350d2a8..74bc210 100644 --- a/.claude/skills/spec/references/spec.md +++ b/.claude/skills/spec/references/spec.md @@ -30,7 +30,7 @@ The phased spec workflow (the top tier since the SpecFlow MCP was retired, DEVS- | `/spec-review ` | Per-phase peer review (standalone skill). Run after each phase. | | `/spec reconcile ` | Classify reviewer findings, ask about ambiguous items inline, edit the phase file on your approval, archive marks. Run before the next phase. | | `/spec apply ` | **HARD GATE** → worktree + implementation | -| `/spec archive ` | Move to archive, close issue, save mem0 | +| `/spec archive ` | Move to archive, close issue, save a milestone memory | ## Tier comparison diff --git a/.claude/skills/spec/references/templates/discovery-template.md b/.claude/skills/spec/references/templates/discovery-template.md index 4116619..1e68f9e 100644 --- a/.claude/skills/spec/references/templates/discovery-template.md +++ b/.claude/skills/spec/references/templates/discovery-template.md @@ -19,9 +19,9 @@ _Files and modules already in the project that this work will touch or build on. ## Prior Decisions -_Search mem0 and recent sessions for related decisions. Quote the relevant memory or commit, with date._ +_Search SessionFlow memory and recent sessions for related decisions. Quote the relevant memory or commit, with date._ -- {{DATE}} — _description of the prior decision_ (mem0 memory id or commit sha) +- {{DATE}} — _description of the prior decision_ (memory ID or commit sha) - _none found — first time touching this surface_ ## External References diff --git a/.claude/skills/spec/references/templates/tasks-template.md b/.claude/skills/spec/references/templates/tasks-template.md index c11a823..8a69df3 100644 --- a/.claude/skills/spec/references/templates/tasks-template.md +++ b/.claude/skills/spec/references/templates/tasks-template.md @@ -30,7 +30,7 @@ _Tasks in this cohort touch independent files and can be dispatched to different - [ ] **A.1 [P]** — _short imperative title_ - **File(s):** `path/to/file.ts` - **Acceptance:** _how we know this task is done — usually one or two lines tying back to a specific AC_ - - **Leverage:** _existing helpers, prior art, mem0 memory id if applicable_ + - **Leverage:** _existing helpers, prior art, memory ID if applicable_ - **Maps to:** AC-1 - [ ] **A.2 [P]** — _title_ @@ -136,7 +136,7 @@ _TDD green phase. Write the minimum code that makes all Cohort B tests pass. Tas - Note: scanners often re-post findings on each new commit. After running `/pr-resolve`, check whether new threads appeared from auto-scanners and address those before merge. - [ ] **CLOSE-9. Archive spec** (after PR merges) - - **MUST invoke `/spec archive {{ISSUE-ID}}`** as a skill — moves folder to `archive/YYYY-MM-DD-{{ISSUE-ID}}-{{SLUG}}/` and saves mem0 summary. + - **MUST invoke `/spec archive {{ISSUE-ID}}`** as a skill — moves folder to `archive/YYYY-MM-DD-{{ISSUE-ID}}-{{SLUG}}/` and saves a milestone memory. --- diff --git a/.claude/skills/start/SKILL.md b/.claude/skills/start/SKILL.md index 69a5c1b..5366d99 100644 --- a/.claude/skills/start/SKILL.md +++ b/.claude/skills/start/SKILL.md @@ -1,13 +1,13 @@ --- name: start description: > - Lightweight session reorientation — queries sessionflow + mem0 for recent session + Lightweight session reorientation — queries SessionFlow transcripts and memory for recent session context, checks git state and active work (worktrees, stashes, open PRs, recent remote branches, version-lock claims), and surfaces the 5 most recent open issues. Use it for continuing same-day work or resuming after a short break. No indexing, no code search, no agent dispatch. Triggers: "start", "quick start", "resume", "orient me", "where were we". -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Start @@ -16,7 +16,7 @@ Lightweight session reorientation. Use this when you're continuing recent work a need to know where you left off — not when you need a full environment boot. **Under 15 seconds.** No code indexing, no agent dispatch. One Bash sweep for active work, -one Plane list, and two fast memory calls (sessionflow + mem0). +one Plane list, and two fast SessionFlow calls (transcripts + memory). > **Harness-neutral.** One master in `Devops/skill-library/skills/start/`, deployed to > `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex). Edit the master. MCP tool @@ -69,7 +69,7 @@ suspect stale context after a force-push / external merge. The injected git block cannot see other worktrees, stashes, or work another harness or machine pushed. Codex, another Claude account, or a cloud session may have work in flight -that never reached mem0 (no `/wrap` yet) and that the Step 3 keywords would not match. +that never reached SessionFlow memory (no `/wrap` yet) and that the Step 3 keywords would not match. Run this single Bash call: ```bash @@ -145,7 +145,7 @@ If Plane returns nothing or errors, note it briefly and move on. ### Step 3 — Build targeted keywords from Steps 1, 1b and 2 -Before querying sessionflow or mem0, extract 3-5 keywords from what you already learned: +Before querying transcripts or memory, extract 3-5 keywords from what you already learned: - **Issue IDs** from active work (Step 1b) first, then open issues - **Key terms** from issue titles (e.g. `tag taxonomy`, `dual-write`, `frontmatter`) @@ -265,41 +265,34 @@ starting with `agent-a` — subagent dispatches and context compaction blobs. Pr UUID-format session IDs, but keep non-Claude provider IDs when SessionFlow returns them with a valid `provider` label. -**Pass 3 — mem0** (run in parallel with Pass 0+1): +**Pass 3 — SessionFlow memory** (run in parallel with Pass 0+1): -Take `USER` and `PROJECT` from the `project.json` read in Step 0 (DEVS-92 standard): -`USER = mem0.userId` (default `"lbruton"`), `PROJECT = mem0.project` (default: `tag`, -lowercased). - -> mem0's live tool prefix is connection-specific (`mcp____*`), not a fixed -> `mcp__mem0__`. Resolve `search_memories` from the tool catalog (Claude Code: -> `ToolSearch({query: "select:search_memories"})`) and use the identifier it returns. +Take `PROJECT` from the `project.json` read in Step 0: `memory.project` (default: `tag`, +lowercased). The session-start hook already printed the three newest session summaries; this +pass finds the summaries, decisions and handoffs that match the Step 3 keywords: ``` -search_memories( +mcp__sessionflow__search_memories( query="", - top_k=10, - filters={"AND": [{"user_id": USER}, {"metadata": {"project": PROJECT}}]} + project=PROJECT, + n=10, + format="json" ) ``` > **Never filter on `agent_id`.** It names the harness that wrote the record > (`claude-code`, `codex`, …), and `/start` must see every harness's handoffs. -> **Param shape (verified 2026-09-29, hosted connector DEVS-94):** the result count is -> `top_k`, not `limit`, and there is no `enable_graph` param. Always pass `filters` with -> at least a `user_id` clause. If the live schema differs, follow the live schema, not -> this doc. - -> **Quota:** mem0 allows 1,000 retrieval calls per month across every harness. On a -> 429 / "quota exceeded", don't retry — print `⚠ mem0 read quota exhausted — context -> from sessionflow only` and continue. +When a hit needs its session, call `mcp__sessionflow__get_memory_context(memory_id, project=PROJECT)` +instead of searching transcripts again. -Merge with sessionflow findings — mem0 adds `/wrap` session summaries, decisions and handoffs. +Merge with the transcript findings — memory adds `/wrap` session summaries, decisions and handoffs. -**Degradation:** If sessionflow unreachable, use mem0 only + warn: -`⚠ sessionflow unavailable — context from mem0 only`. -If both unavailable, note it and continue. +**Degradation:** SessionFlow serves both transcripts and memory, so check which part failed. A +`memory_unavailable` error means the memory store has not started: warn +`⚠ SessionFlow memory unavailable — context from transcripts only` and continue. If the whole +server is unreachable, use the summaries the session-start hook printed (they may be from its +cache; it says so) and note it. ## Output Format @@ -337,12 +330,12 @@ nothing active. --- -**Handoff:** +**Handoff:** --- ### Last Session -<3-5 sentence recap synthesized from sessionflow turns + mem0 memories — what was worked on, decisions made, next steps> +<3-5 sentence recap synthesized from SessionFlow turns and memories — what was worked on, decisions made, next steps> --- ``` diff --git a/.claude/skills/vault-update/SKILL.md b/.claude/skills/vault-update/SKILL.md index ef0f232..353c8f1 100644 --- a/.claude/skills/vault-update/SKILL.md +++ b/.claude/skills/vault-update/SKILL.md @@ -8,7 +8,7 @@ description: > "vault update", "docvault", "update docs", "add to vault", "vault" user-invocable: true allowed-tools: Bash, Read, Write, Edit, Grep, Glob -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Vault Update diff --git a/.claude/skills/verification-before-completion/SKILL.md b/.claude/skills/verification-before-completion/SKILL.md index 56cd2be..e59519c 100644 --- a/.claude/skills/verification-before-completion/SKILL.md +++ b/.claude/skills/verification-before-completion/SKILL.md @@ -1,7 +1,7 @@ --- name: verification-before-completion description: Run verification commands before claiming work is complete. Evidence before assertions. -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Verification Before Completion diff --git a/.claude/skills/wrap/SKILL.md b/.claude/skills/wrap/SKILL.md index f7fcfa8..63bdfa1 100644 --- a/.claude/skills/wrap/SKILL.md +++ b/.claude/skills/wrap/SKILL.md @@ -2,11 +2,11 @@ name: wrap description: > End-of-session orchestrator — verifies session work, saves ONE detailed session summary to - mem0 (the big-picture record), writes day-to-day lessons to local memory and durable facts to - .context/, syncs docs, and reports Session Health. Run at end of any session, optionally after + SessionFlow memory (the big-picture record), writes day-to-day lessons to local memory and durable + facts to .context/, syncs docs, and reports Session Health. Run at end of any session, optionally after /pr-cleanup. Triggers: "wrap", "wrap up", "close session", "end of session", "done for the night", "finish up", "closing time". -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Wrap Session @@ -22,8 +22,7 @@ Without PR: /wrap Quick re-orient only: /start (no wrap needed) ``` -`/retro` was retired in DEVS-75 (2026-09-27): its mem0 `retro-learning` entries were never -read back by any session. Lessons now go to each harness's local memory, which it loads. +There is no `/retro`: lessons go to each harness's local memory, which that harness loads. ## Arguments @@ -38,14 +37,15 @@ Each memory layer has one job (DEVS-75, confirmed by the user 2026-09-27): | Layer | Holds | Written by /wrap as | |---|---|---| -| **mem0** | The bigger picture: what was worked on, when, where, and what was decided | ONE detailed session summary (Step 3) | +| **SessionFlow memory** | The bigger picture: what was worked on, when, where, and what was decided | ONE detailed session summary (Step 3) | | **Local agent memory** (Claude Code: auto-memory; Codex: `~/.codex/memories/`) | Active day-to-day operating memory: preferences, corrections, gotchas | Local memory entries (Step 4) | | **`.context/`** | Long-term foundational context for implementation work | Doc sync via chore PR (Step 5) | -| **SessionFlow + git** | Verbatim turns and exact history | Nothing — indexed automatically | +| **SessionFlow transcripts + git** | Verbatim turns and exact history | Nothing — indexed automatically | -mem0 + SessionFlow + git history together give the full picture. mem0 does not need to repeat -turn-level detail — it needs searchable anchors (issue IDs, file paths, PR numbers, decisions) -that let a later session find the right SessionFlow turns and commits. +The summary, the transcripts and git history together give the full picture. The summary does not +repeat turn-level detail — it needs searchable anchors (issue IDs, file paths, PR numbers, decisions) +that let a later session find the right turns and commits. Its source-session provenance links it to +this session's turns (`mcp__sessionflow__get_memory_context`). **Three rules that follow from this:** @@ -73,11 +73,11 @@ pwd git rev-parse --show-toplevel 2>/dev/null ``` -If `.claude/project.json` is missing, STOP — the mem0 summary would be tagged to the wrong +If `.claude/project.json` is missing, STOP — the session summary would be tagged to the wrong project. Warn and fix before continuing: ``` -⚠ project.json missing — mem0 project tag will be wrong +⚠ project.json missing — the memory project will be wrong cwd: git toplevel: Likely cause: dropped during merge/reset/worktree switch. @@ -86,8 +86,13 @@ project. Warn and fix before continuing: Offer to create `project.json` from a sibling template and proceed once resolved. Also warn if `pwd` is a subdir of a different git toplevel — same class of bug. -mem0 scope comes from `project.json` (DEVS-92 standard): `USER = mem0.userId` (default -`"lbruton"`), `PROJECT = mem0.project` (default: `tag`, lowercased). +The memory project comes from `project.json`: `PROJECT = memory.project` (default: `tag`, +lowercased). The user defaults to `lbruton`; pass `memory.userId` only when it differs. + +**Provenance** comes from the session-start hook context (the "SessionFlow memory" block at the +top of the session): `session_id`, `provider` and `agent_id`. Keep them as `SESSION_ID`, +`PROVIDER` and `AGENT`. When that block says the harness is unknown, or it is missing, there is +no provenance: leave those fields out. ### Step 1 — Observe (parallel) @@ -107,11 +112,11 @@ Hold the results in working memory for later steps. Do not display them yet. ### Step 2 — (retired: implementation log catch-up, DEVS-71) -### Step 3 — Session summary to mem0 (always) +### Step 3 — Session summary to SessionFlow memory (always) -Write **ONE** mem0 add call that gives a detailed prose account of the session. This is -the only routine mem0 write. Write it yourself from the conversation — never dispatch a -subagent to summarize. +Write **ONE** `mcp__sessionflow__add_memory` call that gives a detailed prose account of the +session. This is the only routine memory write. Write it yourself from the conversation — never +dispatch a subagent to summarize. **Content — include every anchor that applies** (they are what makes the record findable): @@ -125,35 +130,48 @@ subagent to summarize. non-obvious state or gotchas **Style:** as much concrete detail as the session warrants — plain prose, concrete nouns, -no headings or bullets (mem0 stores text, not markdown). mem0's dashboard instructions tell it -to keep a session summary as one memory; the goal is a broad, searchable "have we worked on X before?" -record shared across harnesses and developers, which then points into SessionFlow, git and -the code for depth. No lessons phrased as rules — those go to local memory in Step 4. +no headings or bullets. The record is stored verbatim; the goal is a broad, searchable "have we +worked on X before?" record shared across harnesses, which then points into the transcripts, git +and the code for depth. No lessons phrased as rules — those go to local memory in Step 4. Never put +a secret value in the text: the server rejects a write that matches its secret scanner. + +**Idempotency check first.** When `SESSION_ID` is known, look for this session's summary: + +``` +mcp__sessionflow__list_memories(project: PROJECT, type: "session-summary", + source_session_id: SESSION_ID, limit: 1, format: "json") +``` -> **mem0 tool prefix (DEVS-94):** mem0 is the official hosted MCP connector now — its live tool -> prefix is `mcp____*`, not a fixed `mcp__mem0__`. `add_memory` names the -> capability; resolve the live tool from your catalog before calling it. -> Claude Code: if `add_memory` isn't already in your tool list, resolve it with -> `ToolSearch({query: "select:add_memory", max_results: 5})` and use the prefix it returns. +A hit means this session was wrapped before. Write anyway: the same `topic_key` makes the new +summary replace the old one in place, so the record always holds the latest account. With no +`SESSION_ID`, list today's summaries for the project (`created_from` and `created_to` set to +today) and skip the write if one already covers this session. ``` -add_memory( +mcp__sessionflow__add_memory( text: "[ session – CT | | claude-code] ", - user_id: USER, agent_id: "claude-code", - metadata: { - "type": "session-summary", + project: PROJECT, + type: "session-summary", + topic_key: "session:" + SESSION_ID, # omit when SESSION_ID is unknown + source_session_id: SESSION_ID, # omit when unknown + source_provider: PROVIDER, # omit when unknown + source_project_root: "", + extra: { "source": "wrap", - "project": PROJECT, "date": "", + "branch": "", "issues": ["", ...], "handoff": - } + }, + format: "json" ) ``` -`agent_id` is the harness (`claude-code` here), never the project. The project lives in -`metadata.project` only (DEVS-92 standard). If the write fails, report it 🟡 — SessionFlow still holds the session. +`agent_id` is the harness (`claude-code` here), never the project. The result lists similar +memories; when one is an older summary this one replaces, mention it in the recap. If the write +fails (`memory_unavailable`, a secret-scanner rejection), report it 🟡 with the error code — +the transcripts still hold the session. ### Step 4 — Operating memory (local agent memory) @@ -168,7 +186,7 @@ pointer in `MEMORY.md`). Update an existing entry rather than adding a duplicate Save only prescriptive, reusable guidance. Descriptive session facts belong in the Step 3 summary, not in local memory. Skip this step when there is nothing new. -Local memory is **not** promoted to mem0 any more (DEVS-75 retired the old promotion step). +Local memory is never copied into SessionFlow memory. ### Step 5 — Documentation sync (MANDATORY when behavior changed — fix, don't warn) @@ -243,7 +261,7 @@ warnings, not actions. Compute the traffic-light color: - **🟢 Green** — all four checks pass - **🟡 Yellow** — one or more soft warnings (uncommitted files, stale worktrees, PR open - with passing checks, mem0 summary write failed, etc.) but nothing broken + with passing checks, session summary write failed, etc.) but nothing broken - **🔴 Red** — something is genuinely wrong (PR with failing checks, etc.) ### Step 7 — Print the recap to the user @@ -253,10 +271,10 @@ The recap is the *last* thing the user sees. ``` ## Session Wrapped 🟢 / 🟡 / 🔴 -**mem0 summary:** saved () — or "⚠ write failed" +**Session summary:** saved as (; "replaced" when a re-wrap) — or "⚠ write failed: " **Local memory:** (or "nothing new") **Docs:** <"chore PR #N (auto-merge)" | "shared vault updated (Devops )" | "no impact"> -**Handoff:** <"included in the mem0 summary" if --handoff, else "n/a"> +**Handoff:** <"included in the session summary" if --handoff, else "n/a"> @@ -302,7 +320,7 @@ Warning examples: - `⚠ PR #47 open with passing checks — not merged this session` - `⚠ Worktree .worktrees/swf-92 has uncommitted changes — left intact` - `⚠ Stale worktree .worktrees/swf-88 (branch merged) — run /pr-cleanup next session` -- `⚠ mem0 session summary write failed — SessionFlow still holds the session` +- `⚠ Session summary write failed (memory_unavailable) — the transcripts still hold the session` ### 🔴 Red — something is genuinely broken @@ -327,17 +345,16 @@ Even when red, the wrap still completes. Red is a *report*, not a halt. ## Rules (the short version) - **One flow, no gates.** No "STOP HERE", no phase banners, no mid-flow approval prompts. -- **Exactly one routine mem0 write per wrap:** the Step 3 session summary, tagged - `metadata.project` and `type: session-summary`. No `retro-learning` entries, no local-memory - promotion, no per-fact mem0 writes. -- **Lessons → local memory. Foundations → `.context/`. Big picture → mem0.** +- **Exactly one routine memory write per wrap:** the Step 3 session summary, with `project` and + `type: session-summary`. No local-memory copies, no per-fact memory writes. +- **Lessons → local memory. Foundations → `.context/`. Big picture → SessionFlow memory.** - **Run actions autonomously where the action is obvious.** Fast-forward pull when clean, docs sync. Anything that touches dirty user work becomes a warning, not an action. - **Session Health is the only place warnings appear.** - **The recap is the last thing the user sees.** No follow-up questions after it. - **No subagents for summarization.** You write the summary from your own context. -- **Idempotent.** Running `/wrap` twice should not write two summaries — search mem0 for a - `session-summary` for this project and date first, and skip if one covers this session. +- **Idempotent.** Running `/wrap` twice never leaves two summaries for one session: the + `session:` topic key replaces the earlier record (Step 3). - **Never auto-delete uncommitted work, ever.** Worktrees, branches, files, stashes — all off-limits to autonomous deletion. diff --git a/.codex/agents/firecrawl-scraper.toml b/.codex/agents/firecrawl-scraper.toml index 0292f06..3156019 100644 --- a/.codex/agents/firecrawl-scraper.toml +++ b/.codex/agents/firecrawl-scraper.toml @@ -1,4 +1,4 @@ -# library-version: 6b4e75d9e513 +# library-version: ce6718eb297b description = "Web scraping and research subagent. Dispatched to scrape URLs, search the web, crawl sites, and extract structured data using the self-hosted Firecrawl MCP tools. Returns distilled results to keep the main context clean." developer_instructions = """ You are a web scraping specialist. You are dispatched by the orchestrator to fetch, extract, and distill web content. Your job is to do the scraping work and return only the useful results — never dump raw HTML or full page markdown back to the caller unless explicitly asked. diff --git a/.codex/agents/pr-discover.toml b/.codex/agents/pr-discover.toml index ad38f75..f41db03 100644 --- a/.codex/agents/pr-discover.toml +++ b/.codex/agents/pr-discover.toml @@ -1,4 +1,4 @@ -# library-version: 6b4e75d9e513 +# library-version: ce6718eb297b description = "PR discovery and pre-analysis agent. Gathers all PR review threads, Codacy findings, runs code review subagents, and returns a structured findings report with file-based thread clusters. Dispatched by /pr-resolve to isolate the heavy data-gathering phases from main context." developer_instructions = ''' # PR Discovery & Pre-Analysis Agent diff --git a/.codex/agents/pr-thread-resolver.toml b/.codex/agents/pr-thread-resolver.toml index 50da39f..b30826e 100644 --- a/.codex/agents/pr-thread-resolver.toml +++ b/.codex/agents/pr-thread-resolver.toml @@ -1,4 +1,4 @@ -# library-version: 6b4e75d9e513 +# library-version: ce6718eb297b description = "Resolves a cluster of PR review threads grouped by file/topic. Dispatched in parallel by pr-resolve for independent clusters. Re-fetches thread IDs via GraphQL before acting to handle intervening rebases. Makes code fixes, generates replies, and returns results for the orchestrator to post." developer_instructions = """ You are a PR thread cluster resolver. You receive a cluster of classified review threads (all on the same file or topic) and execute the resolutions — fixing code, generating replies, or both. Multiple clusters run in parallel, but within your cluster you handle threads sequentially to avoid edit conflicts. diff --git a/.vale/styles/Prose/README.md b/.vale/styles/Prose/README.md index 0d6ce57..f1dea6b 100644 --- a/.vale/styles/Prose/README.md +++ b/.vale/styles/Prose/README.md @@ -1,5 +1,5 @@ --- -library-version: 6b4e75d9e513 +library-version: ce6718eb297b --- # Prose