zmNinjaNg AGENTS.md

Development Guidelines

Portable core. This file contains no project-specific names and copies verbatim into any project. Load order: this file, then AGENTS.project.md (architecture contracts, project rules, verification commands, playbooks), then the playbook it lists for your work area.

Adopting this core in another project: copy this file unchanged, then write your own AGENTS.project.md and the gates it names. Project facts never belong in this file.

Rule format

Every rule is a statement, a one-clause why, and a gate. A rule a script could check but names no gate is a defect here. Rules carry stable IDs by tier; docs reference IDs, never copied text.

Invariants (never simplified away)

• I1. Validate at trust boundaries: server responses, user input, IPC. Malformed input is routine, not rare.
• I2. Destructive operations need error handling and a recovery path. Lost user data cannot be patched later.
• I3. Security and accessibility are never traded for simplicity or speed. Gate: blocking accessibility and correctness lints.

Process

• P1. Create or use an issue before feature or bug work, after checking the out-of-scope ledger; land through an issue-linked PR whose body quotes the issue's acceptance lines. Commits reference the issue; closing keywords only after the user confirms. If instructed to push directly to the default branch, do so and verify the issue timeline. Typo-level fixes and doc corrections with no behavior change need no issue.
• P2. Test first: a failing test precedes the implementation of every feature and bugfix. A test that has never failed does not demonstrate it can catch the bug. Changes an existing gate already covers fully rely on that gate instead of a bespoke new test. Gate: the proven-red CI job runs each change's tests against the pre-change code and fails when they pass.
• P3. Run the gates covering the change before every commit; run the full suite before push or PR. Never commit after a failed or unrun gate.
• P4. Read failures and fix the cause. Never blindly retry.
• P5. One logical change per conventional commit.
• P6. Verification runs direct commands. Tooling that transforms output, such as wrappers, compressors, or summarizers, is untrusted until validated once against raw output.
• P7. Finish the requested behavior. Materially different UX options need approval before choosing.
• P8. Never merge the default branch without approval.
• P10. Docs move with behavior: user docs for changed behavior, developer docs and call flows for new APIs, components, hooks, and utilities. All prose reads like a developer explaining to a colleague: no marketing language, filler, headline headings, aphorisms, or news cadence.