AI-First Tooling (Thundercats)

WhiskerPlatform treats the developer’s AI agent (Cursor, Claude Code, etc.) as a first-class consumer of platform context, on equal footing with the developer. The package that owns this is @nike/whisker-cli — branded Thundercats in the CLI itself (thundercats <subcommand>).

Design north star

Retrieve context so a user’s agent codes and reasons about Whisker better — without bloating the repo with things consumers aren’t meant to manage.

• The @thundercats orchestrator skill is installed once, globally (~/.cursor/skills/thundercats/, via thundercats install-skill) — not per repo. It works in every Whisker project on the machine, and in an empty folder to bootstrap a brand-new one.
• Each repo only carries a thin, self-sufficient always-on rule (.cursor/rules/thundercats-core.mdc) plus a consumer-owned AGENTS.md router — no per-repo skill files to keep in sync.
• Fetched content is local-only (.cursor/external/** is gitignored).
• The source of truth for external content is the canonical source repo, not a Thundercats mirror.
• Consumer-owned skills and rules coexist with Thundercats-managed ones via selective gitignore by prefix.
• Updates are manual (thundercats update per repo, thundercats install-skill per machine) — no bot, no scheduled PR, no autocommit into consumer repos.

What’s built today

Capability	Command	Status
Scaffolding — wraps @nike/create-whisker	thundercats create module|service|monorepo	✅ Real
Add a package to an existing monorepo	thundercats add module|service|lambda	✅ Real
Iframe conversion	thundercats add iframe-consumer	✅ Real
Global skill install — the @thundercats orchestrator	thundercats install-skill	✅ Real — once per machine, not per repo
AI-context install — populates a repo’s .cursor/	thundercats init	✅ Real. create no longer chains this — @nike/create-whisker writes AGENTS.md / .cursor/rules/ itself as the last scaffold step, so it works with zero @nike/whisker-cli installed too. init is now for retrofitting a pre-existing repo; add iframe-consumer still chains it for that reason.
Updates — re-renders managed files	thundercats update	✅ Real for --rules; also migrates/removes obsolete per-repo skill files from older layouts. For module-kind repos, also shells into the locally-installed kit’s own whisker upgrade. Does not self-update the CLI itself first
Audits — read-only diagnostic	thundercats audit	✅ Real — exit 0 clean / 1 drift / 2 blocker
Enumerate the installed global skill	thundercats list-agent-skills	✅ Real — inspects ~/.cursor/skills/
CLI upgrade — explicit Artifactory install	thundercats upgrade	✅ Real — the CLI’s own self-update path (distinct from the module kit’s whisker upgrade — see Scaffolder & Kits)
Per-module maintenance — kit codemods	whisker upgrade (ships from @nike/whisker-module-kit, not thundercats)	✅ Real — dry-run by default, --write to apply; thundercats update calls this for you on module repos
External-skill registration (Tier 3)	thundercats add-skill <pkg-or-url>	⏳ Phase 2D — command exists, prints a deferral notice
Promoted-rule drift	thundercats diff <pkg>	⏳ Phase 2D
Multi-repo scope (--all, --repos, --root)	(flag set)	⏳ Phase 2D — falls back to single-repo today
Host-contract bump	thundercats update --contract	⏳ Phase 2D

There is no tc short alias yet — package.json#bin only exposes thundercats (see Planned).

The three tiers of agent context

Tier	Source	Posture	Examples
1 — Curated specialists	Hand-tuned wrapper templates shipped with Thundercats	Active when the repo declares the matching dep	Podium, WCL
2 — @nike/* deps with AGENTS.md	Auto-discovered from package.json	Auto-installed on clean audience + quality gate pass	Any internal Nike package with a consumer-audience AGENTS.md
3 — Explicit external	thundercats add-skill <pkg-or-git-url>	Always opt-in	Material UI, external docs sites

Tiers 1-3 are all planned/Phase 2D except that the always-on core rule and the global orchestrator + three specialist reference docs below already ship today without needing any external-content pipeline.

The global skill, not per-repo

Earlier iterations rendered a SKILL.md per repo, under .cursor/skills/. That created two problems: Cursor only discovers skills inside the currently open workspace (so a skill in repo A was invisible in repo B, even though the underlying platform knowledge is identical), and every repo’s copy had to be kept in sync by thundercats update even though nothing about the skill’s content is actually repo-specific.

The fix: @thundercats is installed once, globally, at ~/.cursor/skills/thundercats/, via thundercats install-skill. It works in every Whisker repo on the machine, and – because it can also drive @nike/create-whisker’s scaffolder – in an empty folder to bootstrap a brand-new module or service. Each repo keeps only a thin, self-sufficient always-on rule; thundercats update no longer needs to touch any skill files, and migrates away (deletes) orphaned per-repo skill directories left over from the old layout.

.cursor/ layout today

.cursor/                                          <- partly gitignored
  rules/thundercats-core.mdc                      <- only always-applied rule (managed)
  .thundercats.manifest.json                      <- sidecar tracking managed-file hashes
AGENTS.md                                         <- consumer-owned router (repo root, preserved across updates)

~/.cursor/skills/thundercats/                     <- global, machine-wide, NOT part of any repo
  SKILL.md                                        <- orchestrator (@thundercats)
  module-author.md                                <- UI module pages/widgets/nav specialist reference
  bff-service-author.md                           <- BFF routes/auth specialist reference
  manifest-validator.md                           <- config/compliance specialist reference

A consumer can author their own skills, rules, and slash-commands side-by-side in the repo; only the thundercats-* / external-* prefixes under .cursor/rules/ are gitignored. The orchestrator’s user-facing name is @thundercats.

The three specialist references

Each is authored at platform-docs depth, grounded in the actual @nike/whisker-module-kit and @nike/whisker-service-kit source. They are plain markdown files living alongside SKILL.md in the global skill folder – not separate skills themselves – and @thundercats reads exactly one of them per delegation, never all three upfront:

Reference	Covers
module-author.md	Full manifest schema reference, federation exposes rules, the host shared-deps contract, navigation/page/widget recipes, WCL -> Podium -> MUI composition order
bff-service-author.md	The real Express + node-file-router stack, middleware boot order, per-route auth guard composition, OTel recipes
manifest-validator.md	The three-file ownership map (moduleManifest.ts vs module-manifest.json vs whisker.config.json), pinnedHostContractVersion, compliance-tag contract

All three hand back to @thundercats for cross-specialist coordination.

How a consuming repo gets the AI surface

# Once per machine - installs the global @thundercats skill
thundercats install-skill

# Scaffolding a new project - @nike/create-whisker populates .cursor/ itself
# as the last scaffold step (no separate init call happens under the hood)
thundercats create module my-module

# Onboarding an existing Whisker repo that create-whisker didn't scaffold -
# one-time per repo
thundercats init

# Refresh managed files in this repo (also migrates away stale per-repo
# skills, and for module repos runs the kit's own `whisker upgrade`)
thundercats update

# Read-only diagnostic
thundercats audit

# Inventory the installed global skill
thundercats list-agent-skills

# After `thundercats upgrade`, refresh the global skill too
thundercats install-skill

Why this design, not the rejected alternatives

Rejected idea	Why we said no
Stuff knowledge inside the kits	Nike-org rules don’t belong in Whisker-team files; blocks cross-platform reuse
Hard runtime dep on a spec-driven framework	Thundercats stays convention-aligned instead – see OpenSpec for the co-install path we designed for instead
MCP server with on-demand fetching	Deferred – live-fetch-on-update gets most of the value at a fraction of the infra cost
CI-bundled snapshots of external content	Would duplicate other teams’ content into our release cadence and go stale within hours
PR-bot that auto-updates consumers’ repos	Moot – managed content is gitignored, nothing for a bot to PR against

Planned / proposed

• tc short binary alias — decided but not shipped.
• Self-update by default on thundercats update — this is specifically about the CLI binary itself: today only the separate thundercats upgrade command self-updates @nike/whisker-cli; update doesn’t call it first. This needs a product decision on which behavior is intended. (Not to be confused with the module kit’s own whisker upgrade, which thundercats update already does call on every run for module repos — that ships today.)
• External-skills pipeline (Phase 2D) — Tier 1/2/3 content (Podium, WCL, opt-in third parties), a centralized ~/.thundercats/cache/, a GitHub fetcher, audience + quality gates, an optimizer that generates slim wrapper rules, and thundercats diff <pkg> / add-skill --re-anchor drift tooling. None of this is coded yet.
• Multi-repo scope (--all / --repos / --root) — ships bundled with the external-skills pipeline since they share per-repo plumbing.
• thundercats update --contract — pairs with the host-contract enforcement work in Host ↔ module contract.
• WCL AGENTS.md hierarchy — parallel workstream in the WCL repo; must ship before the Tier 1 specialist can flip from placeholder: true in the (also not-yet-built) Tier 1/2/3 registry.

See Risks & improvements for the full backlog and pickup criteria (also tracked in whisker-platform/DEFERRED.md).