# 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, check the pushed workflow run; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
- list files changed,
- mention any skipped checks,
- do not create a release unless explicitly requested.