@builderos/create-agent-os 0.0.2

package/src/template/design/.claude/commands/design-os/product-roadmap.md

@@ -0,0 +1,121 @@
+# Product Roadmap
+
+You are helping the user create or update their product roadmap for Design OS. This command serves two purposes:
+
+1. **Create** an initial roadmap if one doesn't exist
+2. **Sync** changes if the user has manually edited the markdown files
+
+## Step 1: Check Current State
+
+First, check if `/product/product-roadmap.md` exists and read `/product/product-overview.md` if it exists.
+
+---
+
+## If No Roadmap Exists (Creating New)
+
+### Analyze the Product Overview
+
+Read the product overview and analyze:
+- The core description
+- The problems being solved
+- The key features listed
+
+### Propose Sections
+
+Based on your analysis, propose 3-5 sections that represent:
+- **Navigation items** - main areas of the product UI
+- **Roadmap phases** - logical order for building
+- **Self-contained feature areas** - each can be designed and built independently
+
+Present your proposal:
+
+"Based on your product overview, I'd suggest breaking this into these sections:
+
+1. **[Section Title]** - [One sentence description]
+2. **[Section Title]** - [One sentence description]
+3. **[Section Title]** - [One sentence description]
+
+These are ordered by importance and logical development sequence. The first section would be the core functionality, with each subsequent section building on it."
+
+Then use the AskUserQuestion tool to ask the user: "Does this breakdown make sense? Would you like to adjust any sections or their order?"
+
+### Refine with User
+
+Iterate on the sections based on user feedback. Ask clarifying questions:
+- "Should [feature X] be its own section or part of [Section Y]?"
+- "What would you consider the most critical section to build first?"
+- "Are there any major areas I'm missing?"
+
+### Create the File
+
+Once approved, create `/product/product-roadmap.md` with this exact format:
+
+```markdown
+# Product Roadmap
+
+## Sections
+
+### 1. [Section Title]
+[One sentence description]
+
+### 2. [Section Title]
+[One sentence description]
+
+### 3. [Section Title]
+[One sentence description]
+```
+
+### Confirm
+
+"I've created your product roadmap at `/product/product-roadmap.md`. The homepage now shows your [N] sections:
+
+1. **[Section 1]** — [Description]
+2. **[Section 2]** — [Description]
+3. **[Section 3]** — [Description]
+
+**Next step:** Run `/data-model` to define the core entities and relationships in your product. This establishes a shared vocabulary that keeps your sections consistent."
+
+---
+
+## If Roadmap Already Exists (Syncing)
+
+### Read Current Files
+
+Read both:
+- `/product/product-overview.md`
+- `/product/product-roadmap.md`
+
+### Report Current State
+
+"I see you already have a product roadmap defined with [N] sections:
+
+1. [Section 1 Title]
+2. [Section 2 Title]
+...
+
+What would you like to do?
+- **Update sections** - Add, remove, or reorder sections
+- **Sync from files** - I'll re-read the markdown files and confirm everything is in sync
+- **Start fresh** - Regenerate the roadmap based on the current product overview"
+
+### Handle User Choice
+
+**If updating sections:**
+Ask what changes they want to make, then update the file accordingly.
+
+**If syncing:**
+Confirm the current state matches what's in the files. If the user has manually edited the `.md` files, let them know the app will pick up those changes on next build/refresh.
+
+**If starting fresh:**
+Follow the "Creating New" flow above, but note you're replacing the existing roadmap.
+
+---
+
+## Important Notes
+
+- Sections should be ordered by development priority
+- Each section should be self-contained enough to design and build independently
+- Section titles become navigation items in the app
+- The numbered format (`### 1. Title`) is required for parsing
+- Keep descriptions to one sentence - concise and clear
+- Don't create too many sections (3-5 is ideal)

package/src/template/design/.claude/commands/design-os/product-vision.md

@@ -0,0 +1,99 @@
+# Product Vision
+
+You are helping the user define their product vision for Design OS. This is a conversational, multi-step process.
+
+## Step 1: Gather Initial Input
+
+First, ask the user to share their raw notes, ideas, or thoughts about the product they want to build. Be warm and open-ended:
+
+"I'd love to help you define your product vision. Tell me about the product you're building - share any notes, ideas, or rough thoughts you have. What problem are you trying to solve? Who is it for? Don't worry about structure yet, just share what's on your mind."
+
+Wait for their response before proceeding.
+
+## Step 2: Ask Clarifying Questions
+
+After receiving their input, use the AskUserQuestion tool to ask 3-5 targeted questions to help shape:
+
+- **The product name** - A clear, concise name for the product
+- **The core product description** (1-3 sentences that capture the essence)
+- **The key problems** the product solves (1-5 specific pain points)
+- **How the product solves each problem** (concrete solutions)
+- **The main features** that make this possible
+
+**Important:** If the user hasn't already provided a product name, ask them:
+- "What would you like to call this product? (A short, memorable name)"
+
+Other example clarifying questions (adapt based on their input):
+- "Who is the primary user of this product? Can you describe them?"
+- "What's the single biggest pain point you're addressing?"
+- "How do people currently solve this problem without your product?"
+- "What makes your approach different or better?"
+- "What are the 3-5 most essential features?"
+
+Ask questions one or two at a time, and engage conversationally.
+
+## Step 3: Present Draft and Refine
+
+Once you have enough information, present a draft summary:
+
+"Based on our discussion, here's what I'm capturing for **[Product Name]**:
+
+**Description:**
+[Draft 1-3 sentence description]
+
+**Problems & Solutions:**
+1. [Problem] → [Solution]
+2. [Problem] → [Solution]
+
+**Key Features:**
+- Feature 1
+- Feature 2
+- Feature 3
+
+Does this capture your vision? Would you like to adjust anything?"
+
+Iterate until the user is satisfied.
+
+## Step 4: Create the File
+
+Once the user approves, create the file at `/product/product-overview.md` with this exact format:
+
+```markdown
+# [Product Name]
+
+## Description
+[The finalized 1-3 sentence description]
+
+## Problems & Solutions
+
+### Problem 1: [Problem Title]
+[How the product solves it in 1-2 sentences]
+
+### Problem 2: [Problem Title]
+[How the product solves it in 1-2 sentences]
+
+[Add more as needed, up to 5]
+
+## Key Features
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+[Add more as needed]
+```
+
+**Important:** The `# [Product Name]` heading at the top is required - this is what displays as the card title in the app.
+
+## Step 5: Confirm Completion
+
+Let the user know:
+
+"I've created your product overview at `/product/product-overview.md`. The homepage will now display **[Product Name]** with your product vision. You can run `/product-roadmap` next to break this down into development sections."
+
+## Important Notes
+
+- Be conversational and helpful, not robotic
+- Ask follow-up questions when answers are vague
+- Help the user think through their product, don't just transcribe
+- Keep the final output concise and clear
+- The format must match exactly for the app to parse it correctly
+- **Always ensure the product has a name** - if user didn't provide one, ask for it

package/src/template/design/.claude/commands/design-os/sample-data.md

@@ -0,0 +1,263 @@
+# Sample Data
+
+You are helping the user create realistic sample data for a section of their product. This data will be used to populate screen designs. You will also generate TypeScript types based on the data structure.
+
+## Step 1: Check Prerequisites
+
+First, identify the target section and verify that `spec.md` exists for it.
+
+Read `/product/product-roadmap.md` to get the list of available sections.
+
+If there's only one section, auto-select it. If there are multiple sections, use the AskUserQuestion tool to ask which section the user wants to generate data for.
+
+Then check if `product/sections/[section-id]/spec.md` exists. If it doesn't:
+
+"I don't see a specification for **[Section Title]** yet. Please run `/shape-section` first to define the section's requirements, then come back to generate sample data."
+
+Stop here if the spec doesn't exist.
+
+## Step 2: Check for Global Data Model
+
+Check if `/product/data-model/data-model.md` exists.
+
+**If it exists:**
+- Read the file to understand the global entity definitions
+- Entity names in your sample data should match the global data model
+- Use the descriptions and relationships as a guide
+
+**If it doesn't exist:**
+Show a warning but continue:
+
+"Note: A global data model hasn't been defined yet. I'll create entity structures based on the section spec, but for consistency across sections, consider running `/data-model` first."
+
+## Step 3: Analyze the Specification
+
+Read and analyze `product/sections/[section-id]/spec.md` to understand:
+
+- What data entities are implied by the user flows?
+- What fields/properties would each entity need?
+- What sample values would be realistic and helpful for design?
+- What actions can be taken on each entity? (These become callback props)
+
+**If a global data model exists:** Cross-reference the spec with the data model. Use the same entity names and ensure consistency.
+
+## Step 4: Present Data Structure
+
+Present your proposed data structure to the user in human-friendly language. Non-technical users should understand how their data is being organized.
+
+**If using global data model:**
+
+"Based on the specification for **[Section Title]** and your global data model, here's how I'm organizing the data:
+
+**Entities (from your data model):**
+
+- **[Entity1]** — [Description from data model]
+- **[Entity2]** — [Description from data model]
+
+**Section-specific data:**
+
+[Any additional data specific to this section's UI needs]
+
+**What You Can Do:**
+
+- View, edit, and delete [entities]
+- [Other key actions from the spec]
+
+**Sample Data:**
+
+I'll create [X] realistic [Entity1] records with varied content to make your screen designs feel real.
+
+Does this structure make sense? Any adjustments?"
+
+**If no global data model:**
+
+"Based on the specification for **[Section Title]**, here's how I'm proposing to organize your data:
+
+**Data Models:**
+
+- **[Entity1]** — [One sentence explaining what this represents]
+- **[Entity2]** — [One sentence explanation]
+
+**How They Connect:**
+
+[Explain relationships in simple terms]
+
+**What You Can Do:**
+
+- View, edit, and delete [entities]
+- [Other key actions from the spec]
+
+**Sample Data:**
+
+I'll create [X] realistic [Entity1] records with varied content to make your screen designs feel real.
+
+Does this structure make sense for your product? Any adjustments?"
+
+Use the AskUserQuestion tool if there are ambiguities about what data is needed.
+
+## Step 5: Generate the Data File
+
+Once the user approves the structure, create `product/sections/[section-id]/data.json` with:
+
+- **A `_meta` section** - Human-readable descriptions of each data model and their relationships (displayed in the UI)
+- **Realistic sample data** - Use believable names, dates, descriptions, etc.
+- **Varied content** - Mix short and long text, different statuses, etc.
+- **Edge cases** - Include at least one empty array, one long description, etc.
+- **TypeScript-friendly structure** - Use consistent field names and types
+
+### Required `_meta` Structure
+
+Every data.json MUST include a `_meta` object at the top level with:
+
+1. **`models`** - An object where each key is a model name and value is a plain-language description
+2. **`relationships`** - An array of strings explaining how models connect to each other
+
+Example structure:
+
+```json
+{
+  "_meta": {
+    "models": {
+      "invoices": "Each invoice represents a bill you send to a client for work completed.",
+      "lineItems": "Line items are the individual services or products listed on each invoice."
+    },
+    "relationships": [
+      "Each Invoice contains one or more Line Items (the breakdown of charges)",
+      "Invoices track which Client they belong to via the clientName field"
+    ]
+  },
+  "invoices": [
+    {
+      "id": "inv-001",
+      "invoiceNumber": "INV-2024-001",
+      "clientName": "Acme Corp",
+      "clientEmail": "billing@acme.com",
+      "total": 1500.00,
+      "status": "sent",
+      "dueDate": "2024-02-15",
+      "lineItems": [
+        { "description": "Web Design", "quantity": 1, "rate": 1500.00 }
+      ]
+    }
+  ]
+}
+```
+
+The `_meta` descriptions should:
+- Use plain, non-technical language
+- Explain what each model represents in the context of the user's product
+- Describe relationships in terms of "contains", "belongs to", "links to", etc.
+- **Match the global data model descriptions if one exists**
+
+The data should directly support the user flows and UI requirements in the spec.
+
+## Step 6: Generate TypeScript Types
+
+After creating data.json, generate `product/sections/[section-id]/types.ts` based on the data structure.
+
+### Type Generation Rules
+
+1. **Infer types from the sample data values:**
+   - Strings → `string`
+   - Numbers → `number`
+   - Booleans → `boolean`
+   - Arrays → `TypeName[]`
+   - Objects → Create a named interface
+
+2. **Use union types for status/enum fields:**
+
+   - If a field like `status` has known values, use a union: `'draft' | 'sent' | 'paid' | 'overdue'`
+
+   - Base this on the spec and the variety in sample data
+
+3. **Create a Props interface for the main component:**
+   - Include the data as a prop (e.g., `invoices: Invoice[]`)
+   - Include optional callback props for each action (e.g., `onDelete?: (id: string) => void`)
+
+4. **Use consistent entity names:**
+   - If a global data model exists, use the same entity names
+   - This ensures consistency across sections
+
+Example types.ts:
+
+```typescript
+// =============================================================================
+// Data Types
+// =============================================================================
+
+export interface LineItem {
+  description: string
+  quantity: number
+  rate: number
+}
+
+export interface Invoice {
+  id: string
+  invoiceNumber: string
+  clientName: string
+  clientEmail: string
+  total: number
+  status: 'draft' | 'sent' | 'paid' | 'overdue'
+  dueDate: string
+  lineItems: LineItem[]
+}
+
+// =============================================================================
+// Component Props
+// =============================================================================
+
+export interface InvoiceListProps {
+  /** The list of invoices to display */
+  invoices: Invoice[]
+  /** Called when user wants to view an invoice's details */
+  onView?: (id: string) => void
+  /** Called when user wants to edit an invoice */
+  onEdit?: (id: string) => void
+  /** Called when user wants to delete an invoice */
+  onDelete?: (id: string) => void
+  /** Called when user wants to archive an invoice */
+  onArchive?: (id: string) => void
+  /** Called when user wants to create a new invoice */
+  onCreate?: () => void
+}
+```
+
+### Naming Conventions
+
+- Use PascalCase for interface names: `Invoice`, `LineItem`, `InvoiceListProps`
+
+- Use camelCase for property names: `clientName`, `dueDate`, `lineItems`
+
+- Props interface should be named `[SectionName]Props` (e.g., `InvoiceListProps`)
+
+- Add JSDoc comments for callback props to explain when they're called
+
+- **Match entity names from the global data model if one exists**
+
+## Step 7: Confirm and Next Steps
+
+Let the user know:
+
+"I've created two files for **[Section Title]**:
+
+1. `product/sections/[section-id]/data.json` - Sample data with [X] records
+
+2. `product/sections/[section-id]/types.ts` - TypeScript interfaces for type safety
+
+The types include:
+
+- `[Entity]` - The main data type
+- `[SectionName]Props` - Props interface for the component (includes callbacks for [list actions])
+
+When you're ready, run `/design-screen` to create the screen design for this section."
+
+## Important Notes
+
+- Generate realistic, believable sample data - not "Lorem ipsum" or "Test 123"
+- Include 5-10 sample records for main entities (enough to show a realistic list)
+- Include edge cases: empty arrays, long text, different statuses
+- Keep field names clear and TypeScript-friendly (camelCase)
+- The data structure should directly map to the spec's user flows
+- Always generate types.ts alongside data.json
+- Callback props should cover all actions mentioned in the spec
+- **Use entity names from the global data model for consistency across sections**

package/src/template/design/.claude/commands/design-os/screenshot-design.md

@@ -0,0 +1,112 @@
+# Screenshot Screen Design
+
+You are helping the user capture a screenshot of a screen design they've created. The screenshot will be saved to the product folder for documentation purposes.
+
+## Prerequisites: Check for Playwright MCP
+
+Before proceeding, verify that you have access to the Playwright MCP tool. Look for a tool named `browser_take_screenshot` or `mcp__playwright__browser_take_screenshot`.
+
+If the Playwright MCP tool is not available, output this EXACT message to the user (copy it verbatim, do not modify or "correct" it):
+
+---
+To capture screenshots, I need the Playwright MCP server installed. Please run:
+
+```
+claude mcp add playwright npx @playwright/mcp@latest
+```
+
+Then restart this Claude Code session and run `/screenshot-design` again.
+---
+
+Do not substitute different package names or modify the command. Output it exactly as written above.
+
+Do not proceed with the rest of this command if Playwright MCP is not available.
+
+## Step 1: Identify the Screen Design
+
+First, determine which screen design to screenshot.
+
+Read `/product/product-roadmap.md` to get the list of available sections, then check `src/sections/` to see what screen designs exist.
+
+If only one screen design exists across all sections, auto-select it.
+
+If multiple screen designs exist, use the AskUserQuestion tool to ask which one to screenshot:
+
+"Which screen design would you like to screenshot?"
+
+Present the available screen designs as options, grouped by section:
+- [Section Name] / [ScreenDesignName]
+- [Section Name] / [ScreenDesignName]
+
+## Step 2: Start the Dev Server
+
+Start the dev server yourself using Bash. Run `npm run dev` in the background so you can continue with the screenshot capture.
+
+Do NOT ask the user if the server is running or tell them to start it. You must start it yourself.
+
+After starting the server, wait a few seconds for it to be ready before navigating to the screen design URL.
+
+## Step 3: Capture the Screenshot
+
+Use the Playwright MCP tool to navigate to the screen design and capture a screenshot.
+
+The screen design URL pattern is: `http://localhost:3000/sections/[section-id]/screen-designs/[screen-design-name]`
+
+1. First, use `browser_navigate` to go to the screen design URL
+2. Wait for the page to fully load
+3. **Click the "Hide" link** in the navigation bar to hide it before taking the screenshot. The Hide button has the attribute `data-hide-header` which you can use to locate it.
+4. Use `browser_take_screenshot` to capture the page (without the navigation bar)
+
+**Screenshot specifications:**
+- Capture at desktop viewport width (1280px recommended)
+- Use **full page screenshot** to capture the entire scrollable content (not just the viewport)
+- PNG format for best quality
+
+When using `browser_take_screenshot`, set `fullPage: true` to capture the entire page including content below the fold.
+
+## Step 4: Save the Screenshot
+
+The Playwright MCP tool can only save screenshots to its default output directory (`.playwright-mcp/`). You must save the screenshot there first, then copy it to the product folder.
+
+1. **First**, use `browser_take_screenshot` with just a filename (no path):
+   - Use a simple filename like `dashboard.png` or `invoice-list.png`
+   - The file will be saved to `.playwright-mcp/[filename].png`
+
+2. **Then**, copy the file to the product folder using Bash:
+   ```bash
+   cp .playwright-mcp/[filename].png product/sections/[section-id]/[filename].png
+   ```
+
+**Naming convention:** `[screen-design-name]-[variant].png`
+
+Examples:
+- `invoice-list.png` (main view)
+- `invoice-list-dark.png` (dark mode variant)
+- `invoice-detail.png`
+- `invoice-form-empty.png` (empty state)
+
+If the user wants both light and dark mode screenshots, capture both.
+
+## Step 5: Confirm Completion
+
+Let the user know:
+
+"I've saved the screenshot to `product/sections/[section-id]/[filename].png`.
+
+The screenshot captures the **[ScreenDesignName]** screen design for the **[Section Title]** section."
+
+If they want additional screenshots (e.g., dark mode, different states):
+
+"Would you like me to capture any additional screenshots? For example:
+- Dark mode version
+- Mobile viewport
+- Different states (empty, loading, etc.)"
+
+## Important Notes
+
+- Start the dev server yourself - do not ask the user to do it
+- Screenshots are saved to `product/sections/[section-id]/` alongside spec.md and data.json
+- Use descriptive filenames that indicate the screen design and any variant (dark mode, mobile, etc.)
+- Capture at a consistent viewport width for documentation consistency
+- Always capture full page screenshots to include all scrollable content
+- After you're done, you may kill the dev server if you started it