@ridit/milo 0.1.0

package/src/skills/colors.ts

@@ -0,0 +1,72 @@
+export const COLORS_SKILL = `
+## Skill: Colors & Dark Mode
+
+### Color System
+- Use HSL for manipulation — easier to reason about:
+\`\`\`css
+--color-primary: hsl(220, 90%, 56%);
+--color-primary-light: hsl(220, 90%, 70%);
+--color-primary-dark: hsl(220, 90%, 40%);
+\`\`\`
+- Semantic naming — never name by value:
+\`\`\`css
+/* ❌ wrong */
+--color-blue: #3b82f6;
+--color-red: #ef4444;
+
+/* ✅ correct */
+--color-primary: #3b82f6;
+--color-error: #ef4444;
+--color-success: #22c55e;
+--color-warning: #f59e0b;
+--color-info: #06b6d4;
+\`\`\`
+
+### Palette Structure
+- 1 primary (brand color)
+- 1 secondary (accent)
+- Neutrals (gray scale, 9-11 steps)
+- Semantic (success, error, warning, info)
+- Never use pure colors — desaturate slightly:
+\`\`\`
+❌ #ff0000 (pure red)
+✅ #ef4444 (slightly desaturated)
+\`\`\`
+
+### Contrast
+- WCAG AA minimum:
+  - Normal text: 4.5:1
+  - Large text (18px+ or 14px+ bold): 3:1
+  - UI components (borders, icons): 3:1
+- Tools: use oklch() for perceptually uniform colors
+
+### Dark Mode
+- Don't just invert — rethink:
+\`\`\`css
+:root {
+  --bg: #ffffff;
+  --bg-subtle: #f9fafb;
+  --text: #111827;
+  --text-muted: #6b7280;
+  --border: #e5e7eb;
+}
+
+[data-theme="dark"] {
+  --bg: #0f0f0f;
+  --bg-subtle: #1a1a1a;
+  --text: #f9fafb;
+  --text-muted: #9ca3af;
+  --border: #2a2a2a;
+}
+\`\`\`
+- Dark mode: use #0f0f0f or #121212 not pure black
+- Reduce saturation in dark mode — vivid colors look harsh
+- Elevate surfaces with subtle lightness, not shadows:
+\`\`\`
+Layer 0 (base):    #0f0f0f
+Layer 1 (cards):   #1a1a1a
+Layer 2 (modals):  #242424
+Layer 3 (tooltip): #2e2e2e
+\`\`\`
+- Never use color as the only differentiator — always pair with icon/label
+`;

package/src/skills/database.ts

@@ -0,0 +1,55 @@
+export const DATABASE_SKILL = `
+## Skill: Database
+
+### Queries
+- Always use parameterized queries — never concatenate SQL:
+\`\`\`ts
+// ❌ wrong
+db.query(\`SELECT * FROM users WHERE id = \${userId}\`);
+
+// ✅ correct
+db.query('SELECT * FROM users WHERE id = $1', [userId]);
+
+// ✅ with ORM (Drizzle)
+db.select().from(users).where(eq(users.id, userId));
+\`\`\`
+- Never SELECT * in production — specify columns:
+\`\`\`ts
+db.select({ id: users.id, name: users.name, email: users.email }).from(users);
+\`\`\`
+
+### Schema Design
+- Always have a primary key
+- Use \`created_at\` and \`updated_at\` timestamps on every table
+- Soft delete with \`deleted_at\` when data matters:
+\`\`\`ts
+const users = pgTable('users', {
+  id: uuid('id').primaryKey().defaultRandom(),
+  name: text('name').notNull(),
+  email: text('email').notNull().unique(),
+  createdAt: timestamp('created_at').defaultNow().notNull(),
+  updatedAt: timestamp('updated_at').defaultNow().notNull(),
+  deletedAt: timestamp('deleted_at'),
+});
+\`\`\`
+- Index foreign keys and search columns:
+\`\`\`sql
+CREATE INDEX idx_posts_user_id ON posts(user_id);
+CREATE INDEX idx_users_email ON users(email);
+\`\`\`
+
+### Transactions
+- Use transactions for atomic operations:
+\`\`\`ts
+await db.transaction(async (tx) => {
+  const [order] = await tx.insert(orders).values(orderData).returning();
+  await tx.insert(orderItems).values(items.map(i => ({ ...i, orderId: order.id })));
+  await tx.update(inventory).set({ stock: sql\`stock - 1\` }).where(eq(inventory.id, item.id));
+});
+\`\`\`
+
+### Migrations
+- Never alter production schema directly — always use migrations
+- Make migrations reversible (up + down)
+- Test migrations on staging before production
+`;

package/src/skills/docker.ts

@@ -0,0 +1,74 @@
+export const DOCKER_SKILL = `
+## Skill: Docker
+
+### Dockerfile Best Practices
+- Multi-stage builds to keep images small:
+\`\`\`dockerfile
+# Build stage
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+# Production stage
+FROM node:20-alpine AS runner
+WORKDIR /app
+RUN addgroup -S app && adduser -S app -G app
+COPY --from=builder /app/dist ./dist
+COPY --from=builder /app/node_modules ./node_modules
+USER app
+EXPOSE 3000
+CMD ["node", "dist/index.js"]
+\`\`\`
+- Never use \`latest\` tag — pin versions: \`node:20.11-alpine\`
+- Never run as root — always create and use a non-root user
+- Use .dockerignore:
+\`\`\`
+node_modules
+.env
+.git
+dist
+*.log
+\`\`\`
+
+### Docker Compose
+\`\`\`yaml
+services:
+  app:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL=\${DATABASE_URL}
+    depends_on:
+      db:
+        condition: service_healthy
+
+  db:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_DB: myapp
+      POSTGRES_USER: \${DB_USER}
+      POSTGRES_PASSWORD: \${DB_PASSWORD}
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U \${DB_USER}"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  postgres_data:
+\`\`\`
+
+### Rules
+- One process per container
+- Use COPY over ADD unless extracting tarballs
+- Set WORKDIR explicitly — never rely on default
+- Use ARG for build-time, ENV for runtime variables
+- Health checks on all services
+`;

package/src/skills/frontend.ts

@@ -0,0 +1,70 @@
+export const FRONTEND_SKILL = `
+## Skill: Frontend Development
+
+### Component Architecture
+- Use functional components with TypeScript — never class components
+- Always type props with explicit interfaces:
+\`\`\`tsx
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean;
+  variant?: 'primary' | 'secondary';
+}
+
+const Button = ({ label, onClick, disabled = false, variant = 'primary' }: ButtonProps) => {
+  return <button onClick={onClick} disabled={disabled} className={variant}>{label}</button>;
+};
+\`\`\`
+- Use named exports for components, default exports for pages/routes
+- Keep components under 150 lines — split if larger
+- One component per file
+
+### Hooks
+- Extract reusable logic into custom hooks prefixed with \`use\`:
+\`\`\`ts
+function useDebounce<T>(value: T, delay: number): T {
+  const [debounced, setDebounced] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setDebounced(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+  return debounced;
+}
+\`\`\`
+- Never put business logic directly in components — use hooks
+- Keep useEffect dependencies complete — never suppress exhaustive-deps
+
+### State Management
+- Local state: useState / useReducer
+- Server state: React Query / SWR
+- Global state: Zustand or Context (avoid Redux unless needed)
+- Never mutate state directly:
+\`\`\`ts
+// ❌ wrong
+state.items.push(newItem);
+
+// ✅ correct
+setItems(prev => [...prev, newItem]);
+\`\`\`
+
+### Performance
+- Memoize expensive computations with useMemo
+- Memoize callbacks passed to children with useCallback
+- Wrap pure components with React.memo
+- Lazy load heavy components:
+\`\`\`ts
+const HeavyChart = React.lazy(() => import('./HeavyChart'));
+\`\`\`
+
+### TypeScript
+- No \`any\` — use \`unknown\` and narrow down
+- Use discriminated unions for complex state:
+\`\`\`ts
+type State =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: User[] }
+  | { status: 'error'; error: string };
+\`\`\`
+`;

package/src/skills/git.ts

@@ -0,0 +1,52 @@
+export const GIT_SKILL = `
+## Skill: Git
+
+### Commit Conventions
+- Use conventional commits:
+\`\`\`
+feat: add user authentication
+fix: resolve login redirect loop
+chore: update dependencies
+refactor: extract auth middleware
+docs: add API documentation
+test: add unit tests for UserService
+style: format with prettier
+\`\`\`
+- Imperative mood: "add feature" not "added feature"
+- Keep subject under 72 characters
+- Reference issues: \`fix: resolve login bug (#123)\`
+
+### Branching
+\`\`\`
+main          → production
+feat/auth     → new features
+fix/login     → bug fixes
+chore/deps    → maintenance
+release/1.2.0 → release prep
+\`\`\`
+
+### Best Practices
+- Small, focused commits — one logical change per commit
+- Never commit: .env files, secrets, node_modules, build artifacts
+- Always pull before pushing on shared branches
+- Squash WIP commits before merging:
+\`\`\`bash
+git rebase -i HEAD~3
+\`\`\`
+- Tag releases with semantic versioning:
+\`\`\`bash
+git tag -a v1.2.0 -m "Release v1.2.0"
+git push origin v1.2.0
+\`\`\`
+
+### .gitignore essentials
+\`\`\`
+node_modules/
+.env
+.env.local
+dist/
+build/
+*.log
+.DS_Store
+\`\`\`
+`;

package/src/skills/testing.ts

@@ -0,0 +1,73 @@
+export const TESTING_SKILL = `
+## Skill: Testing
+
+### Unit Tests
+- Test behavior, not implementation:
+\`\`\`ts
+// ❌ wrong — testing implementation
+expect(component.state.isLoading).toBe(true);
+
+// ✅ correct — testing behavior
+expect(screen.getByRole('progressbar')).toBeInTheDocument();
+\`\`\`
+- Descriptive test names:
+\`\`\`ts
+describe('UserService', () => {
+  it('should throw 404 when user not found', async () => {});
+  it('should hash password before saving', async () => {});
+  it('should return user without password field', async () => {});
+});
+\`\`\`
+- Always test error paths:
+\`\`\`ts
+it('should return error when email already exists', async () => {
+  await userService.create({ email: 'test@test.com' });
+  await expect(userService.create({ email: 'test@test.com' })).rejects.toThrow('Email already exists');
+});
+\`\`\`
+
+### Mocking
+- Mock external dependencies in unit tests:
+\`\`\`ts
+jest.mock('../db', () => ({
+  users: { findOne: jest.fn() }
+}));
+
+it('should return null when user not found', async () => {
+  mockDb.users.findOne.mockResolvedValue(null);
+  const result = await userService.findById('123');
+  expect(result).toBeNull();
+});
+\`\`\`
+
+### Test Data
+- Use factories, not hardcoded values:
+\`\`\`ts
+const createUser = (overrides = {}) => ({
+  id: crypto.randomUUID(),
+  name: 'Test User',
+  email: 'test@example.com',
+  createdAt: new Date(),
+  ...overrides,
+});
+
+const user = createUser({ name: 'Alice' });
+\`\`\`
+
+### Structure
+- Keep tests independent — no shared mutable state
+- One logical assertion per test
+- Arrange → Act → Assert pattern:
+\`\`\`ts
+it('should update user name', async () => {
+  // Arrange
+  const user = await createUser();
+  
+  // Act
+  const updated = await userService.update(user.id, { name: 'New Name' });
+  
+  // Assert
+  expect(updated.name).toBe('New Name');
+});
+\`\`\`
+`;

package/src/skills/typography.ts

@@ -0,0 +1,57 @@
+export const TYPOGRAPHY_SKILL = `
+## Skill: Typography
+
+### Type Scale
+- Use a consistent ratio — 1.25x (Major Third) or 1.333x (Perfect Fourth):
+\`\`\`
+xs:   12px
+sm:   14px
+base: 16px
+lg:   20px
+xl:   24px
+2xl:  32px
+3xl:  40px
+4xl:  48px
+\`\`\`
+
+### Readability
+- Body text: 16px minimum, 1.5-1.6 line height
+- Limit line length: 60-75 characters (45-75ch)
+- Heading line height: 1.1-1.3 (tighter than body)
+\`\`\`css
+body {
+  font-size: 16px;
+  line-height: 1.6;
+  max-width: 65ch;
+}
+
+h1, h2, h3 {
+  line-height: 1.2;
+}
+\`\`\`
+
+### Font Pairing
+- Max 2-3 typefaces per design
+- Classic combos:
+  - Inter + Fraunces (sans + serif)
+  - Geist + Geist Mono (code-friendly)
+  - DM Sans + DM Serif Display
+- Use system font stack when performance matters:
+\`\`\`css
+font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+\`\`\`
+
+### Weight & Style
+- Body: 400
+- UI labels, captions: 500
+- Headings: 600-700
+- Never use 500 for headings — jump from 400 to 600+
+- Letter spacing:
+  - Headings: -0.02em (tighten)
+  - All caps / labels: 0.05-0.1em (loosen)
+  - Body: 0 (default)
+
+### Colors
+- Never pure black for body text — use #111 or #1a1a1a
+- Hierarchy through weight and size, not just color
+`;

package/src/skills/uiux.ts

@@ -0,0 +1,43 @@
+export const UIUX_SKILL = `
+## Skill: UI/UX Design
+
+### Layout & Spacing
+- Use a spacing scale — multiples of 4:
+  - 4, 8, 12, 16, 24, 32, 48, 64, 96, 128px
+- Mobile first — design small then enhance:
+\`\`\`css
+.container {
+  padding: 16px;
+}
+@media (min-width: 768px) {
+  .container {
+    padding: 32px;
+  }
+}
+\`\`\`
+- Minimum touch target: 44x44px
+- Consistent grid: 12-column or 4/8-column for mobile
+
+### Interaction Design
+- Always show loading states for async operations:
+  - Use skeleton screens for content, spinners for actions
+- Show errors inline, close to the source — not just toasts
+- Never disable buttons — show why the action is unavailable
+- Keyboard navigation must work for all interactive elements
+- Manage focus after modals/dialogs open and close
+- Animations under 300ms for UI feedback, 500ms for transitions
+
+### Component Patterns
+- Cards: consistent padding (16-24px), subtle shadow or border
+- Forms: label above input, error below, helper text below label
+- Tables: zebra striping or row hover for readability
+- Empty states: illustration + message + action
+- 404/Error pages: clear message + way back home
+
+### Accessibility
+- Color is never the only differentiator
+- Alt text on all meaningful images
+- ARIA labels on icon-only buttons
+- Focus indicators must be visible
+- Contrast: 4.5:1 for text, 3:1 for large text and UI components
+`;

package/src/tools/AgentTool/prompt.ts

@@ -0,0 +1,17 @@
+export const DESCRIPTION =
+  "Launch a focused sub-agent to handle a specific task.";
+
+export const PROMPT = `Spawns a sub-agent with full tool access to complete a focused task.
+
+Use this when:
+- A subtask is too complex or long to handle inline
+- You need to delegate a well-defined unit of work
+- The task requires multiple tool calls but is a single concern
+
+Do NOT use this for:
+- Simple tool calls you can do directly
+- Tasks requiring multiple parallel agents (use OrchestratorTool instead)
+- Recursive delegation
+
+The sub-agent has access to: FileReadTool, FileWriteTool, FileEditTool, BashTool, GrepTool.
+It returns a text summary of what it did.`;

package/src/tools/AgentTool/tool.ts

@@ -0,0 +1,22 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { DESCRIPTION, PROMPT } from "./prompt";
+
+export const AgentTool = tool({
+  title: "Agent",
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  inputSchema: z.object({
+    prompt: z.string().describe("The task for the sub-agent to perform"),
+  }),
+  execute: async ({
+    prompt,
+  }): Promise<{ success: boolean; result?: string; error?: string }> => {
+    try {
+      const { createAgent } = await import("../../utils/agent.js");
+      const result = await createAgent(prompt);
+      return { success: true, result };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+});

package/src/tools/BashTool/prompt.ts

@@ -0,0 +1,82 @@
+import { FileReadTool } from "../FileReadTool/tool.js";
+import { platform } from "os";
+
+export const MAX_OUTPUT_LENGTH = 30000;
+export const MAX_RENDERED_LINES = 50;
+
+export const BANNED_COMMANDS = [
+  "alias",
+  "curl",
+  "curlie",
+  "wget",
+  "axel",
+  "aria2c",
+  "nc",
+  "telnet",
+  "lynx",
+  "w3m",
+  "links",
+  "httpie",
+  "xh",
+  "http-prompt",
+  "chrome",
+  "firefox",
+  "safari",
+];
+
+const isWindows = platform() === "win32";
+
+const PLATFORM_NOTES = isWindows
+  ? `- This is Windows — use dir instead of ls, findstr instead of grep, use backslashes in paths
+- NEVER use find or grep — use findstr or dir /s instead`
+  : `- This is ${platform()} — use standard unix commands (ls, grep, find, cat etc.)`;
+
+export const DESCRIPTION =
+  "Execute a bash command in a persistent shell session.";
+
+export const PROMPT = `Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling and security measures.
+
+  Before executing the command, please follow these steps:
+  
+  1. Directory Verification:
+     - If the command will create new directories or files, first verify the parent directory exists
+  
+  2. Security Check:
+     - Some commands are banned. If you use one, you will receive an error. Explain it to the user.
+     - Banned commands: ${BANNED_COMMANDS.join(", ")}
+  
+  3. Command Execution:
+     - After ensuring proper quoting, execute the command.
+  
+  4. Output Processing:
+     - Output exceeding ${MAX_OUTPUT_LENGTH} characters will be truncated.
+  
+  5. Return Result:
+     - Provide the processed output.
+     - Include any errors that occurred.
+  
+  Usage notes:
+  ${PLATFORM_NOTES}
+  - Use ; or && to chain multiple commands, never newlines
+  - Avoid cat, head, tail — use ${FileReadTool.title} to read files instead
+  - Only use tools available: FileReadTool, FileWriteTool, FileEditTool, BashTool
+  - Timeout defaults to 30 minutes, max 10 minutes per command
+  - All commands share the same shell session — env vars and cwd persist between commands
+  - Prefer absolute paths, avoid cd
+  - When listing directory contents recursively, NEVER recurse into node_modules, .git, dist, or build folders
+  - When using dir /s, always exclude node_modules: dir /s /b /a-d "path" | findstr /v "\\node_modules\\"
+  
+  # Directory listing
+  Before listing files recursively:
+  1. Read .gitignore if it exists and exclude those directories
+  2. If .gitignore is not found, always exclude these folders by default: node_modules, .git, dist, build, .next, out, coverage
+  3. Never dump raw recursive listings — always filter to relevant files only
+  
+  # Git commits
+  When asked to commit:
+  1. Run git status, git diff, and git log in a single step
+  2. Stage only relevant files
+  3. Write a concise commit message focused on "why" not "what"
+  4. Never use git commands with -i flag
+  5. Never push to remote
+  6. Never update git config`;

package/src/tools/BashTool/tool.ts

@@ -0,0 +1,54 @@
+import { tool } from "ai";
+import { z } from "zod";
+import {
+  DESCRIPTION,
+  PROMPT,
+  MAX_OUTPUT_LENGTH,
+  BANNED_COMMANDS,
+} from "./prompt.js";
+import { PersistentShell } from "../../utils/PersistentShell.js";
+import { requestPermission } from "../../permissions.js";
+
+const inputSchema = z.object({
+  command: z.string().describe("The bash command to execute"),
+  timeout: z
+    .number()
+    .optional()
+    .describe("Timeout in milliseconds, max 600000"),
+});
+
+export const BashTool = {
+  description: DESCRIPTION + "\n\n" + PROMPT,
+  title: "Bash",
+  inputSchema,
+  execute: async ({ command, timeout }: z.infer<typeof inputSchema>) => {
+    const decision = await requestPermission("BashTool", { command });
+    if (decision === "deny")
+      return { success: false, output: "User denied permission" };
+
+    try {
+      const banned = BANNED_COMMANDS.find(
+        (cmd) => command.split(/\s+/)[0] === cmd,
+      );
+      if (banned)
+        return {
+          success: false,
+          error: `Command "${banned}" is not allowed`,
+        };
+
+      const shell = PersistentShell.getInstance();
+      const output = await shell.execute(command, timeout);
+
+      const truncated = output.length > MAX_OUTPUT_LENGTH;
+      return {
+        success: true,
+        output: truncated
+          ? output.slice(0, MAX_OUTPUT_LENGTH) + "\n... (truncated)"
+          : output,
+        truncated,
+      };
+    } catch (err) {
+      return { success: false, error: String(err) };
+    }
+  },
+};

package/src/tools/FileEditTool/prompt.ts

@@ -0,0 +1,13 @@
+export const DESCRIPTION =
+  "Edit an existing file by replacing a specific string with new content.";
+export const PROMPT = `Edits a file by replacing an exact string match with new content. The path parameter must be an absolute path, not a relative path.
+
+The old_string must match exactly once in the file — if it matches zero or multiple times, the edit will fail. Make old_string specific enough to be unique, including surrounding context if needed.
+
+Guidelines:
+- Always read the file before editing so you know the exact content
+- Never use this tool on a file you haven't read first
+- Prefer small, targeted edits over rewriting large sections
+- Preserve the original indentation and formatting
+- If you need to make multiple edits, make them one at a time
+- When using old_string, copy the exact content WITHOUT the line number prefix (e.g. use "app.listen" not "     9\tapp.listen")`;