Clarify agent responsibilities

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.
+
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
 ## 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`.
+
+<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
+
+## 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.
+
 <p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
 
 ## Gitea API Token

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

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.
 

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",