agentleFS
Sign inStart free
kartikkabadikartikkabadi/grok-brownfield/AGENTS.md

grok-brownfield

AGENTS.md2 starsChanged 5 months agoMITView on GitHub

Brief guidance for AI agents editing grok-brownfield. When changing normative transport or phase behavior in SKILL.md, apply all four steps in order: Skip step 4 only for purely internal wiring with no contributor or end-user visibility. Always run from repo root: Fix failures before committing. Negative tests intentionally mutate copies under mktemp — do not skip them. Do not duplicate the entire skill in README; link to SKILL.md for internals.

  • 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,774 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

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

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

  • ≈1

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep phase numbering consistent (0 → 6, plus 2a, 4b)

    line 13
  2. Very specific:

    When adding normative behavior, add a matching pattern to scripts/verify_skill.sh

    line 16
  3. Very specific:

    When changing normative transport or phase behavior in SKILL.md, apply all four steps in order:

    line 20
  4. Distinctive:

    Always run from repo root:

    line 31
  5. Very specific:

    Do not duplicate the entire skill in README.

    line 45
  6. Common:

    No tokens or credentials in messages or files

    line 50
  7. Very specific:

    Commit /tmp/grok-* state or design drafts

    line 56

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

Agent instructions (contributors)

Brief guidance for AI agents editing grok-brownfield.

Scope

  • In scope: SKILL.md, scripts/verify_skill.sh, tests/test_verify_skill.sh, README.md, CONTRIBUTING.md
  • Out of scope: ~/.grok/bundled/skills/ (separate bundle), user /tmp artifacts, secrets

Editing SKILL.md

  1. Preserve frontmatter keys: name, description, when-to-use, argument-hint, compatibility
  2. Keep phase numbering consistent (0 → 6, plus 2a, 4b)
  3. Tool-call discipline section is normative — do not weaken anti-hallucination rules
  4. Resume path validation (brownfield_id, workspace_root, artifact allowlist) must stay strict
  5. When adding normative behavior, add a matching pattern to scripts/verify_skill.sh

Protocol-update checklist

When changing normative transport or phase behavior in SKILL.md, apply all four steps in order:

  1. SKILL.md — encode the normative section (e.g. Context Budget Protocol, Phase 1b columns, Delegation prompt rule). Cite line ranges; do not inline the full skill in prompts.
  2. scripts/verify_skill.sh — add or update anchored grep patterns that fail if the section is removed or hollowed out.
  3. tests/test_verify_skill.sh — add a negative test that strips the section and expects verify failure (pattern: NO_CONTEXT_BUDGET).
  4. README.md — update mermaid, deliverables, or workflow description if the change is user-facing (phases, flags, context budget, artifacts).

Skip step 4 only for purely internal wiring with no contributor or end-user visibility.

Verification workflow

Always run from repo root:

bash scripts/verify_skill.sh
bash tests/test_verify_skill.sh

Fix failures before committing. Negative tests intentionally mutate copies under mktemp — do not skip them.

README vs SKILL.md

  • README.md — human-facing GitHub landing (install, examples, tables, mermaid)
  • SKILL.md — full orchestrator spec for Grok at runtime

Do not duplicate the entire skill in README; link to SKILL.md for internals.

Git

  • One logical change per commit when possible
  • No tokens or credentials in messages or files
  • Public repo: kartikkabadi/grok-brownfield

Do not

  • Reference internal hostnames (e.g. internal.example.com, <org>-internal) in examples
  • Commit /tmp/grok-* state or design drafts
  • Change verify scripts to pass on a weakened skill without updating tests intentionally

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.

Reviews can't be read right now.

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