@punks/cli 0.1.16 → 1.0.0

package/dist/skills/agnostic/frontend/frontend-domain-structure/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: frontend-domain-structure
+description: |
+  Organize frontend applications into domain-first layers with thin framework composition entrypoints,
+  user-facing features, reusable app-local modules, and shared libraries. Use when creating or
+  refactoring frontend code, replacing flat components/hooks/lib/utils folders, deciding whether code
+  belongs in framework composition, features/, modules/, or shared packages, or reviewing frontend
+  import boundaries across React, Vue, Svelte, Solid, or other UI frameworks.
+---
+
+# Frontend Domain Structure
+
+Use this skill to keep frontend code domain-based instead of folder-type-based.
+Treat `features/*` and `modules/*` as the main app-local domain containers.
+
+Read `references/structure.md` before structure decisions or large refactors.
+For React scopes, also read `references/react/structure.md`.
+
+## Quick Classifier
+
+Place code by responsibility first, framework file type second.
+
+- Put route files, screen entrypoints, layout shells, metadata, and framework-owned composition in the framework composition layer.
+- Put user-visible flows, screens, sections, and product orchestration in feature domains under `features/*`.
+- Put reusable app-local concerns such as providers, client wiring, routing helpers, metadata helpers, API clients, form foundations, and UI libraries in module domains under `modules/*`.
+- Put cross-app reusable domains, UI foundations, tokens, primitives, and framework-neutral helpers in shared libraries or packages.
+
+Inside each feature or module domain, use local technical folders only when useful.
+
+## Boundary Rules
+
+- Keep framework composition thin. Compose features and modules there; do not accumulate domain logic.
+- Let `features/*` depend on `modules/*` and shared libraries.
+- Do not let `modules/*` import `features/*`.
+- Do not move app-specific product features into shared libraries.
+- Avoid root-level generic buckets like `components`, `hooks`, `utils`, `helpers`, or `lib` when code can belong to a domain.
+
+## Shared Library Rule
+
+Use shared libraries for code reused across app boundaries.
+
+- Keep app-local reusable domains in `modules/*`.
+- Keep user-facing product domains in `features/*`.
+- Move only truly shared domains, presentation layers, primitives, tokens, or utilities into shared libraries.
+
+In a monorepo, shared packages should still be domain-first internally instead of becoming global buckets.
+
+## Use This Skill
+
+- Read `references/structure.md`.
+- Add framework-specific references only when the current scope uses that framework.
+- Classify each file by responsibility first.
+- Group by domain second.
+- Organize inside each domain by local technical role only when needed.
+- Keep imports flowing downward: framework composition -> `features` -> `modules` -> shared libraries or shared packages.

package/dist/skills/agnostic/frontend/frontend-domain-structure/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Frontend Domain Structure"
+  short_description: "Domain-first frontend structure"
+  default_prompt: "Use $frontend-domain-structure to place frontend code in the correct framework composition, features, modules, or shared-library layer; in React scopes, also apply references/react/structure.md for hooks, context, providers, components, route modules, and Next.js route files."

package/dist/skills/agnostic/frontend/frontend-domain-structure/references/react/structure.md

@@ -0,0 +1,102 @@
+# React Domain Structure Addendum
+
+Use this after the agnostic frontend structure reference when the current frontend scope is React, Next.js, Remix, TanStack Router, Expo web, tRPC-backed React, or another React-based stack.
+
+The agnostic frontend skill owns the shared layer model:
+
+- framework composition
+- `features/*`
+- `modules/*`
+- shared libraries and packages
+
+This reference owns React-specific placement for hooks, context, providers, components, route modules, and Next.js route files.
+
+## Framework Composition
+
+React framework entrypoints should stay thin.
+
+Common composition folders:
+
+- `app/` in Next.js App Router
+- `pages/` in Next.js Pages Router or Remix-style route modules
+- `routes/` in TanStack Router, Remix, or file-route setups
+- `src/app/` in app-shell conventions
+
+Good fits:
+
+- `page.tsx`
+- `layout.tsx`
+- route modules
+- route-level `loading`, `error`, and `not-found`
+- route metadata
+- tiny route composition wrappers
+
+Bad fits:
+
+- long client components
+- data orchestration that belongs to a feature
+- reusable product sections
+- provider setup repeated across routes
+- low-level hooks imported directly by routes when a feature entrypoint should own them
+
+Route files should import feature entrypoints instead of several low-level hooks, helpers, and components.
+
+## React Domain Internals
+
+Inside `features/*`, `modules/*`, and shared package domains, React-specific technical folders are allowed when they are local to the domain.
+
+Common local folders:
+
+- `components/`
+- `hooks/`
+- `context/`
+- `providers/`
+- `state/` or `store/`
+- `queries/`
+- `mutations/`
+- `actions/`
+- `forms/`
+- `lib/`
+- `utils/`
+
+Keep these folders under a domain. Avoid root-level `components/`, `hooks/`, `context/`, or `providers/` unless they are temporary migration debt or genuinely global app shell code.
+
+## Placement Examples
+
+Prefer:
+
+- `features/auth/components/LoginForm.tsx`
+- `features/auth/hooks/useLoginForm.ts`
+- `features/settings/context/SettingsDraftContext.tsx`
+- `features/dashboard/queries/useDashboardSummary.ts`
+- `modules/auth/providers/AuthProvider.tsx`
+- `modules/auth/hooks/useCurrentUser.ts`
+- `modules/api/lib/httpClient.ts`
+- `modules/ui/components/Button.tsx`
+- `<shared-ui-root>/src/primitives/button.tsx`
+- `<shared-ui-root>/src/brand/components/Logo.tsx`
+
+Avoid:
+
+- `src/components/LoginForm.tsx`
+- `src/hooks/useCurrentUser.ts`
+- `src/context/SettingsDraftContext.tsx`
+- `src/providers/AuthProvider.tsx`
+- `src/lib/httpClient.ts`
+
+## React Boundary Rules
+
+- Route components may import feature entrypoints and app-local modules.
+- Feature components may import hooks, context, providers, and helpers from the same feature, modules, or shared libraries.
+- Module hooks and providers must not import feature components.
+- Shared UI packages must not import app-local modules or features.
+- Context providers should live where their scope lives: feature-scoped context in `features/*`, app-wide reusable providers in `modules/*`, cross-app providers in shared packages.
+- Hooks follow the same ownership rule as the state or side effect they wrap.
+
+## React Review Checklist
+
+- Is the route file mostly composition?
+- Are React hooks under the domain that owns their state or side effect?
+- Is context scoped to the smallest domain that needs it?
+- Are providers app-local modules unless they are feature-specific or shared across apps?
+- Are root-level React technical folders avoided unless the project has an explicit app-shell convention?

package/dist/skills/agnostic/frontend/frontend-domain-structure/references/structure.md

@@ -0,0 +1,257 @@
+# Frontend Domain Structure Reference
+
+## Goal
+
+Organize frontend code by responsibility and domain instead of by file type.
+
+Prefer this shape:
+
+```text
+src/
+  <framework-composition>/
+  features/
+  modules/
+```
+
+Interpret the layers like this:
+
+- framework composition layer
+  Framework-owned user-land entrypoints such as routes, pages, screens, layouts, loading states, errors, metadata, and navigation shells.
+- `features/*`
+  Domain containers for user-visible product logic and page- or screen-facing slices.
+- `modules/*`
+  Domain containers for reusable app-local support building blocks, integrations, and root-level dependencies reused by multiple features.
+- shared libraries
+  Cross-app or cross-surface domains, primitives, tokens, utilities, and presentation helpers.
+
+The exact names of framework composition folders and shared libraries vary by project. The rule does not.
+
+`features` and `modules` are both domain layers. They are not flat dumping grounds. Each domain may contain local technical folders when those folders serve that domain.
+
+The same principle applies to packages in a monorepo. A package should still be structured by domain internally instead of becoming one flat global `components`, `hooks`, or `utils` bucket.
+
+## Why This Shape
+
+Flat folders such as `components`, `hooks`, `lib`, and `utils` scale poorly because they group by technical type instead of business purpose.
+
+Group around domains first, then use technical subfolders inside the domain when useful.
+
+Root-level escape hatches like `utils/` and `lib/` should stay rare. Small truly global helpers can exist, but most code placed there eventually belongs to a feature domain, a module domain, or a shared library.
+
+This structure improves:
+
+- discoverability
+- ownership
+- reuse boundaries
+- thin route or screen entrypoints
+- resistance to feature leakage across the app
+
+## Decision Table
+
+Classify each file in this order.
+
+1. Is this a framework entrypoint or composition shell?
+   Put it in the framework composition layer.
+2. Is this a user-facing business section, screen flow, or product workflow that an entrypoint should import?
+   Put it in a feature domain under `features/*`.
+3. Is this reusable inside the app but not itself a page- or screen-facing product slice?
+   Put it in a module domain under `modules/*`.
+4. Is this generic enough to reuse across apps, packages, or surfaces?
+   Put it in a shared library or shared package.
+
+If a file is named by type instead of purpose, rename around the domain or concern when moving it.
+
+## Layer Meanings
+
+### Framework Composition Layer
+
+Keep this layer thin.
+
+Good fits:
+
+- route files
+- screen entrypoint files
+- layouts and navigation shells
+- loading, error, empty, and not-found boundaries
+- route or screen metadata
+- tiny composition wrappers
+
+Bad fits:
+
+- domain logic
+- long form flows
+- reusable product sections
+- app client setup scattered across many entrypoints
+- business state orchestration
+
+The entrypoint should mostly assemble higher-level pieces.
+
+### `features/*`
+
+Use features for meaningful user-facing domains.
+
+Good fits:
+
+- authentication screens and flows
+- dashboard sections
+- account settings areas
+- navigation experiences
+- user-facing forms and workflows
+- domain-specific business state and orchestration
+
+A feature domain may contain local UI, state, data access, config, helpers, and sub-sections.
+
+Do not create a feature for every tiny component. A feature should represent a coherent user-facing capability.
+
+### `modules/*`
+
+Use modules for reusable app-local support domains.
+
+Good fits:
+
+- auth client setup
+- API client wiring
+- providers
+- routes or navigation configuration
+- metadata helpers
+- form foundations reused across several features
+- domain service adapters used by many features
+- UI library domains
+- framework integration layers
+- root-level dependencies shared by several features
+
+Modules are reusable inside the app, but they are not page-facing product slices.
+
+A `modules/ui` domain is valid when it is effectively the app's local UI library: primitives, brand-styled abstractions, UI behavior, and UI-specific logic reused across many features.
+
+### Shared Libraries
+
+Use shared libraries for code that is reused across app boundaries.
+
+Good fits:
+
+- shared domain abstractions
+- UI primitives
+- design tokens
+- framework-neutral helpers
+- icons
+- styling foundations
+- generic presentation helpers
+
+Bad fits:
+
+- page sections
+- product workflows
+- app-specific domain widgets
+- route- or screen-specific logic
+
+If the code is only reusable within one app, keep it inside that app, usually in `modules/*`.
+
+In a monorepo, shared packages should still be domain-based internally.
+
+Good package patterns:
+
+- a package that is itself one coherent shared domain
+- a package with a small number of clearly separated internal domains
+
+Examples:
+
+- `<shared-ui-root>/src/primitives/*`
+- `<shared-ui-root>/src/brand/*`
+- `<auth-package-root>/src/client/*`
+- `<auth-package-root>/src/server/*`
+- `<forms-package-root>/src/fields/*`
+
+Bad package patterns:
+
+- a giant `<shared-ui-root>/src/components` folder holding unrelated concerns
+- `<shared-foundation-root>/src/utils` growing without domain ownership
+- a single package collecting every reusable concern just because it is shared
+
+If a package contains several unrelated concerns, split the package or introduce internal domain folders.
+
+## Import Boundaries
+
+Keep dependencies flowing downward.
+
+- framework composition layer may import:
+  - `features/*`
+  - `modules/*`
+  - bootstrapping helpers
+- `features/*` may import:
+  - sibling files in the same feature
+  - `modules/*`
+  - shared libraries
+- `modules/*` may import:
+  - sibling files in the same module
+  - shared libraries
+  - external libraries
+- shared packages may import:
+  - sibling files inside the same package domain
+  - lower-level shared utilities inside that package
+  - external libraries
+
+Avoid these inversions:
+
+- `modules/*` importing `features/*`
+- shared libraries importing app-local code
+- one shared package domain importing unrelated package domains without a clear boundary
+- framework entrypoints importing many low-level helpers instead of a feature-level entrypoint
+
+## Refactoring Guide
+
+When migrating from flat buckets like `components`, `hooks`, `lib`, and `utils`:
+
+- move framework-facing composition into the framework composition layer
+- group page- or screen-facing workflows under domain folders in `features/*`
+- group reusable app-local support code under domain folders in `modules/*`
+- move only truly shared code into shared libraries or shared packages
+
+Name folders by domain or responsibility, not by file type.
+
+Prefer:
+
+- `features/auth`
+- `features/settings`
+- `features/layout`
+- `modules/auth`
+- `modules/providers`
+- `modules/api`
+- `modules/ui`
+
+In monorepos, also prefer:
+
+- `<shared-ui-root>/src/primitives`
+- `<shared-ui-root>/src/brand`
+- `<auth-package-root>/src/client`
+- `<auth-package-root>/src/server`
+- `<table-package-root>/src/hooks`
+
+Then, inside a domain, use local technical folders only when they help:
+
+- `features/auth/components`
+- `features/auth/state`
+- `features/auth/api`
+- `modules/auth/config`
+- `modules/api/lib`
+- `<auth-package-root>/src/client`
+- `<shared-ui-root>/src/brand/components`
+
+Avoid:
+
+- `components/common`
+- `components/shared`
+- `utils/misc`
+- `lib/helpers`
+
+When root-level `utils/` already exists, treat it as migration debt unless the helpers are genuinely global and domain-neutral.
+
+## Review Checklist
+
+When reviewing or designing structure:
+
+- Can the framework composition file get thinner?
+- Is the entrypoint importing a feature instead of several low-level files?
+- Is reusable app-local logic living in a module instead of scattered buckets?
+- Is truly shared code kept out of app-local layers?
+- Are shared packages internally domain-based instead of flat dumping grounds?

package/dist/skills/agnostic/frontend/gpt-taste/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: gpt-taste
+description: Elite UX/UI & Advanced GSAP Motion Engineer. Enforces Python-driven true randomization for layout variance, strict AIDA page structure, wide editorial typography (bans 6-line wraps), gapless bento grids, strict GSAP ScrollTriggers (pinning, stacking, scrubbing), inline micro-images, and massive section spacing.
+---
+
+# CORE DIRECTIVE: AWWWARDS-LEVEL DESIGN ENGINEERING
+You are an elite, award-winning frontend design engineer. Standard LLMs possess severe statistical biases: they generate massive 6-line wrapped headings by using narrow containers, leave ugly empty gaps in bento grids, use cheap meta-labels ("QUESTION 05", "SECTION 01"), output invisible button text, and endlessly repeat the same Left/Right layouts. 
+
+Your goal is to aggressively break these defaults. Your outputs must be highly creative, perfectly spaced, motion-rich (GSAP), mathematically flawless in grid execution, and heavily rely on varied, high-end assets.
+
+DO NOT USE EMOJIS IN YOUR CODE, COMMENTS, OR OUTPUT. Maintain strictly professional formatting.
+
+## 1. PYTHON-DRIVEN TRUE RANDOMIZATION (BREAKING THE LOOP)
+LLMs are inherently lazy and always pick the first layout option. To prevent this, you MUST simulate a Python script execution in your `<design_plan>` before writing any UI code. 
+Use a deterministic seed (e.g., character count of the user prompt modulo math) to simulate `random.choice()` and strictly select:
+- 1 Hero Architecture (from Section 3)
+- 1 Typography Stack (Satoshi, Cabinet Grotesk, Outfit, or Geist. NEVER Inter)
+- 3 Unique Component Architectures (from Section 6)
+- 2 Advanced GSAP Paradigms (from Section 5)
+You are forbidden from defaulting to the same UI twice. You must follow the exact output of your simulated Python randomization.
+
+## 2. AIDA STRUCTURE & SPACING
+Every page MUST begin with a highly creative, premium Navigation Bar (e.g., floating glass pill, or minimal split nav).
+The rest of the page MUST follow the AIDA framework:
+- **Attention (Hero):** Cinematic, clean, wide layout.
+- **Interest (Features/Bento):** High-density, mathematically perfect grid or interactive typographic components.
+- **Desire (GSAP Scroll/Media):** Pinned sections, horizontal scroll, or text-reveals.
+- **Action (Footer/Pricing):** Massive, high-contrast CTA and clean footer links.
+**SPACING RULE:** Add huge vertical padding between all major sections (e.g., `py-32 md:py-48`). Sections must feel like distinct, cinematic chapters. Do not cramp elements together.
+
+## 3. HERO ARCHITECTURE & THE 2-LINE IRON RULE
+The Hero must breathe. It must NOT be a narrow, 6-line text wall.
+- **The Container Width Fix:** You MUST use ultra-wide containers for the H1 (e.g., `max-w-5xl`, `max-w-6xl`, `w-full`). Allow the words to flow horizontally.
+- **The Line Limit:** The H1 MUST NEVER exceed 2 to 3 lines. 4, 5, or 6 lines is a catastrophic failure. Make the font size smaller (`clamp(3rem, 5vw, 5.5rem)`) and the container wider to ensure this.
+- **Hero Layout Options (Randomly Assigned via Python):**
+  1. *Cinematic Center (Highly Preferred):* Text perfectly centered, massive width. Below the text, exactly two high-contrast CTAs. Below the CTAs or behind everything, a stunning, full-bleed background image with a dark radial wash.
+  2. *Artistic Asymmetry:* Text offset to the left, with an artistic floating image overlapping the text from the bottom right.
+  3. *Editorial Split:* Text left, image right, but with massive negative space.
+- **Button Contrast:** Buttons must be perfectly legible. Dark background = white text. Light background = dark text. Invisible text is a failure.
+- **BANNED IN HERO:** Do NOT use arbitrary floating stamp/badge icons on the text. Do NOT use pill-tags under the hero. Do NOT place raw data/stats in the hero.
+
+## 4. THE GAPLESS BENTO GRID
+- **Zero Empty Space in Grids:** LLMs notoriously leave blank, dead cells in CSS grids. You MUST use Tailwind's `grid-flow-dense` (`grid-auto-flow: dense`) on every Bento Grid. You must mathematically verify that your `col-span` and `row-span` values interlock perfectly. No grid shall have a missing corner or empty void.
+- **Card Restraint:** Do not use too many cards. 3 to 5 highly intentional, beautifully styled cards are better than 8 messy ones. Fill them with a mix of large imagery, dense typography, or CSS effects.
+
+## 5. ADVANCED GSAP MOTION & HOVER PHYSICS
+Static interfaces are strictly forbidden. You must write real GSAP (`@gsap/react`, `ScrollTrigger`).
+- **Hover Physics:** Every clickable card and image must react. Use `group-hover:scale-105 transition-transform duration-700 ease-out` inside `overflow-hidden` containers.
+- **Scroll Pinning (GSAP Split):** Pin a section title on the left (`ScrollTrigger pin: true`) while a gallery of elements scrolls upwards on the right side.
+- **Image Scale & Fade Scroll:** Images must start small (`scale: 0.8`). As they scroll into view, they grow to `scale: 1.0`. As they scroll out of view, they smoothly darken and fade out (`opacity: 0.2`).
+- **Scrubbing Text Reveals:** Opacity of central paragraph words starts at 0.1 and scrubs to 1.0 sequentially as the user scrolls.
+- **Card Stacking:** Cards overlap and stack on top of each other dynamically from the bottom as the user scrolls down.
+
+## 6. COMPONENT ARSENAL & CREATIVITY
+Select components from this arsenal based on your randomization:
+- **Inline Typography Images:** Embed small, pill-shaped images directly INSIDE massive headings. Example: `I shape <span className="inline-block w-24 h-10 rounded-full align-middle bg-cover bg-center mx-2" style={{backgroundImage: 'url(...)'}}></span> digital spaces.`
+- **Horizontal Accordions:** Vertical slices that expand horizontally on hover to reveal content and imagery.
+- **Infinite Marquee (Trusted Partners):** Smooth, continuously scrolling rows of authentic `@phosphor-icons/react` or large typography.
+- **Feedback/Testimonial Carousel:** Clean, overlapping portrait images next to minimalist typography quotes, controlled by subtle arrows.
+
+## 7. CONTENT, ASSETS & STRICT BANS
+- **The Meta-Label Ban:** BANNED FOREVER are labels like "SECTION 01", "SECTION 04", "QUESTION 05", "ABOUT US". Remove them entirely. They look cheap and unprofessional.
+- **Image Context & Style:** Use `https://picsum.photos/seed/{keyword}/1920/1080` and match the keyword to the vibe. Apply sophisticated CSS filters (`grayscale`, `mix-blend-luminosity`, `opacity-90`, `contrast-125`) so they do not look like boring stock photos.
+- **Creative Backgrounds:** Inject subtle, professional ambient design. Use deep radial blurs, grainy mesh gradients, or shifting dark overlays. Avoid flat, boring colors.
+- **Horizontal Scroll Bug:** Wrap the entire page in `<main className="overflow-x-hidden w-full max-w-full">` to absolutely prevent horizontal scrollbars caused by off-screen animations.
+
+## 8. MANDATORY PRE-FLIGHT <design_plan>
+Before writing ANY React/UI code, you MUST output a `<design_plan>` block containing:
+1. **Python RNG Execution:** Write a 3-line mock Python output showing the deterministic selection of your Hero Layout, Component Arsenal, GSAP animations, and Fonts based on the prompt's character count.
+2. **AIDA Check:** Confirm the page contains Navigation, Attention (Hero), Interest (Bento), Desire (GSAP), Action (Footer).
+3. **Hero Math Verification:** Explicitly state the `max-w` class you are applying to the H1 to GUARANTEE it will flow horizontally in 2-3 lines. Confirm NO stamp icons or spam tags exist.
+4. **Bento Density Verification:** Prove mathematically that your grid columns and rows leave zero empty spaces and `grid-flow-dense` is applied.
+5. **Label Sweep & Button Check:** Confirm no cheap meta-labels ("QUESTION 05") exist, and button text contrast is perfect.
+Only output the UI code after this rigorous verification is complete.