AGENTS.md git:20261102.dfe6aa7A

Immutable. This exact content never changes and is served at /api/v1/blob/793726dc23a1d5df.

# CubeCloud Skills Bundle — Copilot Instructions

## What this repo is

A Windows PowerShell toolkit (no application code — **scripts are the product**) that installs a
global VS Code Copilot Chat stack: 275 bundle skills (302 on disk incl. 27 Azure/Entra/Foundry
extension skills), 20 CLIs, 12 MCP servers, 55 fork mirrors, 74 DESIGN.md files — all gated by
NVIDIA SkillSpector. The source of truth for every count is [README.md](README.md) (badges +
"What you get" table); [setup/SETUP_GUIDE.md](setup/SETUP_GUIDE.md) documents phases and
verification; [CHANGELOG.md](CHANGELOG.md) records dated fixes. Link, don't duplicate.

## Layout map

| Path | Role |
| --- | --- |
| `setup/setup-global-skills.ps1` | Global installer (phases 0–7) — see "Installer surface" below |
| `setup/skills-list.csv` | **Pipe-delimited** manifest: `repo\|name\|skillRelPath\|disabled[\|localSourcePath]`; `local/*` rows point at vendored clean-ports under `upstream/` |
| `bin/*.ps1` | Audit/repair/verify scripts; shared prelude in `bin/lib/bundle-common.ps1` (PATH prepend + `PYTHONUTF8=1`, repo-root discovery, MCP template cross-check), emit Markdown reports into `~/dev/upstream/` (`AUDIT_REPORT.md`, `MCP_SMOKE_TEST.md`) or console PASS/MISS/FAIL lines |
| `upstream/` | Vendored skill sources for `local/*` manifest rows — mix of methodology-only clean ports (`archify`, `webapp-testing`, `idea-to-design`) and adapted copies (`agent-reach`) |
| `docs/plans/` | Dated evaluation/plan reports |
| `plans/001-local-addon-sourcepaths.md` | **Closed P1 fix (DONE)** — see "Closed: plan 001" below |

## Full verification routine (run this, in order)

Use `bin/full-audit.ps1` — the canonical, **parameter-less** audit. It is self-contained
(no sub-script calls), runs 7 inline phases, and writes `~/dev/upstream/AUDIT_REPORT.md`:
MCP `mcp.json` + 6 daemon liveness probes → 10 CLI version probes → `skills-ref validate`
per skill → SKILL.md frontmatter check → `~/.claude/skills` mirror parity → disabled/docs/forks
existence → SkillSpector re-scan. Final line: `PASS: N | FAIL: N | WARN: N | ADVISORY: N`.
WARN and ADVISORY are counted separately — report both, never a unioned count.

The two WARN rows that were permanent until 2026-11-02 now clear, and both were real:
- **MCP daemon WARN** — an unreachable `HTTP_PROXY` (inherited from the parent shell) makes
  every `npx`/`uvx` launcher die with `error sending request`, before the server is reached.
  That is the shell environment, not the bundle. The audit now labels it as such instead of
  reporting a bare "exited early". `scrapling` had a *separate* real fault: `scrapling[ai]`
  declares `mcp>=1.27.0` with no upper bound, so it resolved `mcp 2.x`, which renamed
  `mcp.server.fastmcp` → `mcp.server.mcpserver` and broke the import. Pinned `mcp<2` in
  `setup-global-skills.ps1` and `bin/safe-update-pass.ps1` (which is what re-broke it).
- **MIRROR parity WARN** — 27 Azure/Entra/Foundry extension skills are provisioned by VS Code
  into `~/.agents/skills` only, so they can never be mirrored. Parity now excludes them,
  but **only when they are not manifest rows**: `airunway-aks-setup` matches the extension
  prefix yet is a real `local/*` manifest row, and excluding it by prefix would have masked
  the genuine gap that was just repaired by re-running `install-skill.ps1 -SourcePath`.

For fast iterations when MCP daemons are irrelevant or would hang the run, `bin/fast-audit.ps1`
is the same result-matrix minus daemon tests. For a quick global-state check,
`bin/verify-state.ps1` is console-only (PASS/MISS/FAIL/INFO, exit 1 on failure) and reads the
expected MCP set from `setup/mcp.json.template` (the single source of truth; leaf-name
normalization means gallery installs don't read as missing).

Smoke-testing MCP servers in isolation: `bin/mcp-smoke-test.ps1` (deterministic `--help` probes,
writes `~/dev/upstream/MCP_SMOKE_TEST.md`, no hanging daemons). In VS Code, the verified path is
the `verify-global-bundle` workspace task → `bin/verify-global-bundle.ps1` (avoids large inline
`-Command` quoting failures); it delegates MCP validation to `bin/validate-mcp.ps1`, which now
exits non-zero when a bundle server is absent (it previously never failed).

## Verification = counters + counts, every time

A session is only "done" when the numbers reconcile. Check all four:
1. `bin/full-audit.ps1` → report the PASS/FAIL/WARN/ADVISORY line explicitly.
2. `(Get-ChildItem ~/.agents/skills -Directory).Count` vs README badge (302 on disk / 275 bundled).
3. `~/.agents/skills._disabled/` count vs README (45 manifest comment rows parked; 14 folders on
   disk: 1 upstream `caveman` + 13 Copilot-incompatible ports).
4. Manifest row count in `setup/skills-list.csv` (275: regex `^[a-zA-Z][^|#]*\|`) vs README "275".
   Comment/blank lines do not count. If numbers diverge, fix counters inline **and the truth**.

## Post-merge workflow

After merging from `origin/main` or installing any new skills batch:
1. Run the full verification routine above (or at minimum `bin/full-audit.ps1`) and report PASS / FAIL / WARN counts.
2. Re-check all four counter reconciliations. If they diverge, flag it before claiming completion.

## Closed: plan 001 `local/*` installs (fixed + verified)

Plan [plans/001-local-addon-sourcepaths.md](plans/001-local-addon-sourcepaths.md) is the gate for
"fully verified": `local/impeccable-audit`, `local/impeccable-craft-floor` etc. rows in the CSV are
rewritten into bogus GitHub clone URLs by the installer, so the clean-port replacements for
SkillSpector-blocked upstreams silently never install (**P1/M/MED**). Verified fix: the installer
must pass `-SourcePath` (already supported by `bin/install-skill.ps1`) for `local/*` rows. Do not
declare full verification complete while this plan is open; run its drift-check
(`git diff --stat b5c05f2..HEAD`) and respect its STOP conditions before editing.

## Installer surface (know before touching setup-global-skills.ps1)

`[CmdletBinding()]` switches: `-SkipForks`, `-SkipAudit`, `-IncludeAdditionalEditorProfiles`
(MCP + model pins for Code-Insiders/Cursor/VSCodium), `-IncludeArchifyCli` (opt-in 86-byte
`~/.local/bin/archify.cmd` shim; needs fork mirrors — incompatible with `-SkipForks`, warns and
continues). Phases: 0 prereqs (uv/bun) · 0b PATH+PYTHONUTF8 persist · 0c dir skeleton ·
1 SkillSpector+skills-ref · 1b helper + suppression baselines to `~/dev/` · 2 20 CLIs · 3 clone 55 forks ·
3b archify shim · 4 install 275 manifest skills (security-gated) · 5 write 12 MCP servers to
`User/mcp.json` · 5b Copilot utility model pins · 5c SkillOpt-Sleep nightly task · 6 governance
docs · 7 audit.

## Suppression baselines are applied by the gate (fixed 2026-10-12)

`skillspector scan` alone re-blocks any reviewed skill on every install. `setup/install-skill.ps1`
now resolves a suppression baseline and passes `--baseline`, in this order: explicit
`-BaselinePath`, then `<repoRoot>\baselines\<name>.baseline.yaml`, then
`~/dev/baselines\<name>.baseline.yaml`, then `$env:SKILL_BASELINES_DIR\<name>.baseline.yaml`.
Phase 1b of the installer deploys `baselines/*.baseline.yaml` to `~/dev/baselines/` alongside the
helper. Verified end-to-end: `diagram-design` exits 1 (hard block) without the baseline and 0
(pass) with it. The scan-log row now records `baseline:<file>|none` for traceability. When a skill
is parked or gated, check for a baseline before assuming the scanner disagrees.

## `install-missing-skills.ps1 -WhatIf` does NOT prevent installs

Verified 2026-09-13. `-WhatIf` only gates the **refresh** path (via
`$PSCmdlet.ShouldProcess`). The **install** path calls `install-skill.ps1` as a child process
with no `-WhatIf` propagation, so it **really installs everything**.

Do not treat `-WhatIf` as a dry run. It is not safe to run for a preview. If you want a
preview, read `skills-list.csv` directly instead — the rows are the plan. To genuinely verify
without installing, check source-path existence for each row.

## Two fork names are deliberately NOT the upstream repo name

`install-skill.ps1` clones `JZKK720/<last-path-segment>`. Two candidates collided with
unrelated pre-existing forks, so both were forked under a new name:

| Upstream | Naive name (already taken by) | Actual fork |
| --- | --- | --- |
| `tech-leads-club/agent-skills` | `agent-skills` (addyosmani/agent-skills — **this bundle's active mirror**) | `tech-leads-club-agent-skills` |
| `openai/skills` | `skills` (vercel-labs/skills) | `openai-skills` |

Never "simplify" these names. A naive clone of the tech-leads-club repo into `agent-skills`
would overwrite the addyosmani mirror that 23 manifest rows depend on.

## Escaped-dollar in `git clone` lines is a silent failure

`setup-global-skills.ps1` had two clone lines written as `` `$"var`" `` (backtick-dollar = an
escaped literal `$`). Those interpolated nothing, so the clone command received a literal
`$<path>` argument and failed silently under `>nul 2>nul`. Effect: `archify` and `book-to-skill`
mirrors were never created by the installer. Fixed 2026-09-13.

When adding a clone line, confirm the variable is `"$var"` (no backtick) and that the
directory actually appears afterward — `>nul 2>nul` hides every error.

## Large install batches (10+ skills)

When installing 10+ skills in one session, start each batch in its own sub-process invocation so a single skill failure doesn't orphan the rest. If the batch exceeds ~20 skills, suggest a fresh chat or `/compact` to avoid context exhaustion mid-batch.