# Gitea skill splits into deep modules under `plugins/gitea/`, replacing the flat `plugins/bin/skills/gitea/`

The gitea skill originated under kyberforge (`b9c73cc`), moved to `plugins/bin/skills/gitea/`
(`4f603cd`), and covers only 5 of gitea-mcp's ~15 tool domains (issues, labels, milestones, PRs,
branches) in one flat `SKILL.md` mixing routing logic with execution detail. Meanwhile
`plugins/gitea/` already existed as a plugin scaffold holding comprehensive research docs (all 55
MCP tool schemas, code-derived from gitea-mcp source, at
`plugins/gitea/docs/research/docs/gitea/`) but empty `skills/`, `agents/`, and `.mcp.json`. This
ADR records the decisions from a grill-with-docs session on issue #6 that splits the flat skill
into deep modules and relocates it to `plugins/gitea/`.

**Relocation.** The new deep-module skill structure is built in `plugins/gitea/`, not
`plugins/bin/`, making the gitea plugin self-contained — bundling its own skills, agents, and MCP
config — matching this repo's Plugin glossary definition (the deployable unit that bundles skills,
agents, hooks, and MCP servers into a single installable directory) and mirroring the existing
`plugins/git/` plugin's shape. The old flat skill stays at `plugins/bin/skills/gitea/` untouched
for now, kept as a reference/fallback — not deleted in this pass; removal is a future cleanup once
the new structure is validated in practice.

**Scope expansion.** Coverage expands beyond the original 5 domains to 3 new domains verified
working with the current token scope (`write:issue`, `write:repository`) per
`plugins/bin/skills/gitea/references/token-access.md`: Files (get/create/update/delete file, dir
contents, repo tree), Commits (list/get), and Releases & Tags (full CRUD). Domains not added:
repo/org listing, user identity, notifications, and packages are blocked by token scope
(`read:user`, `read:organization`, `read:notification`, `read:package`); Actions/CI (list_runs and
secrets return 403, writes untested) and Wiki (404 on this repo, writes untested) are partially
broken or unverified. All are deferred to future issues once scope is expanded or the domain is
verified safe elsewhere.

**Domain skill split.** The flat skill becomes 6 domain skills plus a workflow orchestrator and an
agent counterpart, composed per the Skill composition pattern:

- `gitea-issues` — issues only (list/read/write/search); closes out 4 enrichments deferred from
  issue #6 comment #848 — milestone assignment on create, assignee on create (documented
  workaround since `get_me`/`read:user` is blocked), dependency-linking convention ("Depends on
  #N" in body, since gitea-mcp has no native dependency field) — and delegates label inference to
  `gitea-labels-milestones`.
- `gitea-labels-milestones` — split out as its own shared skill since labels/milestones are
  cross-cutting (apply to both issues and PRs), rather than bundled under `gitea-issues`; owns the
  label inference guide (context-pattern → Kind/*/Priority/*/Status/* taxonomy mapping).
- `gitea-prs` — pull requests + reviews, composes `gitea-labels-milestones` for label/milestone
  application.
- `gitea-branches` — branches + commits bundled together (commits are read-only history within
  branches, a natural pairing).
- `gitea-files` — new domain.
- `gitea-releases` — releases + tags bundled together.
- `gitea-workflow` — thin human-facing orchestrator mirroring `git-workflow`
  (`plugins/git/skills/git-workflow/`). Preserves the original flat skill's default no-args status
  view (composes `gitea-issues` + `gitea-prs`) and routes ambiguous requests to the right domain
  skill. Named `gitea-workflow`, not bare `gitea`, for naming consistency with the other 6 skills,
  despite breaking the old `/gitea` invocation muscle memory — an explicit accepted tradeoff.
- `gitea-orchestrate` (agent, not skill) — agent-facing deterministic counterpart mirroring
  `git-orchestrate`, for multi-step composition when the caller is an agent rather than a human.

**Reference-file signature sourcing.** Each new skill's `references/*.md` restates verified MCP
call signatures cross-checked live via `ToolSearch` at authoring time, not copied from
`api-reference.md`, which could drift from the deployed MCP server version. This resolves issue #6
comment #849's root-cause question about the original `type` parameter bug, which happened
because the skill was authored from Gitea REST API docs instead of the actual MCP tool schema.
This is applied manually during this authoring pass; the `kyberforge:skill-author` meta-skill
itself is not changed — comment #849's "option 2" process fix is considered and explicitly
deferred as out of scope for this PR.

**MCP config deferred.** `plugins/gitea/.mcp.json` is deliberately left as an empty `mcpServers`
block — the real gitea-mcp server config continues to live in the user's `~/.claude.json` rather
than being wired into the plugin manifest. This means the gitea plugin is not yet installable
standalone via `claude plugin install gitea@holocron` without manual MCP setup. A follow-up Gitea
issue tracks closing this gap.

**Correction (2026-09-14):** this gap is now closed by removal rather than by wiring. ADR-0024
made apm the only supported install path, so `claude plugin install gitea@holocron` is no longer
a route this repo supports, and the per-plugin manifests it needed are gone. Because apm reads a
plugin-root `.mcp.json` only on the marketplace-plugin code path, that file became unreadable;
every `plugins/*/.mcp.json` was deleted, including this one. A plugin that needs an MCP server
declares it in `dependencies.mcp` in its `apm.yml` — the supported mechanism, which this repo has
never used. The follow-up issue this paragraph anticipates is moot.

**Research backfill.** The existing research docs
(`plugins/gitea/docs/research/docs/gitea/`) are 100% code-derived from gitea-mcp source with zero
external/best-practice content (the original docs.gitea.com fetch timed out and was never
retried). Context7 has `/websites/gitea` (official docs mirror) and `/git_gitea_com/gitea_tea` (Tea
CLI) available now — backfilled via a parallel research pass before skill-authoring, so the
Provenance chain (`source_keys` → `sources.md` → research doc) has real external sources for
workflow/convention guidance, not just API mechanics.

**Authoring route.** All 8 artifacts (7 skills + 1 agent) are authored via `kyberforge:forge`, not
direct `skill-author`/`agent-author` calls, even though `forge`'s own routing rule would normally
bypass itself here since the target artifact types are already known — chosen deliberately for
uniform audit/recheck coverage across every artifact.

## Considered options

**5-skill split, labels+milestones bundled under `gitea-issues` (rejected)** — simpler, one fewer
skill, but re-buries label/milestone logic inside an issues-specific skill even though PRs need it
equally, forcing `gitea-prs` to either duplicate the guide or reach into `gitea-issues`'
`references/` — breaking the self-contained skill boundary.

**8-skill split, one skill per raw API domain, no bundling (rejected)** — e.g. separate
`gitea-commits` and `gitea-tags` skills. Rejected as over-fragmentation: commits are read-only
history naturally scoped to branches, and tags are naturally scoped to releases, so bundling
avoids two near-empty skills each routing to a single tool family.

## Consequences

- `plugins/gitea/` gains `skills/gitea-issues/`, `skills/gitea-labels-milestones/`,
  `skills/gitea-prs/`, `skills/gitea-branches/`, `skills/gitea-files/`, `skills/gitea-releases/`,
  `skills/gitea-workflow/`, and `agents/gitea-orchestrate.md` (+ Copilot counterpart), each with
  its own `references/` and provenance records.
- `plugins/gitea/.mcp.json` stays an empty `mcpServers` block until the follow-up issue wires in
  the real gitea-mcp server config; the plugin is not standalone-installable until then.
- `plugins/bin/skills/gitea/` remains in place, unreferenced by new work, until a future cleanup
  issue removes it once the new structure is validated in practice.
- Follow-up issues are needed for: the deferred domains (Actions/CI, Wiki, Notifications,
  Packages, User/Org), the `.mcp.json` wiring gap, and the eventual removal of
  `plugins/bin/skills/gitea/`.
- Future domain-plugin work in this repo can point to this ADR as the template for splitting an
  MCP-wrapping skill into deep modules.