holocron/docs/adr/0011-gitea-skill-deep-modules.md

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.

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.