headlamp-plugin: add opt-in --with-claude-skills to create/upgrade

[yolossn]

headlamp-plugin: opt-in Claude Code agent harness (--with-claude-skills)

What

Adds an opt-in --with-claude-skills flag to headlamp-plugin create and
headlamp-plugin upgrade that scaffolds a Claude Code agent harness for
building a Headlamp plugin with an AI agent.

The harness:

• CLAUDE.md — always-on agent policy (replaces the default AGENTS.md)
• .claude/skills/ — the CNCF/CRD plugin workflow: create-cncf-plugin,
  plan-plugin, define-resource, add-list-view, add-detail-view,
  add-settings, ensure-dependency, seed-test-data, run-and-verify,
  document-plugin
• .claude/settings.json — permission allowlist for common dev commands
• .mcp.json — kubernetes, helm and chrome-devtools MCP servers

How

• Harness lives in a separate template-claude/ folder (shipped via
  package.json files), so the default scaffold path is byte-for-byte
  unchanged unless the flag is passed.
• create --with-claude-skills copies it over the fresh scaffold.
• upgrade --with-claude-skills opts an existing plugin in, adding only
  missing files (overwrite: false) so user customizations are preserved —
  safe to re-run.
• When the harness is present, CLAUDE.md is the single agent guide: AGENTS.md
  is dropped on add, and upgrade's addMissingTemplateFiles no longer
  reintroduces AGENTS.md once CLAUDE.md exists.

Usage

headlamp-plugin create my-plugin --with-claude-skills   # new plugin
headlamp-plugin upgrade --with-claude-skills            # existing plugin

Tests

• Added create/upgrade assertions to test-headlamp-plugin.js (harness added,
  AGENTS.md dropped, no-flag upgrade doesn't reintroduce AGENTS.md).
• Documented the flag in the README.
• Verified npm pack --dry-run ships all template-claude/ files (incl. the
  .claude/ dotdir and .mcp.json).

How to test manually

Setup

Run from the headlamp-plugin package dir:

cd plugins/headlamp-plugin
npm install          # one-time, so the CLI can boot (you may have this already)
BIN="$PWD/bin/headlamp-plugin.js"
cd /tmp              # scratch area for generated plugins

1. Default create is unchanged (regression guard)

rm -rf t-default
node "$BIN" create t-default --noinstall
ls -a t-default        # expect AGENTS.md, .vscode, .gitignore, src/, package.json
test -e t-default/AGENTS.md  && echo "AGENTS.md present ✓"
test -e t-default/CLAUDE.md  && echo "CLAUDE present ✗" || echo "no CLAUDE.md ✓"
test -e t-default/.mcp.json  && echo ".mcp present ✗" || echo "no .mcp.json ✓"
test -d t-default/.claude    && echo ".claude present ✗" || echo "no .claude ✓"

Expect: AGENTS.md present; no CLAUDE.md / .mcp.json / .claude.

2. create --with-claude-skills adds the harness, drops AGENTS.md

rm -rf t-claude
node "$BIN" create t-claude --noinstall --with-claude-skills
test -e t-claude/CLAUDE.md            && echo "CLAUDE.md ✓"
test -e t-claude/.mcp.json            && echo ".mcp.json ✓"
test -e t-claude/.claude/settings.json && echo "settings.json ✓"
echo "skills: $(ls t-claude/.claude/skills | wc -l | tr -d ' ')"   # expect 10
test -e t-claude/AGENTS.md && echo "AGENTS.md present ✗" || echo "AGENTS.md dropped ✓"
test -e t-claude/src/index.tsx && test -d t-claude/.vscode && echo "default files intact ✓"

Expect: CLAUDE.md + .mcp.json + .claude/settings.json + 10 skills; no AGENTS.md; default scaffold files still present.

3. upgrade --with-claude-skills opts an existing plugin in

rm -rf t-upgrade
node "$BIN" create t-upgrade --noinstall          # starts as a default plugin
test -e t-upgrade/AGENTS.md && echo "starts with AGENTS.md ✓"

node "$BIN" upgrade t-upgrade --skip-package-updates --with-claude-skills
test -e t-upgrade/CLAUDE.md && echo "CLAUDE.md added ✓"
test -e t-upgrade/.mcp.json && echo ".mcp.json added ✓"
echo "skills: $(ls t-upgrade/.claude/skills | wc -l | tr -d ' ')"   # expect 10
test -e t-upgrade/AGENTS.md && echo "AGENTS.md present ✗" || echo "AGENTS.md dropped ✓"

--skip-package-updates keeps it fast/offline (skips npm audit/format/lint/tsc). Drop it for a full upgrade run.

Expect: harness added, AGENTS.md dropped.

4. Safety: plain upgrade (no flag) doesn't disturb a harness plugin

node "$BIN" upgrade t-upgrade --skip-package-updates    # no flag this time
test -e t-upgrade/AGENTS.md && echo "AGENTS.md reappeared ✗" || echo "AGENTS.md still gone ✓"
test -e t-upgrade/CLAUDE.md && echo "CLAUDE.md intact ✓"

Expect: AGENTS.md stays gone, CLAUDE.md intact (the guard at work).

Optional — confirm a plain upgrade on a default plugin still re-adds AGENTS.md if deleted:

rm t-default/AGENTS.md
node "$BIN" upgrade t-default --skip-package-updates
test -e t-default/AGENTS.md && echo "AGENTS.md restored on default plugin ✓"

5. --help shows the new options

node "$BIN" create --help   | grep -i claude     # shows --with-claude-skills
node "$BIN" upgrade --help  | grep -i claude     # shows --with-claude-skills

6. Packaging — the harness ships in the npm tarball

cd plugins/headlamp-plugin
npm pack --dry-run 2>/dev/null | grep template-claude   # expect 13 entries incl .claude/* and .mcp.json

7. (Optional) Full automated suite

This runs the create/upgrade assertions plus build/lint/tsc/storybook — slow (does real installs), needs network:

cd plugins/headlamp-plugin
node test-headlamp-plugin.js

8. (Optional) Real load test in Headlamp

For a true smoke test of a generated harness plugin (not just file checks):

cd /tmp/t-claude
npm install        # real install
npm start          # builds into Headlamp's dev-plugins dir; open the desktop app

Cleanup

rm -rf /tmp/t-default /tmp/t-claude /tmp/t-upgrade

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: yolossn

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [yolossn]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[yolossn]

closing this in favor of #6096