agent-smith CLAUDE.md

agent-smith — AI Agent Instructions

Context Files (read in this order)

1. Every .agentsmith/contexts/<name>/context.yaml (glob contexts/*/context.yaml) — architecture, stack, integrations, phase status PER stack
2. Every .agentsmith/contexts/<name>/principles.md — code quality rules per stack (ALWAYS follow)
3. .agentsmith/phases/active/*.yaml — spec for the phase being implemented (its applies_to: names the dominant context)
4. .agentsmith/decisions/*.yaml — past decisions, one YAML per phase or run (read the active phase's file and its requires: chain)
5. .agentsmith/memory/MEMORY.md — the experiential-memory index, one line per recorded fact; recall detail from .agentsmith/memory/<name>.md on demand when a line touches your task

Phase Directory Structure

.agentsmith/phases/
  done/       # completed phases (historical reference)
  active/     # phase currently being worked on
  planned/    # upcoming phases with requirements

Experiential Memory (remember / recall)

.agentsmith/memory/ holds typed Markdown facts: one file per memory with frontmatter name (slug = filename), description (one line), and metadata.type (feedback = how the operator wants the agent to work, ratification required; project = goals/constraints/state not derivable from code or git; reference = external pointers). MEMORY.md is the index — one line per memory, content never in the index.

• Recall before re-deriving: when the index hints at a fact you are about to work out from scratch, read the entry file instead.
• Remember sparingly: store what code and git cannot already tell the next agent — one fact per file; check the index for an existing entry and update rather than duplicate; delete a memory that turns out wrong; link related memories as [[slug]] (a cited slug requires its committed definition). A new or changed feedback entry is a PROPOSAL until the operator ratifies it.
• Memory vs decision: a decision records a CHOICE (decisions/); a memory records a transferable FACT or RULE. Never duplicate one into the other.