vibes

Imported from ckaznocha/vibes (AGENTS.md). Install upstream with npx skills add ckaznocha/vibes. Copyright stays with the author.

General Guidelines for working with Nx

• For navigating/exploring the workspace, invoke the nx-workspace skill first - it has patterns for querying projects, targets, and dependencies
• When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through nx (i.e. nx run, nx run-many, nx affected) instead of using the underlying tooling directly
• Prefix nx commands with the workspace's package manager (e.g., pnpm nx build, npm exec nx test) - avoids using globally installed CLI
• You have access to the Nx MCP server and its tools, use them to help the user
• For Nx plugin best practices, check node_modules/@nx/<plugin>/PLUGIN.md. Not all plugins have this file - proceed without it if unavailable.
• NEVER guess CLI flags - always check nx_docs or --help first when unsure

Scaffolding & Generators

• For scaffolding tasks (creating apps, libs, project structure, setup), ALWAYS invoke the nx-generate skill FIRST before exploring or calling MCP tools

When to use nx_docs

• USE for: advanced config options, unfamiliar flags, migration guides, plugin configuration, edge cases
• DON'T USE for: basic generator syntax (nx g @nx/react:app), standard commands, things you already know
• The nx-generate skill handles generator discovery internally - don't call nx_docs just to look up generator syntax

Workspace conventions (this section is NOT nx-managed — edit freely, do not delete)

This is a generic harness meant to keep growing with new, independently-published projects. The root-level tooling (.claude/skills, .claude/agents, .claude/hooks) is written to discover projects via Nx tags and the project graph, not by hardcoding project names — a new project gets skills, agents, hooks, and lint/module-boundary rules "for free" by carrying the right tags, with zero changes needed to root-level .claude/ content. Keep it that way: when you add root-level automation, make it query nx show projects -p "tag:..." / nx show project <p> --json rather than naming a specific project.

Tag taxonomy

Declared in each project's project.json tags array. npm:* tags and metadata.description are free — Nx infers them from package.json keywords/ description, don't set them by hand.

Adding a new project

1. Tag it appropriately in project.json (table above) — this is what makes it discoverable, not a name added to some root config file.
2. If it's type:mcp-server, follow project-conventions (auto-loads when you touch its src/) and use new-mcp-tool to add tools.
3. If it's publish:npm, .github/workflows/release.yml needs a publish-<project> job added by hand — the tag alone doesn't wire up CI (release-gatekeeper checks for this).
4. If it's data-source:scraping, add a fixture-sources.json at its root so regen-fixture can check it for upstream drift.
5. If it introduces a genuinely new category of thing (not just another instance of an existing tag), extend the taxonomy table above and, if it constrains dependencies, eslint.config.ts's depConstraints — don't invent an untagged, undocumented convention.
6. The @nx/js/typescript sync generator (registered in nx.json) is supposed to keep root tsconfig.json's references array up to date from the project graph, but every project in this workspace (apps and libs alike) overrides its inferred build/ typecheck targets with hand-written nx:run-commands ones in project.json — the sync generator doesn't engage for a project once its targets are hand-written, so in practice it has never auto-updated this file. Add the new project's { "path": "./apps/<name>" } / { "path": "./libs/<name>" } entry to root tsconfig.json references by hand; don't rely on nx build/nx typecheck to prompt for it.
7. eslint.config.ts's typed-linting parserOptions.project glob already covers both apps/*/tsconfig.spec.json and libs/*/tsconfig.spec.json — a project under either directory gets typed linting for free; a project in some third top-level directory would need that glob extended.
8. pnpm-workspace.yaml declares libs/* (added once the first lib — libs/mcp-tool-result — landed; sherif, see pnpm run lint:workspace, would otherwise flag a workspace glob matching zero packages as a smell). A libs/<name> package needs a main/types and exports field in its package.json pointing at ./src/index.ts — these are TS-source-only libs with no build step (consuming apps' esbuild bundle: true builds read the source directly), so nothing else resolves the bare import from "<lib-name>" specifier otherwise. A lib meant to be shared across more than one app's scope:<project> gets tagged scope:shared (see taxonomy above) instead of a single app's scope tag. Use the new-lib skill to scaffold one — it encodes every gotcha in this item plus the two below, all discovered the hard way once already:
   • eslint.config.ts's type:app depConstraints entry must list type:lib in its onlyDependOnLibsWithTags, not just type:app — every project here is tagged both type:app and type:mcp-server simultaneously, and @nx/enforce-module-boundaries requires every matching constraint to pass, so the type:mcp-server constraint already allowing type:lib isn't enough on its own.
   • @nx/dependency-checks (wired in eslint.config.ts for apps/*/package.json and libs/*/package.json) is configured with buildTargets: ["typecheck"] instead of its default ["build"], because it only counts a workspace dependency as "used" if that dependency also has the named target — and libs here intentionally have no build target. Don't "fix" this back to the default; every project (apps included) has typecheck, so that's the one target guaranteed to exist everywhere.
9. lefthook.yml's affected-checks command already runs nx affected -t typecheck,test scoped to whatever you staged — nothing to add there for a new project either.
10. .vscode/launch.json is the one thing here Nx/pnpm can't make automatic: VS Code debug configs are inherently per-project (no glob support), so a new project that needs one still needs a hand-added entry, following the existing Debug <project> with Nx pattern (own inspector port, own outFiles path).
11. Before writing new logic in any type:mcp-server project — new or existing — check whether it already exists elsewhere first. Grep sibling type:mcp-server projects' src/ (nx show projects -p "tag:type:mcp-server" --json, then read each match) and libs/* for a function doing the same thing. If it's genuinely the same concern in two or more projects (not just superficially similar — see the litmus test below), extract it into a scope:shared lib via the new-lib skill instead of writing a second copy, the same way libs/mcp-tool-result and libs/resilient-fetch (retry/circuit-breaking/ throttling for outbound network calls — see project-conventions's "Network calls" section) got pulled out, and libs/tmdb-client (later reverted — see next paragraph) did not. This applies equally when scaffolding a brand-new project: check what the existing type:mcp-server projects already have before hand-rolling something they've already solved (tool-result wrapping, env-var parsing helpers, network retry/throttling, an API client with request caching, etc).
    • Litmus test — extract only if the concern is shared, not just the shape. Two functions with a similar signature that happen to solve different problems don't belong in one lib. libs/tmdb-client looked identical to libs/mcp-tool-result in spirit (both were "cache an instance/format a response, used in ≥2 projects") but got reverted: tmdb-mcp was created specifically to be the only place TMDB logic lives in this workspace, so letterboxd-mcp depending on a shared TMDB client re-created the exact coupling that project split was meant to remove. libs/mcp-tool-result survived the same review because MCP response formatting isn't "owned" by any one project — it's incidental plumbing every type:mcp-server project needs alike. When unsure which case you're in, ask: does one project exist specifically so others don't have to implement this? If yes, don't extract — make the other project(s) call it instead (even if that means a second tool-call round trip), or ask the user first.
12. Every project's package.json name is scoped @ckaznocha/<project> (the Nx project name itself — project.json name, tags, nx run <project>:... — stays unscoped; only the npm-facing package.json name carries the prefix), and every project's package.json gets "license": "MIT". This is enforced at the root, not per-project: root package.json's own name is @ckaznocha/vibes, and Nx infers the org prefix for anything scaffolded with an @nx/* generator (e.g. @nx/js:lib) from that root name field, so a fresh generator-created project is prefixed automatically. Projects scaffolded by hand (this workspace's type:mcp-server apps and libs/* don't go through a generator — see new-lib/project-conventions) need the prefix and license added by hand in their package.json, and any workspace:* dependency reference or bare-specifier import of a libs/* package elsewhere in the workspace must use the scoped name (import { ... } from "@ckaznocha/mcp-tool-result", not "mcp-tool-result") — new-lib's template already reflects this.

nx.json's release block is configured for independent per-project versioning (conventionalCommits, releaseTag.pattern: "{projectName}@v{version}" matching the tag format release.yml already parses) and changelog generation, but version.git/ changelog.git are both disabled — nx release version/nx release changelog are available as optional local helpers (e.g. to auto-compute the next semver bump or draft a CHANGELOG.md entry), but they do not commit, tag, or push. The actual commit/tag/publish trigger stays exactly as cut-release describes: a manually created GitHub Release whose tag CI parses. Future direction worth considering as this grows: flipping version.git.tag and wiring nx release publish into CI so tagging and publishing become fully automated instead of the current manual cut-release steps — not done yet since it touches CI/release infra and wasn't asked for.