feat: migrate to pnpm monorepo with Turborepo and add AI agent context #2
Conversation
- Rewrite README.md for Usage UI registry project with updated installation instructions, component roadmap, and tech stack - Add CLAUDE.md and AGENTS.md for AI coding assistant context - Add ARCHITECTURE.md with component design and implementation roadmap - Add AI-AGENT-PROJECT-BEST-PRACTICES.md research document - Add AI-CONTEXT-MANAGEMENT-RESEARCH.md analysis - Add .cursor/rules for project-specific coding conventions - Add public/llms.txt for LLM-friendly project summary
Co-authored-by: andresthedesigner <andresthedesigner@gmail.com>
Claude skills research
…ills - Update CLAUDE.md, AGENTS.md, and cursor rules to reflect planned monorepo structure with apps/www and packages/ui - Add .agents/ directory with shared skills for AI assistants: - shadcn-ui: Component library reference - tailwind-v4-shadcn: Setup and migration guide - skill-creator: Tool for creating new skills - sync-agent-skills: Sync skills across tool directories - web-design-guidelines: UI review checklist - Add MONOREPO-MIGRATION.md with detailed migration checklist - Add CONTRIBUTING.md with contribution guidelines - Add 000-monorepo-structure.mdc cursor rule - Update .gitignore to exclude agent symlink directories
Move scattered AI documentation into organized structure: - Add .agents/context/ for glossary, decisions (ADRs), and research - Add .agents/skills/monorepo-validation/ for workspace validation - Add .agents/workflows/ for step-by-step procedures - Remove redundant root-level AI documentation files - Update AGENTS.md with new directory structure reference - Expand MONOREPO-MIGRATION.md with detailed migration checklist
Restructure project into a monorepo with: - apps/www: Next.js documentation site (@usage-ui/www) - packages/ui: Component registry (@usage-ui/ui) - tooling/typescript: Shared TypeScript config Key changes: - Add pnpm workspaces with Turborepo orchestration - Move app source to apps/www/ - Create packages/ui with shadcn components - Add Changesets for versioning - Add GitHub Actions CI workflow - Configure Lefthook git hooks - Update .gitignore for monorepo artifacts All builds, lint, and typecheck passing.
- Mark Phase 0 (monorepo setup) as complete in ARCHITECTURE.md - Update current state assessment to show all infrastructure in place - Mark all checkpoints complete in MONOREPO-MIGRATION.md - Update README.md with monorepo structure and commands
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Let pnpm/action-setup@v4 read version from package.json's packageManager field instead of specifying it twice, which causes ERR_PNPM_BAD_PM_VERSION.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
.agents/skills/monorepo-validation/scripts/validate-monorepo.sh
Outdated
Show resolved
Hide resolved
| echo "🏷️ Checking package names..." | ||
|
|
||
| if [ -f "apps/www/package.json" ]; then | ||
| WWW_NAME=$(grep '"name"' apps/www/package.json | head -1 | sed 's/.*"\(.*\)".*/\1/' | sed 's/.*: "//' | sed 's/".*//') |
There was a problem hiding this comment.
Redundant sed commands in package name extraction
Low Severity
The sed pipeline chains three separate sed commands, but the second and third are redundant. The first sed 's/.*"\(.*\)".*/\1/' extracts the value between the last pair of quotes (e.g., @usage-ui/www). After this, the output contains no : " pattern for the second sed to match, and no " character for the third sed to match. Both subsequent sed commands are effectively no-ops that add unnecessary complexity without changing the result.
Additional Locations (1)
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
14 issues found across 303 files
Note: This PR contains a large number of files. cubic only reviews up to 75 files per PR, so some files may not have been reviewed.
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name=".agents/skills/skill-creator/scripts/quick_validate.py">
<violation number="1" location=".agents/skills/skill-creator/scripts/quick_validate.py:63">
P2: Empty string values for `name` pass validation. The code checks if the key exists but doesn't verify the value is non-empty after stripping whitespace. A skill with `name: ""` or `name: " "` would be considered valid.</violation>
<violation number="2" location=".agents/skills/skill-creator/scripts/quick_validate.py:78">
P2: Empty string values for `description` pass validation. Same issue as `name` - the code checks key existence but not that the stripped value is non-empty.</violation>
</file>
<file name=".agents/skills/shadcn-ui/ui-reference.md">
<violation number="1" location=".agents/skills/shadcn-ui/ui-reference.md:568">
P3: Escape the quotes in this JSON example so it is valid JSON; unescaped quotes inside the string currently break the snippet.</violation>
<violation number="2" location=".agents/skills/shadcn-ui/ui-reference.md:1277">
P3: Escape the inner quotes in these JSON strings so the media query example is valid JSON.</violation>
</file>
<file name="apps/www/public/r/brand-sidebar.json">
<violation number="1" location="apps/www/public/r/brand-sidebar.json:16">
P2: `usePathname()` returns only the URL pathname, so comparing it to hash-only hrefs like `#projects` will never mark any menu item as active. If you want hash navigation, track `window.location.hash` (or switch to real paths) for the active state.</violation>
</file>
<file name=".agents/skills/monorepo-validation/scripts/validate-monorepo.sh">
<violation number="1" location=".agents/skills/monorepo-validation/scripts/validate-monorepo.sh:96">
P2: Substring matching instead of exact matching causes false positives. A package named `@usage-ui/www-fork` would incorrectly pass this validation. Use exact matching without the wildcards.</violation>
<violation number="2" location=".agents/skills/monorepo-validation/scripts/validate-monorepo.sh:105">
P2: Same issue as above - use exact matching to prevent false positives with package names that contain '@usage-ui/ui' as a substring.</violation>
</file>
<file name="ARCHITECTURE.md">
<violation number="1" location="ARCHITECTURE.md:1068">
P2: Inconsistent import pattern: This example uses `@radix-ui/react-progress` but the project uses the unified `radix-ui` package per AGENTS.md. This will mislead developers following this guide.
Should be: `import { Progress as ProgressPrimitive } from "radix-ui"`</violation>
</file>
<file name=".agents/skills/tailwind-v4-shadcn/references/dark-mode.md">
<violation number="1" location=".agents/skills/tailwind-v4-shadcn/references/dark-mode.md:39">
P2: The `useTheme` guard will never trigger because the context is created with a non-undefined default value, so using `useTheme` outside `ThemeProvider` silently returns the initial state. Consider initializing the context as `undefined` and typing it as `ThemeProviderState | undefined` so the guard works as intended.</violation>
</file>
<file name=".agents/skills/shadcn-ui/reference.md">
<violation number="1" location=".agents/skills/shadcn-ui/reference.md:444">
P3: Encode `debouncedSearch` before interpolating it into the query string so special characters don’t break the URL or alter parameters.</violation>
</file>
<file name=".agents/skills/skill-creator/scripts/init_skill.py">
<violation number="1" location=".agents/skills/skill-creator/scripts/init_skill.py:287">
P2: Missing input validation for `skill_name`. The script documents requirements (hyphen-case, lowercase letters/digits/hyphens only, max 40 chars) but doesn't enforce them. This could allow invalid skill names or path traversal attacks (e.g., `../malicious` as skill name).</violation>
</file>
<file name=".agents/skills/tailwind-v4-shadcn/templates/theme-provider.tsx">
<violation number="1" location=".agents/skills/tailwind-v4-shadcn/templates/theme-provider.tsx:88">
P2: The undefined check will never trigger because the context is created with a default value. When `useTheme()` is called outside a `ThemeProvider`, it returns `initialState` (not `undefined`), so users won't get the helpful error message.
The fix requires changing line 20 to use `null` as default: `createContext<ThemeProviderState | null>(null)`, and updating this check to `if (!context)`.</violation>
</file>
<file name=".agents/skills/sync-agent-skills/scripts/sync-skills.sh">
<violation number="1" location=".agents/skills/sync-agent-skills/scripts/sync-skills.sh:58">
P1: Arithmetic increment `((var++))` with `set -e` will exit the script when the variable is 0. The post-increment returns exit code 1 because the expression evaluates to 0 (falsy) before incrementing. Use pre-increment `((++skipped))` or assignment `skipped=$((skipped + 1))` instead. The same issue applies to `((created++))` on line 68 and `((removed++))` on line 79.</violation>
</file>
<file name=".agents/skills/tailwind-v4-shadcn/rules/tailwind-v4-shadcn.md">
<violation number="1" location=".agents/skills/tailwind-v4-shadcn/rules/tailwind-v4-shadcn.md:2">
P2: `paths` frontmatter isn’t valid YAML. Use a proper list so the rules engine can parse the file patterns.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
.agents/skills/monorepo-validation/scripts/validate-monorepo.sh
Outdated
Show resolved
Hide resolved
…ld pipeline - Refactor validate-monorepo.sh to use helper function for package name extraction - Add skill name validation with regex pattern in init_skill.py - Make name/description validation stricter in quick_validate.py (non-empty required) - Fix POSIX arithmetic syntax in sync-skills.sh - Improve React context initialization pattern in theme-provider templates - Fix paths frontmatter format in tailwind-v4-shadcn rules - Fix URL encoding in shadcn-ui reference fetch example - Update ARCHITECTURE.md with correct unified radix-ui import patterns - Add shadcn registry build step to www package build script - Fix brand-sidebar to use client-side hash state instead of pathname - Regenerate registry JSON files
There was a problem hiding this comment.
1 issue found across 14 files (changes from recent commits).
Prompt for AI agents (all issues)
Check if these issues are valid — if so, understand the root cause of each and fix them.
<file name="apps/www/package.json">
<violation number="1" location="apps/www/package.json:7">
P2: Avoid `shadcn@latest` in build scripts; it makes builds non-deterministic. Pin the CLI version (or add it as a devDependency and use `pnpm exec shadcn`) so CI and local builds use the same tooling.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Replace `pnpm dlx shadcn@latest` with `pnpm exec shadcn` and add shadcn as a pinned devDependency (3.7.0). This ensures CI and local builds use the same tooling version.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 3 potential issues.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
|
|
||
| if [ -f "pnpm-workspace.yaml" ]; then | ||
| if grep -q "apps/\*" pnpm-workspace.yaml && grep -q "packages/\*" pnpm-workspace.yaml; then | ||
| pass "pnpm-workspace.yaml includes apps/* and packages/*" |
There was a problem hiding this comment.
Validation script missing check for tooling workspace pattern
Medium Severity
The workspace configuration check in validate-monorepo.sh only validates that pnpm-workspace.yaml contains apps/* and packages/*, but the SKILL.md documentation explicitly states it must also contain tooling/*. The actual workspace file includes all three patterns, but removing tooling/* would pass validation despite violating documented requirements and breaking the tooling/typescript workspace dependency.
Additional Locations (1)
| [ -f "packages/ui/components.json" ] && pass "packages/ui/components.json exists" || fail "packages/ui/components.json missing" | ||
| [ -d "packages/ui/src/components/ui" ] && pass "packages/ui/src/components/ui exists" || fail "packages/ui/src/components/ui missing" | ||
| [ -f "packages/ui/src/lib/utils.ts" ] && pass "packages/ui/src/lib/utils.ts exists" || fail "packages/ui/src/lib/utils.ts missing" | ||
| fi |
There was a problem hiding this comment.
Missing validation check for required CSS variables file
Medium Severity
The packages/ui file validation section doesn't check for packages/ui/src/styles/globals.css, which is documented as required in structure-checks.md and contains critical OKLCH color variables for the meter components. The package exports ./styles/* which would fail to resolve meaningful content if this file is missing, causing build or runtime styling failures that validation wouldn't catch.
Additional Locations (1)
| - React Hook Form: https://react-hook-form.com | ||
| - Zod: https://zod.dev | ||
| - Tailwind CSS: https://tailwindcss.com | ||
| - Examples: https://ui.shadcn.com/examples |
There was a problem hiding this comment.
SKILL.md exceeds documented 200-line limit significantly
Medium Severity
The shadcn-ui/SKILL.md file is 1616 lines, far exceeding the project's own documented guideline of 200 lines maximum for SKILL.md files. The research document .agents/context/research/ai-context-management.md explicitly states that SKILL.md files should be capped at 200 lines with "Core instructions only" and that reference content should be moved to references/*.md files which have no line limit and are "Loaded on-demand." This guideline exists because "accuracy drops from 99% to ~50% as context window fills." The extensive component examples and configuration snippets in this file are reference material that belongs in a references/ subdirectory, following the pattern used correctly by monorepo-validation/.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 3 potential issues.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| # Usage: get_package_name "path/to/package.json" | ||
| get_package_name() { | ||
| grep '"name"' "$1" | head -1 | sed 's/.*"\(.*\)".*/\1/' | sed 's/.*: "//' | sed 's/".*//' | ||
| } |
There was a problem hiding this comment.
Package name extraction fails on non-standard JSON formatting
Low Severity
The get_package_name function assumes the name field in package.json is formatted on a single line. If the JSON is formatted with the key and value on separate lines (e.g., "name":\n "@usage-ui/www"), the first sed command fails to match and the function returns whitespace, causing a confusing validation error message like "got: " instead of clearly indicating the actual formatting issue.
| FormMessage, | ||
| } from "@/components/ui/form" | ||
| import { Input } from "@/components/ui/input" | ||
| import { toast } from "@/components/ui/use-toast" |
There was a problem hiding this comment.
Form examples missing required useToast hook call
Medium Severity
Two form examples incorrectly import toast directly from @/components/ui/use-toast and call it without using the useToast() hook. Standard shadcn/ui requires importing useToast, calling it to get the toast function, then using that function. The examples show import { toast } instead of import { useToast } and are missing the required const { toast } = useToast() call inside the components, causing runtime errors when users copy these examples.
Additional Locations (1)
| - React Hook Form: https://react-hook-form.com | ||
| - Zod: https://zod.dev | ||
| - Tailwind CSS: https://tailwindcss.com | ||
| - Examples: https://ui.shadcn.com/examples |
There was a problem hiding this comment.
SKILL.md exceeds project size guidelines by 8x
Medium Severity
The shadcn-ui/SKILL.md file is 1616 lines, violating the project's documented 200-line guideline for SKILL.md files. The file contains extensive reference material (complete component examples, configuration samples, API documentation) that belongs in the references/ directory per the project's own ai-context-management research guidelines.
2 participants
Summary
apps/www(docs site) andpackages/ui(component library).agents/directory with skills, workflows, and decision records for AI coding assistantsKey Changes
Structure
New Capabilities
Test plan
pnpm installto verify workspace setuppnpm buildto verify Turborepo pipelinepnpm devto start development serverspnpm lintandpnpm typecheckto verify code quality.agents/skills/content loads correctly in AI assistantsNote
Low Risk
Documentation-heavy change; the only executable addition is a standalone validation shell script that doesn’t affect runtime behavior unless manually invoked.
Overview
Adds a new
.agents/context/knowledge base (README, glossary, ADRs, and research notes) to document key architectural decisions (e.g., OKLCH theming, monorepo structure, dual primitive strategy, migration approach) for on-demand AI agent retrieval.Introduces a
monorepo-validationagent skill, including avalidate-monorepo.shscript, to sanity-check expected pnpm workspace/Turborepo repo structure, key config files, package naming, TS path aliases, and registry build outputs.Written by Cursor Bugbot for commit 245897f. This will update automatically on new commits. Configure here.
Summary by cubic
Migrated the repo to a pnpm monorepo with Turborepo and split it into apps/www (docs site) and packages/ui (component registry). Added a structured .agents/ directory with context (ADRs), skills, workflows, plus CI, versioning, and editor rules to improve developer workflow.
New Features
Migration
Written for commit 245897f. Summary will update on new commits.