codex-agent-repository-kit/agent-quickstart.md

Agent Quickstart

Use this file when you want Codex to apply the repository kit with minimal instructions.

Required Agent Behavior

Read manifest.json first.
Use its copyMap for file destinations.
Use new-repository.md or existing-project.md as the task workflow.
Use matching profiles/*.md guidance after detecting the stack.
Conserve context tokens: search first, read only relevant files, summarize large outputs, and avoid generated folders, dependency folders, build outputs, or full logs unless directly relevant.
At the start of each user-requested task, check for upstream repository updates and apply them immediately with a safe fast-forward pull when the working tree is clean.
If local changes exist, do not overwrite them; fetch or report the blocker before editing.
For releasable projects, add or preserve scheduled security automation.
For active projects, add or preserve non-destructive scheduled repository cleanup checks.
For Codex-maintained projects, add or preserve dependency, release dry-run, and template compliance checks when useful.
Check git status before editing.
Preserve unrelated user changes.
Replace all applicable placeholders and remove non-applicable placeholder sections.
Keep AGENTS.md and .codex/project.md aligned with real commands and artifact paths.
Update README.md whenever blueprint.md or blueprint.json changes.
Create tracker issues for real, actionable follow-ups that are outside the current scope or independently parallelizable; use docs/agent-handoff.md when no issue tracker is available.
Exclude Codex kit metadata from user-facing release, package, installer, archive, and GitHub/Gitea upload artifacts unless explicitly requested.
Run git diff --check before finishing.
Run the cheapest reliable verification command, or explain why it could not run.

New Repository Prompt

Apply the Codex Agent Repository Kit from templates/codex-project.
Use new-repository.md as the workflow.
Create the smallest useful baseline for this repository.
Detect the stack and replace placeholders with real project values.
Keep commands truthful: do not add commands that cannot run.
Use manifest.json as the source of truth for copy targets.
Keep the README generator only if it adds value.
When using the README generator, keep the rainbow `{{ template:section-line }}` divider between major sections.
Do not create a release.
Run the cheapest available verification before finishing.

Existing Repository Prompt

Apply the Codex Agent Repository Kit from templates/codex-project.
Use existing-project.md as the workflow.
Preserve existing code, README knowledge, CI behavior, and project style.
Add missing Codex agent context, security review, release checklist, and optional README generator files.
Keep commands truthful: do not add commands that cannot run.
Use manifest.json as the source of truth for copy targets.
When using or adding the README generator, keep the rainbow `{{ template:section-line }}` divider between major sections.
Do not create a release.
Run the cheapest available verification before finishing.

Agent Decision Tree

Is this a fresh repo?
  yes -> use new-repository.md
  no  -> use existing-project.md

Did you read manifest.json?
  yes -> use copyMap and placeholders from it
  no  -> read it before editing

Is the working tree clean at task start?
  yes -> run a fast-forward update check such as git pull --ff-only before editing
  no  -> do not overwrite local changes; fetch or report the blocker before editing

Does a stack profile match?
  yes -> read the matching profiles/*.md file and adapt commands carefully
  no  -> continue with universal rules only

Can you answer the next question with targeted search or a small file slice?
  yes -> use that instead of loading whole directories or long logs
  no  -> read the smallest complete file set that preserves correctness

Does the project already have README structure?
  yes -> preserve it; only add blueprint files if useful
  no  -> add blueprint.md and blueprint.json with the rainbow section-line divider

Does the project produce artifacts?
  yes -> add downloads/artifacts section and release checklist
  no  -> keep downloads section minimal or remove it

Does the project have CI?
  yes -> patch existing workflow
  no  -> add .gitea/workflows/build.yml only when commands are known

Is the project releasable or does it process user/secrets/config data?
  yes -> add .gitea/workflows/security-scan.yml or preserve equivalent scheduled security automation
  no  -> document why scheduled security automation is not needed

Is this an active repository with generated files, artifacts, or branches?
  yes -> add .gitea/workflows/repo-cleanup.yml or preserve equivalent cleanup checks
  no  -> cleanup automation can be skipped

Is this an active project with dependencies?
  yes -> add .gitea/workflows/dependency-check.yml or preserve equivalent dependency checks
  no  -> dependency automation can be skipped

Is this project releasable?
  yes -> add .gitea/workflows/release-dry-run.yml or preserve equivalent release dry-run checks
  no  -> release dry-run can be skipped

Is this project intended to stay Codex-maintained?
  yes -> add .gitea/workflows/template-compliance.yml or preserve equivalent template checks
  no  -> template compliance can be skipped

Are commands unknown?
  yes -> document PENDING in .codex/project.md
  no  -> wire commands into AGENTS.md and CI

Did blueprint.md or blueprint.json change?
  yes -> regenerate or manually update README.md and check the rendered structure
  no  -> leave README.md alone unless content changed

Did release behavior, artifacts, or downloads change?
  yes -> update docs/release-checklist.md and README downloads/artifacts
  no  -> do not invent release details

Does the user expect a Gitea Package Registry package?
  yes -> add an explicit generic package upload step; upload-artifact alone is not enough
  no  -> workflow-run artifacts may be sufficient

Do package upload URLs include raw build filenames?
  yes -> copy artifacts to URL-safe filenames first, then upload those names
  no  -> continue

Do user-facing release artifacts include Codex kit metadata such as AGENTS.md, .codex/, blueprint files, template workflows, or agent handoff notes?
  yes -> exclude those files unless the user explicitly asked to ship repository-maintenance files
  no  -> continue

Is the work interrupted, risky, or multi-session?
  yes -> update docs/agent-handoff.md
  no  -> no handoff file is required

Did you find real follow-up work outside the current scope?
  yes -> create focused tracker issues for independent work; include impact, affected files, next steps, and verification
  no  -> do not create placeholder issues

Could the issue expose secrets, private data, or sensitive logs?
  yes -> do not put sensitive details in a public issue; summarize safely and keep details private or in handoff notes
  no  -> continue

Is this a private Gitea repo with Actions?
  yes -> if GITEA_TOKEN is set locally, use it for read-only API checks of repository and workflow-run status
  no  -> use public web/API checks when available

Did you push a commit that should trigger a workflow?
  yes -> poll the workflow run until success; if it fails, inspect logs, fix in scope, push again, and keep looping after the follow-up push
  no  -> finish with local verification status

Minimal File Set

For tiny projects:

AGENTS.md
.codex/project.md
README.md
SECURITY.md
CHANGELOG.md

For releasable projects:

AGENTS.md
.codex/project.md
README.md
SECURITY.md
CHANGELOG.md
docs/release-checklist.md
docs/security-review.md
docs/agent-handoff.md
.gitea/workflows/build.yml
.gitea/workflows/security-scan.yml
.gitea/workflows/repo-cleanup.yml
.gitea/workflows/dependency-check.yml
.gitea/workflows/release-dry-run.yml
.gitea/workflows/template-compliance.yml

For README-generator projects:

blueprint.md
blueprint.json
README.md

For stack-specific guidance:

profiles/node.md
profiles/electron.md
profiles/python.md
profiles/docker.md
profiles/static-site.md