create-hq 5.0.0

package/template/workers/dev-team/architect/src/index.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { systemDesign } from './skills/system-design';
+import { apiDesign } from './skills/api-design';
+import { refactorPlan } from './skills/refactor-plan';
+
+const program = new Command();
+
+program
+  .name('architect')
+  .description('System design, planning, and technical decision-making')
+  .version('1.0.0');
+
+program
+  .command('system-design')
+  .description('Design system architecture for a feature')
+  .requiredOption('--feature <description>', 'Feature to design')
+  .option('--repo <path>', 'Target repository')
+  .option('--scope <level>', 'Scope: small|medium|large')
+  .action(async (options) => {
+    await systemDesign(options);
+  });
+
+program
+  .command('api-design')
+  .description('Design API contracts and interfaces')
+  .option('--endpoint <path>', 'API endpoint path')
+  .option('--feature <name>', 'Feature name')
+  .option('--repo <path>', 'Target repository')
+  .option('--format <type>', 'Output format: openapi|typescript')
+  .action(async (options) => {
+    if (!options.endpoint && !options.feature) {
+      console.error('Either --endpoint or --feature is required');
+      process.exit(1);
+    }
+    await apiDesign(options);
+  });
+
+program
+  .command('refactor-plan')
+  .description('Plan a refactoring approach')
+  .requiredOption('--target <path>', 'Target file, directory, or pattern')
+  .option('--repo <path>', 'Target repository')
+  .option('--goal <description>', 'Refactoring goal')
+  .action(async (options) => {
+    await refactorPlan(options);
+  });
+
+program.parse();

package/template/workers/dev-team/architect/src/mcp-server.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+
+const server = new Server(
+  {
+    name: 'architect',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'system_design',
+        description: 'Design system architecture for a feature',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            feature: { type: 'string', description: 'Feature to design' },
+            repo: { type: 'string', description: 'Target repository path' },
+            scope: { type: 'string', enum: ['small', 'medium', 'large'], description: 'Scope of design' },
+          },
+          required: ['feature'],
+        },
+      },
+      {
+        name: 'api_design',
+        description: 'Design API contracts and interfaces',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            endpoint: { type: 'string', description: 'API endpoint path' },
+            feature: { type: 'string', description: 'Feature name' },
+            repo: { type: 'string', description: 'Target repository' },
+            format: { type: 'string', enum: ['openapi', 'typescript'], description: 'Output format' },
+          },
+        },
+      },
+      {
+        name: 'refactor_plan',
+        description: 'Plan a refactoring approach',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            target: { type: 'string', description: 'Target file, directory, or pattern' },
+            repo: { type: 'string', description: 'Target repository' },
+            goal: { type: 'string', description: 'Refactoring goal' },
+          },
+          required: ['target'],
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'system_design': {
+        const { systemDesign } = await import('./skills/system-design');
+        const result = await captureOutput(() => systemDesign(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      case 'api_design': {
+        const { apiDesign } = await import('./skills/api-design');
+        const result = await captureOutput(() => apiDesign(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      case 'refactor_plan': {
+        const { refactorPlan } = await import('./skills/refactor-plan');
+        const result = await captureOutput(() => refactorPlan(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+  }
+});
+
+async function captureOutput(fn: () => Promise<any>): Promise<string> {
+  const logs: string[] = [];
+  const originalLog = console.log;
+  const originalError = console.error;
+
+  console.log = (...args) => logs.push(args.join(' '));
+  console.error = (...args) => logs.push(`ERROR: ${args.join(' ')}`);
+
+  try {
+    await fn();
+  } finally {
+    console.log = originalLog;
+    console.error = originalError;
+  }
+
+  return logs.join('\n');
+}
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/template/workers/dev-team/architect/src/skills/api-design.ts

@@ -0,0 +1,316 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface ApiDesignOptions {
+  endpoint?: string;
+  feature?: string;
+  repo?: string;
+  format?: 'openapi' | 'typescript';
+}
+
+interface EndpointSpec {
+  method: string;
+  path: string;
+  description: string;
+  request?: Record<string, string>;
+  response: Record<string, string>;
+  errors: string[];
+  auth: boolean;
+}
+
+export async function apiDesign(options: ApiDesignOptions): Promise<void> {
+  const { endpoint, feature, repo, format = 'typescript' } = options;
+
+  const target = endpoint || feature;
+  console.log(`\n=== API Design: ${target} ===\n`);
+
+  // Analyze existing API patterns if repo provided
+  if (repo) {
+    console.log('Analyzing existing API patterns...');
+    const patterns = analyzeApiPatterns(repo);
+    console.log('\nExisting conventions:');
+    for (const pattern of patterns) {
+      console.log(`  - ${pattern}`);
+    }
+  }
+
+  // Generate endpoint specifications
+  const endpoints = generateEndpoints(target!);
+
+  console.log('\n' + '-'.repeat(40));
+  console.log('\nProposed endpoints:\n');
+
+  for (const ep of endpoints) {
+    console.log(`${ep.method} ${ep.path}`);
+    console.log(`  ${ep.description}`);
+    if (ep.request) {
+      console.log(`  Request: ${JSON.stringify(ep.request)}`);
+    }
+    console.log(`  Response: ${JSON.stringify(ep.response)}`);
+    if (ep.errors.length > 0) {
+      console.log(`  Errors: ${ep.errors.join(', ')}`);
+    }
+    console.log(`  Auth: ${ep.auth ? 'Required' : 'None'}`);
+    console.log();
+  }
+
+  // Generate TypeScript interfaces
+  if (format === 'typescript') {
+    console.log('-'.repeat(40));
+    console.log('\nGenerated TypeScript interfaces:\n');
+    console.log(generateTypeScriptInterfaces(endpoints, target!));
+  }
+
+  console.log('\n[Human approval required]');
+  console.log('Approve contract? [y/n/modify]');
+
+  console.log('\nOn approval, will generate:');
+  console.log('  - Type definitions in src/types/');
+  console.log('  - API route stubs (if Next.js detected)');
+  console.log('  - Validation schemas');
+}
+
+function analyzeApiPatterns(repoPath: string): string[] {
+  const patterns: string[] = [];
+
+  // Check for API directory structure
+  const apiDirs = [
+    'src/app/api',
+    'src/pages/api',
+    'pages/api',
+    'api',
+  ];
+
+  for (const dir of apiDirs) {
+    const fullPath = path.join(repoPath, dir);
+    if (fs.existsSync(fullPath)) {
+      patterns.push(`API routes in ${dir}`);
+      break;
+    }
+  }
+
+  // Check for common API patterns
+  const pkgPath = path.join(repoPath, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+
+      if (deps['zod']) patterns.push('Zod validation');
+      if (deps['@trpc/server']) patterns.push('tRPC');
+      if (deps['express']) patterns.push('Express.js');
+      if (deps['next']) patterns.push('Next.js API routes');
+    } catch (e) {
+      // Ignore
+    }
+  }
+
+  if (patterns.length === 0) {
+    patterns.push('(No existing patterns detected)');
+  }
+
+  return patterns;
+}
+
+function generateEndpoints(target: string): EndpointSpec[] {
+  const targetLower = target.toLowerCase();
+
+  // Auth-related endpoints
+  if (targetLower.includes('auth') || targetLower.includes('login')) {
+    return [
+      {
+        method: 'POST',
+        path: '/api/auth/login',
+        description: 'Authenticate user with credentials',
+        request: { email: 'string', password: 'string', rememberMe: 'boolean?' },
+        response: { user: 'User', token: 'string', expiresAt: 'string' },
+        errors: ['INVALID_CREDENTIALS', 'ACCOUNT_LOCKED', 'RATE_LIMITED'],
+        auth: false,
+      },
+      {
+        method: 'POST',
+        path: '/api/auth/logout',
+        description: 'End user session',
+        response: { success: 'boolean' },
+        errors: ['UNAUTHORIZED'],
+        auth: true,
+      },
+      {
+        method: 'GET',
+        path: '/api/auth/me',
+        description: 'Get current user profile',
+        response: { user: 'User' },
+        errors: ['UNAUTHORIZED'],
+        auth: true,
+      },
+      {
+        method: 'POST',
+        path: '/api/auth/refresh',
+        description: 'Refresh authentication token',
+        request: { refreshToken: 'string' },
+        response: { token: 'string', expiresAt: 'string' },
+        errors: ['INVALID_TOKEN', 'EXPIRED_TOKEN'],
+        auth: false,
+      },
+    ];
+  }
+
+  // User-related endpoints
+  if (targetLower.includes('user')) {
+    return [
+      {
+        method: 'GET',
+        path: '/api/users',
+        description: 'List users (paginated)',
+        request: { page: 'number?', limit: 'number?' },
+        response: { users: 'User[]', total: 'number', page: 'number' },
+        errors: ['UNAUTHORIZED', 'FORBIDDEN'],
+        auth: true,
+      },
+      {
+        method: 'GET',
+        path: '/api/users/:id',
+        description: 'Get user by ID',
+        response: { user: 'User' },
+        errors: ['UNAUTHORIZED', 'NOT_FOUND'],
+        auth: true,
+      },
+      {
+        method: 'PATCH',
+        path: '/api/users/:id',
+        description: 'Update user',
+        request: { name: 'string?', email: 'string?' },
+        response: { user: 'User' },
+        errors: ['UNAUTHORIZED', 'FORBIDDEN', 'VALIDATION_ERROR'],
+        auth: true,
+      },
+      {
+        method: 'DELETE',
+        path: '/api/users/:id',
+        description: 'Delete user',
+        response: { success: 'boolean' },
+        errors: ['UNAUTHORIZED', 'FORBIDDEN', 'NOT_FOUND'],
+        auth: true,
+      },
+    ];
+  }
+
+  // Generic CRUD endpoints
+  const resource = target.replace(/[^a-zA-Z]/g, '').toLowerCase();
+  const Resource = resource.charAt(0).toUpperCase() + resource.slice(1);
+
+  return [
+    {
+      method: 'GET',
+      path: `/api/${resource}`,
+      description: `List ${resource} (paginated)`,
+      request: { page: 'number?', limit: 'number?' },
+      response: { items: `${Resource}[]`, total: 'number' },
+      errors: ['UNAUTHORIZED'],
+      auth: true,
+    },
+    {
+      method: 'POST',
+      path: `/api/${resource}`,
+      description: `Create ${resource}`,
+      request: { '...fields': 'varies' },
+      response: { item: Resource },
+      errors: ['UNAUTHORIZED', 'VALIDATION_ERROR'],
+      auth: true,
+    },
+    {
+      method: 'GET',
+      path: `/api/${resource}/:id`,
+      description: `Get ${resource} by ID`,
+      response: { item: Resource },
+      errors: ['UNAUTHORIZED', 'NOT_FOUND'],
+      auth: true,
+    },
+    {
+      method: 'PATCH',
+      path: `/api/${resource}/:id`,
+      description: `Update ${resource}`,
+      request: { '...fields': 'varies' },
+      response: { item: Resource },
+      errors: ['UNAUTHORIZED', 'NOT_FOUND', 'VALIDATION_ERROR'],
+      auth: true,
+    },
+    {
+      method: 'DELETE',
+      path: `/api/${resource}/:id`,
+      description: `Delete ${resource}`,
+      response: { success: 'boolean' },
+      errors: ['UNAUTHORIZED', 'NOT_FOUND'],
+      auth: true,
+    },
+  ];
+}
+
+function generateTypeScriptInterfaces(endpoints: EndpointSpec[], target: string): string {
+  const lines: string[] = [];
+  const targetLower = target.toLowerCase();
+
+  // Determine main entity type
+  let entityName = 'Item';
+  if (targetLower.includes('user') || targetLower.includes('auth')) {
+    entityName = 'User';
+  }
+
+  lines.push(`// API Types for: ${target}`);
+  lines.push('');
+  lines.push(`export interface ${entityName} {`);
+  lines.push('  id: string;');
+  if (entityName === 'User') {
+    lines.push('  email: string;');
+    lines.push('  name: string;');
+    lines.push('  createdAt: string;');
+  } else {
+    lines.push('  // Add entity fields');
+    lines.push('  createdAt: string;');
+    lines.push('  updatedAt: string;');
+  }
+  lines.push('}');
+  lines.push('');
+
+  // Generate request/response types for each endpoint
+  for (const ep of endpoints) {
+    const typeName = ep.path
+      .replace('/api/', '')
+      .replace(/[/:]/g, '_')
+      .split('_')
+      .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+      .join('');
+
+    if (ep.request) {
+      lines.push(`export interface ${typeName}${ep.method}Request {`);
+      for (const [key, type] of Object.entries(ep.request)) {
+        const optional = type.endsWith('?') ? '?' : '';
+        const cleanType = type.replace('?', '');
+        lines.push(`  ${key}${optional}: ${cleanType};`);
+      }
+      lines.push('}');
+      lines.push('');
+    }
+
+    lines.push(`export interface ${typeName}${ep.method}Response {`);
+    for (const [key, type] of Object.entries(ep.response)) {
+      lines.push(`  ${key}: ${type};`);
+    }
+    lines.push('}');
+    lines.push('');
+  }
+
+  // Generate error type
+  const allErrors = [...new Set(endpoints.flatMap(ep => ep.errors))];
+  if (allErrors.length > 0) {
+    lines.push('export type ApiErrorCode =');
+    lines.push(`  | '${allErrors.join("'\n  | '")}';`);
+    lines.push('');
+    lines.push('export interface ApiError {');
+    lines.push('  code: ApiErrorCode;');
+    lines.push('  message: string;');
+    lines.push('}');
+  }
+
+  return lines.join('\n');
+}