Skip to content

AGENTS.md

Latest commit

 

History

History
114 lines (90 loc) · 5.32 KB

AGENTS.md

File metadata and controls

114 lines (90 loc) · 5.32 KB
Raw

AGENTS.md — font.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.

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 git commit/push unless asked. If asked and on the default branch, create a feature branch first.
  • Hard-to-reverse or outward-facing actions (publishing, deleting, sending) require confirmation unless explicitly authorized.

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).

Repo-specific notes

Repo-specific guidance goes here; preserved across regeneration.