@builderos/create-agent-os 0.0.2

package/src/template/design/.claude/commands/design-os/shape-section.md

@@ -0,0 +1,138 @@
+# Shape Section
+
+You are helping the user define the specification for a section of their product. This is a conversational process to establish the scope of functionality, user flows, and UI requirements.
+
+## Step 1: Check Prerequisites
+
+First, verify that `/product/product-roadmap.md` exists. If it doesn't:
+
+"I don't see a product roadmap defined yet. Please run `/product-roadmap` first to define your product sections, then come back to shape individual sections."
+
+Stop here if the roadmap doesn't exist.
+
+## Step 2: Identify the Target Section
+
+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 work on:
+
+"Which section would you like to define the specification for?"
+
+Present the available sections as options.
+
+## Step 3: Gather Initial Input
+
+Once the section is identified, invite the user to share any initial thoughts:
+
+"Let's define the scope and requirements for **[Section Title]**.
+
+Do you have any notes or ideas about what this section should include? Share any thoughts about the features, user flows, or UI patterns you're envisioning. If you're not sure yet, we can start with questions."
+
+Wait for their response. The user may provide raw notes or ask to proceed with questions.
+
+## Step 4: Ask Clarifying Questions
+
+Use the AskUserQuestion tool to ask 4-6 targeted questions to define:
+
+- **Main user actions/tasks** - What can users do in this section?
+- **Information to display** - What data and content needs to be shown?
+- **Key user flows** - What are the step-by-step interactions?
+- **UI patterns** - Any specific interactions, layouts, or components needed?
+- **Scope boundaries** - What should be explicitly excluded?
+
+Example questions (adapt based on their input and the section):
+- "What are the main actions a user can take in this section?"
+- "What information needs to be displayed on the primary view?"
+- "Walk me through the main user flow - what happens step by step?"
+- "Are there any specific UI patterns you want to use (e.g., tables, cards, modals)?"
+- "What's intentionally out of scope for this section?"
+- "Are there multiple views needed (e.g., list view and detail view)?"
+
+Ask questions one or two at a time, conversationally. Focus on user experience and interface requirements - no backend or database details.
+
+## Step 5: Ask About Shell Configuration
+
+If a shell design has been created for this project (check if `/src/shell/components/AppShell.tsx` exists), ask the user about shell usage:
+
+"Should this section's screen designs be displayed **inside the app shell** (with navigation header), or should they be **standalone pages** (without the shell)?
+
+Most sections use the app shell, but some pages like public-facing views, landing pages, or embedded widgets should be standalone."
+
+Use AskUserQuestion with options:
+- "Inside app shell" - The default for most in-app sections
+- "Standalone (no shell)" - For public pages, landing pages, or embeds
+
+If no shell design exists yet, skip this question and default to using the shell.
+
+## Step 6: Present Draft and Refine
+
+Once you have enough information, present a draft specification:
+
+"Based on our discussion, here's the specification for **[Section Title]**:
+
+**Overview:**
+[2-3 sentence summary of what this section does]
+
+**User Flows:**
+- [Flow 1]
+- [Flow 2]
+- [Flow 3]
+
+**UI Requirements:**
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+**Display:** [Inside app shell / Standalone]
+
+Does this capture everything? Would you like to adjust anything?"
+
+Iterate until the user is satisfied. Don't add features that weren't discussed. Don't leave out features that were discussed.
+
+## Step 7: Create the Spec File
+
+Once the user approves, create the file at `product/sections/[section-id]/spec.md` with this exact format:
+
+```markdown
+# [Section Title] Specification
+
+## Overview
+[The finalized 2-3 sentence description]
+
+## User Flows
+- [Flow 1]
+- [Flow 2]
+- [Flow 3]
+[Add all flows discussed]
+
+## UI Requirements
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+[Add all requirements discussed]
+
+## Configuration
+- shell: [true/false]
+```
+
+**Important:**
+- Set `shell: true` if the section should display inside the app shell (this is the default)
+- Set `shell: false` if the section should display as a standalone page without the shell
+
+The section-id is the slug version of the section title (lowercase, hyphens instead of spaces).
+
+## Step 8: Confirm and Next Steps
+
+Let the user know:
+
+"I've created the specification at `product/sections/[section-id]/spec.md`.
+
+You can review the spec on the section page. When you're ready, run `/sample-data` to create sample data for this section."
+
+## Important Notes
+
+- Be conversational and helpful, not robotic
+- Ask follow-up questions when answers are vague
+- Focus on UX and UI - don't discuss backend, database, or API details
+- Keep the spec concise - only include what was discussed, no bloat
+- The format must match exactly for the app to parse it correctly

package/src/template/design/.claude/skills/frontend-design/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: frontend-design
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+---
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Tailwind, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.

package/src/template/design/.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,5 @@
+# Code of Conduct
+
+Be respectful, assume good intent, and keep discussion constructive and on-topic. Harassment or discrimination is not tolerated.
+
+Contact: buildermethods.com/contact

package/src/template/design/.github/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to Design OS
+
+Thanks for considering a contribution! Design OS is free and open source, but to keep things manageable we follow a **Discussions-first workflow**.
+
+---
+
+## Where things go
+
+- **Discussions (Bugs):** Report suspected bugs. Maintainers may promote confirmed bugs into Issues.
+  👉 **Check the docs before posting:** [buildermethods.com/design-os](https://buildermethods.com/design-os)
+
+- **Discussions (Ideas):** Share feature ideas and proposals.
+  👉 **Check the docs first** to ensure it’s not already supported.
+
+- **Discussions (Q&A):** Ask & answer community questions.
+
+- **Builder Methods Pro:** Paid membership with guaranteed support responses → https://buildermethods.com/pro
+
+---
+
+## Pull Requests (read first!)
+
+To avoid wasted effort and to protect maintainer time:
+
+- **Bug-fix PRs:**
+  Please include `[bug fix]` in your PR title and clearly describe the steps to reproduce and test the fix.
+
+- **Feature PRs:**
+  > 💡 **Ideas welcome!** We strongly recommend starting with a Discussion in our **Ideas** section to gather feedback and community support before submitting a PR. This helps us understand your use case and explore the best approach together.
+  > Please note: New features are rarely accepted into core as we must consider long-term roadmap, maintainability, and support implications. A declined PR doesn't mean "never"—it means "not now." Starting with a Discussion gives your idea the best chance of success.
+
+- **Docs-only PRs:**
+  Typos, clarifications, and doc improvements are always welcomed.
+
+---
+
+## How to propose a new feature or integration
+
+Open a Discussion in **Ideas** with:
+- Problem & motivation
+- Proposed change & alternatives
+- User experience impact
+- Updating & compatibility considerations
+
+If a maintainer labels it **`approved`**, then a PR may be opened.
+
+---
+
+## Code of Conduct
+
+By participating, you agree to our [Code of Conduct](./CODE_OF_CONDUCT.md). Be respectful and constructive.

package/src/template/design/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,22 @@
+blank_issues_enabled: false
+
+contact_links:
+  - name: 🐛 Report a bug or propose a fix
+    url: https://github.com/buildermethods/design-os/discussions/categories/bugs
+    about: Already checked the docs and found a reproducible bug? Please report it in the 'Bugs' discussion area.
+
+  - name: 💡 Feature request or idea
+    url: https://github.com/buildermethods/design-os/discussions/categories/ideas
+    about: Request new features, integrations, or other improvements in the 'Ideas' discussion area.
+
+  - name: ❓ Ask a question
+    url: https://github.com/buildermethods/design-os/discussions/categories/q-a
+    about: For community support and general questions, use the 'Q&A' discussion area.
+
+  - name: 🎯 Member support request
+    url: https://buildermethods.com/pro
+    about: Join Builder Methods Pro for official Design OS support with guaranteed responses from Brian & team, plus access to community chat, workshops, courses and more.
+
+  - name: 📗 Check the official docs
+    url: https://buildermethods.com/design-os
+    about: Please review the docs before posting a bug, question, or idea.

package/src/template/design/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,20 @@
+## Summary
+<!-- What does this change do and why? Keep it tight. -->
+
+## Linked item
+- Closes: #<number> (must be an open Issue) **OR**
+- Implements: #<number> (must be a Discussion)
+
+## Checklist
+- [ ] Linked to related Issue/Discussion
+- [ ] Documented steps to test (below)
+- [ ] Drafted “how to use” docs (if this adds new behavior)
+- [ ] Backwards compatibility considered (notes if applicable)
+
+## Documented steps to test
+1.
+2.
+3.
+
+## Notes for reviewers
+<!-- Anything to call out, screenshots, logs, perf notes, etc. -->

package/src/template/design/.github/SECURITY.yml

@@ -0,0 +1,5 @@
+# Security Policy
+
+Please do not open public issues for potential security problems.
+
+Send potential security problems to brian@buildermethods.com and they will be addressed promptly.

package/src/template/design/.github/SUPPORT.md

@@ -0,0 +1,19 @@
+# Support policy
+
+Design OS is free and open source. To keep it sustainable, you can seek support in any of these ways:
+
+- **[Documentation](https://buildermethods.com/design-os):** Complete and up-to-date guides for installation, updating, and usage of Design OS.
+
+- **[Community Support (Free)](https://github.com/buildermethods/design-os/discussions):** Ask & answer questions with other users in the **Q&A** category of GitHub Discussions.
+
+- **[Official Support (Paid)](https://buildermethods.com/pro):** For guaranteed responses from Brian & team, join **Builder Methods Pro**.
+
+---
+
+## Bugs
+- Post suspected bugs in the **Bugs category** of Discussions.  Maintainers may promote confirmed bugs to Issues for tracking and fixes.
+
+---
+
+## Feature ideas
+Use the **Ideas category** of Discussions to propose and upvote new features and integration requests.

package/src/template/design/.github/workflows/pr-decline.yml

@@ -0,0 +1,135 @@
+name: PR manual decline (label or button)
+
+on:
+  pull_request_target:
+    types: [labeled]
+
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "PR number to act on"
+        required: true
+      reason:
+        description: "Reason to use"
+        required: true
+        type: choice
+        options: [Out of scope, Low info, Duplicate, Spam]
+
+permissions:
+  pull-requests: write
+  contents: read
+
+env:
+  REPO: ${{ github.repository }}
+  IDEAS_URL: https://github.com/buildermethods/design-os/discussions/categories/ideas
+  CONTRIBUTING_URL: https://github.com/buildermethods/design-os/blob/main/.github/CONTRIBUTING.md
+
+jobs:
+  decline:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Determine PR number and reason (from label or dispatch)
+        id: vars
+        uses: actions/github-script@v7
+        with:
+          script: |
+            let prNumber = "";
+            let reason = "";
+            let skip = false;
+
+            if (context.eventName === "pull_request_target" && context.payload.action === "labeled") {
+              prNumber = String(context.payload.pull_request.number);
+              const label = (context.payload.label?.name || "").trim();
+
+              const map = {
+                "Close PR: Out of scope": "Out of scope",
+                "Close PR: Low info": "Low info",
+                "Close PR: Duplicate": "Duplicate",
+                "Close PR: Spam": "Spam",
+              };
+
+              if (map[label]) {
+                reason = map[label];
+              } else {
+                skip = true; // not one of your decline labels
+              }
+            }
+
+            if (context.eventName === "workflow_dispatch") {
+              prNumber = (core.getInput("pr_number") || "").trim();
+              reason   = (core.getInput("reason") || "").trim();
+            }
+
+            core.setOutput("skip", skip ? "true" : "false");
+            core.setOutput("pr", prNumber);
+            core.setOutput("reason", reason);
+
+      - name: Stop if not a decline event
+        if: steps.vars.outputs.skip == 'true' || steps.vars.outputs.pr == '' || steps.vars.outputs.reason == ''
+        run: echo "No decline action to run."
+
+      - name: Build canned message
+        if: steps.vars.outputs.skip != 'true' && steps.vars.outputs.pr != '' && steps.vars.outputs.reason != ''
+        id: msg
+        uses: actions/github-script@v7
+        env:
+          REASON: ${{ steps.vars.outputs.reason }}          # <-- pass raw string
+          IDEAS_URL: ${{ env.IDEAS_URL }}
+          CONTRIBUTING_URL: ${{ env.CONTRIBUTING_URL }}
+        with:
+          script: |
+            const reason = process.env.REASON;              // <-- read raw string
+            const IDEAS = process.env.IDEAS_URL;
+            const CONTRIB = process.env.CONTRIBUTING_URL;
+
+            let body = "";
+            switch (reason) {
+              case "Out of scope":
+                body =
+                  "Thanks for the PR! After review, this change isn’t on the current roadmap for Design OS. " +
+                  "We keep core focused to manage long-term maintenance and compatibility.\n\n" +
+                  `If you'd like to continue the conversation, please start a proposal in **Ideas**: ${IDEAS}\n` +
+                  "If you publish a fork/plugin/example, feel free to share it in **Show & Tell** so others can try it.\n\n" +
+                  "_Closing to keep the backlog focused._";
+                break;
+
+              case "Low info":
+                body =
+                  "Thanks for the PR! We’re missing required details for review.\n\n" +
+                  "Please update the PR with:\n" +
+                  "• **Summary**\n" +
+                  "• **Checklist**\n" +
+                  "• **Documented steps to test**\n\n" +
+                  `Guidelines: ${CONTRIB}\n\n` +
+                  "Once updated, you can open a new PR or ask a maintainer to reopen.";
+                break;
+
+              case "Duplicate":
+                body =
+                  "Thanks for the PR! This appears to duplicate existing work or discussion. " +
+                  "We’ll consolidate on the canonical thread/PR to reduce churn.\n\n" +
+                  "_Closing this one to keep things tidy._";
+                break;
+
+              case "Spam":
+                body = "Closing this PR. It doesn’t meet our contribution policy.";
+                break;
+
+              default:
+                body = "Thanks for the PR! Closing per maintainer review.";
+            }
+
+            core.setOutput("body", body);
+
+      - name: Comment and close PR
+        if: steps.vars.outputs.skip != 'true' && steps.vars.outputs.pr != '' && steps.msg.outputs.body != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ env.REPO }}
+        run: |
+          PR="${{ steps.vars.outputs.pr }}"
+          BODY="${{ steps.msg.outputs.body }}"
+
+          gh pr comment "$PR" --repo "$REPO" --body "$BODY"
+          gh pr close   "$PR" --repo "$REPO"

package/src/template/design/.github/workflows/stale.yml

@@ -0,0 +1,25 @@
+name: Close stale threads
+
+on:
+  schedule:
+    - cron: "0 9 * * *" # daily at 09:00 UTC
+
+permissions:
+  issues: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v9
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          days-before-stale: 30
+          days-before-close: 7
+          stale-issue-message: >
+            This issue has been marked stale due to inactivity. If this is still a problem,
+            please add new details (logs, steps to reproduce) and we’ll revisit.
+          close-issue-message: >
+            Closing due to inactivity. If you can provide a fresh, reproducible case on the latest version,
+            please open a new bug report with full details. Thanks!
+          exempt-issue-labels: bug

package/src/template/design/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+Get notified of major releases by subscribing here:
+https://buildermethods.com/design-os
+
+## [0.1.1] - 2025-12-18
+
+- In the export package, consolidated '01-foundation' and '02-shell' into one.
+- Updated README.md tips that come in the export.
+
+## [0.1] - 2025-12-16
+
+- Initial release

package/src/template/design/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CasJam Media LLC (Builder Methods)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/template/design/README.md

@@ -0,0 +1,54 @@
+<img width="1280" height="640" alt="Design OS" src="https://github.com/user-attachments/assets/a9c04258-7b9a-45b6-8475-3431cdf5dbe9" />
+
+## The missing design process between your idea and your codebase.
+
+[Design OS](https://buildermethods.com/design-os) is a product planning and design tool that helps you define your product vision, structure your data model, design your UI, and export production-ready components for implementation. Rather than jumping straight into code, you work through a guided process that captures what you're building and why—then hands off everything your coding agent needs to build it right.
+
+## The Problem
+
+AI coding tools are incredible at building fast. But the results often miss the mark. You describe what you want, the agent builds *something*, but it's not what you envisioned. The UI looks generic. Features get half-implemented. You spend as much time fixing and redirecting as you would have spent building.
+
+**The core issue:** we're asking coding agents to figure out what to build *and* build it simultaneously. Design decisions get made on the fly, buried in code, impossible to adjust without starting over. There's no spec. No shared understanding. No source of truth for what "done" looks like.
+
+## The Design OS Process
+
+Design OS powers a guided design and architecture process. You + AI, working together through structured steps:
+
+1. **Product Planning** — Define your vision, break down your roadmap, and model your data
+2. **Design System** — Choose colors, typography, and design your application shell
+3. **Section Design** — For each feature area: specify requirements, generate sample data, and design the screens
+4. **Export** — Generate a complete handoff package for implementation
+
+Each step is a conversation. The AI asks questions, you provide direction, and together you shape a product that matches your vision—before any implementation begins.
+
+---
+
+## Documentation & Installation
+
+Docs, installation, usage, & best practices 👉 [It's all here](https://buildermethods.com/design-os)
+
+---
+
+## Support, Training & Community
+
+For official support, training, and community as you use Design OS—for yourself or with your team, consider joining _Builder Methods Pro_. You'll get access to Brian Casel (the creator) for questions, a community of builders using Design OS, plus all Builder Methods workshops and training on AI-first development.
+
+👉 [Join Builder Methods Pro](https://buildermethods.com/pro)
+
+---
+
+## Follow updates & releases
+
+Read the [changelog](CHANGELOG.md)
+
+[Subscribe to be notified of major new releases of Design OS](https://buildermethods.com/design-os)
+
+---
+
+## Created by Brian Casel @ Builder Methods
+
+Created by Brian Casel, the creator of [Builder Methods](https://buildermethods.com), where Brian helps professional software developers and teams build with AI.
+
+Get Brian's free resources on building with AI:
+- [Builder Briefing newsletter](https://buildermethods.com)
+- [YouTube](https://youtube.com/@briancasel)