hungry-ghost-hive 0.3.0

package/src/config/schema.ts

@@ -0,0 +1,238 @@
+import { z } from 'zod';
+
+// Model configuration for each agent type
+const ModelConfigSchema = z.object({
+  provider: z.enum(['anthropic', 'openai']),
+  model: z.string(),
+  max_tokens: z.number().int().positive().default(8000),
+  temperature: z.number().min(0).max(2).default(0.5),
+  cli_tool: z.enum(['claude', 'codex', 'gemini']).optional().default('claude'),
+});
+
+// Models configuration for all agent types
+const ModelsConfigSchema = z.object({
+  tech_lead: ModelConfigSchema.default({
+    provider: 'anthropic',
+    model: 'claude-opus-4-20250514',
+    max_tokens: 16000,
+    temperature: 0.7,
+    cli_tool: 'claude',
+  }),
+  senior: ModelConfigSchema.default({
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 8000,
+    temperature: 0.5,
+    cli_tool: 'claude',
+  }),
+  intermediate: ModelConfigSchema.default({
+    provider: 'anthropic',
+    model: 'claude-haiku-3-5-20241022',
+    max_tokens: 4000,
+    temperature: 0.3,
+    cli_tool: 'claude',
+  }),
+  junior: ModelConfigSchema.default({
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    max_tokens: 4000,
+    temperature: 0.2,
+    cli_tool: 'claude',
+  }),
+  qa: ModelConfigSchema.default({
+    provider: 'anthropic',
+    model: 'claude-sonnet-4-20250514',
+    max_tokens: 8000,
+    temperature: 0.2,
+    cli_tool: 'claude',
+  }),
+});
+
+// Scaling rules
+const ScalingConfigSchema = z.object({
+  // Story points threshold before hiring additional senior
+  senior_capacity: z.number().int().positive().default(20),
+  // Complexity threshold for delegation to junior
+  junior_max_complexity: z.number().int().min(1).max(13).default(3),
+  // Complexity threshold for delegation to intermediate
+  intermediate_max_complexity: z.number().int().min(1).max(13).default(5),
+});
+
+// GitHub integration
+const GitHubConfigSchema = z.object({
+  // Base branch for PRs
+  base_branch: z.string().default('main'),
+  // PR template
+  pr_template: z.string().default(`## Story: {story_id}
+
+{description}
+
+### Acceptance Criteria
+{acceptance_criteria}
+
+### Changes
+{changes}`),
+});
+
+// QA configuration
+const QAConfigSchema = z.object({
+  // Commands to run for quality checks
+  quality_checks: z.array(z.string()).default(['npm run lint', 'npm run type-check']),
+  // Build command
+  build_command: z.string().default('npm run build'),
+  // Test command (optional)
+  test_command: z.string().optional(),
+});
+
+// Agent behavior configuration
+const AgentsConfigSchema = z.object({
+  // Polling interval for state checks (ms)
+  poll_interval: z.number().int().positive().default(5000),
+  // Max retries before escalation
+  max_retries: z.number().int().nonnegative().default(2),
+  // Token threshold for checkpoint
+  checkpoint_threshold: z.number().int().positive().default(14000),
+  // LLM call timeout in milliseconds (default: 30 minutes)
+  llm_timeout_ms: z.number().int().positive().default(1800000),
+  // Max retries for LLM calls on timeout
+  llm_max_retries: z.number().int().nonnegative().default(2),
+});
+
+// Manager daemon configuration
+const ManagerConfigSchema = z.object({
+  fast_poll_interval: z.number().int().positive().default(15000),
+  slow_poll_interval: z.number().int().positive().default(60000),
+});
+
+// Logging configuration
+const LoggingConfigSchema = z.object({
+  // Log level
+  level: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  // Retain logs for N days
+  retention_days: z.number().int().positive().default(30),
+});
+
+// Main configuration schema
+export const HiveConfigSchema = z.object({
+  version: z.string().default('1.0'),
+  models: ModelsConfigSchema.default({}),
+  scaling: ScalingConfigSchema.default({}),
+  github: GitHubConfigSchema.default({}),
+  qa: QAConfigSchema.default({}),
+  agents: AgentsConfigSchema.default({}),
+  manager: ManagerConfigSchema.default({}),
+  logging: LoggingConfigSchema.default({}),
+});
+
+// Export types
+export type ModelConfig = z.infer<typeof ModelConfigSchema>;
+export type ModelsConfig = z.infer<typeof ModelsConfigSchema>;
+export type ScalingConfig = z.infer<typeof ScalingConfigSchema>;
+export type GitHubConfig = z.infer<typeof GitHubConfigSchema>;
+export type QAConfig = z.infer<typeof QAConfigSchema>;
+export type AgentsConfig = z.infer<typeof AgentsConfigSchema>;
+export type ManagerConfig = z.infer<typeof ManagerConfigSchema>;
+export type LoggingConfig = z.infer<typeof LoggingConfigSchema>;
+export type HiveConfig = z.infer<typeof HiveConfigSchema>;
+
+// Default configuration
+export const DEFAULT_CONFIG: HiveConfig = HiveConfigSchema.parse({});
+
+// Generate default config YAML content
+export function generateDefaultConfigYaml(): string {
+  return `# Hive Orchestrator Configuration
+version: "1.0"
+
+# Model assignments per agent tier
+models:
+  tech_lead:
+    provider: anthropic
+    model: claude-opus-4-20250514
+    max_tokens: 16000
+    temperature: 0.7
+    # CLI tool used to spawn agents (claude, codex, or gemini)
+    cli_tool: claude
+
+  senior:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    max_tokens: 8000
+    temperature: 0.5
+    cli_tool: claude
+
+  intermediate:
+    provider: anthropic
+    model: claude-haiku-3-5-20241022
+    max_tokens: 4000
+    temperature: 0.3
+    cli_tool: claude
+
+  junior:
+    provider: openai
+    model: gpt-4o-mini
+    max_tokens: 4000
+    temperature: 0.2
+    cli_tool: claude
+
+  qa:
+    provider: anthropic
+    model: claude-sonnet-4-20250514
+    max_tokens: 8000
+    temperature: 0.2
+    cli_tool: claude
+
+# Team scaling rules
+scaling:
+  # Story points threshold before hiring additional senior
+  senior_capacity: 20
+  # Complexity threshold for delegation
+  junior_max_complexity: 3
+  intermediate_max_complexity: 5
+
+# GitHub integration
+github:
+  # Base branch for PRs
+  base_branch: main
+  # PR template
+  pr_template: |
+    ## Story: {story_id}
+
+    {description}
+
+    ### Acceptance Criteria
+    {acceptance_criteria}
+
+    ### Changes
+    {changes}
+
+# QA configuration
+qa:
+  # Commands to run for quality checks
+  quality_checks:
+    - npm run lint
+    - npm run type-check
+  # Build command
+  build_command: npm run build
+  # Test command (optional)
+  # test_command: npm test
+
+# Agent behavior
+agents:
+  # Polling interval for state checks (ms)
+  poll_interval: 5000
+  # Max retries before escalation
+  max_retries: 2
+  # Token threshold for checkpoint
+  checkpoint_threshold: 14000
+  # LLM call timeout in milliseconds (default: 30 minutes)
+  llm_timeout_ms: 1800000
+  # Max retries for LLM calls on timeout
+  llm_max_retries: 2
+
+# Logging
+logging:
+  level: info
+  # Retain logs for N days
+  retention_days: 30
+`;
+}

package/src/context-files/generator.ts

@@ -0,0 +1,132 @@
+/**
+ * Context File Content Generator
+ *
+ * Generates the actual content for context files based on CLI tool type
+ */
+
+import { claudeCodeTemplate, codexTemplate, geminiTemplate } from './templates.js';
+import type { ContextFileOptions } from './index.js';
+import type { StoryRow } from '../db/queries/stories.js';
+
+/**
+ * Generate context file content for the specified CLI tool
+ */
+export function generateContextFileContent(options: ContextFileOptions): string {
+  const { cliTool } = options;
+
+  // Get the appropriate template for the CLI tool
+  let template: (options: ContextFileOptions) => string;
+
+  switch (cliTool) {
+    case 'claude-code':
+      template = claudeCodeTemplate;
+      break;
+    case 'codex':
+      template = codexTemplate;
+      break;
+    case 'gemini':
+      template = geminiTemplate;
+      break;
+    default:
+      throw new Error(`Unsupported CLI tool: ${cliTool}`);
+  }
+
+  return template(options);
+}
+
+/**
+ * Format stories for display in context files
+ */
+export function formatStoriesForContext(stories: StoryRow[]): string {
+  if (stories.length === 0) {
+    return 'No active stories';
+  }
+
+  return stories
+    .map(story => `
+### ${story.id}: ${story.title}
+- **Status**: ${story.status}
+- **Complexity**: ${story.complexity_score || 'Not estimated'}
+- **Story Points**: ${story.story_points || 'Not estimated'}
+- **Description**: ${story.description}
+${story.acceptance_criteria && story.acceptance_criteria.length > 0
+        ? `**Acceptance Criteria**:\n${(Array.isArray(story.acceptance_criteria) ? story.acceptance_criteria : JSON.parse(story.acceptance_criteria || '[]')).map((c: string) => `  - ${c}`).join('\n')}`
+        : ''}`)
+    .join('\n\n');
+}
+
+/**
+ * Format quality check commands for display
+ */
+export function formatQualityChecks(commands: string[]): string {
+  return commands.map(cmd => `\`${cmd}\``).join('\n');
+}
+
+/**
+ * Format agent role description
+ */
+export function getAgentRoleDescription(agentType: string): string {
+  switch (agentType) {
+    case 'tech_lead':
+      return 'Tech Lead - Orchestrates multiple teams, manages cross-repo dependencies, and escalation endpoint';
+    case 'senior':
+      return 'Senior Developer - Team lead, estimates complexity, delegates work, reviews code';
+    case 'intermediate':
+      return 'Intermediate Developer - Handles moderate complexity tasks, works on delegated stories';
+    case 'junior':
+      return 'Junior Developer - Works on simple tasks under senior guidance, learns from code reviews';
+    case 'qa':
+      return 'QA Agent - Runs quality checks, builds, and validates code before PR submission';
+    default:
+      return `${agentType} Agent`;
+  }
+}
+
+/**
+ * Format hive msg command examples
+ */
+export function formatHiveMsgCommands(agentId?: string): string {
+  return `
+## Communication with Hive Team
+
+Use \`hive msg\` to communicate with other team members:
+
+\`\`\`bash
+# Send a message to your senior
+hive msg send hive-senior-<team> "Your question here"
+
+# Send a message to the tech lead
+hive msg send hive-tech-lead "Your question here"
+
+# Check your inbox
+hive msg inbox ${agentId || 'your-agent-id'}
+
+# Reply to a message
+hive msg reply <msg-id> "Your response here"
+\`\`\`
+
+${agentId ? `**Your Agent ID**: \`${agentId}\`` : ''}
+`;
+}
+
+/**
+ * Format git workflow instructions
+ */
+export function formatGitWorkflow(): string {
+  return `
+## Git Workflow
+
+1. **Create feature branch**: \`git checkout -b feature/<story-id>-<description>\`
+2. **Commit changes**: \`git commit -m "<message>"\` with clear, focused messages
+3. **Keep commits clean**: One logical change per commit
+4. **Push regularly**: \`git push origin feature/<story-id>-<description>\`
+5. **Create PR**: Use GitHub to create a PR with story ID in title
+6. **Link to story**: Include story ID in PR description for tracking
+
+### Naming Conventions
+
+- **Branches**: \`feature/STORY-123-short-description\`
+- **Commits**: \`STORY-123: Brief description of what changed\`
+- **PR Titles**: \`Story STORY-123: Feature title\`
+`;
+}

package/src/context-files/index.test.ts

@@ -0,0 +1,323 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdirSync, readFileSync, rmSync, existsSync } from 'fs';
+import {
+  getContextFileName,
+  getContextFilePath,
+  contextFileExists,
+  generateContextFile,
+  type ContextFileOptions,
+} from './index.js';
+import type { TeamRow } from '../db/queries/teams.js';
+import type { StoryRow } from '../db/queries/stories.js';
+import type { HiveConfig } from '../config/schema.js';
+
+describe('context-files module', () => {
+  let testDir: string;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `hive-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    mkdirSync(testDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(testDir)) {
+      rmSync(testDir, { recursive: true, force: true });
+    }
+  });
+
+  describe('getContextFileName', () => {
+    it('should return CLAUDE.md for claude-code', () => {
+      expect(getContextFileName('claude-code')).toBe('CLAUDE.md');
+    });
+
+    it('should return AGENTS.md for codex', () => {
+      expect(getContextFileName('codex')).toBe('AGENTS.md');
+    });
+
+    it('should return GEMINI.md for gemini', () => {
+      expect(getContextFileName('gemini')).toBe('GEMINI.md');
+    });
+  });
+
+  describe('getContextFilePath', () => {
+    it('should construct correct file path', () => {
+      const path = getContextFilePath('/repos/service-a', 'claude-code');
+      expect(path).toBe('/repos/service-a/CLAUDE.md');
+    });
+
+    it('should work for different CLI tools', () => {
+      const claudePath = getContextFilePath('/repo', 'claude-code');
+      const codexPath = getContextFilePath('/repo', 'codex');
+      const geminiPath = getContextFilePath('/repo', 'gemini');
+
+      expect(claudePath).toContain('CLAUDE.md');
+      expect(codexPath).toContain('AGENTS.md');
+      expect(geminiPath).toContain('GEMINI.md');
+    });
+  });
+
+  describe('contextFileExists', () => {
+    it('should return false when file does not exist', () => {
+      expect(contextFileExists(testDir, 'claude-code')).toBe(false);
+    });
+
+    it('should return true when file exists', () => {
+      const filePath = getContextFilePath(testDir, 'claude-code');
+      mkdirSync(testDir, { recursive: true });
+      require('fs').writeFileSync(filePath, 'test content');
+
+      expect(contextFileExists(testDir, 'claude-code')).toBe(true);
+    });
+  });
+
+  describe('generateContextFile', () => {
+    const mockTeam: TeamRow = {
+      id: 'team-test',
+      name: 'test-team',
+      repo_path: '',
+      repo_url: 'https://github.com/test/repo.git',
+      created_at: new Date().toISOString(),
+    };
+
+    const mockStory: StoryRow = {
+      id: 'STORY-001',
+      requirement_id: 'REQ-001',
+      team_id: 'team-test',
+      title: 'Implement authentication',
+      description: 'Add OAuth2 support',
+      acceptance_criteria: JSON.stringify(['User can login', 'Token is valid']),
+      complexity_score: 5,
+      story_points: 5,
+      status: 'in_progress',
+      assigned_agent_id: 'agent-001',
+      branch_name: 'feature/STORY-001-auth',
+      pr_url: 'https://github.com/test/repo/pull/1',
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+
+    const mockConfig: HiveConfig = {
+      version: '1.0',
+      models: {
+        tech_lead: { provider: 'anthropic', model: 'claude-opus', max_tokens: 16000, temperature: 0.7, cli_tool: 'claude' },
+        senior: { provider: 'anthropic', model: 'claude-sonnet', max_tokens: 8000, temperature: 0.5, cli_tool: 'claude' },
+        intermediate: { provider: 'anthropic', model: 'claude-haiku', max_tokens: 4000, temperature: 0.3, cli_tool: 'claude' },
+        junior: { provider: 'openai', model: 'gpt-4o-mini', max_tokens: 4000, temperature: 0.2, cli_tool: 'claude' },
+        qa: { provider: 'anthropic', model: 'claude-sonnet', max_tokens: 8000, temperature: 0.2, cli_tool: 'claude' },
+      },
+      scaling: { senior_capacity: 20, junior_max_complexity: 3, intermediate_max_complexity: 5 },
+      github: { base_branch: 'main', pr_template: '' },
+      qa: {
+        quality_checks: ['npm run lint', 'npm run type-check'],
+        build_command: 'npm run build',
+      },
+      agents: {
+        poll_interval: 5000,
+        max_retries: 2,
+        checkpoint_threshold: 14000,
+        llm_timeout_ms: 1800000,
+        llm_max_retries: 2,
+      },
+      manager: { fast_poll_interval: 15000, slow_poll_interval: 60000 },
+      logging: { level: 'info', retention_days: 30 },
+    };
+
+    it('should create a new context file if it does not exist', () => {
+      const team = { ...mockTeam, repo_path: testDir };
+      const options: ContextFileOptions = {
+        cliTool: 'claude-code',
+        team,
+        stories: [mockStory],
+        agentType: 'intermediate',
+        config: mockConfig,
+        agentId: 'agent-001',
+      };
+
+      generateContextFile(options);
+
+      expect(contextFileExists(testDir, 'claude-code')).toBe(true);
+      const content = readFileSync(getContextFilePath(testDir, 'claude-code'), 'utf-8');
+      expect(content).toContain('<!-- HIVE:START -->');
+      expect(content).toContain('<!-- HIVE:END -->');
+      expect(content).toContain('STORY-001');
+    });
+
+    it('should include story information in generated file', () => {
+      const team = { ...mockTeam, repo_path: testDir };
+      const options: ContextFileOptions = {
+        cliTool: 'claude-code',
+        team,
+        stories: [mockStory],
+        agentType: 'senior',
+        config: mockConfig,
+      };
+
+      generateContextFile(options);
+
+      const content = readFileSync(getContextFilePath(testDir, 'claude-code'), 'utf-8');
+      expect(content).toContain('STORY-001');
+      expect(content).toContain('Implement authentication');
+      expect(content).toContain('OAuth2');
+    });
+
+    it('should generate different content for different CLI tools', () => {
+      const team = { ...mockTeam, repo_path: testDir };
+      const baseOptions: ContextFileOptions = {
+        cliTool: 'claude-code',
+        team,
+        stories: [mockStory],
+        agentType: 'intermediate',
+        config: mockConfig,
+      };
+
+      // Generate for Claude Code
+      generateContextFile({ ...baseOptions, cliTool: 'claude-code' });
+      const claudeContent = readFileSync(getContextFilePath(testDir, 'claude-code'), 'utf-8');
+
+      // Clean up and generate for Codex
+      rmSync(testDir, { recursive: true, force: true });
+      mkdirSync(testDir, { recursive: true });
+
+      generateContextFile({ ...baseOptions, cliTool: 'codex' });
+      const codexContent = readFileSync(getContextFilePath(testDir, 'codex'), 'utf-8');
+
+      // Both should have markers and story info, but different headers
+      expect(claudeContent).toContain('Claude Code');
+      expect(codexContent).toContain('Codex');
+      expect(claudeContent).toContain('STORY-001');
+      expect(codexContent).toContain('STORY-001');
+    });
+
+    it('should update existing file preserving content outside markers', () => {
+      const team = { ...mockTeam, repo_path: testDir };
+      const filePath = getContextFilePath(testDir, 'claude-code');
+
+      // Write initial file with custom content
+      mkdirSync(testDir, { recursive: true });
+      const initialContent = `# My Custom Header
+
+This is my custom content that should be preserved.
+
+<!-- HIVE:START -->
+Old Hive content
+<!-- HIVE:END -->
+
+## Footer
+
+More custom content here.`;
+
+      require('fs').writeFileSync(filePath, initialContent);
+
+      // Generate new context
+      const options: ContextFileOptions = {
+        cliTool: 'claude-code',
+        team,
+        stories: [mockStory],
+        agentType: 'junior',
+        config: mockConfig,
+      };
+
+      generateContextFile(options);
+
+      const updatedContent = readFileSync(filePath, 'utf-8');
+
+      // Original content should be preserved
+      expect(updatedContent).toContain('# My Custom Header');
+      expect(updatedContent).toContain('This is my custom content');
+      expect(updatedContent).toContain('## Footer');
+      expect(updatedContent).toContain('More custom content here');
+
+      // Hive content should be updated
+      expect(updatedContent).toContain('STORY-001');
+      expect(updatedContent).not.toContain('Old Hive content');
+      expect(updatedContent).toContain('<!-- HIVE:START -->');
+      expect(updatedContent).toContain('<!-- HIVE:END -->');
+    });
+
+    it('should append Hive section if markers do not exist', () => {
+      const team = { ...mockTeam, repo_path: testDir };
+      const filePath = getContextFilePath(testDir, 'claude-code');
+
+      // Write initial file without markers
+      mkdirSync(testDir, { recursive: true });
+      const initialContent = '# Existing README\n\nSome content here.';
+      require('fs').writeFileSync(filePath, initialContent);
+
+      // Generate context
+      const options: ContextFileOptions = {
+        cliTool: 'claude-code',
+        team,
+        stories: [mockStory],
+        agentType: 'qa',
+        config: mockConfig,
+      };
+
+      generateContextFile(options);
+
+      const updatedContent = readFileSync(filePath, 'utf-8');
+
+      // Original content should be preserved
+      expect(updatedContent).toContain('# Existing README');
+      expect(updatedContent).toContain('Some content here');
+
+      // Hive content should be appended
+      expect(updatedContent).toContain('<!-- HIVE:START -->');
+      expect(updatedContent).toContain('STORY-001');
+    });
+
+    it('should work with empty stories list', () => {
+      const team = { ...mockTeam, repo_path: testDir };
+      const options: ContextFileOptions = {
+        cliTool: 'claude-code',
+        team,
+        stories: [],
+        agentType: 'senior',
+        config: mockConfig,
+      };
+
+      generateContextFile(options);
+
+      const content = readFileSync(getContextFilePath(testDir, 'claude-code'), 'utf-8');
+      expect(content).toContain('<!-- HIVE:START -->');
+      expect(content).toContain('No active stories');
+    });
+
+    it('should include quality check commands from config', () => {
+      const team = { ...mockTeam, repo_path: testDir };
+      const options: ContextFileOptions = {
+        cliTool: 'claude-code',
+        team,
+        stories: [mockStory],
+        agentType: 'intermediate',
+        config: mockConfig,
+      };
+
+      generateContextFile(options);
+
+      const content = readFileSync(getContextFilePath(testDir, 'claude-code'), 'utf-8');
+      expect(content).toContain('npm run lint');
+      expect(content).toContain('npm run type-check');
+      expect(content).toContain('npm run build');
+    });
+
+    it('should include agent ID when provided', () => {
+      const team = { ...mockTeam, repo_path: testDir };
+      const agentId = 'intermediate-abc123def456';
+      const options: ContextFileOptions = {
+        cliTool: 'claude-code',
+        team,
+        stories: [mockStory],
+        agentType: 'intermediate',
+        config: mockConfig,
+        agentId,
+      };
+
+      generateContextFile(options);
+
+      const content = readFileSync(getContextFilePath(testDir, 'claude-code'), 'utf-8');
+      expect(content).toContain(agentId);
+    });
+  });
+});