@techwavedev/agi-agent-kit 1.6.1 → 1.6.4

package/templates/skills/knowledge/frontend/stitch-loop/SKILL.md

@@ -7,7 +7,6 @@ allowed-tools:
   - "Read"
   - "Write"
   - "Bash"
-  - "qdrant-memory"
 ---
 
 # Stitch Build Loop
@@ -17,8 +16,7 @@ You are an **autonomous frontend builder** participating in an iterative site-bu
 ## 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`)
+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
@@ -26,73 +24,56 @@ The Build Loop pattern enables continuous, autonomous website development throug
 ## 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
+- 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
-- 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:
+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 DESIGN.md Section 6]
+[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 `DESIGN.md`
+- 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 `next-prompt.md` to extract:
-
+Parse `.stitch/next-prompt.md` to extract:
 - **Page name** from the `page` frontmatter field
 - **Prompt content** from the markdown body
 
-### Step 2: Check Context Files
+### 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: Check 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.
+| 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
@@ -102,20 +83,23 @@ If the **Qdrant Memory Skill** is available, retrieve relevant context to ensure
 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`
+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**: Call `[prefix]:get_screen` to get:
-   - `htmlCode.downloadUrl` — Download and save as `queue/{page}.html`
-   - `screenshot.downloadUrl` — Download and save as `queue/{page}.png`
+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 `queue/{page}.html` to `site/public/{page}.html`
+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
@@ -130,35 +114,24 @@ If the **Chrome DevTools MCP Server** is available, verify the generated page:
 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
+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 `SITE.md`:
-
+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 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.
+**You MUST update `.stitch/next-prompt.md` before completing.** This keeps the loop alive.
 
-1. **Decide the next page**:
-   - Check `SITE.md` Section 5 (Roadmap) for pending items
+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:
@@ -167,14 +140,12 @@ If **Qdrant Memory Skill** is available:
 ---
 page: achievements
 ---
-
 A competitive achievements page showing developer badges and milestones.
 
 **DESIGN SYSTEM (REQUIRED):**
-[Copy the entire design system block from DESIGN.md]
+[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
@@ -184,28 +155,85 @@ A competitive achievements page showing developer badges and milestones.
 
 ```
 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
+├── .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 `next-prompt.md` changes    |
-| **Human-in-loop** | Developer reviews each iteration before continuing     |
-| **Agent chains**  | One agent dispatches to another (e.g., CI/CD pipeline) |
-| **Manual**        | Developer runs the agent repeatedly with the same repo |
+| 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.
 
@@ -213,58 +241,23 @@ The skill is orchestration-agnostic — focus on the pattern, not the trigger me
 
 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
+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 `next-prompt.md` (breaks the loop)
+- ❌ 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 in the prompt
+- ❌ 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.json` after creating a new project
+- ❌ 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 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        |
-
-## AGI Framework Integration
-
-### Qdrant Memory Integration
-
-Before executing complex tasks with this skill:
-```bash
-python3 execution/memory_manager.py auto --query "<task summary>"
-```
-
-**Decision Tree:**
-- **Cache hit?** Use cached response directly — no need to re-process.
-- **Memory match?** Inject `context_chunks` into your reasoning.
-- **No match?** Proceed normally, then store results:
-
-```bash
-python3 execution/memory_manager.py store \
-  --content "Description of what was decided/solved" \
-  --type decision \
-  --tags stitch-loop <relevant-tags>
-```
-
-> **Note:** Storing automatically updates both Vector (Qdrant) and Keyword (BM25) indices.
-
-### Agent Team Collaboration
-
-- **Strategy**: This skill communicates via the shared memory system.
-- **Orchestration**: Invoked by `orchestrator` via intelligent routing.
-- **Context Sharing**: Always read previous agent outputs from memory before starting.
-
-### Local LLM Support
-
-When available, use local Ollama models for embedding and lightweight inference:
-- Embeddings: `nomic-embed-text` via Qdrant memory system
-- Lightweight analysis: Local models reduce API costs for repetitive patterns
+| 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 |