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:

git status --short

Read:

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.

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:

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:

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.