Use Snipara with AI agents

# AGENTS.md

## Snipara Context Workflow

This project uses Snipara Hosted MCP for project context and reviewed memory.

- Endpoint: https://api.snipara.com/mcp/YOUR_PROJECT_SLUG
- Auth: use `SNIPARA_API_KEY` from the environment. Never commit keys.
- For Codex, expose the endpoint as a streamable HTTP MCP server and load the
  key from `SNIPARA_API_KEY`.
- At the start of every new thread, validate hosted MCP with a tool-oriented
  call such as `snipara_settings`, `tools/list`, or a lightweight
  `snipara_context_query`. Do not treat empty MCP resources/templates as an
  outage because Snipara may be tool-only.
- If a session appears to expose only a subset of expected Snipara tools, call
  `snipara_help(list_all=true)` and compare exact tool names before concluding
  that a tool is unavailable. Do not infer absence from one broad discovery
  pass or a ranked tool-search result.

Agent task lifecycle:

1. Start every new thread by validating hosted MCP availability, then use
   project-scoped `snipara_recall` and a targeted `snipara_context_query` before
   falling back to local documentation search.
2. Use `snipara_context_query` for docs, project truth, architecture notes, runbooks, and narrative source material.
3. When `snipara_context_query` returns `answer_pack`, treat it as the first-pass response plan: use its source facts, caveats, source map, and verification checklist before drafting claims.
4. Use `snipara_get_chunk` to load cited source sections returned by reference-based queries before relying on precise wording.
5. For coding tasks, choose a workflow mode before editing: LITE for small
   single-phase changes, FULL managed workflow for multi-file, risky,
   release/deploy, architectural, compaction-prone, or future-maintainer-sensitive
   work.
6. Use whichever structural code graph tools are exposed in the current session
   for callers, imports, neighbors, and path questions. Tool exposure can vary.
7. On paid Context plans, use `snipara_code_symbol_card` for agent-ready symbol
   context. For impact, use `snipara-companion code impact` first when
   companion is installed; it selects the local overlay for dirty/ahead worktrees
   and hosted MCP for clean indexed code. Use hosted `snipara_code_impact` only
   when companion is unavailable or after push/reindex for canonical graph impact.
8. Use `snipara_plan` for complex work in any plan when exposed; reserve
   `snipara_decompose` for FULL-mode work when the hosted server exposes it.
9. When the LLM has produced a visible multi-phase plan and `snipara-companion`
   is installed, keep the machine plan in JSON and run
   `snipara-companion workflow start --goal "<goal>" --plan-file <plan_json_file>`.
   Use `workflow phase-start` / `workflow phase-commit` per phase, and after
   compaction run `workflow resume` then `workflow phase-start` before editing
   again.
10. Use local file reads, `rg`, git commands, and test commands for exact edits,
    current working-tree state, and verification.
11. Treat every `snipara_code_*` response as indexed context: check indexed
    commit SHA, indexing time, included file sample, coverage, freshness warnings,
    and sync guidance before relying on it. If `git status --short` is dirty,
    warn that the indexed graph may not include local edits.
12. If `snipara-companion` is installed and local commits or a dirty worktree
    matter, use `snipara-companion code callers/imports/neighbors/shortest-path/impact`.
    It auto-selects hosted MCP or the local overlay and reports `sourceSelection`.
    Treat local overlays as non-canonical; they do not change hosted
    `snipara_code_*` answers until pushed code is reindexed.
13. Use Snipara Sandbox only when sandboxed execution, repeatable validation, or
    isolated transformations materially help.
14. If a broad query is slow, retry once with a narrow keyword query before
    falling back to local search.
15. When generated hooks are enabled, `snipara-companion pre-tool`, `post-tool`,
    and `stuck-guard status` provide runtime Rescue Pack checks for repeated
    failures, empty searches, and risky workflows.
16. End each substantial phase with `snipara_end_of_task_commit` or
    `snipara-companion workflow phase-commit` when companion manages the plan.
    End the whole managed workflow with `snipara-companion final-commit`.
17. Use `snipara_remember_if_novel` for one reusable memory while avoiding
    duplicates, and use `snipara_remember` for explicit direct memory writes.
18. When remembered knowledge is obsolete or replaced, use
    `snipara-companion memory invalidate <memory-id>` or
    `snipara-companion memory supersede <old-memory-id> <new-memory-id>`
    when companion is installed; otherwise use hosted `snipara_memory_invalidate`
    or `snipara_memory_supersede`.
19. Do not store secrets, tokens, passwords, private keys, raw logs, transient
    command output, or unreviewed guesses in memory.

# CLAUDE.md

Canonical project context is in AGENTS.md. This file exists for Claude Code compatibility.

## Snipara

Use Snipara Hosted MCP before answering project-specific questions.

- Endpoint: https://api.snipara.com/mcp/YOUR_PROJECT_SLUG
- Start substantial work with snipara_recall and a targeted snipara_context_query.
- Use snipara_context_query for source truth and snipara_get_chunk for exact cited sections.
- When snipara_context_query returns answer_pack, use its facts, caveats, source map, and verification checklist before drafting claims.
- Use snipara_code_callers, snipara_code_imports, snipara_code_neighbors, or snipara_code_shortest_path for canonical structural code questions.
- On paid Context plans, use snipara_code_symbol_card before editing important symbols. For impact, use snipara-companion code impact first when companion is installed; it selects the local overlay for dirty/ahead worktrees and hosted MCP for clean indexed code. Use hosted snipara_code_impact only when companion is unavailable or after push/reindex for canonical graph impact.
- Check every snipara_code_* response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
- Companion code commands report sourceSelection on every response. Hosted snipara_code_* answers remain canonical until pushed code is reindexed.
- Use local file reads, rg, git status --short, and tests for exact edits/current working tree; use Snipara for architecture and indexed code graph context.
- When the plan is visible and snipara-companion is installed, keep the machine plan in JSON, use snipara-companion workflow start, phase-start, and phase-commit per phase, and after workflow resume rerun workflow phase-start before editing again.
- Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps.
- For runtime-bound phases, capture compact rehydratable state with workflow runtime-checkpoint <phase_id> --summary "<state>" --rehydrate-file <state.json>. Then workflow resume restores workflow and memory continuity plus the recorded Sandbox binding and prints a reattach or rehydrate plan. It does not snapshot or exactly restore a live Snipara Sandbox or REPL process.
- End substantial work with snipara_end_of_task_commit when available; for managed workflows, end every phase with snipara-companion workflow phase-commit and the task with snipara-companion final-commit.
- Use snipara_remember_if_novel or snipara_remember only for narrow durable memories.
- When remembered knowledge is obsolete or replaced and snipara-companion is installed, use snipara-companion memory invalidate <memory-id> or snipara-companion memory supersede <old-memory-id> <new-memory-id>; otherwise use hosted snipara_memory_invalidate or snipara_memory_supersede.
- Do not store secrets, one-off command output, raw logs, or unreviewed guesses in memory.
- Use the Snipara Claude Code plugin only when slash commands, skills, or hooks are helpful; Hosted MCP remains the normal agent path.

---
description: Use Snipara Hosted MCP for project context and reviewed memory.
alwaysApply: true
---

# Snipara Agent Workflow

This workspace uses Snipara Hosted MCP for current project context and reviewed memory.

- Check the configured Snipara MCP server before answering project-specific questions.
- Use `snipara_recall` for durable decisions, preferences, and validated learnings.
- Use `snipara_context_query` for docs, current project truth, and narrative source material.
- When `snipara_context_query` returns `answer_pack`, use its facts, caveats, source map, and verification checklist before drafting claims.
- Use `snipara_get_chunk` before relying on exact cited wording from reference-based results.
- Use `snipara_code_callers`, `snipara_code_imports`, `snipara_code_neighbors`, or `snipara_code_shortest_path` for canonical structural code questions.
- On paid Context plans, use `snipara_code_symbol_card` before editing important symbols. For impact, use `snipara-companion code impact` first when companion is installed; it selects the local overlay for dirty/ahead worktrees and hosted MCP for clean indexed code. Use hosted `snipara_code_impact` only when companion is unavailable or after push/reindex for canonical graph impact.
- Check every `snipara_code_*` response for indexed commit SHA, indexing time, included files, coverage, and freshness warnings.
- Companion code commands report `sourceSelection` on every response. Hosted `snipara_code_*` answers remain canonical until pushed code is reindexed.
- Use `snipara_plan` for complex work when available; use `snipara_decompose` when deeper decomposition is needed and the hosted server exposes it.
- Use local file reads, `rg`, `git status --short`, and tests for exact code edits and current working-tree state.
- When `snipara-companion` is installed and the LLM has a visible multi-phase plan, keep the machine plan in JSON, use `snipara-companion workflow start`, `phase-start`, and `phase-commit` per phase, and after `workflow resume` rerun `workflow phase-start` before editing again.
- Use Snipara Sandbox only when sandboxed execution or repeatable validation materially helps.
- For runtime-bound phases, capture compact rehydratable state with `workflow runtime-checkpoint <phase_id> --summary "<state>" --rehydrate-file <state.json>`. Then `workflow resume` restores workflow and memory continuity plus the recorded Sandbox binding and prints a reattach or rehydrate plan. It does not snapshot or exactly restore a live Snipara Sandbox or REPL process.
- End substantial work with `snipara_end_of_task_commit` when available; for managed workflows, end every phase with `snipara-companion workflow phase-commit` and the task with `snipara-companion final-commit`. Use `snipara_remember_if_novel` or `snipara_remember` only for narrow durable memories. When remembered knowledge is obsolete or replaced, use `snipara-companion memory invalidate <memory-id>` or `snipara-companion memory supersede <old-memory-id> <new-memory-id>` when companion is installed; otherwise use hosted `snipara_memory_invalidate` or `snipara_memory_supersede`. Never store secrets.

npx create-snipara

npx create-snipara doctor