158 lines
5.0 KiB
Markdown
158 lines
5.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.
|
|
For releasable projects, add or preserve scheduled security automation.
|
|
For active projects, add or preserve non-destructive scheduled repository cleanup checks.
|
|
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
|
|
|
|
```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 the cheapest available verification before finishing.
|
|
```
|
|
|
|
## 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 the cheapest available verification before finishing.
|
|
```
|
|
|
|
## 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
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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:
|
|
|
|
```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
|
|
```
|
|
|
|
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
|
|
```
|
|
|