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

feat(kyberforge): execute plugin-to-apm marketplace conversion

Browse Source 
Why:
ADR-0015 established that Microsoft APM (apm.yml + .apm/) should replace
this repo's hand-authored plugin.json/marketplace.json model, with those
files becoming compiled output of `apm pack` instead of files edited by
hand via the (now-retired) plugin-author/marketplace-author skills.
Issue #90 was the deferred execution of that decision, gated on #88
(apm tooling) and #89 (apm-native agent-author/skill-author routing).

Implementation notes:
- All six plugins (bin, core, git, gitea, kyberforge, lint) now carry
  apm.yml + .apm/{skills,agents,hooks} as their authoring source. Skills
  moved with a plain git mv (content-identical across targets). Agents
  were re-authored, not moved: per ADR-0016, .apm/agents/*.agent.md
  compiles verbatim to both Claude and Copilot, so plugin-scope agents
  now carry only name/description/model/source_keys -- no tools: field,
  no Claude-only knobs (isolation, maxTurns, effort, memory,
  permissionMode).
- Root apm.yml registers all 7 marketplace packages (6 local plus
  mattpocock-skills as a remote entry) under versioning: per_package,
  matching this repo's existing independent-plugin-versioning practice.
- .claude-plugin/marketplace.json and every plugin's plugin.json are now
  apm-pack-compiled output, verified against the prior hand-maintained
  content: same names/descriptions/versions/licenses/authors, only
  cosmetic serialization differences (JSON key order, owner email vs.
  url, Unicode escaping).
- plugin-author and marketplace-author are retired now that apm-based
  authoring fully replaces their job; kyberforge bumped 1.3.1 -> 1.4.0
  for that removal, and the root marketplace catalog bumped
  0.3.1 -> 0.3.2 to match, per the version-bump convention now
  documented in apm-workflow's reference docs instead of a dedicated
  script (apm has no native version-bump automation).
- Fixed hardcoded pre-.apm/ path assumptions across
  .pre-commit-config.yaml, .pre-commit-hooks.yaml,
  scripts/check-scope-walkup-sync.sh, scripts/sync-vale-styles.sh,
  scripts/check-vale-style-sync.sh, six plugins' root plugin.json
  (stale skills/hooks/agents pointer fields that check-manifests.sh
  validates), and several tests/*.bats and tests/*.sh fixtures --
  including a bats REPO_ROOT relative-path depth bug (10 files, one
  extra .apm/ directory level to walk up) and a vale probe-path
  isolation regression introduced mid-fix.
- Corrected empirically-wrong assumptions surfaced this session in
  apm-workflow/apm-install's own reference docs: `apm marketplace
  package add` does not accept local paths (only owner/repo remote
  shorthand -- local packages are registered by editing apm.yml's
  marketplace.packages[] directly); `apm compile` is a consumer-side
  AGENTS.md/CLAUDE.md generator, not the plugin.json producer, and
  hard-fails on skill/agent-only packages without --clean; `apm plugin
  init <name>` nests a stray subdirectory when run with a positional
  name arg from inside a same-named directory; no native Copilot
  marketplace output profile exists; .mcp.json is merged into the
  compiled plugin.json content-aware and target-scoped, with no
  dependencies.mcp entry needed for simple passthrough; pipx is the
  correct pip fallback on externally-managed Python environments.
- Renamed agent-author's copilot.agent.md template asset to
  copilot.agent.md.template so apm compile's recursive *.agent.md glob
  stops misparsing the placeholder template as a real agent primitive.

Impact:
plugin.json and marketplace.json are compiled artifacts from here on --
editing them by hand is no longer the workflow; edit apm.yml/.apm/ and
run apm pack. CONTEXT.md's Plugin/Plugin marketplace glossary entries
reflect this. ADR-0001 is marked superseded, ADR-0006 moot, and
ADR-0010 updated for the new .apm/agents/ path (project/user scope
unaffected, per ADR-0016). Full local verification: claude plugin
validate --strict on all 6 plugins, apm audit --ci, apm marketplace
check, check-manifests.sh, and the full test suite (165/165 bats,
13/13 shell scripts) all pass clean.

Fixes: #90
Refs: #88, #89
ADR: 0015
ADR: 0016

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Ub96PyaSRD9BHPktotj1pC
This commit is contained in:
Defame1297
2026-08-12 18:09:37 +00:00
parent 50d5c30a3c
commit 5e232503c4
289 changed files with 741 additions and 1974 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
plugins/gitea/.apm/skills/gitea-labels-milestones/README.md Normal file
View File

@@ -0,0 +1,25 @@
# gitea-labels-milestones
Read and write Gitea labels and milestones, and resolve label/milestone identity for the skills that apply them to issues and PRs.
## What it does
This skill handles label and milestone CRUD (`label_read`/`label_write`, `milestone_read`/`milestone_write`) — listing repo or org labels, creating/editing/deleting a label, resolving a label name to the numeric ID required for any write, and listing/creating/updating/closing/deleting a milestone. It also owns label inference: mapping conversation context (bug report, feature request, urgency language) to this repo's `Kind/*`/`Priority/*`/`Status/*` taxonomy. It is a cross-cutting shared skill composed by `gitea-issues` and `gitea-prs`, which call into it for label/milestone resolution before their own `issue_write`/`pull_request_write` calls apply the resolved IDs.
## Usage
```
/gitea-labels-milestones
```
Describe the label or milestone task: list labels, resolve a name to an ID, create/edit/delete a label, or list/create/update/close/delete a milestone. For applying already-resolved labels or a milestone to a specific issue or PR, use `gitea-issues` or `gitea-prs` instead.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents — dispatch table and Gotchas |
| `references/labels.md` | Execution detail for `label_read`/`label_write` |
| `references/milestones.md` | Execution detail for `milestone_read`/`milestone_write` |
| `references/label-inference.md` | Context-pattern → `Kind/*`/`Priority/*`/`Status/*` label inference guide |
| `references/sources.md` | Research sources backing the label/milestone guidance |

68
plugins/gitea/.apm/skills/gitea-labels-milestones/SKILL.md Normal file
View File

@@ -0,0 +1,68 @@
---
name: gitea-labels-milestones
description: >
Use when reading or writing Gitea labels or milestones — listing repo/org labels, creating,
editing, or deleting a label, resolving label names to the numeric IDs required for applying
them to an issue or PR, or listing, creating, updating, closing, or deleting a milestone. This is
a cross-cutting shared skill: `gitea-issues` and `gitea-prs` both compose it whenever they need to
apply labels or assign a milestone, rather than duplicating label/milestone logic. Also use for
label inference — mapping a bug report, feature request, or urgency signal in conversation
context to the repo's `Kind/*`/`Priority/*`/`Status/*` label taxonomy. Do not use for applying
already-resolved label IDs or milestone IDs to a specific issue or PR — that write goes through
`issue_write`/`pull_request_write` in `gitea-issues`/`gitea-prs`, not here.
compatibility: Requires Gitea MCP server configured with write:issue and write:repository token scopes.
metadata:
category: integration
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
- context7-websites-gitea
- context7-gitea-tea-cli
version: "0.1.1"
allowed-tools: Bash mcp__gitea__label_read mcp__gitea__label_write mcp__gitea__milestone_read mcp__gitea__milestone_write
---
## Gotchas
- **Label writes take IDs, reads return names.** `label_read` is the only tool that returns full label objects (`id`, `name`, `color`, `description`). Issue/PR responses slim labels down to name strings. Before any label is applied to an issue or PR (in `gitea-issues`/`gitea-prs`), resolve names → IDs here via `label_read method: "list_repo_labels"` — never pass a name string where an ID is expected.
- **Milestones are referenced by ID everywhere, never by title.** `milestone_write` update/delete take `id`. The one place titles show up as the sole handle is the `pull_request_read` response (see next gotcha).
- **Milestone representation differs between issues and PRs.** `issue_read` returns `milestone: {id, title}` — an object. `pull_request_read` returns `milestone: "title string"` — title only, no ID. You cannot recover a milestone ID from a PR response directly; call `milestone_read method: "list"` and match by title instead.
- **Repo labels and org labels are separate pools, never mixed in one call.** `label_read`/`label_write` take either `owner`+`repo` (repo-scoped methods) or `org` (org-scoped methods) — passing both or neither for a given method is a caller error, not something the schema enforces for you. Repo and org labels can both apply to the same issue, but you list/create/edit them through different method values.
- **`milestone_write` accepts `"update"` and `"edit"` as the same operation.** Both method values map to the identical update call. Prefer `"update"` for consistency with `issue_write`/`pull_request_write`.
- **`exclusive` is documented as an org-labels-only flag — it isn't what enforces exclusivity here.** Gitea's docs scope the settable/server-enforced `exclusive` flag to org labels only, and the live `label_write` schema for `create_repo_label`/`edit_repo_label` doesn't document accepting it at all. This repo's `Kind/*`, `Priority/*`, `Status/*` groups still behave as one-label-per-scope, but that's a manually-enforced convention this skill implements client-side, not a guaranteed server behavior for repo labels: applying a new label within a scope (e.g. `Priority/High`) must replace any existing label in that same scope, not add alongside it, and nothing on the server enforces that for you. Label inference (see `references/label-inference.md`) must respect this — replace, don't stack.
- **Pagination is manual on every list call.** `label_read` and `milestone_read` both default to `per_page: 30`. Iterate `page: 1, 2, ...` until the result count is less than `per_page` — there is no cursor or auto-pagination.
- **Schema requiredness differs between the two tool families.** `milestone_read`/`milestone_write` have `owner` and `repo` as hard-required parameters (the call fails validation without them). `label_read`/`label_write` only hard-require `method` — `owner`/`repo`/`org` are functionally required per method but not schema-enforced, so passing none produces a runtime error from Gitea, not a client-side validation error.
## Step 1 — Resolve owner and repo
Before any tool call, extract `owner` and `repo` from the git remote (skip this if an orchestrating caller already passed them in):
```bash
git remote get-url origin
```
If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL."
## Step 2 — Dispatch
| Task | Tool | method |
|---|---|---|
| List repo labels | `label_read` | `"list_repo_labels"` |
| Get one repo label by ID | `label_read` | `"get_repo_label"` |
| List org labels | `label_read` | `"list_org_labels"` |
| Create a repo/org label | `label_write` | `"create_repo_label"` / `"create_org_label"` |
| Edit a repo/org label | `label_write` | `"edit_repo_label"` / `"edit_org_label"` |
| Delete a repo/org label | `label_write` | `"delete_repo_label"` / `"delete_org_label"` |
| List milestones | `milestone_read` | `"list"` |
| Get one milestone by ID | `milestone_read` | `"get"` |
| Create a milestone | `milestone_write` | `"create"` |
| Update / close a milestone | `milestone_write` | `"update"` |
| Delete a milestone | `milestone_write` | `"delete"` |
For full parameter detail and step-by-step call sequences, read `references/labels.md` (label operations) or `references/milestones.md` (milestone operations). For mapping conversation context to a label to apply, read `references/label-inference.md`.
Applying resolved label IDs or a milestone ID to a specific issue or PR is out of scope here — that's `issue_write`/`pull_request_write` in the composing skill (`gitea-issues`/`gitea-prs`).

68
plugins/gitea/.apm/skills/gitea-labels-milestones/references/label-inference.md Normal file
View File

@@ -0,0 +1,68 @@
---
topic: label-inference
source_keys:
- context7-websites-gitea
- gitea-mcp-repo
---
# Label inference guide
Maps context-pattern signals from conversation content (an issue being drafted, a bug report, a PR
description) to this repo's `Kind/*` / `Priority/*` / `Status/*` label taxonomy. Used by
`gitea-issues` and `gitea-prs` before creating or updating an issue/PR, and directly when the user
asks to label something without naming exact labels.
## Scoped labels are mutually exclusive — replace, don't stack
Each of `Kind/*`, `Priority/*`, `Status/*` is treated as a scoped-label group by convention (the `/`
delimiter naming pattern). Gitea's `exclusive` flag — the mechanism that would let the server itself
enforce one-label-per-scope — is documented as an org-labels-only setting, and the repo-level
`label_write` methods used here don't accept it at all. So exclusivity within these scopes is a
convention this skill enforces client-side, not something the server guarantees: applying a new
label within a scope is expected to replace any existing label in that same scope on the target
issue/PR, not add alongside it. When inference
selects a `Priority/High` label and the issue already carries `Priority/Medium`, the write should
result in only `Priority/High` remaining — use `replace_labels` scoped to that group's labels, or at
minimum remove the superseded label before adding the new one. Never leave two labels from the same
scope applied at once.
## Signal → label mapping
**`Kind/*`** (what kind of work this is):
| Signal in context | Label |
|---|---|
| Bug report, error, crash, unexpected behavior, "broken", "doesn't work" | `Kind/Bug` |
| New capability, "add support for", net-new functionality | `Kind/Feature` |
| Improvement to existing behavior, "make X better", refactor with behavior change | `Kind/Enhancement` |
| Docs-only change, README/comment/guide updates | `Kind/Documentation` |
| Vulnerability, credential exposure, injection risk, auth bypass | `Kind/Security` |
**`Priority/*`** (urgency):
| Signal in context | Label |
|---|---|
| "blocking", "critical", "urgent", production-down | `Priority/Critical` |
| "soon", "high priority", "should do this sprint" | `Priority/High` |
| No urgency signal present | `Priority/Medium` (default) |
**`Status/*`** (workflow state):
| Signal in context | Label |
|---|---|
| Explicit statement that the work is blocked on something else | `Status/Blocked` |
## Procedure
1. Read the conversation context (issue/PR title, body, or the triggering discussion) for the
signals above.
2. Call `label_read method: "list_repo_labels"` (see `references/labels.md`) to get the current
label set with IDs — inference must never guess an ID, only a name, then resolve it.
3. Match inferred label names against the resolved list (case-insensitive). If a scope group
already has a different label applied on the target and a new one is inferred for that same
scope, plan to replace rather than add (see above).
4. **Low-confidence inference omits the label.** If no signal confidently maps to a `Kind/*` value,
do not guess — omit `Kind/*` entirely rather than default to one. `Priority/Medium` is the one
exception: it's the explicit default when no urgency signal is present, not a guess.
5. Hand the resolved IDs (plus which scopes to replace) to the caller's `issue_write`/
`pull_request_write` call — this skill does not apply labels to an issue or PR itself.

97
plugins/gitea/.apm/skills/gitea-labels-milestones/references/labels.md Normal file
View File

@@ -0,0 +1,97 @@
---
topic: labels
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Label operations
Execution detail for `label_read` and `label_write`. Both tools operate on either **repo-scoped**
or **org-scoped** labels — never both in one call. Pick the method family (`*_repo_label*` vs.
`*_org_label*`) that matches the target, and pass `owner`+`repo` or `org` accordingly.
## Verified live schemas
`label_read` — required: `method`.
| Param | Type | Notes |
|---|---|---|
| `method` | string (enum) | `"list_repo_labels"` \| `"get_repo_label"` \| `"list_org_labels"` |
| `owner` | string | for repo methods |
| `repo` | string | for repo methods |
| `org` | string | for org methods |
| `id` | number | label ID, required for `"get_repo_label"` |
| `page` | number | default `1` |
| `per_page` | number | default `30` |
`label_write` — required: `method`.
| Param | Type | Notes |
|---|---|---|
| `method` | string (enum) | `"create_repo_label"` \| `"edit_repo_label"` \| `"delete_repo_label"` \| `"create_org_label"` \| `"edit_org_label"` \| `"delete_org_label"` |
| `owner` | string | for repo methods |
| `repo` | string | for repo methods |
| `org` | string | for org methods |
| `id` | number | for edit/delete |
| `name` | string | required for create |
| `color` | string | hex `#RRGGBB`, required for create |
| `description` | string | optional |
| `exclusive` | boolean | org labels only |
| `is_archived` | boolean | repo labels only |
Note: unlike `milestone_read`/`milestone_write`, `owner`/`repo`/`org` are **not** schema-required on
either label tool — only `method` is. Passing none for a repo/org method still fails, just as a
runtime error from Gitea rather than a client-side validation error.
## List repo labels
```
label_read method: "list_repo_labels" owner: <owner> repo: <repo> per_page: 50
```
Paginate (`page: 1, 2, ...`) until the returned count is less than `per_page`. This is the only way
to build a complete name → ID map — there is no lookup-by-name endpoint.
## Get one label
```
label_read method: "get_repo_label" owner: <owner> repo: <repo> id: <id>
```
## Resolve a name to an ID
There is no direct name lookup. List all repo labels (paginating if needed), scan for a
case-insensitive name match, and extract `id`. This is the required first step before any label
application on an issue or PR — the actual `add_labels`/`replace_labels`/`remove_label` call lives
in `gitea-issues`/`gitea-prs` via `issue_write`/`pull_request_write`, which take numeric IDs only.
## Create a label
```
label_write method: "create_repo_label"
owner: <owner> repo: <repo>
name: "Kind/Bug"
color: "#d73a4a"
description: "Confirmed bug"
```
For an org label, use `method: "create_org_label"` with `org:` instead of `owner`/`repo`, and
`exclusive: true` if the label belongs to a mutually-exclusive scope group.
## Edit a label
```
label_write method: "edit_repo_label" owner: <owner> repo: <repo> id: <id> color: "#ff0000"
```
Only pass the fields being changed — `id` plus any of `name`/`color`/`description`/`is_archived`.
## Delete a label
```
label_write method: "delete_repo_label" owner: <owner> repo: <repo> id: <id>
```
Deleting a label does not remove it from historical issue/PR timeline events — it disappears only
from current label lists.

98
plugins/gitea/.apm/skills/gitea-labels-milestones/references/milestones.md Normal file
View File

@@ -0,0 +1,98 @@
---
topic: milestones
source_keys:
- gitea-mcp-repo
- gitea-mcp-slim-go
---
# Milestone operations
Execution detail for `milestone_read` and `milestone_write`. Milestones are always repo-scoped —
there is no org-level milestone concept, unlike labels.
## Verified live schemas
`milestone_read` — required: `method`, `owner`, `repo`.
| Param | Type | Notes |
|---|---|---|
| `method` | string (enum) | `"get"` \| `"list"` |
| `owner` | string | required |
| `repo` | string | required |
| `id` | number | milestone ID, required for `"get"` |
| `name` | string | title filter, for `"list"` |
| `state` | string | default `"all"` — conventional values `"open"`/`"closed"`/`"all"`, but **not enforced by an enum in the live schema** (plain string). Any other value is passed through to Gitea rather than rejected client-side. |
| `page` | number | default `1` |
| `per_page` | number | default `30` |
`milestone_write` — required: `method`, `owner`, `repo`.
| Param | Type | Notes |
|---|---|---|
| `method` | string (enum) | `"create"` \| `"update"` \| `"edit"` \| `"delete"` — `"update"`/`"edit"` are aliases for the same operation; prefer `"update"` |
| `owner` | string | required |
| `repo` | string | required |
| `id` | number | required for update/delete |
| `title` | string | required for create |
| `description` | string | optional |
| `due_on` | string | due date — the live tool schema only describes this as an opaque "due date" string with no enforced format; ISO 8601 (e.g. `"2025-03-01T00:00:00Z"`) is the conventional value Gitea's REST API accepts, not something confirmed by the live MCP schema itself |
| `state` | string (enum) | `"open"` \| `"closed"` — **this one is schema-enforced**, unlike `milestone_read`'s `state` |
Note: unlike `label_read`/`label_write`, both milestone tools hard-require `owner` and `repo` at the
schema level — there's no scope variant to omit them for.
## List milestones
```
milestone_read method: "list" owner: <owner> repo: <repo> state: "open"
```
Report each as: id, title, state, due date, open/closed issue counts.
## Get one milestone
```
milestone_read method: "get" owner: <owner> repo: <repo> id: <id>
```
## Resolve a milestone ID from a title
Needed whenever the only handle available is a title — e.g. a `pull_request_read` response, which
returns `milestone` as a bare title string rather than `{id, title}`. Call:
```
milestone_read method: "list" owner: <owner> repo: <repo> name: <title>
```
and take the `id` of the matching result. If `name` filtering returns no match (e.g. due to a
title typo or case mismatch), fall back to listing without the filter and matching manually.
## Create a milestone
```
milestone_write method: "create"
owner: <owner> repo: <repo>
title: "v1.0"
description: "First stable release"
due_on: "2025-03-01T00:00:00Z"
```
Report the returned ID — the caller (`gitea-issues`/`gitea-prs`) needs it to assign issues/PRs to
this milestone via `issue_write`/`pull_request_write`.
## Update or close a milestone
```
milestone_write method: "update" owner: <owner> repo: <repo> id: <id> state: "closed"
```
Only pass the fields being changed — `id` plus any of `title`/`description`/`due_on`/`state`.
## Delete a milestone
```
milestone_write method: "delete" owner: <owner> repo: <repo> id: <id>
```
Deleting a milestone does not delete or unassign the issues/PRs that referenced it — they simply
lose the milestone reference.

33
plugins/gitea/.apm/skills/gitea-labels-milestones/references/sources.md Normal file
View File

@@ -0,0 +1,33 @@
# Sources
## gitea-mcp-repo
- **URL:** https://gitea.com/gitea/gitea-mcp
- **Description:** Official gitea-mcp repository (v1.3.0); operation/*.go source files documenting all 55 MCP tools, their parameters, and CLI flags
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/labels.md, references/milestones.md, references/label-inference.md
- **Status:** `extracted`
## gitea-mcp-slim-go
- **URL:** https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/issue/slim.go, https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/pull/slim.go, https://gitea.com/gitea/gitea-mcp/raw/branch/main/operation/repo/slim.go
- **Description:** Slim response shape structs from gitea-mcp source; defines exactly which fields the MCP server returns for issues, PRs, branches, commits, tags, releases, and files — including the label name-vs-ID and milestone object-vs-string representation quirks this skill's Gotchas document
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/labels.md, references/milestones.md
- **Status:** `extracted`
## context7-websites-gitea
- **URL:** context7:/websites/gitea
- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — scoped/exclusive label conventions and milestone/label state-transition semantics
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md, references/label-inference.md
- **Status:** `extracted`
## context7-gitea-tea-cli
- **URL:** context7:/git_gitea_com/gitea_tea
- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner command patterns for labels and milestones
- **Research doc:** plugins/gitea/docs/research/docs/gitea/sources.md
- **Contributing files:** SKILL.md
- **Status:** `extracted`