agentleFS
jbaruchjbaruch/agentic-context-registry/AGENTS.md

agentic-context-registry

AGENTS.md9 starsChanged 2 days agoApache-2.0View on GitHub

Right after cloning, and before starting an agent session, realize the generated agent files. Run it from the repository root. Owners run it without Tessl. When the non-owner install below applies, run that install first, then this command: If you do not own this repository, before making a substantive change in this repository: tessl install appends a tessl-managed include to this tracked file: the heading # Agent Rules <!-- tessl-managed -->, then a line that starts with @ and names…

  • Reads credentials
  • 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 33,315 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 repositoryOne other file it gives its agents.

The file

Show its rules and text

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

100 rules. About 4 are common, 75 are distinctive, and 21 are very specific to this project.

  • ≈4

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈75

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 21

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    If you do not own this repository, before making a substantive change in this repository:

    line 9
  2. Very specific:

    Run tessl install tessl-labs/good-oss-citizen from the repository root, before go run ./cmd/acr realize.

    line 12
  3. Very specific:

    Read and follow CONTRIBUTING.md.

    line 13
  4. Distinctive:

    When asked to create an ACR plugin from an existing repository, or assess whether that repository is compliant, read Plugin authoring.

    line 20
  5. Distinctive:

    Use the manifest contract, schema, and examples as the source requirements.

    line 22
  6. Very specific:

    Check complete skill support files, references, and distribution inventory.

    line 31
  7. Very specific:

    Check CLI availability before using acr validate (pending v0.2.0.

    line 36
  8. Distinctive:

    Never launch agents, commit, rebase, review or merge by hand where a factory step exists.

    line 50
  9. Distinctive:

    When the factory cannot do a step, file the gap at jbaruch/software-factory with the evidence, do the minimum by hand, and tell the user …

    line 51
  10. Very specific:

    If your instructions start with # Assignment:, the factory launched you as a specialist: follow that assignment and ignore this rule.

    line 52
  11. Distinctive:

    Before concurrent repository inspection or writes, worktree or branch lifecycle operations, or cleanup reporting, or relying on any …

    line 64
  12. Distinctive:

    Read explicitly when triggered.

    line 68
  13. Very specific:

    Never @-import the reference.

    line 69
  14. Distinctive:

    Remove only this task's owned worktree through the binding cleanup order.

    line 76
  15. Distinctive:

    Leave the authorized task surface in better shape than you found it

    line 87
  16. Very specific:

    Before branch, commit or CI work, authoring commit messages, reading or handling PR reviews, merges, publication, release-helper lookup, or …

    line 116
  17. Distinctive:

    Do not change CI outside the authorized scope.

    line 125
  18. Distinctive:

    Never skip failing tests or bypass review.

    line 126
  19. Distinctive:

    Never push directly to protected branches outside a binding carve-out.

    line 127
  20. Distinctive:

    Use whatever formatter and linter the project already has configured

    line 138
  21. Distinctive:

    Don't introduce a new formatter without team consensus

    line 139
  22. Distinctive:

    Don't bikeshed style — let the tooling decide

    line 140
  23. Distinctive:

    Run format/lint checks before tests in CI — catch style issues early and cheaply

    line 144
  24. Distinctive:

    Never mix formatting changes with functional changes in the same commit

    line 149
  25. Distinctive:

    If code needs reformatting, do it in a dedicated commit before or after the functional change

    line 150
  26. Distinctive:

    Use consistent indentation (whatever the project standard is)

    line 157
  27. Distinctive:

    Don't mix refactors with features, formatting with bug fixes, or dependency updates with code changes

    line 175
  28. Distinctive:

    If you need to refactor before implementing, that's a separate commit

    line 176
  29. Distinctive:

    Never add a CHANGELOG entry in a PR

    line 183
  30. Distinctive:

    Keep PRs focused — large PRs are hard to review and risky to merge

    line 184
  31. Very specific:

    Before authoring, modifying, reviewing or publishing plugin artifacts in any distribution, or relying on any exception to this rule, read …

    line 195
  32. Distinctive:

    Keep plugin surfaces synchronized.

    line 204
  33. Distinctive:

    Before writing plugin prose or its PR descriptions, judging policy edge cases, debugging directives or auditing rules, or relying on any …

    line 216
  34. Distinctive:

    Keep loaded rules and skills compact.

    line 225
  35. Distinctive:

    Keep unconditional role, authorization and security boundaries in the startup rules.

    line 237
  36. Distinctive:

    Read references explicitly when triggered.

    line 240
  37. Very specific:

    Never load a reference through an @ import.

    line 241
  38. Distinctive:

    Verify complete contract retention in installed-session acceptance.

    line 244
  39. Distinctive:

    Verify the required native reference read in that acceptance.

    line 245
  40. Distinctive:

    Every other rule follows the reference's Structure clause unchanged.

    line 248
  41. Distinctive:

    Before writing code, selecting, installing or changing dependencies and manifests, or relying on a dependency carve-out, or relying on any …

    line 257
  42. Distinctive:

    Never vendor this repository's dependencies.

    line 268
  43. Distinctive:

    Before handling errors, choosing fallbacks, writing or reviewing logging, exception handlers, shell failure paths or process boundaries, or …

    line 278
  44. Distinctive:

    Use catch-all only at an authorized outer boundary.

    line 288
  45. Distinctive:

    Never silently suppress failures.

    line 290
  46. Distinctive:

    Never open issues, pull requests, or discussions, post comments, or apply reactions in repositories the operator does not own unless the …

    line 301
  47. Distinctive:

    When tempted to contribute externally, surface the proposed action to the operator before any API call: name the target repo, the action …

    line 323
  48. Distinctive:

    Wait for an affirmative response.

    line 324
  49. Distinctive:

    Use templates from github/gitignore as a starting point

    line 336
  50. Distinctive:

    Never commit generated files (compiled output, bundled assets, rendered docs)

    line 340
  51. Distinctive:

    If a file can be reproduced from source, it doesn't belong in the repo

    line 341
  52. Distinctive:

    Use meaningful exit codes when the platform supports them

    line 353
  53. Distinctive:

    Don't fail if a directory already exists, a file was already processed, or a resource was already created

    line 358
  54. Very specific:

    Use .coding-policy-disposable/ inside an available native scratchpad for reproducible files and temporary environments.

    line 362
  55. Distinctive:

    Keep deliverables, continuation material, shared files and background-task inputs outside it.

    line 363
  56. Distinctive:

    After relaying the block, act on any such action per its governing rule

    line 384
  57. Distinctive:

    Never push, commit, stash, delete or discard a listed item unasked

    line 389
  58. Distinctive:

    Every other turn opens with the action, no status block

    line 397
  59. Very specific:

    Before working on code, configuring diagnostic engines or handing off code changes, or relying on any exception to this rule, read …

    line 406
  60. Distinctive:

    Use the existing language engine in the editor.

    line 415
  61. Distinctive:

    Run its zero-findings deterministic gate in CI and before handoff.

    line 416
  62. Distinctive:

    Never silence a whole file.

    line 418
  63. Very specific:

    Never commit API keys, tokens, passwords, private keys, or .env files

    line 427
  64. Common:

    If a secret was committed, rotate it immediately — removing the commit is not enough

    line 429
  65. Common:

    Read secrets from environment variables or a secrets manager at runtime

    line 433
  66. Common:

    Never hardcode credentials in source code, config files, or scripts

    line 434
  67. Distinctive:

    Document what each variable is for and where to get the value

    line 439
  68. Common:

    Use pre-commit hooks for secret scanning (e.g., detect-secrets, gitleaks, trufflehog)

    line 444
  69. Distinctive:

    Keep each numbered item to one bounded action, no compound "and then" clause

    line 466
  70. Distinctive:

    Keep a hedge that carries real uncertainty ("might", "perhaps", "possibly")

    line 471
  71. Distinctive:

    No softening, no apology spiral

    line 483
  72. Distinctive:

    No recap, no pleasantries, no closer

    line 488
  73. Distinctive:

    Every other blocker is resolved before merge.

    line 530
  74. Very specific:

    Read all feedback under rules/reviewer-feedback-reading.md.

    line 534
  75. Very specific:

    Before disposing of feedback or merging, the author/release handler still reads every full review body and inline comment through …

    line 549
  76. Distinctive:

    Read every reviewer's review body in full and every inline comment body before judging that any item needs no action

    line 555
  77. Distinctive:

    Never report a reviewer as handled by its state label alone — "COMMENTED (non-blocking)" is not a summary of what the reviewer said

    line 567
  78. Distinctive:

    Before authoring, interpreting or changing rule frontmatter and activation scope, filtering rules from an agent's context, or relying on …

    line 578
  79. Very specific:

    Before authoring skills or references that invoke scripts, or relying on any exception to this rule, read …

    line 602
  80. Very specific:

    Before choosing, authoring or invoking scripts, bounded classifiers and automation, or choosing model reasoning, or relying on any …

    line 621
  81. Distinctive:

    Do not pause to ask a human whether to merge

    line 644
  82. Distinctive:

    Add no option, flag, schema version, fallback, abstraction or extension point without a current caller or an observed failure.

    line 676
  83. Distinctive:

    Prefer deleting code, state and process over adding them.

    line 680
  84. Distinctive:

    Delete code, options and files a change leaves unused in that change.

    line 681
  85. Distinctive:

    Treat issue proposals as suggestions.

    line 687
  86. Distinctive:

    Add no approval gate.

    line 691
  87. Distinctive:

    Consider deletion or authorized policy narrowing before safeguards.

    line 698
  88. Distinctive:

    Keep policy binding until an authorized amendment takes effect.

    line 699
  89. Very specific:

    Before model comparisons, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/review-calibration.md in full.

    line 703
  90. Very specific:

    Before authoring or reviewing skills, references and manifests, or relying on a skill invocation or lookup exception, or relying on any …

    line 715
  91. Very specific:

    Keep SKILL.md an ordered execution plan.

    line 724
  92. Distinctive:

    Use typed cross-skill calls.

    line 725
  93. Distinctive:

    Use the declared script lookup contract.

    line 726
  94. Very specific:

    Before creating, reading, writing, migrating, renaming or removing persistent state artifacts, or relying on any exception to this rule, …

    line 735
  95. Distinctive:

    Verify recalled state against its live source.

    line 745
  96. Distinctive:

    Only the owner migrates.

    line 746
  97. Distinctive:

    Run git fetch origin before the first read — not after the first failure

    line 756
  98. Distinctive:

    Every other task starts from the synced remote default

    line 776
  99. Very specific:

    Before writing or reviewing shipped code, building fixtures, running tests or relying on a test exemption, or relying on any exception to …

    line 785
  100. Distinctive:

    Every shipped module has tests.

    line 794

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

Agent Contribution Requirements

Right after cloning, and before starting an agent session, realize the generated agent files. Run it from the repository root. Owners run it without Tessl. When the non-owner install below applies, run that install first, then this command:

go run ./cmd/acr realize

If you do not own this repository, before making a substantive change in this repository:

  1. Install Tessl if the tessl command is unavailable.
  2. Run tessl install tessl-labs/good-oss-citizen from the repository root, before go run ./cmd/acr realize.
  3. Read and follow CONTRIBUTING.md.
  4. Preserve existing project and agent instructions when realizing generated context.

tessl install appends a tessl-managed include to this tracked file: the heading # Agent Rules <!-- tessl-managed -->, then a line that starts with @ and names .tessl/RULES.md. That include is the session loader for the good-oss-citizen rules, and Tessl may also add a [mcp_servers.tessl] stanza to .codex/config.toml; keep both while you work. A clone without .tessl fails realize with unresolved_include when the include is committed, and the stanza keeps realize printing shared_file_requires_commit. Before you submit, remove only those contributor-local additions: the heading and @ include line from AGENTS.md, and the [mcp_servers.tessl] stanza from .codex/config.toml. Keep all project source and every hook entry, then run go run ./cmd/acr realize again. .agents/registry.lock is committed; realize maintains it, so never restore or prune it as cleanup.

Author or audit an ACR plugin

When asked to create an ACR plugin from an existing repository, or assess whether that repository is compliant, read Plugin authoring. Use the manifest contract, schema, and examples as the source requirements.

  • Audit read-only by default; create or edit files only when requested. Preserve existing instructions, source content, and application structure.
  • Identify the package root and check agent-plugin.yaml, identity, version, declared paths, artifact shapes, activation policies, and hook events. Folder names such as rules/ and skills/ are conventions, not validity requirements.
  • Check complete skill support files, references, and distribution inventory. Separate authored package content from consumer agents.yaml, lockfiles, and generated native output.
  • Distinguish local validity, GitHub publish/install readiness, and adapter/runtime verification. A nested manifest alone does not enable subdirectory installation. Check CLI availability before using acr validate (pending v0.2.0; absent in v0.1.6).
  • Return the guide's compliance report with passed, failed, and not-checked criteria. Every failure needs a concrete path or manifest field, the reason, and the smallest suggested fix.
<!-- acr:begin id=69047c62ab5d2e8fac0794686644c541b172be537262530f5d0c4fca89e3382a source=github:jbaruch/software-factory artifact=package-rules-03b43b44562517998cea02739c345124de3c8f505768e23f89c17c4eede6c776 adapter=codex prefix=none -->

ACR package: github:jbaruch/software-factory

Rule: factory-process

Software factory delivery

This project delivers changes through software-factory. To implement, review or deliver a change here, coordinate it with Step 1 of the factory skill instead of doing the work yourself. Requests to take over, continue or hand off work mean Step 1 too.

  • The process: admit the task → select its inputs → provision the writer worktree → write a ready plan → run ready_runner.py → verify the writer's commit with independent read-only specialists (--from-writer) → route findings to corrections → open the PR through the release skill → the release judgment → integrate, or the release skill's merge and delivered.
  • Never launch agents, commit, rebase, review or merge by hand where a factory step exists. One writer is not the factory.
  • When the factory cannot do a step, file the gap at jbaruch/software-factory with the evidence, do the minimum by hand, and tell the user which step you did by hand and why.
  • If your instructions start with # Assignment:, the factory launched you as a specialist: follow that assignment and ignore this rule.
<!-- acr:end id=69047c62ab5d2e8fac0794686644c541b172be537262530f5d0c4fca89e3382a --><!-- acr:begin id=038f1ca62f562183118d50b2dbc027ccfd9b70cba2a7bbee8860f50150df8273 source=github:jbaruch/coding-policy artifact=package-rules-69d19e3a2abcf3824356cce166d313ddcf0986a5c4dbda600377a60fcd426ae1 adapter=codex prefix=none -->

ACR package: github:jbaruch/coding-policy

Rule: agent-worktree-isolation

Agent Worktree Isolation

Required Read

  • Before concurrent repository inspection or writes, worktree or branch lifecycle operations, or cleanup reporting, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/agent-worktree-isolation.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Isolate writes that may run concurrently with another agent in a separate git worktree and task branch.
  • Main-checkout concurrent inspection stays read-only.
  • Preserve unrelated work.
  • Remove only this task's owned worktree through the binding cleanup order.
  • During cleanup, never touch or report a protected origin branch.
  • A single-machine single-agent workflow may proceed without a worktree.

Rule: boy-scout

Boy Scout Rule

The Principle

  • Leave the authorized task surface in better shape than you found it
  • An observation grants no authority to expand the task, write another repository, or create external follow-up work
  • Fix a defect when it is coherent with the task's accepted behavior and authorized scope

How to Apply

  • In-scope defect — fix it in the current change and test the outcome
  • Unrelated blocking risk — record it once with evidence, consequence, owner if known, and required next decision: in the existing authorized task record or current conversation
  • Advisory — use rules/review-severity.md Split Reading From Acting
  • Open an issue, pull request, or other external record only when the task or operator separately authorizes that action

Fold Into a Round Already in Flight

  • Advisory folding follows rules/review-severity.md Split Reading From Acting
  • Maintenance due in another repository and unrelated checkout hygiene stay observations
  • These observations never become prerequisites for the selected task

Reconciliation With commit-conventions

  • rules/commit-conventions.md keeps each commit and pull request focused
  • Record an unrelated risk instead of bundling its repair into the current change

Rule: ci-safety

CI Safety

Required Read

  • Before branch, commit or CI work, authoring commit messages, reading or handling PR reviews, merges, publication, release-helper lookup, or any CI exception, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/ci-safety.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Do not change CI outside the authorized scope.
  • Never skip failing tests or bypass review.
  • Never push directly to protected branches outside a binding carve-out.
  • Watch every push to its required terminal gates.
  • Helper lookup grants no merge, publication, installation or operator authority.

Rule: code-formatting

Code Formatting

Use the Project's Tools

  • Use whatever formatter and linter the project already has configured
  • Don't introduce a new formatter without team consensus
  • Don't bikeshed style — let the tooling decide

CI Integration

  • Run format/lint checks before tests in CI — catch style issues early and cheaply
  • Format checks should be a separate CI step that runs fast

Separation of Concerns

  • Never mix formatting changes with functional changes in the same commit
  • If code needs reformatting, do it in a dedicated commit before or after the functional change
  • This keeps diffs reviewable and bisectable

Basics

  • Remove trailing whitespace
  • End files with a single newline
  • Use consistent indentation (whatever the project standard is)
  • These should be enforced by editor config or pre-commit hooks, not manual effort

Rule: commit-conventions

Commit Conventions

Commit Messages

  • Imperative mood in the subject line: "Add feature", not "Added feature" or "Adds feature"
  • Subject line ~50 characters; hard limit at 72
  • Body explains why, not what — the diff shows what changed
  • Separate subject from body with a blank line

One Change Per Commit

  • Each commit represents one logical change
  • Don't mix refactors with features, formatting with bug fixes, or dependency updates with code changes
  • If you need to refactor before implementing, that's a separate commit

Pull Requests

  • CI must pass before merging — sole exception: rules/ci-safety.md Bootstrap-Red Carve-Out
  • PR title follows <type>(<scope>): <imperative summary> format
  • The PR title is the changelog line
  • Never add a CHANGELOG entry in a PR
  • Keep PRs focused — large PRs are hard to review and risky to merge

Rule: context-artifacts

Apply only when a working path matches: .tessl-plugin/plugin.json, agent-plugin.yaml, rules/, skills/, .tesslignore, CHANGELOG.md, README.md

Context Artifacts

Required Read

  • Before authoring, modifying, reviewing or publishing plugin artifacts in any distribution, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/context-artifacts.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Keep plugin surfaces synchronized.
  • Validate and review every applicable distribution before publication.

Rule: context-writing-style

Apply only when a working path matches: rules//*.md, skills//SKILL.md, README.md, CHANGELOG.md

Context Writing Style

Required Read

  • Before writing plugin prose or its PR descriptions, judging policy edge cases, debugging directives or auditing rules, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/context-writing-style.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Keep loaded rules and skills compact.
  • Retain binding constraints.
  • Move detail to explicitly read references.

Full-Contract Task Router

  • Narrow exception for a full-contract task router.
  • Applies when a rule routes its complete single-concept contract to a co-shipped skill reference.
  • Preconditions (all required):
    1. Preserve the rule's applicability, title and affected-action trigger.
    2. Require the full reference before every affected action, including reliance on an exception.
    3. Preserve every original directive, carve-out trigger, applies-when clause, precondition, pointer and reset in the reference.
    4. Keep unconditional role, authorization and security boundaries in the startup rules.
    5. Resolve the reference within its owning installed plugin.
    6. Missing or unreadable content stops the affected action.
    7. Read references explicitly when triggered.
    8. Never load a reference through an @ import.
    9. Package every reference in each distribution.
    10. Retain trust-boundary review coverage.
    11. Verify complete contract retention in installed-session acceptance.
    12. Verify the required native reference read in that acceptance.
  • A qualifying router may use two H2 sections and fewer than 25 lines.
  • A qualifying router keeps one whole-contract read gate instead of repeating the moved carve-out catalog.
  • Every other rule follows the reference's Structure clause unchanged.

Rule: dependency-management

Dependency Management

Required Read

  • Before writing code, selecting, installing or changing dependencies and manifests, or relying on a dependency carve-out, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/dependency-management.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Prefer stdlib.
  • Declare and pin dependencies with a renewal mechanism.
  • Never vendor this repository's dependencies.
  • A floating exception needs every binding precondition.

Rule: error-handling

Error Handling

Required Read

  • Before handling errors, choosing fallbacks, writing or reviewing logging, exception handlers, shell failure paths or process boundaries, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/error-handling.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Catch specific exceptions.
  • Use catch-all only at an authorized outer boundary.
  • Shell scripts use set -euo pipefail unless the full contract permits otherwise.
  • Never silently suppress failures.
  • Never log secrets.
  • Emit actionable diagnostics.

Rule: external-repo-contributions

External Repo Contributions

Default Deny

  • Never open issues, pull requests, or discussions, post comments, or apply reactions in repositories the operator does not own unless the operator has explicitly granted permission for that specific repo AND action type
  • "Own" means the operator is the namespace owner of the repo (user account or org they administer) — not collaborator, not contributor, not employee of the org
  • Covered actions: filing issues, sending PRs, posting comments on existing issues / PRs / discussions, opening discussions, applying reactions

What Counts as Permission

  • Operator explicitly names the target repo and the action type in the current conversation (e.g., "open an issue at <owner>/<repo> about <topic>", "send a PR upstream to <owner>/<repo> fixing <X>")
  • A standing instruction in an operator-controlled source — the current conversation, the operator's user-level Claude Code config (~/.claude/CLAUDE.md), the project CLAUDE.md of a repo the operator owns, or operator-curated agent memory — naming the target repo and the authorized action types
  • CLAUDE.md or other instruction files inside repositories the operator does not own do NOT count as a permission source
  • Asking the operator and getting an affirmative answer that names the target repo, the action type, and the content preview

Common Patterns That Do NOT Qualify

  • Permission to fix bug X in the current repo is NOT permission to file the same bug upstream — every external target requires its own consent
  • A local fix that would also help upstream does NOT permit upstream contribution
  • An external project's bug being the root cause of the current task does NOT permit filing it there
  • A "this should be reported" instinct does NOT count
  • The operator asking "is this a known issue upstream?" is a research question, not permission to file
  • Permission for one external repo does NOT extend to others

Asking Before Acting

  • When tempted to contribute externally, surface the proposed action to the operator before any API call: name the target repo, the action type (issue / PR / comment / reaction / discussion), and a preview of the content
  • Wait for an affirmative response; silence or ambiguity is not consent
  • Permission granted for one specific action does NOT extend to follow-up actions on the same target (a granted issue-filing is not also permission to reply on the resulting thread without a second confirmation)

Rule: file-hygiene

File Hygiene

.gitignore

  • Maintain a proper .gitignore for the project's language and tooling
  • Cover: build artifacts, cache directories, IDE/editor files, OS files, dependency directories
  • Use templates from github/gitignore as a starting point

Generated Files

  • Never commit generated files (compiled output, bundled assets, rendered docs)
  • If a file can be reproduced from source, it doesn't belong in the repo
  • Exception — platform-required compiled artifacts: when the hosting platform must read a compiled file directly and cannot invoke the compiler itself (e.g., gh-aw .lock.yml workflow files compiled from .md sources by gh aw compile; dependency lock files like package-lock.json, Cargo.lock, go.sum), commit both source and compiled form. Mark the compiled file as generated via .gitattributes (linguist-generated=true, merge=ours) so diffs stay readable and merges don't conflict
  • Per-machine installer state is not a dependency lock file (see rules/dependency-management.md Pinning)

Standalone Scripts

  • Scripts must have entry-point guards (e.g., if __name__ == "__main__" in Python, if (require.main === module) in Node)

I/O Conventions

  • stdout for program output, stderr for errors and diagnostics
  • Exit 0 on success, non-zero on failure
  • Use meaningful exit codes when the platform supports them

Idempotency

  • Scripts should be safe to run multiple times
  • Don't fail if a directory already exists, a file was already processed, or a resource was already created

Session Scratchpads

  • Use .coding-policy-disposable/ inside an available native scratchpad for reproducible files and temporary environments.
  • Keep deliverables, continuation material, shared files and background-task inputs outside it.
  • SessionEnd cleanup follows .codex/skills/acr__jbaruch__coding-policy__release/hooks/session-end-cleanup.py's contract.

Rule: hook-action-reporting

Hook Action Reporting

Surface the Status

  • A SessionStart hook emits an additionalContext payload beginning with Session-start status — only when it has a status to report
  • Many outcomes emit nothing (non-repo, no matching dependency)
  • At session start, collect every such payload the context carries (there may be none) and relay each in full as one block, before the first substantive action
  • A payload may span several lines, a marker line plus continuation lines such as an update list or a NOTE:
  • Relay the whole payload, never only its marker line
  • Report the block once per session, at the start, never repeating it every turn
  • Relay the payloads verbatim, without padding or restating them as your own analysis

Act on What It Names

  • A payload may name an action: a branch to sync, a pinned dependency to fix, an update that failed
  • After relaying the block, act on any such action per its governing rule
  • An all-green status needs only the report, no further action
  • A status may list worktrees and branches awaiting an operator decision
  • Raise each listed item with the user, one question at a time
  • Offer the choices push, commit, open a pull request, delete, or keep
  • Never push, commit, stash, delete or discard a listed item unasked

Reconciliation With response-clarity

  • Narrow exception for the session-start status block to rules/response-clarity.md Lead With the Action
  • Preconditions (all required):
    1. The block appears once per session, at the start, before the first substantive action
    2. It carries only the Session-start status — payloads, nothing else
  • Every other turn opens with the action, no status block

Rule: language-diagnostics

Language Diagnostics

Required Read

  • Before working on code, configuring diagnostic engines or handing off code changes, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/language-diagnostics.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Use the existing language engine in the editor.
  • Run its zero-findings deterministic gate in CI and before handoff.
  • Fix findings or attach a stated-cause inline suppression.
  • Never silence a whole file.

Rule: no-secrets

No Secrets

Never Commit Secrets

  • Never commit API keys, tokens, passwords, private keys, or .env files
  • This includes test/development credentials — they tend to leak into production
  • If a secret was committed, rotate it immediately — removing the commit is not enough

Use Environment Variables or Secrets Managers

  • Read secrets from environment variables or a secrets manager at runtime
  • Never hardcode credentials in source code, config files, or scripts

Document Required Variables

  • Maintain a .env.example file listing every required environment variable with placeholder values
  • Document what each variable is for and where to get the value
  • For hosted-CI secrets, include a deep link to the platform's secrets configuration page in the file header so a new maintainer can reach the settings page in one click (GitHub Actions: https://github.com/<owner>/<repo>/settings/secrets/actions; GitLab CI: https://gitlab.com/<group>/<project>/-/settings/ci_cd)

Pre-commit Scanning

  • Use pre-commit hooks for secret scanning (e.g., detect-secrets, gitleaks, trufflehog)
  • Block commits that contain patterns matching secrets

Logging

  • Never log secrets — not at any log level, not in error messages, not in stack traces
  • Sanitize or redact sensitive values before they reach any logging or monitoring system

Rule: response-clarity

Response Clarity

Scope

  • Governs the agent's live responses to the user, not context artifacts (rules, skills, READMEs — those follow rules/context-writing-style.md)
  • Applies every turn, in every session

Lead With the Action

  • Open with the command, edit, or answer — never context, preamble, or restated question
  • Number multi-step work
  • Keep each numbered item to one bounded action, no compound "and then" clause
  • Cap an unranked list at 5 items
  • Split a longer list into "do now" and "later" tiers
  • Defer secondary issues — finish the primary problem, then offer the rest as separate follow-ups
  • Cut hedging adverbs that carry no uncertainty ("basically", "essentially", "practically")
  • Keep a hedge that carries real uncertainty ("might", "perhaps", "possibly")
  • Replace an idiom or figurative phrase ("circle back", "on the same page") with the literal action

Show State and Progress

  • Restate progress across turns: "Step 3 of 5 done: schema updated. Next: backfill the column"
  • Make a win concrete and verifiable — name what works and the command that shows it
  • Give a concrete time ballpark ("~15 minutes if tests exist"), never vague "some work"

Report Errors Plainly

  • State a failure matter-of-fact: what failed, where, expected versus actual
  • No softening, no apology spiral

Close With One Next Step

  • End with one concrete action the user can take in two minutes or less
  • No recap, no pleasantries, no closer
  • End when the answer is done

Exceptions

  • Explanation requested — give full detail, still no preamble
  • Destructive or irreversible action — add a confirmation step before running it
  • Debug spiral — ask one diagnostic question instead of guessing
  • Genuine ambiguity with no obvious default — ask one clarifying question, then proceed

Rule: review-severity

Review Severity

Categories and Evidence

  • Prefix messages with [defect], [policy mismatch] or [optional hardening].
  • Defects require a concrete trigger, reachable path and material consequence.
  • Policy mismatches cite binding clauses and source.
  • Identify unproven harm as unproven.
  • Optional hardening adds safeguards without a demonstrated defect or obligation.

Severity and Remedy

  • Blocking: substantiated material defects, tests concealing them, or binding obligations affecting meaning or behavior.
  • Advisory: optional hardening and presentation-only suggestions.
  • A behavior-changing suggestion alone never establishes a blocker.
  • Resolve mismatches through compliant code or authorized policy amendment and re-review.
  • Reviewers cannot waive policy.
  • Apply rules/simplicity.md to remedy cost and scope.

Merge Gate

  • Any blocker → CHANGES_REQUESTED; otherwise APPROVED or COMMENTED.
  • Retain both independent review gates.

Judge-Weighed Finding Carve-Out

  • Narrow exception for merging with a blocking policy finding a weighing ruled defer or decline.
  • Applies only when fixing costs more than the failure it prevents.
  • Preconditions are binding: read .codex/skills/acr__jbaruch__coding-policy__release/references/review-severity-carve-outs.md Judge-Weighed Finding Carve-Out before relying on it.
  • Every other blocker is resolved before merge.

Split Reading From Acting

  • Read all feedback under rules/reviewer-feedback-reading.md.
  • Advisory → note it directly in the existing review conversation or authorized task record.
  • Fold advisories into required same-surface fixes only without another push or check round.
  • Advisories require no push, review round, issue, PR or delivery prerequisite.

Rule: reviewer-feedback-reading

Reviewer Feedback Reading

Independent Review Context

  • This contract governs feedback disposition and release readiness
  • An independent read-only review may use a bounded historical index to locate contracts and prior source identities; an index never disposes of feedback or establishes that it needs no action
  • A fresh current-head review assesses current source independently; its verdict does not claim prior feedback was read or handled
  • Before disposing of feedback or merging, the author/release handler still reads every full review body and inline comment through .codex/skills/acr__jbaruch__coding-policy__release/poll-pr-reviews.sh and GitHub's original feedback; omitted or unavailable index entries remain unread

State Classifies Gating, Not Reading

  • A review's state (APPROVED, CHANGES_REQUESTED, COMMENTED) classifies whether the review gates the merge — it never classifies whether the review's content must be read
  • COMMENTED and "non-blocking" describe the merge gate, never permission to skip the review body
  • Read every reviewer's review body in full and every inline comment body before judging that any item needs no action
  • A COMMENTED review with zero inline comments still carries a body that must be read
  • State classifies gating, severity classifies acting, neither classifies reading — read all, then act per rules/review-severity.md

Read the Text, Not the Tally

  • Review states and inline-comment counts are loop-control and gate signals, never a substitute for the words a reviewer wrote
  • Fetch the actual review body and inline comment text; conclude an item is non-blocking only after reading it
  • "Non-blocking" is a conclusion reached after reading, never a reason to not read

Report the Substance

  • Never report a reviewer as handled by its state label alone — "COMMENTED (non-blocking)" is not a summary of what the reviewer said
  • Name each reviewer whose body you read and summarize the content, not the classification
  • Lumping reviewers under one state label hides unread feedback — account for each reviewer's body separately

Rule: rule-frontmatter

Rule Frontmatter

Required Read

  • Before authoring, interpreting or changing rule frontmatter and activation scope, filtering rules from an agent's context, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/rule-frontmatter.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • A host may omit a conditional rule from an agent's context.
  • Tiers run cheapest first, host script, then bounded classifier, then reasoning model.
  • Each undecided case fails safe to inclusion.
  • An undecided rule may load on demand from its path and verbatim frontmatter.
  • Included rules keep their bytes and frontmatter unchanged.

Rule: script-as-black-box

Apply only when a working path matches: skills//SKILL.md, skills//*.md

Script as Black Box

Required Read

  • Before authoring skills or references that invoke scripts, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/script-as-black-box.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Describe inputs, outputs, failures and side effects.
  • The script owns internal thresholds, predicates and allowlists.

Rule: script-delegation

Script Delegation

Required Read

  • Before choosing, authoring or invoking scripts, bounded classifiers and automation, or choosing model reasoning, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/script-delegation.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Deterministic logic uses executable scripts.
  • Bounded classification needs its approved bounds.
  • Reasoning stays with the model.
  • Classification approval waives no unrelated gate.
  • It grants no authority for third-party communication, data deletion or merge.

Rule: ship-on-green

Ship on Green

Green Gate Is the Approval

  • Required checks green and none of the exits below apply ⇒ merge. The green gates ARE the approval
  • Do not pause to ask a human whether to merge
  • Flag, confirm, "say go and I'll", "worth one confirmation", "want me to?" are asking in a costume — each resolves to asking, and asking IS the decision to not ship
  • Governs every merge, whether or not skills/release was invoked — an agent running the flow by hand is bound identically

Stakes Raise Care, Not Permission

  • Scary, wide-reaching, always-on, ships-to-prod, deletes-a-thing ⇒ verify harder — more tests, tighter review, a pristine-checkout lint
  • A change being high-impact is never itself an exit — stakes buy care, never permission

The Three Exits Are Exhaustive

  • Merge is blocked only by one of these three, each with a literal test — no fourth exit, no vibe word:
  • Red — a required check is failing or pending. Not "I feel uneasy"
  • No undo — git revert cannot restore it: force-push over protected history, an immutable published artifact, deleted data, sent external comms. A supersedable version bump is undoable; shipping to prod is NOT "no undo"
  • Murky — the task's own source states 2+ conflicting options AND names no default. Source names a default ⇒ take it, never murky

Relationship to Other Rules

  • .codex/skills/acr__jbaruch__coding-policy__release/SKILL.md Step 7 references this rule for the merge decision rather than restating it
  • The release contract's watch and verify steps (rules/ci-safety.md) feed the Red test; they add no fourth exit
  • Advisory findings never gate (rules/review-severity.md), so an unaddressed advisory does not make a gate Red

Rule: simplicity

Simplicity

KISS and YAGNI

  • Choose the simplest design that solves the stated problem today.
  • Build nothing for a need nobody has today.
  • Overengineering is forbidden.
  • Add no option, flag, schema version, fallback, abstraction or extension point without a current caller or an observed failure.
  • One caller gets no abstraction.
  • One value gets no setting.
  • Future consumers justify no machinery.
  • Prefer deleting code, state and process over adding them.
  • Delete code, options and files a change leaves unused in that change.

Before Implementation

  • State problem and smallest sufficient solution in conversation or PR.
  • Try scoped instructions, agent actions, platform behavior or deletion before automation.
  • Treat issue proposals as suggestions; explain simpler options' gaps before adopting machinery.
  • Justify custom state, recovery, coordination and abstractions with requirements and platform gaps.
  • Weigh maintenance, rollout and failures against likelihood and impact.
  • Explain briefly.
  • Add no approval gate.

During Review

  • Apply rules/review-severity.md.
  • Flag machinery added without the justification above as a [policy mismatch] against this rule.
  • Recommend smallest sufficient remedy.
  • Consider deletion or authorized policy narrowing before safeguards.
  • Keep policy binding until an authorized amendment takes effect.

Calibration

  • Before model comparisons, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/review-calibration.md in full.
  • Calibrate on demand, never as a merge gate.

Rule: skill-authoring

Apply only when a working path matches: skills//SKILL.md, skills//*.md, .tessl-plugin/plugin.json, agent-plugin.yaml

Skill Authoring

Required Read

  • Before authoring or reviewing skills, references and manifests, or relying on a skill invocation or lookup exception, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/skill-authoring.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Keep SKILL.md an ordered execution plan.
  • Use typed cross-skill calls.
  • Use the declared script lookup contract.

Rule: stateful-artifacts

Stateful Artifacts

Required Read

  • Before creating, reading, writing, migrating, renaming or removing persistent state artifacts, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/stateful-artifacts.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Require an owner, versioned schema and reader/writer contract.
  • Verify recalled state against its live source.
  • Only the owner migrates.

Rule: sync-before-work

Sync Before Work

Sync Before Reading

  • At the start of any task that will read or modify a repo, sync the local checkout with the remote default branch
  • Run git fetch origin before the first read — not after the first failure
  • The default branch you start from must match what the remote currently has, not whatever the local clone was left at

Land on the Fresh Default

  • On the default branch: fast-forward to origin/<default>
  • Local default diverged or stale: rebase or reset onto origin/<default> before branching
  • Cut the feature branch from the synced default, never from a stale local tip

Staleness Poisons Conclusions

  • Local default behind origin/<default> by more than a trivial amount: treat every "this file looks like X" conclusion as suspect until re-derived against the fresh tree
  • An issue naming files, skills, or steps absent from the local tree is a staleness tell — fetch and re-derive before mapping the work onto what you see

Working Against a Pinned Ref

  • Narrow exception for starting work from a specific older ref instead of the fresh default
  • Preconditions (all required):
    1. The user explicitly names the older ref or commit to work against
    2. You state you are starting from that pinned ref rather than origin/<default>
  • Every other task starts from the synced remote default

Rule: testing-standards

Testing Standards

Required Read

  • Before writing or reviewing shipped code, building fixtures, running tests or relying on a test exemption, or relying on any exception to this rule, read .codex/skills/acr__jbaruch__coding-policy__coding-contracts/references/testing-standards.md in full.
  • Its full text and named sections bind as rule content.
  • Resolve the reference within its owning installed plugin.
  • Missing or unreadable content stops the affected action until the plugin is repaired.
  • Read explicitly when triggered.
  • Never @-import the reference.

Boundary

  • Every shipped module has tests.
  • Assert outcomes with fixed independent fixtures.
  • Keep tests deterministic.
  • A test exemption needs every binding precondition.
<!-- acr:end id=038f1ca62f562183118d50b2dbc027ccfd9b70cba2a7bbee8860f50150df8273 -->

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.