@builderos/create-agent-os 0.0.2

package/README.md

@@ -0,0 +1,39 @@
+# @builderos/create-agent-os
+
+The official scaffolding tool for **Agent OS** applications.
+
+Agent OS provides a structured workspace for building AI Agents, including:
+- **Control Center**: A local dashboard to manage your agent's mission, specs, and status.
+- **Design OS**: A pre-configured Design System (colors, typography, components) to ensure your agent's UI looks premium.
+- **Agent OS UI**: A component library optimized for building agentic interfaces.
+
+## Usage
+
+To create a new project, run:
+
+```bash
+npm create @builderos/agent-os@latest
+# or
+npx @builderos/create-agent-os@latest
+```
+
+Follow the prompts to name your project.
+
+## Workspace Structure
+
+The scaffolded workspace includes:
+- `app/`: Your main application (React + Vite).
+- `control-center/`: Local tools for managing the agent lifecycle.
+- `design-system/`: Your customizable design system documentation.
+- `agent-os/`: Markdown-based storage for specs, roadmap, and tasks.
+
+## Getting Started
+
+1. `cd <project-name>`
+2. `npm install`
+3. `npm run dev`
+
+This will start all services concurrently:
+- **Control Center**: http://localhost:3001
+- **Design OS**: http://localhost:3000
+- **Your App**: http://localhost:3002

package/bin/cli.js

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import prompts from 'prompts';
+import { red, green, bold, cyan } from 'kolorist';
+import { spawn } from 'node:child_process';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const cwd = process.cwd();
+
+async function init() {
+    const program = new Command();
+
+    program
+        .name('create-agent-os')
+        .description('Scaffold a new Agent OS application')
+        .argument('[project-directory]', 'Directory to create the application in')
+        .action(async (targetDir) => {
+            let result = { projectName: targetDir };
+
+            if (!targetDir) {
+                result = await prompts({
+                    type: 'text',
+                    name: 'projectName',
+                    message: 'Project name:',
+                    initial: 'my-agent-app'
+                });
+            }
+
+            if (!result.projectName) return;
+
+            const root = path.join(cwd, result.projectName);
+            console.log(`\n${bold('Creating Agent OS workspace in:')} ${green(root)}\n`);
+
+            if (fs.existsSync(root)) {
+                console.log(red(`Error: Directory ${result.projectName} already exists.`));
+                process.exit(1);
+            }
+
+            fs.mkdirSync(root, { recursive: true });
+
+            // 1. Scaffold App (Client)
+            console.log(cyan('1. Scaffolding Client App...'));
+            const appDir = path.join(root, 'app');
+            // Use npm create vite to scaffold the app inside the 'app' folder
+            // Pin version to avoid experimental prompts (e.g. rolldown) and use npx -y to avoid install prompt
+            const viteProcess = spawn('npx', ['-y', 'create-vite@5.2.0', 'app', '--template', 'react-ts'], {
+                stdio: 'inherit',
+                shell: true,
+                cwd: root // Run inside the project root so it creates 'app' there
+            });
+
+            viteProcess.on('close', async (code) => {
+                if (code !== 0) {
+                    console.error(red('Vite scaffolding failed.'));
+                    process.exit(code);
+                }
+
+                // 2. Copy Templates
+                console.log(cyan('\n2. Installing Control Center & Design OS...'));
+                const templateDir = path.resolve(__dirname, '../src/template');
+
+                // Copy Control Center
+                fs.cpSync(path.join(templateDir, 'control-center'), path.join(root, 'control-center'), { recursive: true });
+
+                // Copy Design System
+                fs.cpSync(path.join(templateDir, 'design'), path.join(root, 'design-system'), { recursive: true });
+
+                // Copy Agent OS Docs
+                fs.cpSync(path.join(templateDir, 'agent-os'), path.join(root, 'agent-os'), { recursive: true });
+
+                // Copy Agent OS UI Package (for local workspace support)
+                fs.cpSync(path.join(templateDir, 'agent-os-ui'), path.join(root, 'agent-os-ui'), { recursive: true });
+
+                // 3. Configure Workspace
+                console.log(cyan('\n3. Configuring Workspace...'));
+
+                // Root package.json
+                const rootPkg = JSON.parse(fs.readFileSync(path.join(templateDir, 'package.json'), 'utf-8'));
+                rootPkg.name = result.projectName;
+                fs.writeFileSync(path.join(root, 'package.json'), JSON.stringify(rootPkg, null, 2));
+
+                // App Package.json (Add dependencies)
+                const appPkgPath = path.join(appDir, 'package.json');
+                const appPkg = JSON.parse(fs.readFileSync(appPkgPath, 'utf-8'));
+
+                appPkg.dependencies = {
+                    ...appPkg.dependencies,
+                    "@antigravity/agent-os-ui": "*", // Use workspace version
+                    "lucide-react": "^0.469.0",
+                    "clsx": "^2.1.0",
+                    "tailwind-merge": "^2.2.0"
+                };
+
+                // Inject App Template (App.tsx, vite.config.ts) - we need to make sure these exist in template dir or just write them
+                // Re-using the logic from before, assuming App.tsx and vite.config.ts are in src/template top level?
+                // Wait, I updated template structure. I should check where App.tsx is.
+                // It was in src/template/App.tsx. I should move it to src/template/app-template? 
+                // Or just leave it at top level and selective copy.
+
+                // Let's assume they are still at src/template root for the app
+                const appTemplateDir = templateDir;
+                if (fs.existsSync(path.join(appTemplateDir, 'App.tsx'))) {
+                    fs.copyFileSync(path.join(appTemplateDir, 'App.tsx'), path.join(appDir, 'src/App.tsx'));
+                }
+                if (fs.existsSync(path.join(appTemplateDir, 'vite.config.ts'))) {
+                    fs.copyFileSync(path.join(appTemplateDir, 'vite.config.ts'), path.join(appDir, 'vite.config.ts'));
+                }
+
+
+                fs.writeFileSync(appPkgPath, JSON.stringify(appPkg, null, 2));
+
+
+                console.log(green(`\n\nAgent OS Workspace created successfully! 🚀\n`));
+                console.log(`Next steps:\n`);
+                console.log(`  cd ${result.projectName}`);
+                console.log(`  npm install`);
+                console.log(`  npm run dev\n`);
+                console.log(`This will start the App, Control Center, and Design OS concurrently.`);
+            });
+        });
+
+    program.parse();
+}
+
+init().catch((e) => {
+    console.error(e);
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "@builderos/create-agent-os",
+    "version": "0.0.2",
+    "description": "Scaffolding tool for Agent OS applications",
+    "type": "module",
+    "bin": {
+        "create-agent-os": "bin/cli.js"
+    },
+    "files": [
+        "bin",
+        "src"
+    ],
+    "scripts": {
+        "test": "echo \"Error: no test specified\" && exit 1"
+    },
+    "keywords": [
+        "agent-os",
+        "cli",
+        "scaffold",
+        "vite"
+    ],
+    "author": "Antigravity",
+    "license": "MIT",
+    "dependencies": {
+        "commander": "^11.1.0",
+        "fs-extra": "^11.2.0",
+        "kolorist": "^1.8.0",
+        "prompts": "^2.4.2"
+    },
+    "devDependencies": {
+        "@types/node": "^20.10.0",
+        "@types/react": "^18.2.0",
+        "@types/react-dom": "^18.2.0",
+        "@vitejs/plugin-react": "^4.2.1",
+        "react": "^18.3.1",
+        "react-dom": "^18.3.1",
+        "typescript": "^5.3.3",
+        "vite": "^5.0.10"
+    }
+}

package/src/template/App.tsx

@@ -0,0 +1,68 @@
+import { AgentShell, AgentSidebar, GuidanceCard, ThemeToggle } from '@antigravity/agent-os-ui';
+import '@antigravity/agent-os-ui/style.css';
+import { Home, Layers, Box } from 'lucide-react';
+import { useState } from 'react';
+
+function App() {
+    const [active, setActive] = useState('Home');
+
+    return (
+        <AgentShell
+            sidebar={
+                <AgentSidebar
+                    title="Agent App"
+                    version="v1.0"
+                    items={[
+                        {
+                            label: 'Home',
+                            icon: <Home size={18} />,
+                            active: active === 'Home',
+                            onClick: () => setActive('Home')
+                        },
+                        {
+                            label: 'Tasks',
+                            icon: <Layers size={18} />,
+                            active: active === 'Tasks',
+                            onClick: () => setActive('Tasks')
+                        }
+                    ]}
+                    footer={<ThemeToggle />}
+                />
+            }
+        >
+            <div className="p-12 max-w-4xl mx-auto font-sans">
+                <header className="mb-12">
+                    <h1 className="text-4xl font-bold text-stone-900 dark:text-stone-50 tracking-tight">Welcome to Agent OS</h1>
+                    <p className="text-xl text-stone-500 dark:text-stone-400 mt-3">Your rapid agent development environment is ready.</p>
+                </header>
+
+                <GuidanceCard
+                    phase="Phase 1: Setup"
+                    title="App Initialized"
+                    description="This boilerplate comes pre-configured with the Agent OS UI kit, routing, and theme management."
+                    prompt="Analyze this project structure and suggest the next feature implementation."
+                    className="mb-12"
+                />
+
+                <div className="grid grid-cols-1 md:grid-cols-2 gap-6">
+                    <div className="p-6 rounded-xl border border-stone-200 dark:border-stone-800 bg-white dark:bg-stone-950/50 shadow-sm">
+                        <Box className="mb-4 text-stone-400" size={24} />
+                        <h3 className="font-bold text-stone-900 dark:text-stone-100 mb-2">Component Library</h3>
+                        <p className="text-sm text-stone-500 dark:text-stone-400 leading-relaxed">
+                            Start building with pre-built components like <code>AgentShell</code>, <code>GuidanceCard</code>, and more.
+                        </p>
+                    </div>
+                    <div className="p-6 rounded-xl border border-stone-200 dark:border-stone-800 bg-white dark:bg-stone-950/50 shadow-sm">
+                        <Layers className="mb-4 text-stone-400" size={24} />
+                        <h3 className="font-bold text-stone-900 dark:text-stone-100 mb-2">Theme Ready</h3>
+                        <p className="text-sm text-stone-500 dark:text-stone-400 leading-relaxed">
+                            Dark mode is fully supported out of the box. Toggle it using the sidebar button.
+                        </p>
+                    </div>
+                </div>
+            </div>
+        </AgentShell>
+    )
+}
+
+export default App;

package/src/template/agent-os/commands/create-tasks/1-get-spec-requirements.md

@@ -0,0 +1,19 @@
+The FIRST STEP is to make sure you have ONE OR BOTH of these files to inform your tasks breakdown:
+- `agent-os/specs/[this-spec]/spec.md`
+- `agent-os/specs/[this-spec]/planning/requirements.md`
+
+IF you don't have ONE OR BOTH of those files in your current conversation context, then ask user to provide direction on where to you can find them by outputting the following request then wait for user's response:
+
+"I'll need a spec.md or requirements.md (or both) in order to build a tasks list.
+
+Please direct me to where I can find those.  If you haven't created them yet, you can run /shape-spec or /write-spec."
+
+## Display confirmation and next step
+
+Once you've confirmed you have the spec and/or requirements, output the following message (replace `[this-spec]` with the folder name for this spec)
+
+```
+✅ I have the spec and requirements `[spec and requirements path]`.
+
+NEXT STEP 👉 Run the command, 2-create-tasks-list.md
+```

package/src/template/agent-os/commands/create-tasks/2-create-tasks-list.md

@@ -0,0 +1,234 @@
+Now that you have the spec.md AND/OR requirements.md, please break those down into an actionable tasks list with strategic grouping and ordering, by following these instructions:
+
+# Task List Creation
+
+## Core Responsibilities
+
+1. **Analyze spec and requirements**: Read and analyze the spec.md and/or requirements.md to inform the tasks list you will create.
+2. **Plan task execution order**: Break the requirements into a list of tasks in an order that takes their dependencies into account.
+3. **Group tasks by specialization**: Group tasks that require the same skill or stack specialization together (backend, api, ui design, etc.)
+4. **Create Tasks list**: Create the markdown tasks list broken into groups with sub-tasks.
+
+## Workflow
+
+### Step 1: Analyze Spec & Requirements
+
+Read each of these files (whichever are available) and analyze them to understand the requirements for this feature implementation:
+- `agent-os/specs/[this-spec]/spec.md`
+- `agent-os/specs/[this-spec]/planning/requirements.md`
+
+Use your learnings to inform the tasks list and groupings you will create in the next step.
+
+
+### Step 2: Create Tasks Breakdown
+
+Generate `agent-os/specs/[current-spec]/tasks.md`.
+
+**Important**: The exact tasks, task groups, and organization will vary based on the feature's specific requirements. The following is an example format - adapt the content of the tasks list to match what THIS feature actually needs.
+
+```markdown
+# Task Breakdown: [Feature Name]
+
+## Overview
+Total Tasks: [count]
+
+## Task List
+
+### Database Layer
+
+#### Task Group 1: Data Models and Migrations
+**Dependencies:** None
+
+- [ ] 1.0 Complete database layer
+  - [ ] 1.1 Write 2-8 focused tests for [Model] functionality
+    - Limit to 2-8 highly focused tests maximum
+    - Test only critical model behaviors (e.g., primary validation, key association, core method)
+    - Skip exhaustive coverage of all methods and edge cases
+  - [ ] 1.2 Create [Model] with validations
+    - Fields: [list]
+    - Validations: [list]
+    - Reuse pattern from: [existing model if applicable]
+  - [ ] 1.3 Create migration for [table]
+    - Add indexes for: [fields]
+    - Foreign keys: [relationships]
+  - [ ] 1.4 Set up associations
+    - [Model] has_many [related]
+    - [Model] belongs_to [parent]
+  - [ ] 1.5 Ensure database layer tests pass
+    - Run ONLY the 2-8 tests written in 1.1
+    - Verify migrations run successfully
+    - Do NOT run the entire test suite at this stage
+
+**Acceptance Criteria:**
+- The 2-8 tests written in 1.1 pass
+- Models pass validation tests
+- Migrations run successfully
+- Associations work correctly
+
+### API Layer
+
+#### Task Group 2: API Endpoints
+**Dependencies:** Task Group 1
+
+- [ ] 2.0 Complete API layer
+  - [ ] 2.1 Write 2-8 focused tests for API endpoints
+    - Limit to 2-8 highly focused tests maximum
+    - Test only critical controller actions (e.g., primary CRUD operation, auth check, key error case)
+    - Skip exhaustive testing of all actions and scenarios
+  - [ ] 2.2 Create [resource] controller
+    - Actions: index, show, create, update, destroy
+    - Follow pattern from: [existing controller]
+  - [ ] 2.3 Implement authentication/authorization
+    - Use existing auth pattern
+    - Add permission checks
+  - [ ] 2.4 Add API response formatting
+    - JSON responses
+    - Error handling
+    - Status codes
+  - [ ] 2.5 Ensure API layer tests pass
+    - Run ONLY the 2-8 tests written in 2.1
+    - Verify critical CRUD operations work
+    - Do NOT run the entire test suite at this stage
+
+**Acceptance Criteria:**
+- The 2-8 tests written in 2.1 pass
+- All CRUD operations work
+- Proper authorization enforced
+- Consistent response format
+
+### Frontend Components
+
+#### Task Group 3: UI Design
+**Dependencies:** Task Group 2
+
+- [ ] 3.0 Complete UI components
+  - [ ] 3.1 Write 2-8 focused tests for UI components
+    - Limit to 2-8 highly focused tests maximum
+    - Test only critical component behaviors (e.g., primary user interaction, key form submission, main rendering case)
+    - Skip exhaustive testing of all component states and interactions
+  - [ ] 3.2 Create [Component] component
+    - Reuse: [existing component] as base
+    - Props: [list]
+    - State: [list]
+  - [ ] 3.3 Implement [Feature] form
+    - Fields: [list]
+    - Validation: client-side
+    - Submit handling
+  - [ ] 3.4 Build [View] page
+    - Layout: [description]
+    - Components: [list]
+    - Match mockup: `planning/visuals/[file]`
+  - [ ] 3.5 Apply base styles
+    - Follow existing design system
+    - Use variables from: [style file]
+  - [ ] 3.6 Implement responsive design
+    - Mobile: 320px - 768px
+    - Tablet: 768px - 1024px
+    - Desktop: 1024px+
+  - [ ] 3.7 Add interactions and animations
+    - Hover states
+    - Transitions
+    - Loading states
+  - [ ] 3.8 Ensure UI component tests pass
+    - Run ONLY the 2-8 tests written in 3.1
+    - Verify critical component behaviors work
+    - Do NOT run the entire test suite at this stage
+
+**Acceptance Criteria:**
+- The 2-8 tests written in 3.1 pass
+- Components render correctly
+- Forms validate and submit
+- Matches visual design
+
+### Testing
+
+#### Task Group 4: Test Review & Gap Analysis
+**Dependencies:** Task Groups 1-3
+
+- [ ] 4.0 Review existing tests and fill critical gaps only
+  - [ ] 4.1 Review tests from Task Groups 1-3
+    - Review the 2-8 tests written by database-engineer (Task 1.1)
+    - Review the 2-8 tests written by api-engineer (Task 2.1)
+    - Review the 2-8 tests written by ui-designer (Task 3.1)
+    - Total existing tests: approximately 6-24 tests
+  - [ ] 4.2 Analyze test coverage gaps for THIS feature only
+    - Identify critical user workflows that lack test coverage
+    - Focus ONLY on gaps related to this spec's feature requirements
+    - Do NOT assess entire application test coverage
+    - Prioritize end-to-end workflows over unit test gaps
+  - [ ] 4.3 Write up to 10 additional strategic tests maximum
+    - Add maximum of 10 new tests to fill identified critical gaps
+    - Focus on integration points and end-to-end workflows
+    - Do NOT write comprehensive coverage for all scenarios
+    - Skip edge cases, performance tests, and accessibility tests unless business-critical
+  - [ ] 4.4 Run feature-specific tests only
+    - Run ONLY tests related to this spec's feature (tests from 1.1, 2.1, 3.1, and 4.3)
+    - Expected total: approximately 16-34 tests maximum
+    - Do NOT run the entire application test suite
+    - Verify critical workflows pass
+
+**Acceptance Criteria:**
+- All feature-specific tests pass (approximately 16-34 tests total)
+- Critical user workflows for this feature are covered
+- No more than 10 additional tests added when filling in testing gaps
+- Testing focused exclusively on this spec's feature requirements
+
+## Execution Order
+
+Recommended implementation sequence:
+1. Database Layer (Task Group 1)
+2. API Layer (Task Group 2)
+3. Frontend Design (Task Group 3)
+4. Test Review & Gap Analysis (Task Group 4)
+```
+
+**Note**: Adapt this structure based on the actual feature requirements. Some features may need:
+- Different task groups (e.g., email notifications, payment processing, data migration)
+- Different execution order based on dependencies
+- More or fewer sub-tasks per group
+
+## Important Constraints
+
+- **Create tasks that are specific and verifiable**
+- **Group related tasks:** For example, group back-end engineering tasks together and front-end UI tasks together.
+- **Limit test writing during development**:
+  - Each task group (1-3) should write 2-8 focused tests maximum
+  - Tests should cover only critical behaviors, not exhaustive coverage
+  - Test verification should run ONLY the newly written tests, not the entire suite
+  - If there is a dedicated test coverage group for filling in gaps in test coverage, this group should add only a maximum of 10 additional tests IF NECESSARY to fill critical gaps
+- **Use a focused test-driven approach** where each task group starts with writing 2-8 tests (x.1 sub-task) and ends with running ONLY those tests (final sub-task)
+- **Include acceptance criteria** for each task group
+- **Reference visual assets** if visuals are available
+
+
+## Display confirmation and next step
+
+Display the following message to the user:
+
+```
+The tasks list has created at `agent-os/specs/[this-spec]/tasks.md`.
+
+Review it closely to make sure it all looks good.
+
+NEXT STEP 👉 Run `/implement-tasks` (simple, effective) or `/orchestrate-tasks` (advanced, powerful) to start building!
+```
+
+## User Standards & Preferences Compliance
+
+IMPORTANT: Ensure that the tasks list is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files:
+
+@agent-os/standards/backend/api.md
+@agent-os/standards/backend/migrations.md
+@agent-os/standards/backend/models.md
+@agent-os/standards/backend/queries.md
+@agent-os/standards/frontend/accessibility.md
+@agent-os/standards/frontend/components.md
+@agent-os/standards/frontend/css.md
+@agent-os/standards/frontend/responsive.md
+@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
+@agent-os/standards/testing/test-writing.md