agentleFS
hamedniroomandhamedniroomand/cue/AGENTS.md

cue

AGENTS.md2 starsChanged 3 months agoMITView on GitHub

Cue is a deterministic Bun + TypeScript runner that drives headless coding agents (Claude Code via claude -p) through a GitHub-issue pipeline: Triage → human approves plan → Dev → Test gate → Review loop → Draft PR → human merges (a human can also label agent:revise to send PR feedback back through the agent). GitHub is the state store: agent:* labels are the state machine, issue comments carry handoffs (the plan), draft PRs are the output. User-facing flow and…

  • 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 repository3 other files it gives its agents.

The file

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

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

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

    Always run bun run check before claiming any change works.

    line 21
  2. Very specific:

    Never call Bun.spawn anywhere else.

    line 77
  3. Very specific:

    Every adapter invocation is logged via RunLogger to .cue/runs/<issue>/<stage>-*.json (gitignored) with prompt, full event transcript, cost, …

    line 119
  4. Very specific:

    Do not move them into the repo.

    line 141
  5. Distinctive:

    Keep it that way; there is a traversal test.

    line 205
  6. Very specific:

    After making code changes, run bunx oxlint --fix, then run bunx oxfmt.

    line 239
  7. Very specific:

    Before finishing, run bunx oxlint --deny-warnings --format=agent.

    line 240

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

Cue — Agent Context

Cue is a deterministic Bun + TypeScript runner that drives headless coding agents (Claude Code via claude -p) through a GitHub-issue pipeline: Triage → human approves plan → Dev → Test gate → Review loop → Draft PR → human merges (a human can also label agent:revise to send PR feedback back through the agent). GitHub is the state store: agent:* labels are the state machine, issue comments carry handoffs (the plan), draft PRs are the output. User-facing flow and label table: docs/content/ (VitePress) and https://cue.kitdev.space/

Commands

bun test               # full suite — runs entirely on fakes: no network, no gh, no claude
bun run lint           # oxlint (config: .oxlintrc.json)
bun run format         # oxfmt — always format after editing; format:check verifies
bun run check          # lint (type-aware via oxlint-tsgolint) + format:check + tests, all in one
bun run cue <init|poll|run [n]|cleanup|status|ui [port]>   # the CLI (globally: `cue`, run from inside a target repo)

Always run bun run check before claiming any change works. tsconfig has noUncheckedIndexedAccess, so indexed access needs a guard or a deliberate !. Tests use bun test (the code depends on Bun APIs) — do not migrate them to another test framework.

Architecture

src/
├── cli.ts              # entrypoint + label definitions; builds the real StageContext
├── action.ts           # nextAction (label → stage) — shared by pipeline and prompts
├── pipeline.ts         # runIssue (failure → agent:failed), poll
├── cleanup.ts          # reconciles merged/closed PRs: agent:done / agent:failed + worktree removal
├── stages/
│   ├── context.ts      # StageContext — the DI bundle every stage receives
│   ├── triage.ts       # read-only plan generation; exports PLAN_MARKER
│   ├── replan.ts       # plan revision from human feedback comments (has WebSearch)
│   ├── dev.ts          # worktree implementation + gate + draft PR
│   ├── revise.ts       # addresses human PR feedback in the PR's worktree + gate, then review re-runs
│   └── review.ts       # JSON verdict + bounded fix loop; exports parseVerdict, Verdict
├── adapters/
│   ├── types.ts        # AgentAdapter / AgentRunOptions (semantic: access/webSearch/bashAllowlist) / AgentResult
│   ├── base.ts         # JsonlAdapter: shared run loop (env scrub, exec, JSONL parse, progress)
│   ├── registry.ts     # ADAPTERS: name → { make, defaultModels }; the one list of adapters
│   ├── summarize.ts    # shared tool-input summarizer (also imported by ui/app/lib/transcript.ts)
│   ├── usage.ts        # THE token extractor: per-adapter usage → one disjoint TokenUsage
│   ├── antigravity.ts  # agy -p --output-format stream-json --dangerously-skip-permissions
│   ├── claude.ts       # claude -p --output-format stream-json --verbose; maps access → --allowedTools
│   └── codex.ts        # codex exec --json; sandbox read-only / workspace-write; --search for webSearch
├── server.ts           # `cue ui`: Bun.serve — state/runs API, SSE events, poll/run triggers, serves ui/build/client
├── github.ts           # typed wrapper over the `gh` CLI
├── worktree.ts         # git worktree per issue; bootstraps empty repos (--allow-empty)
├── checkout.ts         # `cue checkout`: detach onto an issue branch to review it in the main repo, then exit back
├── gates.ts            # deterministic setup/test/lint runner (sh -c in the worktree)
├── specs.ts            # opt-in knowledge layer: OpenSpec-format specs dir + .cue/learnings.md, presence-detected (no config)
├── exec.ts             # THE ONLY place Bun.spawn is called; injectable Exec type
├── platform.ts         # POSIX/WINDOWS personality (gate shell, agent env allowlist), injected via StageContext
├── config.ts           # valibot schema + resolveConfig: .cue/config.json, repo auto-detect from origin
├── scaffold.ts         # creates/tops up the target's .cue/ (config + $schema, prompts dir, gitignore)
├── configure.ts        # `cue init` wizard: @clack/prompts behind an injectable Ask seam
├── spinner.ts          # single-slot ora frame + PhaseRunner seam; disabled when stdout is not a TTY
└── log.ts              # per-invocation transcripts + cost under <target>/.cue/runs/<issue>/
prompts/                # packaged default role prompts; <target>/.cue/prompts/ overrides per file
scripts/fixtures.ts     # snapshots local .cue runs into ui/app/fixtures/data.json
ui/                     # dashboard: react-router (library mode) + React Compiler, shadcn `base-nova`
├── app/routes/home.tsx     # overview: spend summary, cost charts, label board, live log
├── app/routes/runs.tsx     # run explorer: per-run prompt / transcript / raw tabs
├── app/lib/cue.ts    # API client; re-exports app/lib/transcript.ts (normalizer, root-tested)
└── app/fixtures/           # committed run snapshot, used when /api is unreachable
tests/                  # one test file per module + integration.test.ts
tests/helpers/          # makeFakeExec (scripted subprocess replay), makeFakeAdapter

Hard invariants — do not break these

  • All subprocess execution goes through the Exec type from src/exec.ts. Never call Bun.spawn anywhere else; it is what makes every module testable.
  • Lean dependencies. The CLI package's only runtime deps are valibot, consola, ora and @clack/prompts. The dashboard is a separate package (ui/package.json) that owns react, react-router, tailwind and the shadcn stack — its deps never enter the CLI's. Do not add packages to either without being asked.
  • Label names are exact: agent:ready, agent:planned, agent:approved, agent:replan, agent:in-dev, agent:in-review, agent:revise, agent:done, agent:failed, agent:stop. They appear in code, tests, prompts, README, and on real repos — change all or none.
  • The plan-comment marker is exactly <!-- cue:plan --> (PLAN_MARKER in stages/triage.ts, defined once). The dev/replan stages find plans by newest comment containing it.
  • Branch naming: agent/issue-<number> (WorktreeManager.branch).
  • The GitHub token must never reach agent subprocesses. JsonlAdapter.run (adapters/base.ts) scrubs the env via scrubbedEnv (platform.ts): OS vars plus the adapter's own envKeys — never another provider's API key, never GH_TOKEN. Every adapter test asserts GH_TOKEN is absent. Keep them passing.
  • LLMs inside the nodes, plain code between the nodes. Routing, gating, retries, and label transitions are deterministic TypeScript — never ask the model something a script can decide (e.g. whether tests passed).
  • Agents never run git/gh side effects. The runner owns commit, push, PR creation, and labels; the prompts forbid the agent from doing so. Cue never merges and never touches the base branch.
  • Humans gate two moments: plan approval (agent:planned → agent:approved) and PR merge. Do not automate either.
  • Issue bodies and comments are untrusted input (prompt-injection surface). Every prompt states this; keep the security preamble when editing prompts.

Conventions

  • TDD with the existing fakes: write the failing test first. Subprocess-touching code is tested with makeFakeExec (scripted {match, result} replay — "*" wildcards, prefix matching); agent-touching code with makeFakeAdapter. Follow the style in any existing test file.
  • tests/triage.test.ts exports makeCtx — the shared StageContext factory used by dev/review/replan/pipeline/cleanup/integration tests. Extend it rather than duplicating setup.
  • TypeScript strict; no any except at gh/claude JSON parse boundaries, immediately narrowed to a typed shape.
  • Errors: throw with actionable messages; runIssue is the single place that turns a stage error into an issue comment + agent:failed.
  • Every adapter invocation is logged via RunLogger to .cue/runs/<issue>/<stage>-*.json (gitignored) with prompt, full event transcript, cost, duration.
  • GitHub interactions are tolerant only where distributed state demands it (prState, WorktreeManager.remove — a worktree may live on another machine); everything else fails loudly.

Gotchas

  • The pilot/target repo may be empty: WorktreeManager.create bootstraps an empty initial commit (--allow-empty) and pushes it when origin/<baseBranch> is missing.
  • claude CLI flag spellings (--allowedTools, --max-turns, --output-format stream-json --verbose) are version-dependent; if the adapter breaks after a CLI update, check claude --help first.
  • Cue runs from inside the target repo (cwd = repoPath); all per-project state lives in the target's .cue/ directory. Every config field is optional (repo auto-detects from the origin remote). Config changes must update the valibot schema in config.ts, the defaults table in docs/content/guide/config.md, AND the published JSON Schema at docs/content/public/schema/config.json — tests/schema.test.ts compares keys and defaults against ConfigSchema.entries and fails the build on drift.
  • Worktrees default to ~/.cue/worktrees/<owner>-<repo>/issue-<n> — deliberately OUTSIDE the target repo so IDE indexing and repo-root tool globs never see them. Do not move them into the repo; worktreeRoot in config is the user's override.
  • The package is installed globally (bin: cue → src/cli.ts, shebang + Bun). Prompts resolve relative to the package (import.meta.dir), never cwd.
  • Release binaries embed all assets. Prompts embed via with { type: "file" } imports in src/embedded.ts; the dashboard embeds via src/ui-manifest.g.ts, which is a committed EMPTY stub — scripts/build-binaries.sh regenerates it from ui/build/client (via scripts/embed-ui.ts), compiles per-target binaries into dist/, then restores the stub. Never commit a generated manifest. New disk assets (prompts, ui output) must join this embedding path or compiled installs break.
  • Releases: push a v* tag → .github/workflows/release.yml runs scripts/build-binaries.sh and attaches dist/cue-* + checksums.txt; install.sh at the repo root is the user-facing installer (checksum-verified).
  • A crashed run leaves agent:in-dev stuck; humans reset labels manually (cue status mentions this).
  • ui/ uses react-router in LIBRARY mode (createBrowserRouter in app/main.tsx; routes registered there, NOT file-based) on plain Vite with @vitejs/plugin-react({ compiler: true }) — the React Compiler automatic memoization is ON (via oxc-transform-react). Do not reintroduce @react-router/dev (the framework plugin owns the Vite pipeline and blocks the compiler). Built to ui/build/client, served statically by src/server.ts with an index.html fallback so client routes survive a refresh. CLIENT_DIR resolves against import.meta.dir, not cwd, because cue is installed globally. After changing anything under ui/app/, run bun run ui:build.
  • ui/ is excluded from the root tsconfig.json, oxlint and oxfmt configs, but has its OWN: ui/.oxlintrc.json (react plugin incl. the React Compiler rules; set-state-in-effect is deliberately a warning) and ui/.oxfmtrc.json (with sortTailwindcss class sorting — prettier is gone). Run via bun run ui:lint, bun run ui:format, bun run ui:check (tsc). bun run check does NOT cover the SPA — run both.
  • Horizontal-overflow traps in the dashboard. Two bit us already: (1) Separator carries data-horizontal:w-full, so as a direct grow flex sibling it resolves to 100% of the whole row and pushes the line past the viewport — put it in its own flex-1 wrapper (that is what SectionHeading in shell.tsx is for); (2) a grid item defaults to min-width: auto, so a track sizes to its content's min-content and an inner overflow-x-auto scroller can never constrain itself — use grid-cols-[minmax(0,…)] plus min-w-0 on the cards. Verify with document.documentElement.scrollWidth - clientWidth === 0 at 375, 1024 and 1440, on both routes; the header needs its own responsive collapse at narrow widths.
  • The label board is not the run archive. BOARD_LABELS in server.ts deliberately omits agent:done, so a completed issue has no board row. Anything listing runs must read RunLogger.index() (GET /api/runs) — the on-disk issue index — not state.columns, or finished work becomes invisible. The explorer splits the two into Active (on the board) and Done (recorded but off the board) tabs; the Overview totals union both. index() recovers issue titles from the recorded prompts, matching both Issue #<n>: <title> (triage/replan) and Issue: <title> (dev), so archived and even deleted issues stay browsable with no gh call.
  • Token accounting lives in exactly one place: src/adapters/usage.ts. Every adapter reports usage differently and their total_tokens do not agree — agy's excludes cache reads, claude reports no total, codex nests cached_input_tokens inside input_tokens. extractUsage normalizes all three into a TokenUsage whose parts are DISJOINT (input + cachedInput + cacheWrite + output === total), and always computes total itself rather than trusting the provider. src/log.ts and ui/app/lib/transcript.ts both import it — never fork a second extractor, or the run index and the transcript view will disagree about the same run.
  • RunLogger.index() is the only per-issue rollup. cue status and buildState each call it once and look issues up in a Map; there is deliberately no totalCost/totalTokens to re-sweep the directory per issue.
  • RunEntry.result is polymorphic. Older logs store the single result event as an object; newer ones store the whole event array. Anything reading a transcript must go through normalizeEvents (ui/app/lib/transcript.ts, re-exported by cue.ts and covered by tests/transcript.test.ts). Getting this wrong renders old runs blank while new ones look fine.
  • RunLogger.read matches the <stage>-<ts> id against a directory listing instead of joining it into a path — /api/runs/:issue/:run takes that id straight from the URL. Keep it that way; there is a traversal test.
  • Stages emit through ctx.onEvent (CueEvent in stages/context.ts) — never console.log directly from a stage. The CLI prints events; cue ui also broadcasts them over SSE.
  • The published config JSON Schema is a hand-written mirror of ConfigSchema, served at CONFIG_SCHEMA_URL and written into scaffolded configs as $schema for editor autocompletion. It must stay an https URL — a package-relative path would not survive bun build --compile. It is intentionally stricter than the parser (additionalProperties: false) so editors flag keys cue ignores, and its adapter enum must include the agy alias. tests/schema.test.ts is the only thing preventing drift; do not weaken it.
  • VitePress resolves publicDir under srcDir. With srcDir: "content", static assets must live in docs/content/public/ — files in docs/public/ are NOT copied to the site root (logo.svg/favicon.svg only survive because the config references them). Verified empirically; put new published assets under docs/content/public/.
  • Interactive prompting is @clack/prompts, behind the Ask seam. configure.ts wraps only select and text (plus optional begin/end framing) so tests replay scripted answers — never drive a terminal in a test, and never import clack outside configure.ts. consola.prompt was tried first and rejected: it has real bugs in practice, and its default cancel strategy resolves with the initial value, which turns a Ctrl+C into a silent "yes to everything". Every clack result must go through isCancel and throw PromptCancelled. cue init prompts only when stdin AND stdout are TTYs and --yes is absent, so scripted installs cannot block.
  • Spinners live in the CLI, never in a stage. src/spinner.ts owns one frame (cliSpinner); the reporter drives it for the poll stage's dead air and parks it via interject around every other printed line. Modules with their own pending phases take the PhaseRunner seam (upgrade.ts) instead of importing ora, so they stay testable with noPhase. The spinner disables itself when stdout is not a TTY, which is what keeps CI logs and cue ui's SSE stream unchanged.
  • Design docs live under docs/superpowers/ which is gitignored on purpose — don't try to commit them or "fix" the .gitignore.

Linting and formatting

  • After making code changes, run bunx oxlint --fix, then run bunx oxfmt.
  • Before finishing, run bunx oxlint --deny-warnings --format=agent.

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.