# 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.

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, business context, client/project truth,
   architecture notes, runbooks, and narrative source material. Keep simple Q&A
   and single-source lookups on a targeted `snipara_context_query`.
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. For code impact and structural code questions, use `snipara-companion code
callers/imports/neighbors/shortest-path/impact` first when
   `snipara-companion` is installed; it auto-selects hosted MCP for clean indexed
   code or the local overlay for dirty/ahead worktrees and reports
   `sourceSelection`. 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
   `workflow resume` rerun `workflow phase-start <phase_id>` before editing
   again. For runtime-bound phases, capture compact rehydratable Sandbox state
   with `workflow runtime-checkpoint <phase_id> --summary "<state>" --rehydrate-file <state.json>`.
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. Use Snipara Sandbox only when sandboxed execution, repeatable validation, or
    isolated transformations materially help.
13. If a broad query is slow, retry once with a narrow keyword query before
    falling back to local search.
14. 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.
15. 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`.
16. Use `snipara_remember_if_novel` for one reusable memory while avoiding
    duplicates, and use `snipara_remember` for explicit direct memory writes.
17. 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`.
18. Do not store secrets, tokens, passwords, private keys, raw logs, transient
    command output, or unreviewed guesses in memory.