generated from MrSphay/codex-agent-repository-kit
Initial commit
This commit is contained in:
60
AGENTS.md
Normal file
60
AGENTS.md
Normal file
@@ -0,0 +1,60 @@
|
||||
# Agent Instructions For This Repository
|
||||
|
||||
This file is for Codex agents working on the Codex Agent Repository Kit itself. The public `README.md` is for humans and should stay focused on setup and usage.
|
||||
|
||||
## Start Of Task
|
||||
|
||||
- Check `git status --short`.
|
||||
- If the working tree is clean, run `git pull --ff-only` before editing.
|
||||
- If local changes exist, preserve them and do not overwrite user work.
|
||||
- Conserve context tokens: use `rg`, targeted file reads, and short summaries instead of loading unrelated files or long logs.
|
||||
|
||||
## Repository Purpose
|
||||
|
||||
This repository ships reusable baseline files for other repositories:
|
||||
|
||||
- `files/` contains templates copied into target repositories.
|
||||
- `agent-quickstart.md`, `new-repository.md`, and `existing-project.md` are agent workflows.
|
||||
- `manifest.json` is the source of truth for copy targets and placeholders.
|
||||
- `profiles/` contains stack-specific guidance.
|
||||
|
||||
## Editing Rules
|
||||
|
||||
- Keep repository owner, repository name, project names, and local paths dynamic. This kit intentionally targets `https://git.wilkensxl.de` and SSH port `2222`, so keep that host/port consistent in user-facing setup and Gitea workflow defaults.
|
||||
- If a new placeholder is introduced, update `manifest.json`, the README placeholder list, and placeholder scans in workflow templates.
|
||||
- Keep `README.md` user-facing. Put agent operating rules in this file or the workflow docs.
|
||||
- Keep `files/AGENTS.md` generic; it is copied into target repositories and must not describe this repository specifically.
|
||||
- Do not include secrets, tokens, private data, or sensitive logs in docs, issues, commits, or release notes.
|
||||
|
||||
## Follow-up Work
|
||||
|
||||
- Create focused tracker issues for real follow-up work that is outside the current scope or can be done independently.
|
||||
- Do not create issues for work that can be safely completed in the current task.
|
||||
- If issue creation is unavailable, update `docs/agent-handoff.md` with the blocker and next steps.
|
||||
|
||||
## Verification
|
||||
|
||||
Before committing:
|
||||
|
||||
```powershell
|
||||
Get-Content manifest.json | ConvertFrom-Json | Out-Null
|
||||
Get-Content manifest.schema.json | ConvertFrom-Json | Out-Null
|
||||
Get-Content files\blueprint.json | ConvertFrom-Json | Out-Null
|
||||
git diff --check
|
||||
```
|
||||
|
||||
Also verify:
|
||||
|
||||
- every `manifest.json` copyMap source exists,
|
||||
- every profile path exists,
|
||||
- reusable files contain no private instance defaults such as a specific username or private host,
|
||||
- `README.md` documents every placeholder listed in `manifest.json`.
|
||||
|
||||
## Release
|
||||
|
||||
- Bump `manifest.json` version.
|
||||
- Update `CHANGELOG.md`.
|
||||
- Commit changes.
|
||||
- Create an annotated tag such as `v1.0.2`.
|
||||
- Push `main` and tags.
|
||||
- Create or update the Gitea release when a valid API token is available.
|
||||
41
CHANGELOG.md
Normal file
41
CHANGELOG.md
Normal file
@@ -0,0 +1,41 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to the Codex Agent Repository Kit are documented here.
|
||||
|
||||
## 1.0.5 - 2026-05-15
|
||||
|
||||
- Restored the rainbow section divider theme in the human-facing `README.md`.
|
||||
- Added separate minimal permission guidance for `REGISTRY_TOKEN` and `GITEA_TOKEN`.
|
||||
- Clarified where package-only and API-capable tokens should be used.
|
||||
|
||||
## 1.0.4 - 2026-05-15
|
||||
|
||||
- Set the documented Gitea host to `git.wilkensxl.de` instead of a generic URL placeholder.
|
||||
- Documented SSH clone URLs for port `2222` and optional SSH config.
|
||||
- Restored Gitea workflow and README badge defaults for the intended Gitea instance while keeping repository owner and repository name dynamic.
|
||||
|
||||
## 1.0.3 - 2026-05-15
|
||||
|
||||
- Updated repository handoff notes after verifying the refreshed local `GITEA_TOKEN`.
|
||||
- Confirmed live issue creation and Gitea release API access for this repository.
|
||||
|
||||
## 1.0.2 - 2026-05-15
|
||||
|
||||
- Split the repository documentation into a human-facing setup `README.md` and a repository-specific agent instruction file in `AGENTS.md`.
|
||||
- Expanded the human README with full new-repository setup guidance, SSH setup, Gitea token permissions, local token configuration, repository secrets, package publishing, and release checks.
|
||||
- Documented the recommended Gitea token permission matrix shown in the token UI.
|
||||
|
||||
## 1.0.1 - 2026-05-15
|
||||
|
||||
- Added agent guidance to create focused tracker issues for actionable follow-up work that is outside the current scope or independently parallelizable.
|
||||
- Added safeguards against creating vague, duplicate, or sensitive public issues.
|
||||
- Updated handoff guidance to use `docs/agent-handoff.md` when no issue tracker is available or the details are too sensitive for public issues.
|
||||
|
||||
## 1.0.0 - 2026-05-15
|
||||
|
||||
- Added universal repository baseline templates for Codex-assisted projects.
|
||||
- Added agent quickstart, new repository, and existing project workflows.
|
||||
- Added optional Gitea workflow templates for build, security scanning, cleanup, dependency checks, release dry runs, and template compliance.
|
||||
- Added stack profiles for Node, Electron, Python, Docker, and static sites.
|
||||
- Added guidance for dynamic repository owners, safe task-start syncs, release artifact exclusions, and context token conservation.
|
||||
- Removed hard-coded private Gitea instance URLs from reusable templates.
|
||||
368
README.md
Normal file
368
README.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Codex Agent Repository Kit
|
||||
|
||||
Reusable setup kit for new or existing repositories that should be easy for Codex agents, humans, and CI workflows to maintain.
|
||||
|
||||
This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quickstart.md`, `new-repository.md`, and `existing-project.md`.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## What This Kit Adds
|
||||
|
||||
- `AGENTS.md` and `.codex/project.md` for agent context.
|
||||
- Optional Gitea workflows for build, security scan, cleanup, dependency check, release dry run, and template compliance.
|
||||
- Release, security, handoff, changelog, and contribution templates.
|
||||
- README blueprint templates for projects that want generated README output.
|
||||
- Stack notes for Node, Electron, Python, Docker, and static-site projects.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Recommended New Repository Setup
|
||||
|
||||
1. Create the repository in Gitea.
|
||||
2. Clone it locally with SSH.
|
||||
3. Copy this kit into the repository with Codex or manually from `files/`.
|
||||
4. Replace placeholders with real project values.
|
||||
5. Add repository secrets for CI publishing.
|
||||
6. Commit and push the baseline.
|
||||
7. Let the Gitea workflows report any missing setup.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## SSH Setup
|
||||
|
||||
Generate a key if you do not already have one:
|
||||
|
||||
```powershell
|
||||
ssh-keygen -t ed25519 -C "you@example.com"
|
||||
```
|
||||
|
||||
Start the SSH agent and add the key:
|
||||
|
||||
```powershell
|
||||
Start-Service ssh-agent
|
||||
ssh-add $env:USERPROFILE\.ssh\id_ed25519
|
||||
```
|
||||
|
||||
Show the public key:
|
||||
|
||||
```powershell
|
||||
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
|
||||
```
|
||||
|
||||
Add that public key in Gitea:
|
||||
|
||||
```text
|
||||
Profile -> Settings -> SSH / GPG Keys -> Add Key
|
||||
```
|
||||
|
||||
Clone with SSH:
|
||||
|
||||
```bash
|
||||
git clone ssh://git@git.wilkensxl.de:2222/OWNER/REPOSITORY.git
|
||||
cd REPOSITORY
|
||||
```
|
||||
|
||||
Optional SSH config:
|
||||
|
||||
```text
|
||||
Host git.wilkensxl.de
|
||||
HostName git.wilkensxl.de
|
||||
User git
|
||||
Port 2222
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
With that config, this shorter clone URL also works:
|
||||
|
||||
```bash
|
||||
git clone git@git.wilkensxl.de:OWNER/REPOSITORY.git
|
||||
```
|
||||
|
||||
Verify the remote:
|
||||
|
||||
```bash
|
||||
git remote -v
|
||||
git status --short
|
||||
```
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Applying The Kit With Codex
|
||||
|
||||
For a new repository, start Codex in the target repository and use:
|
||||
|
||||
```text
|
||||
Use the Codex Agent Repository Kit.
|
||||
Read manifest.json, then use new-repository.md.
|
||||
Create the smallest useful baseline for this repository.
|
||||
Replace placeholders with real values from this repository.
|
||||
Keep commands truthful and do not invent scripts that cannot run.
|
||||
Do not create a release.
|
||||
```
|
||||
|
||||
For an existing repository:
|
||||
|
||||
```text
|
||||
Use the Codex Agent Repository Kit.
|
||||
Read manifest.json, then use existing-project.md.
|
||||
Retrofit the baseline without replacing existing project structure or README knowledge.
|
||||
Preserve current CI behavior and project style.
|
||||
Do not create a release.
|
||||
```
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Manual Copy Map
|
||||
|
||||
Use `manifest.json` as the source of truth. Common targets:
|
||||
|
||||
| Template | Target |
|
||||
| --- | --- |
|
||||
| `files/AGENTS.md` | `AGENTS.md` |
|
||||
| `files/project.md` | `.codex/project.md` |
|
||||
| `files/build-gitea.yml` | `.gitea/workflows/build.yml` |
|
||||
| `files/security-scan-gitea.yml` | `.gitea/workflows/security-scan.yml` |
|
||||
| `files/repo-cleanup-gitea.yml` | `.gitea/workflows/repo-cleanup.yml` |
|
||||
| `files/dependency-check-gitea.yml` | `.gitea/workflows/dependency-check.yml` |
|
||||
| `files/release-dry-run-gitea.yml` | `.gitea/workflows/release-dry-run.yml` |
|
||||
| `files/template-compliance-gitea.yml` | `.gitea/workflows/template-compliance.yml` |
|
||||
| `files/SECURITY.md` | `SECURITY.md` |
|
||||
| `files/CHANGELOG.md` | `CHANGELOG.md` |
|
||||
| `files/CONTRIBUTING.md` | `CONTRIBUTING.md` |
|
||||
| `files/release-checklist.md` | `docs/release-checklist.md` |
|
||||
| `files/security-review.md` | `docs/security-review.md` |
|
||||
| `files/agent-handoff.md` | `docs/agent-handoff.md` |
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Required Placeholder Values
|
||||
|
||||
Replace or remove all placeholders before considering a repository ready:
|
||||
|
||||
```text
|
||||
PROJECT_NAME
|
||||
PROJECT_DESCRIPTION
|
||||
REPOSITORY_OWNER
|
||||
REPOSITORY_NAME
|
||||
PACKAGE_NAME
|
||||
ARTIFACT_NAME
|
||||
ARTIFACT_OUTPUT_DIRECTORY
|
||||
AUTHOR_NAME
|
||||
PROJECT_STACK
|
||||
DOWNLOAD_URL
|
||||
CI_URL
|
||||
RELEASES_URL
|
||||
BUILD_COMMAND
|
||||
TEST_COMMAND
|
||||
LINT_COMMAND
|
||||
AUDIT_COMMAND
|
||||
README_COMMAND
|
||||
INSTALL_COMMAND
|
||||
DEV_COMMAND
|
||||
PACKAGE_MANAGER
|
||||
PROJECT_VERSION
|
||||
COMMIT_OR_VERSION
|
||||
```
|
||||
|
||||
If a value does not apply, remove that section instead of leaving fake data. If a value is genuinely unknown, mark it as `PENDING`.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Token Overview
|
||||
|
||||
Use separate tokens for separate jobs.
|
||||
|
||||
| Token | Location | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `REGISTRY_TOKEN` | Repository secret | CI package publishing from Gitea Actions |
|
||||
| `GITEA_TOKEN` | Local environment or repository secret | Gitea API access for issues, releases, workflow polling, and repository metadata |
|
||||
|
||||
Repository secrets are available to workflows. They are not visible to local Codex sessions. Local Codex API actions need a local environment variable.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Gitea Token Permissions
|
||||
|
||||
For both tokens, choose this repository access level:
|
||||
|
||||
```text
|
||||
Repository and Organization Access: All (public, private, and limited)
|
||||
```
|
||||
|
||||
Use separate tokens where possible. A package-only token should not be able to create issues or releases.
|
||||
|
||||
### REGISTRY_TOKEN Permissions
|
||||
|
||||
Use this token as a repository secret for package publishing from Gitea Actions:
|
||||
|
||||
```text
|
||||
package: Read and Write
|
||||
repository: Read
|
||||
user: Read
|
||||
|
||||
activitypub: No Access
|
||||
admin: No Access
|
||||
issue: No Access
|
||||
misc: No Access
|
||||
notification: No Access
|
||||
organization: No Access
|
||||
```
|
||||
|
||||
These permissions cover generic package uploads while still allowing the workflow to read repository metadata.
|
||||
|
||||
### GITEA_TOKEN Permissions
|
||||
|
||||
Use this token locally on the PC for Codex API actions, or as a repository secret only when workflows need issue, release, or workflow API access:
|
||||
|
||||
```text
|
||||
issue: Read and Write
|
||||
package: Read
|
||||
repository: Read and Write
|
||||
user: Read
|
||||
|
||||
activitypub: No Access
|
||||
admin: No Access
|
||||
misc: No Access
|
||||
notification: No Access
|
||||
organization: No Access
|
||||
```
|
||||
|
||||
These permissions cover creating and reading issues, creating and reading releases, reading repository metadata, and polling workflow runs where the Gitea API allows it. `package: Read` is enough for API checks; use `package: Read and Write` only if this same token must publish packages.
|
||||
|
||||
Use a dedicated bot or automation user when possible.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Setting Local Tokens
|
||||
|
||||
Set a local token for Codex or shell-based API work.
|
||||
|
||||
Current PowerShell session:
|
||||
|
||||
```powershell
|
||||
$env:GITEA_TOKEN = "paste-token-here"
|
||||
```
|
||||
|
||||
Persist for the current Windows user:
|
||||
|
||||
```powershell
|
||||
setx GITEA_TOKEN "paste-token-here"
|
||||
```
|
||||
|
||||
Open a new terminal after `setx`.
|
||||
|
||||
Test repository API access:
|
||||
|
||||
```powershell
|
||||
$headers = @{ Authorization = "token $env:GITEA_TOKEN" }
|
||||
Invoke-RestMethod `
|
||||
-Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
|
||||
-Headers $headers
|
||||
```
|
||||
|
||||
Test issue access:
|
||||
|
||||
```powershell
|
||||
Invoke-RestMethod `
|
||||
-Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
|
||||
-Headers $headers
|
||||
```
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Setting Repository Secrets
|
||||
|
||||
In Gitea:
|
||||
|
||||
```text
|
||||
Repository -> Settings -> Actions -> Secrets -> Add Secret
|
||||
```
|
||||
|
||||
Add:
|
||||
|
||||
```text
|
||||
REGISTRY_TOKEN
|
||||
```
|
||||
|
||||
Use a token with package write access. If you want workflows to create releases or issues too, add a separate secret:
|
||||
|
||||
```text
|
||||
GITEA_TOKEN
|
||||
```
|
||||
|
||||
Keep package publishing and release or issue automation separate when possible. It makes permission reviews easier.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Package Publishing
|
||||
|
||||
`files/build-gitea.yml` can publish generic packages when `REGISTRY_TOKEN` is available.
|
||||
|
||||
The workflow:
|
||||
|
||||
- builds project artifacts,
|
||||
- copies them to URL-safe filenames,
|
||||
- uploads immutable versioned packages,
|
||||
- updates a stable `latest` package path.
|
||||
|
||||
The workflow uses:
|
||||
|
||||
```text
|
||||
GITHUB_SERVER_URL
|
||||
GITHUB_REPOSITORY_OWNER
|
||||
GITHUB_REPOSITORY
|
||||
REGISTRY_TOKEN
|
||||
```
|
||||
|
||||
When those values are unavailable, replace `REPOSITORY_OWNER`, `REPOSITORY_NAME`, and related placeholders before use. The default Gitea server is `https://git.wilkensxl.de`.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Agent Follow-up Issues
|
||||
|
||||
Agents should create focused tracker issues for real follow-up work that is outside the current scope or can be handled independently by humans or other agents.
|
||||
|
||||
An issue should include:
|
||||
|
||||
- observed problem,
|
||||
- impact,
|
||||
- affected files or commands,
|
||||
- suggested next steps,
|
||||
- verification already performed.
|
||||
|
||||
Agents must not create issues for vague reminders, duplicate work, or tasks they can safely finish immediately. Sensitive details belong in private channels or `docs/agent-handoff.md`, not public issues.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Release Checklist For A New Repo
|
||||
|
||||
Before the first release of a target project:
|
||||
|
||||
1. Ensure `AGENTS.md` and `.codex/project.md` match the real project.
|
||||
2. Replace all placeholders or mark genuinely unknown values as `PENDING`.
|
||||
3. Configure `REGISTRY_TOKEN` if packages are published.
|
||||
4. Configure `GITEA_TOKEN` only if workflows need issue or release API access.
|
||||
5. Verify SSH push access.
|
||||
6. Run lint, test, build, and audit commands that exist.
|
||||
7. Run `git diff --check`.
|
||||
8. Confirm release artifacts do not include Codex kit metadata unless explicitly wanted.
|
||||
9. Push and poll workflows to success or document the blocker.
|
||||
|
||||
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
|
||||
|
||||
## Updating The Kit In A Project
|
||||
|
||||
When this kit changes, update target repositories conservatively:
|
||||
|
||||
```bash
|
||||
git status --short
|
||||
git pull --ff-only
|
||||
```
|
||||
|
||||
Then ask Codex:
|
||||
|
||||
```text
|
||||
Update this repository's Codex Agent Repository Kit files from the latest kit.
|
||||
Preserve project-specific README content, commands, release rules, and workflow customizations.
|
||||
Do not overwrite unrelated changes.
|
||||
```
|
||||
206
agent-quickstart.md
Normal file
206
agent-quickstart.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# 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.
|
||||
Conserve context tokens: search first, read only relevant files, summarize large outputs, and avoid generated folders, dependency folders, build outputs, or full logs unless directly relevant.
|
||||
At the start of each user-requested task, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean.
|
||||
If local changes exist, do not overwrite them; fetch or report the blocker before editing.
|
||||
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.
|
||||
Create tracker issues for real, actionable follow-ups that are outside the current scope or independently parallelizable; use docs/agent-handoff.md when no issue tracker is available.
|
||||
Exclude Codex kit metadata from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless explicitly requested.
|
||||
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
|
||||
|
||||
Is the working tree clean at task start?
|
||||
yes -> run a fast-forward update check such as git pull --ff-only before editing
|
||||
no -> do not overwrite local changes; fetch or report the blocker before editing
|
||||
|
||||
Does a stack profile match?
|
||||
yes -> read the matching profiles/*.md file and adapt commands carefully
|
||||
no -> continue with universal rules only
|
||||
|
||||
Can you answer the next question with targeted search or a small file slice?
|
||||
yes -> use that instead of loading whole directories or long logs
|
||||
no -> read the smallest complete file set that preserves correctness
|
||||
|
||||
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
|
||||
|
||||
Do user-facing release artifacts include Codex kit metadata such as AGENTS.md, .codex/, blueprint files, template workflows, or agent handoff notes?
|
||||
yes -> exclude those files unless the user explicitly asked to ship repository-maintenance files
|
||||
no -> continue
|
||||
|
||||
Is the work interrupted, risky, or multi-session?
|
||||
yes -> update docs/agent-handoff.md
|
||||
no -> no handoff file is required
|
||||
|
||||
Did you find real follow-up work outside the current scope?
|
||||
yes -> create focused tracker issues for independent work; include impact, affected files, next steps, and verification
|
||||
no -> do not create placeholder issues
|
||||
|
||||
Could the issue expose secrets, private data, or sensitive logs?
|
||||
yes -> do not put sensitive details in a public issue; summarize safely and keep details private or in handoff notes
|
||||
no -> continue
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
40
docs/agent-handoff.md
Normal file
40
docs/agent-handoff.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# Agent Handoff
|
||||
|
||||
Use this file for current repository follow-ups when tracker issues cannot be created or when a compact session summary is useful.
|
||||
|
||||
## Current State
|
||||
|
||||
The kit includes guidance for creating focused tracker issues for actionable follow-up work. The local `GITEA_TOKEN` has been refreshed and verified.
|
||||
|
||||
## Changes Made
|
||||
|
||||
- Added issue creation guidance to the agent rules, quickstart, README, new/existing repository workflows, and manifest.
|
||||
- Added handoff guidance for cases where issue creation is unavailable or too sensitive.
|
||||
- Updated the kit version to `1.0.2`.
|
||||
- Created a live follow-up issue after token access was restored.
|
||||
- Created the Gitea release entry for `v1.0.2`.
|
||||
|
||||
## Verification
|
||||
|
||||
| Check | Result |
|
||||
| --- | --- |
|
||||
| Issue creation test | Passed: created issue #1 |
|
||||
| Release API test | Passed: created release entry for `v1.0.2` |
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None at this time.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- Use issue #1 to track adding a reusable follow-up issue template.
|
||||
|
||||
## Follow-up Issues
|
||||
|
||||
| Issue | Status |
|
||||
| --- | --- |
|
||||
| #1 Add reusable issue template for agent follow-ups | Open |
|
||||
|
||||
## Risks
|
||||
|
||||
- No known token blocker remains after the refreshed token test.
|
||||
189
existing-project.md
Normal file
189
existing-project.md
Normal file
@@ -0,0 +1,189 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
At task start, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean:
|
||||
|
||||
```bash
|
||||
git pull --ff-only
|
||||
```
|
||||
|
||||
If local changes exist, do not overwrite them. Fetch or report the blocker before editing.
|
||||
|
||||
Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the retrofit decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
|
||||
|
||||
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.
|
||||
|
||||
Derive the repository owner and repository name from the target repository remote URL or `GITHUB_REPOSITORY`. Do not copy the owner from this repository kit's own remote.
|
||||
|
||||
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.
|
||||
|
||||
Keep Codex kit files tracked in the source repository when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly wants repository-maintenance files shipped. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`.
|
||||
|
||||
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.
|
||||
|
||||
When retrofit work reveals real follow-up work that is outside the current scope or can be worked on independently, create focused tracker issues so humans or other agents can pick them up later or in parallel. Each issue should include the observed problem, impact, affected files or commands, suggested next steps, and verification already performed. Do not create issues for work you can safely finish in the current task, and never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md`.
|
||||
|
||||
### 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 Gitea repositories on `https://git.wilkensxl.de`, 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.
|
||||
|
||||
88
files/AGENTS.md
Normal file
88
files/AGENTS.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# 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.
|
||||
- Conserve context tokens: search with `rg` or targeted file lists first, read only the files needed for the task, summarize large outputs instead of pasting them, and avoid loading generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
|
||||
- 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.
|
||||
- At the start of every user-requested task, briefly check the repository for upstream updates and apply them immediately with a safe fast-forward pull when the working tree is clean. If local changes exist, do not overwrite them; fetch or report the blocker before editing.
|
||||
- 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.
|
||||
- Derive `REPOSITORY_OWNER` and `REPOSITORY_NAME` from the target repository remote or `GITHUB_REPOSITORY`. Never reuse the owner from this template repository.
|
||||
- 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.
|
||||
- When you find a real, actionable follow-up that is outside the current scope or can be worked on independently, create a tracker issue so humans or other agents can pick it up later or in parallel. Do not create issues for work you can safely finish in the current task. If no issue tracker is available, update `docs/agent-handoff.md` instead.
|
||||
- Keep issues scoped and actionable: include the observed problem, impact, affected files or commands, suggested next steps, and any verification already performed. Never include secrets, tokens, private data, or sensitive logs in public issues.
|
||||
- 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.
|
||||
- Keep Codex kit files in source control when they are useful for agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly asks to ship repository-maintenance files.
|
||||
|
||||
## 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.
|
||||
- Do not include Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, or agent handoff notes in downloadable release artifacts unless explicitly requested.
|
||||
- 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.
|
||||
- Independent follow-up work has tracker issues, or `docs/agent-handoff.md` explains why issues could not be created.
|
||||
- Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported.
|
||||
|
||||
8
files/CHANGELOG.md
Normal file
8
files/CHANGELOG.md
Normal file
@@ -0,0 +1,8 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this project are documented here.
|
||||
|
||||
## Unreleased
|
||||
|
||||
- Initial project setup.
|
||||
|
||||
48
files/CONTRIBUTING.md
Normal file
48
files/CONTRIBUTING.md
Normal 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.
|
||||
- Create focused issues for real follow-up work that is outside the current change or can be worked on independently. Do not put secrets, tokens, private data, or sensitive logs in public issues.
|
||||
|
||||
## 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
22
files/SECURITY.md
Normal file
@@ -0,0 +1,22 @@
|
||||
# Security Policy
|
||||
|
||||
## Supported Versions
|
||||
|
||||
| Version | Supported |
|
||||
| --- | --- |
|
||||
| Latest | Yes |
|
||||
|
||||
## Reporting A Vulnerability
|
||||
|
||||
Please report security issues privately to the project owner.
|
||||
|
||||
Do not include secrets, production data, or private credentials in public issues.
|
||||
|
||||
## Project Security Principles
|
||||
|
||||
- Keep secrets out of the repository.
|
||||
- Prefer local processing for user data.
|
||||
- Document external network calls.
|
||||
- Keep release artifacts reproducible through CI.
|
||||
- Run dependency audits before releases.
|
||||
|
||||
42
files/agent-handoff.md
Normal file
42
files/agent-handoff.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Agent Handoff
|
||||
|
||||
Use this file when a task spans multiple sessions, has unresolved follow-up work, or changes release behavior.
|
||||
|
||||
Prefer focused tracker issues for independent follow-up work when an issue tracker is available. Use this handoff file when issues cannot be created, when the context is too sensitive for a public issue, or when a task needs a compact session summary.
|
||||
|
||||
## 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
|
||||
|
||||
## Follow-up Issues
|
||||
|
||||
| Issue | Status |
|
||||
| --- | --- |
|
||||
| PENDING | PENDING |
|
||||
|
||||
## Risks
|
||||
|
||||
- PENDING
|
||||
29
files/blueprint.json
Normal file
29
files/blueprint.json
Normal file
@@ -0,0 +1,29 @@
|
||||
{
|
||||
"ids": {
|
||||
"github": "REPOSITORY_OWNER/REPOSITORY_NAME"
|
||||
},
|
||||
"badges": [
|
||||
{
|
||||
"alt": "Build",
|
||||
"img": "https://img.shields.io/badge/build-Gitea%20Runner-2563eb",
|
||||
"url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/actions"
|
||||
},
|
||||
{
|
||||
"alt": "Version",
|
||||
"img": "https://img.shields.io/badge/version-0.1.0-111827",
|
||||
"url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/releases"
|
||||
}
|
||||
],
|
||||
"headingPrefix": {
|
||||
"1": "",
|
||||
"2": ""
|
||||
},
|
||||
"line": "rainbow",
|
||||
"templates": [
|
||||
{
|
||||
"name": "section-line",
|
||||
"template": "<p align=\"center\"><img src=\"https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png\" alt=\"-----------------------------------------------------\" width=\"100%\"></p>"
|
||||
}
|
||||
],
|
||||
"text": "PROJECT_DESCRIPTION"
|
||||
}
|
||||
76
files/blueprint.md
Normal file
76
files/blueprint.md
Normal file
@@ -0,0 +1,76 @@
|
||||
{{ template:title }}
|
||||
|
||||
{{ template:badges }}
|
||||
|
||||
{{ template:section-line }}
|
||||
{{ template:table-of-contents }}
|
||||
|
||||
{{ template:section-line }}
|
||||
## Overview
|
||||
|
||||
PROJECT_DESCRIPTION
|
||||
|
||||
{{ template:section-line }}
|
||||
## Features
|
||||
|
||||
| Area | Description |
|
||||
| --- | --- |
|
||||
| Core | Describe the main project capability |
|
||||
| Workflow | Describe the primary user or developer workflow |
|
||||
| Build | Describe how artifacts are produced |
|
||||
| Security | Describe the default security posture |
|
||||
|
||||
{{ template:section-line }}
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
INSTALL_COMMAND
|
||||
```
|
||||
|
||||
{{ template:section-line }}
|
||||
## Development
|
||||
|
||||
```bash
|
||||
DEV_COMMAND
|
||||
LINT_COMMAND
|
||||
TEST_COMMAND
|
||||
BUILD_COMMAND
|
||||
```
|
||||
|
||||
{{ template:section-line }}
|
||||
## Downloads
|
||||
|
||||
| Variant | Download |
|
||||
| --- | --- |
|
||||
| Latest artifact | [Download latest](DOWNLOAD_URL) |
|
||||
|
||||
Private repositories may require an active session or a token with package read access.
|
||||
|
||||
{{ template:section-line }}
|
||||
## Security
|
||||
|
||||
Security posture:
|
||||
|
||||
| Area | State |
|
||||
| --- | --- |
|
||||
| Secrets | Secrets must not be committed |
|
||||
| Dependency audit | CI should run the project dependency audit |
|
||||
| User data | User data should stay local unless explicitly documented |
|
||||
| External services | Network calls should be documented |
|
||||
|
||||
See `SECURITY.md` and `docs/security-review.md`.
|
||||
|
||||
{{ template:section-line }}
|
||||
## Release
|
||||
|
||||
Release readiness is tracked in `docs/release-checklist.md`.
|
||||
|
||||
{{ template:section-line }}
|
||||
## Project Info
|
||||
|
||||
| Field | Value |
|
||||
| --- | --- |
|
||||
| Author | `AUTHOR_NAME` |
|
||||
| Repository | `REPOSITORY_OWNER/REPOSITORY_NAME` |
|
||||
| Stack | `PROJECT_STACK` |
|
||||
| README workflow | Blueprint workflow based on `andreasbm/readme` |
|
||||
111
files/build-gitea.yml
Normal file
111
files/build-gitea.yml
Normal file
@@ -0,0 +1,111 @@
|
||||
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"
|
||||
repository_owner="${GITHUB_REPOSITORY_OWNER:-${GITHUB_REPOSITORY%%/*}}"
|
||||
if [ -z "${repository_owner}" ] || [ "${repository_owner}" = "${GITHUB_REPOSITORY}" ]; then
|
||||
repository_owner="REPOSITORY_OWNER"
|
||||
fi
|
||||
gitea_server="${GITHUB_SERVER_URL:-https://git.wilkensxl.de}"
|
||||
gitea_server="${gitea_server%/}"
|
||||
package_dir="package-registry"
|
||||
latest_url="${gitea_server}/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}" \
|
||||
"${gitea_server}/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
114
files/dependency-check-gitea.yml
Normal 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
46
files/gitignore.template
Normal 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
|
||||
|
||||
73
files/project.md
Normal file
73
files/project.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# 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. verify release artifacts exclude Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflows, and agent handoff notes unless the user explicitly wants those shipped,
|
||||
6. create a tag,
|
||||
7. create the release.
|
||||
|
||||
Do not create releases unless the user explicitly asks for a release.
|
||||
36
files/release-checklist.md
Normal file
36
files/release-checklist.md
Normal file
@@ -0,0 +1,36 @@
|
||||
# Release Checklist
|
||||
|
||||
## Version
|
||||
|
||||
- [ ] Version number updated.
|
||||
- [ ] Changelog updated.
|
||||
- [ ] README regenerated if blueprint files changed.
|
||||
|
||||
## Quality
|
||||
|
||||
- [ ] Working tree is clean.
|
||||
- [ ] Lint/type checks pass.
|
||||
- [ ] Tests pass or missing tests are documented.
|
||||
- [ ] Build succeeds in CI.
|
||||
|
||||
## Security
|
||||
|
||||
- [ ] Security review is current.
|
||||
- [ ] Dependency audit is clean or documented.
|
||||
- [ ] No secrets are committed.
|
||||
- [ ] Release artifacts do not contain local config files.
|
||||
|
||||
## Artifacts
|
||||
|
||||
- [ ] Artifacts are uploaded.
|
||||
- [ ] User-facing artifacts exclude Codex kit metadata such as `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflows, and agent handoff notes unless explicitly requested.
|
||||
- [ ] 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
133
files/release-dry-run-gitea.yml
Normal 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 .gitea)
|
||||
placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|CI_URL|RELEASES_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|COMMIT_OR_VERSION'
|
||||
|
||||
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
31
files/release-notes.md
Normal 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
139
files/repo-cleanup-gitea.yml
Normal 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
54
files/security-review.md
Normal file
@@ -0,0 +1,54 @@
|
||||
# Security Review
|
||||
|
||||
## Scope
|
||||
|
||||
Project:
|
||||
|
||||
```text
|
||||
PROJECT_NAME
|
||||
```
|
||||
|
||||
Reviewed version or commit:
|
||||
|
||||
```text
|
||||
COMMIT_OR_VERSION
|
||||
```
|
||||
|
||||
## Code Patterns Checked
|
||||
|
||||
- [ ] No `eval`.
|
||||
- [ ] No dynamic `Function` constructor.
|
||||
- [ ] No unsafe HTML injection.
|
||||
- [ ] No unexpected shell execution.
|
||||
- [ ] No unexpected external network calls.
|
||||
- [ ] No secrets committed.
|
||||
- [ ] No unsafe file writes outside expected user-selected paths.
|
||||
|
||||
## Dependency Review
|
||||
|
||||
Command:
|
||||
|
||||
```bash
|
||||
AUDIT_COMMAND
|
||||
```
|
||||
|
||||
Result:
|
||||
|
||||
```text
|
||||
PENDING
|
||||
```
|
||||
|
||||
## Runtime Review
|
||||
|
||||
- [ ] Least-privilege runtime configuration.
|
||||
- [ ] External URLs documented.
|
||||
- [ ] Local data storage documented.
|
||||
- [ ] Sensitive data is not persisted unless explicitly required.
|
||||
|
||||
## Release Notes
|
||||
|
||||
Known residual risks:
|
||||
|
||||
```text
|
||||
None documented yet.
|
||||
```
|
||||
174
files/security-scan-gitea.yml
Normal file
174
files/security-scan-gitea.yml
Normal 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
109
files/template-compliance-gitea.yml
Normal 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 .gitea 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|CI_URL|RELEASES_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|README_COMMAND|INSTALL_COMMAND|DEV_COMMAND|PACKAGE_MANAGER|PROJECT_VERSION|COMMIT_OR_VERSION'
|
||||
|
||||
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
|
||||
231
manifest.json
Normal file
231
manifest.json
Normal file
@@ -0,0 +1,231 @@
|
||||
{
|
||||
"name": "codex-agent-repository-kit",
|
||||
"version": "1.0.5",
|
||||
"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.",
|
||||
"Conserve context tokens by searching first, reading only relevant files, summarizing large outputs, and avoiding generated folders, dependency folders, build outputs, or full logs unless directly relevant.",
|
||||
"At the start of each user-requested task, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean.",
|
||||
"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.",
|
||||
"Create focused tracker issues for real follow-up work that is outside the current scope or independently parallelizable, and use docs/agent-handoff.md when no issue tracker is available.",
|
||||
"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",
|
||||
"CI_URL",
|
||||
"RELEASES_URL",
|
||||
"BUILD_COMMAND",
|
||||
"TEST_COMMAND",
|
||||
"LINT_COMMAND",
|
||||
"AUDIT_COMMAND",
|
||||
"README_COMMAND",
|
||||
"INSTALL_COMMAND",
|
||||
"DEV_COMMAND",
|
||||
"PACKAGE_MANAGER",
|
||||
"PROJECT_VERSION",
|
||||
"COMMIT_OR_VERSION"
|
||||
],
|
||||
"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
209
manifest.schema.json
Normal 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"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
203
new-repository.md
Normal file
203
new-repository.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 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
|
||||
```
|
||||
|
||||
At task start, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean:
|
||||
|
||||
```bash
|
||||
git pull --ff-only
|
||||
```
|
||||
|
||||
If local changes exist, do not overwrite them. Fetch or report the blocker before editing.
|
||||
|
||||
Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the baseline decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
Derive `REPOSITORY_OWNER` and `REPOSITORY_NAME` from the target repository remote URL or `GITHUB_REPOSITORY`. Do not copy the owner from this repository kit's own remote.
|
||||
|
||||
Optional:
|
||||
|
||||
```text
|
||||
PACKAGE_NAME
|
||||
ARTIFACT_NAME
|
||||
ARTIFACT_OUTPUT_DIRECTORY
|
||||
AUTHOR_NAME
|
||||
PROJECT_STACK
|
||||
DOWNLOAD_URL
|
||||
CI_URL
|
||||
RELEASES_URL
|
||||
BUILD_COMMAND
|
||||
TEST_COMMAND
|
||||
LINT_COMMAND
|
||||
AUDIT_COMMAND
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
Keep Codex kit files tracked in the source repository when they help agents, but exclude them from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless the user explicitly wants repository-maintenance files shipped. Typical excluded paths are `AGENTS.md`, `.codex/`, `blueprint.md`, `blueprint.json`, template workflow files, and `docs/agent-handoff.md`.
|
||||
|
||||
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.
|
||||
|
||||
When the setup reveals real follow-up work that is outside the current scope or can be worked on independently, create focused tracker issues so humans or other agents can pick them up later or in parallel. Each issue should include the observed problem, impact, affected files or commands, suggested next steps, and verification already performed. Do not create issues for work you can safely finish in the current task, and never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md`.
|
||||
|
||||
### 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 Gitea repositories on `https://git.wilkensxl.de`, 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
36
profiles/docker.md
Normal 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
43
profiles/electron.md
Normal 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
42
profiles/node.md
Normal 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
36
profiles/python.md
Normal 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
36
profiles/static-site.md
Normal 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/
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user