codex-agent-repository-kit/existing-project.md

# 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.

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.

If CI does not exist:

- add `.gitea/workflows/build.yml` from the template,
- remove stack-specific steps that do not apply,
- keep publishing disabled until credentials and artifact names are known.

For releasable projects, add `.gitea/workflows/security-scan.yml` unless the repository already has equivalent scheduled security automation. If an existing scanner is present, document it in `.codex/project.md` instead of duplicating it.

For active repositories, add `.gitea/workflows/repo-cleanup.yml` unless equivalent cleanup checks already exist. Keep cleanup automation non-destructive and document intentional exceptions.

For projects with dependencies, add `.gitea/workflows/dependency-check.yml` unless equivalent dependency update or dependency audit checks already exist. Keep it report-only.

For releasable projects, add `.gitea/workflows/release-dry-run.yml` unless equivalent release readiness checks already exist. It must not tag, publish, or create releases.

For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml` unless equivalent agent-context checks already exist. Preserve documented project-specific exceptions.

### 6. Security Review

Fill `docs/security-review.md` with known facts.

At minimum check for:

```text
eval
dynamic Function
unsafe HTML injection
shell execution
external network calls
file writes
secret persistence
committed .env files
```

Use the stack-native audit command when possible:

| Stack | Audit command |
| --- | --- |
| Node | `npm audit --omit=dev --audit-level=high` |
| Python | `pip-audit` or `uv pip audit` |
| Rust | `cargo audit` |
| Go | `govulncheck ./...` |
| .NET | `dotnet list package --vulnerable` |

### 7. Finish

Before final response:

- run `git diff --check`,
- run the smallest reliable verification command,
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
- if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
- list files changed,
- mention any skipped checks,
- do not create a release unless explicitly requested.