---
name: manage-gitea-task
description: Create, update, or prepare Sendico Gitea tasks and implementation branches with the required body, metadata, branch naming, issue association, and verification. Use when Codex creates a Gitea issue or task, corrects its labels, assignee, or project, or begins code work that requires a task branch.
---

# Manage Gitea Task

## Establish scope

1. Read the repository root `AGENTS.md`.
2. Resolve the target owner and repository from authoritative repository
   context. Do not infer ambiguous values.
3. Determine whether the request only manages a task or also starts code work.
4. Before any tracker mutation, resolve the required existing labels, assignee,
   and project. Ask the user for any value that authoritative data cannot
   establish.

## Create or update the task

1. Use a concise, outcome-oriented title.
2. Write a self-contained body with these exact sections:

   - `### Goal`: state the concrete outcome, why it is needed, and its value.
   - `### Approach`: describe the intended direction, likely components, known
     constraints, and boundaries without inventing decisions.
   - `### Acceptance criteria`: provide a checklist of observable, testable
     completion outcomes, including relevant edge cases and validation.
   - `### Notes`: record contracts, compatibility, migrations, dependencies,
     rollout, configuration, security, observability, risks, open questions,
     exclusions, and authoritative links when relevant. Write
     `None identified` when no significant notes apply.

3. Prefer the configured Gitea connector for issue operations. If it cannot
   assign a project or attach a branch, use the authenticated Gitea REST API.
4. Resolve the project ID from authoritative Gitea data. If no project-list
   endpoint is available, inspect the `projects` fields on existing issues in
   the required project. Never infer an ID from its name.
5. When creating an issue through
   `POST /api/v1/repos/<owner>/<repo>/issues`, include `labels`, `assignees`, and
   `projects: [<project-id>]` in the request.
6. When correcting project assignment through
   `PATCH /api/v1/repos/<owner>/<repo>/issues/<number>`, send the complete
   intended `projects` list because it replaces the existing assignment.
7. Verify the response contains the intended project, labels, assignee, title,
   and body before proceeding.

Never print, log, store in repository files, or expose API tokens or Git
credentials.

## Prepare a code-change branch

Skip this section when the task does not require repository changes.

1. Resolve the numeric task number and the specific primary module before
   changing code.
2. Form the short branch name as `<module>-<task-number>` with a lowercase
   kebab-case module. Do not use `codex/`, `#`, task text, or an avoidably generic
   module name.
3. Create or select the branch only after the task exists.
4. Push the branch to the Gitea repository before changing repository files.
5. Attach the branch by setting the issue `ref` to the exact short name. Prefer
   the connector; otherwise send `{"ref": "<module>-<task-number>"}` through
   the issue PATCH endpoint.
6. Verify the response contains the exact short `ref` and the required project,
   labels, and assignee. Stop before code changes if any value is empty or
   mismatched.

## Report the result

Report the task number and URL, resolved metadata, and attached branch when
applicable. Identify any unresolved metadata or external blocker precisely; do
not claim the task is ready when verification did not succeed.