npm package: @hitit-ai/primevue-agent
Description: PrimeVue v4 planning guides for AI coding agents — a two-agent workflow tool inspired by Filament Blueprint
Latest version: 1.0.1

# Hitit

PrimeVue v4 planning guides for AI coding agents — inspired by [Filament Blueprint](https://filamentphp.com/insights/danharrin-filament-v5-blueprint).

## What Is This?

Hitit provides curated planning guides and full component documentation for PrimeVue v4. It's designed for AI coding agents that follow a **two-agent workflow**:

1. **Planning Agent** — Reads the guide files to produce a structured implementation plan (component choices, props, state, events, validation, layout)
2. **Implementing Agent** — Takes the plan and writes the actual Vue.js code

## Installation

```bash
# npm
npm install @hitit-ai/primevue-agent

# pnpm
pnpm install @hitit-ai/primevue-agent
```

On install, Hitit automatically injects its rules into `AGENTS.md` and `CLAUDE.md` (if they exist). On uninstall, the rules are cleanly removed.

> **pnpm users**: If lifecycle scripts are disabled, add `hitit` to your `.npmrc`:
> ```
> enable-pre-post-scripts=true
> ```
> Or run the postinstall manually: `node node_modules/@hitit-ai/primevue-agent/scripts/postinstall.mjs`

## How to Use

Point the planning agent to the overview file:

```
Read /node_modules/@hitit-ai/primevue-agent/resources/markdown/planning/overview.md and create a plan for: [user's request]
```

The overview will guide the agent through:
- Asking clarification questions
- Choosing components from decision tables
- Writing a structured plan with imports, props, state, events
- Running through the checklist before handing off

## Directory Structure

```
node_modules/@hitit-ai/primevue-agent/
├── package.json
├── README.md                          ← You are here
├── scripts/
│   ├── postinstall.mjs                ← Injects rules into AGENTS.md / CLAUDE.md
│   └── preuninstall.mjs               ← Removes rules on uninstall
└── resources/
    └── markdown/
        └── planning/
            ├── overview.md            ← Start here — master orchestrator
            ├── component-selection.md ← Decision tables: use case → component
            ├── form-inputs.md         ← Form fields, validation, layout helpers
            ├── data-display.md        ← DataTable, Tree, Charts, Tags, Progress
            ├── overlays.md            ← Dialog, Toast, Confirm, Popover, Drawer
            ├── navigation.md          ← Menubar, Tabs, Stepper, Breadcrumb
            ├── layout.md             ← Panel, Accordion, Card, Splitter, Skeleton
            ├── media.md               ← Image, Galleria, Carousel, ImageCompare
            ├── feedback.md            ← Toast, Message, ProgressBar, loading states
            ├── theming.md             ← Design tokens, presets, dark mode, PT, icons
            ├── accessibility.md       ← ARIA, keyboard nav, screen readers, WCAG
            ├── testing.md             ← Vitest, Testing Library, Playwright patterns
            ├── checklist.md           ← Pre-implementation verification checklist
            └── components/            ← Full PrimeVue docs per component (88 files)
                ├── accordion.md
                ├── autocomplete.md
                ├── avatar.md
                ├── badge.md
                ├── ...
                └── virtualscroller.md
```

## Planning Guide Files

| File | Purpose |
|---|---|
| **overview.md** | Entry point. Contains planning order, required plan format, section templates, and links to all other files |
| **component-selection.md** | Decision tables organized by use case ("User needs to enter…", "User needs to see…", etc.) mapping to components with import paths |
| **form-inputs.md** | Detailed guide for all form input components: text, number, date, select, checkbox, file upload, validation patterns |
| **data-display.md** | DataTable (sorting, filtering, pagination, lazy, editing), TreeTable, DataView, Chart, Tag, Badge, Avatar, Progress |
| **overlays.md** | Dialog, DynamicDialog, ConfirmDialog, ConfirmPopup, Popover, Tooltip, Drawer, Toast, Message, service registration |
| **navigation.md** | Menubar, MegaMenu, Menu, TieredMenu, ContextMenu, PanelMenu, Breadcrumb, Tabs, Stepper, Dock, SpeedDial, ScrollTop |
| **layout.md** | Accordion, Panel, Fieldset, Card, Splitter, Divider, Toolbar, Inplace, DeferredContent, Skeleton, BlockUI, Fluid |
| **media.md** | Image (with preview), ImageCompare, Galleria (thumbnails, fullscreen), Carousel (responsive, vertical) |
| **feedback.md** | Notification strategy (Toast vs Message), loading patterns (Skeleton, ProgressBar, Button loading), BlockUI |
| **theming.md** | Design tokens (primitive, semantic, component), custom presets, dark mode, Tailwind integration, Pass Through, PrimeIcons |
| **accessibility.md** | ARIA labeling, keyboard navigation, focus management, screen reader patterns, WCAG checklist |
| **testing.md** | Vitest setup, component testing patterns, E2E selectors, test ID conventions |
| **checklist.md** | Final verification before implementation: imports, v-model types, required props, slot names, services, accessibility, performance |

## Component Docs (88 files)

The `components/` folder contains the full official PrimeVue LLM documentation for every component, fetched from `https://primevue.org/llms/components/{name}.md`. Each file includes:

- Import path
- Feature examples with code
- Complete Props table
- Slots reference
- Events reference
- Pass Through options
- CSS classes
- Design tokens

## Example Prompt

```
Using Hitit PrimeVue Agent, produce an implementation plan for a PrimeVue application. The application is
a Product Management module with the following capabilities:

- List products in a DataTable (name, price, category, status)
- Sorting, filtering, and pagination
- Inline editing for price
- Create new products via a "New Product" button that opens a Dialog with a form
- Edit and delete existing products
- Toast notifications for create/update/delete outcomes
- Dark mode support across all UI

The plan should:
- Describe the primary user flows end to end (for example: listing products, filtering/sorting, inline price update, creating a product via dialog, deleting a product).
- Map each domain concept and flow to concrete PrimeVue primitives (DataTable, Column, Paginator, InputText/InputNumber, Dropdown/MultiSelect, Dialog, Form handling, Buttons, Toast, ConfirmDialog, Skeleton/ProgressSpinner).
- Identify state transitions (such as idle → loading → success/error, view → edit → saved, dialog closed → open → submitted) and the UI Actions/events that trigger them.
- Specify the data layer design (API endpoints, DTO shape, pagination/sort/filter query format, optimistic vs pessimistic updates, error handling strategy).
- Define validation rules and UX constraints (required fields, numeric ranges for price, unique name/SKU if applicable, disabled states, unsaved changes guard).
- Include dark mode theming strategy (CSS variables/design tokens, persistence of theme choice, component-level considerations).
- Provide a phased build plan with milestones and acceptance criteria for each phase.
```

## What Gets Injected

When installed, Hitit adds the following rules section to your `AGENTS.md` and `CLAUDE.md`:

```markdown
=== primevue/hitit rules ===

## Hitit PrimeVue Agent

You are writing PrimeVue v4 implementation plans for Vue.js interfaces. Plans must be
specific enough that an implementing agent can write code without making decisions.

**Start here**: Read
`/node_modules/@hitit-ai/primevue-agent/resources/markdown/planning/overview.md` for plan format,
required sections, and what to clarify with the user before planning.

Component-level documentation is available at
`/node_modules/@hitit-ai/primevue-agent/resources/markdown/planning/components/{component-name}.md` for full
props, events, slots, and styling details.
```

## Credits

- Structure inspired by [Filament Blueprint](https://filamentphp.com/insights/danharrin-filament-v5-blueprint)
- Component documentation from [PrimeVue](https://primevue.org) official LLM docs
- PrimeVue v4 — https://primevue.org