154 lines
3.5 KiB
Markdown
154 lines
3.5 KiB
Markdown
# Existing Project Agent Workflow
|
|
|
|
Use this file when an existing repository should become easier for Codex agents to maintain.
|
|
|
|
## Objective
|
|
|
|
Add a Codex-friendly repository baseline without flattening the project's existing structure, README voice, or release process.
|
|
|
|
## Rules
|
|
|
|
- Preserve existing application code.
|
|
- Preserve existing README knowledge.
|
|
- Do not rename files or folders unless the project already requires it.
|
|
- Do not replace a working CI pipeline wholesale.
|
|
- Add missing structure gradually.
|
|
- Prefer documenting current reality over inventing a new process.
|
|
|
|
## Steps
|
|
|
|
### 1. Inspect First
|
|
|
|
Run:
|
|
|
|
```bash
|
|
git status --short
|
|
```
|
|
|
|
Read:
|
|
|
|
```text
|
|
README*
|
|
package.json / pyproject.toml / Cargo.toml / go.mod / *.csproj
|
|
.github/workflows/*
|
|
.gitea/workflows/*
|
|
docs/*
|
|
```
|
|
|
|
Identify:
|
|
|
|
- stack,
|
|
- package manager,
|
|
- build command,
|
|
- test command,
|
|
- lint command,
|
|
- audit command,
|
|
- release artifacts,
|
|
- current CI,
|
|
- existing release notes or changelog,
|
|
- security-sensitive behavior.
|
|
|
|
### 2. Add Agent Context
|
|
|
|
Add `AGENTS.md` first. Keep it short and factual.
|
|
|
|
Then add `.codex/project.md` with:
|
|
|
|
- project purpose,
|
|
- authoritative commands,
|
|
- artifact locations,
|
|
- release process,
|
|
- security constraints.
|
|
|
|
### 3. Add Documentation Files
|
|
|
|
Add only missing files:
|
|
|
|
```text
|
|
SECURITY.md
|
|
CHANGELOG.md
|
|
docs/security-review.md
|
|
docs/release-checklist.md
|
|
```
|
|
|
|
If equivalent files already exist, update those instead of duplicating them.
|
|
|
|
### 4. README Generator Decision
|
|
|
|
Use README blueprint generation only when it helps.
|
|
|
|
Use it when:
|
|
|
|
- README is large enough to benefit from structure,
|
|
- project has downloads or release artifacts,
|
|
- repeated README updates are expected.
|
|
|
|
Avoid it when:
|
|
|
|
- README is tiny,
|
|
- project has a strong existing documentation system,
|
|
- generator output would erase project-specific style.
|
|
|
|
If converting:
|
|
|
|
1. Copy the current README content into `blueprint.md`.
|
|
2. Add `blueprint.json`.
|
|
3. Add a `readme` command.
|
|
4. Generate `README.md`.
|
|
5. Compare the diff carefully.
|
|
|
|
### 5. CI Retrofit
|
|
|
|
If CI already exists:
|
|
|
|
- add missing audit/check steps,
|
|
- keep existing runner labels,
|
|
- keep existing artifact names unless they are broken,
|
|
- avoid changing deployment behavior.
|
|
|
|
If CI does not exist:
|
|
|
|
- add `.gitea/workflows/build.yml` from the template,
|
|
- remove stack-specific steps that do not apply,
|
|
- keep publishing disabled until credentials and artifact names are known.
|
|
|
|
### 6. Security Review
|
|
|
|
Fill `docs/security-review.md` with known facts.
|
|
|
|
At minimum check for:
|
|
|
|
```text
|
|
eval
|
|
dynamic Function
|
|
unsafe HTML injection
|
|
shell execution
|
|
external network calls
|
|
file writes
|
|
secret persistence
|
|
committed .env files
|
|
```
|
|
|
|
Use the stack-native audit command when possible:
|
|
|
|
| Stack | Audit command |
|
|
| --- | --- |
|
|
| Node | `npm audit --omit=dev --audit-level=high` |
|
|
| Python | `pip-audit` or `uv pip audit` |
|
|
| Rust | `cargo audit` |
|
|
| Go | `govulncheck ./...` |
|
|
| .NET | `dotnet list package --vulnerable` |
|
|
|
|
### 7. Finish
|
|
|
|
Before final response:
|
|
|
|
- run `git diff --check`,
|
|
- run the smallest reliable verification command,
|
|
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
|
|
- if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
|
|
- list files changed,
|
|
- mention any skipped checks,
|
|
- do not create a release unless explicitly requested.
|
|
|