agentleFS
Sign inStart free
photon-hqphoton-hq/cli/AGENTS.md

cli

AGENTS.md34 starsChanged 8 days agoMITView on GitHub

  • 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 31,700 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

15 rules. About 0 are common, 4 are distinctive, and 11 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 11

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use Bun exclusively — never Node, npm, pnpm, yarn

    line 7
  2. Very specific:

    Never hand-edit API types — they come from the @photon-ai/dashboard-api dependency.

    line 8
  3. Distinctive:

    Never add forbidden dependencies: axios, chalk, zod, jest, vitest, ts-node, ws, express, dotenv, ioredis, pg, better-sqlite3

    line 9
  4. Very specific:

    Every command must use getApi() from ~/lib/api.ts + Eden treaty pattern — never raw fetch()

    line 10
  5. Distinctive:

    Never delete or rewrite snapshot files without justification in PR body under "## Snapshot changes"

    line 13
  6. Very specific:

    Never modify files in .github/workflows/ or scripts/agent-flow/

    line 15
  7. Distinctive:

    Prefer adding fields to existing DTOs over creating parallel types

    line 20
  8. Very specific:

    All user-facing output uses c.dim(), c.success(), c.error() from ~/lib/output.ts

    line 21
  9. Very specific:

    Read UPSTREAM_DIFF.md (committed at the root of your branch)

    line 34
  10. Very specific:

    Run bun install && bun run check.

    line 35
  11. Very specific:

    Update DTOs in src/lib/types.ts if the API surface changed

    line 36
  12. Very specific:

    Update command files in src/commands/ to match new routes

    line 37
  13. Very specific:

    Update or add tests in tests/ to cover changes

    line 38
  14. Very specific:

    Run bun run check until green

    line 39
  15. Very specific:

    If you can't make it green within 20 iterations, create AGENT_NOTES.md explaining where you got stuck

    line 40

≈ “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 Guide for @photon-ai/cli

Mission

You're updating this CLI in response to upstream API changes in @photon-ai/dashboard-api. The API type contract arrives as a version bump of that dependency (in package.json/bun.lock). Your job: make bun run check pass.

Hard Rules (CI will fail if violated)

  1. Use Bun exclusively — never Node, npm, pnpm, yarn
  2. Never hand-edit API types — they come from the @photon-ai/dashboard-api dependency; update them by bumping its version
  3. Never add forbidden dependencies: axios, chalk, zod, jest, vitest, ts-node, ws, express, dotenv, ioredis, pg, better-sqlite3
  4. Every command must use getApi() from ~/lib/api.ts + Eden treaty pattern — never raw fetch()
  5. Destructure Eden responses as { data, error, status } — check error before using data
  6. Handle 401 by throwing SessionExpiredError (caught centrally in handleTopLevelError)
  7. Never delete or rewrite snapshot files without justification in PR body under "## Snapshot changes"
  8. One PR = one upstream version bump — don't bundle refactors
  9. Never modify files in .github/workflows/ or scripts/agent-flow/

Soft Rules (reviewer will flag)

  • Match the style in src/commands/projects.ts: same option ordering (--api-host, -t/--token, --json), same error handling
  • New DTOs go in src/lib/types.ts, cast at the API boundary
  • Prefer adding fields to existing DTOs over creating parallel types
  • All user-facing output uses c.dim(), c.success(), c.error() from ~/lib/output.ts
  • Comments only when intent isn't obvious from the code

Anti-patterns (we've seen AI do these — don't)

  • Splitting the Project DTO into one type per command
  • Adding try/catch around every getApi() call (handled centrally in src/index.ts#handleTopLevelError)
  • Using console.log(JSON.stringify(...)) instead of the output helpers
  • Replacing picocolors with chalk
  • Using node:fs instead of Bun.file
  • Adding dotenv (Bun auto-loads .env)
  • Importing from @elysiajs/eden directly instead of using getApi()

Workflow

  1. Read UPSTREAM_DIFF.md (committed at the root of your branch)
  2. Run bun install && bun run check. Note what breaks.
  3. Update DTOs in src/lib/types.ts if the API surface changed
  4. Update command files in src/commands/ to match new routes
  5. Update or add tests in tests/ to cover changes
  6. Run bun run check until green
  7. If you can't make it green within 20 iterations, create AGENT_NOTES.md explaining where you got stuck

Tooling

  • Package manager: bun only
  • Test runner: bun test
  • Type check: tsc --noEmit
  • Build: bun run build
  • Aggregate: bun run check (runs typecheck + test + build)

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.

Check your setup, free