MrTrust/files/AGENTS.md

Agent Instructions

Project

PROJECT_NAME: PROJECT_DESCRIPTION

Repository Rules

• Start by reading manifest.json, then the workflow file that matches the task: new-repository.md for fresh repos or existing-project.md for retrofit work.
• Use the matching profiles/*.md file when the repository stack is detected. Profiles are guidance, not permission to ignore existing project conventions.
• Conserve context tokens: search with rg or targeted file lists first, read only the files needed for the task, summarize large outputs instead of pasting them, and avoid loading generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
• Follow the manifest.json copy map for source and target paths. Do not invent alternate locations unless the target repository already has an equivalent convention.
• Prefer existing project patterns over new abstractions.
• Keep changes scoped to the user's request.
• Do not commit secrets, .env files, private keys, certificates, or tokens.
• Do not rewrite history or run destructive git commands unless explicitly requested.
• Do not create a release unless explicitly requested.
• At the start of every user-requested task, briefly check the repository for upstream updates and apply them immediately with a safe fast-forward pull when the working tree is clean. If local changes exist, do not overwrite them; fetch or report the blocker before editing.
• Check git status --short before editing and before finishing. Preserve unrelated user changes.
• Replace all applicable placeholders. Remove non-applicable placeholder sections instead of leaving fake values.
• Derive REPOSITORY_OWNER and REPOSITORY_NAME from the target repository remote or GITHUB_REPOSITORY. Never reuse the owner from this template repository.
• If GITEA_TOKEN is available locally, use it only for read-only Gitea API checks such as private repository metadata, package-read visibility, and Actions run status. Never print, commit, or store the token.
• When you find a real, actionable follow-up that is outside the current scope or can be worked on independently, create a tracker issue so humans or other agents can pick it up later or in parallel. Do not create issues for work you can safely finish in the current task. If no issue tracker is available, update docs/agent-handoff.md instead.
• Keep issues scoped and actionable: include the observed problem, impact, affected files or commands, suggested next steps, and any verification already performed. Never include secrets, tokens, private data, or sensitive logs in public issues.
• After pushing commits that trigger a Gitea workflow, poll the workflow run until it succeeds. If it fails or is cancelled, inspect the failing job/logs, fix the issue when in scope, push again, and repeat the workflow check loop. Fixing and pushing a workflow failure is not a stopping point.
• When the project uses blueprint.md and blueprint.json for README generation, keep the rainbow {{ template:section-line }} divider between major README sections. Do not replace it with plain --- unless the target renderer cannot display inline images.
• If README blueprint files are changed, regenerate or update README.md in the same change and verify the generated output renders reasonably.
• For releasable projects, add or preserve .gitea/workflows/security-scan.yml using files/security-scan-gitea.yml unless the repository already has equivalent scheduled security automation.
• For active projects, add or preserve .gitea/workflows/repo-cleanup.yml using files/repo-cleanup-gitea.yml unless the repository already has equivalent cleanup checks.
• Add or preserve .gitea/workflows/dependency-check.yml, .gitea/workflows/release-dry-run.yml, and .gitea/workflows/template-compliance.yml when the repository is active, releasable, or intended as a Codex-maintained project.
• Repository cleanup automation must be non-destructive. Do not delete branches, packages, releases, or tracked files without explicit user approval.
• Dependency, compliance, and release dry-run automation must report findings only. Do not auto-update dependencies, auto-open PRs, create tags, publish packages, or create releases without explicit user approval.
• Gitea Actions artifacts are not Gitea Package Registry packages. If the user expects a package/download entry, add an explicit registry publish step and verify the package URL after the workflow succeeds.
• Keep Codex kit files in source control when they are useful for agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly asks to ship repository-maintenance files.

Commands

Use these commands when available:

LINT_COMMAND
TEST_COMMAND
BUILD_COMMAND
AUDIT_COMMAND

If a command is missing, inspect the project and document the closest safe alternative in .codex/project.md.

Keep .codex/project.md and this AGENTS.md aligned when commands, artifact paths, or release rules change.

Artifacts

Expected artifact output:

ARTIFACT_OUTPUT_DIRECTORY

Expected artifact names:

ARTIFACT_NAME

Security Notes

• Review docs/security-review.md before release work.
• Fill docs/security-review.md with actual checked commands and results when performing release-readiness work.
• Review scheduled security workflow failures before changing code. Treat matches as leads: they may be true positives, documentation examples, or test fixtures.
• Review repository cleanup workflow failures as maintenance leads. Document intentional exceptions instead of blindly deleting files.
• Review dependency and template compliance workflow failures as maintenance leads. Preserve project-specific conventions when they are documented.
• Treat generated credentials and config files as sensitive.
• Keep external network calls documented.
• Prefer local processing for user data.
• Keep CI publishing secrets in repository or organization secrets, not in tracked files. REGISTRY_TOKEN is the default package publishing secret name for the Gitea workflow template.
• Use URL-safe package filenames when publishing to a registry. Do not put raw artifact names with spaces or punctuation directly into upload URLs.
• Do not include Codex kit metadata such as AGENTS.md, .codex/, blueprint.md, blueprint.json, template workflow files, or agent handoff notes in downloadable release artifacts unless explicitly requested.
• Ensure .gitignore covers local config, build outputs, logs, temporary files, and secret material for the detected stack.

Finish Checklist

• git diff --check passes.
• The cheapest reliable verification command has been run, or the reason it could not be run is documented.
• README, changelog, security review, and release checklist are updated when the change touches release behavior.
• docs/agent-handoff.md is updated when work is interrupted, risky, or spans multiple sessions.
• Independent follow-up work has tracker issues, or docs/agent-handoff.md explains why issues could not be created.
• Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported.