Add follow-up issue guidance

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.