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

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

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.

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.

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:

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:

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 Gitea repositories, use a locally set GITEA_TOKEN and GITEA_SERVER_URL 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.