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

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:
2026-08-12 18:09:37 +00:00
parent 50d5c30a3c
commit 5e232503c4
289 changed files with 741 additions and 1974 deletions

View File

@@ -1,24 +0,0 @@
# git-commits
Create, amend, squash, and cherry-pick commits with Conventional Commits formatting and validation.
## What it does
This skill handles commit operations within the git workflow suite. It generates well-formatted commit messages following the Conventional Commits spec, validates against commitlint config-conventional constraints, and communicates SemVer impact. It enforces confirmation gates for history-altering operations (amend, rebase, squash) and returns structured JSON output for agent consumption.
## Usage
```
/git-commits
```
Describe your commit task: create a new commit, amend, squash, or cherry-pick. The skill will guide message formatting and handle confirmation for destructive operations.
## Files
| File | Purpose |
|------|---------|
| `SKILL.md` | Skill instructions for agents |
| `references/conventional-commits-spec.md` | Full Conventional Commits specification |
| `references/commit-template.md` | Why / Implementation Notes / Impact body structure and full trailer list |
| `references/sources.md` | Research sources and provenance |

View File

@@ -1,115 +0,0 @@
---
name: git-commits
description: >
Use when creating, amending, squashing, or cherry-picking commits.
Generates well-formatted commit messages following Conventional Commits spec (type, scope, description, body, footers).
Validates against commitlint config-conventional constraints (header max 100 chars, lowercase subject, no trailing periods, type must be one of 11 standard types).
Communicates SemVer impact (MAJOR for breaking changes, MINOR for features, PATCH for fixes).
Handles confirmation gates for history-altering operations (amend, rebase, squash).
Provides interactive guidance for humans, structured JSON output for agents.
Do not use for: inspecting git history, branch management, or repository state inspection — those are separate skills.
metadata:
version: "0.1.2"
category: git
source_keys:
- conventional-commits-spec
- commitlint-config-conventional
- org-commit-conventions
- context7-git-htmldocs
allowed-tools: Bash
---
## Gotchas
- **Type must be one of 11 standard types** — `feat`, `fix`, `perf`, `revert`, `docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`. Non-standard types will fail commitlint validation. Note: the Conventional Commits spec itself only mandates `feat`/`fix` — the 11-type set is a commitlint/Angular convention this skill validates against, not a spec requirement.
- **Scope is optional but should be used** — helps identify which part of the system changed. Examples: `api`, `db`, `cli`, `config`.
- **Header max 100 characters** — type + scope + colon + description must fit. If longer, move detail to body.
- **BREAKING CHANGE notation** — use `!` before the colon (`feat!: drop Node 6`) for visibility in `git log --oneline`. Footer notation (`BREAKING CHANGE: ...`) is machine-readable but hidden in log.
- **SemVer mapping is not optional** — agents must communicate: `feat` → MINOR bump, `fix`/`perf`/`revert` → PATCH, any with breaking change → MAJOR.
- **Confirmation gates are mandatory for destructive operations** — amend, rebase, squash require explicit user/agent approval before execution.
- **Never skip hooks with `--no-verify`** — hooks are the automated QA gate; bypassing them breaks the pipeline. Do not add this flag to any commit command unless the user explicitly demands it, and warn them if they do.
- **Never force-push `main`/`master`** — even after an amend or interactive rebase, refuse to force-push a protected branch (`main`, `master`) and explain why; force-push is only safe on branches no one else has based work on.
- **Command examples use the `rtk git` wrapper** — this org's convention routes all git invocations through `rtk git <subcommand>` instead of bare `git <subcommand>`. Follow this prefix in any command you actually run.
- **Never commit secrets, credentials, or environment-specific config** — if staged changes contain what looks like an API key, token, password, or connection string, stop and flag it before committing rather than committing it.
- **Commits must be atomic and leave the repo working** — each commit should be one logical, independently reviewable and reversible change, and should leave the repository in a buildable/testable state. If staged changes bundle unrelated work, suggest splitting before committing.
- **Commit messages explain why, not what** — the diff already shows what changed; the message's job is to capture context the diff can't (motivation, root cause, tradeoffs). See `references/commit-template.md` for the structure this maps to.
## Workflow
### For creating a new commit:
1. **Gather context** — what changed and why? (from staged changes, PR description, issue context). Verify the staged diff is one logical, atomic change and that the repo would still build/test at this commit — if not, suggest splitting before proceeding.
2. **Check for secrets** — scan the staged diff for anything that looks like a credential, API key, token, or environment-specific config. Stop and flag it rather than committing.
3. **Determine type** — is this a feature (`feat`), bug fix (`fix`), or other? Default: check the change itself.
4. **Determine scope** — which system/module? Use scope from plugin config if set, otherwise infer from files changed.
5. **Write description** — imperative mood, no period. Neither source spec sets a length target below the 100-char header max, but convention favors keeping it to ~50 characters where possible for `git log --oneline` readability. Examples: "add user authentication", "fix race condition in cache".
6. **Add body if needed** — explain why (not what). Blank line before body, wrap at 100 chars. For non-trivial changes, follow the Why / Implementation Notes / Impact structure in `references/commit-template.md`.
7. **Add footers if needed** — `Fixes: #123`, `Refs: #123`, `ADR: 0012`, `RFC: 0003`, `Design: <link>`, `Reviewed-by: Name`, `Co-authored-by: Name <email>`, `Signed-off-by: Name <email>`, `BREAKING CHANGE: description`. See `references/commit-template.md` for the full trailer list.
8. **Validate** — check header length, type correctness, no trailing periods, lowercase.
9. **Confirm and execute** — for agents, require explicit approval; for humans, show preview and ask. Never add `--no-verify` to skip hooks.
### For amending a commit:
1. **Stage new changes** (or changes to undo)
2. **Run amend operation** — executes `rtk git commit --amend [--no-edit]` based on user intent
3. **Offer message edit** — if user wants to change commit message, show current message and prompt for new one
4. **Confirm before force-push** — amending is only safe on non-shared branches; if the current branch is `main`/`master`, refuse to force-push and explain why rather than warning and proceeding
### For squashing commits (interactive rebase):
1. **Identify commits to squash** — typically the last N commits on current branch
2. **Confirm operation** — squashing rewrites history; get explicit approval
3. **Execute rebase** — `rtk git rebase -i HEAD~N`, mark older commits as `squash` or `fixup`
4. **Handle merge conflicts** — if rebase halts, offer conflict resolution options or abort; do not resolve automatically without confirmation
5. **Offer message composition** — if squashing interactive, allow message editing
### For squashing commits (autosquash — preferred when tagging at commit time):
Prefer this over manual interactive rebase when a commit is written to be folded into an earlier one, since it removes the manual "mark as squash/fixup" step and the risk of reordering the wrong line:
1. **Create the fixup/squash commit** — `rtk git commit --fixup=<commit>` (keeps target's message) or `rtk git commit --squash=<commit>` (lets you edit the combined message later). Both prefix the message with `fixup!`/`squash!` and target `<commit>`.
2. **Confirm operation** — rewriting history still requires explicit approval before the rebase runs.
3. **Execute** — `rtk git rebase --autosquash HEAD~N` (or `-i --autosquash` to review the plan first); git reorders and marks the `fixup!`/`squash!` commits against their targets automatically.
4. **Handle merge conflicts** — same as manual rebase: offer resolution or abort, never resolve automatically without confirmation.
### For cherry-picking:
1. **Identify source commit(s)** — hash or branch reference
2. **Confirm destination branch** — cherry-pick will replay commits on current branch
3. **Execute cherry-pick** — `rtk git cherry-pick <commit-hash>`
4. **Handle conflicts** — offer conflict resolution or abort
5. **Report outcome** — successful replays, conflicts, or rejected commits
## Output format (for agent consumption)
Return structured JSON:
```json
{
"operation": "create|amend|squash|cherry-pick",
"status": "success|conflict|rejected",
"message": "Commit message or error description",
"commit_hash": "abc1234",
"semver_impact": "MAJOR|MINOR|PATCH|none",
"breaking_change": true|false,
"confirmation_required": true|false,
"details": {
"type": "feat",
"scope": "api",
"description": "add user authentication",
"body": "optional body text",
"footers": ["Fixes: #123", "Refs: #456", "ADR: 0012", "Reviewed-by: Alice", "Co-authored-by: Bob <bob@example.com>", "Signed-off-by: Alice <alice@example.com>"]
}
}
```
For interactive human use, format as readable prose with clear prompts and previews.
## Reference
If a footer or type/scope edge case isn't covered above, read `references/conventional-commits-spec.md` for the full specification.
For the Why / Implementation Notes / Impact body structure and the full trailer list, read `references/commit-template.md`.

View File

@@ -1,66 +0,0 @@
---
source_keys:
- org-commit-conventions
---
# Commit Message Body Template
Use this structure for the body/footer of any non-trivial commit (skip sections that don't apply — do not leave placeholders in the actual commit).
```
<type>(<scope>): <concise summary>
```
The header is required. Describe the intended outcome, not the implementation.
## Why
Explain why this change exists. This is the most valuable part of the commit — the diff already shows *what* changed; future maintainers (human or AI) need *why*.
Include, where applicable:
- Problem being solved
- User or business need
- Bug or root cause
- Important context not visible in the code
Omit if the reason is immediately obvious.
## Implementation Notes
Capture decisions that are difficult to infer from the code:
- Why this approach was chosen
- Important assumptions or invariants
- Constraints imposed by external systems
- Tradeoffs or intentional compromises
- Non-obvious implementation details
- Workarounds or temporary solutions
Do NOT describe the diff ("renamed X", "added Y"). Omit if there's nothing worth preserving.
## Impact
Document effects future developers should know about:
- Behavior changes
- Breaking changes
- Performance implications
- Security considerations
- Migration or deployment requirements
- Compatibility concerns
- Follow-up work or known limitations
Omit if there are no noteworthy impacts.
## Trailers
Structured metadata for traceability and tooling. Use only the trailers that apply:
```
Fixes:
Refs:
ADR:
RFC:
Design:
Co-authored-by:
Reviewed-by:
Signed-off-by:
BREAKING CHANGE:
```

View File

@@ -1,170 +0,0 @@
---
source_keys:
- conventional-commits-spec
- commitlint-config-conventional
---
# Conventional Commits Specification (v1.0.0)
Conventional Commits is a lightweight convention on top of commit messages that provides a set of rules for creating an explicit commit history. It enables automated tooling (CHANGELOG generation, semantic version bumping) and structured filtering.
## Message Format
```
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
```
Each section is separated by a blank line. The header is the only required part.
## Rules
| Element | Rule |
|---|---|
| `type` | Required. Lowercase noun. |
| `scope` | Optional. Noun in parentheses directly after type: `feat(api):`. |
| `description` | Required. Immediately follows `type/scope: `. Imperative mood, no trailing period. |
| `body` | Optional. Begins one blank line after description. Free-form prose, multiple paragraphs allowed. Lines max 100 characters. |
| `footer(s)` | Optional. Begins one blank line after body (or description). `<token>: <value>` format. Lines max 100 characters. |
| `BREAKING CHANGE` | Must be uppercase. Either a footer token or signalled by `!` before the colon. |
## Standard Types
The spec itself mandates only `feat` and `fix`. The 11-type set below is the de-facto standard from `@commitlint/config-conventional` (Angular commit message guidelines), not a spec requirement — but it is what this skill validates against.
### 11-type set (commitlint/config-conventional)
| Type | Meaning | SemVer impact | Appears in CHANGELOG |
|---|---|---|---|
| `feat` | New user-visible feature | MINOR | Yes |
| `fix` | Bug fix | PATCH | Yes |
| `perf` | Performance improvement, no API change | PATCH | Yes |
| `revert` | Reverts a previous commit | PATCH | Yes |
| `docs` | Documentation only | none | No |
| `style` | Formatting, whitespace — no logic change | none | No |
| `refactor` | Code restructuring — no feature or fix | none | No |
| `test` | Adding or fixing tests | none | No |
| `build` | Build system or external dependency changes | none | No |
| `ci` | CI configuration and scripts | none | No |
| `chore` | Anything not fitting above | none | No |
A `BREAKING CHANGE` footer or `!` on **any** type always triggers a MAJOR bump.
## Breaking Changes
Two equivalent notations:
**`!` in header** (preferred — visible in `git log --oneline`):
```
feat!: drop support for Node 6
feat(api)!: remove deprecated endpoint
```
**`BREAKING CHANGE` footer** (machine-readable body):
```
feat: allow config to extend other configs
BREAKING CHANGE: `extends` key now used for extending config files
```
**Both together** (most explicit):
```
feat!: drop support for Node 6
BREAKING CHANGE: use JavaScript features not available in Node 6.
```
Rules:
- `BREAKING CHANGE` must be all caps.
- `BREAKING-CHANGE` (hyphenated) is an accepted synonym.
- Any type can carry a breaking change, not just `feat`.
- The footer value must describe what broke.
## Footer Token Rules
```
<token>: <value>
<token> #<value> # for issue references
```
- Tokens use hyphens for word separation: `Reviewed-by`, `Co-authored-by`, `Refs`.
- Exception: `BREAKING CHANGE` (space allowed, uppercase).
- Multiple footers allowed, one per line.
- Blank line required before the footer block.
Valid footer examples:
```
Reviewed-by: Z
Refs: #123
Co-authored-by: Alice <alice@example.com>
BREAKING CHANGE: the `--format` flag now requires a value
```
## Examples
Minimal — no body, no footer:
```
docs: correct spelling of CHANGELOG
```
With scope:
```
feat(lang): add Polish language
```
Breaking change via `!`:
```
feat!: send an email to the customer when a product is shipped
```
Breaking change via footer:
```
feat: allow provided config object to extend other configs
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
```
Multi-paragraph body with multiple footers:
```
fix: prevent racing of requests
Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.
Remove timeouts which were used to mitigate the racing issue but are
obsolete now.
Reviewed-by: Z
Refs: #123
```
Revert:
```
revert: let us never again speak of the noodle incident
Refs: 676104e, a215868
```
## commitlint Constraints (config-conventional)
| Constraint | Value |
|---|---|
| Header max length | 100 characters |
| Subject must not end with `.` | enforced |
| Subject must be lowercase (not sentence-case or UPPER-CASE) | enforced |
| Body / footer line max length | 100 characters |
| Type must be one of the 11 standard types | error if not |
| Blank line before body | warning |
| Blank line before footer | warning |
## SemVer Mapping Summary
| Condition | SemVer bump |
|---|---|
| `fix`, `perf`, `revert` | PATCH |
| `feat` | MINOR |
| Any type with `BREAKING CHANGE` or `!` | MAJOR |
| All other types (`docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`) | none |

View File

@@ -1,40 +0,0 @@
---
topic: commits
source_keys:
- conventional-commits-spec
- commitlint-config-conventional
- org-commit-conventions
- context7-git-htmldocs
---
# Research Sources for git:commits Skill
Sources extracted from the git plugin research phase. Only sources that directly informed this skill are listed; sibling skills (git:branches, git:history, git:remotes, etc.) have their own sources.md.
## conventional-commits-spec
- **Description:** Conventional Commits Specification (v1.0.0) — message format, types, breaking changes, footer rules
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "Conventional Commits Specification (v1.0.0)"
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md
- **Status:** extracted
## commitlint-config-conventional
- **Description:** commitlint config-conventional preset — validation constraints (max 100 chars header, no trailing periods, lowercase type, 11-type set enforcement)
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "commitlint Constraints (`config-conventional`)"
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md
- **Status:** extracted
## org-commit-conventions
- **Description:** Organization commit message body template and git conventions (atomic commits, no `--no-verify`, no force-push main/master, `rtk git` wrapper) — content fully embedded in this skill; the org's `core/instructions/git.md` and `core/instructions/commits.md` are provenance only and are not a live dependency
- **Research doc:** core/instructions/commits.md, core/instructions/git.md (org convention, not part of the plugin's research corpus)
- **Contributing files:** SKILL.md, references/commit-template.md
- **Status:** extracted
## context7-git-htmldocs
- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup` and `git rebase --autosquash` flag semantics
- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md
- **Contributing files:** SKILL.md
- **Status:** extracted