Files

Defame1297 38f1ba4e03 fix(kyberforge): bridge apm content to Claude Code's flat plugin discovery

Claude Code's (and Copilot's) native plugin installer has zero awareness of
.apm/ nesting -- it convention-scans only flat skills/, agents/, commands/,
hooks.json at each plugin's root. Confirmed via strings on the installed
claude binary and live installs of git@holocron/gitea@holocron/kyberforge@
holocron, all reporting Skills(0) Agents(0) Hooks(0) post ADR-0015's apm
conversion. Root cause (apm_cli/core/plugin_manifest.py): apm's plugin.json
compiler deliberately strips skills/agents/commands keys, assuming the host
already auto-discovers those convention directories -- it has no model of
.apm/ being host-visible at all. Separately, apm's own bundle exporter
(apm_cli/bundle/plugin_exporter.py, behind `apm pack --format plugin`)
implements the correct .apm/ -> flat mapping, but only ever targeted
build/<name>-<version>/, a path nothing in marketplace.json's source: points
at.

scripts/sync-plugin-content.sh wraps that bundle exporter and copies its
agents/, skills/, commands/, instructions/, extensions/, and merged
hooks.json back into each plugin's own root as a second tracked
compiled-output category -- same governance status as
.claude-plugin/plugin.json: generated from .apm/, never hand-edited. tests/
subdirectories are excluded from the mirror (dev fixtures, not host-visible
runtime content; several hardcode a relative repo-root walk-up sized for the
.apm/-nested depth, which breaks when duplicated one level shallower).
Applied for real across all 6 plugins and verified two ways: `claude plugin
validate --strict` passes on every real plugin directory, and a live
`claude --plugin-dir <path> -p "list skills/agents"` behavioral test
confirms content is now actually discovered.

Also, from the same issue #90 review round:
- scripts/check-manifests.sh pointed at each plugin's root-level plugin.json
  (checking skills/hooks/mcpServers/agents pointer fields) -- that file was a
  stale near-duplicate of .claude-plugin/plugin.json nothing else read or
  wrote, now deleted across all 6 plugins. check-manifests.sh is rewritten to
  validate .claude-plugin/plugin.json instead, and drops the pointer-field
  checks entirely (nothing to check -- those fields are correctly absent by
  design). Content-presence drift is now check-plugin-content-sync's job, a
  new pre-push hook wired in .pre-commit-config.yaml.

docs/adr/0017 records the root cause and decision in full, including two
rejected alternatives (patching plugin.json's path fields directly -- apm's
compiler strips them on every run; pointing marketplace.json at apm pack's
build/ output -- a version-suffixed non-source directory nothing can install
from without an extra build step). ADR-0015 and CONTEXT.md are updated to
point at it.

Refs: #90

2026-08-13 16:59:03 +00:00

3.1 KiB

Raw Blame History

topic, source_keys

topic

source_keys

submodules

git-scm-submodule-docs

Submodules — Deep Reference

Update flag reference

Flag	Meaning
`--init`	Run init first (avoids a separate step)
`--remote`	Use the submodule's remote branch tip instead of the superproject's recorded commit
`--checkout`	Detached HEAD at recorded commit (default)
`--rebase`	Rebase current branch onto recorded commit
`--merge`	Merge recorded commit into current branch
`--recursive`	Operate on nested submodules
`--jobs <n>`	Parallel clone (defaults to `submodule.fetchJobs`)
`-N` / `--no-fetch`	Skip remote fetch
`--depth <n>`	Shallow clone
`--filter <spec>`	Partial clone filter

Workflow patterns

Clone a repo with submodules

git clone --recurse-submodules <url>   # Git 2.13+, one step
# or
git clone <url>
git submodule update --init --recursive

Add a dependency as a submodule

git submodule add https://github.com/org/lib.git libs/lib
git commit -m "chore: add lib as submodule"

Keep submodules pinned to the superproject's recorded commit

git submodule update --recursive   # after every git pull
git config submodule.recurse true  # do this automatically on pull

Update submodules to the latest commit on their tracked branch

git submodule update --remote --merge --recursive
git commit -am "chore: update submodules to latest"

Override a submodule URL locally (private mirror)

git submodule init
# edit .git/config: submodule.<name>.url = <mirror-url>
git submodule update

Local-only override (.git/config, not .gitmodules) — doesn't propagate to collaborators. Re-running sync overwrites it with the .gitmodules URL.

Removal, in full

deinit alone does not remove a submodule — it only clears .git/config and empties the working tree. To fully remove:

git submodule deinit -f <path>   # unregister from .git/config
git rm <path>                     # remove .gitmodules entry + gitlink from index
rm -rf .git/modules/<name>/       # stale git dir; not tracked by git, not auto-cleaned
git commit -m "chore: remove <name> submodule"

.git/modules/<name>/ persisting after git rm will block re-adding the same path until manually deleted.

Relocate an embedded `.git` directory

git submodule absorbgitdirs [<path>...]

Moves a submodule's own .git directory into the superproject's .git/modules/<name>/, linking it back with a .git pointer file. Needed when a submodule was created or copied without going through git submodule add (e.g. converting a plain nested repo into a proper submodule).

`foreach` shell variables

Available inside the <command> argument to git submodule foreach:

Variable	Meaning
`$name`	Logical submodule name
`$sm_path`	Path relative to superproject root
`$displaypath`	Path relative to current working directory
`$sha1`	Recorded commit SHA
`$toplevel`	Superproject's root path

git submodule foreach --recursive '<command>'
git submodule foreach 'git pull origin main || :'   # || : continues past failures

3.1 KiB Raw Blame History