cnsplots AGENTS.md

AGENTS.md

Use this file as the repo-specific operating manual for branch, validation, commit, and pull request behavior. When two rules appear to overlap, follow the more specific rule.

Working branch rules

• Never work directly on main.
• If starting new work, create and switch to a new branch from main named <type>/<short-name> such as feature/<short-name>, bugfix/<short-name>, docs/<short-name>, refactor/<short-name>, or chore/<short-name>.
• If you discover local changes while on main, create the new branch first and continue the work there.
• If already on the intended work branch, continue there unless explicitly told to create a new branch.
• Do not rename or delete branches unless explicitly asked.
• Do not use gh to create branches; use git.

Implementation rules

• Follow the smallest-change approach that fully solves the task.
• Keep the diff scoped to the task at hand. If you notice a separate issue, mention it instead of bundling it into the same change.
• Do not make unrelated refactors or opportunistic cleanup unless explicitly asked.
• Ask before:
  • adding or removing dependencies
  • changing CI, build, release, or deployment files
  • modifying infrastructure, secrets, or environment configuration
  • running destructive commands

Validation rules

• Before opening a pull request, run:
  • make test
  • make lint
• Run validation after the proposed changes are in place so the results match the branch you plan to submit.
• If either command fails:
  • fix the issue when it is clearly in scope
  • otherwise stop and report the failure clearly, including which command failed
• Do not claim tests passed unless they were actually run successfully.

Commit rules

• Keep commits small and messages clear.
• Prefer a single commit for a small, self-contained change.
• For larger work, use multiple logical commits rather than one large commit.
• Do not amend, squash, or rewrite existing commits unless explicitly asked.
• Each commit message must start with <emoji> <subject>.
• Use a Unicode Gitmoji, not a shortcode.
• In the subject line, do not add a scope, colon, or trailing period.
• Base the subject only on the staged diff.
• Do not infer intent from unstaged files, branch names, task titles, or unrelated context.
• Prefer the smallest accurate claim.
• When multiple edits exist, describe only the dominant change.
• Write in imperative mood.
• Capitalize the first word unless syntax or style requires otherwise.
• For subject use at most five words, excluding the emoji.
• Add a body only when it meaningfully explains why, highlights follow-up work, or calls out a breaking change.
• If you add a body, leave one blank line after the subject and keep the body concise.