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
2026-08-12 18:09:37 +00:00
parent 50d5c30a3c
commit 5e232503c4
289 changed files with 741 additions and 1974 deletions
--- a/plugins/git/.apm/skills/git-commits/README.md
+++ b/plugins/git/.apm/skills/git-commits/README.md
@@ -0,0 +1,24 @@
+# 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 |
--- a/plugins/git/.apm/skills/git-commits/SKILL.md
+++ b/plugins/git/.apm/skills/git-commits/SKILL.md
@@ -0,0 +1,115 @@
+---
+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`.
--- a/plugins/git/.apm/skills/git-commits/references/commit-template.md
+++ b/plugins/git/.apm/skills/git-commits/references/commit-template.md
@@ -0,0 +1,66 @@
+---
+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:
+```
--- a/plugins/git/.apm/skills/git-commits/references/conventional-commits-spec.md
+++ b/plugins/git/.apm/skills/git-commits/references/conventional-commits-spec.md
@@ -0,0 +1,170 @@
+---
+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 |
--- a/plugins/git/.apm/skills/git-commits/references/sources.md
+++ b/plugins/git/.apm/skills/git-commits/references/sources.md
@@ -0,0 +1,40 @@
+---
+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