bps-kit 1.0.18 → 1.1.0

package/templates/agents-template/workflows/build-site.md

@@ -0,0 +1,122 @@
+---
+description: Build cinematic landing pages with preset design systems, GSAP animations, and optional Stitch integration
+---
+
+# build-site
+
+End-to-end workflow for building a cinematic, pixel-perfect landing page from scratch.
+
+## When to Use
+
+- User asks to "build a site", "create a landing page", "make a one-pager"
+- User wants a cinematic/premium web presence with animations
+- User wants to use Stitch MCP to generate or extend pages
+
+## Prerequisites
+
+- Node.js installed
+- Agent: `site-builder` (loaded automatically)
+
+## Workflow Steps
+
+### Phase 1 — Discovery (Socratic Gate)
+
+> **DO NOT SKIP.** Ask all 4 questions before writing any code.
+
+Activate the `site-builder` agent and present the 4 mandatory questions:
+
+1. **Brand name + purpose** (one sentence)
+2. **Aesthetic preset** (A: Organic Tech, B: Midnight Luxe, C: Brutalist Signal, D: Vapor Clinic)
+3. **3 value propositions** (short phrases)
+4. **Primary CTA** (what visitors should do)
+
+Wait for user responses. Do not assume answers.
+
+### Phase 2 — Design Token Mapping
+
+From the user's answers:
+
+1. Load the selected preset's full design tokens from `site-builder` agent:
+   - Palette (primary, accent, background, dark)
+   - Typography (heading, drama, data fonts)
+   - Image mood (Unsplash keywords)
+   - Hero phrase pattern
+
+2. Generate all copy:
+   - Hero headline (following preset's phrase pattern)
+   - Feature card titles + descriptions (from 3 value props)
+   - Philosophy contrast statements (from brand purpose)
+   - Protocol steps (from brand methodology)
+   - Pricing tier names (aligned to brand)
+
+### Phase 3 — Scaffold & Build
+
+```bash
+npm create vite@latest {brand-slug} -- --template react
+cd {brand-slug}
+npm install gsap @gsap/react lucide-react
+```
+
+Create all files following `site-builder` agent's Component Architecture:
+
+| Component | File | Priority |
+|-----------|------|----------|
+| Navbar | `App.jsx` or `components/Navbar.jsx` | P0 |
+| Hero | `App.jsx` or `components/Hero.jsx` | P0 |
+| Features (3 interactive cards) | `components/Features.jsx` | P0 |
+| Philosophy | `components/Philosophy.jsx` | P1 |
+| Protocol (sticky stack) | `components/Protocol.jsx` | P1 |
+| Pricing | `components/Pricing.jsx` | P2 |
+| Footer | `components/Footer.jsx` | P2 |
+| Noise overlay + utilities | `index.css` | P0 |
+
+**Rules:**
+- Load Google Fonts via `<link>` in `index.html`
+- Use real Unsplash URLs (match `imageMood`)
+- Every animation uses `gsap.context()` with cleanup
+- Mobile-first responsive design
+
+### Phase 4 — Quality Assurance
+
+Before declaring done, verify:
+
+| Check | How |
+|-------|-----|
+| All animations work | Open dev server, scroll through all sections |
+| All images load | No broken Unsplash URLs |
+| Mobile responsive | Check at 375px, 768px, 1440px |
+| No console errors | DevTools clean |
+| CTA visible | Above fold on desktop, prominent on mobile |
+| Noise overlay active | Subtle grain visible on backgrounds |
+
+Use `verification-before-completion` skill.
+
+### Phase 5 — Stitch Extension (Optional)
+
+If the user wants to add more pages or extract the design system:
+
+1. **Extract design system:** Run `design-md` skill to create `DESIGN.md` from the built site
+2. **Generate new pages:** Use `enhance-prompt` to polish the prompt, then generate via Stitch MCP
+3. **Convert to React:** Use `react-components` skill to convert Stitch HTML into modular components
+4. **Autonomous loop:** (Extra profile only) Use `stitch-loop` for multi-page autonomous generation
+
+## Integration Notes
+
+- This workflow auto-routes to the `site-builder` agent
+- Skills `scroll-experience` and `tailwind-patterns` are auto-loaded via the agent's frontmatter
+- The `frontend-specialist` agent can handle component-level work within the built site
+- For design system extraction, the `design-md` skill works independently of Stitch MCP
+
+## Examples
+
+**Simple:**
+> "Cria uma landing page cinematográfica para minha startup"
+→ Triggers build-site workflow → Socratic Gate with 4 questions → Full build
+
+**With Stitch:**
+> "Usa o Stitch pra gerar a página About baseada no design do meu site"
+→ Uses `design-md` to extract tokens → `enhance-prompt` to polish → Stitch MCP to generate
+
+**Autonomous multi-page:**
+> "Constrói 5 páginas pro meu site usando Stitch em loop"
+→ Uses `stitch-loop` skill (Extra profile) for autonomous baton-passing generation

package/templates/skills_extra/stitch-loop/README.md

@@ -0,0 +1,54 @@
+# Stitch Build Loop Skill
+
+Teaches agents to iteratively build websites using Stitch with an autonomous baton-passing loop pattern.
+
+## Install
+
+```bash
+npx skills add google-labs-code/stitch-skills --skill stitch-loop --global
+```
+
+## What It Does
+
+Enables continuous, autonomous website development through a "baton" system:
+
+1. Agent reads task from `next-prompt.md`
+2. Generates page via Stitch MCP tools
+3. Integrates into site structure
+4. Writes next task to continue the loop
+
+## Prerequisites
+
+- Stitch MCP Server access
+- A `DESIGN.md` file (generate with the `design-md` skill)
+- A `SITE.md` file for project context
+
+## Example Prompt
+
+```text
+Read my next-prompt.md and generate the page using Stitch, then prepare the next iteration.
+```
+
+## Skill Structure
+
+```
+stitch-loop/
+├── SKILL.md              — Core pattern instructions
+├── README.md             — This file
+├── resources/
+│   ├── baton-schema.md   — Baton file format spec
+│   └── site-template.md  — SITE.md/DESIGN.md templates
+└── examples/
+    ├── next-prompt.md    — Example baton
+    └── SITE.md           — Example site constitution
+```
+
+## Works With
+
+- **`design-md` skill**: Generate `DESIGN.md` from existing Stitch screens
+- **CI/CD**: GitHub Actions can trigger new iterations on push
+- **Agent chains**: Dispatch to other agents (Jules, etc.)
+
+## Learn More
+
+See [SKILL.md](./SKILL.md) for complete instructions.

package/templates/skills_extra/stitch-loop/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: stitch-loop
+description: Teaches agents to iteratively build websites using Stitch with an autonomous baton-passing loop pattern
+allowed-tools:
+  - "stitch*:*"
+  - "chrome*:*"
+  - "Read"
+  - "Write"
+  - "Bash"
+---
+
+# Stitch Build Loop
+
+You are an **autonomous frontend builder** participating in an iterative site-building loop. Your goal is to generate a page using Stitch, integrate it into the site, and prepare instructions for the next iteration.
+
+## Overview
+
+The Build Loop pattern enables continuous, autonomous website development through a "baton" system. Each iteration:
+1. Reads the current task from a baton file (`.stitch/next-prompt.md`)
+2. Generates a page using Stitch MCP tools
+3. Integrates the page into the site structure
+4. Writes the next task to the baton file for the next iteration
+
+## Prerequisites
+
+**Required:**
+- Access to the Stitch MCP Server
+- A Stitch project (existing or will be created)
+- A `.stitch/DESIGN.md` file (generate one using the `design-md` skill if needed)
+- A `.stitch/SITE.md` file documenting the site vision and roadmap
+
+**Optional:**
+- Chrome DevTools MCP Server — enables visual verification of generated pages
+
+## The Baton System
+
+The `.stitch/next-prompt.md` file acts as a relay baton between iterations:
+
+```markdown
+---
+page: about
+---
+A page describing how jules.top tracking works.
+
+**DESIGN SYSTEM (REQUIRED):**
+[Copy from .stitch/DESIGN.md Section 6]
+
+**Page Structure:**
+1. Header with navigation
+2. Explanation of tracking methodology
+3. Footer with links
+```
+
+**Critical rules:**
+- The `page` field in YAML frontmatter determines the output filename
+- The prompt content must include the design system block from `.stitch/DESIGN.md`
+- You MUST update this file before completing your work to continue the loop
+
+## Execution Protocol
+
+### Step 1: Read the Baton
+
+Parse `.stitch/next-prompt.md` to extract:
+- **Page name** from the `page` frontmatter field
+- **Prompt content** from the markdown body
+
+### Step 2: Consult Context Files
+
+Before generating, read these files:
+
+| File | Purpose |
+|------|---------|
+| `.stitch/SITE.md` | Site vision, **Stitch Project ID**, existing pages (sitemap), roadmap |
+| `.stitch/DESIGN.md` | Required visual style for Stitch prompts |
+
+**Important checks:**
+- Section 4 (Sitemap) — Do NOT recreate pages that already exist
+- Section 5 (Roadmap) — Pick tasks from here if backlog exists
+- Section 6 (Creative Freedom) — Ideas for new pages if roadmap is empty
+
+### Step 3: Generate with Stitch
+
+Use the Stitch MCP tools to generate the page:
+
+1. **Discover namespace**: Run `list_tools` to find the Stitch MCP prefix
+2. **Get or create project**: 
+   - If `.stitch/metadata.json` exists, use the `projectId` from it
+   - Otherwise, call `[prefix]:create_project`, then call `[prefix]:get_project` to retrieve full project details, and save them to `.stitch/metadata.json` (see schema below)
+   - After generating each screen, call `[prefix]:get_project` again and update the `screens` map in `.stitch/metadata.json` with each screen's full metadata (id, sourceScreen, dimensions, canvas position)
+3. **Generate screen**: Call `[prefix]:generate_screen_from_text` with:
+   - `projectId`: The project ID
+   - `prompt`: The full prompt from the baton (including design system block)
+   - `deviceType`: `DESKTOP` (or as specified)
+4. **Retrieve assets**: Before downloading, check if `.stitch/designs/{page}.html` and `.stitch/designs/{page}.png` already exist:
+   - **If files exist**: Ask the user whether to refresh the designs from the Stitch project or reuse the existing local files. Only re-download if the user confirms.
+   - **If files do not exist**: Proceed with download:
+     - `htmlCode.downloadUrl` — Download and save as `.stitch/designs/{page}.html`
+      - `screenshot.downloadUrl` — Append `=w{width}` to the URL before downloading, where `{width}` is the `width` value from the screen metadata (Google CDN serves low-res thumbnails by default). Save as `.stitch/designs/{page}.png`
+
+### Step 4: Integrate into Site
+
+1. Move generated HTML from `.stitch/designs/{page}.html` to `site/public/{page}.html`
+2. Fix any asset paths to be relative to the public folder
+3. Update navigation:
+   - Find existing placeholder links (e.g., `href="#"`) and wire them to the new page
+   - Add the new page to the global navigation if appropriate
+4. Ensure consistent headers/footers across all pages
+
+### Step 4.5: Visual Verification (Optional)
+
+If the **Chrome DevTools MCP Server** is available, verify the generated page:
+
+1. **Check availability**: Run `list_tools` to see if `chrome*` tools are present
+2. **Start dev server**: Use Bash to start a local server (e.g., `npx serve site/public`)
+3. **Navigate to page**: Call `[chrome_prefix]:navigate` to open `http://localhost:3000/{page}.html`
+4. **Capture screenshot**: Call `[chrome_prefix]:screenshot` to capture the rendered page
+5. **Visual comparison**: Compare against the Stitch screenshot (`.stitch/designs/{page}.png`) for fidelity
+6. **Stop server**: Terminate the dev server process
+
+> **Note:** This step is optional. If Chrome DevTools MCP is not installed, skip to Step 5.
+
+### Step 5: Update Site Documentation
+
+Modify `.stitch/SITE.md`:
+- Add the new page to Section 4 (Sitemap) with `[x]`
+- Remove any idea you consumed from Section 6 (Creative Freedom)
+- Update Section 5 (Roadmap) if you completed a backlog item
+
+### Step 6: Prepare the Next Baton (Critical)
+
+**You MUST update `.stitch/next-prompt.md` before completing.** This keeps the loop alive.
+
+1. **Decide the next page**: 
+   - Check `.stitch/SITE.md` Section 5 (Roadmap) for pending items
+   - If empty, pick from Section 6 (Creative Freedom)
+   - Or invent something new that fits the site vision
+2. **Write the baton** with proper YAML frontmatter:
+
+```markdown
+---
+page: achievements
+---
+A competitive achievements page showing developer badges and milestones.
+
+**DESIGN SYSTEM (REQUIRED):**
+[Copy the entire design system block from .stitch/DESIGN.md]
+
+**Page Structure:**
+1. Header with title and navigation
+2. Badge grid showing unlocked/locked states
+3. Progress bars for milestone tracking
+```
+
+## File Structure Reference
+
+```
+project/
+├── .stitch/
+│   ├── metadata.json   # Stitch project & screen IDs (persist this!)
+│   ├── DESIGN.md       # Visual design system (from design-md skill)
+│   ├── SITE.md         # Site vision, sitemap, roadmap
+│   ├── next-prompt.md  # The baton — current task
+│   └── designs/        # Staging area for Stitch output
+│       ├── {page}.html
+│       └── {page}.png
+└── site/public/        # Production pages
+    ├── index.html
+    └── {page}.html
+```
+
+### `.stitch/metadata.json` Schema
+
+This file persists all Stitch identifiers so future iterations can reference them for edits or variants. Populate it by calling `[prefix]:get_project` after creating a project or generating screens.
+
+```json
+{
+  "name": "projects/6139132077804554844",
+  "projectId": "6139132077804554844",
+  "title": "My App",
+  "visibility": "PRIVATE",
+  "createTime": "2026-03-04T23:11:25.514932Z",
+  "updateTime": "2026-03-04T23:34:40.400007Z",
+  "projectType": "PROJECT_DESIGN",
+  "origin": "STITCH",
+  "deviceType": "MOBILE",
+  "designTheme": {
+    "colorMode": "DARK",
+    "font": "INTER",
+    "roundness": "ROUND_EIGHT",
+    "customColor": "#40baf7",
+    "saturation": 3
+  },
+  "screens": {
+    "index": {
+      "id": "d7237c7d78f44befa4f60afb17c818c1",
+      "sourceScreen": "projects/6139132077804554844/screens/d7237c7d78f44befa4f60afb17c818c1",
+      "x": 0,
+      "y": 0,
+      "width": 390,
+      "height": 1249
+    },
+    "about": {
+      "id": "bf6a3fe5c75348e58cf21fc7a9ddeafb",
+      "sourceScreen": "projects/6139132077804554844/screens/bf6a3fe5c75348e58cf21fc7a9ddeafb",
+      "x": 549,
+      "y": 0,
+      "width": 390,
+      "height": 1159
+    }
+  },
+  "metadata": {
+    "userRole": "OWNER"
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name` | Full resource name (`projects/{id}`) |
+| `projectId` | Stitch project ID (from `create_project` or `get_project`) |
+| `title` | Human-readable project title |
+| `designTheme` | Design system tokens: color mode, font, roundness, custom color, saturation |
+| `deviceType` | Target device: `MOBILE`, `DESKTOP`, `TABLET` |
+| `screens` | Map of page name → screen object. Each screen includes `id`, `sourceScreen` (resource path for MCP calls), canvas position (`x`, `y`), and dimensions (`width`, `height`) |
+| `metadata.userRole` | User's role on the project (`OWNER`, `EDITOR`, `VIEWER`) |
+
+## Orchestration Options
+
+The loop can be driven by different orchestration layers:
+
+| Method | How it works |
+|--------|--------------|
+| **CI/CD** | GitHub Actions triggers on `.stitch/next-prompt.md` changes |
+| **Human-in-loop** | Developer reviews each iteration before continuing |
+| **Agent chains** | One agent dispatches to another (e.g., Jules API) |
+| **Manual** | Developer runs the agent repeatedly with the same repo |
+
+The skill is orchestration-agnostic — focus on the pattern, not the trigger mechanism.
+
+## Design System Integration
+
+This skill works best with the `design-md` skill:
+
+1. **First time setup**: Generate `.stitch/DESIGN.md` using the `design-md` skill from an existing Stitch screen
+2. **Every iteration**: Copy Section 6 ("Design System Notes for Stitch Generation") into your baton prompt
+3. **Consistency**: All generated pages will share the same visual language
+
+## Common Pitfalls
+
+- ❌ Forgetting to update `.stitch/next-prompt.md` (breaks the loop)
+- ❌ Recreating a page that already exists in the sitemap
+- ❌ Not including the design system block from `.stitch/DESIGN.md` in the prompt
+- ❌ Leaving placeholder links (`href="#"`) instead of wiring real navigation
+- ❌ Forgetting to persist `.stitch/metadata.json` after creating a new project
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| Stitch generation fails | Check that the prompt includes the design system block |
+| Inconsistent styles | Ensure `.stitch/DESIGN.md` is up-to-date and copied correctly |
+| Loop stalls | Verify `.stitch/next-prompt.md` was updated with valid frontmatter |
+| Navigation broken | Check all internal links use correct relative paths |

package/templates/skills_extra/stitch-loop/examples/SITE.md

@@ -0,0 +1,73 @@
+---
+stitch-project-id: 13534454087919359824
+---
+# Project Vision & Constitution
+
+> **AGENT INSTRUCTION:** Read this file before every iteration. It serves as the project's "Long-Term Memory." If `next-prompt.md` is empty, pick the highest priority item from Section 5 OR invent a new page that fits the project vision.
+
+## 1. Core Identity
+* **Project Name:** Oakwood Furniture Co.
+* **Stitch Project ID:** `13534454087919359824`
+* **Mission:** A premium online furniture showroom showcasing handcrafted, sustainable wood furniture.
+* **Target Audience:** Design-conscious homeowners, interior designers, eco-minded buyers.
+* **Voice:** Warm, refined, artisanal, and trustworthy.
+
+## 2. Visual Language (Stitch Prompt Strategy)
+*Strictly adhere to these descriptive rules when prompting Stitch. Do NOT use code.*
+
+* **The "Vibe" (Adjectives):**
+    * *Primary:* **Warm** (Inviting, cozy, natural materials).
+    * *Secondary:* **Minimal** (Clean layouts, breathing room, gallery-like).
+    * *Tertiary:* **Artisanal** (Handcrafted feel, attention to detail).
+
+* **Color Philosophy (Semantic):**
+    * **Backgrounds:** Warm barely-there cream (#FCFAFA). Soft, inviting canvas.
+    * **Accents:** Deep muted teal-navy (#294056) for CTAs and highlights.
+    * **Text:** Charcoal near-black (#2C2C2C) for headlines, soft gray (#6B6B6B) for body.
+
+## 3. Architecture & File Structure
+* **Root:** `site/public/`
+* **Asset Flow:** Stitch generates to `queue/` -> Validate -> Move to `site/public/`.
+* **Navigation Strategy:**
+    * **Global Header:** Logo, Shop, Collections, About, Contact.
+    * **Global Footer:** Sustainability, Craftsmanship, Shipping Info, Social Links.
+
+## 4. Live Sitemap (Current State)
+*The Agent MUST update this section when a new page is successfully merged.*
+
+* [x] `index.html` - Homepage with hero and featured collections.
+* [x] `collections.html` - Overview of furniture categories.
+* [x] `about.html` - Our story and craftsmanship philosophy.
+* [ ] `contact.html` - Contact form and showroom locations.
+
+## 5. The Roadmap (Backlog)
+*If `next-prompt.md` is empty or completed, pick the next task from here.*
+
+### High Priority
+- [ ] **Product Detail Page:** Template for individual furniture items.
+- [ ] **Contact Page:** Contact form with showroom map.
+
+### Medium Priority
+- [ ] **Sustainability Page:** Our commitment to eco-friendly practices.
+- [ ] **Care Guide:** How to maintain wood furniture.
+
+## 6. Creative Freedom Guidelines
+*When the backlog is empty, follow these guidelines to innovate.*
+
+1. **Stay On-Brand:** New pages must fit the "Warm + Minimal + Artisanal" vibe.
+2. **Enhance the Core:** Support the furniture shopping experience.
+3. **Naming Convention:** Use lowercase, descriptive filenames.
+
+### Ideas to Explore
+*Pick one, build it, then REMOVE it from this list.*
+
+- [ ] `materials.html` - Showcase of wood types and finishes
+- [ ] `custom.html` - Custom furniture ordering process
+- [ ] `gallery.html` - Customer homes featuring our furniture
+- [ ] `blog.html` - Design tips and furniture care articles
+
+## 7. Rules of Engagement
+1. Do not recreate pages in Section 4.
+2. Always update `next-prompt.md` before completing.
+3. Consume ideas from Section 6 when you use them.
+4. Keep the loop moving.

package/templates/skills_extra/stitch-loop/examples/next-prompt.md

@@ -0,0 +1,25 @@
+---
+page: contact
+---
+A warm, inviting contact page for Oakwood Furniture Co.
+
+**DESIGN SYSTEM (REQUIRED):**
+- Platform: Web, Desktop-first
+- Theme: Light, minimal, photography-first
+- Background: Warm barely-there cream (#FCFAFA)
+- Surface: Crisp very light gray (#F5F5F5) for cards
+- Primary Accent: Deep muted teal-navy (#294056) for buttons and links
+- Text Primary: Charcoal near-black (#2C2C2C) for headlines
+- Text Secondary: Soft warm gray (#6B6B6B) for body copy
+- Font: Modern sans-serif (Manrope or similar), clean and approachable
+- Buttons: Subtly rounded corners (8px), comfortable padding
+- Cards: Gently rounded corners (12px), whisper-soft shadows on hover
+- Layout: Centered content, max-width container, generous whitespace
+- No harsh shadows, no aggressive colors - serene and trustworthy
+
+**Page Structure:**
+1. **Header:** Navigation with logo, Shop, Collections, About, Contact (active)
+2. **Hero Section:** Warm headline "Get in Touch" with a brief welcome message
+3. **Contact Form:** Name, email, message fields with the teal-navy submit button
+4. **Showroom Info:** Address, hours, and an embedded map or beautiful showroom photo
+5. **Footer:** Sustainability, Craftsmanship, Shipping links, and social icons

package/templates/skills_extra/stitch-loop/resources/baton-schema.md

@@ -0,0 +1,61 @@
+# Baton File Schema
+
+The baton file (`next-prompt.md`) is the communication mechanism between loop iterations. It tells the next agent what to build.
+
+## Format
+
+```yaml
+---
+page: <filename-without-extension>
+---
+<prompt-content>
+```
+
+## Fields
+
+### Frontmatter (YAML)
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `page` | string | Yes | Output filename (without `.html` extension) |
+
+### Body (Markdown)
+
+The body contains the full Stitch prompt, which must include:
+
+1. **One-line description** with vibe/atmosphere keywords
+2. **Design System block** (required) — copied from `DESIGN.md` Section 6
+3. **Page Structure** — numbered list of sections/components
+
+## Example
+
+```markdown
+---
+page: achievements
+---
+A competitive, gamified achievements page with terminal aesthetics.
+
+**DESIGN SYSTEM (REQUIRED):**
+- Platform: Web, Desktop-first
+- Theme: Dark, minimal, data-focused
+- Background: Deep charcoal/near-black (#0f1419)
+- Primary Accent: Teal/Cyan (#2dd4bf)
+- Text Primary: White (#ffffff)
+- Font: Clean sans-serif (Inter, SF Pro, or system default)
+- Layout: Centered content, max-width container
+
+**Page Structure:**
+1. Header with title "Achievements" and navigation
+2. Badge grid showing locked/unlocked states with icons
+3. Progress section with milestone bars
+4. Footer with links to other pages
+```
+
+## Validation Rules
+
+Before completing an iteration, validate your baton:
+
+- [ ] `page` frontmatter field exists and is a valid filename
+- [ ] Prompt includes the design system block
+- [ ] Prompt describes a page NOT already in `SITE.md` sitemap
+- [ ] Prompt includes specific page structure details