recallium 1.2.6 → 2.0.8

package/bin/skills/antigravity/team/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: team
+description: Answers questions about the people and the shared work on an enterprise Recallium deployment - who is on which team, what the team has been doing across the projects it owns, what is pending there, and which teammate wrote what. Use when the user asks "who's on my team", "what has the team been working on", "what's pending across our projects", "what did a teammate do last week", or before filtering a search by author; on a community deployment these tools are absent by design, not broken.
+---
+
+# Team
+
+## Quick start
+
+```
+list_team_members()                                   # every team you belong to; team_name="core" narrows
+team_recap(days_back=7)                               # all projects your team owns; project_name="my-api" narrows
+team_recap(project_name="my-api", include_tasks=True)
+search_memories(query="...", project_name="__all__", author_email="<exact email from list_team_members>")
+```
+
+## Why
+
+Team tools are the only view that crosses projects and people. `team_recap`
+aggregates recent memories and pending tasks over the projects the team OWNS
+and carries no per-user working state; `session_recap` is the personal view.
+The author filter on `search_memories` is an exact match, so the email must
+come from `list_team_members`, never from recollection.
+
+## Workflow
+
+1. **Gate:** enterprise. If the tool is not in the tool list, say so and fall
+   back to `session_recap` / `search_memories`; do not report it as broken.
+2. "Who is on the team" -> `list_team_members`. Takes no `project_name`;
+   `team_name` is a case-insensitive substring filter.
+3. "What has the team done" -> `team_recap`, 1-30 days back; narrow with
+   `project_name` when one project is meant.
+4. "What did X do" -> `list_team_members` for the exact email, then
+   `search_memories(author_email=..., project_name="__all__")`, because a
+   teammate's memories span projects.
+5. Patterns rather than activity ("what keeps going wrong across the team")
+   -> `get_insights` (see `resume`).
+6. **Gate:** report; store nothing. Someone's activity is not a new finding.
+
+## Anti-patterns
+
+WRONG: guessing a teammate's email for `author_email`.
+RIGHT: `list_team_members` first; the filter is exact.
+
+WRONG: `team_recap` for "where did I leave off".
+RIGHT: `resume`; the team view has no working state.
+
+## Checklist
+
+- [ ] Enterprise confirmed, or the fallback used
+- [ ] Right scope: every team project, or one
+- [ ] Author email taken from the tool, not recalled
+
+## See also
+
+`resume` (the personal view), `recall` (search by author), `project` (links
+between projects), `recallium-tools` (edition gates).

package/bin/skills/antigravity/verdict/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: verdict
+description: Records one agent's judgment of another agent's output - a design, decision, answer, or memory - as a Recallium verdict on that target, so a parent agent can trust it without re-verifying. Use when you are acting as reviewer, critic, or judge of a specific memory and have reached a position on it; a verdict always names its target and is never stored as progress or a note.
+user-invocable: false
+---
+
+# Verdict
+
+## Quick start
+
+```
+expand_memories(memory_ids=["<target-uuid>"])
+store_verdict(target_memory_id="<target-uuid>",
+              decision="accept",            # accept | refute | revise
+              confidence=0.8,               # your certainty IN THIS JUDGMENT
+              reasoning="<self-contained evidence>",
+              project_name="my-api", workstream_slug="auth-hardening")
+```
+
+## Why
+
+A verdict is the convergence primitive: it is how a subtree of agents collapses
+to one trusted result. A false `accept` propagates unverified up the tree and
+poisons every ancestor that trusts it; a false `refute` costs one more round.
+So when in doubt, prefer a low-confidence `refute`. `confidence` is your
+certainty in the judgment, not the quality of the target: a confident refute is
+confidence 0.9 with decision `refute`.
+
+## Workflow
+
+1. **Gate:** `target_memory_id` is required and must be a real memory you can
+   see. Expand it first; judge what it says, not what you remember of it.
+2. Reach a position: `accept` (stands, build on it), `refute` (wrong or
+   unsound, do not build on it), `revise` (close; the changes are named in
+   your reasoning).
+3. Put the full evidence in `reasoning`. A parent may act on it without
+   re-checking, so it must be self-contained and must not present unverified
+   claims as established.
+4. One verdict per (you, target). A changed position is a new verdict that
+   supersedes your earlier reasoning; never edit the old one.
+5. Anchor it to the same `workstream_slug` as the target.
+
+## Anti-patterns
+
+WRONG: a review stored as `progress` or `note`.
+RIGHT: `store_verdict`; progress is a state timeline, not a judgment.
+
+WRONG: a verdict with no target, "the approach is fine".
+RIGHT: a verdict OF a specific memory UUID.
+
+WRONG: `accept` at confidence 0.5 because nothing looked wrong.
+RIGHT: if you are not sure, a low-confidence `refute` and the reason.
+
+## Checklist
+
+- [ ] Target UUID real and expanded
+- [ ] Decision and confidence set independently
+- [ ] Reasoning self-contained; no unverified claims as fact
+- [ ] Anchored to the target's workstream
+
+## See also
+
+`design` (what usually gets judged), `decide`, `capture`.

package/bin/skills/claude-code/capture/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: capture
+description: Stores one durable why in Recallium - a learning from research or from a user correction, a constraint you hit, an experiment's numbers, a reusable snippet or runbook - behind the value gate, with its files and edges. Use when you found something out that a teammate could not reconstruct from the code and git log alone, or the user corrected you on how the system works; and use it to decide NOT to store when nothing new is being added - zero writes in a turn is valid.
+---
+
+# Capture
+
+## Quick start
+
+```
+store_memory(content="## Learned: <title>\n**Claim:** ...\n**Evidence:** ...\n**Consequence:** what to do differently",
+             project_name="my-api", workstream_slug="auth-hardening",
+             memory_type="learning", related_files=["src/auth/token-manager.ts"],
+             relationships=[{"target": "<design-uuid it bears on>", "type": "related"}])
+```
+
+## Why
+
+Two questions get confused, so separate them. **Cadence** asks when a real
+finding is written: one memory per finding as it lands, never batched. **The
+value gate** asks whether there is a finding at all: what NEW durable
+information does this add beyond the workstream already loaded? If none, skip.
+A second copy of the same state competes with the first in every future search,
+so storing it twice makes the original harder to find.
+
+## Workflow
+
+1. Gate it. Restated state, anything reproducible from a command, a paraphrase
+   of the diff, what you are about to do next: not a memory. The last one is
+   `set_working_state`.
+2. Type, first match wins: chose X over Y -> `decision` (`decide`) | imposed
+   bound -> `constraint` | ran a method, have numbers -> `experiment` | defect
+   -> `bugfix` (`investigate`) | architecture -> `design` (`design`) | reusable
+   code or command -> `code-snippet` | how to operate or roll back -> `runbook`
+   | durable claim about behaviour, incl. a user correction -> `learning` |
+   else -> `note`. `task`, `rule`, `verdict` have their own tools.
+3. **Gate:** `workstream_slug` is mandatory; none yet -> `start-work`.
+4. Search the workstream for what this builds on, replaces, bounds or
+   contradicts; attach those UUIDs. `supersedes` means the target is now WRONG.
+   `expand_memories` a hit before you cite it: an edge to a memory you have
+   not read is a guess.
+5. `related_files`: every file read or written. In a chat with no repository,
+   leave it empty; never invent paths.
+6. Read the store response: "unanchored" -> repair now with `modify_memory`;
+   a suggested file or edge -> take it.
+7. `importance_score` 0.9 / 0.7 / 0.5 / 0.3, auto-scored if omitted.
+
+## Anti-patterns
+
+WRONG: a code-related memory with empty `related_files`.
+RIGHT: every file touched, so `search_memories(file_path=...)` finds it later.
+
+## Checklist
+
+- [ ] Value gate applied; could this have been zero writes?
+- [ ] Canonical type, slug, files, at least one edge
+- [ ] Store response read; anchor and suggestions acted on
+
+## See also
+
+`investigate`, `finish` (the checkpoint half), `decide`, `design`, `curate`, `rule`.

package/bin/skills/claude-code/curate/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: curate
+description: Corrects, retires, or closes what Recallium already holds - a wrong memory superseded, a duplicate or mistaken memory inactivated, a stale task inactivated, a workstream marked shipped or abandoned when the effort ends. Use when the user says "that's wrong", "forget that", "we dropped that approach", when a PR merges or a branch is abandoned, or when a search returns two memories saying the same thing; never delete, and store nothing new unless the correction itself is a finding.
+---
+
+# Curate
+
+## Quick start
+
+```
+expand_memories(memory_ids=["<uuid>"])                                   # read before touching
+modify_memory(memory_id="<uuid>", action="update", content="...", related_files=[...])
+modify_memory(memory_id="<uuid>", action="inactivate", reason="duplicate of <uuid>")
+modify_memory(memory_id="<workstream-uuid>", action="update", status="shipped")   # or "abandoned"
+```
+
+A content edit gives the memory a new id; use the id the response names.
+
+## Why
+
+The value gate has two halves. Storing only new durable information is one; keeping
+what is stored true is the other. A wrong memory that stays visible is worse than
+none: the next agent acts on it. A duplicate competes with the original in every
+future search, so cleanup restores findability the gate was protecting. Nothing is
+ever deleted: `inactivate` keeps the row for undo, `supersedes` keeps the chain,
+and an abandoned workstream is information about a dead end.
+
+## Workflow
+
+1. `expand_memories` the target first; judge what it says.
+2. Pick the operation by what is wrong:
+   - factually wrong, but the shape is right -> `modify_memory(action="update")`
+     with new `content`; additive for `tags`, `related_files`, `relationships`.
+   - superseded by a better decision, design, learning or runbook -> a NEW
+     memory with a `supersedes` edge; the old one drops out of search and
+     stays in the chain. **Gate:** never supersede `progress`.
+   - duplicate or mistaken -> `modify_memory(action="inactivate", reason=...)`.
+     `reason` is required. `reactivate` undoes it.
+   - unanchored -> `modify_memory(..., workstream_slug=...)`.
+3. Effort over: `modify_memory(memory_id="<workstream-uuid>", action="update",
+   status="shipped")` on merge, `"abandoned"` on a dead end. Close its tasks:
+   `update_task(status="completed")` for done, `update_task(status="inactive",
+   reason=...)` for stale or duplicate; `task_id` takes a list.
+4. A user correction is a `rule` (preference) or a `learning` (fact); either
+   may also mean a wrong memory to fix here.
+
+## Anti-patterns
+
+WRONG: editing a decision in place when the choice changed.
+RIGHT: a new decision with `supersedes`; the chain is the history.
+
+WRONG: leaving a shipped effort `active`.
+RIGHT: status `shipped` at merge; the roster stays honest.
+
+## Checklist
+
+- [ ] Target expanded before any change
+- [ ] Right operation: update, supersede, inactivate, re-anchor
+- [ ] Nothing deleted; every inactivation has a reason
+- [ ] Workstream status and its tasks closed when the effort ended
+
+## See also
+
+`capture`, `decide`, `finish`, `rule`, `recall`.

package/bin/skills/claude-code/decide/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: decide
+description: "Compare implementation alternatives and recommend a choice with its rationale. Use when the user asks which option to choose, including a small or previously settled choice; the workflow determines whether new reasoning or storage is needed. Use design to form an architecture or approach, and recall to retrieve an earlier decision without reconsidering it."
+---
+
+# Decide
+
+## Quick start
+
+```
+r = start_thinking(goal="Choose the auth strategy for the mobile app",
+                   project_name="my-api", workstream_slug="auth-hardening")
+add_thought(sequence_id=r.sequence_id, thought="...", thought_type="hypothesis")
+add_thought(sequence_id=r.sequence_id, thought="...", thought_type="reasoning")
+add_thought(sequence_id=r.sequence_id, thought="...", thought_type="conclusion")
+```
+
+## Why
+
+A `conclusion` thought auto-stores a `decision` memory, born anchored to the
+workstream passed at `start_thinking`, so the rationale is captured with the
+choice instead of reconstructed from the diff later. The sequence is the audit
+trail: the rejected options and why they lost are the reusable half. A sequence
+left open stores nothing; the Stop hook will say so.
+
+## Workflow
+
+1. **Gate:** is there a real alternative? No trade-off -> not a decision; use
+   `capture` with the right type, or store nothing.
+2. Retrieve prior decisions and constraints. If an applicable decision already settles the request, explain it and stop without starting a sequence or storing a duplicate. A constraint may have removed an option.
+   For a routine choice with no durable project consequence, answer with the relevant trade-off and store nothing. Use a thinking sequence for a new consequential choice.
+3. `start_thinking(goal=..., project_name=..., workstream_slug=...)`.
+   **Gate:** pass `workstream_slug` here; the auto-stored decision inherits
+   it. The server warns if you omit it; pass it now rather than backfilling.
+4. `add_thought` per step: `observation`, `hypothesis` (the options),
+   `question`, `reasoning` (what rules options out), `analysis`, `branch`,
+   `conclusion` (closes and stores; nothing can be added afterwards).
+5. The conclusion states Context / Options / Chosen and why / Consequences.
+6. Take its UUID. Edge it to the constraint that bounded it; put it in the
+   `Recallium-Memory:` trailer of the commit that implements it (`finish`).
+7. A later, better choice does not edit this one: a new `decision` with
+   `supersedes` pointing at it.
+
+## Anti-patterns
+
+WRONG: `start_thinking` without `workstream_slug`, then backfilling.
+RIGHT: pass the slug at `start_thinking`; the conclusion is born anchored.
+
+WRONG: recording only the option you picked.
+RIGHT: the rejected options and why they lost.
+
+## Checklist
+
+- [ ] A real alternative existed
+- [ ] Prior decisions and constraints searched
+- [ ] `workstream_slug` passed at `start_thinking`
+- [ ] Conclusion names options, choice, rationale, consequences
+- [ ] UUID captured for edges and the commit trailer
+
+## See also
+
+`recall`, `design`, `capture`, `finish`, `verdict`.

package/bin/skills/claude-code/design/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: design
+description: "Form or review an architecture, API, data model, module structure, or implementation approach, using the project's recorded constraints. Use when asked to propose how a system should be organized or built, even before a plan exists. Use decide for choosing between specific alternatives; store a design only when a new durable proposal has formed."
+---
+
+# Design
+
+## Quick start
+
+```
+store_memory(content="## Design: <title>\n**Problem:** ...\n**Shape:** ...\n**Why this shape:** ...\n**Files it will touch:** ...\n**Open questions:** ...",
+             project_name="my-api", workstream_slug="auth-hardening",
+             memory_type="design",
+             related_files=["src/auth/token.ts", "src/auth/refresh.ts"],
+             relationships=[{"target": "<constraint-uuid>", "type": "related"},
+                            {"target": "<old-design-uuid>", "type": "supersedes"}])
+search_memories(query="<design title>", project_name="my-api", memory_type="verdict")
+```
+
+## Why
+
+A design stored before the edits, with the files about to change as
+`related_files`, preserves the rationale the edits will implement. Every file in
+that list becomes a door back to the design: the next agent to open one meets
+the plan before diverging from it. A `.md` brief cannot do this, and the hook
+layer nudges you the moment you write one.
+
+## Workflow
+
+1. Form or review the requested design: identify the requirements and constraints, then explain the proposed responsibilities, interfaces, and trade-offs. A design request can begin before any plan exists.
+   **Storage gate:** record the shape chosen and why only when it adds a new durable proposal beyond the loaded workstream; a restatement or description of the diff stores nothing.
+2. `recall` first: an earlier design or decision may cover this, and a
+   `constraint` may bound it. `expand_memories` them and read them before
+   reading the code they describe: a summary line is not the memory. Keep
+   their UUIDs.
+3. Store one `design` with `workstream_slug`, `related_files` (every file it
+   will touch, not only those touched so far) and edges: `related` to what it
+   builds on and to the constraint that bounds it, `supersedes` only if the
+   earlier design is now wrong.
+4. Capture the full UUID; cite it in `create_task` and the commit trailer.
+5. Briefing a subagent? Pass that full UUID and the slug in its prompt and tell
+   it to `expand_memories` the UUID first. Never a file.
+6. Reviewers judge it with `store_verdict` on the design's UUID (`verdict`).
+   Before building on a reviewed design, read its verdicts: a `refute` or
+   `revise` means a new `design` with `supersedes`, not an edit in place.
+
+## Anti-patterns
+
+WRONG: `Write("DESIGN.md", ...)` then start editing.
+RIGHT: `store_memory(memory_type="design", ...)`; the memory is the artifact.
+
+## Checklist
+
+- [ ] Real design, not a diff summary
+- [ ] Prior designs, decisions, constraints searched, read in full, and edged
+- [ ] Files it will touch listed; full UUID captured
+- [ ] Verdicts read before building on a reviewed design
+
+## See also
+
+`decide`, `verdict`, `start-work`, `capture`, `curate`, `handoff`.

package/bin/skills/claude-code/finish/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: finish
+description: "Assess or close a piece of work when the user requests completion, a tracked task reaches its endpoint, or a commit needs its checkpoint and memory links. Verify the actual state before recording closure. Completing a routine edit or running a check alone does not trigger this workflow. Already-closed work needs no duplicate checkpoint."
+---
+
+# Finish
+
+## Quick start
+
+```
+git commit -F <body-file> --trailer "Recallium-Memory: <uuid>, <uuid>"   # why-UUIDs only
+
+# the commit CLOSES a tracked task → the task close is the checkpoint, no progress:
+update_task(task_id="<uuid>", memory_ids=["<why-uuid>", ...], status="completed")
+
+# no task closes → ONE progress carries the SHA back:
+store_memory(content="## Landed: <title>\n**SHA:** <full>\n**What it achieved:** ...\n**Verified by:** ...\n**Next:** ...",
+             project_name="my-api", workstream_slug="auth-hardening",
+             memory_type="progress", tags=["commit:e436e0a4"],
+             related_files=["<files in the commit>"],
+             relationships=[{"target": "<why-uuid>", "type": "related"}])
+
+set_working_state(project_name="my-api", content="<only what is still open — never the checkpoint>")
+```
+
+## Why
+
+`git log` records what changed; Recallium records why. The trailer carries the
+why-UUIDs forward from the commit; the `commit:`-tagged progress carries the SHA
+back, so a blame line reaches the decision and a decision reaches the code.
+Progress is a timeline, not a chain: one memory per state worth resuming from,
+never superseded, never restated. The task link, not a tag, anchors task
+progress — and when a commit closes a task, that link IS the checkpoint:
+a progress memory on top of it says the same thing twice. Working state is
+not a checkpoint either: it holds what is left, never what was just stored.
+
+## Workflow
+
+1. Verify the requested completion against the code, checks, and recorded scope. If work remains, report it as incomplete; do not mark it shipped or infer abandonment from a failed completion check. Use abandoned only when the user explicitly ends or drops the effort. Already-closed work needs no duplicate checkpoint. If an approval blocks a status change, report the actual unchanged state.
+2. Before committing, the why-memories must exist (see `capture`, `decide`,
+   `design`). Missing one? Store it now. Collect the UUIDs.
+3. `git commit --trailer "Recallium-Memory: ..."`. **Gate:** use `--trailer`,
+   not hand-typing; one blank line inside the trailer block demotes it to body
+   text. Verify with `git interpret-trailers --parse`. Trivial change? Say so
+   in the body and skip the trailer. The `prepare-commit-msg` hook from
+   `recallium --install-git-hook` self-heals an orphaned trailer where installed.
+4. **Gate — one checkpoint, not two.** Does this commit close a tracked
+   task? Then close it in one call, `update_task(task_id=..., memory_ids=[the
+   why-UUIDs], status="completed")` (`task_id` takes one UUID or a list), and
+   store NO progress: the completed task, linked to the why-memories, is the
+   checkpoint. No task closes? Then ONE `progress`: full SHA in content, tag
+   `commit:<short-sha>`, `related_files` = `git diff-tree --no-commit-id
+   --name-only -r <sha>`, `related` edges to the trailer UUIDs; verification
+   evidence lives here. Not a commit? Still one progress if the state changed.
+5. `set_working_state` with ONLY what is left over after that last store or
+   task close — what is mid-way, what is next, which writes are pending or
+   unknown. Never restate the checkpoint (its SHA, files or evidence): the
+   working state is a resume note, not a second copy of the memory.
+
+## Anti-patterns
+
+WRONG: UUIDs mentioned in the progress memory's prose.
+RIGHT: real `relationships` edges; prose is not traversable.
+
+WRONG: `supersedes` on an older progress memory.
+RIGHT: never; an old checkpoint is history, not an error.
+
+WRONG: a task closed with `memory_ids` AND a `progress` for the same commit.
+RIGHT: one checkpoint — the task close when a task closes, the progress otherwise.
+
+WRONG: `set_working_state` repeating the SHAs and evidence just stored.
+RIGHT: the working state names only what is still open.
+
+## Checklist
+
+- [ ] Why-memories exist; trailer parse-verified
+- [ ] ONE checkpoint: the task closed with `memory_ids` when a task closes, else one progress (full SHA, `commit:` tag, commit's files, edges)
+- [ ] Working state holds only what is left open — not the checkpoint
+
+## See also
+
+`capture`, `decide`, `design`, `start-work`, `handoff`.

package/bin/skills/claude-code/handoff/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: handoff
+description: "Preserve a continuation point when unfinished work is explicitly paused, parked, or transferred to another session or agent, or when compaction or /clear is imminent. Use working state for the immediate continuation and a memory for a durable brief. Finishing a routine response or updating working state alone does not trigger this workflow."
+---
+
+# Handoff
+
+## Quick start
+
+```
+set_working_state(project_name="my-api",
+                  content="branch / workstream / in flight / parked / next action / open questions")
+
+# Subagent brief: a memory, never a file
+store_memory(memory_type="design", content="<the full brief>",
+             project_name="my-api", workstream_slug="auth-hardening",
+             related_files=[...])
+# then in the subagent prompt: "expand_memories(['<FULL uuid>']) first"
+```
+
+## Why
+
+Working state is the note to your next turn: temporary, plaintext, overwritten
+on every call, not searchable and not a memory. A brief is the opposite:
+durable, workstream-anchored, surfaced at session start. A `HANDOFF.md` feels
+faster than an MCP round-trip and is permanently lossy: a repo file is invisible
+to the next session unless someone recalls its path, and the hook layer nudges
+you the moment such a file is written.
+
+## Workflow
+
+1. Confirm an actual pause, compaction, or transfer of unfinished work. A routine scratch update after an edit uses `set_working_state` directly and does not require this workflow.
+   For a handoff, immediate continuation context goes in working state; analysis, design, scope, and exclusions the receiver must act on go in a memory.
+2. `set_working_state(project_name=..., content=...)`. **Gate:** the parameter
+   is `content`; the call overwrites, so write the whole note. Write it after
+   each step that changes "resume here", before compaction or `/clear`, and at
+   session end. The Stop hook asks for it when the context is filling.
+3. Shape: branch, workstream slug, in flight, parked, next action, open
+   questions.
+4. For a subagent: `store_memory(memory_type="design", ...)` with the slug and
+   `related_files`; capture the FULL UUID. **Gate:** prefixes collide and do
+   not survive compaction.
+5. In the subagent's prompt, pass that UUID and the slug, and instruct it to
+   `expand_memories` it first. Have it hand results back the same way.
+6. Session end: every memory this session has a slug, files and an edge; every
+   commit has its trailer and its checkpoint (a `commit:`-tagged progress, or the task it closed); every worked task
+   is linked. Then `session_recap` if the user wants a summary.
+
+## Anti-patterns
+
+WRONG: `Write("HANDOFF.md", brief)` then `Task(prompt="read HANDOFF.md")`.
+RIGHT: `store_memory(...)` then pass the UUID with "expand_memories it first".
+
+## Checklist
+
+- [ ] Working state written (branch, slug, in flight, next action)
+- [ ] Brief stored as a memory; no `.md` authored
+- [ ] Full UUID passed with an expand-first instruction
+- [ ] Session-end hygiene check done
+
+## See also
+
+`resume` (the other end), `finish`, `design`, `capture`.

package/bin/skills/claude-code/investigate/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: investigate
+description: Runs a bug report, failing test, or unexplained behaviour to its root cause with Recallium's trail - searches for a prior fix by symptom and by file, reasons through the cause as a thinking sequence when it is not obvious, and stores the root cause as a bugfix BEFORE the fix is written. Use when the user says "this is broken", "why does this fail", pastes a stack trace or error, or a test goes red — even when the cause looks obvious, invoke this and search for the prior fix first; if the cause is already stored, fix it and store nothing new. Applies to code you wrote this session, uncommitted or not — fresh code is where a standing ruling is most likely to have been missed, and "I know why" is not a reason to skip the search.
+---
+
+# Investigate
+
+## Quick start
+
+```
+search_memories(query="<the symptom in a sentence>", project_name="my-api",
+                file_path="%token-manager.ts%")          # by symptom AND by file
+r = start_thinking(goal="Why does refresh fail after 24h", project_name="my-api",
+                   workstream_slug="auth-hardening")     # only when the cause is not obvious
+add_thought(sequence_id=r.sequence_id, thought="...", thought_type="conclusion")
+store_memory(memory_type="bugfix", content="## Fixed: <title>\n**Problem:** ...\n**Root cause:** ...\n**Solution:** ...\n**Testing:** ...", ...)
+```
+
+## Why
+
+Debugging is the most frequent moment a coding agent has, and it is where memory
+pays most: a bug that looks new is often one that was fixed before, in a file a
+teammate touched, for a reason a stored bugfix already names. The root cause is stored before the fix because the fix
+rewrites the evidence: once the code changes, the diagnosis can only be
+reconstructed from the diff, which is the failure this whole system exists to
+prevent.
+
+## Workflow
+
+1. **Gate:** `recall` first, by symptom and by `file_path`. A prior `bugfix`
+   or `constraint` may already explain it. If it does, apply it and skip to
+   `finish`; a second copy of a stored cause is noise.
+   `expand_memories` the hits and read them before reading code: the
+   `design` says how the thing is meant to behave, the `bugfix` what broke
+   before. A summary line is not the memory.
+   Search a third time by the thing the failing test asserts — a key
+   binding, a path, a flag, a constant — not only the symptom. If a hit says
+   the current behaviour was a deliberate ruling, the fix must honour the
+   ruling, and that reversal is a `bugfix` however small the code change.
+   A batch of failures is triaged, not skipped: routine ones store nothing;
+   any fix that reverses a choice you made earlier this session, or that an
+   existing test's comment predicted, gets its own `bugfix`.
+2. Reproduce and narrow. Cause obvious? Go to step 4. Not obvious? Open a
+   thinking sequence with `workstream_slug`; `observation` for facts,
+   `hypothesis` per candidate cause, `reasoning` for what rules each out,
+   `conclusion` when one stands (it auto-stores a `decision`).
+3. Long investigation? `set_working_state` with what was ruled out so far.
+4. **Gate:** store the `bugfix` with the root cause BEFORE editing: Problem,
+   Root cause, Solution and why this approach, Testing; `related_files` where
+   the defect lived; a `related` edge to the design it exposed a gap in.
+   **Quota warning or not.** A store that comes back refused is reported as
+   refused; a store never attempted because a warning made it look
+   pointless is the anti-pattern below.
+5. Fix, verify, then `finish`: the bugfix UUID goes in the commit trailer.
+6. An imposed limit is a `constraint`; a claim about behaviour is a `learning`.
+
+## Anti-patterns
+
+WRONG: the search returns the design of the feature; the code is read first
+to find out how it is meant to behave.
+RIGHT: `expand_memories` the design; the code is opened to confirm it, or to
+find where it departs from it.
+
+WRONG: editing until the test passes, then writing "fixed X" as the memory.
+RIGHT: the root cause stored first; the memory says why it broke, not that it passes.
+
+WRONG: "these are my own red tests from an hour ago, I know the causes" — fixing
+all eight inline, storing nothing, and only an old test's comment catching the
+ruling you reversed.
+RIGHT: the same eight triaged; seven store nothing; the one that reversed a
+ruling is a `bugfix` stored before its edit, quota warning or not.
+
+## Checklist
+
+- [ ] Searched by symptom, by file, and by what the failing test asserts
+- [ ] Hits expanded and read before any source file was opened
+- [ ] A batch triaged: every reversal of a ruling or of your own earlier choice has its own bugfix
+- [ ] Thinking sequence concluded, or never opened
+- [ ] Root cause stored before the fix, with files and an edge
+- [ ] Bugfix UUID in the commit trailer
+
+## See also
+
+`recall`, `decide`, `capture`, `finish`, `handoff`.

package/bin/skills/claude-code/project/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: project
+description: Creates, inspects, retires, or links Recallium projects - the metadata containers that scope memories - and keeps project administration out of memories. Use when the user says "set up a project for this repo", "which projects do we have", "link this repo to the API project", "unlink those", "retire that old project", "restore it", or when a summon reports an unknown project; goals, roadmaps and decisions never go on a project, they are memories under a workstream.
+---
+
+# Project
+
+## Quick start
+
+```
+list_projects(include_inactive=False)                     # paginated; True shows retired ones
+get_project(project_name="my-api")                        # name, UUID, description, counts, status, links
+create_project(project_name="my-api", description="...")  # idempotent: an existing project is returned unchanged
+update_project(project_name="my-api", description="...")  # or status="inactive" (+ reason) / status="active"
+link_projects(project_name="my-api", target_project_name="my-web", relationship="sibling")
+unlink_projects(project_name="my-api", target_project_name="my-web")
+```
+
+## Why
+
+A project is grouping and scope, nothing more: a kebab-case name, a one-line
+description, a lifecycle status, and links. Everything that describes the work
+(goals, roadmap, decisions, learnings) is a memory under a workstream, where
+search finds it; a project holds no document. A link is search visibility:
+each project's memories become reachable one hop from the other.
+
+## Workflow
+
+1. `list_projects` before creating: names are lowercase kebab-case and the
+   workspace root is the default name, so the project may exist already.
+2. Create with a description worth reading later. `create_project` never
+   modifies an existing project; `update_project` does.
+3. Two repos, one effort? `link_projects` ONCE per pair. `sibling` is
+   order-agnostic; `parent` / `child` read source -> target. Re-linking the
+   same pair overwrites it. There is no narrower link, so do not link
+   projects that should stay separate.
+4. Retire: `update_project(status="inactive", reason=...)`. The row, its
+   memories and links are kept; `status="active"` restores. There is no
+   delete. A shipped workstream is `curate`'s job, not a project change.
+5. **Gate:** store nothing; administration is not a finding.
+
+## Anti-patterns
+
+WRONG: `create_project(description="Goals: ... Roadmap: ...")`.
+RIGHT: a `design` or `decision` memory under a workstream; one line here.
+
+WRONG: linking two projects so a teammate can see the other's memories.
+RIGHT: links are project-to-project visibility; people are `team`'s matter.
+
+## Checklist
+
+- [ ] Listed before creating; name is kebab-case
+- [ ] One link per pair; direction right for parent / child
+- [ ] Retired with a reason, never deleted
+- [ ] Nothing stored as a memory
+
+## See also
+
+`start-work` (the workstream inside it), `resume` (switching project), `curate`,
+`team`, `recallium-tools`.