@builderos/create-agent-os 0.0.2

package/src/template/design/agents.md

@@ -0,0 +1,218 @@
+# Agent Directives for Design OS
+
+Design OS is a **product planning and design tool** that helps users define their product vision, structure their data model, design their UI, and prepare export packages for implementation in a separate codebase.
+
+> **Important**: Design OS is a planning tool, not the end product codebase. The screen designs and components generated here are meant to be exported and integrated into your actual product's codebase.
+
+---
+
+## Understanding Design OS Context
+
+When working in Design OS, be aware of two distinct contexts:
+
+### 1. Design OS Application
+The React application that displays and manages planning files. When modifying the Design OS UI itself:
+- Files live in `src/` (components, pages, utilities)
+- Uses the Design OS design system (stone palette, DM Sans, etc.)
+- Provides the interface for viewing specs, screen designs, exports, etc.
+
+### 2. Product Design (Screen Designs & Exports)
+The product you're planning and designing. When creating screen designs and exports:
+- Screen design components live in `src/sections/[section-name]/` and `src/shell/`
+- Product definition files live in `product/`
+- Exports are packaged to `product-plan/` for integration into a separate codebase
+- Follow the design requirements specified in each section's spec
+
+---
+
+## Getting Started — The Planning Flow
+
+Design OS follows a structured planning sequence:
+
+### 1. Product Overview (`/product-vision`)
+Define your product's core description, the problems it solves, and key features.
+**Output:** `product/product-overview.md`
+
+### 2. Product Roadmap (`/product-roadmap`)
+Break your product into 3-5 development sections. Each section represents a self-contained area that can be designed and built independently.
+**Output:** `product/product-roadmap.md`
+
+### 3. Data Model (`/data-model`)
+Define the core entities and relationships in your product. This establishes the "nouns" of your system and ensures consistency across sections.
+**Output:** `product/data-model/data-model.md`
+
+### 4. Design System (`/design-tokens`)
+Choose your color palette (from Tailwind) and typography (from Google Fonts). These tokens are applied to all screen designs.
+**Output:** `product/design-system/colors.json`, `product/design-system/typography.json`
+
+### 5. Application Shell (`/design-shell`)
+Design the persistent navigation and layout that wraps all sections.
+**Output:** `product/shell/spec.md`, `src/shell/components/`
+
+### 6. For Each Section:
+- `/shape-section` — Define the specification
+- `/sample-data` — Create sample data and types
+- `/design-screen` — Create screen designs
+- `/screenshot-design` — Capture screenshots
+
+### 7. Export (`/export-product`)
+Generate the complete export package with all components, types, and handoff documentation.
+**Output:** `product-plan/`
+
+---
+
+## File Structure
+
+```
+product/                           # Product definition (portable)
+├── product-overview.md            # Product description, problems/solutions, features
+├── product-roadmap.md             # List of sections with titles and descriptions
+│
+├── data-model/                    # Global data model
+│   └── data-model.md              # Entity descriptions and relationships
+│
+├── design-system/                 # Design tokens
+│   ├── colors.json                # { primary, secondary, neutral }
+│   └── typography.json            # { heading, body, mono }
+│
+├── shell/                         # Application shell
+│   └── spec.md                    # Shell specification
+│
+└── sections/
+    └── [section-name]/
+        ├── spec.md                # Section specification
+        ├── data.json              # Sample data for screen designs
+        ├── types.ts               # TypeScript interfaces
+        └── *.png                  # Screenshots
+
+src/
+├── shell/                         # Shell design components
+│   ├── components/
+│   │   ├── AppShell.tsx
+│   │   ├── MainNav.tsx
+│   │   ├── UserMenu.tsx
+│   │   └── index.ts
+│   └── ShellPreview.tsx
+│
+└── sections/
+    └── [section-name]/
+        ├── components/            # Exportable components
+        │   ├── [Component].tsx
+        │   └── index.ts
+        └── [ViewName].tsx         # Preview wrapper
+
+product-plan/                      # Export package (generated)
+├── README.md                      # Quick start guide
+├── product-overview.md            # Product summary
+├── prompts/                       # Ready-to-use prompts for coding agents
+│   ├── one-shot-prompt.md         # Prompt for full implementation
+│   └── section-prompt.md          # Prompt template for incremental
+├── instructions/                  # Implementation instructions
+│   ├── one-shot-instructions.md   # All milestones combined
+│   └── incremental/               # Milestone-by-milestone instructions
+│       ├── 01-foundation.md
+│       ├── 02-shell.md
+│       └── [NN]-[section-id].md   # Section-specific instructions
+├── design-system/                 # Tokens, colors, fonts
+├── data-model/                    # Types and sample data
+├── shell/                         # Shell components
+└── sections/                      # Section components (with tests.md each)
+```
+
+---
+
+## Design Requirements
+
+When creating screen designs, follow these guidelines:
+
+- **Mobile Responsive**: Use Tailwind's responsive prefixes (`sm:`, `md:`, `lg:`, `xl:`) to ensure layouts adapt properly across screen sizes.
+
+- **Light & Dark Mode**: Use `dark:` variants for all colors. Test that all UI elements are visible and readable in both modes.
+
+- **Use Design Tokens**: When design tokens are defined, apply the product's color palette and typography. Otherwise, fall back to `stone` for neutrals and `lime` for accents.
+
+- **Props-Based Components**: All screen design components must accept data and callbacks via props. Never import data directly in exportable components.
+
+- **No Navigation in Section Screen Designs**: Section screen designs should not include navigation chrome. The shell handles all navigation.
+
+---
+
+## Tailwind CSS Directives
+
+These rules apply to both the Design OS application and all screen designs/components it generates:
+
+- **Tailwind CSS v4**: We always use Tailwind CSS v4 (not v3). Do not reference or create v3 patterns.
+
+- **No tailwind.config.js**: Tailwind CSS v4 does not use a `tailwind.config.js` file. Never reference, create, or modify one.
+
+- **Use Built-in Utility Classes**: Avoid writing custom CSS. Stick to using Tailwind's built-in utility classes for all styling.
+
+- **Use Built-in Colors**: Avoid defining custom colors. Use Tailwind's built-in color utility classes (e.g., `stone-500`, `lime-400`, `red-600`).
+
+---
+
+## The Four Pillars
+
+Design OS is organized around four main areas:
+
+1. **Product Overview** — The "what" and "why"
+   - Product name and description
+   - Problems and solutions
+   - Key features
+   - Sections/roadmap
+
+2. **Data Model** — The "nouns" of the system
+   - Core entity names and descriptions
+   - Relationships between entities
+   - Minimal — leaves room for implementation
+
+3. **Design System** — The "look and feel"
+   - Color palette (Tailwind colors)
+   - Typography (Google Fonts)
+
+4. **Application Shell** — The persistent chrome
+   - Global navigation structure
+   - User menu
+   - Layout pattern
+
+Plus **Sections** — The individual features, each with spec, data, screen designs.
+
+---
+
+## Design System Scope
+
+Design OS separates concerns between its own UI and the product being designed:
+
+- **Design OS UI**: Always uses the stone/lime palette and DM Sans typography
+- **Product Screen Designs**: Use the design tokens defined for the product (when available)
+- **Shell**: Uses product design tokens to preview the full app experience
+
+---
+
+## Export & Handoff
+
+The `/export-product` command generates a complete handoff package:
+
+- **Ready-to-use prompts**: Pre-written prompts to copy/paste into coding agents
+  - `one-shot-prompt.md`: For full implementation in one session
+  - `section-prompt.md`: Template for section-by-section implementation
+- **Implementation instructions**: Detailed guides for each milestone
+  - `product-overview.md`: Always provide for context
+  - `one-shot-instructions.md`: All milestones combined
+  - Incremental instructions in `instructions/incremental/`
+- **Test instructions**: Each section includes `tests.md` with TDD specs
+- **Portable components**: Props-based, ready for any React setup
+
+The prompts guide the implementation agent to ask clarifying questions about authentication, user modeling, and tech stack before building. Test instructions are framework-agnostic and include user flows, empty states, and edge cases.
+
+---
+
+## Design System (Design OS Application)
+
+The Design OS application itself uses a "Refined Utility" aesthetic:
+
+- **Typography**: DM Sans for headings and body, IBM Plex Mono for code
+- **Colors**: Stone palette for neutrals (warm grays), lime for accents
+- **Layout**: Maximum 800px content width, generous whitespace
+- **Cards**: Minimal borders (1px), subtle shadows, generous padding
+- **Motion**: Subtle fade-ins (200ms), no bouncy animations

package/src/template/design/claude.md

@@ -0,0 +1 @@
+Refer to @agents.md

package/src/template/design/components.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/index.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {}
+}

package/src/template/design/docs/codebase-implementation.md

@@ -0,0 +1,153 @@
+# Codebase Implementation
+
+After exporting your designs from Design OS, you have a complete handoff package ready for implementation. This guide covers how to work with your AI coding agent to build the product.
+
+## Getting Started
+
+1. Copy the `product-plan/` folder into your target codebase
+2. Start your AI coding agent (Claude Code, Cursor, etc.)
+3. Choose your implementation approach: one-shot or section-by-section
+
+## Implementation Approaches
+
+### Option A: Incremental Implementation (Recommended)
+
+For larger products or when you want to review progress incrementally.
+
+**How it works:**
+
+Work through the instructions in order:
+
+1. **Foundation** (`instructions/incremental/01-foundation.md`) — Design tokens, data model types, routing
+2. **Shell** (`instructions/incremental/02-shell.md`) — Application shell and navigation
+3. **Sections** (`instructions/incremental/03-*.md`, `04-*.md`, etc.) — Each feature section, one at a time
+
+For each milestone:
+
+1. Open `product-plan/prompts/section-prompt.md`
+2. Fill in the section variables at the top (SECTION_NAME, SECTION_ID, NN)
+3. Add any section-specific notes
+4. Copy/paste the prompt into your coding agent
+5. Answer clarifying questions and let the agent implement
+6. Review and test before moving to the next milestone
+
+**The section prompt:**
+
+- References the section's instruction file and assets
+- Points to `tests.md` for test-driven development
+- Asks about auth, data relationships, and integration points
+
+### Option B: One-Shot Implementation
+
+For simpler products or when you want to build everything in one session.
+
+**How it works:**
+
+1. Open `product-plan/prompts/one-shot-prompt.md`
+2. Add any additional notes (tech stack preferences, constraints)
+3. Copy/paste the prompt into your coding agent
+4. Answer the agent's clarifying questions about auth, user modeling, etc.
+5. Let the agent plan and implement everything
+
+The prompt references `product-overview.md` and `instructions/one-shot-instructions.md`, and guides your agent to ask important questions before starting.
+
+**The prompt includes questions about:**
+
+- Authentication & authorization (login methods, user roles)
+- User & account modeling (single-user vs multi-user, teams/workspaces)
+- Tech stack preferences (backend framework, database)
+- Any other clarifications needed
+
+## Test-Driven Development
+
+Each section includes a `tests.md` file with detailed test-writing instructions. We recommend a TDD approach:
+
+1. **Read the test instructions** — Review `sections/[section-id]/tests.md`
+2. **Write failing tests** — Based on the user flows and assertions described
+3. **Implement the feature** — Make the tests pass
+4. **Refactor** — Clean up while keeping tests green
+
+The test instructions include:
+
+- **User flow tests** — Success and failure paths for key interactions
+- **Empty state tests** — Verifying behavior when no records exist
+- **Component interaction tests** — Specific UI elements and behaviors
+- **Edge cases** — Boundary conditions and transitions
+
+Test instructions are **framework-agnostic**—they describe WHAT to test, not HOW. Adapt them to your testing setup (Jest, Vitest, Playwright, Cypress, RSpec, Minitest, PHPUnit, etc.).
+
+## Spec-Driven Development
+
+We also recommend a spec-driven approach:
+
+1. **Review the design** — Understand what's been designed and why
+2. **Ask clarifying questions** — Resolve any ambiguities before coding
+3. **Write the technical spec** — Define the backend architecture, API contracts, database schema
+4. **Write tests first** — Based on the provided test instructions
+5. **Implement** — Build to make tests pass
+6. **Verify** — Ensure the implementation matches the design
+
+This approach prevents wasted work from misunderstandings and ensures the backend properly supports the frontend designs.
+
+## Clarifying Questions
+
+Before finalizing any implementation plan, encourage your agent to ask questions like:
+
+**Architecture:**
+- What backend framework are we using?
+- How should authentication work?
+- Are there existing patterns in this codebase to follow?
+
+**Data:**
+- How should the data model extend what's defined?
+- Are there validation rules beyond what the UI shows?
+- How should relationships be handled (eager loading, lazy loading)?
+
+**Integration:**
+- How should the callbacks be implemented (API calls, local state)?
+- What error handling patterns should we use?
+- Are there existing UI components to reuse alongside the new ones?
+
+**Scope:**
+- Should we implement all features in this milestone or prioritize?
+- Are there any features to skip for now?
+- What's the testing strategy?
+
+## What Your Agent Needs to Build
+
+The Design OS export provides finished UI designs. Your implementation agent still needs to create:
+
+**Backend:**
+- Database schema and migrations
+- API endpoints (REST or GraphQL)
+- Business logic and validation
+- Authentication and authorization
+
+**Data Layer:**
+- State management setup
+- Data fetching and caching
+- Real-time updates (if needed)
+
+**Integration:**
+- Routing configuration
+- Callback implementations
+- Error handling and loading states
+- Empty state handling (when no records exist)
+- Form validation and submission
+
+**Tests:**
+- Unit and integration tests based on `tests.md` instructions
+- User flow tests (success and failure paths)
+- Empty state verification
+
+**The UI components are complete and production-ready.** Focus implementation effort on the data layer, backend, and tests—don't redesign or restyle the provided components.
+
+## Tips
+
+- **Use the pre-written prompts** — They include important clarifying questions about auth and data modeling
+- **Always include product-overview.md** — It gives essential context about the full product
+- **Write tests first** — Use the `tests.md` instructions for TDD
+- **Review incrementally** — Section-by-section implementation lets you catch issues early
+- **Test with sample data first** — Use the provided sample-data.json before building real APIs
+- **Handle empty states** — Ensure good UX when no records exist (first-time users)
+- **Trust the components** — They're designed and styled already; wire them up, don't rebuild them

package/src/template/design/docs/design-section.md

@@ -0,0 +1,135 @@
+# Designing Sections
+
+After completing [Product Planning](product-planning.md), you're ready to design individual sections. Work through each section in your roadmap, completing these steps for each one.
+
+## 1. Shape the Section
+
+```
+/shape-section
+```
+
+Define what the section does. If you have multiple sections, you'll be asked which one to work on.
+
+This is a conversational process to establish:
+
+- **Overview** — What this section is for (2-3 sentences)
+- **User flows** — The main actions and step-by-step interactions
+- **UI requirements** — Specific layouts, patterns, or components needed
+- **Scope boundaries** — What's intentionally excluded
+
+Share any notes or ideas you have. The AI will ask clarifying questions about user actions, information to display, and UI patterns. Focus on experience and interface requirements—no backend or database details.
+
+You'll also be asked whether this section should display inside the application shell (most sections do) or as a standalone page (for things like landing pages or embedded widgets).
+
+**Creates:** `product/sections/[section-id]/spec.md`
+
+## 2. Create Sample Data
+
+```
+/sample-data
+```
+
+Generate realistic sample data based on the spec. This data populates your screen designs and makes them feel real.
+
+The AI analyzes your section spec and proposes a data structure:
+
+- **Entities** — Based on your global data model (if defined) or inferred from the spec
+- **Relationships** — How the data connects
+- **Sample records** — 5-10 realistic entries with varied content
+
+You'll also get TypeScript types generated automatically:
+
+- **Data interfaces** — Type definitions for each entity
+- **Props interface** — What the component expects, including callbacks for actions (onView, onEdit, onDelete, etc.)
+
+The sample data includes:
+- Realistic names, dates, and descriptions (not "Lorem ipsum")
+- Varied content lengths and statuses
+- Edge cases (empty arrays, long text)
+
+**Creates:**
+- `product/sections/[section-id]/data.json` — Sample data with `_meta` descriptions
+- `product/sections/[section-id]/types.ts` — TypeScript interfaces
+
+## 3. Design the Screen
+
+```
+/design-screen
+```
+
+Build the actual React components for the section. This is where the spec and sample data become a working UI.
+
+### What Gets Created
+
+**Exportable components** (props-based, portable):
+
+The main component and any sub-components, all accepting data and callbacks via props. These are what get exported to your codebase.
+
+```tsx
+// Example: Components accept props, never import data directly
+export function InvoiceList({
+  invoices,
+  onView,
+  onEdit,
+  onDelete,
+  onCreate
+}: InvoiceListProps) {
+  // ...
+}
+```
+
+**Preview wrapper** (for Design OS only):
+
+A wrapper that imports the sample data and feeds it to the component, so you can see it running in Design OS.
+
+### Design Requirements
+
+All screen designs include:
+
+- **Mobile responsive** — Tailwind responsive prefixes (`sm:`, `md:`, `lg:`)
+- **Light & dark mode** — Using `dark:` variants
+- **Design tokens applied** — Your color palette and typography choices
+- **All spec requirements** — Every user flow and UI requirement implemented
+
+### Multiple Views
+
+If the spec implies multiple views (list view, detail view, form, etc.), you'll be asked which to build first. Run `/design-screen` again for additional views.
+
+**Creates:**
+- `src/sections/[section-id]/components/[ViewName].tsx` — Main component
+- `src/sections/[section-id]/components/[SubComponent].tsx` — Sub-components as needed
+- `src/sections/[section-id]/components/index.ts` — Component exports
+- `src/sections/[section-id]/[ViewName].tsx` — Preview wrapper
+
+**Important:** Restart your dev server after creating screen designs to see the changes.
+
+## 4. Capture Screenshots (Optional)
+
+```
+/screenshot-design
+```
+
+Take screenshots of your screen designs for documentation. Screenshots are saved alongside the spec and data files.
+
+This command:
+1. Starts the dev server automatically
+2. Navigates to your screen design
+3. Hides the Design OS navigation bar
+4. Captures a full-page screenshot
+
+Screenshots are useful for:
+- Visual reference during implementation
+- Documentation and handoff materials
+- Comparing designs across sections
+
+**Requires:** Playwright MCP server. If not installed, you'll be prompted with setup instructions.
+
+**Creates:** `product/sections/[section-id]/[screen-name].png`
+
+## Repeat for Each Section
+
+Work through your roadmap sections in order. Each section builds on the foundation you established and benefits from the consistency of your global data model and design tokens.
+
+## What's Next
+
+When all sections are designed, you're ready to export. See [Export](export.md) for generating the complete handoff package.

package/src/template/design/docs/export.md

@@ -0,0 +1,149 @@
+# Export
+
+When your designs are complete, export everything your implementation agent (or team) needs to build the product.
+
+## When to Export
+
+You're ready to export when:
+
+- Product vision and roadmap are defined
+- At least one section has screen designs
+- You're satisfied with the design direction
+
+You can export at any point—it doesn't have to be "complete." Exporting generates a snapshot of your current designs. You can always export again later as you add more sections.
+
+## Running the Export
+
+```
+/export-product
+```
+
+The export command:
+
+1. **Checks prerequisites** — Verifies required files exist
+2. **Gathers all design assets** — Components, types, data, tokens
+3. **Generates implementation instructions** — Including ready-to-use prompts
+4. **Generates test instructions** — TDD specs for each section
+5. **Creates the export package** — A complete `product-plan/` directory
+6. **Creates a zip file** — `product-plan.zip` for easy download
+
+## What's Included
+
+### Ready-to-Use Prompts
+
+```
+product-plan/prompts/
+├── one-shot-prompt.md     # Prompt for full implementation
+└── section-prompt.md      # Prompt template for section-by-section
+```
+
+These are pre-written prompts you copy/paste into your coding agent. They reference the instruction files and prompt your agent to ask important clarifying questions about authentication, user modeling, and tech stack before implementing.
+
+### Instructions
+
+```
+product-plan/
+├── product-overview.md              # Product summary (always provide)
+└── instructions/
+    ├── one-shot-instructions.md     # All milestones combined
+    └── incremental/                 # Milestone-by-milestone implementation
+        ├── 01-foundation.md         # Design tokens, data model, routing
+        ├── 02-shell.md              # Application shell implementation
+        ├── 03-[section-id].md        # One per section (e.g., 03-invoices.md)
+        └── ...
+```
+
+**product-overview.md** provides context about the full product—always include it with any implementation session.
+
+**one-shot-instructions.md** combines all milestones into a single document. Use this with `one-shot-prompt.md` for full implementation.
+
+**Incremental instructions** break the work into milestones. Use these with `section-prompt.md` for step-by-step implementation.
+
+### Design System
+
+```
+product-plan/design-system/
+├── tokens.css           # CSS custom properties
+├── tailwind-colors.md   # Tailwind configuration guide
+└── fonts.md             # Google Fonts setup
+```
+
+### Data Model
+
+```
+product-plan/data-model/
+├── README.md            # Entity descriptions
+├── types.ts             # TypeScript interfaces
+└── sample-data.json     # Combined sample data
+```
+
+### Shell Components
+
+```
+product-plan/shell/
+├── README.md            # Design intent
+├── components/
+│   ├── AppShell.tsx     # Main layout wrapper
+│   ├── MainNav.tsx      # Navigation
+│   ├── UserMenu.tsx     # User menu
+│   └── index.ts         # Exports
+└── screenshot.png       # Visual reference (if captured)
+```
+
+### Section Components
+
+For each section:
+
+```
+product-plan/sections/[section-id]/
+├── README.md            # Feature overview, user flows
+├── tests.md             # Test-writing instructions (TDD)
+├── components/
+│   ├── [Component].tsx  # Exportable components
+│   └── index.ts         # Exports
+├── types.ts             # TypeScript interfaces
+├── sample-data.json     # Test data
+└── screenshot.png       # Visual reference (if captured)
+```
+
+### Test Instructions
+
+Each section includes a `tests.md` file with framework-agnostic test-writing instructions:
+
+- **User flow tests** — Success and failure paths for key interactions
+- **Empty state tests** — Verifying UI when no records exist
+- **Component interaction tests** — Specific UI elements and behaviors to verify
+
+These instructions describe WHAT to test, not HOW—your coding agent adapts them to your test framework (Jest, Vitest, Playwright, Cypress, RSpec, Minitest, PHPUnit, etc.).
+
+## About the Components
+
+Exported components are:
+
+- **Props-based** — Accept data and callbacks via props, never import data directly
+- **Portable** — Work with any React setup, no Design OS dependencies
+- **Complete** — Full styling, responsive design, dark mode support
+- **Production-ready** — Not prototypes or mockups
+
+```tsx
+// Components expect data and callbacks as props
+<InvoiceList
+  invoices={data}
+  onView={(id) => navigate(`/invoices/${id}`)}
+  onEdit={(id) => navigate(`/invoices/${id}/edit`)}
+  onDelete={(id) => confirmDelete(id)}
+  onCreate={() => navigate('/invoices/new')}
+/>
+```
+
+Your implementation agent's job is to:
+- Wire up callbacks to routing and API calls
+- Replace sample data with real data from your backend
+- Implement proper error handling and loading states
+- Implement empty states when no records exist (first-time users, after deletions)
+- Build the backend APIs the components need
+- Write tests based on the provided test instructions (TDD approach)
+
+## Using the Export
+
+See [Codebase Implementation](codebase-implementation.md) for detailed guidance on implementing your design in your codebase.