Skip to content

AGENTS.md

Latest commit

 

History

History
146 lines (119 loc) · 7.19 KB

AGENTS.md

File metadata and controls

146 lines (119 loc) · 7.19 KB
Raw

AGENTS.md — stylescape-devcontainer

Guidelines for AI coding assistants. Generated by @starling-cloud/agents v0.1.0. Classification: owner=starling-cloud, fleets=stylescape. 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 — Starling

  • Owner: Starling Associates BV. Code is Proprietary unless a repo's LICENSE says otherwise — do not add open-source license headers.
  • Contact: info@starling.studio.
  • Repo naming: kebab-case, family-prefixed (system-*, portal-*, sturnus-*, sturnia-*, public-*).
  • Packages: published to GitHub Packages (npm scope @starling-cloud/*, Python via the GitHub Packages PyPI). In dev, intra-fleet deps may be file: / path links; release builds use the published versions.
  • Shared tooling lives in fleet-level bin/ (audit, release, sync scripts). Reuse it; don't reinvent fleet-wide automation per repo.

Fleet — stylescape (design system / tokens)

This repo authors the design system consumed fleet-wide.

  • Tokens first: colour, spacing, type, radius, shadow, motion are defined as --ss-* custom properties. Components reference tokens — never raw hex.
  • Stylelint enforces the token contract (--ss-* only, no raw hex, kebab-case selectors); keep it green.
  • Changes to token names/values are breaking for consumers — version and document them.

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.