sxchnge/AGENTS.md

Repository Agent Guidelines

Instruction hierarchy

• The rules in this file apply to every repository task.
• Before changing files in a scoped module, read and follow that module's AGENTS.md in addition to this file.
• For cross-module work, apply every relevant scoped instruction file and completion workflow.

Gitea task policy

Whenever creating or updating a Gitea task, correcting its tracker metadata, or preparing its implementation branch, use the $manage-gitea-task skill.

Every created task must have:

• A concise, outcome-oriented title.
• One or more relevant existing labels.
• A responsible person assigned as owner.
• The appropriate existing Gitea project.
• A self-contained body with Goal, Approach, Acceptance criteria, and Notes sections.

Do not guess an assignee, project, label, repository, task number, or module. Resolve missing metadata from authoritative repository or Gitea data, and ask the user when it cannot be determined. Do not create labels or projects unless explicitly requested. Never print, log, or commit API tokens or Git credentials.

Implementation branch policy

Every Gitea task that requires code changes must use a dedicated branch after the task exists and before repository files are changed. Tasks without repository changes do not require a branch.

• Name the branch <module>-<task-number> using the numeric Gitea task number without # and a specific lowercase kebab-case primary module.
• Do not add a codex/ prefix, task title, summary, or generic module such as feature, fix, or backend when a more specific module is known.
• For cross-module work, name the primary module and document secondary modules in the task or pull request.
• Push the branch and attach its exact short name to the issue ref before changing repository files.
• Verify the issue response contains the intended branch, project, labels, and assignee before implementation begins.

Scoped implementation requirements

• For backend code under api/, read and follow api/AGENTS.md. Before reporting completion, use the $review-backend-change skill.
• For Dart or Flutter code under frontend/, read and follow frontend/AGENTS.md. Before reporting completion, use the $review-frontend-change skill.
• For a change spanning both modules, use both completion-review skills.

These references are explicit because nested AGENTS.md and .agents/skills discovery depends on the working directory. Keeping the skills at the repository root makes them available to tasks launched from any repository subtree.

Optional security validation

Security checks are not mandatory prerequisites for completing a task, committing changes, or pushing a branch. Do not run security scans solely because files changed or a commit or push is planned. Run them when the user requests security validation or when security validation is an explicit part of the task's acceptance criteria.

References in scoped AGENTS.md files and completion-review skills to the root security requirements follow this optional policy; they do not create an automatic security gate for completion, commits, or pushes.

When security validation is requested, select commands from the task's own diff, including its uncommitted files, and ignore unrelated pre-existing worktree changes:

• Use make security-source-frontend for frontend source, dependencies, configuration, assets, or executable tests.
• Use make security-source-backend for backend Go source, dependencies, configuration, or protobuf contracts that affect generated backend code.
• Use make security-source for changes spanning both source areas or shared source-security inputs.
• Use make security-images SERVICES="..." for the exact affected Compose services when container contents, Dockerfiles, container dependencies, Compose image/build configuration, or deployment image selection change.
• Use make test-security for changes to the security gate, scanner wrappers, lock handling, exception evaluation, database handling, security-related Make targets, or deployment-gate orchestration. Pair it with the relevant live scan when that behavior is part of the requested validation.
• Use the full make security gate when the requested validation covers the canonical service set or requires a combined source and image verdict.

For scans that are run, use the latest stable scanner images, current validated databases, and the canonical exception manifest. Do not add native scanner suppressions or weaken thresholds. Any reviewed temporary exception must use the canonical exception manifest and satisfy its validation policy.

Report commands actually run and their outcomes, including any failures or external blockers. Do not claim successful validation for checks that were not run. This policy does not change executable CI or deployment gates.

Delivery workflow

For implementation work, finish the authorized delivery workflow: validate, commit the task contribution, push the implementation branch, and create or update its Gitea pull request. Do not leave completed implementation solely in an uncommitted working tree. Preserve unrelated changes and avoid mixing them into task commits. Record scope, validation, limitations, and PR links in the task and durable repository documentation. Merge only when authorized by the user. If work is delivered as stacked PRs, document dependencies and merge order.