Skip to content

Commit 9b2b18f

Browse files
jal-cojal-co
authored
chore(repo): track .pi/, apply RFC 2119, clean up skills and prompts (#8)
* chore(repo): track AGENTS.md and .pi/, clean up skills and prompts - Remove AGENTS.md and .pi/ from .gitignore - Apply RFC 2119 keywords to AGENTS.md for unambiguous requirements - Update branch naming to follow Conventional Branch spec - Remove posthog-integration and seo-aeo-best-practices skills - Consolidate duplicate prompts (keep component-create, component-review, ideate) - Remove create-jalco-component, create-jalco-block, review-jalco-component - Update prompts README * refactor(pi): apply RFC 2119 keywords and XML structure to skills and prompts - Add XML semantic tags (overview, context, workflow, rules, constraints, guidelines, quality-checklist, instructions, format, examples) to all SKILL.md files and prompt files - Convert casual requirement language to RFC 2119 keywords (MUST, SHOULD, MAY) - Track .pi/prompts/ (removed prompts/ from .gitignore) - Leave rules/ reference files untouched (code pattern docs, not directives) - Leave AGENTS.md and README.md in vercel-* skills as-is (generated/informational) * chore(repo): clean up root directory - Create docs-component-format-spec.md in .pi/references/ (was missing) - Update all skill/prompt references to new path - Remove docs-component-format-spec.md and prompts/ from .gitignore - Delete empty launch-posts/ directory --------- Co-authored-by: Justin Levine <20596508+justinlevinedotme@users.noreply.github.com>
1 parent d41e35d commit 9b2b18f

86 files changed

Lines changed: 10930 additions & 4 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,10 +45,7 @@ next-env.d.ts
4545

4646
# local agent/tooling artifacts
4747
.agents/
48-
.pi/
49-
prompts/
50-
docs-component-format-spec.md
51-
AGENTS.md
48+
5249
skills-lock.json
5350
bun.lock
5451
.env.local

‎.pi/prompts/README.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# jal-co/ui Prompts
2+
3+
Repo-aware prompts for creating, reviewing, and ideating jalco ui registry content.
4+
5+
## Prompts
6+
7+
- `/component-create` — create a new component, block, or registry item through the standard workflow
8+
- `/component-review` — audit an existing component against the jalco ui quality bar
9+
- `ideate-jalco-components.md` — ideate new additions based on the current repo state
10+
11+
## How they work
12+
13+
Each prompt:
14+
- reads the repo first (AGENTS.md, registry.json, existing patterns)
15+
- consults local skills before generating output
16+
- acts as an implementation/review partner, not a generic text generator
17+
- follows Conventional Branch naming for feature branches

‎.pi/prompts/component-create.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# /component-create
2+
3+
Build a new jalco ui component through the standard repository workflow.
4+
5+
<context>
6+
Use this prompt when the user wants to create a new component, block, registry item, or docs-facing UI artifact.
7+
</context>
8+
9+
<instructions>
10+
11+
1. Create a feature branch: `feat/<component-name>`.
12+
2. Read `.pi/skills/jalco-component-builder/SKILL.md` first and treat it as the primary workflow.
13+
3. If the request is underspecified, use the `question` or `questionnaire` tool to clarify the component before coding.
14+
4. Use concise, Socratic questioning to determine:
15+
- the core use case
16+
- whether this is a primitive, composed component, or block
17+
- whether it belongs in the public registry, docs site only, or both
18+
- the intended default feel and strongest default state
19+
- the minimum public API
20+
- which variants are truly justified
21+
- whether the component should stay in one file
22+
- whether any dependency is genuinely needed
23+
5. SHOULD prefer a single-file implementation unless multiple files materially improve readability, runtime correctness, reuse, or installability.
24+
6. Use supporting references named in `jalco-component-builder` as needed, especially for shadcn ergonomics, Tailwind v4 patterns, composition, React/Next implementation quality, and accessibility.
25+
7. Reuse established Jalco and shadcn variant language when appropriate, but MUST NOT add variants mechanically.
26+
8. SHOULD prefer strong default styling, realistic preview content, and restrained visual treatment over decorative complexity.
27+
9. If this is a public component, MUST update the docs, preview/demo coverage, and any relevant registry metadata in the same change.
28+
10. MUST create a catalog card preview at `components/docs/previews/<registry-name>.tsx` showing key variants, and run `pnpm previews:generate`.
29+
11. MUST add the sidebar nav entry in `lib/docs.ts` with `badge: "New"` and `badgeAdded` set to today's ISO date.
30+
12. MUST generate screenshots via `/dev/screenshots` — save `<name>-dark.png` and `<name>-light.png` to `public/previews/`.
31+
13. MUST run `pnpm registry:build` and `pnpm build` to verify.
32+
14. MUST open a PR using the component template and attach dark/light screenshots.
33+
15. MUST keep comments compact and useful. Use Jalco-style file headers when appropriate. MUST NOT add decorative separator banners.
34+
35+
</instructions>
36+
37+
<format>
38+
39+
## Output expectations
40+
41+
Before implementing, briefly state:
42+
- the component's use case
43+
- the proposed API shape
44+
- the justified variants
45+
- the one-file vs multi-file decision
46+
- any dependency decision
47+
48+
Then implement the component and related docs updates.
49+
50+
</format>

‎.pi/prompts/component-review.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# /component-review
2+
3+
Audit a jalco ui component using the repository's public component quality bar.
4+
5+
<context>
6+
Use this prompt when the user wants feedback on an existing component, registry item, docs-facing component, preview, or public API.
7+
</context>
8+
9+
<instructions>
10+
11+
1. MUST read `.pi/skills/jalco-component-builder/SKILL.md` first and use it as the review rubric.
12+
2. MUST inspect the component source, related demos/previews, and relevant docs before judging quality.
13+
3. Evaluate the component for:
14+
- clarity of use case
15+
- quality of the default state
16+
- visual hierarchy and restraint
17+
- API size and semantic clarity
18+
- variant discipline
19+
- one-file vs multi-file appropriateness
20+
- dependency justification
21+
- accessibility and copy-paste ergonomics
22+
- alignment across implementation, preview, docs, and registry metadata
23+
- presence of a catalog card preview file in `components/docs/previews/`
24+
- sidebar nav entry in `lib/docs.ts`
25+
4. MUST be direct and critical when needed. MUST NOT praise weak work just because it is technically valid.
26+
5. If recommending changes, prioritize:
27+
- what SHOULD be removed or simplified
28+
- which variants SHOULD be merged or cut
29+
- whether the file structure SHOULD be collapsed
30+
- whether dependencies SHOULD be avoided
31+
- how the default example SHOULD be improved
32+
33+
</instructions>
34+
35+
<format>
36+
37+
## Output structure
38+
39+
1. What feels strong
40+
2. What feels off or generic
41+
3. API and variant issues
42+
4. File structure and dependency issues
43+
5. Recommended changes in priority order
44+
6. Whether the component is ready for jalco ui in its current form
45+
46+
</format>

‎.pi/prompts/ideate-jalco-components.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# /ideate-jalco-components
2+
3+
Ideate new jalco ui additions based on repository context and gaps.
4+
5+
<context>
6+
7+
Before ideating, MUST read these files:
8+
- `AGENTS.md`
9+
- `README.md`
10+
- `registry.json`
11+
- `app/page.tsx`
12+
- `.pi/skills/vercel-react-best-practices/SKILL.md`
13+
- `.pi/skills/vercel-composition-patterns/SKILL.md`
14+
- `.pi/skills/tailwind-design-system/SKILL.md`
15+
16+
Then inspect the current registry items and identify what categories, use cases, or quality levels are missing.
17+
18+
</context>
19+
20+
<instructions>
21+
22+
## Task
23+
24+
Help ideate new jalco ui additions based on this context:
25+
26+
{{IDEATION_CONTEXT}}
27+
28+
## Ideation goals
29+
30+
Suggested additions MUST be:
31+
- practical
32+
- installable
33+
- visually strong
34+
- differentiated from generic examples
35+
- documentation-friendly
36+
- aligned with jalco ui's brand and quality bar
37+
38+
Consider whether each idea is best as a:
39+
- component
40+
- block
41+
- hook
42+
- pattern
43+
- docs concept
44+
45+
## Required process
46+
47+
1. MUST read the required files first.
48+
2. MUST inspect the current registry and surface obvious gaps.
49+
3. SHOULD propose ideas that balance usefulness, visual appeal, and implementation value.
50+
4. SHOULD prioritize ideas that would make jalco ui more distinctive.
51+
5. SHOULD call out quick wins versus longer-term standout additions.
52+
53+
</instructions>
54+
55+
<format>
56+
57+
## Output format
58+
59+
Return these sections:
60+
61+
1. **Current gap summary**
62+
2. **Top 10 proposed additions**
63+
- name
64+
- type
65+
- what it does
66+
- why it belongs in jalco ui
67+
- implementation complexity: low / medium / high
68+
- docs/demo appeal: low / medium / high
69+
3. **Best 3 quick wins**
70+
4. **Best 3 standout additions**
71+
5. **Suggested build order**
72+
6. **Docs categories these ideas support**
73+
74+
</format>
75+
76+
<constraints>
77+
Optimize for additions that would make jalco ui feel curated, not bloated.
78+
</constraints>

‎.pi/references/docs-component-format-spec.md‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Component Docs Format Spec
2+
3+
Canonical reference for the structure, section order, writing rules, and review checklist of jalco ui component documentation pages.
4+
5+
## Page anatomy
6+
7+
Every component docs page MUST use `ComponentDocsPage` from `components/docs/component-docs-page.tsx` and follow this section order:
8+
9+
1. **Metadata** — `export const metadata: Metadata` with `title` and `description`
10+
2. **Header** — rendered by `ComponentDocsPage`: title, description, AiCopyButton, DependencyBadges
11+
3. **Preview** — live component inside `ComponentPreview` with source file tabs
12+
4. **Installation** — `InstallCommand` with registry name; `installNote` for bundled exports
13+
5. **Usage** — import snippet via `CodeLine`, minimal usage example, server/client rendering context
14+
6. **Children** (optional, order as needed):
15+
- Playground
16+
- Examples (variants, sizes, configurations, etc.)
17+
- API Reference
18+
- Notes
19+
20+
## ComponentDocsPage props
21+
22+
| Prop | Type | Required | Purpose |
23+
|---|---|---|---|
24+
| `title` | `string` | yes | Display name (e.g. "GitHub Stars Button") |
25+
| `description` | `string` | yes | One-sentence summary |
26+
| `registryName` | `string` | no | Registry item name; enables install block and badges |
27+
| `sourceFiles` | `(string \| { path, name?, language? })[]` | no | Source file paths for the code tab |
28+
| `preview` | `ReactNode` | no | Live component for the Preview section |
29+
| `installNote` | `ReactNode` | no | Note below install command (e.g. bundled-in explanation) |
30+
| `usage` | `ReactNode` | no | Usage section content |
31+
| `children` | `ReactNode` | no | Everything after Usage |
32+
33+
## Writing rules
34+
35+
### Descriptions
36+
37+
- MUST be one sentence, capability-first
38+
- MUST NOT start with "A", "An", or "A React component for..."
39+
- MUST NOT contain implementation details, subjective adjectives, or unnecessary jargon
40+
- MUST match across: page `metadata.description`, `ComponentDocsPage` `description` prop, and `registry.json` description
41+
42+
### Usage section
43+
44+
- MUST include an import snippet via `CodeLine`
45+
- MUST include a minimal usage example via `CodeLine`
46+
- Server/client rendering context MUST be stated here (e.g. "Async server component")
47+
- The first example SHOULD be minimal — layer complexity in the Examples section
48+
49+
### Examples section
50+
51+
- MUST use `VariantGrid` with labeled items when showing multiple visual states
52+
- MUST group items by meaning: Variants, Sizes, Icon Styles, Configurations, etc.
53+
- MUST NOT label everything as a "variant" — use the most accurate grouping label
54+
- SHOULD use realistic, polished content over placeholder text
55+
56+
### Playground section
57+
58+
- MAY be included when the component has multiple interactive props worth exploring
59+
- SHOULD be a client component that lets users toggle props and see results
60+
61+
### API Reference section
62+
63+
- SHOULD be included when the component has a non-obvious public API
64+
- MUST use `ApiRefTable` from `registry/api-ref-table/api-ref-table`
65+
- SHOULD list all public props with name, type, required flag, and description
66+
67+
### Notes section
68+
69+
- MUST contain only caveats, limitations, and external service behavior
70+
- MUST NOT contain architecture decisions, feature highlights, or rendering context
71+
- SHOULD be brief — a short bulleted list
72+
73+
### Bundled exports
74+
75+
- When a component is bundled inside another registry item, MUST use `installNote` to explain
76+
- MUST set `bundledIn` on the nav item in `lib/docs.ts`
77+
78+
## Section heading style
79+
80+
All `<h2>` headings inside `ComponentDocsPage` children MUST use:
81+
82+
```tsx
83+
<h2 className="text-xl font-semibold tracking-tight">Section Title</h2>
84+
```
85+
86+
Sub-headings (`<h3>`) inside example groups MUST use:
87+
88+
```tsx
89+
<h3 className="text-base font-medium">Group Label</h3>
90+
```
91+
92+
## Naming alignment
93+
94+
These MUST all refer to the same artifact using consistent naming:
95+
- page `metadata.title`
96+
- `ComponentDocsPage` `title` prop
97+
- `registry.json` item `title`
98+
- sidebar nav title in `lib/docs.ts`
99+
- preview file name in `components/docs/previews/`
100+
- component export name
101+
102+
## File header and comment rules
103+
104+
- Public Jalco-authored component source files SHOULD use the compact Jalco-style header
105+
- Headers MUST be compact and human-written in tone
106+
- Headers MUST NOT duplicate the docs page content
107+
- Decorative separator banners MUST NOT appear in source code
108+
- Inline comments MUST be minimal and useful
109+
- Comments MUST NOT narrate straightforward code
110+
111+
## Review checklist
112+
113+
Before shipping a component docs page, verify:
114+
115+
- [ ] Page uses `ComponentDocsPage`
116+
- [ ] `metadata.description` matches `ComponentDocsPage` `description` and `registry.json`
117+
- [ ] Preview renders a realistic default state
118+
- [ ] Usage includes import, minimal example, and server/client context
119+
- [ ] Examples use `VariantGrid` with accurate group labels
120+
- [ ] Notes contains only caveats (no features, no architecture)
121+
- [ ] Sidebar entry in `lib/docs.ts` is correct (title, order, badge, bundledIn)
122+
- [ ] Card preview exists at `components/docs/previews/<registry-name>.tsx`
123+
- [ ] Screenshots exist at `public/previews/<name>-dark.png` and `<name>-light.png`
124+
- [ ] `pnpm previews:generate` has been run
125+
- [ ] `pnpm registry:build` and `pnpm build` pass

0 commit comments

Comments
 (0)