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

Add dependency release and compliance automations

Browse Source
This commit is contained in:
MrSphay
2026-05-03 22:17:27 +02:00
parent 0366a285c5
commit 4de3fb693c
10 changed files with 554 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
README.md
View File

@@ -37,7 +37,12 @@ Give every repository the same predictable anchor points:
| `-- project.md
|-- .gitea/
| `-- workflows/
| `-- build.yml
| |-- security-scan.yml
| |-- repo-cleanup.yml
| |-- dependency-check.yml
| |-- release-dry-run.yml
| |-- build.yml
| `-- template-compliance.yml
|-- docs/
| |-- release-checklist.md
| `-- security-review.md
@@ -49,7 +54,7 @@ Give every repository the same predictable anchor points:
`-- .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.
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, useful scheduled checks, and README blueprint workflow.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
@@ -62,6 +67,9 @@ Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `R
| `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/release-checklist.md` | `docs/release-checklist.md` |
| `files/security-review.md` | `docs/security-review.md` |
| `files/blueprint.md` | `blueprint.md` |
@@ -127,6 +135,7 @@ When applying this kit, an agent should:
- update security and release docs when release behavior changes,
- add or preserve scheduled security automation for releasable projects,
- add or preserve scheduled repository cleanup checks for active projects,
- add dependency, release dry-run, and template compliance checks when they fit the project,
- update `docs/agent-handoff.md` when work is interrupted, risky, or multi-session,
- run `git diff --check` before finishing,
- run the cheapest reliable verification command,
@@ -164,6 +173,36 @@ The workflow is intentionally non-destructive. It must not delete files, branche
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Dependency Automation
`files/dependency-check-gitea.yml` provides a weekly dependency health report.
It detects common stacks and reports:
- security audit results,
- outdated Node, Python, Rust, and Go dependencies,
- Docker base image references that should be reviewed manually.
The workflow does not update lockfiles, create pull requests, or publish packages. Agents should use the report as a starting point for focused dependency update branches.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Release Dry Run
`files/release-dry-run-gitea.yml` checks whether a project looks ready to release without creating a release.
It checks release documents, unresolved placeholders, stack-specific build/test commands where they can be detected, and likely artifact directories. It must not create tags, releases, packages, or uploaded artifacts.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Template Compliance
`files/template-compliance-gitea.yml` checks whether a repository still follows the Codex kit baseline.
It verifies required agent context files, unresolved placeholders, README divider usage for generated READMEs, and recommended workflow presence. Treat failures as maintenance guidance, not as a reason to overwrite project-specific documentation blindly.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Gitea API Token
When working with private repositories on `git.wilkensxl.de`, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine.

16
agent-quickstart.md
View File

@@ -11,6 +11,7 @@ Use new-repository.md or existing-project.md as the task workflow.
Use matching profiles/*.md guidance after detecting the stack.
For releasable projects, add or preserve scheduled security automation.
For active projects, add or preserve non-destructive scheduled repository cleanup checks.
For Codex-maintained projects, add or preserve dependency, release dry-run, and template compliance checks when useful.
Check git status before editing.
Preserve unrelated user changes.
Replace all applicable placeholders and remove non-applicable placeholder sections.
@@ -84,6 +85,18 @@ Is this an active repository with generated files, artifacts, or branches?
yes -> add .gitea/workflows/repo-cleanup.yml or preserve equivalent cleanup checks
no -> cleanup automation can be skipped
Is this an active project with dependencies?
yes -> add .gitea/workflows/dependency-check.yml or preserve equivalent dependency checks
no -> dependency automation can be skipped
Is this project releasable?
yes -> add .gitea/workflows/release-dry-run.yml or preserve equivalent release dry-run checks
no -> release dry-run can be skipped
Is this project intended to stay Codex-maintained?
yes -> add .gitea/workflows/template-compliance.yml or preserve equivalent template checks
no -> template compliance can be skipped
Are commands unknown?
yes -> document PENDING in .codex/project.md
no -> wire commands into AGENTS.md and CI
@@ -135,6 +148,9 @@ docs/agent-handoff.md
.gitea/workflows/build.yml
.gitea/workflows/security-scan.yml
.gitea/workflows/repo-cleanup.yml
.gitea/workflows/dependency-check.yml
.gitea/workflows/release-dry-run.yml
.gitea/workflows/template-compliance.yml
```
For README-generator projects:

6
existing-project.md
View File

@@ -124,6 +124,12 @@ For releasable projects, add `.gitea/workflows/security-scan.yml` unless the rep
For active repositories, add `.gitea/workflows/repo-cleanup.yml` unless equivalent cleanup checks already exist. Keep cleanup automation non-destructive and document intentional exceptions.
For projects with dependencies, add `.gitea/workflows/dependency-check.yml` unless equivalent dependency update or dependency audit checks already exist. Keep it report-only.
For releasable projects, add `.gitea/workflows/release-dry-run.yml` unless equivalent release readiness checks already exist. It must not tag, publish, or create releases.
For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml` unless equivalent agent-context checks already exist. Preserve documented project-specific exceptions.
### 6. Security Review
Fill `docs/security-review.md` with known facts.

3
files/AGENTS.md
View File

@@ -22,7 +22,9 @@ PROJECT_NAME: PROJECT_DESCRIPTION
- If README blueprint files are changed, regenerate or update `README.md` in the same change and verify the generated output renders reasonably.
- For releasable projects, add or preserve `.gitea/workflows/security-scan.yml` using `files/security-scan-gitea.yml` unless the repository already has equivalent scheduled security automation.
- For active projects, add or preserve `.gitea/workflows/repo-cleanup.yml` using `files/repo-cleanup-gitea.yml` unless the repository already has equivalent cleanup checks.
- Add or preserve `.gitea/workflows/dependency-check.yml`, `.gitea/workflows/release-dry-run.yml`, and `.gitea/workflows/template-compliance.yml` when the repository is active, releasable, or intended as a Codex-maintained project.
- Repository cleanup automation must be non-destructive. Do not delete branches, packages, releases, or tracked files without explicit user approval.
- Dependency, compliance, and release dry-run automation must report findings only. Do not auto-update dependencies, auto-open PRs, create tags, publish packages, or create releases without explicit user approval.
## Commands
@@ -59,6 +61,7 @@ ARTIFACT_NAME
- Fill `docs/security-review.md` with actual checked commands and results when performing release-readiness work.
- Review scheduled security workflow failures before changing code. Treat matches as leads: they may be true positives, documentation examples, or test fixtures.
- Review repository cleanup workflow failures as maintenance leads. Document intentional exceptions instead of blindly deleting files.
- Review dependency and template compliance workflow failures as maintenance leads. Preserve project-specific conventions when they are documented.
- Treat generated credentials and config files as sensitive.
- Keep external network calls documented.
- Prefer local processing for user data.

114
files/dependency-check-gitea.yml Normal file
View File

@@ -0,0 +1,114 @@
name: Scheduled Dependency Check
on:
schedule:
- cron: "29 3 * * 2"
workflow_dispatch:
jobs:
dependency-check:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Detect project stack
id: detect
shell: bash
run: |
stacks=""
[ -f package.json ] && stacks="${stacks} node"
{ [ -f pyproject.toml ] || [ -f requirements.txt ]; } && stacks="${stacks} python"
[ -f Cargo.toml ] && stacks="${stacks} rust"
[ -f go.mod ] && stacks="${stacks} go"
{ [ -f Dockerfile ] || [ -f compose.yml ] || [ -f docker-compose.yml ]; } && stacks="${stacks} docker"
echo "stacks=${stacks:-generic}" >> "$GITHUB_OUTPUT"
echo "Detected stacks:${stacks:- generic}"
- name: Node dependency report
if: contains(steps.detect.outputs.stacks, 'node')
shell: bash
run: |
if [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then
npm ci
else
npm install --package-lock-only --ignore-scripts
fi
echo "Security audit:"
npm audit --omit=dev --audit-level=high
echo
echo "Outdated dependencies:"
npm outdated || true
- name: Python dependency report
if: contains(steps.detect.outputs.stacks, 'python')
shell: bash
run: |
python -m pip install --upgrade pip pip-audit
echo "Security audit:"
if [ -f requirements.txt ]; then
pip-audit -r requirements.txt
else
pip-audit
fi
echo
echo "Outdated packages:"
python -m pip list --outdated || true
- name: Rust dependency report
if: contains(steps.detect.outputs.stacks, 'rust')
shell: bash
run: |
cargo install cargo-audit cargo-outdated --locked
echo "Security audit:"
cargo audit
echo
echo "Outdated crates:"
cargo outdated || true
- name: Go dependency report
if: contains(steps.detect.outputs.stacks, 'go')
shell: bash
run: |
go install golang.org/x/vuln/cmd/govulncheck@latest
echo "Security audit:"
govulncheck ./...
echo
echo "Available dependency updates:"
go list -u -m all || true
- name: Docker base image report
if: contains(steps.detect.outputs.stacks, 'docker')
shell: bash
run: |
echo "Docker image references:"
grep -RInE --exclude-dir=.git --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=build '^\s*FROM\s+' Dockerfile* . 2>/dev/null || true
echo
echo "Review Docker base images manually for pinned versions, official sources, and current security status."
- name: Dependency guidance
shell: bash
run: |
cat <<'EOF'
Dependency check completed.
This workflow reports vulnerabilities and available updates. It does
not modify dependency files, create pull requests, or publish packages.
Recommended manual follow-up:
- update dependencies in a focused branch,
- run the project test/build commands,
- review lockfile diffs carefully,
- document intentionally held versions.
EOF

133
files/release-dry-run-gitea.yml Normal file
View File

@@ -0,0 +1,133 @@
name: Release Dry Run
on:
push:
branches:
- main
- master
workflow_dispatch:
jobs:
release-dry-run:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Inspect release metadata
shell: bash
run: |
missing=0
required_docs=(
"README.md"
"CHANGELOG.md"
"SECURITY.md"
"docs/release-checklist.md"
)
for file in "${required_docs[@]}"; do
if [ ! -f "$file" ]; then
echo "Missing release document: $file"
missing=1
fi
done
placeholder_paths=(README.md AGENTS.md .codex docs)
placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND'
for path in "${placeholder_paths[@]}"; do
[ -e "$path" ] || continue
if grep -RInE --exclude-dir=.git "$placeholder_pattern" "$path"; then
echo "Unresolved template placeholders found."
missing=1
fi
done
if [ "$missing" -eq 1 ]; then
exit 1
fi
- name: Detect project stack
id: detect
shell: bash
run: |
stacks=""
[ -f package.json ] && stacks="${stacks} node"
{ [ -f pyproject.toml ] || [ -f requirements.txt ]; } && stacks="${stacks} python"
[ -f Cargo.toml ] && stacks="${stacks} rust"
[ -f go.mod ] && stacks="${stacks} go"
echo "stacks=${stacks:-generic}" >> "$GITHUB_OUTPUT"
echo "Detected stacks:${stacks:- generic}"
- name: Node release checks
if: contains(steps.detect.outputs.stacks, 'node')
shell: bash
run: |
if [ -f package-lock.json ] || [ -f npm-shrinkwrap.json ]; then
npm ci
else
npm install
fi
node -e "const p=require('./package.json'); if(!p.name||!p.version){throw new Error('package.json needs name and version')}; console.log(p.name+'@'+p.version)"
npm run lint --if-present
npm test --if-present
npm run build --if-present
npm run release:check --if-present
- name: Python release checks
if: contains(steps.detect.outputs.stacks, 'python')
shell: bash
run: |
python -m pip install --upgrade pip
if [ -f requirements.txt ]; then
python -m pip install -r requirements.txt
fi
if [ -f pyproject.toml ]; then
python -m pip install build
python -m build
else
echo "No pyproject.toml found; skipped Python package build."
fi
- name: Rust release checks
if: contains(steps.detect.outputs.stacks, 'rust')
shell: bash
run: |
cargo test
cargo build --release
- name: Go release checks
if: contains(steps.detect.outputs.stacks, 'go')
shell: bash
run: |
go test ./...
go build ./...
- name: Artifact report
shell: bash
run: |
echo "Potential release artifacts:"
find . \
-path ./.git -prune -o \
-path ./node_modules -prune -o \
-path './dist/*' -type f -print -o \
-path './build/*' -type f -print -o \
-path './release/*' -type f -print -o \
-path './target/release/*' -type f -print \
| sed 's#^\./##' \
| head -200
cat <<'EOF'
Release dry run completed.
This workflow verifies release readiness. It does not create tags,
releases, packages, or upload artifacts.
EOF

109
files/template-compliance-gitea.yml Normal file
View File

@@ -0,0 +1,109 @@
name: Codex Template Compliance
on:
push:
branches:
- main
- master
pull_request:
workflow_dispatch:
jobs:
template-compliance:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Check required Codex files
shell: bash
run: |
missing=0
required_files=(
"AGENTS.md"
".codex/project.md"
"README.md"
)
recommended_files=(
"SECURITY.md"
"CHANGELOG.md"
"docs/agent-handoff.md"
)
for file in "${required_files[@]}"; do
if [ ! -f "$file" ]; then
echo "Missing required Codex file: $file"
missing=1
fi
done
for file in "${recommended_files[@]}"; do
if [ ! -f "$file" ]; then
echo "Recommended Codex file not found: $file"
fi
done
if [ "$missing" -eq 1 ]; then
exit 1
fi
- name: Check unresolved placeholders
shell: bash
run: |
found=0
paths=(AGENTS.md README.md SECURITY.md CHANGELOG.md .codex docs blueprint.md blueprint.json)
pattern='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'
for path in "${paths[@]}"; do
[ -e "$path" ] || continue
if grep -RInE --exclude-dir=.git "$pattern" "$path"; then
found=1
fi
done
if [ "$found" -eq 1 ]; then
echo "Unresolved template placeholders found. Replace real values or mark genuinely unknown values as PENDING."
exit 1
fi
- name: Check README divider convention
shell: bash
run: |
if [ -f blueprint.md ] || [ -f blueprint.json ]; then
if ! grep -q 'template:section-line' blueprint.md 2>/dev/null; then
echo "README blueprint exists but does not use {{ template:section-line }}."
exit 1
fi
fi
- name: Check workflow baseline
shell: bash
run: |
echo "Detected Gitea workflows:"
find .gitea/workflows -maxdepth 1 -type f -name '*.yml' -print 2>/dev/null || true
if [ ! -f ".gitea/workflows/security-scan.yml" ]; then
echo "Recommended workflow missing: .gitea/workflows/security-scan.yml"
fi
if [ ! -f ".gitea/workflows/repo-cleanup.yml" ]; then
echo "Recommended workflow missing: .gitea/workflows/repo-cleanup.yml"
fi
- name: Compliance guidance
shell: bash
run: |
cat <<'EOF'
Codex template compliance check completed.
This workflow verifies agent context and template hygiene. It does
not change files automatically.
Recommended manual follow-up:
- add missing required Codex context files,
- replace unresolved placeholders,
- keep README blueprint and README output aligned,
- document intentional exceptions in .codex/project.md.
EOF

51
manifest.json
View File

@@ -13,6 +13,7 @@
"Update docs/security-review.md during release-readiness work.",
"Update docs/release-checklist.md when release behavior changes.",
"Add or preserve non-destructive scheduled repository cleanup checks for active projects.",
"Add or preserve dependency, release dry-run, and template compliance checks when they fit the project.",
"Run git diff --check before finishing.",
"Run the cheapest reliable verification command or document why it could not run.",
"After pushing workflow-triggering commits, poll Gitea workflow runs until success or a concrete blocker."
@@ -40,6 +41,41 @@
],
"destructive": false
},
"dependencyAutomation": {
"workflow": "files/dependency-check-gitea.yml",
"target": ".gitea/workflows/dependency-check.yml",
"schedule": "weekly",
"checks": [
"dependency vulnerability reports",
"outdated dependency reports",
"Docker base image references"
],
"destructive": false
},
"releaseDryRunAutomation": {
"workflow": "files/release-dry-run-gitea.yml",
"target": ".gitea/workflows/release-dry-run.yml",
"trigger": "push and manual",
"checks": [
"release documentation presence",
"unresolved placeholder scan",
"stack-specific build/test checks",
"artifact discovery"
],
"publishes": false
},
"templateComplianceAutomation": {
"workflow": "files/template-compliance-gitea.yml",
"target": ".gitea/workflows/template-compliance.yml",
"trigger": "push, pull request, and manual",
"checks": [
"required Codex files",
"unresolved placeholders",
"README divider convention",
"recommended workflow presence"
],
"destructive": false
},
"readmeDivider": {
"templateName": "section-line",
"source": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png",
@@ -126,6 +162,21 @@
"source": "files/repo-cleanup-gitea.yml",
"target": ".gitea/workflows/repo-cleanup.yml",
"required": false
},
{
"source": "files/dependency-check-gitea.yml",
"target": ".gitea/workflows/dependency-check.yml",
"required": false
},
{
"source": "files/release-dry-run-gitea.yml",
"target": ".gitea/workflows/release-dry-run.yml",
"required": false
},
{
"source": "files/template-compliance-gitea.yml",
"target": ".gitea/workflows/template-compliance.yml",
"required": false
}
],
"placeholders": [

72
manifest.schema.json
View File

@@ -79,6 +79,78 @@
}
}
},
"dependencyAutomation": {
"type": "object",
"required": ["workflow", "target", "schedule", "checks", "destructive"],
"properties": {
"workflow": {
"type": "string"
},
"target": {
"type": "string"
},
"schedule": {
"type": "string"
},
"checks": {
"type": "array",
"items": {
"type": "string"
}
},
"destructive": {
"type": "boolean"
}
}
},
"releaseDryRunAutomation": {
"type": "object",
"required": ["workflow", "target", "trigger", "checks", "publishes"],
"properties": {
"workflow": {
"type": "string"
},
"target": {
"type": "string"
},
"trigger": {
"type": "string"
},
"checks": {
"type": "array",
"items": {
"type": "string"
}
},
"publishes": {
"type": "boolean"
}
}
},
"templateComplianceAutomation": {
"type": "object",
"required": ["workflow", "target", "trigger", "checks", "destructive"],
"properties": {
"workflow": {
"type": "string"
},
"target": {
"type": "string"
},
"trigger": {
"type": "string"
},
"checks": {
"type": "array",
"items": {
"type": "string"
}
},
"destructive": {
"type": "boolean"
}
}
},
"workflows": {
"type": "object",
"required": ["newRepository", "existingProject", "quickstart"],

9
new-repository.md
View File

@@ -52,6 +52,9 @@ files/blueprint.json -> blueprint.json
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
```
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.
@@ -162,6 +165,12 @@ For releasable projects, config tools, apps, or repositories that process user d
For active repositories, also add `.gitea/workflows/repo-cleanup.yml`. It should report cleanup candidates only; it must not delete files, branches, packages, or releases automatically.
For projects with dependencies, add `.gitea/workflows/dependency-check.yml`. It should report dependency health only; it must not edit dependency manifests or lockfiles automatically.
For releasable projects, add `.gitea/workflows/release-dry-run.yml`. It should verify release readiness only; it must not create tags, releases, packages, or artifacts automatically.
For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml`. It should verify agent context and template hygiene without overwriting project-specific conventions.
### 7. Finish
Before final response: