Defame1297
062ca47a18
A five-agent review of today's seven commits found no executable
regressions and no dangling references, but a set of documents still
asserting, in present tense, machinery that ADR-0024 and its commits
removed. This corrects them in place, keeping the original text as the
historical record wherever the repo's amendment convention applies.
LESSONS.md: the 2026-06-21 entry prescribed a `claude plugin validate`
sweep that now fails on every plugin, so it is marked superseded with
the surviving gates named. The 2026-08-09 entry gained a recurrence
note: today's manifest deletion broke apm's MCP propagation exactly as
that lesson describes, and its prescribed repo-local grep could not
have caught it, because `plugin_parser.py` ships in the apm toolchain
installed outside this repository.
ADR-0019, ADR-0011 and ADR-0021: amendments extended to passages the
earlier correction passes stepped over -- a dead native-consumer guard,
Consequences bullets still calling for a `plugins/gitea/.mcp.json` that
must not be recreated, and a drift-gate list naming a deleted script.
ADR-0021's list is down to one gate, not two: `apm audit --ci` never
read `description` and was never a drift gate.
architecture.md and enrichments.md: the self-containment constraint is
restated on its live source, the agentskills.io APM package-mode spec,
rather than on Claude Code's plugin cache-install, which ADR-0024
consequence 6 pins as a superseded rationale. releasing.md's pointer to
the deleted sync script is rewritten as history.
tests/run-bats.sh and scripts/lib/batch-run.sh: comment-only. The
`.claude/skills/` exclusion comment claimed a duplication that is not
live yet; apm does not strip `tests/`, and the deployed tree is empty
of them only because the lockfile still resolves the six dependencies
to a pre-ADR-0024 commit carrying the flat mirror. The exclusion is
correct but forward-looking, and now says so.
SIMPLIFICATION-AUDIT.md: reconciled against what the commits actually
did. Two closed findings recorded conclusions that ADR-0024 reversed
hours later; findings 1, 3, 31 and 35 carried prescriptions voided the
same day; finding 28 is now recorded as having moved backwards, with
docs/adr/ measured at +336 lines over the day. The section 1 headline
table is re-measured at a6434e0 and labelled with its basis. The
ADR-0012 contradiction between finding 2b and section 8 is resolved in
2b's favour after reading the ADR: only finding 24 is governed by it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YR2CjVumUbEGWcMikcoXBD
129 lines
9.1 KiB
Markdown
129 lines
9.1 KiB
Markdown
# 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/`.
|
|
|
|
**Correction (2026-09-14):** the three bullets above are historical — do not act on them. The
|
|
`.mcp.json` half is closed by the correction in Decision: `c96ca9c` deleted every
|
|
`plugins/*/.mcp.json`, including this plugin's, because apm reads that file only on the
|
|
marketplace-plugin code path that ADR-0024 removed. **Do not recreate `plugins/gitea/.mcp.json`**
|
|
— an MCP server a plugin needs is declared in `dependencies.mcp` in its `apm.yml`. The
|
|
standalone-installability caveat is moot for the same reason: `claude plugin install
|
|
gitea@holocron` is not a supported route. `plugins/bin/skills/gitea/` no longer exists either —
|
|
`3a1305c` (2026-07-23) removed it as superseded by `plugins/gitea`, the cleanup this bullet
|
|
anticipated — so the "remains in place" claim and its follow-up are both spent. Only the deferred
|
|
domains remain open.
|
|
- Future domain-plugin work in this repo can point to this ADR as the template for splitting an
|
|
MCP-wrapping skill into deep modules.
|