feat(plugin): [nasde.plugin] + skill-by-reference ([[skill]])

[szjanikowski]

What

Mirror [nasde.source] for local Claude Code plugins and add a lighter
skill-by-reference path, removing the snapshot / triple-copy tax that
plugin-exercising benchmarks pay today.

[nasde.plugin] in task.toml

One declaration ships a local plugin dir (.claude-plugin/plugin.json) into
the sandbox image and registers it for the agent:

[nasde.plugin]
path = "../../../src/plugins/my-plugin"
ref = "abc1234"                           # reproducible, like [nasde.source]
install_root = "/opt/my-plugin"
build = "bun install --frozen-lockfile"
[nasde.plugin.env]
CLAUDE_PLUGIN_DATA = "/opt/my-plugin-data"

• config.PluginConfig + [nasde.plugin] parser, next to SourceConfig.
• docker.ensure_task_plugin() stages the plugin (at ref via a temp git
  worktree) into a gitignored _nasde-plugin/ inside the active build
  context, then appends a sentinel-fenced COPY+build stage to the
  Dockerfile.
• plugin_registration.py registers the plugin's own skills/ (whole dirs)
  and injects its MCP server (from <plugin>/.mcp.json, env-wrapped) into
  task.toml.

Skill-by-reference: [[skill]] in variant.toml

[[skill]]
path = "../../../src/plugins/my-plugin/skills/my-skill"
ref  = "abc1234"

Reference a skill from a source path instead of copying it into
variants/<v>/skills/. Whole dir (incl. references/) staged; feeds the
same stage_skill_dir machinery as the plugin path.

End-to-end validation (both faces, on real benchmarks)

Beyond the 192-test unit suite, both features were exercised on real
benchmarks running the full pipeline (Docker build + agent in sandbox +
verifier + LLM evaluator):

[[skill]] on examples/nasde-dev-skill (dogfooding)

• Three existing variants migrated from drift-prone copy-into-variants/
  (claude-nasde-dev-full-stack, -with-arch, -with-testing) to
  [[skill]] referencing the live .claude/skills/nasde-dev/.
• The pre-migration copies had already drifted from the live source
  (SHA ec43ca37e668 vs live 073822c1b52b) — exactly the failure mode
  this feature exists to eliminate.
• Full run of claude-nasde-dev-full-stack (3 skills mixed: 1 by-ref + 2
  legacy copy): verifier reward=1, evaluator score 100/125 (0.80).
  Sandbox SHA matches live source — drift eliminated.

[nasde.plugin] on SDLC evals/analyze-conversation (the motivating downstream)

This is the benchmark whose README explicitly documents the
snapshot-refresh workaround that [nasde.plugin] was designed to remove.
Migrated in the SDLC repo (separate commit 403c253):

• Deleted vendored _plugin-staging/ (~210 files) — replaced by [nasde.plugin]
• Deleted hand-wired [[environment.mcp_servers]] — auto-injected by nasde
• Deleted variants/with-skill/skills/analyze-conversation/ copy —
  plugin skills auto-registered

Full pipeline run with this nasde branch installed locally, against the
migrated benchmark, exercised the baked noesis plugin's MCP server end to
end: verifier reward=1, matching the pre-migration baseline. Confirms
the feature replaces the entire snapshot/MCP/variant-skill workaround on
its motivating real case, in one task.toml declaration.

Design decisions

• Build-context strategy: stage into the active context. Harbor pins the
  Docker context to environment/. The plugin is staged into a gitignored
  _nasde-plugin/ inside whatever context is active — environment/ for
  plugin-only / hand-written-Dockerfile, the source repo/worktree when
  [nasde.source] redirected the compose context (nasde reads it back from
  the generated compose). A base Dockerfile is generated only when there is
  no source and no real Dockerfile content; hand-written Dockerfiles are
  preserved verbatim with the stage appended before any trailing CMD.
• Shared skills/MCP registration. plugin_registration.stage_skill_dir
  is the single mechanism for plugin skills, plugin-[[skill]]-by-reference,
  and the legacy variants/<v>/skills/ copy path. This also fixes a
  latent bug: the variant copy path previously mapped only SKILL.md,
  silently dropping references/ (breaking skills like
  analyze-conversation that read references/*.md at runtime).
• MCP injection writes task.toml. Harbor reads MCP servers only from
  task.config.environment.mcp_servers (trial.py:188). The block is
  sentinel-fenced, idempotent, visibly generated, and respects an
  author-declared same-name server (logs + skips, never clobbers) — the same
  "generate in place where the tool reads it" pattern nasde already uses for
  environment/Dockerfile / docker-compose.yaml.
• Skill-by-reference shape: a [[skill]] array in the existing
  variant.toml (no new file, variant-scoped) — per maintainer preference.

Files changed

File	Change
src/nasde_toolkit/config.py	PluginConfig dataclass + [nasde.plugin] parser
src/nasde_toolkit/docker.py	ensure_task_plugin(), StagedPlugin, plugin staging + Dockerfile stage, public create_ref_worktree
src/nasde_toolkit/plugin_registration.py	new — shared skill+MCP registration
src/nasde_toolkit/runner.py	wire plugin/skill staging; merge derived sandbox files; fix _collect_claude_skills to carry whole dir
src/nasde_toolkit/scaffold/__init__.py	scaffold .gitignore ignores _nasde-plugin/
.gitignore	ignore **/_nasde-plugin/
examples/nasde-dev-skill/variants/*	dogfooding: 3 variants migrated to [[skill]], drifted copies deleted
docs/adr/009-…md	new ADR covering both faces
README.md, docs/use-cases.md, CHANGELOG.md, CLAUDE.md	docs
pyproject.toml, uv.lock	security pins (idna>=3.15, urllib3>=2.7.0)
tests/test_config_plugin.py, tests/test_docker_plugin.py, tests/test_plugin_registration.py, tests/test_runner_skills.py	new — 33 tests

Verification

uv run pytest -q                # 192 passed (159 existing + 33 new)
uv run ruff check src/ tests/   # clean
uv run ruff format --check      # clean
uv run mypy src/nasde_toolkit/  # clean

Existing examples/ benchmarks still load unchanged (plugin = None) for
benchmarks without [nasde.plugin].

Backward compatibility

No [nasde.plugin] / [[skill]] → behaviour is byte-for-byte as before.
Existing variants/<v>/skills/ copies keep working (and now correctly
carry references/ — a strict improvement, also validated in the
nasde-dev-skill migration where python-best-practices / python-testing
remain as legacy copies and continue to work alongside the new [[skill]]
entries).

CI status

Check	Status
Lint (ruff), Type check (mypy)	✅
Unit tests (ubuntu × windows × py3.12 / py3.13)	✅
Validate benchmark configs	✅
Docker build benchmarks	✅
CVE audit (pip-audit)	❌ pyjwt PYSEC-2025-183

The CVE audit failure is environmental and pre-existing: PYSEC-2025-183
is a disputed advisory on pyjwt 2.12.1 (upstream maintainer: "the key
length is chosen by the application that uses the library") with no
upstream fix available — 2.12.1 is the latest release. pyjwt is
transitive via supabase/opik, not used directly by nasde-toolkit. The
same audit fails identically on main once re-run (last green main run is
2026-05-09, before PYSEC-2025-183 was published 2025-07-31). Will be
addressed in a separate dependency-policy PR at release time.

Downstream follow-up

The SDLC analyze-conversation migration referenced above lives on a
separate branch in the SDLC repo and will land there after this PR is
merged. The draft-to-design-doc/ benchmark in SDLC can be migrated the
same way (separate PR, separate repo).

🤖 Generated with Claude Code