From 947cc3a9ab4049b6574a87bdc5a3a93425dc6936 Mon Sep 17 00:00:00 2001 From: MrSphay Date: Sun, 3 May 2026 11:57:22 +0200 Subject: [PATCH] Clarify agent responsibilities --- README.md | 24 ++++++++++++++++++++++++ agent-quickstart.md | 29 +++++++++++++++++++++++++++++ files/AGENTS.md | 16 ++++++++++++++++ manifest.json | 14 ++++++++++++++ 4 files changed, 83 insertions(+) diff --git a/README.md b/README.md index a07af64..947db4a 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,8 @@ Start with `agent-quickstart.md` when using this kit through Codex. `manifest.json` contains the same copy map in a machine-readable format for agents. +Agents should read `manifest.json` before copying files. It is the source of truth for target paths, required files, optional files, and placeholder names. +

-----------------------------------------------------

## Placeholders @@ -96,6 +98,28 @@ AUDIT_COMMAND If a placeholder does not apply, remove it instead of inventing fake information. +Agents must not leave unresolved placeholders in copied files unless the value is genuinely unknown and marked as `PENDING`. + +

-----------------------------------------------------

+ +## Agent Responsibilities + +When applying this kit, an agent should: + +- read `manifest.json` first, +- choose `new-repository.md` or `existing-project.md`, +- check `git status --short` before editing, +- preserve unrelated user changes, +- use the manifest copy map for target paths, +- replace applicable placeholders, +- remove non-applicable placeholder sections, +- keep `AGENTS.md` and `.codex/project.md` aligned, +- update `README.md` whenever README blueprint files change, +- update security and release docs when release behavior changes, +- run `git diff --check` before finishing, +- run the cheapest reliable verification command, +- poll pushed Gitea workflow runs until success or a concrete blocker. +

-----------------------------------------------------

## Gitea API Token diff --git a/agent-quickstart.md b/agent-quickstart.md index 486d964..3db9b76 100644 --- a/agent-quickstart.md +++ b/agent-quickstart.md @@ -2,6 +2,21 @@ 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. +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 @@ -10,6 +25,7 @@ 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. @@ -24,6 +40,7 @@ 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. @@ -36,6 +53,10 @@ 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 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 @@ -52,6 +73,14 @@ 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 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 diff --git a/files/AGENTS.md b/files/AGENTS.md index 11f652d..3584297 100644 --- a/files/AGENTS.md +++ b/files/AGENTS.md @@ -6,14 +6,19 @@ PROJECT_NAME: PROJECT_DESCRIPTION ## Repository Rules +- Start by reading `manifest.json`, then the workflow file that matches the task: `new-repository.md` for fresh repos or `existing-project.md` for retrofit work. +- Follow the `manifest.json` copy map for source and target paths. Do not invent alternate locations unless the target repository already has an equivalent convention. - Prefer existing project patterns over new abstractions. - Keep changes scoped to the user's request. - Do not commit secrets, `.env` files, private keys, certificates, or tokens. - Do not rewrite history or run destructive git commands unless explicitly requested. - Do not create a release unless explicitly requested. +- Check `git status --short` before editing and before finishing. Preserve unrelated user changes. +- Replace all applicable placeholders. Remove non-applicable placeholder sections instead of leaving fake values. - If `GITEA_TOKEN` is available locally, use it only for read-only Gitea API checks such as private repository metadata, package-read visibility, and Actions run status. Never print, commit, or store the token. - After pushing commits that trigger a Gitea workflow, poll the workflow run until it succeeds. If it fails or is cancelled, inspect the failing job/logs, fix the issue when in scope, push again, and repeat the workflow check loop. Fixing and pushing a workflow failure is not a stopping point. - When the project uses `blueprint.md` and `blueprint.json` for README generation, keep the rainbow `{{ template:section-line }}` divider between major README sections. Do not replace it with plain `---` unless the target renderer cannot display inline images. +- If README blueprint files are changed, regenerate or update `README.md` in the same change and verify the generated output renders reasonably. ## Commands @@ -28,6 +33,8 @@ AUDIT_COMMAND If a command is missing, inspect the project and document the closest safe alternative in `.codex/project.md`. +Keep `.codex/project.md` and this `AGENTS.md` aligned when commands, artifact paths, or release rules change. + ## Artifacts Expected artifact output: @@ -45,8 +52,17 @@ ARTIFACT_NAME ## Security Notes - Review `docs/security-review.md` before release work. +- Fill `docs/security-review.md` with actual checked commands and results when performing release-readiness work. - Treat generated credentials and config files as sensitive. - Keep external network calls documented. - Prefer local processing for user data. - Keep CI publishing secrets in repository or organization secrets, not in tracked files. `REGISTRY_TOKEN` is the default package publishing secret name for the Gitea workflow template. +- Ensure `.gitignore` covers local config, build outputs, logs, temporary files, and secret material for the detected stack. + +## Finish Checklist + +- `git diff --check` passes. +- The cheapest reliable verification command has been run, or the reason it could not be run is documented. +- README, changelog, security review, and release checklist are updated when the change touches release behavior. +- Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported. diff --git a/manifest.json b/manifest.json index 0636ec8..3c92a7f 100644 --- a/manifest.json +++ b/manifest.json @@ -2,6 +2,20 @@ "name": "codex-agent-repository-kit", "version": "1.0.0", "description": "Universal repository baseline for Codex-assisted projects.", + "agentResponsibilities": [ + "Read manifest.json before copying files.", + "Use copyMap target paths unless the repository already has an equivalent convention.", + "Check git status before editing and before finishing.", + "Preserve unrelated user changes.", + "Replace 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.", + "Update docs/security-review.md during release-readiness work.", + "Update docs/release-checklist.md when release behavior changes.", + "Run git diff --check before finishing.", + "Run the cheapest reliable verification command or document why it could not run.", + "After pushing workflow-triggering commits, poll Gitea workflow runs until success or a concrete blocker." + ], "readmeDivider": { "templateName": "section-line", "source": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png",