Skip to content

AGENTS.md

Latest commit

 

History

History
79 lines (56 loc) · 3.09 KB

AGENTS.md

File metadata and controls

79 lines (56 loc) · 3.09 KB

👋 Welcome, Agents!

Orientation

If .agents/project.md exists in this repository, read it first — it describes the language, architecture, and role of this specific repo within the Spine SDK organisation. To create one, copy .agents/project.template.md (or the relevant language template) and fill it in. If project.md links to a shared requirements file (e.g. jvm-project.md), read that too.

  • Start every session by reading .agents/quick-reference-card.md (if present).
  • For specific tasks (code review, PR prep, dependency updates, docs, etc.), prefer the matching skill from .agents/skills/.
  • Full standards reference: .agents/_TOC.md (if present) — consult when a skill doesn't cover the needed context.

Commit and history safety

Do not commit, push, tag, rebase, merge, cherry-pick, or otherwise write to git history unless one of the following is true right now:

  1. The currently active skill's SKILL.md has a ## Commit authorization section that explicitly permits the operation.
  2. The user's current prompt explicitly requests the operation.

Authorization does not carry over between turns or sessions. When in doubt: stage changes, show the diff, and stop — let the user commit.

See .agents/safety-rules.md → Commits and history-writing.

Other safety rules

  • All code must compile and pass static analysis.
  • Do not auto-update external dependencies outside a dedicated update task.
  • No analytics, telemetry, or tracking code.
  • No reflection or unsafe code without explicit approval.

See .agents/safety-rules.md for the full list.

Moving files

When moving or renaming tracked files, always use git mv. Do not simulate a move by deleting the old file and creating a new one — preserve Git history unless the user explicitly asks for a fresh replacement.

If git mv fails due to permissions or sandbox restrictions, request approval; do not fall back to delete/create.

Memory

Team-shared memory lives in .agents/memory/ (checked into git). Use it for feedback rules, durable project rationale, and external system pointers. See .agents/memory/README.md for layout and write protocol.

Review .agents/memory/MEMORY.md at the start of every session. Ruthlessly iterate until mistakes stop repeating.

Verification & Quality

  • Never mark a task done without proof (tests, logs, diff vs main).
  • Ask: "Would a senior/staff engineer approve this?"
  • For non-trivial changes: pause and consider a more elegant solution.
  • Fix bugs autonomously — find root cause, no hand-holding, no band-aids.

Core Principles

  • Simplicity first: minimal code impact, minimal surface area.
  • No laziness: always find root causes.
  • Minimal side effects: avoid new bugs.
  • Prefer early returns and clear naming.
  • Challenge your own work before presenting it.

Task planning

  • Write plans to .agents/tasks/<slug>.md before coding. See .agents/tasks/README.md for format and lifecycle.
  • Verify changes before marking a task done.
  • Update memory if lessons emerged.
  • Delete the task file on merge to master.