TORCH/AGENTS.md

AGENTS.md — Repository-Agnostic Agent Operating Guide

This file defines how agents should work in this repository before any project-specific customization exists.

Purpose

• Keep agent work predictable, auditable, and safe.
• Minimize repeated discovery work across sessions.
• Capture durable learnings so future agents can move faster.

Session startup checklist (run every session)

1. Read AGENTS.md.
2. Read CLAUDE.md for execution workflow details.
3. Read CONTRIBUTING.md for commit and PR expectations.
4. Read KNOWN_ISSUES.md for active blockers and workarounds.
5. Read docs/agent-handoffs/README.md.
6. Scan recent notes in:
   • docs/agent-handoffs/learnings/
   • docs/agent-handoffs/incidents/
7. If present, review the current run artifacts in:
   • src/context/
   • src/todo/
   • src/decisions/
   • src/test_logs/
   • src/issues/

Core operating principles

• Default to generic guidance and neutral language.
• Make the smallest safe change that satisfies the request.
• Avoid unrelated refactors.
• Preserve backward compatibility unless explicitly asked otherwise.
• Prefer explicit commands and documented behavior over assumptions.
• Record assumptions clearly in your final summary.

Validation policy

• Run the most relevant checks for changed files (tests, lint, typecheck, build, or targeted scripts).
• Never claim a check passed unless it was actually executed.
• If a check cannot run, record:
  • command attempted,
  • why it could not complete,
  • what fallback validation was performed.

Knowledge-sharing protocol

What belongs where

• KNOWN_ISSUES.md
  • Active, reproducible issues only.
  • Include status, impact, workaround, and last verification date.
• docs/agent-handoffs/learnings/
  • Proven patterns, repeatable fixes, and successful implementation guidance.
• docs/agent-handoffs/incidents/
  • Failures, root causes, mitigations, and prevention guidance.
• src/context/
  • Snapshot of current task context (goal, scope, constraints).
• src/todo/
  • Actionable checklist for in-progress work.
• src/decisions/
  • Key implementation decisions and rationale.
• src/test_logs/
  • Commands run and their outcomes.
• src/issues/
  • One-off investigative or audit outputs not yet promoted to KNOWN_ISSUES.md.

Naming standard (generic)

Use: YYYY-MM-DD-short-topic.md

Examples:

• 2026-02-14-validation-before-summary.md
• 2026-02-14-missing-baseline-context.md

Naming rules:

• Keep names concise and descriptive.
• Avoid company, product, team, customer, and environment names.
• Prefer neutral technical terms.

Required sections for reusable notes

Use these headings in learning/incident notes:

1. Context
2. Observation
3. Action taken
4. Validation performed
5. Recommendation for next agents

Update decision tree

When you discover reusable context:

1. Check if an existing note already covers it.
2. If yes, update that note.
3. If no, add a new note in learnings/ or incidents/.
4. If the issue is still active/reproducible, add or update KNOWN_ISSUES.md.

Priority order when guidance conflicts

1. System/developer/user instructions in the active session
2. AGENTS.md
3. CLAUDE.md
4. CONTRIBUTING.md
5. Inline code comments and prompt templates

Keep this file generic

Only add project-specific details after they are truly needed and explicitly labeled as repository-specific.