first commit
This commit is contained in:
MrSphay
98
README.md
Normal file
98
README.md
Normal 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
86
agent-quickstart.md
Normal 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
151
existing-project.md
Normal 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
48
files/AGENTS.md
Normal 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
8
files/CHANGELOG.md
Normal 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
22
files/SECURITY.md
Normal 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
30
files/blueprint.json
Normal 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
76
files/blueprint.md
Normal 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
78
files/build-gitea.yml
Normal 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
72
files/project.md
Normal 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
36
files/release-checklist.md
Normal 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
54
files/security-review.md
Normal 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
79
manifest.json
Normal 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
159
new-repository.md
Normal 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.
|
||||||
|
|
||||||
Reference in New Issue
Block a user