Defame1297/holocron
0
0
Fork 0
Code Issues 14 Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(kyberforge/gitea): deep modules — move how into reference files, SKILL.md becomes orchestrator #6

New Issue
Closed
opened 2026-06-25 18:46:07 +00:00 by Claude · 3 comments
Claude commented 2026-06-25 18:46:07 +00:00
Collaborator
Copy Link

Context

The kyberforge:gitea dispatch skill currently encodes both routing logic (when/why) and execution detail (how — parameter schemas, call flows, error recovery) in a single SKILL.md. This works for v1 but doesn't scale as the dispatch table grows or new repos/flows are added.

## Context The `kyberforge:gitea` dispatch skill currently encodes both routing logic (when/why) and execution detail (how — parameter schemas, call flows, error recovery) in a single `SKILL.md`. This works for v1 but doesn't scale as the dispatch table grows or new repos/flows are added.
Claude commented 2026-06-25 18:49:46 +00:00
Author
Collaborator
Copy Link

Gaps deferred to deep modules refactor

The following issue-create enrichments were identified during live testing but are deferred to this refactor:

Milestone assignment on create — after inferring labels, check milestone_read method: "list" for open milestones and assign if one clearly fits the issue scope. Requires milestone ID (not title) in the issue_write call.

Assignee on create — derive from git config user.name or leave unset. Gitea issue_write method: "create" accepts assignees: [<login>] but login cannot be discovered without read:user scope (get_me is blocked). Workaround: let user configure a default assignee login or leave unset.

Dependency linking — Gitea has no native dependency field in the MCP surface. Reference related issues in the body during create (e.g. Depends on #N) rather than via a separate API call. Document the convention

Label inference quality — the current fix infers labels from context signals. include a label inference guide: mapping between common context patterns and the Kind/* / Priority/* / Status/* taxonomy used in this repo.

## Gaps deferred to deep modules refactor The following issue-create enrichments were identified during live testing but are deferred to this refactor: **Milestone assignment on create** — after inferring labels, check `milestone_read method: "list"` for open milestones and assign if one clearly fits the issue scope. Requires milestone ID (not title) in the `issue_write` call. **Assignee on create** — derive from `git config user.name` or leave unset. Gitea `issue_write method: "create"` accepts `assignees: [<login>]` but login cannot be discovered without `read:user` scope (`get_me` is blocked). Workaround: let user configure a default assignee login or leave unset. **Dependency linking** — Gitea has no native dependency field in the MCP surface. Reference related issues in the body during create (e.g. `Depends on #N`) rather than via a separate API call. Document the convention **Label inference quality** — the current fix infers labels from context signals. include a label inference guide: mapping between common context patterns and the `Kind/*` / `Priority/*` / `Status/*` taxonomy used in this repo.
Claude commented 2026-06-25 18:57:01 +00:00
Author
Collaborator
Copy Link

Root cause of the type filter bug — MCP schema vs API spec drift

The Status section bug (calling list_issues with a non-existent type parameter) was caused by the skill being authored from Gitea REST API documentation rather than verified against the actual MCP tool schemas.

The MCP layer (gitea-mcp) wraps the REST API but deliberately slims it — parameters are omitted, response shapes are reduced, some API endpoints are combined into a single tool. The type filter exists in the Gitea REST API (GET /repos/{owner}/{repo}/issues?type=issues) but was not exposed in the mcp__gitea__list_issues tool schema. The research docs (api-reference.md) were derived from the MCP source (slim.go files) and correctly captured the MCP schema — but the skill body was written with API-level assumptions that didn't match.

General pattern: Any skill wrapping MCP tools must be authored against the MCP tool schema, not the underlying API. The MCP schema is the ground truth for what parameters exist, what they're called, and what the response shape looks like.

Question for the refactor: Do the reference files need to include explicit MCP tool call signatures (as verified against the live server), or is the api-reference.md research file sufficient? The research file is accurate for MCP schemas — the problem was that the skill author didn't consult it closely enough for every parameter. Options:

  1. Each references/<domain>.md file includes the verified MCP call signatures, explicitly derived from the tool schema (not API docs)
  2. The skill-author process for MCP-wrapping skills includes a mandatory step: cross-check every parameter against the loaded tool schema before writing the execution section
  3. Both — reference files carry verified schemas AND authoring process enforces schema validation

Option 3 is the strongest but highest overhead. Option 2 alone (process fix) is the minimum. This is worth deciding during the refactor.

## Root cause of the `type` filter bug — MCP schema vs API spec drift The `Status` section bug (calling `list_issues` with a non-existent `type` parameter) was caused by the skill being authored from Gitea REST API documentation rather than verified against the actual MCP tool schemas. The MCP layer (`gitea-mcp`) wraps the REST API but deliberately slims it — parameters are omitted, response shapes are reduced, some API endpoints are combined into a single tool. The `type` filter exists in the Gitea REST API (`GET /repos/{owner}/{repo}/issues?type=issues`) but was not exposed in the `mcp__gitea__list_issues` tool schema. The research docs (`api-reference.md`) were derived from the MCP source (slim.go files) and correctly captured the MCP schema — but the skill body was written with API-level assumptions that didn't match. **General pattern:** Any skill wrapping MCP tools must be authored against the MCP tool schema, not the underlying API. The MCP schema is the ground truth for what parameters exist, what they're called, and what the response shape looks like. **Question for the refactor:** Do the reference files need to include explicit MCP tool call signatures (as verified against the live server), or is the `api-reference.md` research file sufficient? The research file is accurate for MCP schemas — the problem was that the skill author didn't consult it closely enough for every parameter. Options: 1. Each `references/<domain>.md` file includes the verified MCP call signatures, explicitly derived from the tool schema (not API docs) 2. The skill-author process for MCP-wrapping skills includes a mandatory step: cross-check every parameter against the loaded tool schema before writing the execution section 3. Both — reference files carry verified schemas AND authoring process enforces schema validation Option 3 is the strongest but highest overhead. Option 2 alone (process fix) is the minimum. This is worth deciding during the refactor.
Defame1297 added this to the The great refactoring milestone 2026-06-25 20:05:49 +00:00
Claude commented 2026-07-05 10:16:56 +00:00
Author
Collaborator
Copy Link

Design resolved — grill-with-docs session summary

Full redesign scope has been resolved. Recording it here so it's not locked in chat history.

1. Plugin relocation

Skill moves from plugins/bin/skills/gitea/ into plugins/gitea/ (the actual plugin — currently a research-doc-only shell). Old plugins/bin/skills/gitea/ is left untouched for now (kept for reference/fallback, removed later once the new structure is validated) — not deleted in this pass.

2. Scope expansion

Adding 3 new domains verified working with the current token (write:issue, write:repository — see plugins/bin/skills/gitea/references/token-access.md): Files, Commits, Releases/Tags.

Explicitly deferred:

  • Blocked by token scope: repo/org listing, user identity, notifications, packages
  • Partially broken / unverified: Actions/CI (secrets + list_runs return 403), Wiki (404 on this repo, writes untested)

3. Skill decomposition — 6 domain skills + orchestrator + agent

  • gitea-issues
  • gitea-labels-milestones (cross-cutting shared skill, composed by both gitea-issues and gitea-prs)
  • gitea-prs
  • gitea-branches (branches + commits)
  • gitea-files
  • gitea-releases (releases + tags)
  • gitea-workflow (human-facing orchestrator, preserves the old /gitea default status view — composes gitea-issues + gitea-prs — invocation becomes /gitea-workflow)
  • gitea-orchestrate (agent-facing deterministic counterpart, mirrors plugins/git/agents/git-orchestrate)

Each skill follows the git plugin's deep-module pattern: SKILL.md (orchestrator/when-why) + references/*.md (how) + references/sources.md (provenance) + README.md.

4. Comment #849's schema-verification question — resolved as "both"

Reference file call signatures are verified live against the loaded MCP tool schema via ToolSearch at authoring time (not copied from api-reference.md). kyberforge:skill-author's own authoring process was explicitly not changed in this pass (considered, declined as out of scope) — the verification discipline is applied manually during this implementation only.

5. Comment #848's deferred enrichments — all in scope

Landing in gitea-issues (composing gitea-labels-milestones):

  • Milestone assignment on create
  • Assignee on create (documented workaround given get_me/read:user is blocked)
  • Dependency-linking convention ("Depends on #N" in body text — no native API for this)
  • Label inference guide (context-pattern → Kind/*/Priority/*/Status/* taxonomy mapping)

6. Research gap backfill

Existing research docs (api-reference.md etc.) are comprehensive but 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). Backfilling now via context7 (/websites/gitea, /git_gitea_com/gitea_tea) + the research skill, before skill-authoring begins.

7. Deliberately deferred out of this PR

  • Wiring plugins/gitea/.mcp.json with the real gitea-mcp server config (currently manual via the user's ~/.claude.json) — tracked as a separate follow-up issue
  • Expanding to the remaining ~9 gitea-mcp domains not covered above

8. ADR

An ADR is being written in docs/adr/ to record this decision formally.

## Design resolved — grill-with-docs session summary Full redesign scope has been resolved. Recording it here so it's not locked in chat history. ### 1. Plugin relocation Skill moves from `plugins/bin/skills/gitea/` into `plugins/gitea/` (the actual plugin — currently a research-doc-only shell). Old `plugins/bin/skills/gitea/` is left untouched for now (kept for reference/fallback, removed later once the new structure is validated) — not deleted in this pass. ### 2. Scope expansion Adding 3 new domains verified working with the current token (`write:issue`, `write:repository` — see `plugins/bin/skills/gitea/references/token-access.md`): **Files**, **Commits**, **Releases/Tags**. Explicitly deferred: - Blocked by token scope: repo/org listing, user identity, notifications, packages - Partially broken / unverified: Actions/CI (secrets + list_runs return 403), Wiki (404 on this repo, writes untested) ### 3. Skill decomposition — 6 domain skills + orchestrator + agent - `gitea-issues` - `gitea-labels-milestones` (cross-cutting shared skill, composed by both `gitea-issues` and `gitea-prs`) - `gitea-prs` - `gitea-branches` (branches + commits) - `gitea-files` - `gitea-releases` (releases + tags) - `gitea-workflow` (human-facing orchestrator, preserves the old `/gitea` default status view — composes `gitea-issues` + `gitea-prs` — invocation becomes `/gitea-workflow`) - `gitea-orchestrate` (agent-facing deterministic counterpart, mirrors `plugins/git/agents/git-orchestrate`) Each skill follows the git plugin's deep-module pattern: `SKILL.md` (orchestrator/when-why) + `references/*.md` (how) + `references/sources.md` (provenance) + `README.md`. ### 4. Comment #849's schema-verification question — resolved as "both" Reference file call signatures are verified live against the loaded MCP tool schema via ToolSearch at authoring time (not copied from `api-reference.md`). `kyberforge:skill-author`'s own authoring process was explicitly **not** changed in this pass (considered, declined as out of scope) — the verification discipline is applied manually during this implementation only. ### 5. Comment #848's deferred enrichments — all in scope Landing in `gitea-issues` (composing `gitea-labels-milestones`): - Milestone assignment on create - Assignee on create (documented workaround given `get_me`/`read:user` is blocked) - Dependency-linking convention (`"Depends on #N"` in body text — no native API for this) - Label inference guide (context-pattern → `Kind/*`/`Priority/*`/`Status/*` taxonomy mapping) ### 6. Research gap backfill Existing research docs (`api-reference.md` etc.) are comprehensive but 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). Backfilling now via context7 (`/websites/gitea`, `/git_gitea_com/gitea_tea`) + the research skill, before skill-authoring begins. ### 7. Deliberately deferred out of this PR - Wiring `plugins/gitea/.mcp.json` with the real gitea-mcp server config (currently manual via the user's `~/.claude.json`) — tracked as a separate follow-up issue - Expanding to the remaining ~9 gitea-mcp domains not covered above ### 8. ADR An ADR is being written in `docs/adr/` to record this decision formally.
Defame1297 removed the
Status
Need More Info
2
 label 2026-07-05 14:02:51 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Compat/Breaking
Breaking change that won't be backward compatible
 Kind/Bug
Something is not working
 Kind/Documentation
Documentation changes
 Kind/Enhancement
Improve existing functionality
 Kind/Feature
New functionality
 Kind/Security
This is security issue
 Kind/Testing
Issue or pull request related to testing
Priority
Critical
1
The priority is critical
Priority
High
2
The priority is high
Priority
Low
4
The priority is low
Priority
Medium
3
The priority is medium
Reviewed
Confirmed
1
Issue has been confirmed
Reviewed
Duplicate
2
This issue or pull request already exists
Reviewed
Invalid
3
Invalid issue
Reviewed
Won't Fix
3
This issue won't be fixed
Status
Abandoned
3
Somebody has started to work on this but abandoned work
Status
Blocked
1
Something is blocking this issue or pull request
Status
Need More Info
2
Feedback is required to reproduce issue or to continue work
No Label Kind/Enhancement
Priority
Medium
3
Reviewed
Confirmed
1
Milestone
No items
No Milestone The great refactoring
Projects
Clear projects
No project
Assignees
Clear assignees
Claude renovate-bot Defame1297
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: Defame1297/holocron#6
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?