3aKHP3aKHP/prts-mcp/AGENTS.md

prts-mcp

AGENTS.md16 starsChanged 28 days agoMITView on GitHub

Never push directly to any long-lived branch. Create a topic branch (<type>/v<version>-<topic>) from the appropriate base branch and open a Pull Request. Human maintainers perform all merges. When porting fixes from lts/2.8 or lts/1.7 to 3.x, reimplement them in Rust on develop — never merge a legacy branch into develop. Before making non-trivial changes, consult the authoritative guides: Documentation task assignment: GPT-family models should focus on fact-based review and small, evidence-backed corrections that preserve the existing writing style. Assign new-document…

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,439 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 repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- comparative-evaluationSkill

The file

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

3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.

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

Common
Distinctive
Very specific

Distinctive:
Before making non-trivial changes, consult the authoritative guides:
line 16
Very specific:
WSL2 Workspace: Keep the repository checkout on the native Linux filesystem (never under /mnt/c/).
line 38
Very specific:
Run ./scripts/check-runtime.sh for a fast toolchain and metadata check.
line 42

≈ “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

Codex Instructions for PRTS-MCP

1. Branch Model

Branch	Purpose
`main`	Latest public stable release (native Rust `3.2.3`).
`develop`	Active 3.x Rust integration branch (`3.2.3-dev.0`). Root Cargo project; no `python/` or `ts/` directories.
`lts/2.8`	Python/TypeScript 2.8.x long-term maintenance branch (EOL `2027-07-02`).
`lts/1.7`	Python/TypeScript 1.7.x long-term maintenance branch (EOL `2027-07-02`).

Never push directly to any long-lived branch. Create a topic branch (<type>/v<version>-<topic>) from the appropriate base branch and open a Pull Request. Human maintainers perform all merges. When porting fixes from lts/2.8 or lts/1.7 to 3.x, reimplement them in Rust on develop — never merge a legacy branch into develop.

2. Startup Reads

Before making non-trivial changes, consult the authoritative guides:

CLAUDE.md and docs/dev/STYLE.md — collaboration rules, module architecture, Rust conventions, and known pitfalls.
docs/dev/DOCUMENTING.md — required standards whenever writing, editing, or reviewing public documentation.
docs/dev/WORKFLOW.md and docs/dev/VERSIONING.md — PR grading, dual-track code review, minimum verification matrix, and SemVer compatibility promises.
docs/dev/LTS.md — maintenance scope and release rules for lts/2.8 and lts/1.7.
STATUS.md and ROADMAP.md — current release state, 3.0 migration milestones, and post-3.0 backlog.
docs/glossary.md — project terminology and abbreviations (single entry point for definitions).
docs/dev/adr/ — architecture decision records (numbered, status-tracked) since 3.1; consult before revisiting settled decisions.

Documentation task assignment: GPT-family models should focus on fact-based review and small, evidence-backed corrections that preserve the existing writing style. Assign new-document drafting, substantial rewrites, large-scale translation, and prose refinement to a human maintainer or a maintainer-designated non-GPT model. This applies to both primary agents and subagents. Follow docs/dev/DOCUMENTING.md; explicit task-specific authorization takes precedence.

(Note: Local working notes, phase plans, and historical archives live under gitignored ./dev/docs/. Never add links to ./dev/ in tracked public documentation.)

3. Runtime and Packaging

Native Rust Server: The repository root is a Cargo workspace-free package (Cargo.toml declares MSRV 1.89, rust-toolchain.toml pins 1.96.1). Source builds require a C compiler for the statically linked QuickJS regexp engine (vendor/quickjs-regexp/) and OS memory diagnostics (native/process_memory.c). Prebuilt native archives and Docker images require no compiler or language runtime.
Distribution Guides:
- docs/dev/NATIVE-PLATFORMS.md — 5 native targets (linux-x64, linux-arm64, windows-x64, darwin-arm64, darwin-x64) and ABI baselines.
- docs/dev/NPM-DISTRIBUTION.md — 9-package npm layout (prts-mcp, prts-mcp-ts, @3akhp/prts-mcp-runtime, @3akhp/prts-mcp-data, and 5 platform packages).
- docs/dev/DOCKER-DISTRIBUTION.md — Linux x64/arm64 Docker images and volume compatibility.
- docs/dev/RELEASE-CANDIDATES.md and docs/dev/RELEASE-CD-RECOVERY.md — candidate aggregation, publishing, and failure recovery.
WSL2 Workspace: Keep the repository checkout on the native Linux filesystem (never under /mnt/c/). Node.js >= 22 and Bun 1.3.14 are used only for development verification harnesses, packaging scripts, and the frozen TS/v2.8.1 oracle (reconstructed under gitignored .reference/ts-v2.8.1/).

4. Verification

Run ./scripts/check-runtime.sh for a fast toolchain and metadata check. For full verification (fixture setup, cargo fmt, cargo clippy, unit/integration tests, release binary build, 384 frozen differential cases, process lifecycle, and extended regex checks), run:

./scripts/check-runtime.sh --full

See docs/dev/ENVIRONMENT.md for single-target test commands and platform-specific notes, and docs/dev/E2E.md for full real-client E2E procedures.

For quantitative code or benchmark comparisons, use docs/dev/COMPARATIVE-EVALUATION.md. Select the contributor's own private environment profile and operations document; the public workflow does not assume maintainer infrastructure.

5. Code Review

Standard and higher-tier PRs require dual-track review: open the PR first to trigger KHPilot Bot Review, and run an independent clean-context, read-only review in parallel (see docs/dev/WORKFLOW.md and CLAUDE.md).

KHPilot is advisory, never a merge prerequisite. Missing, interrupted, incomplete, or action_required Bot results do not delay work or require a waiver. Required CI and independent review still apply; verified substantive findings must be resolved regardless of their source.

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