Repo guide (humans + agents)

Philosophy

• Keep the rules few and useful.
• Optimize for momentum: agents should finish the task, not "perform compliance theatre".
• If a task has a checklist, the checklist is the definition of done.

Writing conventions

• In prose + markdown, use 'single quotes' and "double quotes" normally (no fancy typography).
• In code, follow the project's formatter/linter. If none exists, prefer single quotes where the language allows it.

Files

"AGENTS.md"

Purpose: instructions for LLM/agent contributors.

Put here:

• How to run the project (the 2–5 commands that matter).
• Where planning lives ("tasks/") and where durable docs live ("docs/" if used).
• Repo conventions that actually prevent breakage (e.g. "don't edit generated files", "don't commit secrets").
• How to decide "done": complete the task checklist; if none exists, add one.

Avoid:

• Over-specific process rules that force busywork (heavy templates, long "definitions of done", ceremony).

"tasks/"

Purpose: the working memory of the repo.

• Every plan goes here (to keep a lightweight history).
• Tasks should include a checklist. If the checklist is complete, the task is complete.
• When finished, optionally move to an archive or leave as-is and prune later.

Minimal convention (optional):

• "tasks/.md" for active work
• "tasks/_done/" (or prune periodically)

"docs/" (optional)

Purpose: slow-changing reference and architecture notes.

• Only put things here if you intend to keep them updated.
• If a task produces durable knowledge, promote a short summary into "docs/" and leave a pointer in the task.

Agent behaviour defaults

• Do the smallest set of changes that completes the task checklist.
• Don't add extra requirements unless the task asks for them.
• Prefer readable diffs over "perfect" refactors.
• If you're unsure, write down assumptions in the task file rather than inventing new rules.