agentleFS
Sign inStart free
NatanGer97NatanGer97/nautink/AGENTS.md

nautink

AGENTS.md2 starsChanged 35 days agoMITView on GitHub

Nautink is a local-first, open-source web app for building Mermaid diagrams: a canvas you edit by hand or by chatting with a coding agent, with every agent change shown as an accept/reject review. It is a rebuild of ~/dev/mermaid-chat in TypeScript. Always use simple, clear language that is easy to understand. This file is the contract for every agent harness. CLAUDE.md is a symlink to it, so Claude Code, Codex CLI, and anything else that reads AGENTS.md get one copy…

  • Commits and pushes
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 31,700 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository6 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

6 rules. About 0 are common, 6 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Always use simple, clear language that is easy to understand.

    line 7
  2. Distinctive:

    When writing plans, be extremely concise.

    line 14
  3. Distinctive:

    Every task is a TDD block: write the failing test → verify it fails → write the code → verify it passes → verify no regressions.

    line 23
  4. Distinctive:

    Language: all docs, code, identifiers and commit messages are in English.

    line 33
  5. Distinctive:

    Invalid input throws an explicit error: Never return a silent default.

    line 35
  6. Distinctive:

    When the user asks for one of these without a slash command, read the matching file and follow it exactly.

    line 80

≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md — Nautink

Nautink is a local-first, open-source web app for building Mermaid diagrams: a canvas you edit by hand or by chatting with a coding agent, with every agent change shown as an accept/reject review. It is a rebuild of ~/dev/mermaid-chat in TypeScript.

Always use simple, clear language that is easy to understand.

This file is the contract for every agent harness. CLAUDE.md is a symlink to it, so Claude Code, Codex CLI, and anything else that reads AGENTS.md get one copy with no drift.

Plan mode conventions

When writing plans, be extremely concise. Sacrifice grammar for the sake of concision. At the end of each plan, list unresolved questions. Ask about edge cases, error handling, and unclear requirements before proceeding. End every plan with a numbered list of concrete steps. This should be the last thing visible in the terminal.

Two rules shape every plan, whether it comes from plan mode or from /write-plan:

  • One plan = one target. Two targets means two plans. If the work covers more than one target, say so and propose the split instead of planning both.
  • Every task is a TDD block: write the failing test → verify it fails → write the code → verify it passes → verify no regressions. A task that can't be written that way is too big or too vague.

Plans are artifacts, not chat: /write-plan writes them to docs/plans/, with or without a tracking issue. See docs/agents/sdlc.md.

Working agreements

  • The repo is the source of truth. PRD, ADRs and plans live in docs/. If a decision is not in docs/, it is not decided.
  • Language: all docs, code, identifiers and commit messages are in English.
  • Never change an accepted ADR. Supersede it with a new ADR (docs/adr/000-template.md).
  • Invalid input throws an explicit error. Never return a silent default.
  • Monorepo: pnpm workspaces + Turborepo. Apps in apps/*, shared libraries in packages/*. A change to source there needs a changeset (pnpm changeset).

Where things are

PathWhat
docs/agents/The SDLC pipeline (sdlc.md), its procedures (skills/), issue tracker, triage labels, domain docs
docs/adr/Architecture decisions (numbered, immutable once accepted)
docs/plans/One plan file per piece of work, plus the Definition of done
docs/conventions.mdCoding conventions and the ESLint/Prettier rules that enforce them
CONTEXT.mdGlossary of domain terms, created lazily (see docs/agents/domain.md)

Gates

pnpm check              # lint, typecheck, test, build — the gate that must be green before landing
pnpm format:check       # Prettier
pnpm lint:file <path>   # format + lint one file, exits 2 with the report when it is not clean

After writing or editing any .ts, .tsx, .mts, or .cts file, run pnpm lint:file <path> and fix what it reports before moving on. Claude Code does this automatically through the PostToolUse hook in .claude/settings.json; every other harness must run the command. The husky hooks and CI enforce the same rules at commit and push time, so skipping the per-file step only moves the failure later.

Conventions the linter cannot express, and the review-only rules, are in docs/conventions.md.

The SDLC pipeline

Five procedures, one per stage, described in docs/agents/sdlc.md. The procedure text lives in docs/agents/skills/ and is the single source of truth; the harness wrappers only point at it.

AskProcedure to read and followClaude CodeCodex CLI
File an issue, adopt an untracked plandocs/agents/skills/issue-writer.md/new-issue/new-issue
Plan an issue, break work into tasksdocs/agents/skills/plan-writer.md/write-plan/write-plan
Run a plan task by taskdocs/agents/skills/plan-executor.md/execute-plan/execute-plan
Review a branch before landingdocs/agents/skills/work-reviewer.md/review-work/review-work
Commit, push, open the pull requestdocs/agents/skills/lander.md/land/land

When the user asks for one of these without a slash command, read the matching file and follow it exactly. Read the whole file before acting on any part of it.

Codex CLI discovers custom prompts in ~/.codex/prompts only, so the repo's copies in .codex/prompts/ are installed with:

pnpm agents:install-prompts

Outward-facing actions

gh issue create, git push, and gh pr create are outward-facing: show what you are about to do and wait for confirmation. This holds in every harness, whatever its permission settings allow.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free