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.
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.
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.
Agents should read `manifest.json` before copying files. It is the source of truth for target paths, required files, optional files, and placeholder names.
`files/security-scan-gitea.yml` provides an optional weekly Gitea workflow for releasable projects.
It checks:
- stack-specific dependency vulnerabilities,
- suspicious code patterns,
- committed secrets or local config files,
- AI instruction-injection indicators.
The workflow is intentionally conservative. If it fails, an agent should inspect the matches and decide whether they are real risks, documentation examples, or test fixtures. Do not silence the workflow without documenting why.
`files/repo-cleanup-gitea.yml` provides an optional weekly Gitea workflow for active repositories.
It reports:
- generated files or dependency folders that were accidentally tracked,
- large tracked files that may belong in release artifacts or package storage,
- secret-prone local config files,
- stale remote branch candidates.
The workflow is intentionally non-destructive. It must not delete files, branches, packages, or releases. Agents should treat failures as maintenance reports, document intentional exceptions, and only remove repository data after explicit user approval.
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`.
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.
