@builderos/create-agent-os 0.0.2

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

@@ -0,0 +1,309 @@
+# Design Screen
+
+You are helping the user create a screen design for a section of their product. The screen design will be a props-based React component that can be exported and integrated into any React codebase.
+
+## Step 1: Check Prerequisites
+
+First, identify the target section and verify that `spec.md`, `data.json`, and `types.ts` all exist.
+
+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 create a screen design for.
+
+Then verify all required files exist:
+
+- `product/sections/[section-id]/spec.md`
+- `product/sections/[section-id]/data.json`
+- `product/sections/[section-id]/types.ts`
+
+If spec.md doesn't exist:
+
+"I don't see a specification for **[Section Title]** yet. Please run `/shape-section` first to define the section's requirements."
+
+If data.json or types.ts don't exist:
+
+"I don't see sample data for **[Section Title]** yet. Please run `/sample-data` first to create sample data and types for the screen designs."
+
+Stop here if any file is missing.
+
+## Step 2: Check for Design System and Shell
+
+Check for optional enhancements:
+
+**Design Tokens:**
+- Check if `/product/design-system/colors.json` exists
+- Check if `/product/design-system/typography.json` exists
+
+If design tokens exist, read them and use them for styling. If they don't exist, show a warning:
+
+"Note: Design tokens haven't been defined yet. I'll use default styling, but for consistent branding, consider running `/design-tokens` first."
+
+**Shell:**
+- Check if `src/shell/components/AppShell.tsx` exists
+
+If shell exists, the screen design will render inside the shell in Design OS. If not, show a warning:
+
+"Note: An application shell hasn't been designed yet. The screen design will render standalone. Consider running `/design-shell` first to see section screen designs in the full app context."
+
+## Step 3: Analyze Requirements
+
+Read and analyze all three files:
+
+1. **spec.md** - Understand the user flows and UI requirements
+2. **data.json** - Understand the data structure and sample content
+3. **types.ts** - Understand the TypeScript interfaces and available callbacks
+
+Identify what views are needed based on the spec. Common patterns:
+
+- List/dashboard view (showing multiple items)
+- Detail view (showing a single item)
+- Form/create view (for adding/editing)
+
+## Step 4: Clarify the Screen Design Scope
+
+If the spec implies multiple views, use the AskUserQuestion tool to confirm which view to build first:
+
+"The specification suggests a few different views for **[Section Title]**:
+
+1. **[View 1]** - [Brief description]
+2. **[View 2]** - [Brief description]
+
+Which view should I create first?"
+
+If there's only one obvious view, proceed directly.
+
+## Step 5: Invoke the Frontend Design Skill
+
+Before creating the screen design, read the `frontend-design` skill to ensure high-quality design output.
+
+Read the file at `.claude/skills/frontend-design/SKILL.md` and follow its guidance for creating distinctive, production-grade interfaces.
+
+## Step 6: Create the Props-Based Component
+
+Create the main component file at `src/sections/[section-id]/components/[ViewName].tsx`.
+
+### Component Structure
+
+The component MUST:
+
+- Import types from the types.ts file
+- Accept all data via props (never import data.json directly)
+- Accept callback props for all actions
+- Be fully self-contained and portable
+
+Example:
+
+```tsx
+import type { InvoiceListProps } from '@/../product/sections/[section-id]/types'
+
+export function InvoiceList({
+  invoices,
+  onView,
+  onEdit,
+  onDelete,
+  onCreate
+}: InvoiceListProps) {
+  return (
+    <div className="max-w-4xl mx-auto">
+      {/* Component content here */}
+
+      {/* Example: Using a callback */}
+      <button onClick={onCreate}>Create Invoice</button>
+
+      {/* Example: Mapping data with callbacks */}
+      {invoices.map(invoice => (
+        <div key={invoice.id}>
+          <span>{invoice.clientName}</span>
+          <button onClick={() => onView?.(invoice.id)}>View</button>
+          <button onClick={() => onEdit?.(invoice.id)}>Edit</button>
+          <button onClick={() => onDelete?.(invoice.id)}>Delete</button>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### Design Requirements
+
+- **Mobile responsive:** Use Tailwind responsive prefixes (`sm:`, `md:`, `lg:`) and ensure the design layout works gracefully on mobile, tablet and desktop screen sizes.
+- **Light & dark mode:** Use `dark:` variants for all colors
+- **Use design tokens:** If defined, apply the product's color palette and typography
+- **Follow the frontend-design skill:** Create distinctive, memorable interfaces
+
+### Applying Design Tokens
+
+**If `/product/design-system/colors.json` exists:**
+- Use the primary color for buttons, links, and key accents
+- Use the secondary color for tags, highlights, secondary elements
+- Use the neutral color for backgrounds, text, and borders
+- Example: If primary is `lime`, use `lime-500`, `lime-600`, etc. for primary actions
+
+**If `/product/design-system/typography.json` exists:**
+- Note the font choices for reference in comments
+- The fonts will be applied at the app level, but use appropriate font weights
+
+**If design tokens don't exist:**
+- Fall back to `stone` for neutrals and `lime` for accents (Design OS defaults)
+
+### What to Include
+
+- Implement ALL user flows and UI requirements from the spec
+- Use the prop data (not hardcoded values)
+- Include realistic UI states (hover, active, etc.)
+- Use the callback props for all interactive elements
+- Handle optional callbacks with optional chaining: `onClick={() => onDelete?.(id)}`
+
+### What NOT to Include
+
+- No `import data from` statements - data comes via props
+- No features not specified in the spec
+- No routing logic - callbacks handle navigation intent
+- No navigation elements (shell handles navigation)
+
+## Step 7: Create Sub-Components (If Needed)
+
+For complex views, break down into sub-components. Each sub-component should also be props-based.
+
+Create sub-components at `src/sections/[section-id]/components/[SubComponent].tsx`.
+
+Example:
+
+```tsx
+import type { Invoice } from '@/../product/sections/[section-id]/types'
+
+interface InvoiceRowProps {
+  invoice: Invoice
+  onView?: () => void
+  onEdit?: () => void
+  onDelete?: () => void
+}
+
+export function InvoiceRow({ invoice, onView, onEdit, onDelete }: InvoiceRowProps) {
+  return (
+    <div className="flex items-center justify-between p-4 border-b">
+      <div>
+        <p className="font-medium">{invoice.clientName}</p>
+        <p className="text-sm text-stone-500">{invoice.invoiceNumber}</p>
+      </div>
+      <div className="flex gap-2">
+        <button onClick={onView}>View</button>
+        <button onClick={onEdit}>Edit</button>
+        <button onClick={onDelete}>Delete</button>
+      </div>
+    </div>
+  )
+}
+```
+
+Then import and use in the main component:
+
+```tsx
+import { InvoiceRow } from './InvoiceRow'
+
+export function InvoiceList({ invoices, onView, onEdit, onDelete }: InvoiceListProps) {
+  return (
+    <div>
+      {invoices.map(invoice => (
+        <InvoiceRow
+          key={invoice.id}
+          invoice={invoice}
+          onView={() => onView?.(invoice.id)}
+          onEdit={() => onEdit?.(invoice.id)}
+          onDelete={() => onDelete?.(invoice.id)}
+        />
+      ))}
+    </div>
+  )
+}
+```
+
+## Step 8: Create the Preview Wrapper
+
+Create a preview wrapper at `src/sections/[section-id]/[ViewName].tsx` (note: this is in the section root, not in components/).
+
+This wrapper is what Design OS renders. It imports the sample data and feeds it to the props-based component.
+
+Example:
+
+```tsx
+import data from '@/../product/sections/[section-id]/data.json'
+import { InvoiceList } from './components/InvoiceList'
+
+export default function InvoiceListPreview() {
+  return (
+    <InvoiceList
+      invoices={data.invoices}
+      onView={(id) => console.log('View invoice:', id)}
+      onEdit={(id) => console.log('Edit invoice:', id)}
+      onDelete={(id) => console.log('Delete invoice:', id)}
+      onCreate={() => console.log('Create new invoice')}
+    />
+  )
+}
+```
+
+The preview wrapper:
+
+- Has a `default` export (required for Design OS routing)
+- Imports sample data from data.json
+- Passes data to the component via props
+- Provides console.log handlers for callbacks (for testing interactions)
+- Is NOT exported to the user's codebase - it's only for Design OS
+- **Will render inside the shell** if one has been designed
+
+## Step 9: Create Component Index
+
+Create an index file at `src/sections/[section-id]/components/index.ts` to cleanly export all components.
+
+Example:
+
+```tsx
+export { InvoiceList } from './InvoiceList'
+export { InvoiceRow } from './InvoiceRow'
+// Add other sub-components as needed
+```
+
+## Step 10: Confirm and Next Steps
+
+Let the user know:
+
+"I've created the screen design for **[Section Title]**:
+
+**Exportable components** (props-based, portable):
+
+- `src/sections/[section-id]/components/[ViewName].tsx`
+- `src/sections/[section-id]/components/[SubComponent].tsx` (if created)
+- `src/sections/[section-id]/components/index.ts`
+
+**Preview wrapper** (for Design OS only):
+
+- `src/sections/[section-id]/[ViewName].tsx`
+
+**Important:** Restart your dev server to see the changes.
+
+[If shell exists]: The screen design will render inside your application shell, showing the full app experience.
+
+[If design tokens exist]: I've applied your color palette ([primary], [secondary], [neutral]) and typography choices.
+
+**Next steps:**
+
+- Run `/screenshot-design` to capture a screenshot of this screen design for documentation
+- If the spec calls for additional views, run `/design-screen` again to create them
+- When all sections are complete, run `/export-product` to generate the complete export package"
+
+If the spec indicates additional views are needed:
+
+"The specification also calls for [other view(s)]. Run `/design-screen` again to create those, then `/screenshot-design` to capture each one."
+
+## Important Notes
+
+- ALWAYS read the `frontend-design` skill before creating screen designs
+- Components MUST be props-based - never import data.json in exportable components
+- The preview wrapper is the ONLY file that imports data.json
+- Use TypeScript interfaces from types.ts for all props
+- Callbacks should be optional (use `?`) and called with optional chaining (`?.`)
+- Always remind the user to restart the dev server after creating files
+- Sub-components should also be props-based for maximum portability
+- Apply design tokens when available for consistent branding
+- Screen designs render inside the shell when viewed in Design OS (if shell exists)

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

@@ -0,0 +1,238 @@
+# Design Shell
+
+You are helping the user design the application shell — the persistent navigation and layout that wraps all sections. This is a screen design, not implementation code.
+
+## Step 1: Check Prerequisites
+
+First, verify prerequisites exist:
+
+1. Read `/product/product-overview.md` — Product name and description
+2. Read `/product/product-roadmap.md` — Sections for navigation
+3. Check if `/product/design-system/colors.json` and `/product/design-system/typography.json` exist
+
+If overview or roadmap are missing:
+
+"Before designing the shell, you need to define your product and sections. Please run:
+1. `/product-vision` — Define your product
+2. `/product-roadmap` — Define your sections"
+
+Stop here if overview or roadmap are missing.
+
+If design tokens are missing, show a warning but continue:
+
+"Note: Design tokens haven't been defined yet. I'll proceed with default styling, but you may want to run `/design-tokens` first for consistent colors and typography."
+
+## Step 2: Analyze Product Structure
+
+Review the roadmap sections and present navigation options:
+
+"I'm designing the shell for **[Product Name]**. Based on your roadmap, you have [N] sections:
+
+1. **[Section 1]** — [Description]
+2. **[Section 2]** — [Description]
+3. **[Section 3]** — [Description]
+
+Let's decide on the shell layout. Common patterns:
+
+**A. Sidebar Navigation** — Vertical nav on the left, content on the right
+   Best for: Apps with many sections, dashboard-style tools, admin panels
+
+**B. Top Navigation** — Horizontal nav at top, content below
+   Best for: Simpler apps, marketing-style products, fewer sections
+
+**C. Minimal Header** — Just logo + user menu, sections accessed differently
+   Best for: Single-purpose tools, wizard-style flows
+
+Which pattern fits **[Product Name]** best?"
+
+Wait for their response.
+
+## Step 3: Gather Design Details
+
+Use AskUserQuestion to clarify:
+
+- "Where should the user menu (avatar, logout) appear?"
+- "Do you want the sidebar collapsible on mobile, or should it become a hamburger menu?"
+- "Any additional items in the navigation? (Settings, Help, etc.)"
+- "What should the 'home' or default view be when the app loads?"
+
+## Step 4: Present Shell Specification
+
+Once you understand their preferences:
+
+"Here's the shell design for **[Product Name]**:
+
+**Layout Pattern:** [Sidebar/Top Nav/Minimal]
+
+**Navigation Structure:**
+- [Nav Item 1] → [Section]
+- [Nav Item 2] → [Section]
+- [Nav Item 3] → [Section]
+- [Additional items like Settings, Help]
+
+**User Menu:**
+- Location: [Top right / Bottom of sidebar]
+- Contents: Avatar, user name, logout
+
+**Responsive Behavior:**
+- Desktop: [How it looks]
+- Mobile: [How it adapts]
+
+Does this match what you had in mind?"
+
+Iterate until approved.
+
+## Step 5: Create the Shell Specification
+
+Create `/product/shell/spec.md`:
+
+```markdown
+# Application Shell Specification
+
+## Overview
+[Description of the shell design and its purpose]
+
+## Navigation Structure
+- [Nav Item 1] → [Section 1]
+- [Nav Item 2] → [Section 2]
+- [Nav Item 3] → [Section 3]
+- [Any additional nav items]
+
+## User Menu
+[Description of user menu location and contents]
+
+## Layout Pattern
+[Description of the layout — sidebar, top nav, etc.]
+
+## Responsive Behavior
+- **Desktop:** [Behavior]
+- **Tablet:** [Behavior]
+- **Mobile:** [Behavior]
+
+## Design Notes
+[Any additional design decisions or notes]
+```
+
+## Step 6: Create Shell Components
+
+Create the shell components at `src/shell/components/`:
+
+### AppShell.tsx
+The main wrapper component that accepts children and provides the layout structure.
+
+```tsx
+interface AppShellProps {
+  children: React.ReactNode
+  navigationItems: Array<{ label: string; href: string; isActive?: boolean }>
+  user?: { name: string; avatarUrl?: string }
+  onNavigate?: (href: string) => void
+  onLogout?: () => void
+}
+```
+
+### MainNav.tsx
+The navigation component (sidebar or top nav based on the chosen pattern).
+
+### UserMenu.tsx
+The user menu with avatar and dropdown.
+
+### index.ts
+Export all components.
+
+**Component Requirements:**
+- Use props for all data and callbacks (portable)
+- Apply design tokens if they exist (colors, fonts)
+- Support light and dark mode with `dark:` variants
+- Be mobile responsive
+- Use Tailwind CSS for styling
+- Use lucide-react for icons
+
+## Step 7: Create Shell Preview
+
+Create `src/shell/ShellPreview.tsx` — a preview wrapper for viewing the shell in Design OS:
+
+```tsx
+import data from '@/../product/sections/[first-section]/data.json' // if exists
+import { AppShell } from './components/AppShell'
+
+export default function ShellPreview() {
+  const navigationItems = [
+    { label: '[Section 1]', href: '/section-1', isActive: true },
+    { label: '[Section 2]', href: '/section-2' },
+    { label: '[Section 3]', href: '/section-3' },
+  ]
+
+  const user = {
+    name: 'Alex Morgan',
+    avatarUrl: undefined,
+  }
+
+  return (
+    <AppShell
+      navigationItems={navigationItems}
+      user={user}
+      onNavigate={(href) => console.log('Navigate to:', href)}
+      onLogout={() => console.log('Logout')}
+    >
+      <div className="p-8">
+        <h1 className="text-2xl font-bold mb-4">Content Area</h1>
+        <p className="text-stone-600 dark:text-stone-400">
+          Section content will render here.
+        </p>
+      </div>
+    </AppShell>
+  )
+}
+```
+
+## Step 8: Apply Design Tokens
+
+If design tokens exist, apply them to the shell components:
+
+**Colors:**
+- Read `/product/design-system/colors.json`
+- Use primary color for active nav items, key accents
+- Use secondary color for hover states, subtle highlights
+- Use neutral color for backgrounds, borders, text
+
+**Typography:**
+- Read `/product/design-system/typography.json`
+- Apply heading font to nav items and titles
+- Apply body font to other text
+- Include Google Fonts import in the preview
+
+## Step 9: Confirm Completion
+
+Let the user know:
+
+"I've designed the application shell for **[Product Name]**:
+
+**Created files:**
+- `/product/shell/spec.md` — Shell specification
+- `src/shell/components/AppShell.tsx` — Main shell wrapper
+- `src/shell/components/MainNav.tsx` — Navigation component
+- `src/shell/components/UserMenu.tsx` — User menu component
+- `src/shell/components/index.ts` — Component exports
+- `src/shell/ShellPreview.tsx` — Preview wrapper
+
+**Shell features:**
+- [Layout pattern] layout
+- Navigation for all [N] sections
+- User menu with avatar and logout
+- Mobile responsive design
+- Light/dark mode support
+
+**Important:** Restart your dev server to see the changes.
+
+When you design section screens with `/design-screen`, they will render inside this shell, showing the full app experience.
+
+Next: Run `/shape-section` to start designing your first section."
+
+## Important Notes
+
+- The shell is a screen design — it demonstrates the navigation and layout design
+- Components are props-based and portable to the user's codebase
+- The preview wrapper is for Design OS only — not exported
+- Apply design tokens when available for consistent styling
+- Keep the shell focused on navigation chrome — no authentication UI
+- Section screen designs will render inside the shell's content area