agents/README.md

# agents

Shared **AI dev-team** workflow for Gitea Actions, reusable across repos. It gives any repo the
`@pm` / `@intern` / `@junior` / `@senior` / `@lead` / `@qa` agents driven from issues and comments.

## Agents

| Agent | Model | Vision | Mode | Skills | Role |
|-------|-------|:------:|------|--------|------|
| `@pm` | `ollama-cloud/gemma4:cloud` | yes | comment | `gitea-api` | Product manager — research, plan, ask clarifying questions, and decide which dev should do the work. Comments only; never edits files. |
| `@intern` | `ornith:35b` | no | pr | — | Intern — very basic tasks only. Uses the local self-hosted Ollama model (`ornith:35b`). Text-only; cannot read images. Escalates anything non-trivial to `@junior`, `@senior`, or `@lead`. |
| `@junior` | `ollama-cloud/kimi-k2.7-code:cloud` | no | pr | — | Junior dev — small, low-risk changes (mostly YAML/compose/config). Text-only; cannot read images. Defers complex or image tasks to `@senior` or `@lead`. |
| `@senior` | `ollama-cloud/glm-5.2:cloud` | no | pr | `gitea-api`, `node1-ssh` | Senior dev — complex, multi-file implementation (GLM-5.2 via Ollama Cloud, text-only). |
| `@lead` | `anthropic/claude-opus-4-8` | yes | pr | `gitea-api`, `node1-ssh` | Tech lead — the hardest problems, architecture, and final calls. |
| `@qa` | `ollama-cloud/minimax-m3:cloud` | yes | comment | `gitea-api` | QA — verifies things work. Drives a headless browser (Playwright) to open a URL/web app, click through it, screenshot, and report bugs or confirm behavior. Comments findings; opens no PRs. |

`agent.yml`'s agent registry is the source of truth for this mapping — if you change a model
or an agent's skills there, update this table too.

### Per-agent skill scoping

Skills load **on-demand**: only a skill's one-line `description` ever appears in an agent's
`<available_skills>` list, and the full `SKILL.md` body (curl/API how-to) is fetched *only* when
the agent calls the `skill` tool — it is never baked into any system prompt. On top of that, each
agent's `skills` list in the registry drives an OpenCode `permission.skill` block that **denies all
skills by default and allows only the listed ones**. A denied skill is hidden entirely (its name and
description are omitted), so e.g. `@junior` never sees `gitea-api` — it just knows from the roster
that `@senior`/`@lead` can reach the Gitea API and asks them to. This keeps the "how it's done"
detail out of agents that shouldn't act on it while still letting them know the capability exists.

## Use it in a repo

**The standard caller is one file, identical in every repo.** Copy this repo's own
[`.gitea/workflows/ai-agent.yml`](.gitea/workflows/ai-agent.yml) verbatim into the consuming repo —
it is the source of truth, and `agents` itself uses the same file:

```yaml
name: ai-agent
run-name: "ai-agent · #${{ github.event.issue.number }}"   # quotes required: bare # starts a YAML comment
# Standard caller for the shared AI-agent workflow (ffaerber/agents). Copy this file VERBATIM into
# any repo that should get the agents — it is identical in every repo. All logic + scripts live in
# agents/.gitea/workflows/; scripts are fetched from @main at run time. The `jobs.agent` wrapper is
# required: a reusable (workflow_call) workflow can only be invoked from a caller job, not top-level.
# `run-name` titles each run by the triggering issue (e.g. "ai-agent · #42") in the Actions list.
on:
  issue_comment:
    types: [created]
  issues:
    types: [opened]
jobs:
  agent:
    uses: ffaerber/agents/.gitea/workflows/agent.yml@main
    secrets: inherit
```

That's the whole per-repo footprint, and it's the minimum a caller can be: the `on:` triggers must
live in each repo (a reusable workflow can't declare its callers' triggers) and the `jobs.agent`
wrapper is mandatory for `workflow_call`. Everything else (agent registry, routing, delegation,
reactions, PR/issue plumbing) lives here in `agent.yml`.

## Repo layout

`agent.yml` is kept thin: each step's shell lives in its own file under
`.gitea/workflows/scripts/` (`route.sh`, `install-opencode.sh`, `skill-node1-ssh.sh`,
`skill-gitea-api.sh`, `fetch-images.sh`, `fetch-thread.sh`, `run-agent.sh`,
`build-activity-log.sh`, `publish.sh`), invoked as `bash "$SCRIPTS/<name>.sh"`.

Because this is a **reusable** workflow (`workflow_call`), a caller run checks out the *caller's*
repo, not this one — so those script files aren't on disk by default. `agent.yml` therefore checks
this repo out into `.agents-workflow/` (pinned to `@main`, matching the caller's `uses: …@main`) and
points `$SCRIPTS` at it. Keep the workflow and its scripts moving together on `main`.

## Required secrets (per repo, or org-level for all)

| Secret | For |
|--------|-----|
| `ANTHROPIC_API_KEY` | `@lead` (and `@pm`/`@senior`/`@qa` if on Claude) |
| `OLLAMA_URL`, `OLLAMA_CLOUD_API_KEY` | local ornith / Ollama Cloud (gemma4, kimi-k2.7-code, glm-5.2, minimax-m3) |
| `AGENT_TOKEN` | PAT (issue/repository/organization/misc read+write, cross-repo) — posts the delegation comment that fires the next agent **and** powers the `gitea-api` skill (read/write issues, PRs, comments, labels, and Actions runs/logs across any repo). Do not re-narrow its scopes without also removing the `gitea-api` skill. |
| `TOKEN_PM`,`TOKEN_INTERN`,`TOKEN_SENIOR`,`TOKEN_JUNIOR`,`TOKEN_LEAD`,`TOKEN_QA` | optional — post/commit as each agent's own Gitea user (falls back to the bot) |

`GITEA_TOKEN` is auto-provided. Tip: set these once at the **org** level so every repo inherits
them via `secrets: inherit`.

## Also add to each consuming repo

- **`AGENTS.md`** — the repo's own conventions (copy `AGENTS.template.md` from here and adapt). The
  agent reads the *caller* repo's `AGENTS.md`, so each repo can differ.
- The bot users (`pm`,`senior`,…) as **collaborators** (needed on private repos, and enables
  `@name` autocomplete).

## Maintaining

Change agent behavior once, here. Callers pin `@main` (or pin a tag for stability). History is the
changelog — see `git log`.