create-hq 5.0.0

package/template/workers/dev-team/architect/src/skills/refactor-plan.ts

@@ -0,0 +1,264 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+
+interface RefactorPlanOptions {
+  target: string;
+  repo?: string;
+  goal?: string;
+}
+
+interface RefactorStep {
+  description: string;
+  files: string[];
+  risk: 'low' | 'medium' | 'high';
+  tests: string[];
+}
+
+export async function refactorPlan(options: RefactorPlanOptions): Promise<void> {
+  const { target, repo, goal } = options;
+
+  console.log(`\n=== Refactor Plan: ${target} ===\n`);
+
+  if (goal) {
+    console.log(`Goal: ${goal}\n`);
+  }
+
+  // Analyze target
+  let analysis: { issues: string[]; metrics: Record<string, number> } = {
+    issues: [],
+    metrics: {},
+  };
+
+  if (repo) {
+    console.log('Analyzing target code...');
+    analysis = analyzeTarget(repo, target);
+
+    console.log('\nCurrent state:');
+    for (const issue of analysis.issues) {
+      console.log(`  - ${issue}`);
+    }
+
+    if (Object.keys(analysis.metrics).length > 0) {
+      console.log('\nMetrics:');
+      for (const [key, value] of Object.entries(analysis.metrics)) {
+        console.log(`  - ${key}: ${value}`);
+      }
+    }
+  }
+
+  // Generate refactoring steps
+  const steps = generateSteps(target, goal, analysis.issues);
+
+  console.log('\n' + '-'.repeat(40));
+  console.log('\nRefactoring Steps:\n');
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+    const riskColor = step.risk === 'high' ? '⚠️' : step.risk === 'medium' ? '⚡' : '✓';
+    console.log(`${i + 1}. [ ] ${step.description} ${riskColor}`);
+    console.log(`   Files: ${step.files.join(', ')}`);
+    console.log(`   Risk: ${step.risk}`);
+    if (step.tests.length > 0) {
+      console.log(`   Tests: ${step.tests.join(', ')}`);
+    }
+    console.log();
+  }
+
+  // Test strategy
+  console.log('-'.repeat(40));
+  console.log('\nTest Strategy:');
+  console.log('  - Run existing tests after each step');
+  console.log('  - Verify no regressions');
+  if (analysis.issues.some(i => i.includes('test'))) {
+    console.log('  - Add missing tests before refactoring');
+  }
+
+  // Rollback plan
+  console.log('\nRollback Plan:');
+  console.log('  If issues arise at step N:');
+  console.log('    1. git revert to commit before step N');
+  console.log('    2. Analyze failure');
+  console.log('    3. Adjust approach and retry');
+
+  // Effort estimate
+  const complexity = steps.length <= 3 ? 'simple' :
+    steps.length <= 6 ? 'medium' : 'complex';
+  console.log(`\nEstimated effort: ${steps.length} phases, ${complexity} complexity`);
+
+  console.log('\n[Human approval required]');
+  console.log('Approve plan? [y/n/modify]');
+}
+
+function analyzeTarget(repoPath: string, target: string): { issues: string[]; metrics: Record<string, number> } {
+  const issues: string[] = [];
+  const metrics: Record<string, number> = {};
+
+  const fullPath = path.join(repoPath, target);
+
+  if (!fs.existsSync(fullPath)) {
+    issues.push(`Target not found: ${target}`);
+    return { issues, metrics };
+  }
+
+  // Check if it's a directory or file
+  const stat = fs.statSync(fullPath);
+
+  if (stat.isDirectory()) {
+    // Count files
+    try {
+      const files = fs.readdirSync(fullPath, { recursive: true }) as string[];
+      const tsFiles = files.filter(f => f.endsWith('.ts') || f.endsWith('.tsx'));
+      metrics['files'] = tsFiles.length;
+    } catch (e) {
+      // Ignore
+    }
+  }
+
+  // Look for common issues
+  try {
+    const content = stat.isFile()
+      ? fs.readFileSync(fullPath, 'utf-8')
+      : '';
+
+    // Check for 'any' types
+    const anyCount = (content.match(/: any/g) || []).length;
+    if (anyCount > 0) {
+      issues.push(`${anyCount} uses of 'any' type`);
+      metrics['any_types'] = anyCount;
+    }
+
+    // Check for @ts-ignore
+    const ignoreCount = (content.match(/@ts-ignore/g) || []).length;
+    if (ignoreCount > 0) {
+      issues.push(`${ignoreCount} @ts-ignore comments`);
+      metrics['ts_ignore'] = ignoreCount;
+    }
+
+    // Check for TODO comments
+    const todoCount = (content.match(/TODO/gi) || []).length;
+    if (todoCount > 0) {
+      issues.push(`${todoCount} TODO comments`);
+      metrics['todos'] = todoCount;
+    }
+
+  } catch (e) {
+    // Ignore read errors
+  }
+
+  if (issues.length === 0) {
+    issues.push('No obvious issues detected (manual review recommended)');
+  }
+
+  return { issues, metrics };
+}
+
+function generateSteps(target: string, goal?: string, issues: string[] = []): RefactorStep[] {
+  const goalLower = (goal || '').toLowerCase();
+
+  // TypeScript strict mode refactoring
+  if (goalLower.includes('strict') || goalLower.includes('typescript')) {
+    return [
+      {
+        description: 'Add explicit types to function parameters',
+        files: [target],
+        risk: 'low',
+        tests: ['npm run typecheck'],
+      },
+      {
+        description: 'Add explicit return types to functions',
+        files: [target],
+        risk: 'low',
+        tests: ['npm run typecheck'],
+      },
+      {
+        description: 'Replace "any" with proper types',
+        files: [target],
+        risk: 'medium',
+        tests: ['npm run typecheck', 'npm test'],
+      },
+      {
+        description: 'Add null checks for optional values',
+        files: [target],
+        risk: 'medium',
+        tests: ['npm run typecheck', 'npm test'],
+      },
+      {
+        description: 'Remove @ts-ignore comments',
+        files: [target],
+        risk: 'low',
+        tests: ['npm run typecheck'],
+      },
+      {
+        description: 'Enable strict mode in tsconfig',
+        files: ['tsconfig.json'],
+        risk: 'low',
+        tests: ['npm run typecheck', 'npm run build'],
+      },
+    ];
+  }
+
+  // Performance refactoring
+  if (goalLower.includes('performance') || goalLower.includes('optimize')) {
+    return [
+      {
+        description: 'Profile current performance',
+        files: [target],
+        risk: 'low',
+        tests: ['manual performance measurement'],
+      },
+      {
+        description: 'Identify bottlenecks',
+        files: [target],
+        risk: 'low',
+        tests: [],
+      },
+      {
+        description: 'Implement optimizations',
+        files: [target],
+        risk: 'medium',
+        tests: ['npm test', 'performance benchmark'],
+      },
+      {
+        description: 'Verify performance improvement',
+        files: [],
+        risk: 'low',
+        tests: ['performance benchmark'],
+      },
+    ];
+  }
+
+  // Default: General refactoring steps
+  return [
+    {
+      description: 'Identify code to refactor',
+      files: [target],
+      risk: 'low',
+      tests: [],
+    },
+    {
+      description: 'Add tests for existing behavior',
+      files: [target],
+      risk: 'low',
+      tests: ['npm test'],
+    },
+    {
+      description: 'Perform refactoring',
+      files: [target],
+      risk: 'medium',
+      tests: ['npm run typecheck', 'npm test'],
+    },
+    {
+      description: 'Update documentation',
+      files: [target],
+      risk: 'low',
+      tests: [],
+    },
+    {
+      description: 'Final verification',
+      files: [],
+      risk: 'low',
+      tests: ['npm run typecheck', 'npm run lint', 'npm test'],
+    },
+  ];
+}

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

@@ -0,0 +1,212 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface SystemDesignOptions {
+  feature: string;
+  repo?: string;
+  scope?: 'small' | 'medium' | 'large';
+}
+
+interface DesignOption {
+  name: string;
+  description: string;
+  pros: string[];
+  cons: string[];
+  recommended?: boolean;
+}
+
+export async function systemDesign(options: SystemDesignOptions): Promise<void> {
+  const { feature, repo, scope = 'medium' } = options;
+
+  console.log(`\n=== System Design: ${feature} ===\n`);
+
+  // Analyze existing architecture if repo provided
+  if (repo) {
+    console.log('Analyzing existing architecture...');
+    const analysis = analyzeRepo(repo);
+    console.log('\nExisting patterns:');
+    for (const pattern of analysis.patterns) {
+      console.log(`  - ${pattern}`);
+    }
+    console.log('\nKey dependencies:');
+    for (const dep of analysis.dependencies.slice(0, 5)) {
+      console.log(`  - ${dep}`);
+    }
+  }
+
+  // Generate design options based on feature
+  const designOptions = generateDesignOptions(feature, scope);
+
+  console.log('\n' + '-'.repeat(40));
+  console.log('\nDesign Options:\n');
+
+  for (let i = 0; i < designOptions.length; i++) {
+    const opt = designOptions[i];
+    const rec = opt.recommended ? ' (Recommended)' : '';
+    console.log(`${i + 1}. ${opt.name}${rec}`);
+    console.log(`   ${opt.description}`);
+    console.log('   Pros:');
+    for (const pro of opt.pros) {
+      console.log(`     + ${pro}`);
+    }
+    console.log('   Cons:');
+    for (const con of opt.cons) {
+      console.log(`     - ${con}`);
+    }
+    console.log();
+  }
+
+  console.log('[Human approval required]');
+  console.log(`Select approach: [1-${designOptions.length}]`);
+
+  // Show what would be generated
+  console.log('\n' + '-'.repeat(40));
+  console.log('\nOn approval, will generate:');
+  console.log('  - Architecture Decision Record (ADR)');
+  console.log('  - Component diagram (Mermaid)');
+  console.log('  - Implementation guide for workers');
+
+  // Sample ADR output
+  console.log('\n' + '-'.repeat(40));
+  console.log('\nSample ADR Preview:');
+  console.log(`
+# ADR: ${feature}
+
+## Status
+Proposed
+
+## Context
+Implementation of ${feature} requires architectural decisions
+regarding ${scope} scope changes.
+
+## Decision
+[Selected option will be documented here]
+
+## Consequences
+- Integration with existing patterns
+- Changes to: [affected components]
+- New dependencies: [if any]
+
+## Implementation Guide
+1. [Steps for architect/other workers]
+2. ...
+`);
+}
+
+function analyzeRepo(repoPath: string): { patterns: string[]; dependencies: string[] } {
+  const patterns: string[] = [];
+  const dependencies: string[] = [];
+
+  // Check for common patterns
+  const checks = [
+    { file: 'next.config.js', pattern: 'Next.js' },
+    { file: 'next.config.mjs', pattern: 'Next.js' },
+    { file: 'prisma/schema.prisma', pattern: 'Prisma ORM' },
+    { file: 'drizzle.config.ts', pattern: 'Drizzle ORM' },
+    { file: 'src/app', pattern: 'Next.js App Router' },
+    { file: 'src/pages', pattern: 'Next.js Pages Router' },
+    { file: 'tailwind.config.js', pattern: 'Tailwind CSS' },
+    { file: 'tailwind.config.ts', pattern: 'Tailwind CSS' },
+  ];
+
+  for (const check of checks) {
+    const fullPath = path.join(repoPath, check.file);
+    if (fs.existsSync(fullPath)) {
+      patterns.push(check.pattern);
+    }
+  }
+
+  // Check package.json for dependencies
+  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 };
+      dependencies.push(...Object.keys(deps).slice(0, 10));
+    } catch (e) {
+      // Ignore parse errors
+    }
+  }
+
+  if (patterns.length === 0) {
+    patterns.push('(Unable to detect patterns - provide --repo)');
+  }
+
+  return { patterns, dependencies };
+}
+
+function generateDesignOptions(feature: string, scope: string): DesignOption[] {
+  // Generate context-aware options based on feature keywords
+  const featureLower = feature.toLowerCase();
+
+  if (featureLower.includes('auth')) {
+    return [
+      {
+        name: 'NextAuth.js',
+        description: 'Use NextAuth.js for authentication with built-in providers',
+        pros: ['Battle-tested', 'Many OAuth providers', 'Session management included'],
+        cons: ['Opinionated structure', 'Some flexibility limits'],
+        recommended: true,
+      },
+      {
+        name: 'Custom OAuth',
+        description: 'Build custom OAuth implementation',
+        pros: ['Full control', 'No external dependencies'],
+        cons: ['More work', 'Security risks', 'Maintenance burden'],
+      },
+      {
+        name: 'Managed Service (Clerk/Auth0)',
+        description: 'Use a managed authentication service',
+        pros: ['Zero maintenance', 'Advanced features included'],
+        cons: ['Vendor lock-in', 'Monthly cost', 'Less control'],
+      },
+    ];
+  }
+
+  if (featureLower.includes('api') || featureLower.includes('endpoint')) {
+    return [
+      {
+        name: 'REST API',
+        description: 'Traditional REST endpoints with JSON',
+        pros: ['Simple', 'Well-understood', 'Good tooling'],
+        cons: ['Over/under-fetching', 'Multiple requests needed'],
+        recommended: true,
+      },
+      {
+        name: 'GraphQL',
+        description: 'GraphQL API with schema-first approach',
+        pros: ['Flexible queries', 'Strong typing', 'Single endpoint'],
+        cons: ['Complexity', 'Learning curve', 'Caching challenges'],
+      },
+      {
+        name: 'tRPC',
+        description: 'End-to-end typesafe APIs',
+        pros: ['Full type safety', 'No codegen', 'Great DX'],
+        cons: ['TypeScript only', 'Tighter coupling'],
+      },
+    ];
+  }
+
+  // Default options for general features
+  return [
+    {
+      name: 'Incremental Addition',
+      description: 'Add feature alongside existing code',
+      pros: ['Low risk', 'Quick to implement', 'Easy rollback'],
+      cons: ['May not optimize for feature', 'Technical debt possible'],
+      recommended: true,
+    },
+    {
+      name: 'Refactor First',
+      description: 'Refactor existing code, then add feature',
+      pros: ['Clean architecture', 'Better long-term'],
+      cons: ['More time', 'Higher initial risk'],
+    },
+    {
+      name: 'New Module',
+      description: 'Create isolated module for feature',
+      pros: ['Clean separation', 'Independent testing'],
+      cons: ['Integration overhead', 'Duplication possible'],
+    },
+  ];
+}

package/template/workers/dev-team/architect/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "commonjs",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/workers/dev-team/architect/worker.yaml

@@ -0,0 +1,128 @@
+worker:
+  id: architect
+  name: "Architect"
+  type: CodeWorker
+  version: "1.0"
+
+execution:
+  mode: on_demand
+  max_runtime: 15m
+  retry_attempts: 1
+
+context:
+  base:
+    - workers/public/dev-team/architect/
+    - workers/public/dev-team/architect/skills/
+    - knowledge/public/dev-team/patterns/
+  dynamic:
+    - pattern: "{target_repo}/"
+      when: always
+  exclude:
+    - node_modules/
+    - dist/
+    - "*.log"
+    - ".git/"
+
+verification:
+  post_execute:
+    - check: typescript
+      command: npm run typecheck
+  approval_required: true
+
+external_skills:
+  # Vercel React Best Practices - Architecture guidance
+  - vercel/react-best-practices
+  # Architecture-relevant patterns:
+  # - Strategic Suspense boundaries
+  # - Component composition for parallel fetching
+  # - Bundle splitting strategies
+  # - Server/client boundary decisions
+
+output:
+  destination: workspace/reports/dev-team/
+  format: both
+  naming: "{date}-architect-{task}.{ext}"
+
+mcp:
+  server:
+    command: node
+    args:
+      - dist/mcp-server.js
+    cwd: workers/public/dev-team/architect
+  tools:
+    - system_design
+    - api_design
+    - code_review_plan
+    - refactor_plan
+
+# State Machine (Loom pattern)
+state_machine:
+  enabled: true
+  max_retries: 1
+  hooks:
+    post_execute:
+      - auto_checkpoint
+      - log_metrics
+    on_error:
+      - log_error
+      - checkpoint_error_state
+
+instructions: |
+  # Architect
+
+  System design, planning, and technical decision-making.
+
+  ## Skills
+
+  | Skill | Description |
+  |-------|-------------|
+  | system-design | Design system architecture for feature |
+  | api-design | Design API contracts and interfaces |
+  | code-review-plan | Plan approach for code review |
+  | refactor-plan | Plan refactoring approach |
+
+  ## CLI Usage
+
+  ```bash
+  cd workers/public/dev-team/architect
+  node dist/index.js system-design --feature "user auth" --repo path/to/repo
+  node dist/index.js api-design --endpoint "/api/users" --repo path/to/repo
+  ```
+
+  ## Responsibilities
+
+  1. Analyze existing codebase architecture
+  2. Design new features to fit existing patterns
+  3. Define API contracts before implementation
+  4. Identify breaking changes and migration paths
+  5. Document architectural decisions
+
+  ## React Architecture Patterns (Vercel)
+
+  Data Loading:
+  - Strategic Suspense boundary placement
+  - Component composition for parallel data fetching
+  - Server vs Client component decisions
+
+  Performance:
+  - Bundle splitting strategy (dynamic imports)
+  - Avoid barrel file architectures
+  - Preloading based on user intent patterns
+
+  Server Components:
+  - Minimize RSC serialization boundaries
+  - Cross-request caching strategies
+  - React.cache() placement
+
+  ## Output
+
+  - Architecture decision records (ADR)
+  - API specifications (OpenAPI/TypeScript interfaces)
+  - Component diagrams (Mermaid)
+  - Implementation guides for other workers
+
+  ## Human-in-the-loop
+
+  - Present design options with trade-offs
+  - Get approval before defining contracts
+  - Surface breaking changes clearly