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`, `snipara_help(query=...)`, 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 exposes only the lean default Snipara tool surface, treat that as
  normal. Use `snipara_help(query=...)` for routed guidance and
  `snipara_help(list_all=true)` to inspect specialist opt-in surfaces before
  requesting an expanded MCP surface.
- If the client supports native skills, install the generated Snipara skill pack
  from `.snipara/templates/skills`. Keep this `AGENTS.md` file as the shared
  fallback for clients without native skill support.

## Experience Goal

The target experience is outcome-first agent work across supported clients:
Codex, Claude Code, Cursor, Orca, LM Studio-backed local stacks, or another
MCP-capable environment. The user should be able to state an outcome, ask for
engineering judgment, or request a release while the agent handles Snipara
context retrieval, workflow state, verification, package checks, Git operations,
deployment, and production smoke checks behind the scenes. Surface important
decisions, blockers, and evidence, but do not make the user manually orchestrate
routine Snipara or release mechanics.

Agent task lifecycle:

1. Consume the pushed Snipara session brief when present. If it is empty, do not pull context just to satisfy ceremony.
2. Let the router choose LITE, STANDARD, FULL, or ORCHESTRATED from task intent. LITE has no mandatory Snipara calls.
3. Use `snipara_recall`, `snipara_context_query`, and `snipara_get_chunk` on demand when the task needs memory, source truth, or exact cited wording.
4. 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.
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. Use `snipara_code_symbol_card` for agent-ready symbol context within plan
   capacity. 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 or multi-surface work in any plan when
   exposed. For FULL-mode audits, comparisons, roadmap/implementation planning,
   release readiness, or package-surface reviews, use `snipara_decompose` to
   preserve the work axes and `snipara_multi_query` to execute independent
   follow-up questions when Pro+ tools are exposed.
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

## Experience Goal

The target experience is outcome-first agent work across supported clients:
Codex, Claude Code, Cursor, Orca, LM Studio-backed local stacks, or another
MCP-capable environment. The user should be able to state an outcome, ask for
engineering judgment, or request a release while the agent handles Snipara
context retrieval, workflow state, verification, package checks, Git operations,
deployment, and production smoke checks behind the scenes. Surface important
decisions, blockers, and evidence, but do not make the user manually orchestrate
routine Snipara or release mechanics.

- Let the router choose workflow depth; LITE starts with no mandatory recall or context query.
- If the client supports native skills, install the generated Snipara skill pack from `.snipara/templates/skills`. Keep `AGENTS.md` as the shared fallback for clients without native skill support.
- 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.
- Use snipara_code_symbol_card before editing important symbols within plan capacity. 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.
- If the client supports native skills, install the generated Snipara skill pack from `.snipara/templates/skills`. Keep `AGENTS.md` as the shared fallback for clients without native skill support.

## Experience Goal

The target experience is outcome-first agent work across supported clients:
Codex, Claude Code, Cursor, Orca, LM Studio-backed local stacks, or another
MCP-capable environment. The user should be able to state an outcome, ask for
engineering judgment, or request a release while the agent handles Snipara
context retrieval, workflow state, verification, package checks, Git operations,
deployment, and production smoke checks behind the scenes. Surface important
decisions, blockers, and evidence, but do not make the user manually orchestrate
routine Snipara or release mechanics.

- Use `snipara_recall` for durable decisions, preferences, and validated learnings.
- Use `snipara_context_query` for docs, current project truth, and narrative source material. Keep simple Q&A and single-source lookups on a targeted `snipara_context_query`.
- 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.
- Use `snipara_code_symbol_card` before editing important symbols within plan capacity. 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 or multi-surface work when available. For FULL-mode audits, comparisons, roadmap/implementation planning, release readiness, or package-surface reviews, use `snipara_decompose` to preserve axes and `snipara_multi_query` for independent follow-up questions when Pro+ tools are exposed.
- 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