217 lines
9.0 KiB
Markdown
217 lines
9.0 KiB
Markdown
# 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
|
|
```
|
|
|