tikocitikoci/rosetta/CLAUDE.md

rosetta

CLAUDE.md54 starsChanged 4 months agoMITView on GitHub

RouterOS documentation as SQLite FTS5 — one core data model exposed through three surfaces: an MCP server for agents, a browse TUI for humans, and a command-tree/glossary layer for downstream RouterOS tooling. This file is intentionally a thin routing index. Detailed rationale lives in DESIGN.md; install and operator reference live in MANUAL.md; narrow coding rules live in .github/instructions/*.instructions.md. Each file has one job. Prefer the canonical home instead of inventing a new top-level .md. The canonical routing rule lives in…

In this repository8 other files it gives its agents.
- AGENTS.mdAGENTS.md
- matrix/CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- pick-next-taskSkill
- promote-ideaSkill
- pr-review-gateSkill
- re-extractSkill
- verify-taskSkill

The file

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

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
Avoid ticket sprawl: an issue starts as discussion.
line 40

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.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

CLAUDE.md

rosetta

RouterOS documentation as SQLite FTS5 — one core data model exposed through three surfaces: an MCP server for agents, a browse TUI for humans, and a command-tree/glossary layer for downstream RouterOS tooling. This file is intentionally a thin routing index. Detailed rationale lives in DESIGN.md; install and operator reference live in MANUAL.md; narrow coding rules live in .github/instructions/*.instructions.md.

Project Documentation

Each file has one job. Prefer the canonical home instead of inventing a new top-level .md.

File / dir	Canonical role
`CLAUDE.md`	Project orientation + routing index for agents
`AGENTS.md`	Short Codex-specific routing note
`DESIGN.md`	Durable rationale, data-source provenance, architecture tradeoffs
`MANUAL.md`	Install, operations, release/re-extraction steps, schema reference
`README.md`	User-facing quick start
`CHANGELOG.md`	User-visible shipped changes under `[Unreleased]` / releases
`VALIDATION.md`	Load-bearing invariants and how CI proves them
`BACKLOG.md`	Lightweight inbox, triggers, and briefing index
GitHub Issues	Active committed work items (`agent-ready` / `umbrella` / `blocked` labels)
`tasks/`	Frozen archive of the pre-2026-07 file-based queue; `tasks/done/T-*.md` kept for grep-able history. No new task files
`briefings/B-*.md`	Research notes and decision support
`.github/copilot-instructions.md`	Short Copilot-specific routing note
`.github/instructions/*.instructions.md`	Narrow normative rules matched by `applyTo`
`.github/prompts/*.prompt.md`	Repo-local Copilot prompt workflows
`.github/skills/*/SKILL.md`	Repo-local skill workflows — canonical home; symlinked into `.claude/skills/` so Claude Code triggers them too (same real-dir+symlink convention as the global `routeros-*` skills in `~/CLAUDE.md`)

Where does this go?

The canonical routing rule lives in .github/instructions/where-does-this-go.instructions.md. Short version:

Committed codebase work → a GitHub issue (agent-ready once the spec is settled; PRs close issues via Closes #N)
Grounded research / decision support → briefings/B-*.md
Loose thought with no shape yet → BACKLOG.md Inbox
Waiting on a named external event → BACKLOG.md Triggers
Durable project rationale → DESIGN.md
Operator or release procedure → MANUAL.md
User-visible shipped behavior → CHANGELOG.md
Load-bearing invariant + proof → VALIDATION.md

Avoid ticket sprawl: an issue starts as discussion; the agent-ready label is a promotion earned once acceptance criteria are settled, not a default.

Instruction Routing

Agent-specific entrypoints are thin shims: Claude starts here, Codex starts with AGENTS.md, and Copilot starts with .github/copilot-instructions.md. Then read the narrow files that match the surface you are touching.

Area	Read these files
Cross-cutting rules	`changelog-discipline.instructions.md`, `where-does-this-go.instructions.md`, `instruction-scopes.instructions.md`, `descriptive-prose-file-names.instructions.md`
Bun / runtime conventions	`bun-not-node.instructions.md`, `database.instructions.md` when touching `src/db.ts`
MCP, query, classifier, browse, canonicalizer	`mcp-server.instructions.md` plus `query-core-not-adapter.instructions.md`, `tui-mcp-parity.instructions.md`, `mcp-tool-descriptions.instructions.md`, `tool-surface-change.instructions.md`, `canonicalize-vendored.instructions.md`
Extraction and data-shape work	`extraction.instructions.md` plus `extractor-idempotent.instructions.md`, `extractor-import-side-effects.instructions.md`, `command-versions-vs-presence.instructions.md`, `schema-roundtrip-compat.instructions.md`, `data-source-naming-product-matrix.instructions.md`, `skill-attribution-boundary.instructions.md`
Release / install / provenance	`release-via-ci.instructions.md`, `republish-assets-not-npm.instructions.md`, `db-meta-stamping.instructions.md`
Markdown / doc-authoring rules	`markdownlint-fenced-code.instructions.md`, `llm-instruction-files-excluded-from-mdlint.instructions.md`
Issue / briefing workflow	`tasks-vs-briefings.instructions.md`, `issue-pr-linking.instructions.md`, `tasks/README.md`, `briefings/README.md`
PR is Ready for Review / you're about to say it's mergeable	Run the `pr-review-gate` skill (`.github/skills/pr-review-gate/SKILL.md`) — `reviewDecision` and green checks do not mean mergeable; unresolved bot threads block `main` independently. Rationale: `pr-review-bots.instructions.md`

Fast pointers

Need why something works this way? Read DESIGN.md.
Need how to run, release, or rebuild it? Read MANUAL.md.
Need manual-site migration context? MikroTik moved future docs to Docusaurus at https://manual.mikrotik.com; read DESIGN.md and briefings/B-0012-docusaurus-manual-migration.md before touching extraction, MCP, or TUI search.
Need external agent-benchmark context? ~/GitHub/bench-routeros-tools tests rosetta as one grounding approach for live RouterOS command generation; read DESIGN.md → "External benchmark feedback loop" before changing retrieval, skills, or command-validation surfaces.
Need current corpus counts? Use routeros_stats rather than hard-coded numbers here.
Need to trust the local DB before grounding a claim? In a checkout, repo-root ros-help.db is untrusted until verified. Run make db-doctor (or read routeros_stats → provenance.grounding); make db-sync fetches the latest CI release DB (the grounding source of truth). See .github/instructions/local-db-grounding.instructions.md.
Need work status or open ideas? Use gh issue list (active work), briefings/, and BACKLOG.md; tasks/ is a frozen archive.

Nothing else should be duplicated here. If this file starts growing operational detail, schema blocks, or long rule lists again, move that content back into its canonical home instead.

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