generated from MrSphay/codex-agent-repository-kit
Initial commit
This commit is contained in:
368
README.md
Normal file
368
README.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Codex Agent Repository Kit
|
||||
|
||||
Reusable setup kit for new or existing repositories that should be easy for Codex agents, humans, and CI workflows to maintain.
|
||||
|
||||
This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quickstart.md`, `new-repository.md`, and `existing-project.md`.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## What This Kit Adds
|
||||
|
||||
- `AGENTS.md` and `.codex/project.md` for agent context.
|
||||
- Optional Gitea workflows for build, security scan, cleanup, dependency check, release dry run, and template compliance.
|
||||
- Release, security, handoff, changelog, and contribution templates.
|
||||
- README blueprint templates for projects that want generated README output.
|
||||
- Stack notes for Node, Electron, Python, Docker, and static-site projects.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Recommended New Repository Setup
|
||||
|
||||
1. Create the repository in Gitea.
|
||||
2. Clone it locally with SSH.
|
||||
3. Copy this kit into the repository with Codex or manually from `files/`.
|
||||
4. Replace placeholders with real project values.
|
||||
5. Add repository secrets for CI publishing.
|
||||
6. Commit and push the baseline.
|
||||
7. Let the Gitea workflows report any missing setup.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## SSH Setup
|
||||
|
||||
Generate a key if you do not already have one:
|
||||
|
||||
```powershell
|
||||
ssh-keygen -t ed25519 -C "you@example.com"
|
||||
```
|
||||
|
||||
Start the SSH agent and add the key:
|
||||
|
||||
```powershell
|
||||
Start-Service ssh-agent
|
||||
ssh-add $env:USERPROFILE\.ssh\id_ed25519
|
||||
```
|
||||
|
||||
Show the public key:
|
||||
|
||||
```powershell
|
||||
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
|
||||
```
|
||||
|
||||
Add that public key in Gitea:
|
||||
|
||||
```text
|
||||
Profile -> Settings -> SSH / GPG Keys -> Add Key
|
||||
```
|
||||
|
||||
Clone with SSH:
|
||||
|
||||
```bash
|
||||
git clone ssh://git@git.wilkensxl.de:2222/OWNER/REPOSITORY.git
|
||||
cd REPOSITORY
|
||||
```
|
||||
|
||||
Optional SSH config:
|
||||
|
||||
```text
|
||||
Host git.wilkensxl.de
|
||||
HostName git.wilkensxl.de
|
||||
User git
|
||||
Port 2222
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
With that config, this shorter clone URL also works:
|
||||
|
||||
```bash
|
||||
git clone git@git.wilkensxl.de:OWNER/REPOSITORY.git
|
||||
```
|
||||
|
||||
Verify the remote:
|
||||
|
||||
```bash
|
||||
git remote -v
|
||||
git status --short
|
||||
```
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Applying The Kit With Codex
|
||||
|
||||
For a new repository, start Codex in the target repository and use:
|
||||
|
||||
```text
|
||||
Use the Codex Agent Repository Kit.
|
||||
Read manifest.json, then use new-repository.md.
|
||||
Create the smallest useful baseline for this repository.
|
||||
Replace placeholders with real values from this repository.
|
||||
Keep commands truthful and do not invent scripts that cannot run.
|
||||
Do not create a release.
|
||||
```
|
||||
|
||||
For an existing repository:
|
||||
|
||||
```text
|
||||
Use the Codex Agent Repository Kit.
|
||||
Read manifest.json, then use existing-project.md.
|
||||
Retrofit the baseline without replacing existing project structure or README knowledge.
|
||||
Preserve current CI behavior and project style.
|
||||
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>
|
||||
|
||||
## Manual Copy Map
|
||||
|
||||
Use `manifest.json` as the source of truth. Common targets:
|
||||
|
||||
| Template | Target |
|
||||
| --- | --- |
|
||||
| `files/AGENTS.md` | `AGENTS.md` |
|
||||
| `files/project.md` | `.codex/project.md` |
|
||||
| `files/build-gitea.yml` | `.gitea/workflows/build.yml` |
|
||||
| `files/security-scan-gitea.yml` | `.gitea/workflows/security-scan.yml` |
|
||||
| `files/repo-cleanup-gitea.yml` | `.gitea/workflows/repo-cleanup.yml` |
|
||||
| `files/dependency-check-gitea.yml` | `.gitea/workflows/dependency-check.yml` |
|
||||
| `files/release-dry-run-gitea.yml` | `.gitea/workflows/release-dry-run.yml` |
|
||||
| `files/template-compliance-gitea.yml` | `.gitea/workflows/template-compliance.yml` |
|
||||
| `files/SECURITY.md` | `SECURITY.md` |
|
||||
| `files/CHANGELOG.md` | `CHANGELOG.md` |
|
||||
| `files/CONTRIBUTING.md` | `CONTRIBUTING.md` |
|
||||
| `files/release-checklist.md` | `docs/release-checklist.md` |
|
||||
| `files/security-review.md` | `docs/security-review.md` |
|
||||
| `files/agent-handoff.md` | `docs/agent-handoff.md` |
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Required Placeholder Values
|
||||
|
||||
Replace or remove all placeholders before considering a repository ready:
|
||||
|
||||
```text
|
||||
PROJECT_NAME
|
||||
PROJECT_DESCRIPTION
|
||||
REPOSITORY_OWNER
|
||||
REPOSITORY_NAME
|
||||
PACKAGE_NAME
|
||||
ARTIFACT_NAME
|
||||
ARTIFACT_OUTPUT_DIRECTORY
|
||||
AUTHOR_NAME
|
||||
PROJECT_STACK
|
||||
DOWNLOAD_URL
|
||||
CI_URL
|
||||
RELEASES_URL
|
||||
BUILD_COMMAND
|
||||
TEST_COMMAND
|
||||
LINT_COMMAND
|
||||
AUDIT_COMMAND
|
||||
README_COMMAND
|
||||
INSTALL_COMMAND
|
||||
DEV_COMMAND
|
||||
PACKAGE_MANAGER
|
||||
PROJECT_VERSION
|
||||
COMMIT_OR_VERSION
|
||||
```
|
||||
|
||||
If a value does not apply, remove that section instead of leaving fake data. If a value is genuinely unknown, mark it as `PENDING`.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Token Overview
|
||||
|
||||
Use separate tokens for separate jobs.
|
||||
|
||||
| Token | Location | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `REGISTRY_TOKEN` | Repository secret | CI package publishing from Gitea Actions |
|
||||
| `GITEA_TOKEN` | Local environment or repository secret | Gitea API access for issues, releases, workflow polling, and repository metadata |
|
||||
|
||||
Repository secrets are available to workflows. They are not visible to local Codex sessions. Local Codex API actions need a local environment variable.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Gitea Token Permissions
|
||||
|
||||
For both tokens, choose this repository access level:
|
||||
|
||||
```text
|
||||
Repository and Organization Access: All (public, private, and limited)
|
||||
```
|
||||
|
||||
Use separate tokens where possible. A package-only token should not be able to create issues or releases.
|
||||
|
||||
### REGISTRY_TOKEN Permissions
|
||||
|
||||
Use this token as a repository secret for package publishing from Gitea Actions:
|
||||
|
||||
```text
|
||||
package: Read and Write
|
||||
repository: Read
|
||||
user: Read
|
||||
|
||||
activitypub: No Access
|
||||
admin: No Access
|
||||
issue: No Access
|
||||
misc: No Access
|
||||
notification: No Access
|
||||
organization: No Access
|
||||
```
|
||||
|
||||
These permissions cover generic package uploads while still allowing the workflow to read repository metadata.
|
||||
|
||||
### GITEA_TOKEN Permissions
|
||||
|
||||
Use this token locally on the PC for Codex API actions, or as a repository secret only when workflows need issue, release, or workflow API access:
|
||||
|
||||
```text
|
||||
issue: Read and Write
|
||||
package: Read
|
||||
repository: Read and Write
|
||||
user: Read
|
||||
|
||||
activitypub: No Access
|
||||
admin: No Access
|
||||
misc: No Access
|
||||
notification: No Access
|
||||
organization: No Access
|
||||
```
|
||||
|
||||
These permissions cover creating and reading issues, creating and reading releases, reading repository metadata, and polling workflow runs where the Gitea API allows it. `package: Read` is enough for API checks; use `package: Read and Write` only if this same token must publish packages.
|
||||
|
||||
Use a dedicated bot or automation user when possible.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Setting Local Tokens
|
||||
|
||||
Set a local token for Codex or shell-based API work.
|
||||
|
||||
Current PowerShell session:
|
||||
|
||||
```powershell
|
||||
$env:GITEA_TOKEN = "paste-token-here"
|
||||
```
|
||||
|
||||
Persist for the current Windows user:
|
||||
|
||||
```powershell
|
||||
setx GITEA_TOKEN "paste-token-here"
|
||||
```
|
||||
|
||||
Open a new terminal after `setx`.
|
||||
|
||||
Test repository API access:
|
||||
|
||||
```powershell
|
||||
$headers = @{ Authorization = "token $env:GITEA_TOKEN" }
|
||||
Invoke-RestMethod `
|
||||
-Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
|
||||
-Headers $headers
|
||||
```
|
||||
|
||||
Test issue access:
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod `
|
||||
-Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
|
||||
-Headers $headers
|
||||
```
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Setting Repository Secrets
|
||||
|
||||
In Gitea:
|
||||
|
||||
```text
|
||||
Repository -> Settings -> Actions -> Secrets -> Add Secret
|
||||
```
|
||||
|
||||
Add:
|
||||
|
||||
```text
|
||||
REGISTRY_TOKEN
|
||||
```
|
||||
|
||||
Use a token with package write access. If you want workflows to create releases or issues too, add a separate secret:
|
||||
|
||||
```text
|
||||
GITEA_TOKEN
|
||||
```
|
||||
|
||||
Keep package publishing and release or issue automation separate when possible. It makes permission reviews easier.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Package Publishing
|
||||
|
||||
`files/build-gitea.yml` can publish generic packages when `REGISTRY_TOKEN` is available.
|
||||
|
||||
The workflow:
|
||||
|
||||
- builds project artifacts,
|
||||
- copies them to URL-safe filenames,
|
||||
- uploads immutable versioned packages,
|
||||
- updates a stable `latest` package path.
|
||||
|
||||
The workflow uses:
|
||||
|
||||
```text
|
||||
GITHUB_SERVER_URL
|
||||
GITHUB_REPOSITORY_OWNER
|
||||
GITHUB_REPOSITORY
|
||||
REGISTRY_TOKEN
|
||||
```
|
||||
|
||||
When those values are unavailable, replace `REPOSITORY_OWNER`, `REPOSITORY_NAME`, and related placeholders before use. The default Gitea server is `https://git.wilkensxl.de`.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Agent Follow-up Issues
|
||||
|
||||
Agents should create focused tracker issues for real follow-up work that is outside the current scope or can be handled independently by humans or other agents.
|
||||
|
||||
An issue should include:
|
||||
|
||||
- observed problem,
|
||||
- impact,
|
||||
- affected files or commands,
|
||||
- suggested next steps,
|
||||
- verification already performed.
|
||||
|
||||
Agents must not create issues for vague reminders, duplicate work, or tasks they can safely finish immediately. Sensitive details belong in private channels or `docs/agent-handoff.md`, not public issues.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Release Checklist For A New Repo
|
||||
|
||||
Before the first release of a target project:
|
||||
|
||||
1. Ensure `AGENTS.md` and `.codex/project.md` match the real project.
|
||||
2. Replace all placeholders or mark genuinely unknown values as `PENDING`.
|
||||
3. Configure `REGISTRY_TOKEN` if packages are published.
|
||||
4. Configure `GITEA_TOKEN` only if workflows need issue or release API access.
|
||||
5. Verify SSH push access.
|
||||
6. Run lint, test, build, and audit commands that exist.
|
||||
7. Run `git diff --check`.
|
||||
8. Confirm release artifacts do not include Codex kit metadata unless explicitly wanted.
|
||||
9. Push and poll workflows to success or document the blocker.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Updating The Kit In A Project
|
||||
|
||||
When this kit changes, update target repositories conservatively:
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git pull --ff-only
|
||||
```
|
||||
|
||||
Then ask Codex:
|
||||
|
||||
```text
|
||||
Update this repository's Codex Agent Repository Kit files from the latest kit.
|
||||
Preserve project-specific README content, commands, release rules, and workflow customizations.
|
||||
Do not overwrite unrelated changes.
|
||||
```
|
||||
Reference in New Issue
Block a user