146 lines
6.0 KiB
Markdown
146 lines
6.0 KiB
Markdown
# Codex Agent Repository Kit
|
|
|
|
Reusable baseline files for repositories that should be easy for Codex agents to inspect, modify, build, review, and release.
|
|
|
|
The kit has two modes:
|
|
|
|
- `agent-quickstart.md`: shortest prompts and decision tree for Codex agents.
|
|
- `new-repository.md`: agent workflow for a fresh repository.
|
|
- `existing-project.md`: agent workflow for upgrading an existing repository.
|
|
|
|
The files are intentionally universal. They do not assume Electron, React, Node, or any single stack. Node examples are included only because many Codex projects use them.
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## README Section Divider
|
|
|
|
Generated README files should use the shared rainbow section divider between major sections.
|
|
|
|
The divider is configured in `files/blueprint.json` as the `section-line` template:
|
|
|
|
```md
|
|
{{ template:section-line }}
|
|
```
|
|
|
|
When a project uses the README blueprint workflow, keep this divider in `blueprint.md` between major sections. Do not replace it with plain `---` unless the target platform cannot render inline images.
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## Agent Goal
|
|
|
|
Give every repository the same predictable anchor points:
|
|
|
|
```text
|
|
.
|
|
|-- AGENTS.md
|
|
|-- .codex/
|
|
| `-- project.md
|
|
|-- .gitea/
|
|
| `-- workflows/
|
|
| `-- build.yml
|
|
|-- docs/
|
|
| |-- release-checklist.md
|
|
| `-- security-review.md
|
|
|-- blueprint.md
|
|
|-- blueprint.json
|
|
|-- README.md
|
|
|-- SECURITY.md
|
|
|-- CHANGELOG.md
|
|
`-- .gitignore
|
|
```
|
|
|
|
Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `README.md`, `SECURITY.md`, and `CHANGELOG.md` may be enough. For an app or releasable tool, add the runner, release checklist, and README blueprint workflow.
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## Copy Map
|
|
|
|
| Template | Destination |
|
|
| --- | --- |
|
|
| `files/AGENTS.md` | `AGENTS.md` |
|
|
| `files/project.md` | `.codex/project.md` |
|
|
| `files/build-gitea.yml` | `.gitea/workflows/build.yml` |
|
|
| `files/release-checklist.md` | `docs/release-checklist.md` |
|
|
| `files/security-review.md` | `docs/security-review.md` |
|
|
| `files/blueprint.md` | `blueprint.md` |
|
|
| `files/blueprint.json` | `blueprint.json` |
|
|
| `files/SECURITY.md` | `SECURITY.md` |
|
|
| `files/CHANGELOG.md` | `CHANGELOG.md` |
|
|
|
|
Start with `agent-quickstart.md` when using this kit through Codex.
|
|
|
|
`manifest.json` contains the same copy map in a machine-readable format for agents.
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## Placeholders
|
|
|
|
Replace these after copying:
|
|
|
|
```text
|
|
PROJECT_NAME
|
|
PROJECT_DESCRIPTION
|
|
REPOSITORY_OWNER
|
|
REPOSITORY_NAME
|
|
PACKAGE_NAME
|
|
ARTIFACT_NAME
|
|
ARTIFACT_OUTPUT_DIRECTORY
|
|
AUTHOR_NAME
|
|
PROJECT_STACK
|
|
DOWNLOAD_URL
|
|
BUILD_COMMAND
|
|
TEST_COMMAND
|
|
LINT_COMMAND
|
|
AUDIT_COMMAND
|
|
```
|
|
|
|
If a placeholder does not apply, remove it instead of inventing fake information.
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## Gitea API Token
|
|
|
|
When working with private repositories on `git.wilkensxl.de`, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine.
|
|
|
|
Use `GITEA_TOKEN` only for read-oriented Gitea API checks unless the user explicitly asks for a write action. Typical safe checks include repository metadata, workflow run status, and package-read visibility. Never print the token, commit it, or copy it into workflow files.
|
|
|
|
Example status endpoint:
|
|
|
|
```text
|
|
GET https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
|
|
Authorization: token GITEA_TOKEN
|
|
```
|
|
|
|
`REGISTRY_TOKEN` is still the intended secret name for CI package publishing inside `.gitea/workflows/build.yml`.
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## Gitea Workflow Loop
|
|
|
|
After pushing commits that trigger a Gitea workflow, Codex agents must keep checking the resulting workflow run before finishing. Poll the run until it reaches a terminal state. If it succeeds, report the successful run. If it fails or is cancelled, inspect the failing job/logs, fix the issue when it is in scope, commit, push, and repeat the check loop for the next run. A fixed failure is not a stopping point; the loop continues after the follow-up push until a workflow succeeds or a concrete out-of-scope blocker is reached. Do not stop after a single in-progress status when the user asked the agent to continue the loop.
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## Agent Prompt For A New Repo
|
|
|
|
```text
|
|
Use templates/codex-project/new-repository.md.
|
|
Create the Codex repository baseline for this project.
|
|
Adapt placeholders to this repository.
|
|
Keep the existing stack choices minimal and do not add unnecessary frameworks.
|
|
Do not create a release.
|
|
```
|
|
|
|
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
|
|
|
## Agent Prompt For An Existing Repo
|
|
|
|
```text
|
|
Use templates/codex-project/existing-project.md.
|
|
Retrofit the Codex repository baseline.
|
|
Preserve existing project style and README knowledge.
|
|
Add only the files and commands that fit this repo.
|
|
Do not restructure application code unless required.
|
|
Do not create a release.
|
|
```
|