diff --git a/README.md b/README.md index 7d8d3c4..a07af64 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,22 @@ The kit has two modes: The files are intentionally universal. They do not assume Electron, React, Node, or any single stack. Node examples are included only because many Codex projects use them. +

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

+ +## README Section Divider + +Generated README files should use the shared rainbow section divider between major sections. + +The divider is configured in `files/blueprint.json` as the `section-line` template: + +```md +{{ template:section-line }} +``` + +When a project uses the README blueprint workflow, keep this divider in `blueprint.md` between major sections. Do not replace it with plain `---` unless the target platform cannot render inline images. + +

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

+ ## Agent Goal Give every repository the same predictable anchor points: @@ -35,6 +51,8 @@ Give every repository the same predictable anchor points: Use only the files that fit the project. For a tiny script repo, `AGENTS.md`, `README.md`, `SECURITY.md`, and `CHANGELOG.md` may be enough. For an app or releasable tool, add the runner, release checklist, and README blueprint workflow. +

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

+ ## Copy Map | Template | Destination | @@ -53,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. +

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

+ ## Placeholders Replace these after copying: @@ -76,6 +96,8 @@ AUDIT_COMMAND If a placeholder does not apply, remove it instead of inventing fake information. +

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

+ ## Gitea API Token When working with private repositories on `git.wilkensxl.de`, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine. @@ -91,10 +113,14 @@ Authorization: token GITEA_TOKEN `REGISTRY_TOKEN` is still the intended secret name for CI package publishing inside `.gitea/workflows/build.yml`. +

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

+ ## Gitea Workflow Loop After pushing commits that trigger a Gitea workflow, Codex agents must keep checking the resulting workflow run before finishing. Poll the run until it reaches a terminal state. If it succeeds, report the successful run. If it fails or is cancelled, inspect the failing job/logs, fix the issue when it is in scope, commit, push, and repeat the check loop for the next run. A fixed failure is not a stopping point; the loop continues after the follow-up push until a workflow succeeds or a concrete out-of-scope blocker is reached. Do not stop after a single in-progress status when the user asked the agent to continue the loop. +

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

+ ## Agent Prompt For A New Repo ```text @@ -105,6 +131,8 @@ Keep the existing stack choices minimal and do not add unnecessary frameworks. Do not create a release. ``` +

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

+ ## Agent Prompt For An Existing Repo ```text diff --git a/agent-quickstart.md b/agent-quickstart.md index 5b45cdb..486d964 100644 --- a/agent-quickstart.md +++ b/agent-quickstart.md @@ -11,6 +11,7 @@ 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. 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. ``` @@ -23,6 +24,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. +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,7 +38,7 @@ Is this a fresh repo? Does the project already have README structure? yes -> preserve it; only add blueprint files if useful - no -> add blueprint.md and blueprint.json + 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 diff --git a/existing-project.md b/existing-project.md index e4f4643..973a0a3 100644 --- a/existing-project.md +++ b/existing-project.md @@ -93,9 +93,12 @@ If converting: 1. Copy the current README content into `blueprint.md`. 2. Add `blueprint.json`. -3. Add a `readme` command. -4. Generate `README.md`. -5. Compare the diff carefully. +3. Keep or add `{{ template:section-line }}` between major README sections. +4. Add a `readme` command. +5. Generate `README.md`. +6. Compare the diff carefully. + +The default section divider is the rainbow line from `andreasbm/readme`, configured in `blueprint.json` as `section-line`. Agents should keep it enabled when the project uses generated README files. ### 5. CI Retrofit diff --git a/files/AGENTS.md b/files/AGENTS.md index 5c4e059..11f652d 100644 --- a/files/AGENTS.md +++ b/files/AGENTS.md @@ -13,6 +13,7 @@ PROJECT_NAME: PROJECT_DESCRIPTION - Do not create a release unless explicitly requested. - 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. ## Commands diff --git a/manifest.json b/manifest.json index 6c09979..0636ec8 100644 --- a/manifest.json +++ b/manifest.json @@ -2,6 +2,11 @@ "name": "codex-agent-repository-kit", "version": "1.0.0", "description": "Universal repository baseline for Codex-assisted projects.", + "readmeDivider": { + "templateName": "section-line", + "source": "https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png", + "usage": "Keep {{ template:section-line }} between major sections in generated README files." + }, "workflows": { "newRepository": "new-repository.md", "existingProject": "existing-project.md", @@ -76,4 +81,3 @@ "PROJECT_VERSION" ] } - diff --git a/new-repository.md b/new-repository.md index f09d44d..710dbd5 100644 --- a/new-repository.md +++ b/new-repository.md @@ -114,9 +114,12 @@ If using the generator: 1. Fill `blueprint.md`. 2. Fill `blueprint.json`. -3. Add a `readme` command. -4. Generate `README.md`. -5. Commit `README.md`, `blueprint.md`, and `blueprint.json`. +3. Keep `{{ template:section-line }}` between major README sections. +4. Add a `readme` command. +5. Generate `README.md`. +6. Commit `README.md`, `blueprint.md`, and `blueprint.json`. + +The default section divider is the rainbow line from `andreasbm/readme`, configured in `blueprint.json` as `section-line`. Agents should keep it enabled for generated README files. If not using the generator, keep a manual README with the same main sections: