generated from MrSphay/codex-agent-repository-kit
Initial commit
This commit is contained in:
206
agent-quickstart.md
Normal file
206
agent-quickstart.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# 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.
|
||||
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
|
||||
|
||||
```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
|
||||
|
||||
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:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user