stackfit 0.0.0-stage → 0.1.1

package/starter/skills/stackfit/references/configuration.md

@@ -0,0 +1,136 @@
+# stackfit configuration reference
+
+All files are JSON. Schemas: `https://unpkg.com/stackfit/schemas/<name>.schema.json`.
+
+## stackfit.json (catalog registry)
+
+```json
+{
+  "$schema": "https://unpkg.com/stackfit/schemas/stackfit.schema.json",
+  "schemaVersion": 3,
+  "projectConfigPath": "docs/agent/config.json",
+  "skills": ["grilling", "next-server-security", "shadcn", "my-checkout-rules"],
+  "packs": {
+    "core":   { "description": "Every repo.", "always": true, "skills": ["grilling"] },
+    "nextjs": { "detect": { "dependencies": ["next"] }, "skills": ["next-server-security"] },
+    "shadcn": { "detect": { "files": ["components.json"] }, "skills": ["shadcn"] },
+    "shop":   { "description": "Opt-in.", "skills": ["my-checkout-rules"] }
+  },
+  "adapters": {
+    "agents": ["reviewer.md"],
+    "commands": ["handoff.md"],
+    "rules": ["defaults.mdc"]
+  }
+}
+```
+
+- `skills`: the enabled catalog. A skill reaches a project only through a pack or a project's `skills` list.
+- `packs.<name>.always`: every project gets it; cannot be excluded.
+- `packs.<name>.detect.dependencies`: dependency names (case-insensitive) from `package.json` (all dependency fields), `requirements*.txt`, `pyproject.toml`, `go.mod` (module paths), `Cargo.toml`, `composer.json`.
+- `packs.<name>.detect.files`: file or folder names present at the root, a top-level folder, or one level below it (`components.json`, `go.mod`, `release-please-config.json`).
+- A pack with neither `always` nor `detect` is opt-in.
+- `adapters`: files under `agents/`, `commands/`, `rules/` synced to every project.
+
+## skill-sources.json (provenance and overrides)
+
+```json
+{
+  "schemaVersion": 2,
+  "skills": {
+    "my-checkout-rules": { "kind": "custom", "reviewed": "2026-10-26" },
+    "shadcn": {
+      "kind": "external",
+      "source": { "repository": "https://github.com/shadcn-ui/ui.git", "path": "skills/shadcn" },
+      "reviewed": "2026-10-26",
+      "render": {
+        "frontmatter": { "description": "Add, search, and style shadcn/ui components. Use with components.json." },
+        "exclude": ["evals/evals.json"]
+      }
+    }
+  }
+}
+```
+
+- `kind`: `custom` (owned in the catalog) or `external` (vendored, refreshable).
+- `source`: Git repository + folder holding `SKILL.md`. Required for `refresh`.
+- `reviewed`: last date someone checked the skill is current and worth its context. `audit` warns after 180 days.
+- `render.frontmatter`: replaces top-level SKILL.md frontmatter keys at sync time (`null` removes a key). Survives `refresh`. Typical: shorter `description`, `"disable-model-invocation": true`, `name` when the upstream folder name differs.
+- `render.exclude`: skill-relative files never copied into projects (evals, READMEs, compiled `AGENTS.md` duplicates).
+- `skill-sources.lock.json` (written by `refresh`): upstream commit of each vendored skill.
+
+## docs/agent/config.json (per project, tracked)
+
+```json
+{
+  "schemaVersion": 1,
+  "packs": ["motion"],
+  "excludePacks": ["stripe"],
+  "skills": ["ui-ux-pro-max"],
+  "disabledSharedSkills": ["ponytail"],
+  "detect": true,
+  "overrides": { "skills": [], "agents": [], "commands": [], "rules": [] }
+}
+```
+
+- `packs`: add packs (opt-in ones, or ones detection missed).
+- `excludePacks`: drop detected packs (`core`/`always` packs stay).
+- `skills`: add single catalog skills without their pack.
+- `disabledSharedSkills`: remove single skills, applied last.
+- `detect: false`: only `always` packs plus what is listed.
+- `overrides.<kind>`: names of repo-owned components allowed to replace shared ones with the same name.
+
+Repo-owned components (tracked in the project, synced next to shared ones):
+- `docs/agent/skills/<name>/SKILL.md`
+- `docs/agent/rules/<name>.md`: add `globs:` (becomes Claude `paths:`) or `alwaysApply: true`; otherwise it stays Cursor-only and is routed through `AGENTS.md`.
+- `docs/agent/commands/<name>.md`, `docs/agent/agents/<name>.md`
+
+## stackfit.local.json (per machine, gitignored)
+
+```json
+{
+  "schemaVersion": 1,
+  "machines": [
+    {
+      "id": "mac",
+      "match": { "platform": "darwin" },
+      "roots": ["~/code", "~/work"],
+      "projects": [
+        "shop-web",
+        { "name": "client-site", "scaffold": false, "packs": ["motion"], "excludePacks": ["stripe"] }
+      ]
+    },
+    { "id": "work-pc", "match": { "platform": "win32", "hostname": "WORK-PC" }, "roots": ["C:/dev"] }
+  ]
+}
+```
+
+- `match.platform`: `darwin`, `win32`, or `linux`. `match.hostname` (optional) wins over platform-only entries.
+- `roots`: absolute, `~/`, or relative to the catalog.
+- `projects` (optional): only these folders under the roots. Without it, every Git repo directly under a root is synced.
+- `scaffold: false`: adapter-only. stackfit never reads or creates the repo's `docs/agent/`, and keeps `CLAUDE.md` and `docs/agent/` git-excluded. Put that repo's pack choices here instead.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `STACKFIT_CATALOG` | Catalog folder, so stackfit works from anywhere |
+| `STACKFIT_LOCAL_CONFIG` | Another machine-profile file |
+| `GITHUB_TOKEN` | Private repositories for `refresh` (sent as a header, never stored) |
+| Anything else | Fills `{{env:NAME}}` in commands, rules, and agents |
+
+Read from the shell, `./.env`, then the catalog's `.env`; shell values win. A missing variable prints a warning and leaves the placeholder.
+
+## What gets written where
+
+| Catalog item | Claude Code | Cursor | Codex |
+| --- | --- | --- | --- |
+| Skills | `.claude/skills` → `.agents/skills` | `.cursor/skills` → `.agents/skills` | `.agents/skills` |
+| `alwaysApply` rule | `.claude/rules/<n>.md` | `.cursor/rules/<n>.mdc` | not auto-loaded; point to it from `AGENTS.md` |
+| `globs` rule | `.claude/rules/<n>.md` with `paths:` | `.cursor/rules/<n>.mdc` | not auto-loaded |
+| Description-only rule | not rendered | `.cursor/rules/<n>.mdc` | not auto-loaded |
+| Command | `.claude/commands/<n>.md` (manual-only) | `.cursor/commands/<n>.md` | use a skill |
+| Agent | `.claude/agents/<n>.md` (`model: inherit`) | `.cursor/agents/<n>.md` | n/a |
+
+Links are symlinks on macOS/Linux and directory junctions on Windows (no admin rights needed).
+
+Git: stackfit lists exactly the files it generates (plus `.agents/` and the two skill links) in a managed block in `.git/info/exclude`, so they never show up in `git status`, while the user's own files in `.claude/` or `.cursor/` stay visible. Files in `docs/agent/` are not excluded: commit them.

package/starter/skills/stackfit/references/recipes.md

@@ -0,0 +1,182 @@
+# stackfit recipes
+
+Each recipe lists the commands and files in order. Always run `status` before `sync` and show the user the result.
+
+## 1. See what a repo loads, and why
+
+```bash
+npx stackfit report --project .
+npx stackfit report --root ~/code          # every Git repo directly under ~/code
+npx stackfit report --all --json           # machine profile, for scripts
+```
+
+Explain each column:
+- `skills` = skills this repo gets (catalog packs + its own `docs/agent/skills`).
+- `skill listings` = estimated tokens of those skills' names + descriptions, loaded in every session (about 4 characters per token). Bodies load only when a skill is used; manual-only skills count 0.
+- `rules` = always-on rules (Claude `.claude/rules` without `paths:`), loaded in full every session.
+- `per session` = the two together.
+- `packs` = why: each pack was `always`, detected, or requested.
+- The `Global skills add ...` line is what `~/.claude/skills` and similar folders cost in every repo regardless of stackfit (`No global skill folders found` when there are none). Compare `per session` with it: that is the honest before/after once global copies are moved into the catalog. Note it before cleaning up globals.
+
+If a pack looks wrong, find the signal: `grep -r '"<dependency>"' --include=package.json .` (or the matching manifest), or check for the marker file. Fix with recipe 4.
+
+## 2. First-time setup
+
+Follow "Set up stackfit for someone's repos" in SKILL.md (baseline → catalog → preview → write → machine profile → clean up globals → report). Extras:
+
+- Keep the catalog in a private Git repo (`git init` in it, push it) so other machines and teammates can use it (recipes 5, 9).
+- A catalog outside `~/.stackfit` is found via `--catalog <dir>`, `STACKFIT_CATALOG` (shell or `./.env`), or by running stackfit inside it.
+- `npx stackfit init --project <repo>` adds a tracked `AGENTS.md`, `CLAUDE.md` (`@AGENTS.md`), and `docs/agent/` pages for repo-specific context. It never overwrites, but ask first: these are files the user will commit.
+
+## 3. Migrate existing skills and rules into stackfit
+
+Typical starting points: `~/.claude/skills/`, a repo's `.claude/skills/` or `.cursor/rules/`, an `.agents/skills/` folder from `npx skills add`.
+
+1. Sort each item:
+   - Useful in many repos → catalog: `<catalog>/skills/<name>/SKILL.md` (or `rules/<name>.mdc`).
+   - Specific to one repo → that repo: `docs/agent/skills/<name>/SKILL.md` (or `docs/agent/rules/<name>.md`).
+   - Generic knowledge the model already has → suggest dropping it.
+2. For catalog skills, copy the folder into `<catalog>/skills/<name>/` (copy, don't move: the global copy is handled by setup step 6), then register it:
+   - add the name to `skills` in `stackfit.json` and to a pack. Pick the pack by who needs it: an `always` pack (`core`) for every repo; a detect pack keyed on the base dependency for stack skills (`react` also covers Next.js repos, since they depend on `react`; use `next` only for Next-specific skills); an opt-in pack for occasional ones;
+   - in `skill-sources.json`: `{ "kind": "custom", "reviewed": "<today>" }` for the user's own skills. For one that came from GitHub, use `"kind": "external"` with its real `source` only if you can confirm it (the skill's README, metadata, or the user); never guess a repository path. If unknown, record it as `custom` with a `"note"` saying where it came from;
+   - `npx stackfit audit`.
+3. Move or delete only the items you migrated, one at a time, after the user confirms:
+   ```bash
+   mkdir -p <repo>/docs/agent/skills
+   mv <repo>/.claude/skills/<name> <repo>/docs/agent/skills/<name>   # repo-specific skill
+   rmdir <repo>/.claude/skills 2>/dev/null                          # only if now empty
+   ```
+   If `.claude/skills` was tracked in git, the user commits the move. Leave anything you did not migrate in place.
+4. `npx stackfit status --project <repo>`, then `sync`.
+
+Real example of the collision that step 3 prevents:
+
+```text
+stackfit: shop-web: unmanaged collision under .claude/skills: .claude/skills/my-own-skill/SKILL.md
+```
+
+After moving `my-own-skill` to `shop-web/docs/agent/skills/my-own-skill/`, the same sync succeeds and the skill appears next to the catalog ones in `.agents/skills/`.
+
+Global skills in `~/.claude/skills/` still load in every repo. Once they are in the catalog, follow step 6 of the setup in SKILL.md (diff, check the pack reaches every repo that needs it, move to a backup folder). To keep a skill everywhere, put it in an `always` pack such as `core`.
+
+## 4. Change what one repo gets
+
+Tracked, shared with the team (`<repo>/docs/agent/config.json`):
+
+```json
+{ "schemaVersion": 1, "packs": ["motion"], "excludePacks": ["stripe"], "skills": ["ui-ux-pro-max"] }
+```
+
+Local only, for repos you should not touch (on the project entry in `stackfit.local.json`):
+
+```json
+{ "name": "client-site", "scaffold": false, "packs": ["motion"], "excludePacks": ["stripe"] }
+```
+
+Then `status` (removed skills show as `delete`, and their folders are pruned) and `sync`.
+
+## 5. One or several machines
+
+`stackfit.local.json` lives next to `stackfit.json` and is gitignored, so each computer has its own. Minimal, one machine:
+
+```json
+{ "schemaVersion": 1, "machines": [ { "id": "laptop", "match": { "platform": "darwin" }, "roots": ["~/code"] } ] }
+```
+
+- `platform`: `darwin`, `linux`, or `win32`. Add `"hostname": "WORK-PC"` to tell two machines with the same platform apart.
+- Without `projects`, every Git repo directly under `roots` is included. With `projects`, only those folders (and each entry may carry `packs`, `excludePacks`, `skills`, `scaffold: false`).
+- Don't copy `stackfit.local.example.json` unchanged: its sample project names won't exist and cause `Configured project ... not found`.
+
+Several machines: put the catalog in a private Git repo, clone it on each, give each its own `stackfit.local.json`, then `npx stackfit sync --all`. Later `npx stackfit update --all` pulls the catalog and syncs (it refuses while the catalog has uncommitted changes).
+
+## 6. Add a skill from GitHub
+
+1. Find the folder holding its `SKILL.md`, for example `skills/react-best-practices` in `https://github.com/vercel-labs/agent-skills.git`.
+2. In `skill-sources.json`:
+   ```json
+   "vercel-react-best-practices": {
+     "kind": "external",
+     "source": { "repository": "https://github.com/vercel-labs/agent-skills.git", "path": "skills/react-best-practices" },
+     "reviewed": "2026-10-26",
+     "render": { "exclude": ["AGENTS.md", "README.md", "metadata.json"] }
+   }
+   ```
+   If the upstream frontmatter `name` differs from the folder name you chose, add `"render": { "frontmatter": { "name": "<your-folder-name>" } }`.
+3. Add the name to `skills` and to a pack in `stackfit.json`.
+4. `npx stackfit refresh --skill vercel-react-best-practices`, then `audit`, then review the vendored files with the user before syncing.
+
+Private repositories: set `GITHUB_TOKEN` in the shell or the catalog's `.env`.
+
+## 7. Tame a long or noisy upstream skill
+
+In `skill-sources.json`, under that skill:
+
+```json
+"render": {
+  "frontmatter": {
+    "description": "One line on what it does. Use when <specific trigger>.",
+    "disable-model-invocation": true
+  },
+  "exclude": ["evals/evals.json"]
+}
+```
+
+- Shorter `description`: cheaper in every session; keep the trigger words.
+- `disable-model-invocation: true`: costs nothing until the user calls it by name. Good for adoptions, migrations, releases.
+- Overrides apply at sync time, so `refresh` never undoes them. Check the effect with `npx stackfit audit` (cost per pack).
+
+## 8. Check it in CI
+
+Generated files are never committed, so a fresh CI checkout has none of them, and `status --check` would always report changes there. In CI, check what *is* committed instead:
+
+- **In each project's CI:** run `sync` against the pinned catalog. It exits 1 on real problems: an unknown pack or skill in `docs/agent/config.json`, a repo-owned skill clashing with a shared one, a malformed config.
+- **In the catalog's CI:** run `audit`. It exits 1 on unknown or unvendored skills and broken adapters, and warns on stale or oversized ones.
+
+GitHub Actions, project repo with a private catalog (store a read-only token as `CATALOG_TOKEN`):
+
+```yaml
+- uses: actions/checkout@v5
+- uses: actions/checkout@v5
+  with:
+    repository: your-org/agent-catalog
+    ref: v3                      # pin a tag or commit so builds are reproducible
+    token: ${{ secrets.CATALOG_TOKEN }}
+    path: .stackfit-catalog
+- uses: actions/setup-node@v5
+  with: { node-version: 22 }
+- run: npx stackfit sync --project . --catalog .stackfit-catalog --quiet
+```
+
+Catalog repo:
+
+```yaml
+- uses: actions/checkout@v5
+- uses: actions/setup-node@v5
+  with: { node-version: 22 }
+- run: npx stackfit audit --catalog .
+```
+
+`status --check` is for a developer's machine (for example before a release, or in a pre-push hook): exit 1 means the local generated files no longer match the catalog; `npx stackfit sync --project .` fixes it.
+
+## 9. A team catalog
+
+- One Git repo for the catalog; reviewers approve skill changes like code.
+- Personal values stay out: use `{{env:NAME}}` in commands, rules, and agents, and document the names in the catalog's `.env.example`.
+- `npx stackfit audit` in the catalog's CI catches unknown skills, missing sources, oversized descriptions, and skills not reviewed for 180 days.
+- Everyone runs `npx stackfit update --all` to pull and sync.
+
+## 10. Keep it lean over time
+
+Quarterly, or when `audit` flags it:
+1. `npx stackfit refresh --all` and review the diff.
+2. Read anything `audit` calls stale; archive what no longer earns its context (move it to `skills/_archive/`, remove it from `stackfit.json` and `skill-sources.json`).
+3. Update `reviewed` dates.
+4. `npx stackfit report --all` and compare with last time.
+
+## 11. Write a catalog skill that earns its place
+
+- Only keep what a frontier model would otherwise get wrong: your conventions, a non-obvious workflow, version-specific framework behaviour, a tool's exact CLI. Generic knowledge costs context and adds nothing.
+- `description` is what every session pays for: say what it does and exactly when to use it, in one or two sentences.
+- Keep `SKILL.md` short; move long material into files it links to (loaded only when needed).
+- Mark one-off workflows (migrations, adoptions, releases) `disable-model-invocation: true` so they cost nothing until called.
+- Register it: `skills` + a pack in `stackfit.json`, `{ "kind": "custom", "reviewed": "<today>" }` in `skill-sources.json`, then `npx stackfit audit`.

package/starter/skills/stackfit/references/troubleshooting.md

@@ -0,0 +1,37 @@
+# stackfit troubleshooting
+
+Messages are printed as `stackfit: <message>` and exit with code 1.
+
+| Message (start) | Cause | Fix |
+| --- | --- | --- |
+| `No catalog found` | No `--catalog`, no `STACKFIT_CATALOG`, no `stackfit.json` above the current folder, no `~/.stackfit` | Expected on a first run. `npx stackfit catalog init` (own skills) or `--starter` (curated packs), or point at an existing catalog |
+| `<repo>: unmanaged collision at <path>` / `under <path>` | A file stackfit did not create sits where it would write | Show the file to the user. Move it into the catalog or `docs/agent/` (recipes.md, recipe 3) and remove the old copy. Use `--force` only if the user confirms stackfit should take it over |
+| `Skill '<name>' is enabled but not in the catalog` | Listed in `stackfit.json` but `skills/<name>/SKILL.md` is missing | `npx stackfit refresh --skill <name>` for external skills, or create the folder |
+| `<repo>: unknown pack '<name>'` | Typo in `packs` / `excludePacks` | Use a pack name from `stackfit.json` |
+| `<repo>: unknown shared skill '<name>'` | A project's `skills` lists something the catalog does not enable | Enable it in `stackfit.json`, or fix the name |
+| `<repo>: repo-owned skill '<name>' conflicts with shared skills` | Same name in `docs/agent/skills/` and the catalog | Rename one, or add the name to `overrides.skills` in `docs/agent/config.json` to let the repo's version win |
+| `Configured project '<name>' not found under machine roots` | `stackfit.local.json` lists a folder that is not there | Remove the entry or add the right root |
+| `Machine '<id>' roots do not exist` | A root path is wrong on this machine | Fix `roots` for this machine |
+| `No stackfit.local.json machine matches <platform> hostname=<host>` | No profile for this computer | Add a machine entry, or use `--root` / `--project` |
+| `Choose --project <path>, --root <dir>, or --all` | No project selection given | Add one of them |
+| `Catalog has local changes; commit or stash them before update` | `update` pulls with `--ff-only` | Commit or stash in the catalog, or use `sync` |
+| `Could not clone <repo>` | No network to GitHub, private repo without token | Check network; set `GITHUB_TOKEN` for private repos |
+| `<name> has no recorded upstream source` | `refresh` on a `custom` skill or one without `source` | Add `source` in `skill-sources.json`, or edit the skill directly |
+| `warning: <file> uses {{env:NAME}} but NAME is not set` | Placeholder without a value | Add `NAME=...` to the catalog's `.env` (or the shell). The placeholder stays as-is until then |
+
+## Audit warnings worth acting on
+
+- `last reviewed <date> (<n> days ago)`: re-read the skill; refresh, shorten, or archive it, then update `reviewed`.
+- `description is <n> chars`: shorten it with `render.frontmatter.description`; claude.ai rejects descriptions over 1024 characters.
+- `enabled but in no pack`: it only reaches repos that list it under `skills`; add it to a pack or remove it.
+- `external origin is not recorded`: add `source` so it can be refreshed.
+
+## Behaviour that surprises people
+
+- **Skills still load in a repo that should not have them.** Check `~/.claude/skills/` and other global folders: they apply to every repo regardless of stackfit.
+- **A Claude rule does not load.** Rules with only a `description` are not rendered for Claude Code. Give them `alwaysApply: true` or `globs:`.
+- **Codex ignores rules.** Codex reads `AGENTS.md` and `.agents/skills`, not rule files. Put must-follow rules in `AGENTS.md` or a skill.
+- **Nothing in `git status` after a sync.** Expected: generated files are listed in a managed block in `.git/info/exclude`. Files you add under `docs/agent/` do show up and should be committed.
+- **After upgrading to 0.1.1, new files appear in `git status` under `.claude/` or `.cursor/`.** Older versions excluded those whole folders; now only generated files are excluded. The newly visible files are the user's own: commit them or add them to `.gitignore`.
+- **`status --check` fails in CI on a fresh checkout.** Generated files are never committed, so CI always sees them as missing. Use `sync` (validates config) in project CI and `audit` in catalog CI (recipe 8).
+- **Project names look odd (for example `repo` in CI).** stackfit names a project after its folder.

package/starter/stackfit.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "https://unpkg.com/stackfit/schemas/stackfit.schema.json",
+  "schemaVersion": 3,
+  "skills": [
+    "animation-vocabulary",
+    "apple-design",
+    "baseline-ui",
+    "emil-design-eng",
+    "fixing-accessibility",
+    "fixing-motion-performance",
+    "frontend-design",
+    "grilling",
+    "improve",
+    "improve-animations",
+    "interface-design",
+    "make-interfaces-feel-better",
+    "next-bundle-optimizer",
+    "next-cache-components-adoption",
+    "next-cache-components-optimizer",
+    "next-dev-loop",
+    "next-partial-prefetching-adoption",
+    "next-partial-prefetching-optimizer",
+    "next-server-security",
+    "playwright-e2e-testing",
+    "react-doctor",
+    "review-animations",
+    "shadcn",
+    "stackfit",
+    "stripe-best-practices",
+    "stripe-projects",
+    "ui-ux-pro-max",
+    "upgrade-stripe",
+    "vercel-composition-patterns",
+    "vercel-react-best-practices",
+    "vercel-react-view-transitions",
+    "web-design-guidelines"
+  ],
+  "packs": {
+    "core": {
+      "description": "Every repository: managing this catalog, codebase review planning, decision grilling.",
+      "always": true,
+      "skills": [
+        "grilling",
+        "improve",
+        "stackfit"
+      ]
+    },
+    "react": {
+      "description": "React performance, composition, and diagnostics.",
+      "detect": {
+        "dependencies": [
+          "react"
+        ]
+      },
+      "skills": [
+        "react-doctor",
+        "vercel-composition-patterns",
+        "vercel-react-best-practices"
+      ]
+    },
+    "nextjs": {
+      "description": "Next.js App Router: server security, runtime verification, bundle and navigation workflows (manual-only ones cost no context). Framework reference knowledge comes from node_modules/next/dist/docs (16.2+).",
+      "detect": {
+        "dependencies": [
+          "next"
+        ]
+      },
+      "skills": [
+        "next-bundle-optimizer",
+        "next-cache-components-adoption",
+        "next-cache-components-optimizer",
+        "next-dev-loop",
+        "next-partial-prefetching-adoption",
+        "next-partial-prefetching-optimizer",
+        "next-server-security",
+        "vercel-react-view-transitions"
+      ]
+    },
+    "e2e": {
+      "description": "Playwright browser tests.",
+      "detect": {
+        "dependencies": [
+          "@playwright/test",
+          "playwright"
+        ]
+      },
+      "skills": [
+        "playwright-e2e-testing"
+      ]
+    },
+    "ui": {
+      "description": "Interface design, accessibility, and polish.",
+      "detect": {
+        "dependencies": [
+          "react-dom",
+          "vue",
+          "svelte",
+          "tailwindcss",
+          "@angular/core",
+          "solid-js"
+        ]
+      },
+      "skills": [
+        "baseline-ui",
+        "fixing-accessibility",
+        "frontend-design",
+        "interface-design",
+        "make-interfaces-feel-better",
+        "web-design-guidelines"
+      ]
+    },
+    "shadcn": {
+      "description": "shadcn/ui components and registries.",
+      "detect": {
+        "files": [
+          "components.json"
+        ]
+      },
+      "skills": [
+        "shadcn"
+      ]
+    },
+    "motion": {
+      "description": "Animation craft, review, and performance. Auto-detected from motion libraries; add it by hand for CSS-only motion work.",
+      "detect": {
+        "dependencies": [
+          "motion",
+          "framer-motion",
+          "gsap",
+          "@react-spring/web"
+        ]
+      },
+      "skills": [
+        "animation-vocabulary",
+        "apple-design",
+        "emil-design-eng",
+        "fixing-motion-performance",
+        "improve-animations",
+        "review-animations"
+      ]
+    },
+    "design-research": {
+      "description": "Large searchable UI/UX database (about 1.7 MB). Opt-in only.",
+      "skills": [
+        "ui-ux-pro-max"
+      ]
+    },
+    "stripe": {
+      "description": "Stripe integrations and upgrades.",
+      "detect": {
+        "dependencies": [
+          "stripe",
+          "@stripe/stripe-js",
+          "@stripe/react-stripe-js"
+        ]
+      },
+      "skills": [
+        "stripe-best-practices",
+        "stripe-projects",
+        "upgrade-stripe"
+      ]
+    }
+  },
+  "adapters": {
+    "agents": [],
+    "commands": [],
+    "rules": [
+      "defaults.mdc"
+    ]
+  }
+}

package/starter/stackfit.local.example.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://unpkg.com/stackfit/schemas/stackfit.local.schema.json",
+  "schemaVersion": 1,
+  "machines": [
+    {
+      "id": "mac",
+      "match": { "platform": "darwin" },
+      "roots": ["~/code"],
+      "projects": [
+        "my-next-app",
+        { "name": "client-site", "scaffold": false, "packs": ["motion"] }
+      ]
+    },
+    {
+      "id": "windows",
+      "match": { "platform": "win32" },
+      "roots": ["C:/Users/you/code"]
+    }
+  ]
+}