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.

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.

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