commit ae40f41c316daa0718319ab8fe76d5905476981d Author: MrSphay Date: Sat May 2 02:33:57 2026 +0200 first commit diff --git a/README.md b/README.md new file mode 100644 index 0000000..431e956 --- /dev/null +++ b/README.md @@ -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. +``` diff --git a/agent-quickstart.md b/agent-quickstart.md new file mode 100644 index 0000000..2d9b244 --- /dev/null +++ b/agent-quickstart.md @@ -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 +``` + diff --git a/existing-project.md b/existing-project.md new file mode 100644 index 0000000..069343d --- /dev/null +++ b/existing-project.md @@ -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. + diff --git a/files/AGENTS.md b/files/AGENTS.md new file mode 100644 index 0000000..3df61ab --- /dev/null +++ b/files/AGENTS.md @@ -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. + diff --git a/files/CHANGELOG.md b/files/CHANGELOG.md new file mode 100644 index 0000000..2e3b08b --- /dev/null +++ b/files/CHANGELOG.md @@ -0,0 +1,8 @@ +# Changelog + +All notable changes to this project are documented here. + +## Unreleased + +- Initial project setup. + diff --git a/files/SECURITY.md b/files/SECURITY.md new file mode 100644 index 0000000..b01b725 --- /dev/null +++ b/files/SECURITY.md @@ -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. + diff --git a/files/blueprint.json b/files/blueprint.json new file mode 100644 index 0000000..9aedc00 --- /dev/null +++ b/files/blueprint.json @@ -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": "

\"-----------------------------------------------------\"

" + } + ], + "text": "PROJECT_DESCRIPTION" +} + diff --git a/files/blueprint.md b/files/blueprint.md new file mode 100644 index 0000000..3653ad4 --- /dev/null +++ b/files/blueprint.md @@ -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` | diff --git a/files/build-gitea.yml b/files/build-gitea.yml new file mode 100644 index 0000000..dbde48a --- /dev/null +++ b/files/build-gitea.yml @@ -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 diff --git a/files/project.md b/files/project.md new file mode 100644 index 0000000..763efe8 --- /dev/null +++ b/files/project.md @@ -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. diff --git a/files/release-checklist.md b/files/release-checklist.md new file mode 100644 index 0000000..bf3fa73 --- /dev/null +++ b/files/release-checklist.md @@ -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. + diff --git a/files/security-review.md b/files/security-review.md new file mode 100644 index 0000000..18abd1e --- /dev/null +++ b/files/security-review.md @@ -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. +``` diff --git a/manifest.json b/manifest.json new file mode 100644 index 0000000..6c09979 --- /dev/null +++ b/manifest.json @@ -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" + ] +} + diff --git a/new-repository.md b/new-repository.md new file mode 100644 index 0000000..6ede5e1 --- /dev/null +++ b/new-repository.md @@ -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. +