Skip to content

AGENTS.md

Latest commit

 

History

History
162 lines (128 loc) · 7.73 KB

AGENTS.md

File metadata and controls

162 lines (128 loc) · 7.73 KB
Raw

AGENTS.md — boot.gl

Guidelines for AI coding assistants. Generated by @starling-cloud/agents v0.1.0. Classification: owner=stylescape, fleets=node-lib, docs-site. Edit fragments in the control plane, not the block below; add repo-specific notes beneath the END sentinel.

Branch model

This repository keeps three long-lived branches on origin:

Branch Role
dev Default branch. Clones, new branches, and PRs target this.
pro Long-lived branch, maintained alongside dev and main.
main Long-lived branch, maintained alongside dev and pro.

All three are kept in place — do not delete them, and do not assume main is the trunk. dev is the GitHub default branch, so a fresh git clone lands on dev and gh pr create targets dev unless told otherwise.

Identity & context

You are an AI coding assistant working inside a single repository that is one of ~900 across a multi-brand workspace. Repos are independent git repositories grouped by owner and family — there is no monorepo.

  • Determine the repo's type from this file's fleet sections, its build files (pyproject.toml, package.json, Cargo.toml), and its directory layout.
  • Prefer the conventions documented here over generic habits. When this file and the code disagree, trust the code and flag the discrepancy.
  • Keep changes scoped to the current repo unless explicitly asked to touch a sibling repo.

Working method

  1. Explore before editing. Read the relevant files and match existing patterns (naming, structure, comment density) before writing code.
  2. Plan non-trivial work. For anything beyond a small edit, outline the steps; for large/ambiguous tasks, confirm scope before building.
  3. Make small, reviewable diffs. Don't reformat unrelated code. Don't leave commented-out code or TODO-as-implementation.
  4. Verify (see the verification section) — never report something as done that you haven't run or checked.
  5. Ask when genuinely blocked on a decision that is the user's to make; otherwise pick the conventional default, state it, and proceed.

Git & changes

  • Don't create branches or worktrees on your own initiative. Stay on the branch and in the checkout you were given. The feature branch an approved commit needs is part of that request; anything beyond it — a second branch, a git worktree, a fresh clone — has to be asked for explicitly. If the work looks like it needs one, say so and wait.

Coding standards

  • Match the surrounding code: idioms, naming, file structure, and comment density of the file you are editing take precedence over personal style.
  • Names describe intent; avoid abbreviations that aren't already used in the repo. Kebab-case for repo/package names, the language's norm for identifiers.
  • Comments explain why, not what. Don't narrate obvious code.
  • No dead code: no commented-out blocks, unused imports, or speculative abstractions "for later".
  • Errors: fail loudly in dev, degrade gracefully at trust boundaries (network, user input, optional deps). Never swallow exceptions silently.
  • One concern per file where the fleet already does so (e.g. one model / one component per file).

Git, commits & PRs

  • Branches: never commit directly to the default branch; branch as feat/…, fix/…, chore/…, docs/….
  • Commits: Conventional Commits (type(scope): summary). Keep them atomic and explain why in the body when non-obvious.
  • Co-authorship: when an AI assistant produces a commit, add the assistant's Co-Authored-By trailer.
  • PRs: describe the change, the rationale, and how it was verified. Link the issue/TODO item. Note any follow-ups.
  • Never force-push shared branches or rewrite published history.
  • Use the gh CLI for GitHub operations.

Security

  • Never commit secrets, tokens, or .env contents. If you spot one in the tree or history, stop and flag it.
  • Dependencies: prefer the repo's existing libraries; justify any new dependency. Don't add a dep to solve what stdlib/existing utils already do.
  • Untrusted input (network, user, file uploads) is validated at the boundary; never interpolate it into shell/SQL/HTML without escaping.
  • Auth: respect the caller's permissions; never widen access scope to make something "work". Reuse the platform's auth context rather than bypassing it.
  • Security testing and defensive work are in scope; building tools for unauthorized access, mass-targeting, or detection-evasion is not.

Verification

Before reporting work complete:

  • Run the checks the repo provides — tests, typecheck, lint, build — for the area you changed. The fleet sections below list the exact commands.
  • Report honestly: if a check fails, say so and show the output. If you skipped a step, say which and why. Don't claim verification you didn't do.
  • Prefer the dedicated task/skill the repo ships (e.g. a contract test or a run script) over ad-hoc commands.
  • A change that touches behaviour without a corresponding test run is not done.

Organisation

  • Treat code as Proprietary unless this repo's LICENSE states otherwise.
  • Follow the conventions visible in the repo's build files and existing code.

Stack — Node / TypeScript library

  • Maintain the package.json exports map and emit type declarations.
  • Run npm run typecheck / npm run lint / npm run build (whichever exist) before declaring done.
  • Keep the dependency footprint small; prefer existing utilities.

Stack — documentation site

  • Content is the product: keep prose accurate and in sync with the code it documents.
  • Build with the repo's documented command (e.g. mkdocs build) and fix warnings (broken links, missing nav entries).

TODO.md & CHANGELOG.md

Every repo keeps both files at its root.

  • TODO.md holds open work only — planned tasks, known problems, open decisions. Mark actionable items as - [ ] checkboxes.
  • CHANGELOG.md follows Keep a Changelog: newest first, with an ## [Unreleased] section at the top and entries grouped under ### Added / Changed / Deprecated / Removed / Fixed / Security. At release, [Unreleased] becomes ## [x.y.z] - YYYY-MM-DD. The "generated by semantic-release, do not edit manually" note some changelogs carry is stale — that workflow is disabled (.github/workflows-backup/), so edit the file by hand.
  • When you finish a TODO item, move it — don't tick it. In the same change, delete the item from TODO.md and add an entry under ## [Unreleased] in CHANGELOG.md. Write the entry as what changed (past tense, the effect, the files or APIs involved), not as the original task, and keep any verification note that matters ("verified with an AST scan of src/").
  • A partly done item stays in TODO.md, trimmed to what is left; the done part goes to the changelog. An item closed without a change (stale, duplicate, won't fix) is deleted from TODO.md and not logged — say why in the commit message.
  • Drop a TODO.md heading once its last item has moved. Never leave - [x] items in TODO.md.

Repo-specific notes

Repo-specific guidance goes here; preserved across regeneration.

Working branch

Agents work directly on dev. Unless explicitly asked otherwise, make all changes on the dev branch of this checkout — don't create feature branches or worktrees, and don't switch to another branch.