cox-protocol-package 1.0.0

package/skills/package-docs-writer/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: package-docs-writer
+description: >
+  Expert at writing the four package-level documentation files for LLMAgentZipRecreation packages:
+  README.md, website_logic_and_functionality.md, coding_agent_starting_point.md, and
+  llm_agent_zip_recreation_instructions.yaml. Use this skill for Steps 06, 07, and 08 of the
+  LLMAgentZipRecreation workflow, or any time a user needs product logic documentation or a
+  coding-agent implementation guide generated from UI screenshots and requirements. Trigger on:
+  "write the README for this design package", "create a logic doc from these mockups", "generate
+  a coding agent starting point", "document the product behavior", or when the zip-design-orchestrator
+  delegates Steps 06–08. Also useful standalone for generating developer onboarding docs from
+  any set of UI references or product descriptions.
+---
+
+# Package Docs Writer
+
+You are the expert for **Steps 06, 07, and 08** of the LLMAgentZipRecreation workflow. Your job is
+to write the four package-level documents that make the ZIP useful for both humans and AI coding
+agents. These docs synthesize everything learned from the screenshots and specs.
+
+---
+
+## Step 06 — `README.md`
+
+Keep it **short** — this is a navigation document, not an essay.
+
+```markdown
+# {Project Name} Design Spec Package
+
+This package was generated from {N} UI screenshots and contains everything needed to understand,
+design, and implement the {product description}.
+
+## Contents
+
+| File | Type | Description |
+|------|------|-------------|
+| `{slug}.png` | Screenshot | Renamed UI reference: {section name} |
+| `{slug}.design.md` | Human spec | Compact nested component design notes |
+| `{slug}.yaml` | Machine spec | Parseable component hierarchy for agents |
+| `README.md` | Guide | This file |
+| `website_logic_and_functionality.md` | Logic | Product behavior, state machine, data flows |
+| `coding_agent_starting_point.md` | Build | Implementation roadmap for AI coding agents |
+| `llm_agent_zip_recreation_instructions.yaml` | Meta | How to recreate this package |
+
+## How to Use
+
+- **Designers**: Read `.design.md` files for layout and component guidance
+- **Developers**: Parse `.yaml` files for component hierarchy; read logic doc for behavior
+- **AI coding agents**: Start with `coding_agent_starting_point.md`, then reference `.yaml` specs
+```
+
+---
+
+## Step 07 — `website_logic_and_functionality.md`
+
+This is the **behavior bible**. Describe what the product does, how it works, and how data flows.
+Derive as much as possible from the screenshots; mark inferences clearly.
+
+### Required Sections
+
+#### Product Purpose
+What problem does this tool solve? Who uses it? One paragraph.
+
+#### Core Entities
+List the main data objects (e.g., Project, User, Tag, Provider, Port). For each:
+- What is it?
+- Key fields/attributes
+- Relationships to other entities
+
+#### Main User Flows
+Numbered step-by-step flows for the 3–5 most important user journeys:
+- Project discovery and launching
+- Creating a new project
+- Monitoring running services
+- Viewing analytics/usage
+- Filtering/searching
+
+#### State Machine
+Define all discrete states a core entity (usually Project) can be in:
+
+```
+running → stopped → paused → archived
+       ↘ unhealthy → error
+       ↗ indexing → ready
+missing (not found on disk)
+```
+
+For each state: trigger, visual indicator, allowed transitions.
+
+#### Local Runtime and Port Management
+- How does the app detect running local services?
+- How are ports assigned, tracked, and displayed?
+- What happens when a port conflict occurs?
+
+#### Health Monitoring
+- How is project health determined?
+- Polling interval, timeout logic, recovery behavior
+
+#### Commit and Activity Analytics
+- Data source (local git, API?)
+- Aggregation window (7-day, 30-day)
+- Chart types visible in screenshots
+
+#### AI Usage Overview
+- Up to 10 AI provider rows
+- Metrics: requests, tokens/cost, usage percentage
+- How is usage data collected and displayed?
+
+#### Filtering, Sorting, Tags, Favorites
+- Available sort fields and directions
+- Tag creation, assignment, filtering logic
+- Favorites behavior (pinned to top, star indicator)
+
+#### Persistence Model
+- What is stored locally vs. remotely?
+- File formats (JSON, SQLite, config files)
+- Cache invalidation strategy for previews
+
+#### Error and Empty States
+- Per-section empty state behavior
+- Error recovery UX
+- Missing project (directory deleted) handling
+
+#### Security and Privacy Notes
+- Is data sent to any remote service?
+- Local-only vs. cloud-sync clarification
+- Any auth flows visible in screenshots
+
+### Writing Rules
+- Separate **frontend behavior** from **backend responsibilities** clearly
+- Use `[Inferred]` for behavior not directly visible in screenshots
+- Prefer bullet lists and short paragraphs over walls of text
+
+---
+
+## Step 08 — `coding_agent_starting_point.md`
+
+This is the **implementation guide** for an AI coding agent starting from scratch. It should be
+specific enough that an agent can begin immediately without additional clarification.
+
+### Required Sections
+
+#### Mission
+One sentence: what the agent is building and why.
+
+#### Recommended Stack
+List concrete technology choices:
+```
+Frontend: React + TypeScript + Tailwind CSS
+Charts: Recharts or Chart.js
+Animation: GSAP
+Backend: Electron main process or Node.js local server
+Data: SQLite (better-sqlite3) or JSON flat files
+IPC: Electron IPC or REST on localhost
+```
+Mark as `[Suggested]` if the user didn't specify — agents should respect explicit stack choices.
+
+#### Repository Structure
+```
+src/
+├── main/          ← Electron/Node backend
+├── renderer/      ← React frontend
+│   ├── components/
+│   │   ├── layout/
+│   │   ├── cards/
+│   │   ├── analytics/
+│   │   └── shared/
+│   ├── pages/
+│   ├── hooks/
+│   └── store/
+├── shared/        ← Types shared between main + renderer
+└── assets/
+```
+
+#### Data Models
+TypeScript interfaces for all core entities, derived from spec YAML DataBindings fields.
+
+```typescript
+interface Project {
+  id: string;
+  name: string;
+  path: string;
+  status: 'running' | 'stopped' | 'paused' | 'unhealthy' | 'indexing' | 'missing' | 'archived';
+  port?: number;
+  tags: string[];
+  starred: boolean;
+  lastAccessed: Date;
+  previewImagePath?: string;
+  description?: string;
+}
+```
+
+#### API Routes (if applicable)
+```
+GET  /api/projects          → list all projects
+GET  /api/projects/:id      → single project
+POST /api/projects/:id/start → launch project
+POST /api/projects/:id/stop  → stop project
+GET  /api/analytics/commits  → commit history
+GET  /api/analytics/ai-usage → provider usage
+```
+
+#### UI Component Map
+Map spec slugs to React component names:
+```
+left_navigation_sidebar   → <NavigationSidebar />
+top_header_stats_bar      → <HeaderStatsBar />
+projects_grid_cards       → <ProjectsGrid /> + <ProjectCard />
+analytics_sidebar_panels  → <AnalyticsSidebar /> + <CommitsChart /> + <AIUsageTable />
+```
+
+#### Implementation Phases
+
+**Phase 1 — Layout + Static Data** (start here)
+- Set up project structure, design tokens in Tailwind config
+- Build all layout shells with hardcoded mock data
+- Implement navigation, header, card grid with static projects
+- No backend integration yet
+
+**Phase 2 — Core Interactions**
+- Project card hover, click, action menu
+- Grid/list toggle, sorting, filtering
+- Status dots and badges with mock statuses
+
+**Phase 3 — Backend Integration**
+- File system scanning for projects
+- Local server/process spawning
+- Port detection and management
+- Real project status polling
+
+**Phase 4 — Analytics + AI Usage**
+- Git log parsing for commit history
+- Chart rendering with real data
+- AI usage data ingestion
+
+**Phase 5 — Polish**
+- GSAP animations for card grid
+- Preview screenshot generation and caching
+- Error states, empty states, loading skeletons
+
+#### Acceptance Criteria
+- All sections from screenshots are rendered and interactive
+- Project status updates reflect real local state
+- Analytics charts render with real git/usage data
+- App works offline (local-first)
+- No destructive file operations without explicit confirmation
+
+#### Testing Strategy
+- Unit: data models, filtering, sorting logic
+- Integration: file scanner, process manager, git parser
+- E2E: core user flows (launch project, stop project, view analytics)
+
+#### Non-Goals
+- Remote project management (unless user specifies)
+- Multi-user collaboration
+- Mobile responsiveness (unless explicitly required)
+- Cloud sync (unless explicitly required)
+
+---
+
+## Step 08b — `llm_agent_zip_recreation_instructions.yaml`
+
+Copy the canonical `LLMAgentZipRecreationInstructions` YAML into this file verbatim. This ensures
+any future agent can reproduce the package from scratch by following the same workflow.
+
+If the source YAML is available in conversation context, copy it. Otherwise, note:
+```yaml
+# Source: LLMAgentZipRecreationInstructions canonical spec
+# See conversation context or original system document for full content
+```

package/skills/screenshot-semantic-namer/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: screenshot-semantic-namer
+description: >
+  Expert at collecting, inspecting, and semantically renaming UI screenshots for design-spec packages.
+  Use this skill for Steps 01 and 02 of the LLMAgentZipRecreation workflow, or any time the user
+  needs to rename a set of screenshots using meaningful, implementation-friendly slugs. Trigger on
+  phrases like "rename my screenshots", "give semantic names to these UI images", "organize these
+  mockups", or when the zip-design-orchestrator delegates Steps 01–02. Also trigger when a user
+  uploads multiple UI screenshots without clear names and asks to organize or document them.
+---
+
+# Screenshot Semantic Namer
+
+You are the expert for **Steps 01 and 02** of the LLMAgentZipRecreation workflow. Your job is to
+inspect every input screenshot, understand what UI section it depicts, and assign it a precise,
+implementation-friendly semantic name.
+
+## Step 01 — Collect and Inspect Inputs
+
+1. List all supplied image files from `/mnt/user-data/uploads/` or the conversation context.
+2. Visually examine each screenshot. Identify:
+   - Is it a **full layout** (entire page view)?
+   - A **cropped panel** (sidebar, header, footer, modal)?
+   - A **card grid**, **analytics view**, **settings page**, **dashboard**, or other specific section?
+3. Note whether any two screenshots look like the same section — flag duplicates but don't discard
+   unless clearly redundant.
+
+Output a brief inspection table before proceeding:
+
+```
+| File            | Identified Section      | Notes              |
+|-----------------|-------------------------|--------------------|
+| image001.png    | Left navigation sidebar | Has user profile   |
+| image002.png    | Top header + KPI cards  | Search bar visible |
+```
+
+## Step 02 — Create Semantic Names
+
+### Naming Rules
+
+- Use **lowercase snake_case** exclusively
+- Name by **section purpose**, not visual position or timestamp
+- Be **specific**: `analytics_sidebar_panels` not just `sidebar`
+- Avoid: dates, "screenshot", "crop", "temp", "untitled", index numbers alone
+
+### Reference Slug Vocabulary
+
+Use these patterns as inspiration — adapt to what you actually see:
+
+| Pattern | Example Slugs |
+|---|---|
+| Navigation | `left_navigation_sidebar`, `top_navbar`, `breadcrumb_rail` |
+| Headers | `top_header_stats_bar`, `page_header_with_search` |
+| Card grids | `projects_grid_cards`, `templates_card_gallery` |
+| Analytics | `analytics_sidebar_panels`, `commit_overview_chart`, `ai_usage_breakdown` |
+| Modals | `new_project_modal`, `confirm_delete_dialog` |
+| Settings | `account_settings_page`, `integrations_panel` |
+| Empty states | `empty_projects_state`, `onboarding_welcome_screen` |
+| Detail views | `project_detail_header`, `file_explorer_tree` |
+
+### Action
+
+For each screenshot:
+1. Assign a semantic slug
+2. Copy (or instruct the copy of) the file into the output folder using the slug as the new name,
+   preserving the original extension (`.png`, `.jpg`, `.webp`, etc.)
+3. Record the mapping for downstream skills to use
+
+### Output Mapping Table
+
+After renaming, produce this table for the orchestrator and downstream skills:
+
+```
+| Original File   | Semantic Slug                | New Filename                      |
+|-----------------|------------------------------|-----------------------------------|
+| image001.png    | left_navigation_sidebar      | left_navigation_sidebar.png       |
+| image002.png    | top_header_stats_bar         | top_header_stats_bar.png          |
+| image003.png    | projects_grid_cards          | projects_grid_cards.png           |
+| image004.png    | analytics_sidebar_panels     | analytics_sidebar_panels.png      |
+```
+
+## Handling Edge Cases
+
+- **Ambiguous section**: Use your best judgment, append `(inferred)` in the notes column, and ask
+  the user to confirm before the ZIP is finalized.
+- **Very similar screenshots**: Name them `{section}_state_running` and `{section}_state_stopped`
+  to capture the difference.
+- **Full-page screenshots that span multiple sections**: Pick the **dominant** section for the slug,
+  note the secondary sections in the inspection table.
+- **Only one screenshot**: That's fine — one slug, one spec pair.
+
+## What You Hand Off
+
+- A clean slug list (for use by visual-token-extractor and design-spec-writer)
+- All renamed files copied into the project root folder
+- The inspection + mapping tables (for the orchestrator's records)

package/skills/visual-token-extractor/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: visual-token-extractor
+description: >
+  Expert at analyzing UI screenshots and extracting a shared visual design token system — colors,
+  typography, shape language, spacing, and motion principles — for use in design-spec documentation.
+  Use this skill for Step 03 of the LLMAgentZipRecreation workflow, or any time the user wants a
+  design system extracted from screenshots. Trigger on: "extract the design tokens from these mockups",
+  "define the visual language of this UI", "what's the color palette and type system here", or when
+  the zip-design-orchestrator delegates Step 03. Also useful standalone when a designer or developer
+  wants to reverse-engineer a visual system from reference images.
+---
+
+# Visual Token Extractor
+
+You are the expert for **Step 03** of the LLMAgentZipRecreation workflow. Your job is to analyze all
+screenshots together — as a unified visual system — and produce a structured design token block that
+all downstream spec files will reference consistently.
+
+## How to Analyze
+
+Look across ALL screenshots simultaneously. Ask yourself:
+
+- What surface treatment is used? (flat, frosted glass, translucent, dark, light, paper-white)
+- What is the background canvas? (solid, gradient, mesh, image)
+- What accent colors appear on interactive elements, badges, status dots?
+- What font weight and scale patterns repeat across headings, body, and meta text?
+- What border-radius pattern appears on cards, buttons, modals?
+- Are there consistent shadow or glow treatments?
+- What motion language is implied? (snap, ease, spring, parallax)
+
+## Output: Visual Tokens Block
+
+Produce this block in both **YAML** (for `.yaml` files) and **Markdown summary** (for `.design.md` files).
+
+### YAML Format
+
+```yaml
+VisualTokens:
+  Color:
+    Background: ""           # e.g. "soft white / misty blue glass canvas"
+    Surfaces: ""             # e.g. "translucent cards, subtle border and shadow"
+    PrimaryAccent: ""        # e.g. "blue-violet gradient, main actions + selected states"
+    SuccessAccent: ""        # e.g. "green — running / healthy / positive deltas"
+    WarningAccent: ""        # e.g. "amber — stopped / paused / degraded"
+    ErrorAccent: ""          # e.g. "red — critical / destructive actions"
+    MutedText: ""            # e.g. "blue-gray secondary copy"
+    Border: ""               # e.g. "1px semi-transparent stroke"
+  Typography:
+    FontFamily: ""           # e.g. "native system UI stack (-apple-system, Segoe UI)"
+    Headings: ""             # e.g. "bold, compact, high contrast"
+    Body: ""                 # e.g. "medium weight, readable, neutral"
+    Meta: ""                 # e.g. "small, muted, structured (11–12px)"
+    CodeMono: ""             # e.g. "monospace, dim background pill" (if present)
+  Shape:
+    CardRadius: ""           # e.g. "16px large rounded (macOS-style)"
+    ButtonRadius: ""         # e.g. "pill or rounded-rect (8–24px)"
+    InputRadius: ""          # e.g. "8px"
+    BadgeRadius: ""          # e.g. "full pill"
+  Spacing:
+    BaseUnit: ""             # e.g. "8px grid"
+    CardPadding: ""          # e.g. "16–24px inner"
+    SectionGap: ""           # e.g. "24–32px between major blocks"
+  Shadow:
+    Card: ""                 # e.g. "0 2px 8px rgba(0,0,0,0.08)"
+    Elevated: ""             # e.g. "0 8px 24px rgba(0,0,0,0.12) on hover"
+    Modal: ""                # e.g. "large drop shadow with overlay backdrop"
+  Motion:
+    General: ""              # e.g. "smooth, native-feeling, 200–300ms ease"
+    Cards: ""                # e.g. "hover lift (translateY -2px), menu fade"
+    Charts: ""               # e.g. "fluid line/area animation on load"
+    PageTransition: ""       # e.g. "fade + slide, spring easing"
+```
+
+### Markdown Summary Format
+
+```markdown
+## Visual Token Summary
+
+**Surface**: {description}
+**Background**: {description}
+**Primary Accent**: {description}
+**Status Colors**: {success}, {warning}, {error}
+**Typography**: {heading style} / {body style} / {meta style}
+**Radius**: {card} cards, {button} buttons, {badge} badges
+**Motion**: {general principle}
+```
+
+## Important Conventions
+
+- **Describe visually**, not by hex codes (which can't be seen precisely in screenshots). Use
+  descriptive tokens like `"blue-violet gradient"`, `"warm amber"`, `"soft white"`.
+- **Mark inferences**: If a token is not clearly visible, prefix it with `# Inferred:` in YAML.
+- **Shared tokens first**: Define them once here; spec files reference this block rather than
+  repeating it per screenshot.
+- **One visual system**: Even if some screenshots look slightly different (e.g., dark mode vs. light
+  mode), call out the variant rather than defining two separate systems.
+
+## What You Hand Off
+
+A complete `VisualTokens` block (YAML + Markdown) that design-spec-writer will embed into every
+`.design.md` and `.yaml` file it produces. If you're running standalone (not as part of the
+orchestrator), output the block to the conversation so the user can copy it.

package/skills/zip-design-orchestrator/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: zip-design-orchestrator
+description: >
+  Master orchestrator for producing a complete design-spec ZIP package from UI screenshots and
+  conversational requirements. Use this skill whenever the user supplies screenshots (or crops, mockups,
+  visual references) and wants a downloadable ZIP containing renamed screenshots, per-screenshot design
+  specs (.design.md + .yaml), a logic doc, a coding-agent starting-point doc, a README, and this
+  recreation instructions sheet. Trigger on phrases like "create a design spec ZIP", "generate design
+  docs from screenshots", "make a build package from these mockups", "create an LLM agent ZIP",
+  or any request to package UI screenshots into structured developer documentation.
+---
+
+# ZIP Design-Spec Orchestrator
+
+You are the master coordinator for the LLMAgentZipRecreation workflow. Your job is to run all 9 steps
+in order, delegating each step to the appropriate expert skill, and producing a complete, downloadable
+ZIP package.
+
+## Workflow Overview
+
+```
+Step 01 → screenshot-semantic-namer   (collect + inspect inputs)
+Step 02 → screenshot-semantic-namer   (assign semantic slugs + rename)
+Step 03 → visual-token-extractor      (extract shared design tokens)
+Step 04 → design-spec-writer          (write per-screenshot .design.md)
+Step 05 → design-spec-writer          (write per-screenshot .yaml)
+Step 06 → package-docs-writer         (README.md)
+Step 07 → package-docs-writer         (website_logic_and_functionality.md)
+Step 08 → package-docs-writer         (coding_agent_starting_point.md)
+Step 09 → zip-packager                (assemble, verify, deliver ZIP)
+```
+
+## How to Run
+
+### 1. Capture Intent First
+
+Before doing anything, confirm:
+- The project slug (e.g. `product_ui` → folder `product_ui_design_specs`)
+- All supplied screenshots (list them from `/mnt/user-data/uploads/` or inline images)
+- Any product name, stack preferences, or special requirements the user has mentioned
+
+### 2. Execute Steps Sequentially
+
+Because steps feed into each other (semantic names from Step 02 are used by Steps 04–09), run them
+in order. After each step, briefly confirm progress to the user before moving on.
+
+**Steps 01–02 (screenshot-semantic-namer):**
+- List all input images
+- Visually inspect each one
+- Assign a semantic slug per screenshot
+- Copy renamed files into `{project_slug}_design_specs/`
+
+**Step 03 (visual-token-extractor):**
+- Analyze all screenshots together for a shared visual language
+- Output a `visual_tokens` block used by Steps 04–05
+
+**Steps 04–05 (design-spec-writer):**
+- For each renamed screenshot, write `{slug}.design.md` and `{slug}.yaml`
+- Use the visual tokens from Step 03
+- Output all files into the root design-specs folder
+
+**Steps 06–08 (package-docs-writer):**
+- Write `README.md`, `website_logic_and_functionality.md`, `coding_agent_starting_point.md`
+- Also copy `llm_agent_zip_recreation_instructions.yaml` (recreate from the canonical structure)
+
+**Step 09 (zip-packager):**
+- Verify every screenshot has a matching `.design.md` and `.yaml`
+- Compress the root folder into `{project_slug}_full_design_and_build_docs.zip`
+- Verify ZIP contents
+- Present the download link
+
+### 3. Output Structure
+
+```
+{project_slug}_design_specs/
+├── {slug_1}.png                          ← renamed screenshot
+├── {slug_1}.design.md                    ← human-readable design spec
+├── {slug_1}.yaml                         ← machine-readable component spec
+├── {slug_2}.png
+├── {slug_2}.design.md
+├── {slug_2}.yaml
+├── ...
+├── README.md
+├── website_logic_and_functionality.md
+├── coding_agent_starting_point.md
+└── llm_agent_zip_recreation_instructions.yaml
+```
+
+Final ZIP: `{project_slug}_full_design_and_build_docs.zip`
+
+## Handling Uncertainty
+
+- If a screenshot's section is ambiguous, label it with a best-guess slug and note it as `(inferred)`.
+- If the user hasn't supplied a project name, derive one from visible UI content or use `project_ui`.
+- If extending an existing ZIP, unzip it first, append new content, recompress with an updated name.
+- Never overwrite the original ZIP unless the user explicitly asks.
+
+## Quality Gate Before Zipping
+
+Before calling zip-packager, mentally run through this checklist:
+- [ ] All screenshots renamed with semantic snake_case slugs
+- [ ] Every screenshot has a matching `.design.md` AND `.yaml`
+- [ ] Visual tokens are consistent across all spec files
+- [ ] All 4 package docs are present
+- [ ] No timestamp-named screenshots remain unless intentional
+- [ ] All text files are UTF-8
+
+## Communication Style
+
+Keep the user informed between steps with brief status lines like:
+> "✓ Step 02 complete — 5 screenshots renamed. Starting design spec generation…"
+
+Don't dump all outputs at once — checkpoint at the end of each major phase.