MrSphay/codex-agent-repository-kit
Template
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 5 Wiki Activity

first commit

Browse Source
This commit is contained in:
MrSphay
2026-05-02 02:33:57 +02:00
commit ae40f41c31
14 changed files with 997 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

98
README.md Normal file
View File

@@ -0,0 +1,98 @@
# 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.
## 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.
## 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.
## 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.
## 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.
```
## 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.
```

86
agent-quickstart.md Normal file
View File

@@ -0,0 +1,86 @@
# Agent Quickstart
Use this file when you want Codex to apply the repository kit with minimal instructions.
## New Repository Prompt
```text
Apply the Codex Agent Repository Kit from templates/codex-project.
Use new-repository.md as the workflow.
Create the smallest useful baseline for this repository.
Detect the stack and replace placeholders with real project values.
Keep commands truthful: do not add commands that cannot run.
Keep the README generator only if it adds value.
Do not create a release.
Run the cheapest available verification before finishing.
```
## Existing Repository Prompt
```text
Apply the Codex Agent Repository Kit from templates/codex-project.
Use existing-project.md as the workflow.
Preserve existing code, README knowledge, CI behavior, and project style.
Add missing Codex agent context, security review, release checklist, and optional README generator files.
Keep commands truthful: do not add commands that cannot run.
Do not create a release.
Run the cheapest available verification before finishing.
```
## Agent Decision Tree
```text
Is this a fresh repo?
yes -> use new-repository.md
no -> use existing-project.md
Does the project already have README structure?
yes -> preserve it; only add blueprint files if useful
no -> add blueprint.md and blueprint.json
Does the project produce artifacts?
yes -> add downloads/artifacts section and release checklist
no -> keep downloads section minimal or remove it
Does the project have CI?
yes -> patch existing workflow
no -> add .gitea/workflows/build.yml only when commands are known
Are commands unknown?
yes -> document PENDING in .codex/project.md
no -> wire commands into AGENTS.md and CI
```
## Minimal File Set
For tiny projects:
```text
AGENTS.md
.codex/project.md
README.md
SECURITY.md
CHANGELOG.md
```
For releasable projects:
```text
AGENTS.md
.codex/project.md
README.md
SECURITY.md
CHANGELOG.md
docs/release-checklist.md
docs/security-review.md
.gitea/workflows/build.yml
```
For README-generator projects:
```text
blueprint.md
blueprint.json
README.md
```

151
existing-project.md Normal file
View File

@@ -0,0 +1,151 @@
# Existing Project Agent Workflow
Use this file when an existing repository should become easier for Codex agents to maintain.
## Objective
Add a Codex-friendly repository baseline without flattening the project's existing structure, README voice, or release process.
## Rules
- Preserve existing application code.
- Preserve existing README knowledge.
- Do not rename files or folders unless the project already requires it.
- Do not replace a working CI pipeline wholesale.
- Add missing structure gradually.
- Prefer documenting current reality over inventing a new process.
## Steps
### 1. Inspect First
Run:
```bash
git status --short
```
Read:
```text
README*
package.json / pyproject.toml / Cargo.toml / go.mod / *.csproj
.github/workflows/*
.gitea/workflows/*
docs/*
```
Identify:
- stack,
- package manager,
- build command,
- test command,
- lint command,
- audit command,
- release artifacts,
- current CI,
- existing release notes or changelog,
- security-sensitive behavior.
### 2. Add Agent Context
Add `AGENTS.md` first. Keep it short and factual.
Then add `.codex/project.md` with:
- project purpose,
- authoritative commands,
- artifact locations,
- release process,
- security constraints.
### 3. Add Documentation Files
Add only missing files:
```text
SECURITY.md
CHANGELOG.md
docs/security-review.md
docs/release-checklist.md
```
If equivalent files already exist, update those instead of duplicating them.
### 4. README Generator Decision
Use README blueprint generation only when it helps.
Use it when:
- README is large enough to benefit from structure,
- project has downloads or release artifacts,
- repeated README updates are expected.
Avoid it when:
- README is tiny,
- project has a strong existing documentation system,
- generator output would erase project-specific style.
If converting:
1. Copy the current README content into `blueprint.md`.
2. Add `blueprint.json`.
3. Add a `readme` command.
4. Generate `README.md`.
5. Compare the diff carefully.
### 5. CI Retrofit
If CI already exists:
- add missing audit/check steps,
- keep existing runner labels,
- keep existing artifact names unless they are broken,
- avoid changing deployment behavior.
If CI does not exist:
- add `.gitea/workflows/build.yml` from the template,
- remove stack-specific steps that do not apply,
- keep publishing disabled until credentials and artifact names are known.
### 6. Security Review
Fill `docs/security-review.md` with known facts.
At minimum check for:
```text
eval
dynamic Function
unsafe HTML injection
shell execution
external network calls
file writes
secret persistence
committed .env files
```
Use the stack-native audit command when possible:
| Stack | Audit command |
| --- | --- |
| Node | `npm audit --omit=dev --audit-level=high` |
| Python | `pip-audit` or `uv pip audit` |
| Rust | `cargo audit` |
| Go | `govulncheck ./...` |
| .NET | `dotnet list package --vulnerable` |
### 7. Finish
Before final response:
- run `git diff --check`,
- run the smallest reliable verification command,
- list files changed,
- mention any skipped checks,
- do not create a release unless explicitly requested.

48
files/AGENTS.md Normal file
View File

@@ -0,0 +1,48 @@
# Agent Instructions
## Project
PROJECT_NAME: PROJECT_DESCRIPTION
## Repository Rules
- 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.
- Do not rewrite history or run destructive git commands unless explicitly requested.
- Do not create a release unless explicitly requested.
## 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`.
## Artifacts
Expected artifact output:
```text
ARTIFACT_OUTPUT_DIRECTORY
```
Expected artifact names:
```text
ARTIFACT_NAME
```
## Security Notes
- Review `docs/security-review.md` before release work.
- Treat generated credentials and config files as sensitive.
- Keep external network calls documented.
- Prefer local processing for user data.

8
files/CHANGELOG.md Normal file
View File

@@ -0,0 +1,8 @@
# Changelog
All notable changes to this project are documented here.
## Unreleased
- Initial project setup.

22
files/SECURITY.md Normal file
View File

@@ -0,0 +1,22 @@
# Security Policy
## Supported Versions
| Version | Supported |
| --- | --- |
| Latest | Yes |
## Reporting A Vulnerability
Please report security issues privately to the project owner.
Do not include secrets, production data, or private credentials in public issues.
## Project Security Principles
- Keep secrets out of the repository.
- Prefer local processing for user data.
- Document external network calls.
- Keep release artifacts reproducible through CI.
- Run dependency audits before releases.

30
files/blueprint.json Normal file
View File

@@ -0,0 +1,30 @@
{
"ids": {
"github": "REPOSITORY_OWNER/REPOSITORY_NAME"
},
"badges": [
{
"alt": "Build",
"img": "https://img.shields.io/badge/build-Gitea%20Runner-2563eb",
"url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/actions"
},
{
"alt": "Version",
"img": "https://img.shields.io/badge/version-0.1.0-111827",
"url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/releases"
}
],
"headingPrefix": {
"1": "",
"2": ""
},
"line": "rainbow",
"templates": [
{
"name": "section-line",
"template": "<p align=\"center\"><img src=\"https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png\" alt=\"-----------------------------------------------------\" width=\"100%\"></p>"
}
],
"text": "PROJECT_DESCRIPTION"
}

76
files/blueprint.md Normal file
View File

@@ -0,0 +1,76 @@
{{ template:title }}
{{ template:badges }}
{{ template:section-line }}
{{ template:table-of-contents }}
{{ template:section-line }}
## Overview
PROJECT_DESCRIPTION
{{ template:section-line }}
## Features
| Area | Description |
| --- | --- |
| Core | Describe the main project capability |
| Workflow | Describe the primary user or developer workflow |
| Build | Describe how artifacts are produced |
| Security | Describe the default security posture |
{{ template:section-line }}
## Installation
```bash
INSTALL_COMMAND
```
{{ template:section-line }}
## Development
```bash
DEV_COMMAND
LINT_COMMAND
TEST_COMMAND
BUILD_COMMAND
```
{{ template:section-line }}
## Downloads
| Variant | Download |
| --- | --- |
| Latest artifact | [Download latest](DOWNLOAD_URL) |
Private repositories may require an active session or a token with package read access.
{{ template:section-line }}
## Security
Security posture:
| Area | State |
| --- | --- |
| Secrets | Secrets must not be committed |
| Dependency audit | CI should run the project dependency audit |
| User data | User data should stay local unless explicitly documented |
| External services | Network calls should be documented |
See `SECURITY.md` and `docs/security-review.md`.
{{ template:section-line }}
## Release
Release readiness is tracked in `docs/release-checklist.md`.
{{ template:section-line }}
## Project Info
| Field | Value |
| --- | --- |
| Author | `AUTHOR_NAME` |
| Repository | `REPOSITORY_OWNER/REPOSITORY_NAME` |
| Stack | `PROJECT_STACK` |
| README workflow | Blueprint workflow based on `andreasbm/readme` |

78
files/build-gitea.yml Normal file
View File

@@ -0,0 +1,78 @@
name: Build
on:
push:
branches:
- main
- master
workflow_dispatch:
jobs:
build:
runs-on: ubuntu-latest
env:
REGISTRY_TOKEN: ${{ secrets.REGISTRY_TOKEN }}
steps:
- name: Checkout
uses: actions/checkout@v4
# Replace this runtime setup block with the stack this project uses.
# Examples:
# - Node: actions/setup-node@v4
# - Python: actions/setup-python@v5
# - Go: actions/setup-go@v5
# - Rust: dtolnay/rust-toolchain@stable
- name: Setup runtime
run: echo "Configure PROJECT_STACK runtime here"
- name: Install dependencies
run: INSTALL_COMMAND
- name: Audit dependencies
run: AUDIT_COMMAND
- name: Lint
run: LINT_COMMAND
- name: Test
run: TEST_COMMAND
- name: Build
run: BUILD_COMMAND
- name: Upload artifacts
uses: actions/upload-artifact@v3
with:
name: PROJECT_NAME-artifacts
path: |
ARTIFACT_OUTPUT_DIRECTORY/**
- name: Publish latest package
if: ${{ env.REGISTRY_TOKEN != '' }}
shell: bash
run: |
app_version="PROJECT_VERSION"
package_version="${app_version}-${GITHUB_SHA::7}"
latest_url="https://git.wilkensxl.de/api/packages/REPOSITORY_OWNER/generic/PACKAGE_NAME/latest"
for artifact in ARTIFACT_OUTPUT_DIRECTORY/*; do
[ -f "$artifact" ] || continue
file_name="$(basename "$artifact")"
curl --fail-with-body \
--user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" \
--upload-file "$artifact" \
"https://git.wilkensxl.de/api/packages/REPOSITORY_OWNER/generic/PACKAGE_NAME/${package_version}/${file_name}"
done
curl --silent --show-error --user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" --request DELETE "${latest_url}" || true
for artifact in ARTIFACT_OUTPUT_DIRECTORY/*; do
[ -f "$artifact" ] || continue
file_name="$(basename "$artifact")"
curl --fail-with-body \
--user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" \
--upload-file "$artifact" \
"${latest_url}/${file_name}"
done

72
files/project.md Normal file
View File

@@ -0,0 +1,72 @@
# Codex Project Notes
## Project
`PROJECT_NAME` is `PROJECT_DESCRIPTION`
Repository:
```text
REPOSITORY_OWNER/REPOSITORY_NAME
```
## Commands
Use these commands as the source of truth:
```text
LINT_COMMAND
TEST_COMMAND
BUILD_COMMAND
AUDIT_COMMAND
README_COMMAND
```
If a command does not exist, document the closest safe alternative. Do not invent commands that cannot run.
## Stack
```text
PROJECT_STACK
```
Package manager or build tool:
```text
PACKAGE_MANAGER
```
## Build Artifacts
Release artifacts are produced in:
```text
ARTIFACT_OUTPUT_DIRECTORY
```
Expected files:
```text
ARTIFACT_NAME
```
## Security Rules
- Do not commit secrets, tokens, `.env` files, certificates, or private keys.
- Treat generated credentials as sensitive.
- Prefer local generation and local processing for user data.
- Keep dependency audit results visible in CI where possible.
- Do not add external network calls unless the feature explicitly requires them.
## Release Rules
Before a release:
1. run the release checklist,
2. verify CI is green,
3. verify download links,
4. update README and changelog,
5. create a tag,
6. create the release.
Do not create releases unless the user explicitly asks for a release.

36
files/release-checklist.md Normal file
View File

@@ -0,0 +1,36 @@
# Release Checklist
## Version
- [ ] Version number updated.
- [ ] Changelog updated.
- [ ] README regenerated if blueprint files changed.
## Quality
- [ ] Working tree is clean.
- [ ] Lint/type checks pass.
- [ ] Tests pass or missing tests are documented.
- [ ] Build succeeds in CI.
## Security
- [ ] Security review is current.
- [ ] Dependency audit is clean or documented.
- [ ] No secrets are committed.
- [ ] Release artifacts do not contain local config files.
## Artifacts
- [ ] Artifacts are uploaded.
- [ ] Download links work.
- [ ] Package registry links work if used.
- [ ] Installer/portable/archive naming is clear.
## Release
- [ ] Git tag created.
- [ ] Release notes written.
- [ ] Release published.
- [ ] Post-release download smoke test completed.

54
files/security-review.md Normal file
View File

@@ -0,0 +1,54 @@
# Security Review
## Scope
Project:
```text
PROJECT_NAME
```
Reviewed version or commit:
```text
COMMIT_OR_VERSION
```
## Code Patterns Checked
- [ ] No `eval`.
- [ ] No dynamic `Function` constructor.
- [ ] No unsafe HTML injection.
- [ ] No unexpected shell execution.
- [ ] No unexpected external network calls.
- [ ] No secrets committed.
- [ ] No unsafe file writes outside expected user-selected paths.
## Dependency Review
Command:
```bash
AUDIT_COMMAND
```
Result:
```text
PENDING
```
## Runtime Review
- [ ] Least-privilege runtime configuration.
- [ ] External URLs documented.
- [ ] Local data storage documented.
- [ ] Sensitive data is not persisted unless explicitly required.
## Release Notes
Known residual risks:
```text
None documented yet.
```

79
manifest.json Normal file
View File

@@ -0,0 +1,79 @@
{
"name": "codex-agent-repository-kit",
"version": "1.0.0",
"description": "Universal repository baseline for Codex-assisted projects.",
"workflows": {
"newRepository": "new-repository.md",
"existingProject": "existing-project.md",
"quickstart": "agent-quickstart.md"
},
"copyMap": [
{
"source": "files/AGENTS.md",
"target": "AGENTS.md",
"required": true
},
{
"source": "files/project.md",
"target": ".codex/project.md",
"required": true
},
{
"source": "files/SECURITY.md",
"target": "SECURITY.md",
"required": false
},
{
"source": "files/CHANGELOG.md",
"target": "CHANGELOG.md",
"required": false
},
{
"source": "files/release-checklist.md",
"target": "docs/release-checklist.md",
"required": false
},
{
"source": "files/security-review.md",
"target": "docs/security-review.md",
"required": false
},
{
"source": "files/blueprint.md",
"target": "blueprint.md",
"required": false
},
{
"source": "files/blueprint.json",
"target": "blueprint.json",
"required": false
},
{
"source": "files/build-gitea.yml",
"target": ".gitea/workflows/build.yml",
"required": false
}
],
"placeholders": [
"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",
"README_COMMAND",
"INSTALL_COMMAND",
"DEV_COMMAND",
"PACKAGE_MANAGER",
"PROJECT_VERSION"
]
}

159
new-repository.md Normal file
View File

@@ -0,0 +1,159 @@
# New Repository Agent Workflow
Use this file as the agent-facing workflow for a fresh repository.
## Objective
Create a small, clear repository baseline that helps future Codex agents understand:
- what the project is,
- how to build and verify it,
- how releases are prepared,
- what security rules matter,
- where generated artifacts are expected.
## Steps
### 1. Inspect The Repo
Run:
```bash
git status --short
```
Identify:
- repository name,
- likely stack,
- package manager or build tool,
- expected artifact type,
- whether the repo is app, service, library, script, documentation, or infrastructure.
### 2. Copy Baseline Files
Create directories as needed and copy:
```text
files/AGENTS.md -> AGENTS.md
files/project.md -> .codex/project.md
files/SECURITY.md -> SECURITY.md
files/CHANGELOG.md -> CHANGELOG.md
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/build-gitea.yml -> .gitea/workflows/build.yml
```
Skip `build-gitea.yml` when the project has no CI target yet. Skip README blueprint files when the project should keep a very small manual README.
### 3. Replace Placeholders
Replace only with facts that are known.
Required:
```text
PROJECT_NAME
PROJECT_DESCRIPTION
REPOSITORY_OWNER
REPOSITORY_NAME
```
Optional:
```text
PACKAGE_NAME
ARTIFACT_NAME
ARTIFACT_OUTPUT_DIRECTORY
AUTHOR_NAME
PROJECT_STACK
DOWNLOAD_URL
BUILD_COMMAND
TEST_COMMAND
LINT_COMMAND
AUDIT_COMMAND
```
Delete sections that do not apply.
### 4. Add Standard Commands
Prefer these command names when the stack supports them:
```text
dev
lint
test
build
audit
readme
release:check
```
For Node projects, a reasonable baseline is:
```json
{
"scripts": {
"lint": "tsc --noEmit",
"build": "tsc --noEmit",
"audit": "npm audit --omit=dev --audit-level=high",
"readme": "npx --yes @appnest/readme generate -i blueprint.md -c blueprint.json",
"release:check": "npm run lint && npm run build"
}
}
```
Do not add commands that cannot run.
### 5. Create Or Update README
If using the generator:
1. Fill `blueprint.md`.
2. Fill `blueprint.json`.
3. Add a `readme` command.
4. Generate `README.md`.
5. Commit `README.md`, `blueprint.md`, and `blueprint.json`.
If not using the generator, keep a manual README with the same main sections:
```text
Overview
Features
Installation
Development
Downloads or Artifacts
Security
Release
Project Info
```
### 6. Add CI
Create the smallest useful workflow:
```text
checkout
setup runtime
install dependencies
audit
lint/test
build
upload artifacts
```
Only publish artifacts to a package registry when the artifact names and credentials are known.
### 7. Finish
Before final response:
- run formatting or validation if available,
- run the cheapest reliable verification command,
- check `git diff --check`,
- summarize changed files,
- do not create a release unless explicitly requested.