Add follow-up issue guidance

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to the Codex Agent Repository Kit are documented here.
+
+## 1.0.1 - 2026-05-15
+
+- Added agent guidance to create focused tracker issues for actionable follow-up work that is outside the current scope or independently parallelizable.
+- Added safeguards against creating vague, duplicate, or sensitive public issues.
+- Updated handoff guidance to use `docs/agent-handoff.md` when no issue tracker is available or the details are too sensitive for public issues.
+
+## 1.0.0 - 2026-05-15
+
+- Added universal repository baseline templates for Codex-assisted projects.
+- Added agent quickstart, new repository, and existing project workflows.
+- Added optional Gitea workflow templates for build, security scanning, cleanup, dependency checks, release dry runs, and template compliance.
+- Added stack profiles for Node, Electron, Python, Docker, and static sites.
+- Added guidance for dynamic repository owners, safe task-start syncs, release artifact exclusions, and context token conservation.
+- Removed hard-coded private Gitea instance URLs from reusable templates.

README.md

@@ -2,7 +2,7 @@
 
 Reusable baseline files for repositories that should be easy for Codex agents to inspect, modify, build, review, and release.
 
-The kit has two modes:
+The kit has three entry points:
 
 - `agent-quickstart.md`: shortest prompts and decision tree for Codex agents.
 - `new-repository.md`: agent workflow for a fresh repository.
@@ -106,10 +106,19 @@ ARTIFACT_OUTPUT_DIRECTORY
 AUTHOR_NAME
 PROJECT_STACK
 DOWNLOAD_URL
+CI_URL
+RELEASES_URL
+GITEA_SERVER_URL
 BUILD_COMMAND
 TEST_COMMAND
 LINT_COMMAND
 AUDIT_COMMAND
+README_COMMAND
+INSTALL_COMMAND
+DEV_COMMAND
+PACKAGE_MANAGER
+PROJECT_VERSION
+COMMIT_OR_VERSION
 ```
 
 If a placeholder does not apply, remove it instead of inventing fake information.
@@ -127,6 +136,7 @@ When applying this kit, an agent should:
 - read `manifest.json` first,
 - choose `new-repository.md` or `existing-project.md`,
 - read matching `profiles/*.md` guidance after detecting the stack,
+- conserve context tokens by searching first, reading only relevant files, summarizing large outputs, and avoiding 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,
 - check `git status --short` before editing,
 - preserve unrelated user changes,
@@ -140,6 +150,7 @@ When applying this kit, an agent should:
 - add or preserve scheduled repository cleanup checks for active projects,
 - add dependency, release dry-run, and template compliance checks when they fit the project,
 - update `docs/agent-handoff.md` when work is interrupted, risky, or multi-session,
+- create focused tracker issues for real follow-up work that is outside the current scope or independently parallelizable, using `docs/agent-handoff.md` when no issue tracker is available,
 - run `git diff --check` before finishing,
 - run the cheapest reliable verification command,
 - poll pushed Gitea workflow runs until success or a concrete blocker.
@@ -208,14 +219,14 @@ It verifies required agent context files, unresolved placeholders, README divide
 
 ## 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.
+When working with private Gitea repositories, Codex agents may find a local `GITEA_TOKEN` environment variable on the machine.
 
 Use `GITEA_TOKEN` only for read-oriented Gitea API checks unless the user explicitly asks for a write action. Typical safe checks include repository metadata, workflow run status, and package-read visibility. Never print the token, commit it, or copy it into workflow files.
 
 Example status endpoint:
 
 ```text
-GET https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
+GET GITEA_SERVER_URL/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/actions/runs
 Authorization: token GITEA_TOKEN
 ```
 
@@ -227,6 +238,22 @@ Authorization: token GITEA_TOKEN
 
 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.
 
+## Follow-up Issues
+
+When an agent finds real follow-up work that is outside the current scope or can be worked on independently, it should create a focused tracker issue so humans or other agents can pick it up later or in parallel.
+
+Create issues only for actionable work. Do not create issues for work the agent can safely complete in the current task, duplicate issues, vague reminders, or placeholder TODOs.
+
+Each issue should include:
+
+- observed problem,
+- impact or reason it matters,
+- affected files, commands, or workflows,
+- suggested next steps,
+- verification already performed.
+
+Never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md` instead.
+
 ## Gitea Artifacts And Packages
 
 Actions artifacts and Gitea packages are separate storage paths.

agent-quickstart.md

@@ -9,6 +9,7 @@ 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.
@@ -19,6 +20,7 @@ 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.
@@ -72,6 +74,10 @@ 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
@@ -132,6 +138,14 @@ 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

docs/agent-handoff.md

@@ -0,0 +1,37 @@
+# Agent Handoff
+
+Use this file for current repository follow-ups when tracker issues cannot be created.
+
+## Current State
+
+The kit now includes guidance for creating focused tracker issues for actionable follow-up work.
+
+## Changes Made
+
+- Added issue creation guidance to the agent rules, quickstart, README, new/existing repository workflows, and manifest.
+- Added handoff guidance for cases where issue creation is unavailable or too sensitive.
+- Updated the kit version to `1.0.1`.
+
+## Verification
+
+| Check | Result |
+| --- | --- |
+| Issue creation test | Blocked: Gitea API returned `invalid username, password or token` |
+
+## Open Questions
+
+- Whether the local `GITEA_TOKEN` should be refreshed for future issue/release automation.
+
+## Next Steps
+
+- Create a focused tracker issue for adding a reusable follow-up issue template once issue API access is available.
+
+## Follow-up Issues
+
+| Issue | Status |
+| --- | --- |
+| Add reusable issue template for agent follow-ups | Pending issue tracker access |
+
+## Risks
+
+- Issue automation cannot be fully validated until a valid token is available.

existing-project.md

@@ -33,6 +33,8 @@ git pull --ff-only
 
 If local changes exist, do not overwrite them. Fetch or report the blocker before editing.
 
+Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the retrofit decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
+
 Read:
 
 ```text
@@ -144,6 +146,8 @@ For releasable projects, add `.gitea/workflows/release-dry-run.yml` unless equiv
 
 For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml` unless equivalent agent-context checks already exist. Preserve documented project-specific exceptions.
 
+When retrofit work reveals real follow-up work that is outside the current scope or can be worked on independently, create focused tracker issues so humans or other agents can pick them up later or in parallel. Each issue should include the observed problem, impact, affected files or commands, suggested next steps, and verification already performed. Do not create issues for work you can safely finish in the current task, and never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md`.
+
 ### 6. Security Review
 
 Fill `docs/security-review.md` with known facts.
@@ -177,7 +181,7 @@ Before final response:
 
 - run `git diff --check`,
 - run the smallest reliable verification command,
-- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
+- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories, use a locally set `GITEA_TOKEN` and `GITEA_SERVER_URL` for read-only API status checks when available,
 - if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
 - list files changed,
 - mention any skipped checks,

files/AGENTS.md

@@ -8,6 +8,7 @@ PROJECT_NAME: PROJECT_DESCRIPTION
 
 - 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.
 - Use the matching `profiles/*.md` file when the repository stack is detected. Profiles are guidance, not permission to ignore existing project conventions.
+- Conserve context tokens: search with `rg` or targeted file lists first, read only the files needed for the task, summarize large outputs instead of pasting them, and avoid loading generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
 - 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.
@@ -19,6 +20,8 @@ PROJECT_NAME: PROJECT_DESCRIPTION
 - Replace all applicable placeholders. Remove non-applicable placeholder sections instead of leaving fake values.
 - Derive `REPOSITORY_OWNER` and `REPOSITORY_NAME` from the target repository remote or `GITHUB_REPOSITORY`. Never reuse the owner from this template repository.
 - 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.
+- When you find a real, actionable follow-up that is outside the current scope or can be worked on independently, create a tracker issue so humans or other agents can pick it up later or in parallel. Do not create issues for work you can safely finish in the current task. If no issue tracker is available, update `docs/agent-handoff.md` instead.
+- Keep issues scoped and actionable: include the observed problem, impact, affected files or commands, suggested next steps, and any verification already performed. Never include secrets, tokens, private data, or sensitive logs in public issues.
 - 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.
@@ -80,5 +83,6 @@ ARTIFACT_NAME
 - 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.
 - `docs/agent-handoff.md` is updated when work is interrupted, risky, or spans multiple sessions.
+- Independent follow-up work has tracker issues, or `docs/agent-handoff.md` explains why issues could not be created.
 - Any pushed Gitea workflow has been polled to success or a concrete blocker has been reported.
 

files/CONTRIBUTING.md

@@ -7,6 +7,7 @@
 - Do not commit secrets, generated credentials, local `.env` files, or private keys.
 - Do not create releases unless explicitly requested.
 - Preserve unrelated user changes.
+- Create focused issues for real follow-up work that is outside the current change or can be worked on independently. Do not put secrets, tokens, private data, or sensitive logs in public issues.
 
 ## Before Committing
 
@@ -45,4 +46,3 @@ docs/release-checklist.md
 docs/security-review.md
 README.md
 ```
-

files/agent-handoff.md

@@ -2,6 +2,8 @@
 
 Use this file when a task spans multiple sessions, has unresolved follow-up work, or changes release behavior.
 
+Prefer focused tracker issues for independent follow-up work when an issue tracker is available. Use this handoff file when issues cannot be created, when the context is too sensitive for a public issue, or when a task needs a compact session summary.
+
 ## Current State
 
 ```text
@@ -29,7 +31,12 @@ PENDING
 
 - PENDING
 
+## Follow-up Issues
+
+| Issue | Status |
+| --- | --- |
+| PENDING | PENDING |
+
 ## Risks
 
 - PENDING
-

files/blueprint.json

@@ -6,12 +6,12 @@
     {
       "alt": "Build",
       "img": "https://img.shields.io/badge/build-Gitea%20Runner-2563eb",
-      "url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/actions"
+      "url": "CI_URL"
     },
     {
       "alt": "Version",
       "img": "https://img.shields.io/badge/version-0.1.0-111827",
-      "url": "https://git.wilkensxl.de/REPOSITORY_OWNER/REPOSITORY_NAME/releases"
+      "url": "RELEASES_URL"
     }
   ],
   "headingPrefix": {
@@ -27,4 +27,3 @@
   ],
   "text": "PROJECT_DESCRIPTION"
 }
-

files/build-gitea.yml

@@ -58,7 +58,7 @@ jobs:
           if [ -z "${repository_owner}" ] || [ "${repository_owner}" = "${GITHUB_REPOSITORY}" ]; then
             repository_owner="REPOSITORY_OWNER"
           fi
-          gitea_server="${GITHUB_SERVER_URL:-https://git.wilkensxl.de}"
+          gitea_server="${GITHUB_SERVER_URL:-GITEA_SERVER_URL}"
           gitea_server="${gitea_server%/}"
           package_dir="package-registry"
           latest_url="${gitea_server}/api/packages/${repository_owner}/generic/${package_name}/latest"

files/release-dry-run-gitea.yml

@@ -33,8 +33,8 @@ jobs:
             fi
           done
 
-          placeholder_paths=(README.md AGENTS.md .codex docs)
-          placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND'
+          placeholder_paths=(README.md AGENTS.md .codex docs .gitea)
+          placeholder_pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|DOWNLOAD_URL|CI_URL|RELEASES_URL|GITEA_SERVER_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|COMMIT_OR_VERSION'
 
           for path in "${placeholder_paths[@]}"; do
             [ -e "$path" ] || continue

files/template-compliance-gitea.yml

@@ -53,8 +53,8 @@ jobs:
         shell: bash
         run: |
           found=0
-          paths=(AGENTS.md README.md SECURITY.md CHANGELOG.md .codex docs blueprint.md blueprint.json)
-          pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|AUTHOR_NAME|PROJECT_STACK|DOWNLOAD_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|README_COMMAND|INSTALL_COMMAND|DEV_COMMAND|PACKAGE_MANAGER|PROJECT_VERSION'
+          paths=(AGENTS.md README.md SECURITY.md CHANGELOG.md .codex docs .gitea blueprint.md blueprint.json)
+          pattern='PROJECT_NAME|PROJECT_DESCRIPTION|REPOSITORY_OWNER|REPOSITORY_NAME|PACKAGE_NAME|ARTIFACT_NAME|ARTIFACT_OUTPUT_DIRECTORY|AUTHOR_NAME|PROJECT_STACK|DOWNLOAD_URL|CI_URL|RELEASES_URL|GITEA_SERVER_URL|BUILD_COMMAND|TEST_COMMAND|LINT_COMMAND|AUDIT_COMMAND|README_COMMAND|INSTALL_COMMAND|DEV_COMMAND|PACKAGE_MANAGER|PROJECT_VERSION|COMMIT_OR_VERSION'
 
           for path in "${paths[@]}"; do
             [ -e "$path" ] || continue

manifest.json

@@ -1,10 +1,11 @@
 {
   "name": "codex-agent-repository-kit",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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.",
+    "Conserve context tokens by searching first, reading only relevant files, summarizing large outputs, and avoiding 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.",
     "Check git status before editing and before finishing.",
     "Preserve unrelated user changes.",
@@ -13,6 +14,7 @@
     "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.",
+    "Create focused tracker issues for real follow-up work that is outside the current scope or independently parallelizable, and use docs/agent-handoff.md when no issue tracker is available.",
     "Add or preserve non-destructive scheduled repository cleanup checks for active projects.",
     "Add or preserve dependency, release dry-run, and template compliance checks when they fit the project.",
     "Run git diff --check before finishing.",
@@ -191,6 +193,9 @@
     "AUTHOR_NAME",
     "PROJECT_STACK",
     "DOWNLOAD_URL",
+    "CI_URL",
+    "RELEASES_URL",
+    "GITEA_SERVER_URL",
     "BUILD_COMMAND",
     "TEST_COMMAND",
     "LINT_COMMAND",
@@ -199,7 +204,8 @@
     "INSTALL_COMMAND",
     "DEV_COMMAND",
     "PACKAGE_MANAGER",
-    "PROJECT_VERSION"
+    "PROJECT_VERSION",
+    "COMMIT_OR_VERSION"
   ],
   "profiles": [
     {

new-repository.md

@@ -30,6 +30,8 @@ git pull --ff-only
 
 If local changes exist, do not overwrite them. Fetch or report the blocker before editing.
 
+Conserve context tokens while inspecting: start with targeted searches and file lists, then read only files that affect the baseline decision. Do not load generated folders, dependency folders, build outputs, or full logs unless they are directly relevant.
+
 Identify:
 
 - repository name,
@@ -91,6 +93,9 @@ ARTIFACT_OUTPUT_DIRECTORY
 AUTHOR_NAME
 PROJECT_STACK
 DOWNLOAD_URL
+CI_URL
+RELEASES_URL
+GITEA_SERVER_URL
 BUILD_COMMAND
 TEST_COMMAND
 LINT_COMMAND
@@ -183,6 +188,8 @@ For releasable projects, add `.gitea/workflows/release-dry-run.yml`. It should v
 
 For Codex-maintained projects, add `.gitea/workflows/template-compliance.yml`. It should verify agent context and template hygiene without overwriting project-specific conventions.
 
+When the setup reveals real follow-up work that is outside the current scope or can be worked on independently, create focused tracker issues so humans or other agents can pick them up later or in parallel. Each issue should include the observed problem, impact, affected files or commands, suggested next steps, and verification already performed. Do not create issues for work you can safely finish in the current task, and never include secrets, tokens, private data, or sensitive logs in public issues. If no issue tracker is available, record the follow-up in `docs/agent-handoff.md`.
+
 ### 7. Finish
 
 Before final response:
@@ -190,7 +197,7 @@ Before final response:
 - run formatting or validation if available,
 - run the cheapest reliable verification command,
 - check `git diff --check`,
-- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private `git.wilkensxl.de` repositories, use a locally set `GITEA_TOKEN` for read-only API status checks when available,
+- if using Gitea Actions, poll the pushed workflow run until it reaches a terminal state; for private Gitea repositories, use a locally set `GITEA_TOKEN` and `GITEA_SERVER_URL` for read-only API status checks when available,
 - if the pushed workflow fails or is cancelled, inspect the failing job/logs, fix in scope, push again, and repeat the workflow check loop; fixing and pushing is not a stopping point,
 - summarize changed files,
 - do not create a release unless explicitly requested.