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
```

At task start, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean:

```bash
git pull --ff-only
```

If local changes exist, do not overwrite them. Fetch or report the blocker before editing.

Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the retrofit decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.

Treat `global-runner-1`, `global-runner-2`, and `global-runner-3` as the only supported build runners. Project builds, tests, audits, package jobs, installers, dependency setup, and releases must run on Gitea Ubuntu runners with `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`, not on the user's local machine. If tooling looks Windows-specific, use an open-source Linux-compatible workaround instead of adding a Windows runner.

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,
- replace unsupported runner labels with `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04`,
- 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.

When retrofit work reveals real follow-up work that is outside the current scope or can be worked on independently, create focused tracker issues so humans or other agents can pick them up later or in parallel. Each issue should include the observed problem, impact, affected files or commands, suggested next steps, and verification already performed. Do not create issues for work you can safely finish in the current task, and never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md`.

### 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 only lightweight local validation that does not install dependencies or create build artifacts,
- run the smallest reliable project verification command through Gitea Actions on a supported Ubuntu runner,
- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories on `https://git.wilkensxl.de`, 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.