codex-agent-repository-kit/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.
- 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.
- 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:

```bash
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:

```text
ARTIFACT_OUTPUT_DIRECTORY
```

Expected artifact names:

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