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

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.
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.
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.
Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported.

3.9 KiB Raw Blame History