anodyine/ai-training-skills

Fork 0

Files

T

admin bbfeac41de Publish training skills collection

2026-08-12 16:59:21 -04:00

12 KiB

Raw Blame History

name, description, metadata

name

description

metadata

gitea-issues

Read, create, draft, claim, implement from, label, comment on, and manage Gitea repositories, issues, pull requests, and epic-style dependency links using the Gitea API. Use when the user asks to create a Gitea repository, publish a local repo to Gitea, inspect an issue, summarize an issue, create an issue, publish issues to Gitea, draft Gitea work items, create epic cards, attach child issues, take the next ready issue from an epic, create a branch or PR for an issue, or update ready/in-progress/review/done issue status labels.

short-description
Work from Gitea issues

Gitea Issues

Use this skill to create repositories and to read, draft, create, claim, implement from, and update issues and pull requests in the user's Gitea repository.

Safety

Never ask the user to paste tokens in chat. Authentication must come from environment variables, the current git remote, or a local env file.

The helpers resolve configuration in this order:

Explicit environment variables.
The current repository's origin remote for GITEA_BASE_URL, GITEA_OWNER, and GITEA_REPO.
~/.config/gitea/gitea.env.
~/.config/secrets/gitea.env.
The legacy fallback ~/.config/gitea/data-analysis-agent.env.

A generic env file can look like:

export GITEA_BASE_URL="https://tea.example.com"
export GITEA_TOKEN="..."

Required values:

GITEA_BASE_URL
GITEA_OWNER or a Gitea origin remote
GITEA_REPO or a Gitea origin remote
GITEA_TOKEN

Creating pull requests requires a token with repository read/write scope. Issue-only tokens can read and label issues but cannot call the Gitea pulls API.

Creating repositories requires a token with repository creation permission.

Before creating an issue, draft the title, body, and labels and ask for confirmation unless the user explicitly says to create it without confirmation.

Create Repository

Use the bundled helper instead of hand-writing repository API calls:

python ~/.codex/skills/gitea-issues/scripts/create_repo.py \
  --owner anodyine \
  --name project-name \
  --description "Short repository description"

The helper reads environment variables first, then infers the owner from the current git remote or local env files, then falls back to the authenticated Gitea user. It returns the existing repository URL if the repo already exists.

When publishing a local directory, initialize Git locally, commit the current files, add the SSH remote returned by the user's Gitea host convention, and push the default branch after the repository exists.

Issue Format

Use this structure by default:

## Problem

## Scope

## Acceptance Criteria

Prefer this label vocabulary:

status/needs-triage
status/needs-info
status/ready-for-agent
status/ready-for-human
status/in-progress
status/review
status/done
status/wontfix
type/epic
type/feature
type/bug
type/refactor
type/docs
type/test
type/architecture
area/frontend
area/backend
area/docs
area/tests
area/agent-workflow
area/workflow

Create Issue

Use the bundled helper instead of hand-writing API calls:

python ~/.codex/skills/gitea-issues/scripts/create_issue.py \
  --title "Issue title" \
  --body-file /path/to/body.md \
  --label status/ready-for-agent \
  --label type/docs

The helper reads environment variables first, then infers repo identity from the current git remote, then falls back to the local env files. It fetches repository labels, maps label names to numeric IDs, creates the issue, and prints the issue URL.

If requested labels do not exist in Gitea, stop and tell the user which labels are missing. Do not create the issue with a silently incomplete label set.

Default to grouping implementation issues under an epic. Before creating new ready-for-agent work, either attach it to an existing focused epic or create a small epic for the related batch. Only create a standalone issue when the user explicitly asks for a one-off or no reasonable epic exists.

Read Issue

Use the bundled read helper instead of hand-parsing API JSON:

python ~/.codex/skills/gitea-issues/scripts/read_issue.py --issue 5

Include comments when needed:

python ~/.codex/skills/gitea-issues/scripts/read_issue.py --issue 5 --comments

The helper prints a compact Markdown summary with issue metadata, labels, body, dependencies/blockers, and optional comments. Prefer this when using an issue as task input for coding work.

Work the Next Ready Epic Issue

When asked to take the highest-priority ready task from an epic, treat labels as the agent-writeable source of truth. Gitea project columns are not available through this project's API. Use the epic body's ## Child Issues In Priority Order list for priority, and select the first open child with status/ready-for-agent.

Use the workflow helper to find and claim the issue:

python ~/.codex/skills/gitea-issues/scripts/issue_workflow.py next-ready \
  --epic 5 \
  --claim

This prints the selected issue and moves it from status/ready-for-agent to status/in-progress. Then:

Read the selected issue with comments.
Create a branch named exactly ISSUE-X, where X is the issue number.
Attach that branch to the issue ref using set-ref.
Implement the requested change, including relevant tests and modular docs.
Run the issue-relevant automated tests.
Commit with a concise, logical message.
Push the branch.
Create a Gitea pull request.
Comment on the issue with the PR link.
Move the issue to status/review, not status/done.
Switch the local checkout back to main so the next agent starts new work from main.

The human reviewer marks the issue status/done after review and merge.

YOLO Mode

Use YOLO mode only when the user explicitly asks for yolo/fully automated issue work or when a DAG/workflow parameter clearly enables it. The normal workflow above remains the default.

YOLO mode is for fast exploration where the agent should build, test, merge, delete the branch, and mark the issue done so the user can review the merged result later. It is appropriate for work the user has not yet deeply reviewed, prototypes, small follow-ups, and low-risk changes where post-merge review is acceptable.

In YOLO mode:

Claim the issue and move it to status/in-progress.
Create and attach the ISSUE-X branch as usual.
Implement the change, including relevant tests and docs.
Run the issue-relevant automated tests.
Commit and push the branch.
Create the pull request.
Merge the pull request immediately if it is mergeable.
Delete the merged branch unless the user asks to keep it.
Comment on the issue with the merged PR URL and verification summary.
Move the issue to status/done.

Never use YOLO mode for protected, ambiguous, security-sensitive, destructive, or high-risk work unless the user explicitly accepts that risk. If tests fail, the PR is not mergeable, or the implementation required major unplanned decisions, stop at the normal review state instead of merging.

After creating the PR, use the helper to merge and close the loop:

python ~/.codex/skills/gitea-issues/scripts/issue_workflow.py yolo-merge \
  --issue 6 \
  --pull 12

By default this uses a merge commit and asks Gitea to delete the PR branch after merge. To keep the branch:

python ~/.codex/skills/gitea-issues/scripts/issue_workflow.py yolo-merge \
  --issue 6 \
  --pull 12 \
  --no-delete-branch

Attach Branch or Tag Ref

After creating the issue branch, attach it to the issue so the Gitea sidebar does not show No Branch/Tag Specified:

python ~/.codex/skills/gitea-issues/scripts/issue_workflow.py set-ref \
  --issue 6 \
  --ref ISSUE-6

Use the exact branch name created for the issue. For the standard issue workflow, that branch is ISSUE-X, where X is the issue number.

Update Issue Status

Use this helper instead of hand-writing label API calls:

python ~/.codex/skills/gitea-issues/scripts/issue_workflow.py set-status \
  --issue 6 \
  --status status/review

The helper adds the requested status label and removes other status/* labels from the issue.

Create Pull Request and Link Issue

Write the PR body to a temporary Markdown file so shell quoting does not damage the requested format, then create the PR:

python ~/.codex/skills/gitea-issues/scripts/issue_workflow.py create-pr \
  --head ISSUE-6 \
  --base main \
  --title "Add reusable desktop UI test harness" \
  --body-file /tmp/pr-body.md

Use this PR body format when the user does not provide a different one:

What did you change?

Why did you change it this way rather than using a different strategy or pattern?

Pre-Test Setup:
```bash
git fetch origin
git switch ISSUE-6
git pull --ff-only origin ISSUE-6
cd path/to/relevant/app-or-package
```

Manual Test Plan:
- [ ] Run the relevant test command.

```bash
command-to-run
```

- [ ] Open the changed UI or workflow.
- [ ] Interact with the changed behavior step by step, such as navigating to links, clicking controls, choosing files, typing in fields, selecting options, and checking visible feedback.
- [ ] Confirm the expected result and note any visual or interaction issues.

Post-Merge Cleanup:
```bash
git switch main
git pull origin main
git branch -d ISSUE-6
git push origin --delete ISSUE-6
```

The Pre-Test Setup block should use the actual PR branch name and relevant package path so the reviewer can paste it into a terminal before running tests. The manual test plan should contain only the verification steps and expected checks required to test the change. Include automated test commands when they are relevant, but also include human UI or workflow steps when the reviewer needs to inspect behavior directly: opening links, clicking controls, choosing files, typing in fields, selecting options, and checking visible feedback or layout. Commands intended to be copied and run should be in fenced bash blocks, including commands in the manual test plan. The Post-Merge Cleanup block should use the actual PR branch name so the reviewer can paste it into a terminal after merging. After creating the PR, comment on the issue and move it to review:

python ~/.codex/skills/gitea-issues/scripts/issue_workflow.py comment \
  --issue 6 \
  --body "Implemented in PR: <pull-request-url>"

python ~/.codex/skills/gitea-issues/scripts/issue_workflow.py set-status \
  --issue 6 \
  --status status/review

Epic Issues

Gitea does not provide true nested epics in this project. Represent an epic as a normal issue plus dependency links:

Create an epic issue with type/epic when available, or type/architecture if the label does not exist yet.
List child issues in the epic body under ## Child Issues In Priority Order so agents can use next-ready --epic.
Attach each child issue as a dependency of the epic. Semantically, the epic is blocked until its child issues are complete.
Prefer one focused epic per delivery goal, such as "Frontend testing foundation".
When creating multiple follow-up issues, create the epic in the same turn and link the children before handing work to another agent.

Use the bundled dependency helper:

python ~/.codex/skills/gitea-issues/scripts/add_dependency.py \
  --parent 5 \
  --child 4

The parent is the blocked issue. The child is the issue it depends on.

Project boards are currently a manual UI step for this Gitea instance because its REST API does not expose project endpoints. Use labels and dependency links as the agent-writeable source of truth.

12 KiB Raw Blame History