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.

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

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,
• if the pushed workflow fails, inspect the failing job/logs, fix in scope, push again, and re-check the next run,
• list files changed,
• mention any skipped checks,
• do not create a release unless explicitly requested.