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.
- 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.
- Treat `global-runner-1`, `global-runner-2`, and `global-runner-3` as the only available build runners.
- Run project builds, tests, audits, package jobs, installers, dependency setup, and releases only on Gitea Ubuntu runners with `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`.
- Do not run those heavy project commands on the user's local machine. Local checks are limited to lightweight reads and validation that do not install dependencies or create build artifacts.
- Do not add Windows or macOS runners. Use open-source Linux-compatible tooling or workflow workarounds that run on the Ubuntu runners.
- 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:

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

Run these commands through Gitea Actions on the configured Ubuntu runners, not on the user's local machine.

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.
- Lightweight local validation has passed, and the cheapest reliable runner-based verification command has been run through Gitea Actions 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.