AGENTS.md — AI Assistant Guide

Project Memory Model

• docs/todo/ROADMAP.md = milestone plan, near-term tasks, and completed history.
• .agents/handoff.md = stable current project state.
• .agents/memory.md = chronological session log.

Promote durable findings from memory → handoff, priorities and follow-ups → roadmap.

Reference: docs/process/PROJECT_MEMORY_MODEL.md

Roadmap and Planning Docs

• Check ROADMAP.md before proposing new initiatives.
• Use ROADMAP.md#next for small follow-ups and manual validation.
• Keep detailed plans in docs/todo/TODO_*.md; graduate completed plans to DONE_*.md.
• When creating or renaming a planning doc: .agents/instructions/documentation/todo-done-docs.instructions.md

Package Layout

Canonical shared content lives in assets/; everything under .agents/, .claude/skills/, and .github/copilot-instructions.md is vendored output of this package applied to itself. Edit assets/, never the vendored copies. src/index.ts is the manifest genx consumes.

Rules — Project-Specific

• Project-specific rules live in .agents/instructions/project/**/*.instructions.md.
• Do not reference @workspace/* — all imports and deps must use published package names.

Rules — Global

Rules are canonical in assets/instructions/ and vendored to .agents/instructions/. These files are not auto-loaded — open the one that matches your task before editing. See docs/reference/AGENT_FILE_LOADING.md.

Always

• Baseline for all code: .agents/instructions/general.instructions.md
• Before any commit, push, tag, or release: .agents/instructions/git/git-policy.instructions.md
• Before creating or renaming any file: .agents/instructions/naming/file-naming.instructions.md
• Before adding or changing any path alias: .agents/instructions/code/monorepo-path-aliases.instructions.md

When writing TypeScript

• Parameters, typing, structure: .agents/instructions/code/typescript-patterns.instructions.md
• Modern features worth preferring: .agents/instructions/code/modern-typescript-patterns.instructions.md
• Naming and no-abbreviation policy: .agents/instructions/naming/variable-naming.instructions.md
• What the formatter fixes for you: .agents/instructions/code/linting-code-style.instructions.md
• Adding a provider or context: .agents/instructions/code/provider-context-patterns.instructions.md
• Colouring CLI output: .agents/instructions/code/picocolors-cli-styling.instructions.md

When writing markdown

• Deciding which file content belongs in: .agents/instructions/documentation/agent-context-files.instructions.md
• Creating or editing a skill: .agents/instructions/documentation/writing-skills.instructions.md
• Referencing another file from an agent-facing doc: .agents/instructions/documentation/agent-facing-markdown.instructions.md
• Structure, date tags, links: .agents/instructions/documentation/documentation.instructions.md
• Writing a README: .agents/instructions/documentation/readme-standards.instructions.md
• Writing a design spec: .agents/instructions/documentation/feature-design-specs.instructions.md

Decisions

Durable decisions live in docs/adr/. Read before changing instruction architecture or the package boundary with genx:

• docs/adr/0001-agent-instruction-file-architecture.md
• docs/adr/0002-content-versus-structural-ownership.md

Rules — Markdown Tables

• Padded pipes: one space on each side of every |, including the separator row.
• Do NOT manually align column widths or pad cells to equal width. oxfmt (run automatically by lint-staged on commit and by pnpm format:fix) fixes table alignment automatically. Spending tokens counting characters and iterating on spacing is wasted effort — write the content, let the formatter handle alignment.

Git Policy

• Do not include Co-Authored-By lines in commit messages. Not ever, for any reason.
• Releases are human-only — do not bump versions, push tags, or publish.
• Full policy: .agents/instructions/git/git-policy.instructions.md

Agent execution efficiency

Prefer the smallest complete implementation and validation loop for the task. Aim for one orientation pass, one coherent edit pass, and one focused validation pass; further loops need a concrete failure or newly discovered dependency.

Avoid side quests: do not broaden into adjacent refactors, cleanup, environment repair, or unrelated warning fixes unless required to complete or validate the requested change.

Before editing

• Orient on the owning module, its direct callers/callees, and affected tests — not adjacent subsystems.
• Read applicable repository instructions before implementing.
• Once owning surfaces are identified, start implementing.

Scope

• Reuse established patterns before adding abstractions.
• Do not generalize one-use helpers unless reuse is immediate and obvious.
• Preserve unrelated uncommitted files and pre-existing warnings.

Validation

Use progressive validation and stop once the change is proven:

1. Narrowest relevant test or test file
2. Typecheck for directly affected packages
3. Format/lint on touched files when supported
4. Broader repo checks only when shared exports change, focused checks cannot prove correctness, a failure requires them, or the user asks

Tool use and failures

• Batch related reads/searches and coherent edits; avoid repeating the same command through different wrappers.
• Progress updates at phase boundaries only (orientation / implementation / validation).
• Distinguish failures caused by this change from pre-existing ones; fix unrelated failures only when they block validation, and report them in the summary.

Cursor

• Always-on rules: .cursor/rules/ (alwaysApply — entry point is AGENTS.md, same as CLAUDE.md)