Skip to content

jay-skill.md

Latest commit

 

History

History
123 lines (93 loc) · 4.6 KB

jay-skill.md

File metadata and controls

123 lines (93 loc) · 4.6 KB
Raw
name jay
description Getting started with Jay Stack projects. Covers plugin setup, agent-kit generation, the four roles (designer, developer, plugin, devops), and key CLI commands.

Jay Stack — Agent Skill

Jay Stack is a full-stack framework. Plugins provide headless components (data + logic, no UI). Designers build UI in jay-html templates that bind to plugin contracts. Developers write page logic and services.

Getting Started with a Jay Project

Step 1: Setup plugins

yarn jay-stack-cli setup

This configures plugins — creates config templates, validates credentials, connects to external services. Run this once when starting a new project or after adding a plugin.

Step 2: Generate the agent kit

yarn jay-stack-cli agent-kit

This materializes contracts, generates reference data, and copies role guides into agent-kit/. Run this after setup, or any time you need fresh contract data.

Step 3: Read the agent kit

The agent kit is your entry point. Start here:

agent-kit/plugins-index.yaml — lists every plugin and what it provides:

plugins:
  - name: wix-stores
    contracts:
      - name: product-page
        description: Product detail page with SSR
    actions:
      - name: searchProducts
        description: Search the product catalog
    services:
      - name: products-db
        description: Product catalog API
    commands:
      - name: sync-catalog
        description: Sync product catalog from CMS

Use this file to discover what's available before writing any code.

agent-kit/materialized-contracts/ — the actual .jay-contract files. Read these to understand the data shapes, rendering phases, and refs for each component.

agent-kit/references/<plugin>/ — pre-generated discovery data (product catalogs, collection schemas, etc.). Check here before running CLI commands — it's faster.

The Four Roles

The agent kit contains guides organized by role. Read the role that matches your task:

Folder Role When to read
agent-kit/designer/ Designer Creating or editing .jay-html pages, styling, template syntax
agent-kit/developer/ Developer Writing page.ts components, services, state management, routing
agent-kit/plugin/ Plugin Developer Creating headless components, contracts, actions, CLI commands
agent-kit/devops/ DevOps Building, deploying, serving in production, invalidation

Each folder has an INSTRUCTIONS.md that lists all available guides. Start there.

Key CLI Commands

# Development
yarn jay-stack-cli dev                    # Start dev server
yarn jay-stack-cli dev -v                 # Verbose mode

# Validation
yarn jay-stack-cli validate               # Validate all jay-html, contracts, actions

# Discovery
yarn jay-stack-cli agent-kit --list       # List available contracts
yarn jay-stack-cli params <plugin>/<contract>  # Discover URL params for a contract
yarn jay-stack-cli action <plugin>/<action> --input '{}'  # Run a plugin action

# Plugin commands (admin/batch operations)
yarn jay-stack-cli run --list             # List available plugin commands
yarn jay-stack-cli run <plugin>/<command> # Run a plugin command

# Production
yarn jay-stack-cli build                  # Build production artifacts
yarn jay-stack-cli serve                  # Start production server

Project Structure

src/
  pages/              # File-system routing
    page.jay-html     # Root page (/)
    products/
      page.jay-html   # /products
      [slug]/
        page.jay-html # /products/:slug
        page.ts       # Page component (optional)
  plugins/            # Local plugins
  components/         # Headfull components
  init.ts             # Project service initialization
agent-kit/            # Generated by jay-stack agent-kit
  plugins-index.yaml  # Discovery index
  designer/           # Designer role guides
  developer/          # Developer role guides
  plugin/             # Plugin developer guides
  devops/             # DevOps guides
  materialized-contracts/
  references/

Before Writing Code

  1. Read agent-kit/plugins-index.yaml to see what plugins and contracts exist
  2. Read the relevant contract file to understand the data shape
  3. Read the role guide that matches your task (designer/developer/plugin/devops)
  4. Check agent-kit/references/<plugin>/ for pre-generated data before using CLI commands