pixelcrew 0.2.2 → 0.2.6

package/src/protocol/agent.js

@@ -0,0 +1,124 @@
+/**
+ * PIXEL CREW — Universal Agent Protocol & Roles
+ * 
+ * Standardized agent roles, states, expressions, and capability contracts.
+ */
+
+export const AGENT_STATES = {
+  IDLE: 'IDLE',
+  SPAWNING: 'SPAWNING',
+  ANALYZING: 'ANALYZING',
+  WORKING: 'WORKING',
+  BLOCKED: 'BLOCKED',
+  VERIFYING: 'VERIFYING',
+  COMPLETED: 'COMPLETED',
+  ERROR: 'ERROR'
+};
+
+export const AGENT_EXPRESSIONS = {
+  IDLE: '●_●',
+  SPAWNING: '░_░',
+  ANALYZING: '◉_⊙',
+  WORKING: '◉▂◉',
+  BLOCKED: '?_?',
+  VERIFYING: '🔍_🔍',
+  COMPLETED: '^_^',
+  ERROR: 'x_x'
+};
+
+export const ORCHESTRATOR_EXPRESSIONS = {
+  IDLE: '◉_◉',
+  COORDINATING: '◉_◉ ⚡',
+  ANALYZING: '◉_⊙',
+  COMPLETED: '★_★',
+  ERROR: 'x_x'
+};
+
+export const AGENT_ROLES = {
+  orchestrator: {
+    id: 'orchestrator',
+    name: 'Tech Lead / Master CPU',
+    title: 'Staff Swarm Architect & Project Lead',
+    color: '#ffd700',
+    icon: '👔',
+    defaultSkills: ['anti-ai/slop-guardian']
+  },
+  creativeDirector: {
+    id: 'creativeDirector',
+    name: 'Creative Director',
+    title: 'Lead Aesthetic Strategist & Brand Architect',
+    color: '#ff9900',
+    icon: '✨',
+    defaultSkills: ['design/ui-design', 'design/typography', 'anti-ai/slop-guardian']
+  },
+  frontend: {
+    id: 'frontend',
+    name: 'Frontend Builder',
+    title: 'Senior UI/UX & Component Engineer',
+    color: '#00f0ff',
+    icon: '🎨',
+    defaultSkills: ['frontend/nextjs', 'frontend/react', 'frontend/tailwind', 'frontend/accessibility']
+  },
+  backend: {
+    id: 'backend',
+    name: 'Backend Engineer',
+    title: 'Principal API & Distributed Systems Engineer',
+    color: '#ff007f',
+    icon: '⚡',
+    defaultSkills: ['backend/route-handlers', 'backend/data-models']
+  },
+  database: {
+    id: 'database',
+    name: 'Database Architect',
+    title: 'Principal DBA & Query Performance Engineer',
+    color: '#ffd700',
+    icon: '🗄️',
+    defaultSkills: ['backend/data-models']
+  },
+  security: {
+    id: 'security',
+    name: 'Security Sentinel',
+    title: 'InfoSec Lead & OWASP Auditor',
+    color: '#ff3344',
+    icon: '🛡️',
+    defaultSkills: ['frontend/accessibility']
+  },
+  performance: {
+    id: 'performance',
+    name: 'Performance Profiler',
+    title: 'Core Web Vitals & Runtime Optimizer',
+    color: '#00ff88',
+    icon: '🚀',
+    defaultSkills: ['quality/responsive-design']
+  },
+  qa: {
+    id: 'qa',
+    name: 'QA & Visual Critic',
+    title: 'Lead Verification & Anti-AI Rubric Guardian',
+    color: '#bd00ff',
+    icon: '🧪',
+    defaultSkills: ['quality/visual-review', 'quality/browser-testing', 'anti-ai/slop-guardian']
+  },
+  animationSpecialist: {
+    id: 'animationSpecialist',
+    name: 'Motion Specialist',
+    title: 'Senior Kinetic Choreographer & Micro-Interactions',
+    color: '#38bdf8',
+    icon: '🎬',
+    defaultSkills: ['motion/framer-motion', 'motion/micro-interactions']
+  }
+};
+
+/**
+ * Creates and normalizes an Agent Capabilities record
+ */
+export function normalizeCapabilities(capabilities = {}) {
+  return {
+    fileAccess: Boolean(capabilities.fileAccess ?? true),
+    terminalAccess: Boolean(capabilities.terminalAccess ?? true),
+    subagents: Boolean(capabilities.subagents ?? false),
+    backgroundTasks: Boolean(capabilities.backgroundTasks ?? true),
+    streaming: Boolean(capabilities.streaming ?? true),
+    toolCalls: Boolean(capabilities.toolCalls ?? true)
+  };
+}

package/src/protocol/event.js

@@ -0,0 +1,78 @@
+/**
+ * PIXEL CREW — Universal Event Protocol
+ * 
+ * Standardized telemetry, lifecycle, and progress events across all agent providers.
+ */
+
+export const EVENT_TYPES = {
+  AGENT_STARTED: 'agent.started',
+  AGENT_THINKING: 'agent.thinking',
+  SKILL_ACTIVATED: 'skill.activated',
+  TOOL_INVOKED: 'tool.invoked',
+  PROGRESS: 'progress',
+  TASK_COMPLETED: 'task.completed',
+  TASK_FAILED: 'task.failed',
+  ORCHESTRATION_STARTED: 'orchestration.started',
+  ORCHESTRATION_COMPLETED: 'orchestration.completed',
+  ORCHESTRATION_FAILED: 'orchestration.failed',
+  STATE_CHANGE: 'state.change'
+};
+
+/**
+ * Creates and validates a standardized AgentEvent object
+ */
+export function createEvent(options = {}) {
+  const event = {
+    id: options.id || `evt-${Date.now()}-${Math.random().toString(36).slice(2, 7)}`,
+    timestamp: options.timestamp || Date.now(),
+    agent: options.agent || 'orchestrator',
+    type: options.type || EVENT_TYPES.PROGRESS,
+    taskId: options.taskId || null,
+    taskName: options.taskName || null,
+    skill: options.skill || null,
+    message: String(options.message || ''),
+    provider: options.provider || 'generic',
+    data: typeof options.data === 'object' && options.data !== null ? { ...options.data } : {}
+  };
+
+  validateEvent(event);
+  return event;
+}
+
+/**
+ * Validates that an AgentEvent object satisfies contract
+ */
+export function validateEvent(event) {
+  if (!event || typeof event !== 'object') {
+    throw new Error('Event must be a non-null object');
+  }
+  if (!event.id || typeof event.id !== 'string') {
+    throw new Error('Event must have a valid string id');
+  }
+  if (typeof event.timestamp !== 'number') {
+    throw new Error('Event must have a numeric timestamp');
+  }
+  if (!event.agent || typeof event.agent !== 'string') {
+    throw new Error('Event must have a valid agent name');
+  }
+  if (!event.type || typeof event.type !== 'string') {
+    throw new Error('Event must have a valid event type');
+  }
+  return true;
+}
+
+/**
+ * Serializes event for JSONL log line
+ */
+export function serializeEvent(event) {
+  validateEvent(event);
+  return JSON.stringify(event);
+}
+
+/**
+ * Deserializes an event from JSON string or object
+ */
+export function deserializeEvent(raw) {
+  const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  return createEvent(data);
+}

package/src/protocol/index.js

@@ -0,0 +1,8 @@
+/**
+ * PIXEL CREW — Protocol Index
+ */
+
+export * from './task.js';
+export * from './agent.js';
+export * from './event.js';
+export * from './skill.js';

package/src/protocol/skill.js

@@ -0,0 +1,54 @@
+/**
+ * PIXEL CREW — Universal Skill Protocol
+ * 
+ * Standard skill interfaces, capability tags, and resolution schemas.
+ */
+
+export const SKILL_CATEGORIES = {
+  FRONTEND: 'frontend',
+  DESIGN: 'design',
+  MOTION: 'motion',
+  QUALITY: 'quality',
+  BACKEND: 'backend',
+  CONTENT: 'content',
+  ANTI_AI: 'anti-ai'
+};
+
+/**
+ * Creates a standardized Skill object
+ */
+export function createSkill(options = {}) {
+  const skill = {
+    id: String(options.id || ''),
+    name: String(options.name || options.id || 'Untitled Skill'),
+    category: String(options.category || SKILL_CATEGORIES.FRONTEND),
+    description: String(options.description || ''),
+    targetAgents: Array.isArray(options.targetAgents) ? [...options.targetAgents] : ['frontend'],
+    metadata: typeof options.metadata === 'object' && options.metadata !== null ? { ...options.metadata } : {}
+  };
+
+  validateSkill(skill);
+  return skill;
+}
+
+/**
+ * Validates a Skill object
+ */
+export function validateSkill(skill) {
+  if (!skill || typeof skill !== 'object') {
+    throw new Error('Skill must be a non-null object');
+  }
+  if (!skill.id || typeof skill.id !== 'string') {
+    throw new Error('Skill must have a valid string id');
+  }
+  if (!skill.name || typeof skill.name !== 'string') {
+    throw new Error('Skill must have a valid string name');
+  }
+  if (!skill.category || typeof skill.category !== 'string') {
+    throw new Error('Skill must have a valid category');
+  }
+  if (!Array.isArray(skill.targetAgents) || skill.targetAgents.length === 0) {
+    throw new Error('Skill must target at least one agent');
+  }
+  return true;
+}

package/src/protocol/task.js

@@ -0,0 +1,100 @@
+/**
+ * PIXEL CREW — Universal Task Protocol
+ * 
+ * Standardized task definition, validation, and serialization.
+ * Translates between Pixel Crew Core and Provider Adapters.
+ */
+
+export const TASK_STATUS = {
+  PENDING: 'pending',
+  QUEUED: 'queued',
+  RUNNING: 'running',
+  COMPLETED: 'completed',
+  FAILED: 'failed',
+  CANCELLED: 'cancelled'
+};
+
+/**
+ * Creates a standardized AgentTask object
+ */
+export function createTask(options = {}) {
+  const {
+    id = `task-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+    title = 'Untitled Task',
+    description = '',
+    agent = 'frontend',
+    skills = [],
+    files = { read: [], write: [] },
+    dependencies = [],
+    status = TASK_STATUS.QUEUED,
+    assignedProvider = null,
+    metadata = {}
+  } = options;
+
+  const task = {
+    id: String(id),
+    title: String(title),
+    description: String(description),
+    agent: String(agent),
+    skills: Array.isArray(skills) ? [...skills] : [],
+    files: {
+      read: Array.isArray(files?.read) ? [...files.read] : [],
+      write: Array.isArray(files?.write) ? [...files.write] : []
+    },
+    dependencies: Array.isArray(dependencies) ? [...dependencies] : [],
+    status: Object.values(TASK_STATUS).includes(status) ? status : TASK_STATUS.QUEUED,
+    assignedProvider: assignedProvider ? String(assignedProvider) : null,
+    metadata: typeof metadata === 'object' && metadata !== null ? { ...metadata } : {},
+    createdAt: options.createdAt || Date.now(),
+    updatedAt: options.updatedAt || Date.now(),
+    result: options.result || null,
+    error: options.error || null
+  };
+
+  validateTask(task);
+  return task;
+}
+
+/**
+ * Validates that an AgentTask satisfies the required contract
+ */
+export function validateTask(task) {
+  if (!task || typeof task !== 'object') {
+    throw new Error('Task must be a non-null object');
+  }
+  if (!task.id || typeof task.id !== 'string') {
+    throw new Error('Task must have a valid string id');
+  }
+  if (!task.title || typeof task.title !== 'string') {
+    throw new Error('Task must have a valid string title');
+  }
+  if (!task.agent || typeof task.agent !== 'string') {
+    throw new Error('Task must have a target agent specified');
+  }
+  if (!Array.isArray(task.skills)) {
+    throw new Error('Task skills must be an array');
+  }
+  if (!task.files || typeof task.files !== 'object') {
+    throw new Error('Task files must be an object with read and write arrays');
+  }
+  if (!Array.isArray(task.dependencies)) {
+    throw new Error('Task dependencies must be an array of task IDs');
+  }
+  return true;
+}
+
+/**
+ * Serializes task to JSON format with formatting
+ */
+export function serializeTask(task) {
+  validateTask(task);
+  return JSON.stringify(task, null, 2);
+}
+
+/**
+ * Parses task from JSON string or object
+ */
+export function deserializeTask(raw) {
+  const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+  return createTask(data);
+}

package/src/scaffold/claude-generator.js

@@ -0,0 +1,60 @@
+/**
+ * PIXEL CREW — Claude Code Slash Commands & Instructions Generator
+ * 
+ * Generates .claude/commands/*.md files so that all 24 Floor 42 commands
+ * (/assemble, /blueprint, /recap, /render, /sentinel, /warp, /polish, etc.)
+ * natively appear in the Anthropic Claude Code CLI slash command picker.
+ */
+
+import path from 'node:path';
+import { FLOOR42_COMMANDS } from './commands-catalog.js';
+
+/**
+ * Generates all Claude Code command and instruction files
+ */
+export function generateClaudeFiles(targetDir, isGlobal = false) {
+  const baseDir = isGlobal ? targetDir : path.join(targetDir, '.claude');
+  const files = [];
+
+  // 1. Generate individual command markdown files in .claude/commands/
+  for (const cmd of FLOOR42_COMMANDS) {
+    const cmdPath = path.join(baseDir, 'commands', `${cmd.name}.md`);
+    const cmdContent = `---
+description: ${cmd.description}
+---
+
+# /${cmd.name}
+
+${cmd.prompt}
+`;
+    files.push({ path: cmdPath, content: cmdContent });
+  }
+
+  // 2. Workspace instructions and plugin manifest (for workspace scope)
+  if (!isGlobal) {
+    const claudeMdContent = `# 🏢 PixelCrew Multi-Agent Swarm Instructions for Claude Code
+
+You are integrated with PixelCrew (Floor 42, Pixel Corps HQ).
+Support \`/pixelcrew <command>\` and direct slash commands (\`/assemble\`, \`/blueprint\`, \`/boss-fight\`, \`/render\`, \`/recap\`, \`/sentinel\`, \`/audit\`, \`/warp\`, \`/polish\`, etc.).
+
+## ⚡ Available Slash Commands
+${FLOOR42_COMMANDS.map(c => `- **\`/${c.name}\`**: ${c.description}`).join('\n')}
+
+## 🛡️ Anti-AI Guidelines:
+- Reject purple/cyan neon blobs, floating fake sparkles, and uniform 3-card grids.
+- Apply intentional asymmetry (Bento grids), mathematical fluid clamp() typography, and high-contrast surface tiers.
+`;
+
+    const claudePluginContent = JSON.stringify({
+      name: 'pixelcrew',
+      version: '0.2.5',
+      description: 'Autonomous Multi-Agent Engineering Swarm & Retro Pixel-Art Startup Office',
+      skills: ['skills/pixelcrew']
+    }, null, 2) + '\n';
+
+    files.push({ path: path.join(targetDir, 'CLAUDE.md'), content: claudeMdContent });
+    files.push({ path: path.join(targetDir, '.claude-plugin', 'plugin.json'), content: claudePluginContent });
+  }
+
+  return files;
+}