Skip to main content
rule CX Codex

scripts — Claude Code rule: what it does, how to install

Enforces architecture guardrails for mavericks-os scripts: separates read-only tools from mutating scripts, forbids npm packages, and blocks secret leaks.

Apache-2.0 ★ 121 updated 2026-10-29

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/scripts.md
Open on GitHub

What scripts does

This rule sets design constraints for tools in scripts/. Reporting utilities like dashboard, validator, and --snapshot must operate strictly read-only with no side-effect file writes. Mutating task scripts, including close-session and new-task, are explicitly permitted to edit task artifacts.

Core tools must run on plain Node.js without third-party npm dependencies. The only allowed external library is @anthropic-ai/sdk, which is loaded lazily inside mavp-skill-reflect.js with a try-catch block. Because core tools avoid dependencies, they execute reliably even on machines without a node_modules directory.

Every new file tracked in git must be classified in scripts/publish-manifest.json. The rule strictly forbids embedding credential patterns, /Users/ paths, or private project names inside files marked for release, even in source code comments.

What it helps with

  • prevent read-only reporting surfaces from modifying task artifacts
  • run project operations using plain Node.js without external npm packages
  • prevent accidental leaks of private names and file paths in released code
  • enforce tracking of all new files in the publish manifest

Example prompts for the agent

  • Add a new operator helper to scripts/mavp-operator-lib.js using pure Node.js APIs
  • Classify the newly created file inside scripts/publish-manifest.json as ship
  • Verify that reporting tools do not trigger file updates when checking status

How to install scripts

Manually: put the files in place

.claude/rules/scripts.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about scripts

How do I install scripts in Claude Code?

Add the rule content to .claude/rules/scripts.md in your project repository. Claude Code loads it automatically when working inside scripts/.

Which npm dependencies are permitted in core scripts?

None. Core operator tooling relies strictly on built-in Node.js modules. The sole exception is @anthropic-ai/sdk, which is loaded lazily only in mavp-skill-reflect.js.

How does the rule handle read-only versus mutating scripts?

Reporting tools such as snapshot and dashboard cannot alter project files. Task-management scripts like new-task and close-session are explicitly allowed to write artifacts.

Source text

scripts.md · Apache-2.0
---
paths:
  - "scripts/**/*.js"
  - "scripts/mavp-operator"
---

# Scripts Rules

- Reporting surfaces are read-only operator tools — they report state, they do not modify it. This applies to: dashboard, `--snapshot`, `--agent`/`--watch`, and the validator. In a never-a-project root (the same four discriminators `guardMutatingRoot()` uses, decided by `guardReportingWrite()` in `mavp-operator-lib.js`) their incidental writes — the `PROCESS_STATE.md` regeneration by `--agent`/`--snapshot`, the `.mavp/permission-mode` record, and the validator's `last_task_id` auto-patch — are skipped, never refused (T-847); `--help` on `--agent`/`--snapshot` exits before any of them. The mutating ritual scripts (close-session, new-task, quick-task, update-task, set-status, rename-task, apply-decomposition, merge-task) are explicitly exempt — they intentionally write artifacts as their primary purpose. `--integrate` (T-567) is also gated by `guardMutatingRoot()` like these, but is NOT an artifact writer in the same sense: it mutates the resolved root's git history (cherry-pick) and writes no BACKLOG.md/TASK_STATUS.md/PROCESS_STATE.* content — its own state-artifact involvement is limited to printing a suggested `--set-status` line, never executing it.
- `mavp-operator-lib.js` is shared logic; changes here affect all operator surfaces. Test snapshot and dashboard after any change.
- `mavp-validator.js` parses `## Active Wave` section in BACKLOG.md. If the section heading changes, update the regex in `parseBacklogActiveTasks()`.
- `mavp-operator-agent.js` is the Main Agent's session entry point — keep its JSON output schema stable. Any new fields are additive only.
- Do not add interactive prompts or side effects (file writes) to reporting surfaces (dashboard, snapshot, agent, validator). The mutating ritual scripts listed above are exempt: they may prompt users (close-session interactive mode) and write artifacts by design.
- Node.js only — no external npm dependencies for core operator tooling (dashboard, `--snapshot`, `--agent`/`--watch`, the validator, and all mutating ritual scripts). These must run with zero npm installs. The one exception is `@anthropic-ai/sdk`, declared in `optionalDependencies` in `package.json` and consumed only by `mavp-skill-reflect.js` (`--reflect-skill`) — it is `require()`d lazily inside that script's `main()` function, guarded by try/catch, never at module load. No other script may import it, directly or transitively. `npm install --omit=optional` (or a machine with no `node_modules` at all) must still leave every core command working; only `--reflect-skill` degrades, with a clear "install the optional dependency" error.
- **Publish-manifest registration** — if the repo contains `scripts/publish-manifest.json`, every new git-tracked file must be classified there in the same task: ship for framework content, exclude with a one-line reason for internal material. Roles whose scope excludes `scripts/` must instead emit `MANIFEST_REGISTRATION_NEEDED: <path> -> <ship|exclude> (<reason>)` in their final report so the Main Agent registers it. Developers editing the manifest run `node scripts/check-publish-manifest.js` and quote its output in evidence. See DR-002 (`docs/core/DECISIONS.md`). When a docs role's new file has a path known at spawn, the Main Agent pre-registers its entry in the working tree before spawning, so no token is needed — see the "Pre-spawn registration for docs roles" procedure in CLAUDE.md's "Publish-manifest registration" convention and DR-017 (`docs/core/DECISIONS.md`). A trailing-slash `exclude` entry (e.g. the `docs/archive/` prefix) classifies every file beneath it, so such files need no per-file registration. **Brief authors: a developer brief must never forbid this self-registration line and must never route a developer's registration through the `MANIFEST_REGISTRATION_NEEDED` token above — that token is exclusively for roles whose scope forbids `scripts/`.** `.claude/hooks/pre-commit`'s blocking backstop makes developer self-registration mandatory, not optional: a worktree containing an unclassified new file cannot produce a commit at all, so a brief forbidding the line leaves the task uncommittable. See DR-007 (`docs/core/DECISIONS.md`) for the incident this closes and the parallel-conflict merge protocol (union additive entries, re-run the checker) that still preserves DR-002's original concern where several developer tasks touch the manifest at once.
- **Shipped secret-string discipline (all ship files, not just fixtures)** — this rule covers EVERY git-tracked file classified `ship` in `publish-manifest.json`: source code, code comments, doc prose, and test data/arguments, not only dedicated test-fixture files. A ship file must never embed a literal string the publish secret-scanner detects: private/project repo names, absolute `/Users/` paths, credential/token shapes (AWS keys, PEM blocks, high-entropy secrets), or non-reserved email domains. Three separate tasks tripped this in one wave, and in every case a human read the file and saw nothing wrong — only the assemble+scan gate caught it: a code comment describing the scanner's own detection categories tripped the very category it was describing (T-505); a comment explaining the absolute-path discipline itself contained the matched token, because the scanner matches file text statically and has no concept of "this is prose about the rule, not a violation of it" (T-502); and a private-name string used as a test argument sat as a plain literal in a ship-classified test file, so the assembled tree self-matched on it — worse than a noisy false alarm, since that assertion would have PASSED for the wrong reason, reporting a finding that pointed at the test file rather than at the secret the test had planted (T-513). The remedy is the same in every case: describe the pattern in words, never write the literal shape — even inside a comment, inside doc prose, or inside prose about this very rule. When a test genuinely needs a token matching one of the scanner's categories, construct it at runtime (string concatenation/interpolation) so no contiguous literal substring appears in the file text — the same technique already required for adversarial fixtures below. Reading and grepping the file is NOT the verification step, however careful — the only test that counts is running the gate: `node scripts/mavp-publish-assemble.js <tmpdir>` then `node scripts/mavp-publish-scan.js <tmpdir> --private-names "<comma-separated-fake-placeholder-names>"`; zero findings is the only passing result. Sub-agent briefs are a leak vector for the same strings: a sub-agent transcribes brief text into the shipped comments and test headers it writes (the 0.36.0 release shipped a private incident name that way), so a brief describing a real private-project incident must already use the words-not-literals form ("an adopter project", task ids), never the private name itself.

  The private-repo-name category has two properties an author cannot discover by reading this repo, so they are stated here rather than left implicit. First, the list of names the gate checks against is supplied to the scanner at invocation time by the release process and appears in no tracked file — there is nothing to grep in this repo to find out what will match. Second, an entry ending in a hyphen is a family prefix, not a whole-word name: it matches any hyphenated identifier that begins with those letters, case-insensitive, anywhere on the line — so an innocuous abbreviation that merely happens to start with the same letters can trip the gate with no actual private name present anywhere in the file. Because of that, when inventing synthetic identifiers for ship files (fixture filenames, test constants, sample data), prefer neutral, generic segments — e.g. "fixture" or "sample" — over abbreviations lexically adjacent to this project's own naming family: a shorthand chosen purely for brevity is exactly the kind of string most likely to collide with a family prefix by accident, with no actual private name ever written.

  Adversarial fixtures written specifically to exercise the scanner's detection must do one of two things: (a) construct the detectable string at runtime via string concatenation/interpolation so no literal detectable substring appears in the file text (the scanner matches file contents, symlink targets, and tree-relative file paths statically, not runtime values), or (b) live in a file classified `exclude` in `publish-manifest.json` with a one-line reason. For dummy email addresses, use only the RFC 2606 / RFC 6761 reserved example domains (`example.com`, `example.net`, `example.org`) or the reserved TLDs `.invalid`, `.test`, `.example`, `.localhost` — these are allowlisted by the scanner. Never bake a private project name into a shipped file; parameterize it (e.g. via argv, a placeholder, or a config value) instead.

- **Reserved shapes (bounded, not universal)** — the lesson above generalizes: a static matcher keys on a literal string sitting at a specific position (contiguous substring anywhere, for the scanner above; column zero of a line, for the two matchers below), and prose that reproduces that exact position gets caught by the matcher it is merely describing. The rule is deliberately BOUNDED to the shapes enumerated here — a universal "never write a literal that any static matcher detects" is unfollowable, because an author cannot enumerate matchers they do not know exist, and an unfollowable rule trains people to ignore rules. Enumerated shapes and remedies:
  - **Publish-scanner categories** (private/project repo names, absolute `/Users/` paths, credential/token shapes, non-reserved email domains) — see the shipped secret-string discipline clause above for the full detail and remedy.
  - **Line-initial task-heading shape in `BACKLOG.md`/`TASK_STATUS.md`** (a line beginning with `###` followed by `T-` and digits, e.g. as scanned by `getNextTaskId()`'s anchored `/^###\s+T-(\d+)/gm` in `mavp-operator-lib.js` — see the citation clause in `.claude/rules/backlog.md`). Remedy: describe the shape in words, or cite an example task ID mid-line and/or backticked (never as the first characters of a line) — a citation like a backticked, mid-sentence `T-900` example is safe; the same digits typed as the literal first four characters of a line in one of the two artifacts, even inside a fenced code block, is not.
  - **Line-initial skip token in test output** (`SKIP_TOKEN` in `scripts/run-tests.js`, currently the literal `[SKIP]`, matched by `extractSkipLines()` when it is the leading text of a printed line). Remedy: describe the token in words in prose, or construct it at runtime when a test genuinely needs to print it, rather than emitting it as literal leading text on a line.
  - **Task-heading-anchored non-greedy block matcher in a mutating operator script** (a regex, whether a `/.../ ` literal or built via `new RegExp(\`...\`)`, that opens on a task-heading marker and reaches toward a field bullet through a "match any character, non-greedy" gap with no lookahead assertion or literal end-delimiter bounding that gap — the exact shape T-606/T-607/T-608/T-609 replaced nine independently hand-written instances of across four scripts, and that `scripts/test-no-unbounded-block-matchers.js` (T-610) now scans every `scripts/mavp-operator-*.js` file for). Remedy: never hand-write this shape at all — reach for the canonical bounded helpers instead (see the job-to-helper mapping below); when describing the shape in a code comment or doc prose, describe it in words as this entry does, never reproduce it as one contiguous literal pattern.
  - **Evidence-field commit-declaration shape in `TASK_STATUS.md`** (the field key `commit:` followed by whitespace and a hex-looking hash — matched by `extractCommitEntriesFromEvidence()`'s `ENTRY_PATTERN` in `mavp-validator.js`, an unanchored, case-insensitive pattern that scans the WHOLE Evidence field text, not a leading field line, so it fires anywhere the shape appears inside the field, not only at the start of a line). The matcher reads this shape as a declaration of that task's OWN evidence hash regardless of surrounding prose — there is no way, from the matcher's position, to tell "this is my hash" apart from "I am narrating a different task's hash." Quoting another task's historical hash in the key-colon-space-hash form therefore gets misread as the quoting task's own commit, and if that historical hash isn't reachable from a local ref the validator reports `commit_unreachable` against the QUOTING task, not the task the hash actually belongs to. LIVE REPRODUCTION, executed 2026-08-13 during T-627: quoting a prior task's corrected hash in that form produced, at WARNING severity, "T-627 is merged with evidence commit 846b594 but that hash is not reachable from any local ref"; rephrasing the same citation to a bare backticked hash (no key, no colon) returned the validator to Healthy. Remedy: cite a historical hash backticked and bare — never behind the field key.

    Wave-82 gate ruling (T-579 sub-claim (b), now deprecated): loosening the matcher to also accept inline or backticked commit references as declarations is REFUSED. The strict key-colon-space grammar is deliberate, not an oversight — it is the only thing that lets a bare backticked hash serve as a safe citation form at all, precisely because the matcher ignores that form. If the matcher were widened to parse backticked or inline hashes too, every hash appearing anywhere in evidence prose would become a candidate declaration rather than a citation: there would be no remaining syntax left for citing a historical hash without risking exactly the misattribution this entry warns about. That would not narrow the surface T-627's reproduction exposed — it would eliminate the escape hatch and widen it, since historical citation (a routine and necessary practice — evidence blocks regularly reference prior tasks' hashes for context) would have no safe form left to use. The strict grammar stays as-is.

  - **Line-initial corpus-guard marker in a `scripts/test-*.js` file** (`CORPUS_GUARD_MARKER` in `scripts/run-tests.js`, the comment `// mavp-corpus-guard: always-run`, matched when a line of the file's first 40 lines, once trimmed, is exactly that comment). A line equal to it anywhere in that window opts the file into running alongside every `--filter` run, so a test or comment that merely quotes the marker on a line of its own silently becomes an always-run guard. Remedy: in prose and comments describe the marker in words or cite it backticked mid-line; when a test genuinely needs to emit or write the marker as a line (e.g. building a fixture test file), construct it at runtime by string concatenation so no contiguous literal line appears in the test file's own first 40 lines.

  - **Line-initial declared-invariant header in guard and hook-invoked scripts** (the `// mavp-declared-in: <path> :: <anchor>` comment, matched by `scripts/test-enforcer-declared-in.js` within a script's first 40 lines). A stray copy of the header in a comment or fixture claims an anchor the file does not enforce. Remedy: describe the header in words or cite it backticked mid-line; when a test genuinely needs to emit it, build the key by runtime string concatenation so no contiguous literal line appears in the file's own first 40 lines.

  - **Line-initial feedback-note token in `EXECUTION_LOG.md`** (`FEEDBACK_NOTE_PATTERN` and `parseFeedbackNotes()` in `mavp-operator-lib.js`, read by the `--close-session` feedback-capture advisory: a list-item line whose text, after the bullet and an optional date, begins with the framework's feedback-note token — the word `mavp-feedback` followed by a colon). A log entry that merely discusses the convention, with that token as the first text after the bullet and date, is read as a real note and listed for drafting. Remedy: cite the token mid-line in prose and backticked, never as the first text after the bullet.

  This list is extended whenever a new static matcher ships whose detection key is a position-sensitive literal (not merely "any string that looks like X" — those already covered by the publish-scanner category above). Adding a shape here is a doc-only edit; it does not require re-litigating the boundedness rule itself.

- **Corpus-wide guard tests carry the always-run marker** — any new `scripts/test-*.js` whose subject is a set of enumerated real repo files (a scan of the tracked tree or of `scripts/`, which a task can break without touching the test's own name) must carry the corpus-guard marker, the comment `// mavp-corpus-guard: always-run` on a line of its own within the file's first 40 lines (cited here backticked mid-line only), so `scripts/run-tests.js` runs it with every `--filter` and a violation shows up in the worktree instead of on CI after the push. A marked test must finish in roughly 3 seconds or less standalone, since it is added to every filtered run; a slower real-tree check stays unmarked and relies on the wave-close full run. See `docs/core/ORCHESTRATION_RULES.md` — "Test-execution scope (worktree developers)" and the reserved-shape entry below.
- **Fixture git init pins the initial branch** — every `git init` a `scripts/test-*.js` fixture runs must pin the branch (`-b`, `--initial-branch`, or `-c init.defaultBranch=...` in the same argv array), because an unpinned init inherits the host's default and passes locally while failing on a CI runner whose git defaults to `master`. `scripts/test-fixture-git-init-branch-guard.js` runs on every filtered run and fails on a new unpinned instance; adopter-facing demo scripts are out of its scope by construction.
- **Wrapper flag parity** — every flag the canonical `scripts/mavp-operator` dispatches must also be dispatched by the adopter wrapper that `buildBashWrapper()` in `mavp-install.js` generates, or the flag is silently refused in every adopter project (T-685). Adding a flag to one wrapper without the other fails `scripts/test-wrapper-flag-parity.js`; a deliberate one-sided flag needs a named entry in that test's exception list, never a weakened matcher.
- **Version bump touches two files** — a version bump edits both `scripts/mavp-version.js` and `package.json`; a bump to one alone fails `scripts/test-version-sync.js` on every filtered run, and release tooling would otherwise disagree about which version is shipping.
- **Declared-invariant header** — every marked corpus guard and every script the pre-commit and pre-push hooks invoke carries, within its first 40 lines, a line of the form `// mavp-declared-in: <path> :: <anchor>`, where `<path>` is `CLAUDE.md`, a `.claude/rules/*.md` or a `.claude/agents/*.md` file and `<anchor>` is a bold lead occurring verbatim in that file — so a rule enforced mechanically is declared where its breaker reads it, never only in the enforcer. Checked by `scripts/test-enforcer-declared-in.js`; cite the header backticked mid-line in prose, never as line-initial text (see the reserved-shapes list above).
- **Hermetic test env pinning — generated adopter artifacts and home-directory resolution chains** — any test that executes a generated adopter artifact (a wrapper script, a hook command) — or any process whose framework-root resolution consults the home-directory chain — must pin the framework-root environment variable explicitly in the spawn env; never let such a spawn inherit `process.env` unpinned for that purpose. This convention was already practiced in three places before being written down here: `scripts/test-install-hook-merge.js` merges the framework-root env var into its spawn env before invoking hook commands, `scripts/test-close-session-mode.js` pins it across roughly ten separate spawn calls with an explicit "pin it deterministically" comment, and `scripts/test-check-changelog-frozen.js` pins it too. `scripts/test-wrapper-unrecognized-flag.js` was the only test in the suite executing that resolution chain unpinned — class size exactly one — and canonical CI on `main` sat red across two consecutive pushes (2026-08-21) until it was fixed.

  There are two reasons to pin, not one. The obvious one is determinism: the unpinned resolution chain falls back, in order, to an explicit override environment variable, then a canonical per-user install location, then a legacy fallback location — none of which exist on a CI runner, so an unpinned spawn there dies with a module-not-found error while the same test can appear to pass on a machine that happens to have one of those fallback locations already populated. The less obvious, more important reason is fidelity: on a machine where a fallback location does resolve to something real, that something can be a clone of the *published public mirror* rather than the repo actually under test — so the test was silently exercising the mirror's code, not the checkout's own HEAD, and a broken HEAD would then pass locally while only failing (or worse, passing for the wrong reason) once it reached CI. An unpinned test in this shape may not be testing what you think it is testing.

  Related but distinct: any test that invokes the real `mavp-install.js` in a gated mode (fresh install, `--update`, or `--hooks-only`) as a MEANS to obtain a generated file — not as the SUBJECT the test is asserting about — must also pass `--stale-source-ok` on that installer invocation. The behind-upstream guard (`detectBehindUpstreamGuard()` in `mavp-install.js`) performs a live best-effort `git fetch` against the framework source's own upstream and refuses to proceed when that fetch reveals the checkout is now behind — a correct, working-as-designed refusal, but one that makes an otherwise-hermetic test's outcome depend on live git topology and mid-run fetch timing rather than on the behavior the test actually asserts. `test-install-behind-upstream-guard.js` is the sole exemption: it exists specifically to exercise the guard's own refusal path and must never pass the escape hatch.

- **Task-block field access — use the canonical bounded helpers** — several block-access functions coexist in `mavp-operator-lib.js`, and ambiguity about which one to reach for is how the nine pre-T-610 unbounded-matcher instances got hand-written in the first place. Job-to-helper mapping, by name: single-block field access (reading or writing one specific task's own field) goes through `locateTaskBlock()` / `extractBlockField()` / `setBlockField()`, or the `updateTaskField()` composer built on top of them — these are the ONLY sanctioned path, because `locateTaskBlock()` is the one function that establishes a task's own start/end boundary before any read or write happens inside it. `parseAllTaskBlocks()` is the sanctioned path for whole-file enumeration (iterating every task block in a document) and nothing else — never repurposed to locate one specific task's block. `findTaskBlockById()` is a read-only compatibility wrapper over `locateTaskBlock()`, kept for callers that only need the raw block text; never build new write logic on top of it. `mavp-validator.js`'s own section-aware parser is a separate, validator-only domain and is not part of this mapping.

© yahor-punko · Apache-2.0 · yahor-punko/mavericks-os

Similar IDE rules

All IDE rules for Agent setup: memory, context, orchestration →

From the same set16

The whole set →
security-reviewer security-reviewer audits changed code for security issues and reports specific fixes. Use it when work touches API routes, file parsers, authentication, or third-party integrations. CX Codex ★ 121repo stars analyst analyst — a subagent for outside research: libraries, competitor moves, pricing, standards. It returns a structured brief to help you decide, not a pile of links. CX Codex ★ 121repo stars docs docs enforces structural discipline for documentation, agent specifications, and templates. Controls layer imports, manifest logging, and anchor citations. CX Codex +1 ★ 121repo stars exa-researcher exa-researcher searches Exa for external information, recent news, and code examples, then returns sourced findings to the main agent. Use it for research beyond the project codebase. CX Codex ★ 121repo stars qa Validates completed slices against acceptance criteria. Triggers when a developer marks a slice as dev_done or ready_for_qa, catching issues before code review. CX Codex ★ 121repo stars architect Architecture and task decomposition subagent that inspects codebases and prepares structured design briefs before coding begins. CX Codex ★ 121repo stars session-start session-start loads the current Mavericks state at the start of a session or after context is lost, including the active initiative, stage, slices, and next action. CX Codex +1 ★ 121repo stars developer developer — a subagent that writes code exactly to the acceptance criteria from the backlog. It fits when an architect has already split the work into slices and you need a clean implementation. CX Codex ★ 121repo stars

Project sponsors

Companies that keep this analytics open