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

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

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

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

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

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

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