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

Add scheduled repository cleanup workflow

Browse Source
This commit is contained in:
MrSphay
2026-05-03 22:08:43 +02:00
parent 6308417945
commit 0366a285c5
8 changed files with 212 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
README.md
View File

@@ -61,6 +61,7 @@ Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `R
| `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/release-checklist.md` | `docs/release-checklist.md` |
| `files/security-review.md` | `docs/security-review.md` |
| `files/blueprint.md` | `blueprint.md` |
@@ -125,6 +126,7 @@ When applying this kit, an agent should:
- update `README.md` whenever README blueprint files change,
- update security and release docs when release behavior changes,
- add or preserve scheduled security automation for releasable projects,
- add or preserve scheduled repository cleanup checks for active projects,
- update `docs/agent-handoff.md` when work is interrupted, risky, or multi-session,
- run `git diff --check` before finishing,
- run the cheapest reliable verification command,
@@ -147,6 +149,21 @@ The workflow is intentionally conservative. If it fails, an agent should inspect
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Scheduled Repository Cleanup
`files/repo-cleanup-gitea.yml` provides an optional weekly Gitea workflow for active repositories.
It reports:
- generated files or dependency folders that were accidentally tracked,
- large tracked files that may belong in release artifacts or package storage,
- secret-prone local config files,
- stale remote branch candidates.
The workflow is intentionally non-destructive. It must not delete files, branches, packages, or releases. Agents should treat failures as maintenance reports, document intentional exceptions, and only remove repository data after explicit user approval.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Gitea API Token
When working with private repositories on `git.wilkensxl.de`, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine.

6
agent-quickstart.md
View File

@@ -10,6 +10,7 @@ Use its copyMap for file destinations.
Use new-repository.md or existing-project.md as the task workflow.
Use matching profiles/*.md guidance after detecting the stack.
For releasable projects, add or preserve scheduled security automation.
For active projects, add or preserve non-destructive scheduled repository cleanup checks.
Check git status before editing.
Preserve unrelated user changes.
Replace all applicable placeholders and remove non-applicable placeholder sections.
@@ -79,6 +80,10 @@ 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
Are commands unknown?
yes -> document PENDING in .codex/project.md
no -> wire commands into AGENTS.md and CI
@@ -129,6 +134,7 @@ docs/security-review.md
docs/agent-handoff.md
.gitea/workflows/build.yml
.gitea/workflows/security-scan.yml
.gitea/workflows/repo-cleanup.yml
```
For README-generator projects:

2
existing-project.md
View File

@@ -122,6 +122,8 @@ If CI does not exist:
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.
### 6. Security Review
Fill `docs/security-review.md` with known facts.

3
files/AGENTS.md
View File

@@ -21,6 +21,8 @@ PROJECT_NAME: PROJECT_DESCRIPTION
- 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.
- Repository cleanup automation must be non-destructive. Do not delete branches, packages, releases, or tracked files without explicit user approval.
## Commands
@@ -56,6 +58,7 @@ ARTIFACT_NAME
- 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.
- Treat generated credentials and config files as sensitive.
- Keep external network calls documented.
- Prefer local processing for user data.

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

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

18
manifest.json
View File

@@ -12,6 +12,7 @@
"Update README.md whenever blueprint.md or blueprint.json changes.",
"Update docs/security-review.md during release-readiness work.",
"Update docs/release-checklist.md when release behavior changes.",
"Add or preserve non-destructive scheduled repository cleanup checks for active projects.",
"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."
@@ -27,6 +28,18 @@
"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
},
"readmeDivider": {
"templateName": "section-line",
"source": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png",
@@ -108,6 +121,11 @@
"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
}
],
"placeholders": [

24
manifest.schema.json
View File

@@ -55,6 +55,30 @@
}
}
},
"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"
}
}
},
"workflows": {
"type": "object",
"required": ["newRepository", "existingProject", "quickstart"],

3
new-repository.md
View File

@@ -51,6 +51,7 @@ 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
```
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.
@@ -159,6 +160,8 @@ Only publish artifacts to a package registry when the artifact names and credent
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.
### 7. Finish
Before final response: