agentleFS
sagarchauhan005sagarchauhan005/agent-sage/Agents.md

agent-sage

AGENTS.md0 starsChanged 5 months agoMITView on GitHub

Sage is your SDLC agent orchestration system. Agents.md is the root contract. Every Sage agent reads this file first, then loads its role file from agents/. Cursor skills in .cursor/skills/ must match this registry. Add or remove a skill in the same change as its agent file.

  • Reads credentials

The file

Show its rules and text

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

70 rules. About 3 are common, 55 are distinctive, and 12 are very specific to this project.

  • ≈3

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈55

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 12

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run artifacts live in runs/<run-id>/.

    line 86
  2. Very specific:

    Every phase agent reads runs/.current first to resolve <run-id>.

    line 93
  3. Very specific:

    If the user names a run explicitly, use that instead and update runs/.current to match.

    line 94
  4. Very specific:

    If the project already has code, do not recommend or suggest a language.

    line 110
  5. Distinctive:

    When there is no existing codebase (or the user explicitly asked for greenfield), the planner may recommend a stack in Plan mode:

    line 114
  6. Very specific:

    If still tied — backend preference order: PHP → Node.js.

    line 117
  7. Distinctive:

    Do not recommend Python for greenfield projects.

    line 120
  8. Very specific:

    Use the latest stable PHP and Node.js runtime versions in Docker, CI, and local tooling.

    line 136
  9. Distinctive:

    If a project AGENTS.md or lockfile contradicts this table, follow the project.

    line 153
  10. Distinctive:

    Do not generate any unwarranted or not-asked markdown file to summarize or document an action taken unless asked explicitly to do so

    line 157
  11. Distinctive:

    Do not create unnecessary .sh or shell scripts for every automation unless required and asked explicitly

    line 160
  12. Very specific:

    Always write the plan to runs/<run-id>/plan.md (exception to documentation folder rule).

    line 168
  13. Very specific:

    Start from runs/_plan-template.md.

    line 170
  14. Distinctive:

    All UI/UX design should be made in Shadcn or Tailwind only for any small module, or large feature

    line 175
  15. Distinctive:

    All error states should have clear focus on message and not allow user to get distracted from the message at any times

    line 176
  16. Distinctive:

    Do not push the code to main branch without confirmation

    line 182
  17. Distinctive:

    Always remember the idea is not just build anything but to learn also, so all your summaries should make sure that it teaches me something …

    line 186
  18. Distinctive:

    If the change or feature make edits to both backend and front-end, update the tests for both or write if not available

    line 187
  19. Distinctive:

    Every now and then run both backend and frontend tests to keep checking if all functionalties are working fine or not.

    line 188
  20. Distinctive:

    All functionalities and design should be mobile and tablet friendly always, make decisions to prioritize this always

    line 196
  21. Distinctive:

    All links for images, files or any static assets should always be referenced from a common config, array or some json that is easy to …

    line 198
  22. Distinctive:

    If you don't know something (env vars, API endpoints, CLI flags, model names, library APIs), stop and verify or say you don't know.

    line 214
  23. Distinctive:

    Don't say a task is done until typechecks, linters, and tests pass.

    line 216
  24. Distinctive:

    When renaming a function, type, or variable, search separately for: direct references, type-level references, string literals containing …

    line 217
  25. Distinctive:

    Follow these style guidelines in chat, commit messages, and prose:

    line 221
  26. Distinctive:

    Don't oversell the changes.

    line 224
  27. Distinctive:

    Don't use fancy words like "comprehensive", "utilize", "implement", "exhaustive", "simplify", "optimize", "seamlessly"

    line 225
  28. Distinctive:

    When writing markdown, avoid using headings smaller than H2

    line 226
  29. Distinctive:

    When writing markdown, don't use bold.

    line 227
  30. Distinctive:

    When writing markdown tables, pad cells with spaces so columns align.

    line 228
  31. Distinctive:

    Never use em dashes (—). Use commas, colons, or separate sentences instead.

    line 229
  32. Distinctive:

    If multiple interpretations of a request exist, present them, don't pick silently.

    line 235
  33. Distinctive:

    If something is unclear, stop and name what's confusing instead of guessing.

    line 236
  34. Distinctive:

    Write the minimum code that solves the problem.

    line 237
  35. Distinctive:

    Don't add error handling for impossible scenarios.

    line 238
  36. Distinctive:

    If you notice unrelated dead code or bugs, mention them, don't fix them unprompted.

    line 241
  37. Distinctive:

    Prefer types over prose documentation for API contracts.

    line 246
  38. Distinctive:

    Use schema-first design: the schema defines the contract, and the implementation conforms to it.

    line 248
  39. Distinctive:

    If an API is too complex to type, that's a design problem worth fixing.

    line 251
  40. Distinctive:

    If the project has a "scripts" or "script" directory, run those scripts for tasks like testing, linting, formatting, etc.

    line 255
  41. Very specific:

    If the project has a script/lint or scripts/lint script, run it before committing changes with Git.

    line 256
  42. Distinctive:

    If linting fails, fix the linting errors and run the linter until all the errors are resolved.

    line 257
  43. Distinctive:

    When creating git commits, always use a semantic commit prefixes, with or without parenthetical qualifiers.

    line 261
  44. Distinctive:

    When opening pull requests or merge requests, always use a semantic commit message as the title.

    line 262
  45. Very specific:

    Never bypass pre-commit hooks.

    line 263
  46. Very specific:

    Use gh for GitHub repositories and glab for GitLab repositories.

    line 267
  47. Distinctive:

    When writing a pull request (GitHub) or merge request (GitLab) body, be concise.

    line 268
  48. Distinctive:

    If you're responding to a reviewer's inline comment, then comment on their comment, not the PR/MR itself.

    line 270
  49. Distinctive:

    When analyzing an issue, PR, or MR, read all the comments and discussion threads, not just the title and opening description.

    line 271
  50. Distinctive:

    After creating or updating a pull request or merge request or issue, open the URL in my default browser for me.

    line 272
  51. Very specific:

    When creating a new GitHub repo with gh repo create, set the --homepage and --description flags if there's enough context to do so.

    line 273
  52. Distinctive:

    Follow these guidelines when writing the body of the pull request:

    line 277
  53. Distinctive:

    Start the PR body with the words "This PR..."

    line 282
  54. Distinctive:

    Do not include a "Summary" heading

    line 283
  55. Distinctive:

    Do not mention the test plan

    line 284
  56. Distinctive:

    If there is a Linear ticket or GitHub issue, include a link to the ticket or issue in the PR body.

    line 285
  57. Distinctive:

    If there is a GitLab issue, include a link to the issue in the MR body.

    line 286
  58. Distinctive:

    If you make web requests to public pages and get blocked by sites like OpenAI's docs pages returning 403 status codes, use other methods to …

    line 290
  59. Distinctive:

    Use the following tools for browser automation tasks:

    line 294
  60. Distinctive:

    Always first use the agentic tool built in browser automation to test things end to end by yourself only

    line 296
  61. Distinctive:

    When using the Chrome DevTools MCP, check for an existing tab already on the relevant page before opening a new one.

    line 301
  62. Common:

    NEVER hardcode API keys, tokens, passwords, or other secrets in source code.

    line 306
  63. Common:

    Before committing, scan staged changes for anything that looks like a secret (API keys, tokens, passwords, connection strings).

    line 307
  64. Common:

    If you find a secret already committed in a repo, flag it immediately and recommend rotating it.

    line 309
  65. Distinctive:

    Don't push commits to branches with PRs that have already been merged.

    line 315
  66. Distinctive:

    When I correct you, push back, or express frustration, after you finish the immediate task, propose a one-line addition or edit to the …

    line 325
  67. Distinctive:

    Before proposing, search the relevant AGENTS.md for an existing rule that covers this.

    line 328
  68. Distinctive:

    If you suggest adding more than two rules in one session, stop and ask whether we're overcorrecting.

    line 331
  69. Distinctive:

    When an AGENTS.md grows past about 200 lines, propose deletions or consolidations alongside additions, not just additions.

    line 332
  70. Distinctive:

    If I ask you to "audit AGENTS.md", read the whole file and propose a list of rules to delete because they're obsolete, duplicated, or never …

    line 333

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

Sage — Agent System

Sage is your SDLC agent orchestration system. Agents.md is the root contract. Every Sage agent reads this file first, then loads its role file from agents/.

Agent registry

PhaseAgentRole fileSlash command
OrchestrateSage Orchestratoragents/sage-orchestrator.md/sage-orchestrator
ProfilesWorkflow profilesworkflows/profiles.mdset in manifest
1 PlanSage Planneragents/sage-planner.md/sage-plan
2 DesignSage Designeragents/sage-designer.md/sage-design
3 ArchitectSage Architectagents/sage-architect.md/sage-architect
4 BuildSage Engineeragents/sage-engineer.md/sage-engineer (alias /sage-build)
5 VerifySage QAagents/sage-qa.md/sage-qa
6 PackageSage DevOpsagents/sage-devops.md/sage-devops
7 ShipSage Releaseagents/sage-release.md/sage-release
StatusSage Statusagents/sage-orchestrator.md/sage-status
HandoffSage Handoffagents/_handoff-template.md/sage-handoff
InitSage Initagents/sage-init.md/sage-init

Skills mirror

Cursor skills in .cursor/skills/ must match this registry. Add or remove a skill in the same change as its agent file.

Skill folderSlash commandAgent file
sage-orchestrator/sage-orchestratoragents/sage-orchestrator.md
sage-plan/sage-planagents/sage-planner.md
sage-design/sage-designagents/sage-designer.md
sage-architect/sage-architectagents/sage-architect.md
sage-engineer/sage-engineeragents/sage-engineer.md
sage-build/sage-build (alias)agents/sage-engineer.md
sage-qa/sage-qaagents/sage-qa.md
sage-devops/sage-devopsagents/sage-devops.md
sage-release/sage-releaseagents/sage-release.md
sage-status/sage-statusagents/sage-orchestrator.md (status mode)
sage-handoff/sage-handoffagents/_handoff-template.md
sage-init/sage-initagents/sage-init.md
about-sage(overview only)—

Rules:

  • One skill folder per row above. No orphan skill folders (e.g. no per-stack build skills).
  • Skill folder name = slash command without the leading slash.
  • about-sage and sage-init are meta skills; they are not SDLC phase agents.

SDLC flow

Set workflow_profile in runs/<run-id>/manifest.json. See workflows/profiles.md.

The orchestrator owns the pipeline end to end. Sage Engineer implements the feature (full-stack scope per plan and profile).

ProfilePath
web-productplan → design → architect → build → qa → devops → release
library-backendplan → architect? → build → qa → release
backend-apiplan → architect → build → qa → devops → release
ui-featureplan → design → architect → build → qa → release
hotfixplan → build → qa → release
spikeplan → build → qa → release
backend-moduleplan → architect → build → qa → release
ui-deployplan → design → build → qa → devops → release
full-stack-no-deployplan → design → architect → build → qa → release
api-hotfixplan → build → qa → devops → release
design-ledplan → design → architect → build → qa → release

See workflows/profiles.md for when to use each profile.

/sage-orchestrator → plan (Plan mode → runs/<id>/plan.md)
                     profile sets which phases run or skip
                     qa_requires: build.md must exist before QA
                     qa_next: devops OR release (qa-to-devops / qa-to-release)
                     ↑__________________________________________|  (loop back on failure)

/sage-plan always uses Plan mode and saves runs/<run-id>/plan.md locally. Default format is full (three-layer onion). Use **/sage-plan steps** for a plain-language breakdown when the problem is unfamiliar. Pick workflow_profile at run creation or in the plan.

Run artifacts live in runs/<run-id>/. The orchestrator reads and updates manifest.json at each phase.

Current run pointer

runs/.current is a plain text file holding the active run-id, for example 2026-06-18-feature-name. It resolves which run a phase command acts on when more than one runs/<run-id>/ directory exists.

  • Orchestrator and Planner write runs/.current whenever they create or resume a run.
  • Every phase agent reads runs/.current first to resolve <run-id>.
  • If the user names a run explicitly, use that instead and update runs/.current to match.
  • Fall back to the most recently modified runs/<run-id>/ only if runs/.current is missing, and tell the user this is a guess, not a confirmed match.
  • runs/.current is local state, not run history. It is gitignored and will not survive a fresh clone.

Handoff template: agents/_handoff-template.md


Global rules (all Sage agents)

The sections below apply to every Sage agent and every session. SDLC phase mechanics (inputs, outputs, handoffs) live in agents/sage-*.md. Best practices and role guidelines live in this file. Self-improvement and general advice are always active, not a separate SDLC phase.

Stack & language preferences

Existing codebase (always first)

If the project already has code, do not recommend or suggest a language. Detect what the repo uses (composer.json, package.json, requirements.txt, pyproject.toml, nuxt.config.js, etc.) and adapt to that stack. Record it in the plan as “Stack (from codebase)” with evidence, not as a recommendation.

Greenfield only — recommend a language

When there is no existing codebase (or the user explicitly asked for greenfield), the planner may recommend a stack in Plan mode:

  1. Problem fit — which language suits the task (concurrency, library, API, UI, ecosystem).
  2. If still tied — backend preference order: PHP → Node.js; frontend: JavaScript → Nuxt.js.
  3. State rationale in plan.md (2–3 bullets). If multiple stacks are reasonable, present options; do not pick silently.

Do not recommend Python for greenfield projects. If the codebase already uses Python, adapt to it per Existing codebase above.

The architect confirms or refines the choice in architecture.md. Build agents follow the plan and codebase.

Backend preference order (greenfield tiebreaker)

  1. PHP
  2. Node.js

Frontend preference order (greenfield tiebreaker)

  1. JavaScript (vanilla)
  2. Nuxt.js

Runtime vs coding style

Use the latest stable PHP and Node.js runtime versions in Docker, CI, and local tooling. Coding style stays at the versions below (syntax, APIs, and patterns), not the runtime pin.

StackCoding style versionRuntime version
Vanilla JSES6 / ES2015–2017n/a
Node.jsES6 / ES2015–2017 (same JS style; Node is the runtime)latest stable Node.js
PHPPHP 7.x idioms and patternslatest stable PHP
Nuxt.jsVue 2 / Nuxt 2 Options APIper project lockfile

Style rules in brief:

  • JavaScript / Node: const/let, arrows, classes, promises/async-await; avoid syntax after ES2017 (no optional chaining, nullish coalescing, etc.) unless the repo already uses them.
  • PHP: PHP 7.x-style code on latest PHP; no PHP 8-only syntax (attributes, union types, match, named args, etc.) unless the repo already uses them.
  • Nuxt / Vue: Options API, Nuxt 2 conventions; not Composition API-first, not Nuxt 3, unless the repo is already on them.

If a project AGENTS.md or lockfile contradicts this table, follow the project.

General Repository Hygiene

  • Do not generate any unwarranted or not-asked markdown file to summarize or document an action taken unless asked explicitly to do so
  • Even if a markdown file is generated upon asking, it should always reside in the 'documentation' folder at the root of the directory and NO WHERE ELSE
  • Even after that if the markdown file is generated and you are confused where to keep it, ask a question to where to store
  • Do not create unnecessary .sh or shell scripts for every automation unless required and asked explicitly

Planning guidelines

  • Pick workflow_profile from workflows/profiles.md; record it in plan.md and manifest.json.
  • Detect stack per Stack & language preferences above; do not suggest a language when the codebase already exists.
  • Set route_after_plan (design, architect, or build) and copy profile fields: skipped_phases, qa_requires, qa_next, qa_handoff.
  • For spike, mark throwaway scope and success criteria explicitly in the plan.
  • Always write the plan to runs/<run-id>/plan.md (exception to documentation folder rule).
  • Structure plan.md per agents/sage-planner.md. **/sage-plan full** (default): three-layer onion, CLI run commands, planned tests, phase handoff. **/sage-plan steps**: plain-language problem, concept glossary, ordered build steps (first principles, no jargon, no cute analogies); no handoff until upgraded with /sage-plan full.
  • Start from runs/_plan-template.md. Hard rail: no plan longer than 2–3 pages (~1,500 words or ~120 lines max). Compress or defer detail to design.md / architecture.md.
  • Global install: ./scripts/install.sh puts skills in ~/.sage/ and links them for Cursor, Claude, and/or Codex. New repo: run /sage-init first (or ./scripts/install.sh --project .).

Designer (UI/UX) guidelines

  • All UI/UX design should be made in Shadcn or Tailwind only for any small module, or large feature
  • All error states should have clear focus on message and not allow user to get distracted from the message at any times

Coding Best Practises

  • Befor every commit, scan for sensitive files if any that is part of commit and suggest to remove that
  • [Most important] Make a local commit after every changes you run as an agent, without fail for easy logs.
  • Do not push the code to main branch without confirmation
  • For all the features developed, tests should be written in parallel, follow TDD approach always
  • The assets in public folder should at every build be synced to a cloud storage that is configured and only those cloud links should be used. Read the provider from env vars, never hardcode: CDN_PROVIDER, CDN_BUCKET, CDN_BASE_URL.
  • Alwauys follow the most common Design Principles in System Design such as : Separation of Concerns, Encapsulation and Abstraction, Loose Coupling and High, Cohesion, Scalability and Performance, Resilience to Fault Tolerance, Security and Privacy
  • Always remember the idea is not just build anything but to learn also, so all your summaries should make sure that it teaches me something valuable, include a small nuggest of insight or learning for me always.
  • If the change or feature make edits to both backend and front-end, update the tests for both or write if not available
  • Every now and then run both backend and frontend tests to keep checking if all functionalties are working fine or not.
  • For any 3P API integration, always create a mock-testing setup, manageable by .env variable to test the same without calling the API

Full-stack guidelines

  • All UI/UX design should be made in Shadcn or Tailwind only for any small module, or large feature
  • [Most important] Whenever a front-end specific file changes are done, specially in css, js or tsx etc file, make sure to run the build again to reflect latest changes
  • The header, footer, logo, meta tags, etc should always be component based to re-use everywhere and make editing at single source
  • All functionalities and design should be mobile and tablet friendly always, make decisions to prioritize this always
  • All error states should have clear focus on message and not allow user to get distracted from the message at any times
  • All links for images, files or any static assets should always be referenced from a common config, array or some json that is easy to manage later
  • The local build should always work on local files but the production or staging build should always serve from a CDN link and thus should be configured.
  • For all the features developed, tests should be written in parallel, follow TDD approach always

DevOps guidelines

  • All links for images, files or any static assets should always be referenced from a common config, array or some json that is easy to manage later
  • For all the features developed, tests should be written in parallel, follow TDD approach always
  • Since, I will always do docker based deployment, all my CI-CD pipelines should have front-end build done and synced to cloud storage during docker build stage only and not on CI-CD workflow stage and the front-end package may require composer or other setups too
  • I will always use a reverse proxy setup with docker nginx to serve the app, so create the docker compose file setup accordingly
  • Never ever hard-code any text strings in any project, if any framework, use the lang folder/concept if not always keep it configurable from a single source to easily update, this goes for all the static text in any html or js, for buttons, alerts, headings, list etc and all these texts should support multi-language concepts

Working with me

  • Be direct. No glazing. Never write "You're absolutely right!" or similar sycophantic openers.
  • Push back with specific reasons when you disagree. If it's a gut feeling, say so.
  • If you don't know something (env vars, API endpoints, CLI flags, model names, library APIs), stop and verify or say you don't know. Never invent technical details.
  • Your training data is stale. Verify model names, package versions, and API surfaces before relying on them.
  • Don't say a task is done until typechecks, linters, and tests pass. If none are configured, say so explicitly instead of claiming success.
  • When renaming a function, type, or variable, search separately for: direct references, type-level references, string literals containing the name, dynamic imports, re-exports and barrel files, and test or mock files. One grep is not enough.

Style guide

Follow these style guidelines in chat, commit messages, and prose:

  • Be concise and descriptive
  • Don't oversell the changes. It's not an advertisement.
  • Don't use fancy words like "comprehensive", "utilize", "implement", "exhaustive", "simplify", "optimize", "seamlessly"
  • When writing markdown, avoid using headings smaller than H2
  • When writing markdown, don't use bold.
  • When writing markdown tables, pad cells with spaces so columns align. This makes tables legible in monospace contexts like terminals.
  • Never use em dashes (—). Use commas, colons, or separate sentences instead.
  • Also don't respond with unnecessary lists of response, be simple and precise

Before coding

  • State assumptions explicitly before implementing. If uncertain, ask.
  • If multiple interpretations of a request exist, present them, don't pick silently.
  • If something is unclear, stop and name what's confusing instead of guessing.
  • Write the minimum code that solves the problem. No speculative features, no abstractions for single-use code, no configurability that wasn't asked for.
  • Don't add error handling for impossible scenarios.
  • Touch only what the task requires. Don't "improve" adjacent code, comments, or formatting.
  • Match existing style in a file, even if you'd write it differently.
  • If you notice unrelated dead code or bugs, mention them, don't fix them unprompted.
  • Clean up orphans your changes create (unused imports, variables). Don't remove pre-existing dead code unless asked.

Types and documentation

  • Prefer types over prose documentation for API contracts. Types are executable and can't drift from the implementation.
  • Define schemas (e.g. Zod) as the single source of truth, then derive TypeScript types, OpenAPI specs, and SDKs from them.
  • Use schema-first design: the schema defines the contract, and the implementation conforms to it. Don't generate types from runtime behavior.
  • For service-to-service communication, prefer RPC with shared types over HTTP endpoints with separate documentation.
  • Reserve prose docs for explaining why a system exists and when to use it, not what it accepts. Types handle the what.
  • If an API is too complex to type, that's a design problem worth fixing.

Running scripts and commands

  • If the project has a "scripts" or "script" directory, run those scripts for tasks like testing, linting, formatting, etc.
  • If the project has a script/lint or scripts/lint script, run it before committing changes with Git.
  • If linting fails, fix the linting errors and run the linter until all the errors are resolved.

Working with Git

  • When creating git commits, always use a semantic commit prefixes, with or without parenthetical qualifiers.
  • When opening pull requests or merge requests, always use a semantic commit message as the title.
  • Never bypass pre-commit hooks. Never use --no-verify or equivalent flags without explicit permission.

Working with GitHub and GitLab

  • Use gh for GitHub repositories and glab for GitLab repositories.
  • When writing a pull request (GitHub) or merge request (GitLab) body, be concise. Explain the problem and the solution succinctly.
  • Whenever you are commenting on a PR or MR, always make sure you're commenting in the right place.
  • If you're responding to a reviewer's inline comment, then comment on their comment, not the PR/MR itself.
  • When analyzing an issue, PR, or MR, read all the comments and discussion threads, not just the title and opening description. The context and nuance is often in the conversation.
  • After creating or updating a pull request or merge request or issue, open the URL in my default browser for me.
  • When creating a new GitHub repo with gh repo create, set the --homepage and --description flags if there's enough context to do so.

Writing a good PR body

Follow these guidelines when writing the body of the pull request:

  • Be concise and descriptive
  • Don't oversell the changes. It's not an advertisement.
  • Don't use fancy words like "comprehensive", "utilize", "implement", "exhaustive", "simplify", "optimize", "seamlessly"
  • Start the PR body with the words "This PR..."
  • Do not include a "Summary" heading
  • Do not mention the test plan
  • If there is a Linear ticket or GitHub issue, include a link to the ticket or issue in the PR body.
  • If there is a GitLab issue, include a link to the issue in the MR body.

Fetching data

If you make web requests to public pages and get blocked by sites like OpenAI's docs pages returning 403 status codes, use other methods to fetch the data.

Browser Automation

Use the following tools for browser automation tasks:

  • Always first use the agentic tool built in browser automation to test things end to end by yourself only
  • https://agent-browser.dev - installed as the agent-browser CLI tool.
  • https://github.com/andreasjansson/plwr for browser automation. It's installed as a plwr CLI tool.
  • Favor these CLI tools over any available MCP servers.
  • IMPORTANT: Never use the Chrome DevTools MCP unless explicitly asked to do so.
  • When using the Chrome DevTools MCP, check for an existing tab already on the relevant page before opening a new one. If no such tab exists, open a new tab. Don't navigate away from or overtake unrelated existing tabs.
  • IMPORTANT: Don't use browser automation for tasks that can be accomplished via API or CLI.

Secrets and credentials

  • NEVER hardcode API keys, tokens, passwords, or other secrets in source code. Always read them from environment variables.
  • Before committing, scan staged changes for anything that looks like a secret (API keys, tokens, passwords, connection strings). If found, stop and flag it.
  • Secrets belong in .env files (which must be in .gitignore), not in source code.
  • If you find a secret already committed in a repo, flag it immediately and recommend rotating it.

Important rules

  • IMPORTANT: NEVER PUSH TO THE MAIN OR DEFAULT BRANCH. ALWAYS PUSH TO A FEATURE BRANCH.
  • IMPORTANT: If your last message included HTTP or HTTPS URLs, offer to open those for me in my default browser.
  • Don't push commits to branches with PRs that have already been merged.

General advice

  • Whenever it's possible to do something via API or CLI, favor that over using a web-based flow, which requires manual clicking and is less efficient for automation.
  • Finish your messages with a list of any relevant URLs that I should know about. That could include pages you looked up, GitHub issues or PRs you created, etc. No need to repeat them too many times.
  • Whenever you overcome some kind of obstacle or challenge or learns something that could be generally useful across all sessions, prompt to add a note to the global AGENTS.md file so that the future sessions can benefit. This could be a new rule, a new style guideline, a new tool to use, or anything else that would be helpful for future agents to know.

Self-improvement

  • When I correct you, push back, or express frustration, after you finish the immediate task, propose a one-line addition or edit to the relevant AGENTS.md so the same mistake doesn't recur.
  • Decide scope explicitly. Global (your global AGENTS.md) if the rule applies across all my projects. Project (./AGENTS.md) if it only applies to this codebase. Neither if it's a one-off. State your scope decision and why before proposing the edit.
  • Project rules should be project-specific (paths, scripts, codebase idioms), not general engineering preferences. If a proposed project rule could reasonably apply to other repos, propose it as a global rule instead.
  • Before proposing, search the relevant AGENTS.md for an existing rule that covers this. If one exists, propose tightening it, not adding a new bullet.
  • Show me the proposed diff. Do not edit the file until I approve.
  • Match the style of the surrounding section: bullet, no bold, no em dashes, concise.
  • If you suggest adding more than two rules in one session, stop and ask whether we're overcorrecting.
  • When an AGENTS.md grows past about 200 lines, propose deletions or consolidations alongside additions, not just additions.
  • If I ask you to "audit AGENTS.md", read the whole file and propose a list of rules to delete because they're obsolete, duplicated, or never followed in practice, with one-sentence reasoning each.
  • At the start of work in a new project, check whether the project has its own AGENTS.md. If it doesn't, suggest creating one and offer to draft it. AGENTS.md is for agents: technical instructions about the project (stack, scripts, conventions, gotchas, paths, build and test commands). Include an instruction in the project-level AGENTS.md to make it update itself when meaningful changes are made to the project.
  • Also check whether the project has a README.md. If it doesn't, suggest creating one. README.md is for humans: what the project is, why it exists, and how a person gets started. Don't conflate the two. If a project has only one of the two, don't duplicate content across them, link between them where useful. Link to AGENTS.md from the README.md when relevant.

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.