70 lines
3.6 KiB
Markdown
70 lines
3.6 KiB
Markdown
# Agent Instructions For This Repository
|
|
|
|
This file is for Codex agents working on the Codex Agent Repository Kit itself. The public `README.md` is for humans and should stay focused on setup and usage.
|
|
|
|
## Start Of Task
|
|
|
|
- Check `git status --short`.
|
|
- If the working tree is clean, run `git pull --ff-only` before editing.
|
|
- If local changes exist, preserve them and do not overwrite user work.
|
|
- Conserve context tokens: use `rg`, targeted file reads, and short summaries instead of loading unrelated files or long logs.
|
|
|
|
## Runner Policy
|
|
|
|
- The only supported build runners are the Gitea global runners `global-runner-1`, `global-runner-2`, and `global-runner-3`.
|
|
- Use only these Linux runner labels in workflow templates and generated setup instructions: `ubuntu-latest`, `ubuntu-24.04`, and `ubuntu-22.04`.
|
|
- Never run project builds, tests, audits, package jobs, installers, dependency bootstraps, or release jobs on the local machine. Use the Gitea Ubuntu runners so the user's machine stays clean.
|
|
- Do not introduce Windows or macOS runners. If a project appears to need Windows-specific tooling, document or implement an open-source Linux-compatible workaround that runs on the Ubuntu runners.
|
|
- Lightweight local checks are allowed when they do not install dependencies or create build artifacts, for example JSON parsing, manifest path checks, `rg`, `git diff --check`, and API status checks.
|
|
|
|
## Repository Purpose
|
|
|
|
This repository ships reusable baseline files for other repositories:
|
|
|
|
- `files/` contains templates copied into target repositories.
|
|
- `agent-quickstart.md`, `new-repository.md`, and `existing-project.md` are agent workflows.
|
|
- `manifest.json` is the source of truth for copy targets and placeholders.
|
|
- `profiles/` contains stack-specific guidance.
|
|
|
|
## Editing Rules
|
|
|
|
- Keep repository owner, repository name, project names, and local paths dynamic. This kit intentionally targets `https://git.wilkensxl.de` and SSH port `2222`, so keep that host/port consistent in user-facing setup and Gitea workflow defaults.
|
|
- Keep workflow examples and generated CI defaults on the supported Ubuntu runner labels only.
|
|
- If a new placeholder is introduced, update `manifest.json`, the README placeholder list, and placeholder scans in workflow templates.
|
|
- Keep `README.md` user-facing. Put agent operating rules in this file or the workflow docs.
|
|
- Keep `files/AGENTS.md` generic; it is copied into target repositories and must not describe this repository specifically.
|
|
- Do not include secrets, tokens, private data, or sensitive logs in docs, issues, commits, or release notes.
|
|
|
|
## Follow-up Work
|
|
|
|
- Create focused tracker issues for real follow-up work that is outside the current scope or can be done independently.
|
|
- Do not create issues for work that can be safely completed in the current task.
|
|
- If issue creation is unavailable, update `docs/agent-handoff.md` with the blocker and next steps.
|
|
|
|
## Verification
|
|
|
|
Before committing:
|
|
|
|
```powershell
|
|
Get-Content manifest.json | ConvertFrom-Json | Out-Null
|
|
Get-Content manifest.schema.json | ConvertFrom-Json | Out-Null
|
|
Get-Content files\blueprint.json | ConvertFrom-Json | Out-Null
|
|
git diff --check
|
|
```
|
|
|
|
Also verify:
|
|
|
|
- every `manifest.json` copyMap source exists,
|
|
- every profile path exists,
|
|
- reusable files contain no private instance defaults such as a specific username or private host,
|
|
- `README.md` documents every placeholder listed in `manifest.json`.
|
|
|
|
## Release
|
|
|
|
- Bump `manifest.json` version.
|
|
- Update `CHANGELOG.md`.
|
|
- Commit changes.
|
|
- Create an annotated tag such as `v1.0.2`.
|
|
- Push `main` and tags.
|
|
- Create or update the Gitea release when a valid API token is available.
|