@builderos/create-agent-os 0.0.2

package/src/template/agent-os/commands/plan-product/4-create-tech-stack.md

@@ -0,0 +1,46 @@
+The final part of our product planning process is to document this product's tech stack in `agent-os/product/tech-stack.md`.  Follow these instructions to do so:
+
+Create `agent-os/product/tech-stack.md` with a list of all tech stack choices that cover all aspects of this product's codebase.
+
+### Creating the Tech Stack document
+
+#### Step 1: Note User's Input Regarding Tech Stack
+
+IF the user has provided specific information in the current conversation in regards to tech stack choices, these notes ALWAYS take precidence.  These must be reflected in your final `tech-stack.md` document that you will create.
+
+#### Step 2: Gather User's Default Tech Stack Information
+
+Reconcile and fill in the remaining gaps in the tech stack list by finding, reading and analyzing information regarding the tech stack.  Find this information in the following sources, in this order:
+
+1. If user has provided their default tech stack under "User Standards & Preferences Compliance", READ and analyze this document.
+2. If the current project has any of these files, read them to find information regarding tech stack choices for this codebase:
+  - `claude.md`
+  - `agents.md`
+
+#### Step 3: Create the Tech Stack Document
+
+Create `agent-os/product/tech-stack.md` and populate it with the final list of all technical stack choices, reconciled between the information the user has provided to you and the information found in provided sources.
+
+
+## Display confirmation and next step
+
+Once you've created tech-stack.md, output the following message:
+
+```
+✅ I have documented the product's tech stack at `agent-os/product/tech-stack.md`.
+
+Review it to ensure all of the tech stack details are correct for this product.
+
+You're ready to start planning a feature spec! You can do so by running `shape-spec.md` or `write-spec.md`.
+```
+
+## User Standards & Preferences Compliance
+
+The user may provide information regarding their tech stack, which should take precidence when documenting the product's tech stack.  To fill in any gaps, find the user's usual tech stack information as documented in any of these files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md

package/src/template/agent-os/commands/plan-product/plan-product.md

@@ -0,0 +1,241 @@
+You are helping to plan and document the mission, roadmap and tech stack for the current product.  This will include:
+
+- **Gathering Information**: The user's product vision, user personas, problems and key features
+- **Mission Document**: Take what you've gathered and create a concise mission document
+- **Roadmap**: Create a phased development plan with prioritized features
+- **Tech stack**: Establish the technical stack used for all aspects of this product's codebase
+
+Carefully read and execute the instructions in the following files IN SEQUENCE, following their numbered file names.  Only proceed to the next numbered instruction file once the previous numbered instruction has been executed.
+
+Instructions to follow in sequence:
+
+# PHASE 1: Product Concept
+
+This begins a multi-step process for planning and documenting the mission and roadmap for the current product.
+
+The FIRST STEP is to confirm the product details by following these instructions:
+
+Collect comprehensive product information from the user:
+
+```bash
+# Check if product folder already exists
+if [ -d "agent-os/product" ]; then
+    echo "Product documentation already exists. Review existing files or start fresh?"
+    # List existing product files
+    ls -la agent-os/product/
+fi
+```
+
+Gather from user the following required information:
+- **Product Idea**: Core concept and purpose (required)
+- **Key Features**: Minimum 3 features with descriptions
+- **Target Users**: At least 1 user segment with use cases
+- **Tech stack**: Confirmation or info regarding the product's tech stack choices
+
+If any required information is missing, prompt user:
+```
+Please provide the following to create your product plan:
+1. Main idea for the product
+2. List of key features (minimum 3)
+3. Target users and use cases (minimum 1)
+4. Will this product use your usual tech stack choices or deviate in any way?
+```
+
+
+Then WAIT for me to give you specific instructions on how to use the information you've gathered to create the mission and roadmap.
+
+
+## User Standards & Preferences Compliance
+
+When planning the product's tech stack, mission statement and roadmap, use the user's standards and preferences for context and baseline assumptions, as documented in these files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md
+
+# PHASE 2: Create Mission
+
+Now that you've gathered information about this product, use that info to create the mission document in `agent-os/product/mission.md` by following these instructions:
+
+Create `agent-os/product/mission.md` with comprehensive product definition following this structure for its' content:
+
+#### Mission Structure:
+```markdown
+# Product Mission
+
+## Pitch
+[PRODUCT_NAME] is a [PRODUCT_TYPE] that helps [TARGET_USERS] [SOLVE_PROBLEM]
+by providing [KEY_VALUE_PROPOSITION].
+
+## Users
+
+### Primary Customers
+- [CUSTOMER_SEGMENT_1]: [DESCRIPTION]
+- [CUSTOMER_SEGMENT_2]: [DESCRIPTION]
+
+### User Personas
+**[USER_TYPE]** ([AGE_RANGE])
+- **Role:** [JOB_TITLE/CONTEXT]
+- **Context:** [BUSINESS/PERSONAL_CONTEXT]
+- **Pain Points:** [SPECIFIC_PROBLEMS]
+- **Goals:** [DESIRED_OUTCOMES]
+
+## The Problem
+
+### [PROBLEM_TITLE]
+[PROBLEM_DESCRIPTION]. [QUANTIFIABLE_IMPACT].
+
+**Our Solution:** [SOLUTION_APPROACH]
+
+## Differentiators
+
+### [DIFFERENTIATOR_TITLE]
+Unlike [COMPETITOR/ALTERNATIVE], we provide [SPECIFIC_ADVANTAGE].
+This results in [MEASURABLE_BENEFIT].
+
+## Key Features
+
+### Core Features
+- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
+
+### Collaboration Features
+- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
+
+### Advanced Features
+- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
+```
+
+#### Important Constraints
+
+- **Focus on user benefits** in feature descriptions, not technical details
+- **Keep it concise** and easy for users to scan and get the more important concepts quickly
+
+
+
+## User Standards & Preferences Compliance
+
+IMPORTANT: Ensure the product mission is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md
+
+# PHASE 3: Create Roadmap
+
+Now that you've created this product's mission.md, use that to guide your creation of the roadmap in `agent-os/product/roadmap.md` by following these instructions:
+
+Generate `agent-os/product/roadmap.md` with an ordered feature checklist:
+
+Do not include any tasks for initializing a new codebase or bootstrapping a new application. Assume the user is already inside the project's codebase and has a bare-bones application initialized.
+
+#### Creating the Roadmap:
+
+1. **Review the Mission** - Read `agent-os/product/mission.md` to understand the product's goals, target users, and success criteria.
+
+2. **Identify Features** - Based on the mission, determine the list of concrete features needed to achieve the product vision.
+
+3. **Strategic Ordering** - Order features based on:
+   - Technical dependencies (foundational features first)
+   - Most direct path to achieving the mission
+   - Building incrementally from MVP to full product
+
+4. **Create the Roadmap** - Use the structure below as your template. Replace all bracketed placeholders (e.g., `[FEATURE_NAME]`, `[DESCRIPTION]`, `[EFFORT]`) with real content that you create based on the mission.
+
+#### Roadmap Structure:
+```markdown
+# Product Roadmap
+
+1. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+2. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+3. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+4. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+5. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+6. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+7. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+8. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+
+> Notes
+> - Order items by technical dependencies and product architecture
+> - Each item should represent an end-to-end (frontend + backend) functional and testable feature
+```
+
+Effort scale:
+- `XS`: 1 day
+- `S`: 2-3 days
+- `M`: 1 week
+- `L`: 2 weeks
+- `XL`: 3+ weeks
+
+#### Important Constraints
+
+- **Make roadmap actionable** - include effort estimates and dependencies
+- **Priorities guided by mission** - When deciding on order, aim for the most direct path to achieving the mission as documented in mission.md
+- **Ensure phases are achievable** - start with MVP, build incrementally
+
+
+
+## User Standards & Preferences Compliance
+
+IMPORTANT: Ensure the product roadmap is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md
+
+# PHASE 4: Create Tech Stack
+
+The final part of our product planning process is to document this product's tech stack in `agent-os/product/tech-stack.md`.  Follow these instructions to do so:
+
+Create `agent-os/product/tech-stack.md` with a list of all tech stack choices that cover all aspects of this product's codebase.
+
+### Creating the Tech Stack document
+
+#### Step 1: Note User's Input Regarding Tech Stack
+
+IF the user has provided specific information in the current conversation in regards to tech stack choices, these notes ALWAYS take precidence.  These must be reflected in your final `tech-stack.md` document that you will create.
+
+#### Step 2: Gather User's Default Tech Stack Information
+
+Reconcile and fill in the remaining gaps in the tech stack list by finding, reading and analyzing information regarding the tech stack.  Find this information in the following sources, in this order:
+
+1. If user has provided their default tech stack under "User Standards & Preferences Compliance", READ and analyze this document.
+2. If the current project has any of these files, read them to find information regarding tech stack choices for this codebase:
+  - `claude.md`
+  - `agents.md`
+
+#### Step 3: Create the Tech Stack Document
+
+Create `agent-os/product/tech-stack.md` and populate it with the final list of all technical stack choices, reconciled between the information the user has provided to you and the information found in provided sources.
+
+
+## Display confirmation and next step
+
+Once you've created tech-stack.md, output the following message:
+
+```
+✅ I have documented the product's tech stack at `agent-os/product/tech-stack.md`.
+
+Review it to ensure all of the tech stack details are correct for this product.
+
+You're ready to start planning a feature spec! You can do so by running `shape-spec.md` or `write-spec.md`.
+```
+
+## User Standards & Preferences Compliance
+
+The user may provide information regarding their tech stack, which should take precidence when documenting the product's tech stack.  To fill in any gaps, find the user's usual tech stack information as documented in any of these files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md

package/src/template/agent-os/commands/sample-data/sample-data.md

@@ -0,0 +1,51 @@
+# COMMAND: Generate Sample Data
+
+## Goal
+Create realistic sample data (`data.json`) for a specific product section to populate the UI.
+
+## Prerequisites
+- `design/product/sections/[section-id]/spec.md` should exist (to understand what data is needed).
+- You must know the **Section Title** and **Section ID**.
+
+## Instructions
+
+### Step 1: Analyze Spec
+Read `design/product/sections/[section-id]/spec.md` to identify the entities and data structures required by the UI.
+
+### Step 2: Create Data File
+Create `design/product/sections/[section-id]/data.json`.
+
+Format:
+```json
+{
+  "_meta": {
+    "models": {
+      "ModelName": "Description of the model",
+      "AnotherModel": "Description..."
+    },
+    "relationships": [
+      "ModelName has many AnotherModel",
+      "AnotherModel belongs to ModelName"
+    ]
+  },
+  "modelCollectionName": [
+    {
+      "id": "1",
+      "name": "Sample Item",
+      "status": "active",
+      "createdAt": "2023-10-27T10:00:00Z"
+    }
+  ],
+  "singleObject": {
+    "key": "value"
+  }
+}
+```
+
+**Requirements:**
+- Generate at least 3-5 items for lists.
+- Use realistic, semantic data (not "Item 1", "Item 2").
+- Ensure dates are ISO 8601 strings.
+
+### Step 3: Verification
+- Output: "Sample data for '[Section Title]' generated! You can now view it in Design OS."

package/src/template/agent-os/commands/scaffold-implementation/scaffold-implementation.md

@@ -0,0 +1,36 @@
+# COMMAND: Scaffold Implementation
+
+## Goal
+Initialize the production Next.js application (`app/facilitron`) and prepare it for feature implementation.
+
+## Steps
+
+### 1. Initialize Next.js App
+Run the following command to create the app if it doesn't exist:
+```bash
+npx create-next-app@latest app/facilitron \
+  --typescript \
+  --tailwind \
+  --eslint \
+  --app \
+  --src-dir \
+  --import-alias "@/*" \
+  --use-npm \
+  --no-git # We are already in a git repo
+```
+
+### 2. Install Core Dependencies
+Install the standard UI libraries used in Design OS:
+```bash
+cd app/facilitron
+npm install lucide-react clsx tailwind-merge class-variance-authority @radix-ui/react-slot
+```
+
+### 3. Integrate Design System
+- Copy `product-plan/design-system/colors.json` -> `app/facilitron/src/styles/colors.json` (or verify path)
+- Update `app/facilitron/tailwind.config.ts` (or .js) to import and use these colors.
+- Copy `design/src/lib/utils.ts` -> `app/facilitron/src/lib/utils.ts` (cn helper)
+
+### 4. Verification
+- Start the dev server: `npm run dev` (on a new port, e.g., 3002).
+- Verify basic page load.

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

@@ -0,0 +1,21 @@
+# COMMAND: Capture Design Screenshots
+
+## Goal
+Capture and save a screenshot of the implemented screen design for documentation.
+
+## Prerequisites
+- The screen design must be implemented and visible in Design OS.
+- You must know the **Section Title** and **Section ID**.
+
+## Instructions
+
+### Step 1: Navigate and Capture
+- Use the Browser Tool to navigate to the specific screen design URL in Design OS:
+  `http://localhost:3000/sections/[section-id]/screen-designs/[ComponentName]`
+- Take a screenshot of the viewport (excluding the browser window chrome if possible, or just the main content area).
+
+### Step 2: Save Screenshot
+- Save the screenshot to: `design/product/sections/[section-id]/[component-name-kebab-case].png`.
+
+### Step 3: Verification
+- Output: "Screenshot saved to [path]! It will now appear in the Section Overview."

package/src/template/agent-os/commands/shape-spec/1-initialize-spec.md

@@ -0,0 +1,95 @@
+The FIRST STEP is to initialize the spec by following these instructions:
+
+# Spec Initialization
+
+## Core Responsibilities
+
+1. **Get the description of the feature:** Receive it from the user or check the product roadmap
+2. **Initialize Spec Structure**: Create the spec folder with date prefix
+3. **Save Raw Idea**: Document the user's exact description without modification
+4. **Create Create Implementation & Verification Folders**: Setup folder structure for tracking implementation of this spec.
+5. **Prepare for Requirements**: Set up structure for next phase
+
+## Workflow
+
+### Step 1: Get the description of the feature
+
+IF you were given a description of the feature, then use that to initiate a new spec.
+
+OTHERWISE follow these steps to get the description:
+
+1. Check `@agent-os/product/roadmap.md` to find the next feature in the roadmap.
+2. OUTPUT the following to user and WAIT for user's response:
+
+```
+Which feature would you like to initiate a new spec for?
+
+- The roadmap shows [feature description] is next. Go with that?
+- Or provide a description of a feature you'd like to initiate a spec for.
+```
+
+**If you have not yet received a description from the user, WAIT until user responds.**
+
+### Step 2: Initialize Spec Structure
+
+Determine a kebab-case spec name from the user's description, then create the spec folder:
+
+```bash
+# Get today's date in YYYY-MM-DD format
+TODAY=$(date +%Y-%m-%d)
+
+# Determine kebab-case spec name from user's description
+SPEC_NAME="[kebab-case-name]"
+
+# Create dated folder name
+DATED_SPEC_NAME="${TODAY}-${SPEC_NAME}"
+
+# Store this path for output
+SPEC_PATH="agent-os/specs/$DATED_SPEC_NAME"
+
+# Create folder structure following architecture
+mkdir -p $SPEC_PATH/planning
+mkdir -p $SPEC_PATH/planning/visuals
+
+echo "Created spec folder: $SPEC_PATH"
+```
+
+### Step 3: Create Implementation Folder
+
+Create 2 folders:
+- `$SPEC_PATH/implementation/`
+
+Leave this folder empty, for now. Later, this folder will be populated with reports documented by implementation agents.
+
+### Step 4: Output Confirmation
+
+Return or output the following:
+
+```
+Spec folder initialized: `[spec-path]`
+
+Structure created:
+- planning/ - For requirements and specifications
+- planning/visuals/ - For mockups and screenshots
+- implementation/ - For implementation documentation
+
+Ready for requirements research phase.
+```
+
+## Important Constraints
+
+- Always use dated folder names (YYYY-MM-DD-spec-name)
+- Pass the exact spec path back to the orchestrator
+- Follow folder structure exactly
+- Implementation folder should be empty, for now
+
+
+## Display confirmation and next step
+
+Once you've initialized the spec folder, output the following message (replace `[this-spec]` with the folder name for this spec)
+
+```
+✅ I have initialized the spec folder at `agent-os/specs/[this-spec]`.
+
+NEXT STEP 👉 Run the command, 2-research-spec.md
+```