Add follow-up issue guidance

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 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.

README.md

@@ -150,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.
@@ -237,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

@@ -20,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.
@@ -137,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

@@ -146,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.

files/AGENTS.md

@@ -20,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.
@@ -81,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
-

manifest.json

@@ -1,6 +1,6 @@
 {
   "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.",
@@ -14,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.",

new-repository.md

@@ -188,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: