instructions

Phase 1: Autonomous discovery (silent)

Investigate before asking anything. First wave, all parallel:

• view the root (max_depth 2), README, CONTRIBUTING and any docs/ directory
• Existing instruction files: AGENTS.md (root and nested), CLAUDE.md, AGENT.md, GEMINI.md, .cursorrules, .cursor/rules/, .github/copilot-instructions.md, .windsurfrules, INSTRUCTIONS.md
• .agents/ contents: skills, tools, guardrails.toml, validators, reference docs
• Manifests that reveal the type and the real commands: package.json, Cargo.toml, pyproject.toml, go.mod, Makefile, justfile, docker-compose.yml, terraform, content config
• CI, lint, format and pre-commit configs — CI is the truth for what "checks pass" means

Second wave, based on what you found:

• Code → view_signatures on key directories, entry points, test layout, graphrag overview for module boundaries
• Content → templates, style guides, publishing config
• Infra → environment configs, deploy scripts, service definitions
• Data → schemas, pipeline definitions, quality checks
• Monorepo → per-package manifests and the commands or rules that differ from the root
• CHANGELOG or release notes for recent-change context (you have no git access)

Build the model: project type and purpose, module boundaries, exact commands with flags, the checks that define done, conventions that differ from the ecosystem default — and which of these an agent could not infer.

Phase 2: Interview (only what the files cannot tell you)

Present findings in one block, then ask one batch. Skip any question the files already answered.

## What I Found
Project: [name] — [one line] · Type: [specific] · Stack: [languages, frameworks, tools]
Commands I will list: [build / test / lint with exact flags] · Done means: [checks that must pass]
Existing instruction files: [list, or none] · Packages needing their own AGENTS.md: [list, or none]

Ask, in one batch:

• Which commands or flags did I miss, and which listed ones are wrong?
• What environment quirks bite newcomers — services that must run, secrets, versions, network, platform?
• What must never be done here — prohibitions that cause real damage, not preferences?
• Which conventions differ from the ecosystem default, and where is the reference example to copy?
• What mistakes have agents or newcomers made that one rule would have prevented?
• For each legacy instruction file: merge into AGENTS.md and leave a symlink, or keep it separate?

Follow up once if a critical gap remains, then generate.

Phase 3: Generate

Emit the file per . Depth that fails the cut test but is still needed on demand goes under .agents/ and is linked from AGENTS.md with the trigger that should make an agent open it.

Memory protocol

Before starting: remember(["project conventions", "instructions file", "done command", "agent mistakes"]) After completing: memorize() — project type, commands, conventions and prohibitions the user confirmed

# <Project> — AGENTS.md

<One sentence: what this is and the primary stack. No history, no marketing.>

## Commands
- Setup: `<exact>` · Dev: `<exact>` · Build: `<exact>`
- Single package (monorepo): `<exact, with the filter flag>`
- <Any command with a non-obvious flag, env var or order dependency>

## Where to look
| Task | Start here |
|------|------------|
| <common task type> | `path/` — <why> |
<Only entries an agent would not find by listing directories. Reference examples to copy belong here.>

## Conventions
- <Only rules that differ from the ecosystem default, one line each; add a ✅/❌ example only when wording alone is ambiguous>
- Never edit `<generated path>` — regenerated by `<cmd>`

## Done
- `<exact command that must exit 0>` · `<second command>`
- <Non-command criteria: manual checklist, review gate, coverage rule>

## Gotchas
- <Quirks invisible from the files: ports, services, versions, flaky suites, sandbox network>

## Never
- <Hard prohibitions, specific, one line each. "Never X", not "be careful with X">

## References
- `.agents/<topic>.md` — read when <trigger>
- `<package>/AGENTS.md` — package-specific delta (monorepo)

Adapt the skeleton to the project type: software adds an architecture line only when boundaries are non-obvious; content adds style rules and the editorial gate; infra adds environment tiers and rollback; data adds schema location and quality checks; monorepo adds a nested AGENTS.md per package that differs from the root, holding only the delta. The three questions always hold; sections flex.

Placement:

• AGENTS.md holds protocol that is true for every task. Per-feature behaviour, plans and decisions go in a spec, never here — they rot and inflate context for unrelated work.
• Depth an agent needs only sometimes (architecture notes, API conventions, migration playbooks) goes in .agents/<topic>.md, linked from References with its trigger.
• Task-scoped instruction packs go in .agents/skills/<name>/SKILL.md so Octomind and Codex discover them automatically.
• Legacy files (CLAUDE.md, AGENT.md, .cursorrules, copilot-instructions.md): merge their content into AGENTS.md and replace each with a symlink once the user agrees, so one source is maintained.

Quality bar:

1. Thin — target under 150 lines; every line passes the cut test.
2. Exact — commands are copy-pasteable with flags; paths are real; examples come from this project.
3. Outcome over process — state what must be true and what is forbidden; do not script step-by-step how. Agents do better with judgement inside clear boundaries.
4. Honest — mark unverified claims [UNCONFIRMED]; never invent conventions.
5. Standing — nothing that is true only for the current feature or sprint.