codex-agent-repository-kit/AGENTS.md

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:

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.