npm - @techwavedev/agi-agent-kit - Versions diffs - 1.1.3 → 1.1.7 - Mend

@techwavedev/agi-agent-kit 1.1.3 → 1.1.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (207) hide show

package/templates/skills/react-components/resources/component-template.tsx ADDED Viewed

@@ -0,0 +1,37 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import React from 'react';
+// Use a valid identifier like 'StitchComponent' as the placeholder
+interface StitchComponentProps {
+  readonly children?: React.ReactNode;
+  readonly className?: string;
+}
+export const StitchComponent: React.FC<StitchComponentProps> = ({
+  children,
+  className = '',
+  ...props
+}) => {
+  return (
+    <div className={`relative ${className}`} {...props}>
+      {children}
+    </div>
+  );
+};
+export default StitchComponent;

package/templates/skills/react-components/resources/stitch-api-reference.md ADDED Viewed

@@ -0,0 +1,14 @@
+# Stitch API reference
+This document describes the data structures returned by the Stitch MCP server to ensure accurate component mapping.
+### Metadata schema
+When calling `get_screen`, the server returns a JSON object with these key properties:
+* **htmlCode**: Contains a `downloadUrl`. This is a signed URL that requires a system-level fetch (curl) to handle redirects and security handshakes.
+* **screenshot**: Includes a `downloadUrl` for the visual design. Use this to verify layout intent that might not be obvious in the raw HTML.
+* **deviceType**: Usually set to `DESKTOP`. All generated components should prioritize the corresponding viewport (2560px width) as the base layout.
+### Technical mapping rules
+1. **Element tracking**: Preserve `data-stitch-id` attributes as comments in the TSX to allow for future design synchronization.
+2. **Asset handling**: Treat background images in the HTML as dynamic data. Extract the URLs into `mockData.ts` rather than hardcoding them into the component styles.
+3. **Style extraction**: The HTML `<head>` contains a localized `tailwind.config`. This config must be merged with the local project theme to ensure colors like `primary` and `background-dark` render correctly.

package/templates/skills/react-components/resources/style-guide.json ADDED Viewed

@@ -0,0 +1,27 @@
+{
+  "theme": {
+    "colors": {
+      "primary": "#19e66f",
+      "background": {
+        "light": "#f6f8f7",
+        "dark": "#112118",
+        "elevated": "#1A1A1A"
+      },
+      "accent": {
+        "purple": "#8A2BE2",
+        "lavender": "#D0A9F5"
+      }
+    },
+    "typography": {
+      "display": [
+        "Space Grotesk",
+        "sans-serif"
+      ],
+      "icons": "Material Symbols Outlined"
+    },
+    "spacing": {
+      "header-h": "72px",
+      "container-max": "960px"
+    }
+  }
+}

package/templates/skills/react-components/scripts/fetch-stitch.sh ADDED Viewed

@@ -0,0 +1,30 @@
+#!/bin/bash
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+URL=$1
+OUTPUT=$2
+if [ -z "$URL" ] || [ -z "$OUTPUT" ]; then
+  echo "Usage: $0 <url> <output_path>"
+  exit 1
+fi
+echo "Initiating high-reliability fetch for Stitch HTML..."
+curl -L -f -sS --connect-timeout 10 --compressed "$URL" -o "$OUTPUT"
+if [ $? -eq 0 ]; then
+  echo "✅ Successfully retrieved HTML at: $OUTPUT"
+  exit 0
+else
+  echo "❌ Error: Failed to retrieve content. Check TLS/SNI or URL expiration."
+  exit 1
+fi

package/templates/skills/react-components/scripts/validate.js ADDED Viewed

@@ -0,0 +1,68 @@
+/**
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import swc from '@swc/core';
+import fs from 'node:fs';
+import path from 'node:path';
+async function validateComponent(filePath) {
+  const code = fs.readFileSync(filePath, 'utf-8');
+  const filename = path.basename(filePath);
+  try {
+    const ast = await swc.parse(code, { syntax: "typescript", tsx: true });
+    let hasInterface = false;
+    let tailwindIssues = [];
+    console.log("🔍 Scanning AST...");
+    const walk = (node) => {
+      if (!node) return;
+      if (node.type === 'TsInterfaceDeclaration' && node.id.value.endsWith('Props')) hasInterface = true;
+      if (node.type === 'JSXAttribute' && node.name.name === 'className') {
+        if (node.value?.value && /#[0-9A-Fa-f]{6}/.test(node.value.value)) tailwindIssues.push(node.value.value);
+      }
+      for (const key in node) { if (node[key] && typeof node[key] === 'object') walk(node[key]); }
+    };
+    walk(ast);
+    console.log(`--- Validation for: ${filename} ---`);
+    if (hasInterface) {
+      console.log("✅ Props declaration found.");
+    } else {
+      console.error("❌ MISSING: Props interface (must end in 'Props').");
+    }
+    if (tailwindIssues.length === 0) {
+      console.log("✅ No hardcoded hex values found.");
+    } else {
+      console.error(`❌ STYLE: Found ${tailwindIssues.length} hardcoded hex codes.`);
+      tailwindIssues.forEach(hex => console.error(`   - ${hex}`));
+    }
+    if (hasInterface && tailwindIssues.length === 0) {
+      console.log("\n✨ COMPONENT VALID.");
+      process.exit(0);
+    } else {
+      console.error("\n🚫 VALIDATION FAILED.");
+      process.exit(1);
+    }
+  } catch (err) {
+    console.error("❌ PARSE ERROR:", err.message);
+    process.exit(1);
+  }
+}
+validateComponent(process.argv[2]);

package/templates/skills/stitch-loop/README.md ADDED Viewed

@@ -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 add-skill 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/stitch-loop/SKILL.md ADDED Viewed

@@ -0,0 +1,235 @@
+---
+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"
+  - "qdrant-memory"
+---
+# 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 (`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 `DESIGN.md` file (generate one using the `design-md` skill if needed)
+- A `SITE.md` file documenting the site vision and roadmap
+**Optional:**
+- Chrome DevTools MCP Server — enables visual verification of generated pages
+- Qdrant Memory Skill — enables semantic context retrieval and long-term memory
+## The Baton System
+The `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 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 `DESIGN.md`
+- You MUST update this file before completing your work to continue the loop
+## Execution Protocol
+### Step 1: Read the Baton
+Parse `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                                                               |
+| ----------- | --------------------------------------------------------------------- |
+| `SITE.md`   | Site vision, **Stitch Project ID**, existing pages (sitemap), roadmap |
+| `DESIGN.md` | Required visual style for Stitch prompts                              |
+### Step 2.5: Consult Memory (Optional)
+If the **Qdrant Memory Skill** is available, retrieve relevant context to ensure consistency:
+1. **Retrieve Context**: Call `qdrant_search_memory` (or `retrieve_context` script) with technical queries related to the current task.
+   - Example query: "navigation structure", "footer design", "auth flow pattern"
+   - Filter by project if applicable.
+2. **Check Decisions**: Look for past architectural decisions (`type: "decision"`) that might impact this page.
+**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.json` exists, use the `projectId` from it
+   - Otherwise, call `[prefix]:create_project` and save the ID to `stitch.json`
+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**: Call `[prefix]:get_screen` to get:
+   - `htmlCode.downloadUrl` — Download and save as `queue/{page}.html`
+   - `screenshot.downloadUrl` — Download and save as `queue/{page}.png`
+### Step 4: Integrate into Site
+1. Move generated HTML from `queue/{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 (`queue/{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 `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 5.5: Store Memory (Optional)
+If **Qdrant Memory Skill** is available:
+1. **Store Completion**: Use `qdrant_store_memory` to record the completion of the page.
+   - Content: "Completed page: {page}. Implemented features: [list features]."
+   - Metadata: `type: "milestone"`, `page: "{page}"`
+2. **Store Decisions**: If you made any structural or design decisions (e.g., "Standardized footer links"), store them:
+   - Metadata: `type: "decision"`, `topic: "navigation"`
+### Step 6: Prepare the Next Baton (Critical)
+**You MUST update `next-prompt.md` before completing.** This keeps the loop alive.
+1. **Decide the next page**:
+   - Check `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 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/
+├── next-prompt.md      # The baton — current task
+├── stitch.json         # Stitch project ID (persist this!)
+├── DESIGN.md           # Visual design system (from design-md skill)
+├── SITE.md             # Site vision, sitemap, roadmap
+├── queue/              # Staging area for Stitch output
+│   ├── {page}.html
+│   └── {page}.png
+└── site/public/        # Production pages
+    ├── index.html
+    └── {page}.html
+```
+## Orchestration Options
+The loop can be driven by different orchestration layers:
+| Method            | How it works                                           |
+| ----------------- | ------------------------------------------------------ |
+| **CI/CD**         | GitHub Actions triggers on `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 `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 `next-prompt.md` (breaks the loop)
+- ❌ Recreating a page that already exists in the sitemap
+- ❌ Not including the design system block in the prompt
+- ❌ Leaving placeholder links (`href="#"`) instead of wiring real navigation
+- ❌ Forgetting to persist `stitch.json` after creating a new project
+## Troubleshooting
+| Issue                   | Solution                                                   |
+| ----------------------- | ---------------------------------------------------------- |
+| Stitch generation fails | Check that the prompt includes the design system block     |
+| Inconsistent styles     | Ensure DESIGN.md is up-to-date and copied correctly        |
+| Loop stalls             | Verify `next-prompt.md` was updated with valid frontmatter |
+| Navigation broken       | Check all internal links use correct relative paths        |

package/templates/skills/stitch-loop/examples/SITE.md ADDED Viewed

@@ -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/stitch-loop/examples/next-prompt.md ADDED Viewed

@@ -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/stitch-loop/resources/baton-schema.md ADDED Viewed

@@ -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