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

```text
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.
Treat global-runner-1, global-runner-2, and global-runner-3 as the only supported build runners.
Run project builds, tests, audits, package jobs, installers, dependency setup, and releases only on Gitea Ubuntu runners with ubuntu-latest, ubuntu-24.04, or ubuntu-22.04.
Never run those heavy project commands on the user's local machine.
Use open-source Linux-compatible workflow workarounds instead of adding Windows or macOS runners.
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 lightweight local validation before finishing, and run the cheapest reliable project verification through Gitea Actions or explain why runner verification could not run.
```

## New Repository Prompt

```text
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 lightweight local validation before finishing.
Use Gitea Ubuntu runners for project build, test, audit, package, and release commands.
```

## Existing Repository Prompt

```text
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 lightweight local validation before finishing.
Use Gitea Ubuntu runners for project build, test, audit, package, and release commands.
```

## Agent Decision Tree

```text
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

Does any workflow use Windows, macOS, local-machine builds, or unsupported runner labels?
  yes -> replace it with Gitea Ubuntu runner usage on ubuntu-latest, ubuntu-24.04, or ubuntu-22.04; if a platform-specific step is needed, implement a Linux-compatible workaround
  no  -> continue

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 lightweight local validation status and explain why runner verification was not required or not available
```

## Minimal File Set

For tiny projects:

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

For releasable projects:

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

```text
blueprint.md
blueprint.json
README.md
```

For stack-specific guidance:

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