From 0d2a6cd83916290ca5e83b63296d89f11152934c Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 5 Jul 2026 10:23:34 +0000 Subject: [PATCH] docs(adr): record gitea plugin deep-module redesign decision Captures the grill-with-docs session for issue #6: relocate gitea skill from plugins/bin/ to plugins/gitea/, split into 6 domain skills plus a workflow orchestrator and orchestrate agent, expand scope to 3 token-verified new domains, and resolve the schema-verification question from comment #849. --- docs/adr/0011-gitea-skill-deep-modules.md | 109 ++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 docs/adr/0011-gitea-skill-deep-modules.md diff --git a/docs/adr/0011-gitea-skill-deep-modules.md b/docs/adr/0011-gitea-skill-deep-modules.md new file mode 100644 index 0000000..971cc35 --- /dev/null +++ b/docs/adr/0011-gitea-skill-deep-modules.md @@ -0,0 +1,109 @@ +# 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.