MrSphay/Explosion-Overhaul
1
0
Fork 0
generated from MrSphay/codex-agent-repository-kit
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
MrSphay
2026-05-04 09:03:49 +00:00
commit 592db184a2
29 changed files with 2739 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

261
README.md Normal file
View File

@@ -0,0 +1,261 @@
# 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.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## README Section Divider
Generated README files should use the shared rainbow section divider between major sections.
The divider is configured in `files/blueprint.json` as the `section-line` template:
```md
{{ template:section-line }}
```
When a project uses the README blueprint workflow, keep this divider in `blueprint.md` between major sections. Do not replace it with plain `---` unless the target platform cannot render inline images.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Agent Goal
Give every repository the same predictable anchor points:
```text
.
|-- AGENTS.md
|-- .codex/
| `-- project.md
|-- .gitea/
| `-- workflows/
| |-- 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
|-- 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, 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>
## Copy Map
| Template | Destination |
| --- | --- |
| `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/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` |
| `files/CONTRIBUTING.md` | `CONTRIBUTING.md` |
| `files/gitignore.template` | `.gitignore` |
| `files/agent-handoff.md` | `docs/agent-handoff.md` |
| `files/release-notes.md` | `docs/release-notes.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.
Agents should read `manifest.json` before copying files. It is the source of truth for target paths, required files, optional files, and placeholder names.
`manifest.schema.json` documents the manifest shape. Stack-specific profile notes live in `profiles/`.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## 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.
Agents must not leave unresolved placeholders in copied files unless the value is genuinely unknown and marked as `PENDING`.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Agent Responsibilities
When applying this kit, an agent should:
- read `manifest.json` first,
- choose `new-repository.md` or `existing-project.md`,
- read matching `profiles/*.md` guidance after detecting the stack,
- check `git status --short` before editing,
- preserve unrelated user changes,
- use the manifest copy map for target paths,
- replace applicable placeholders,
- remove non-applicable placeholder sections,
- keep `AGENTS.md` and `.codex/project.md` aligned,
- update `README.md` whenever README blueprint files change,
- 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,
- poll pushed Gitea workflow runs until success or a concrete blocker.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Scheduled Security Automation
`files/security-scan-gitea.yml` provides an optional weekly Gitea workflow for releasable projects.
It checks:
- stack-specific dependency vulnerabilities,
- suspicious code patterns,
- committed secrets or local config files,
- AI instruction-injection indicators.
The workflow is intentionally conservative. If it fails, an agent should inspect the matches and decide whether they are real risks, documentation examples, or test fixtures. Do not silence the workflow without documenting why.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Scheduled Repository Cleanup
`files/repo-cleanup-gitea.yml` provides an optional weekly Gitea workflow for active repositories.
It reports:
- generated files or dependency folders that were accidentally tracked,
- large tracked files that may belong in release artifacts or package storage,
- secret-prone local config files,
- stale remote branch candidates.
The workflow is intentionally non-destructive. It must not delete files, branches, packages, or releases. Agents should treat failures as maintenance reports, document intentional exceptions, and only remove repository data after explicit user approval.
<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.
Use `GITEA_TOKEN` only for read-oriented Gitea API checks unless the user explicitly asks for a write action. Typical safe checks include repository metadata, workflow run status, and package-read visibility. Never print the token, commit it, or copy it into workflow files.
Example status endpoint:
```text
GET https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
Authorization: token GITEA_TOKEN
```
`REGISTRY_TOKEN` is still the intended secret name for CI package publishing inside `.gitea/workflows/build.yml`.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Gitea Workflow Loop
After pushing commits that trigger a Gitea workflow, Codex agents must keep checking the resulting workflow run before finishing. Poll the run until it reaches a terminal state. If it succeeds, report the successful run. If it fails or is cancelled, inspect the failing job/logs, fix the issue when it is in scope, commit, push, and repeat the check loop for the next run. A fixed failure is not a stopping point; the loop continues after the follow-up push until a workflow succeeds or a concrete out-of-scope blocker is reached. Do not stop after a single in-progress status when the user asked the agent to continue the loop.
## Gitea Artifacts And Packages
Actions artifacts and Gitea packages are separate storage paths.
- `actions/upload-artifact` makes a workflow-run artifact. It does not create an entry in the Gitea Package Registry.
- Use `actions/upload-artifact@v3` for Gitea/Act compatibility unless the target runner is known to support newer artifact actions.
- To publish a downloadable package, upload it separately to the generic package registry with `curl --upload-file` and a CI secret such as `REGISTRY_TOKEN`.
- Do not place raw build artifact names directly into package URLs. Build tools often emit names with spaces, parentheses, or platform-specific punctuation. Copy artifacts to temporary package files with URL-safe names before uploading.
- For user-facing downloads, publish both an immutable version such as `PROJECT_VERSION-SHORT_SHA` and a stable `latest` package when the repository owner wants a moving download link.
- After publishing, verify the actual package URL with an authenticated `HEAD` or lightweight download check. A green build does not always prove the package is visible where users expect it.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## 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.
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## 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.
```

181
agent-quickstart.md Normal file
View File

@@ -0,0 +1,181 @@
# Agent Quickstart
Use this file when you want Codex to apply the repository kit with minimal instructions.
## Required Agent Behavior
```text
Read manifest.json first.
Use its copyMap for file destinations.
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.
Keep AGENTS.md and .codex/project.md aligned with real commands and artifact paths.
Update README.md whenever blueprint.md or blueprint.json changes.
Run git diff --check before finishing.
Run the cheapest reliable verification command, or explain why it could not run.
```
## 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.
Use manifest.json as the source of truth for copy targets.
Keep the README generator only if it adds value.
When using the README generator, keep the rainbow `{{ template:section-line }}` divider between major sections.
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.
Use manifest.json as the source of truth for copy targets.
When using or adding the README generator, keep the rainbow `{{ template:section-line }}` divider between major sections.
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
Did you read manifest.json?
yes -> use copyMap and placeholders from it
no -> read it before editing
Does a stack profile match?
yes -> read the matching profiles/*.md file and adapt commands carefully
no -> continue with universal rules only
Does the project already have README structure?
yes -> preserve it; only add blueprint files if useful
no -> add blueprint.md and blueprint.json with the rainbow section-line divider
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
Is the project releasable or does it process user/secrets/config data?
yes -> add .gitea/workflows/security-scan.yml or preserve equivalent scheduled security automation
no -> document why scheduled security automation is not needed
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
Did blueprint.md or blueprint.json change?
yes -> regenerate or manually update README.md and check the rendered structure
no -> leave README.md alone unless content changed
Did release behavior, artifacts, or downloads change?
yes -> update docs/release-checklist.md and README downloads/artifacts
no -> do not invent release details
Does the user expect a Gitea Package Registry package?
yes -> add an explicit generic package upload step; upload-artifact alone is not enough
no -> workflow-run artifacts may be sufficient
Do package upload URLs include raw build filenames?
yes -> copy artifacts to URL-safe filenames first, then upload those names
no -> continue
Is the work interrupted, risky, or multi-session?
yes -> update docs/agent-handoff.md
no -> no handoff file is required
Is this a private Gitea repo with Actions?
yes -> if GITEA_TOKEN is set locally, use it for read-only API checks of repository and workflow-run status
no -> use public web/API checks when available
Did you push a commit that should trigger a workflow?
yes -> poll the workflow run until success; if it fails, inspect logs, fix in scope, push again, and keep looping after the follow-up push
no -> finish with local verification status
```
## 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
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:
```text
blueprint.md
blueprint.json
README.md
```
For stack-specific guidance:
```text
profiles/node.md
profiles/electron.md
profiles/python.md
profiles/docker.md
profiles/static-site.md
```

173
existing-project.md Normal file
View File

@@ -0,0 +1,173 @@
# 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.
If a matching stack profile exists in `profiles/`, read it before changing commands, CI, or ignore rules.
### 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
CONTRIBUTING.md
docs/security-review.md
docs/release-checklist.md
docs/agent-handoff.md
docs/release-notes.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. Keep or add `{{ template:section-line }}` between major README sections.
4. Add a `readme` command.
5. Generate `README.md`.
6. Compare the diff carefully.
The default section divider is the rainbow line from `andreasbm/readme`, configured in `blueprint.json` as `section-line`. Agents should keep it enabled when the project uses generated README files.
### 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.
Treat workflow-run artifacts and Package Registry packages as different outputs. If the project expects user-downloadable packages, confirm there is an explicit package publish step in addition to any `actions/upload-artifact` step. When adding or repairing package publishing, copy build outputs to URL-safe filenames before uploading and verify the final package URL after the workflow succeeds.
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.
For releasable projects, add `.gitea/workflows/security-scan.yml` unless the repository already has equivalent scheduled security automation. If an existing scanner is present, document it in `.codex/project.md` instead of duplicating it.
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.
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,
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
- if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
- list files changed,
- mention any skipped checks,
- do not create a release unless explicitly requested.

80
files/AGENTS.md Normal file
View File

@@ -0,0 +1,80 @@
# Agent Instructions
## Project
PROJECT_NAME: PROJECT_DESCRIPTION
## Repository Rules
- Start by reading `manifest.json`, then the workflow file that matches the task: `new-repository.md` for fresh repos or `existing-project.md` for retrofit work.
- Use the matching `profiles/*.md` file when the repository stack is detected. Profiles are guidance, not permission to ignore existing project conventions.
- Follow the `manifest.json` copy map for source and target paths. Do not invent alternate locations unless the target repository already has an equivalent convention.
- 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.
- Check `git status --short` before editing and before finishing. Preserve unrelated user changes.
- Replace all applicable placeholders. Remove non-applicable placeholder sections instead of leaving fake values.
- If `GITEA_TOKEN` is available locally, use it only for read-only Gitea API checks such as private repository metadata, package-read visibility, and Actions run status. Never print, commit, or store the token.
- After pushing commits that trigger a Gitea workflow, poll the workflow run until it succeeds. If it fails or is cancelled, inspect the failing job/logs, fix the issue when in scope, push again, and repeat the workflow check loop. Fixing and pushing a workflow failure is not a stopping point.
- When the project uses `blueprint.md` and `blueprint.json` for README generation, keep the rainbow `{{ template:section-line }}` divider between major README sections. Do not replace it with plain `---` unless the target renderer cannot display inline images.
- 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.
- Gitea Actions artifacts are not Gitea Package Registry packages. If the user expects a package/download entry, add an explicit registry publish step and verify the package URL after the workflow succeeds.
## 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`.
Keep `.codex/project.md` and this `AGENTS.md` aligned when commands, artifact paths, or release rules change.
## Artifacts
Expected artifact output:
```text
ARTIFACT_OUTPUT_DIRECTORY
```
Expected artifact names:
```text
ARTIFACT_NAME
```
## Security Notes
- Review `docs/security-review.md` before release work.
- 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.
- Keep CI publishing secrets in repository or organization secrets, not in tracked files. `REGISTRY_TOKEN` is the default package publishing secret name for the Gitea workflow template.
- Use URL-safe package filenames when publishing to a registry. Do not put raw artifact names with spaces or punctuation directly into upload URLs.
- Ensure `.gitignore` covers local config, build outputs, logs, temporary files, and secret material for the detected stack.
## Finish Checklist
- `git diff --check` passes.
- The cheapest reliable verification command has been run, or the reason it could not be run is documented.
- README, changelog, security review, and release checklist are updated when the change touches release behavior.
- `docs/agent-handoff.md` is updated when work is interrupted, risky, or spans multiple sessions.
- Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported.

8
files/CHANGELOG.md Normal file
View File

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

48
files/CONTRIBUTING.md Normal file
View File

@@ -0,0 +1,48 @@
# Contributing
## Working Rules
- Keep changes scoped to the issue or user request.
- Prefer existing project patterns.
- Do not commit secrets, generated credentials, local `.env` files, or private keys.
- Do not create releases unless explicitly requested.
- Preserve unrelated user changes.
## Before Committing
Run the cheapest reliable verification commands for this project:
```bash
LINT_COMMAND
TEST_COMMAND
BUILD_COMMAND
```
Also run:
```bash
git diff --check
```
If a command cannot run, document why in the final response or handoff notes.
## Pull Requests
Pull requests should include:
- summary of changes,
- verification performed,
- known risks or skipped checks,
- artifact/download notes when relevant.
## Releases
Before release work, update:
```text
CHANGELOG.md
docs/release-checklist.md
docs/security-review.md
README.md
```

22
files/SECURITY.md Normal file
View File

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

35
files/agent-handoff.md Normal file
View File

@@ -0,0 +1,35 @@
# Agent Handoff
Use this file when a task spans multiple sessions, has unresolved follow-up work, or changes release behavior.
## Current State
```text
PENDING
```
## Changes Made
- PENDING
## Verification
| Check | Result |
| --- | --- |
| `git diff --check` | PENDING |
| `LINT_COMMAND` | PENDING |
| `TEST_COMMAND` | PENDING |
| `BUILD_COMMAND` | PENDING |
## Open Questions
- PENDING
## Next Steps
- PENDING
## Risks
- PENDING

30
files/blueprint.json Normal file
View File

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

76
files/blueprint.md Normal file
View File

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

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

@@ -0,0 +1,105 @@
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}"
package_name="PACKAGE_NAME"
package_dir="package-registry"
latest_url="https://git.wilkensxl.de/api/packages/REPOSITORY_OWNER/generic/PACKAGE_NAME/latest"
mapfile -d '' artifacts < <(find ARTIFACT_OUTPUT_DIRECTORY -maxdepth 1 -type f -print0)
if [ "${#artifacts[@]}" -eq 0 ]; then
echo "No package artifacts found in ARTIFACT_OUTPUT_DIRECTORY"
exit 1
fi
rm -rf "${package_dir}"
mkdir -p "${package_dir}/versioned" "${package_dir}/latest"
for artifact in "${artifacts[@]}"; do
extension=""
base_name="$(basename "$artifact")"
stem="$base_name"
if [[ "$base_name" == *.* ]]; then
extension=".${base_name##*.}"
stem="${base_name%.*}"
fi
safe_stem="$(echo "$stem" | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-//; s/-$//')"
safe_name="${safe_stem}-${package_version}${extension}"
cp "$artifact" "${package_dir}/versioned/${safe_name}"
curl --fail-with-body \
--user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" \
--upload-file "${package_dir}/versioned/${safe_name}" \
"https://git.wilkensxl.de/api/packages/REPOSITORY_OWNER/generic/PACKAGE_NAME/${package_version}/${safe_name}"
done
curl --silent --show-error --user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" --request DELETE "${latest_url}" || true
for artifact in "${artifacts[@]}"; do
extension=""
base_name="$(basename "$artifact")"
stem="$base_name"
if [[ "$base_name" == *.* ]]; then
extension=".${base_name##*.}"
stem="${base_name%.*}"
fi
safe_stem="$(echo "$stem" | tr -cs 'A-Za-z0-9._-' '-' | sed 's/^-//; s/-$//')"
safe_name="${safe_stem}-latest${extension}"
cp "$artifact" "${package_dir}/latest/${safe_name}"
curl --fail-with-body \
--user "REPOSITORY_OWNER:${REGISTRY_TOKEN}" \
--upload-file "${package_dir}/latest/${safe_name}" \
"${latest_url}/${safe_name}"
done

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

46
files/gitignore.template Normal file
View File

@@ -0,0 +1,46 @@
# Dependencies
node_modules/
vendor/
.venv/
venv/
__pycache__/
# Build outputs
dist/
build/
out/
release/
target/
bin/
obj/
# Logs and temporary files
*.log
*.tmp
*.temp
.cache/
.turbo/
.vite/
.pytest_cache/
# Local environment and secrets
.env
.env.*
!.env.example
*.pem
*.key
*.pfx
*.p12
*.crt
*.cer
*.token
secrets/
# OS and editor files
.DS_Store
Thumbs.db
.idea/
.vscode/
*.swp
*.swo

72
files/project.md Normal file
View File

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

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

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

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

31
files/release-notes.md Normal file
View File

@@ -0,0 +1,31 @@
# PROJECT_NAME PROJECT_VERSION
## Downloads
| Variant | Download |
| --- | --- |
| Latest artifact | DOWNLOAD_URL |
## Highlights
- PENDING
## Security
- Dependency audit: PENDING
- Secret handling: PENDING
- External network calls: PENDING
## Verification
| Check | Result |
| --- | --- |
| `LINT_COMMAND` | PENDING |
| `TEST_COMMAND` | PENDING |
| `BUILD_COMMAND` | PENDING |
| Artifact download | PENDING |
## Notes
PENDING

139
files/repo-cleanup-gitea.yml Normal file
View File

@@ -0,0 +1,139 @@
name: Scheduled Repository Cleanup Check
on:
schedule:
- cron: "43 3 * * 1"
workflow_dispatch:
jobs:
cleanup-check:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Check ignored and untracked generated files
shell: bash
run: |
echo "Ignored files that would be skipped by git:"
git status --ignored --short || true
echo
echo "Tracked generated files check:"
generated_patterns=(
'(^|/)node_modules/'
'(^|/)dist/'
'(^|/)build/'
'(^|/)out/'
'(^|/)release/'
'(^|/)target/'
'(^|/)coverage/'
'\.log$'
'\.tmp$'
'\.temp$'
)
found=0
tracked_files="$(git ls-files)"
for pattern in "${generated_patterns[@]}"; do
if echo "$tracked_files" | grep -Ei "$pattern"; then
found=1
fi
done
if [ "$found" -eq 1 ]; then
echo "Generated files appear to be tracked. Review .gitignore and remove generated outputs from version control if appropriate."
exit 1
fi
- name: Check large tracked files
shell: bash
run: |
limit_bytes="${LARGE_FILE_LIMIT_BYTES:-5242880}"
found=0
while IFS= read -r file; do
[ -f "$file" ] || continue
size="$(wc -c < "$file")"
if [ "$size" -gt "$limit_bytes" ]; then
echo "${file} is ${size} bytes, above limit ${limit_bytes}."
found=1
fi
done < <(git ls-files)
if [ "$found" -eq 1 ]; then
echo "Large tracked files found. Move release artifacts to packages/releases or document why they belong in git."
exit 1
fi
- name: Check local config and secret-prone files
shell: bash
run: |
found=0
risky_patterns=(
'^\.env$'
'^\.env\.'
'\.pfx$'
'\.p12$'
'\.pem$'
'\.key$'
'\.token$'
'(^|/)secrets/'
)
tracked_files="$(git ls-files)"
for pattern in "${risky_patterns[@]}"; do
if echo "$tracked_files" | grep -Ei "$pattern" | grep -vE '^\.env\.example$'; then
found=1
fi
done
if [ "$found" -eq 1 ]; then
echo "Secret-prone local config files are tracked. Review immediately."
exit 1
fi
- name: Check stale branches
shell: bash
run: |
git fetch --all --prune
protected='^(main|master|develop|dev|release|staging|production)$'
cutoff="$(date -u -d '90 days ago' +%s)"
found=0
while IFS='|' read -r branch timestamp; do
branch="${branch#origin/}"
[ "$branch" = "HEAD" ] && continue
echo "$branch" | grep -Eq "$protected" && continue
if [ "$timestamp" -lt "$cutoff" ]; then
echo "Stale remote branch candidate: ${branch}"
found=1
fi
done < <(git for-each-ref refs/remotes/origin --format='%(refname:short)|%(committerdate:unix)')
if [ "$found" -eq 1 ]; then
echo "Stale branch candidates found. Review manually before deleting anything."
exit 1
fi
- name: Cleanup guidance
shell: bash
run: |
cat <<'EOF'
Repository cleanup check completed.
This workflow reports cleanup candidates. It does not delete branches,
packages, releases, or files automatically.
Recommended manual follow-up:
- remove generated files from git,
- update .gitignore,
- move large artifacts to releases or package registry,
- review stale branches,
- document intentional exceptions.
EOF

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

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

174
files/security-scan-gitea.yml Normal file
View File

@@ -0,0 +1,174 @@
name: Scheduled Security Scan
on:
schedule:
- cron: "17 3 * * 1"
workflow_dispatch:
jobs:
security-scan:
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 production dependency audit
if: contains(steps.detect.outputs.stacks, 'node')
run: npm audit --omit=dev --audit-level=high
- name: Python dependency audit
if: contains(steps.detect.outputs.stacks, 'python')
shell: bash
run: |
python -m pip install --upgrade pip pip-audit
if [ -f requirements.txt ]; then
pip-audit -r requirements.txt
else
pip-audit
fi
- name: Rust dependency audit
if: contains(steps.detect.outputs.stacks, 'rust')
shell: bash
run: |
cargo install cargo-audit --locked
cargo audit
- name: Go vulnerability scan
if: contains(steps.detect.outputs.stacks, 'go')
shell: bash
run: |
go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...
- name: Suspicious code pattern scan
shell: bash
run: |
grep_excludes=(
--exclude-dir=.git
--exclude-dir=node_modules
--exclude-dir=dist
--exclude-dir=build
--exclude-dir=release
--exclude=security-scan.yml
)
patterns=(
'eval\s*\('
'new Function\s*\('
'dangerouslySetInnerHTML'
'innerHTML\s*='
'child_process'
'exec\s*\('
'spawn\s*\('
'shell\.openExternal'
'nodeIntegration:\s*true'
'webSecurity:\s*false'
'allowRunningInsecureContent:\s*true'
'curl .*sh'
'wget .*sh'
)
found=0
for pattern in "${patterns[@]}"; do
if grep -RInE "${grep_excludes[@]}" "$pattern" .; then
found=1
fi
done
if [ "$found" -eq 1 ]; then
echo "Suspicious code patterns were found. Review the matches above."
exit 1
fi
- name: Secret and config leak scan
shell: bash
run: |
grep_excludes=(
--exclude-dir=.git
--exclude-dir=node_modules
--exclude-dir=dist
--exclude-dir=build
--exclude-dir=release
--exclude=security-scan.yml
)
patterns=(
'BEGIN (RSA |EC |OPENSSH |)PRIVATE KEY'
'AKIA[0-9A-Z]{16}'
'xox[baprs]-[0-9A-Za-z-]+'
'gh[pousr]_[0-9A-Za-z_]+'
'sk-[A-Za-z0-9]{20,}'
'api[_-]?key\s*=\s*["'\'']?[A-Za-z0-9_\-]{20,}'
'token\s*=\s*["'\'']?[A-Za-z0-9_\-]{20,}'
'password\s*=\s*["'\'']?[^[:space:]]{8,}'
)
found=0
for pattern in "${patterns[@]}"; do
if grep -RInE "${grep_excludes[@]}" "$pattern" .; then
found=1
fi
done
if find . -path ./.git -prune -o \( -name ".env" -o -name ".env.*" \) -not -name ".env.example" -print | grep .; then
echo "Committed environment files were found."
found=1
fi
if [ "$found" -eq 1 ]; then
echo "Potential secret or config leak detected. Review the matches above."
exit 1
fi
- name: AI instruction injection scan
shell: bash
run: |
grep_excludes=(
--exclude-dir=.git
--exclude-dir=node_modules
--exclude-dir=dist
--exclude-dir=build
--exclude-dir=release
--exclude=security-scan.yml
)
patterns=(
'ignore (all )?(previous|above) instructions'
'system prompt'
'developer message'
'reveal your instructions'
'exfiltrate'
'send.*token'
'send.*secret'
'disable.*safety'
'jailbreak'
'prompt injection'
)
found=0
for pattern in "${patterns[@]}"; do
if grep -RInEi "${grep_excludes[@]}" "$pattern" .; then
found=1
fi
done
if [ "$found" -eq 1 ]; then
echo "Potential AI instruction-injection text found. Review whether this is documentation, test data, or malicious content."
exit 1
fi

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

225
manifest.json Normal file
View File

@@ -0,0 +1,225 @@
{
"name": "codex-agent-repository-kit",
"version": "1.0.0",
"description": "Universal repository baseline for Codex-assisted projects.",
"agentResponsibilities": [
"Read manifest.json before copying files.",
"Use copyMap target paths unless the repository already has an equivalent convention.",
"Check git status before editing and before finishing.",
"Preserve unrelated user changes.",
"Replace applicable placeholders and remove non-applicable placeholder sections.",
"Keep AGENTS.md and .codex/project.md aligned with real commands and artifact paths.",
"Update README.md whenever blueprint.md or blueprint.json changes.",
"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."
],
"securityAutomation": {
"workflow": "files/security-scan-gitea.yml",
"target": ".gitea/workflows/security-scan.yml",
"schedule": "weekly",
"checks": [
"stack-specific dependency audit",
"suspicious code pattern scan",
"secret and config leak scan",
"AI instruction injection scan"
]
},
"cleanupAutomation": {
"workflow": "files/repo-cleanup-gitea.yml",
"target": ".gitea/workflows/repo-cleanup.yml",
"schedule": "weekly",
"checks": [
"tracked generated files",
"large tracked files",
"secret-prone local config files",
"stale branch candidates"
],
"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",
"usage": "Keep {{ template:section-line }} between major sections in generated README files."
},
"workflows": {
"newRepository": "new-repository.md",
"existingProject": "existing-project.md",
"quickstart": "agent-quickstart.md"
},
"schema": "manifest.schema.json",
"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/CONTRIBUTING.md",
"target": "CONTRIBUTING.md",
"required": false
},
{
"source": "files/gitignore.template",
"target": ".gitignore",
"required": false
},
{
"source": "files/agent-handoff.md",
"target": "docs/agent-handoff.md",
"required": false
},
{
"source": "files/release-notes.md",
"target": "docs/release-notes.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
},
{
"source": "files/security-scan-gitea.yml",
"target": ".gitea/workflows/security-scan.yml",
"required": false
},
{
"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": [
"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"
],
"profiles": [
{
"name": "node",
"path": "profiles/node.md"
},
{
"name": "electron",
"path": "profiles/electron.md"
},
{
"name": "python",
"path": "profiles/python.md"
},
{
"name": "docker",
"path": "profiles/docker.md"
},
{
"name": "static-site",
"path": "profiles/static-site.md"
}
]
}

209
manifest.schema.json Normal file
View File

@@ -0,0 +1,209 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "Codex Agent Repository Kit Manifest",
"type": "object",
"required": ["name", "version", "description", "workflows", "copyMap", "placeholders"],
"properties": {
"name": {
"type": "string"
},
"version": {
"type": "string"
},
"description": {
"type": "string"
},
"agentResponsibilities": {
"type": "array",
"items": {
"type": "string"
}
},
"readmeDivider": {
"type": "object",
"required": ["templateName", "source", "usage"],
"properties": {
"templateName": {
"type": "string"
},
"source": {
"type": "string"
},
"usage": {
"type": "string"
}
}
},
"securityAutomation": {
"type": "object",
"required": ["workflow", "target", "schedule", "checks"],
"properties": {
"workflow": {
"type": "string"
},
"target": {
"type": "string"
},
"schedule": {
"type": "string"
},
"checks": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"cleanupAutomation": {
"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"
}
}
},
"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"],
"properties": {
"newRepository": {
"type": "string"
},
"existingProject": {
"type": "string"
},
"quickstart": {
"type": "string"
}
}
},
"copyMap": {
"type": "array",
"items": {
"type": "object",
"required": ["source", "target", "required"],
"properties": {
"source": {
"type": "string"
},
"target": {
"type": "string"
},
"required": {
"type": "boolean"
}
}
}
},
"placeholders": {
"type": "array",
"items": {
"type": "string"
}
},
"profiles": {
"type": "array",
"items": {
"type": "object",
"required": ["name", "path"],
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
}
}
}
}
}
}

185
new-repository.md Normal file
View File

@@ -0,0 +1,185 @@
# 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.
If a matching stack profile exists in `profiles/`, read it before choosing commands.
### 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/CONTRIBUTING.md -> CONTRIBUTING.md
files/gitignore.template -> .gitignore
files/release-checklist.md -> docs/release-checklist.md
files/security-review.md -> docs/security-review.md
files/agent-handoff.md -> docs/agent-handoff.md
files/release-notes.md -> docs/release-notes.md
files/blueprint.md -> blueprint.md
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.
### 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. Keep `{{ template:section-line }}` between major README sections.
4. Add a `readme` command.
5. Generate `README.md`.
6. Commit `README.md`, `blueprint.md`, and `blueprint.json`.
The default section divider is the rainbow line from `andreasbm/readme`, configured in `blueprint.json` as `section-line`. Agents should keep it enabled for generated README files.
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. `actions/upload-artifact` creates a workflow-run artifact, not a Gitea Package Registry package. If users need a package/download entry, add a separate generic package upload step with `REGISTRY_TOKEN`, copy artifacts to URL-safe filenames before upload, and verify the final package URL after the workflow succeeds.
For releasable projects, config tools, apps, or repositories that process user data, secrets, or deployment files, also add `.gitea/workflows/security-scan.yml`. Keep the scheduled workflow conservative and review false positives before silencing checks.
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:
- run formatting or validation if available,
- run the cheapest reliable verification command,
- check `git diff --check`,
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
- if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
- summarize changed files,
- do not create a release unless explicitly requested.

36
profiles/docker.md Normal file
View File

@@ -0,0 +1,36 @@
# Docker Profile
Use when the repository has `Dockerfile`, `compose.yml`, or deployment container artifacts.
## Checks
Look for:
- secrets copied into images,
- `.env` files committed,
- broad build contexts,
- unpinned base images,
- root-only runtime when avoidable,
- exposed ports documented in README.
## Commands
Common placeholders:
```text
BUILD_COMMAND = docker build -t PROJECT_NAME .
TEST_COMMAND = docker compose config
AUDIT_COMMAND = docker scout cves PROJECT_NAME
```
Use only commands that are available in the target environment.
## Ignore Additions
```text
.env
.env.*
!.env.example
docker-compose.override.yml
```

43
profiles/electron.md Normal file
View File

@@ -0,0 +1,43 @@
# Electron Profile
Use when the repository builds an Electron desktop app.
## Security Expectations
Check for:
```text
contextIsolation: true
nodeIntegration: false
sandbox: true when compatible
webSecurity: true
allowRunningInsecureContent: false
```
Avoid:
```text
eval
shell.openExternal without allowlist
unsafe navigation
unvalidated IPC writes
```
## Release Notes
Document:
- installer artifact,
- portable artifact if available,
- signing status,
- SmartScreen/Defender limitations,
- whether secrets or user files stay local.
## Common Artifacts
```text
release/*.exe
release/*.blockmap
release/*.yml
```

42
profiles/node.md Normal file
View File

@@ -0,0 +1,42 @@
# Node Profile
Use when the repository has `package.json`.
## Detection
Common files:
```text
package.json
package-lock.json
pnpm-lock.yaml
yarn.lock
tsconfig.json
vite.config.*
```
## Commands
Prefer existing scripts. Common defaults:
```text
INSTALL_COMMAND = npm install
LINT_COMMAND = npm run lint
TEST_COMMAND = npm test
BUILD_COMMAND = npm run build
AUDIT_COMMAND = npm audit --omit=dev --audit-level=high
README_COMMAND = npm run readme
```
If scripts are missing, document `PENDING` instead of inventing commands.
## Ignore Additions
```text
node_modules/
dist/
build/
coverage/
*.log
```

36
profiles/python.md Normal file
View File

@@ -0,0 +1,36 @@
# Python Profile
Use when the repository has `pyproject.toml`, `requirements.txt`, or Python source files.
## Commands
Prefer existing tooling. Common examples:
```text
INSTALL_COMMAND = python -m pip install -r requirements.txt
LINT_COMMAND = ruff check .
TEST_COMMAND = pytest
BUILD_COMMAND = python -m build
AUDIT_COMMAND = pip-audit
```
If the project uses `uv`, prefer:
```text
INSTALL_COMMAND = uv sync
TEST_COMMAND = uv run pytest
AUDIT_COMMAND = uv pip audit
```
## Ignore Additions
```text
.venv/
venv/
__pycache__/
.pytest_cache/
dist/
build/
*.egg-info/
```

36
profiles/static-site.md Normal file
View File

@@ -0,0 +1,36 @@
# Static Site Profile
Use when the repository produces static HTML/CSS/JS output.
## Checks
Look for:
- broken asset paths,
- missing responsive viewport,
- inaccessible contrast,
- large unoptimized images,
- external scripts without a clear reason,
- generated output directory.
## Commands
Common examples:
```text
INSTALL_COMMAND = npm install
DEV_COMMAND = npm run dev
LINT_COMMAND = npm run lint
BUILD_COMMAND = npm run build
```
## Artifacts
Common output directories:
```text
dist/
build/
public/
```