Skip to content

AGENTS.md

Latest commit

 

History

History
63 lines (49 loc) · 2.81 KB

AGENTS.md

File metadata and controls

63 lines (49 loc) · 2.81 KB
Raw

San Agent Guide

This file is the short navigation map for agents and contributors. Keep durable knowledge in docs/; keep this file focused on where to look and what rules to follow before changing code.

AGENTS.md is a static navigation aid for whoever opens the repository. SAN.md and CLAUDE.md at the project root are loaded into the running agent's system prompt at startup — they belong to runtime context, not to this file. Do not mix the two.

Start Here

  • Product overview: README.md
  • Documentation index: docs/index.md
  • Detailed architecture: docs/concepts/architecture.md
  • Package map and ownership: docs/reference/package-map.md
  • Dependency rules: docs/reference/dependency-rules.md
  • Feature notes: docs/packages/index.md
  • Development workflow: docs/operations/development.md

Repository Shape

  • cmd/san: CLI entrypoint and command wiring.
  • internal/app: Bubble Tea TUI shell, model composition, event routing.
  • internal/core: stable agent, message, tool, and system-prompt contracts.
  • internal/agent: agent construction and session-facing runtime setup.
  • internal/llm: model provider registry, clients, cost and logging helpers.
  • internal/tool: built-in tool registry, schemas, adapters, and executors.
  • internal/session: transcript persistence, projection, metadata, resume.
  • internal/task, internal/subagent, internal/cron: background work and orchestration.
  • internal/command, internal/skill, internal/plugin, internal/mcp, internal/hook: extension surfaces.
  • internal/setting, internal/persona: configuration and persona overlays.
  • internal/log, internal/secret, internal/filecache, internal/markdown, internal/confdir: infrastructure helpers.
  • internal/selflearn: background memory and skill review loop.
  • docs: durable explanations, design decisions, operations, and references.

Rules

Before editing internal packages, read:

  • docs/reference/dependency-rules.md — allowed import directions and the rule for each layer.
  • docs/design/principles.md — coding principles for package structure, interfaces, tests, and context handling.

Update those files when the rules change. Do not duplicate them here.

Common Commands

See docs/operations/development.md for build / test / lint / format and the sandbox-friendly GOCACHE workaround. Update that file when commands change. Do not duplicate them here.

Documentation Rules

  • Add or update docs in the same change as architecture or workflow changes.
  • Each feature document should list purpose, entrypoints, core packages, flow, configuration, tests, and common pitfalls.
  • Architecture decision records live in docs/design/decisions/.
  • File naming rules live in docs/reference/file-naming.md.
  • Active plans live in notes/active/; completed plans move to notes/completed/.