create-hq 5.0.0

package/template/workers/dev-team/project-manager/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hq/project-manager",
+  "version": "1.0.0",
+  "description": "Project orchestration: PRD lifecycle, issue selection, learning aggregation",
+  "main": "dist/index.js",
+  "bin": {
+    "project-manager": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "ts-node src/index.ts",
+    "mcp": "node dist/mcp-server.js"
+  },
+  "keywords": ["hq", "worker", "project-manager", "prd", "orchestration"],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.2",
+    "ts-node": "^10.9.2"
+  }
+}

package/template/workers/dev-team/project-manager/skills/create-prd.md

@@ -0,0 +1,66 @@
+# create-prd
+
+Create new PRD from requirements input.
+
+## Arguments
+
+`$ARGUMENTS` = `--name <name>` (required)
+
+Optional:
+- `--input <file>` - Input requirements file (markdown)
+- `--template <type>` - Template: feature|bugfix|refactor
+
+## Process
+
+1. Read input requirements (from file or prompt)
+2. Extract user stories from requirements
+3. Break into epics if multiple areas
+4. For each story:
+   - Generate acceptance criteria
+   - Estimate priority
+   - Suggest worker sequence
+   - Identify dependencies
+5. Present draft PRD to human for review
+6. Incorporate feedback
+7. Write to `projects/{name}/prd.json`
+8. Optionally create beads via `bd init --project {name}`
+
+## Output
+
+PRD JSON file with structure:
+```json
+{
+  "project": "feature-name",
+  "created": "2026-01-23",
+  "epics": [{
+    "id": "E1",
+    "title": "Epic Title",
+    "stories": [{
+      "id": "US-001",
+      "title": "Story Title",
+      "description": "As a...",
+      "acceptance_criteria": [...],
+      "priority": 1,
+      "passes": false,
+      "worker_hints": ["architect", "backend-dev"]
+    }]
+  }]
+}
+```
+
+## Example
+
+```bash
+node dist/index.js create-prd --name user-auth --input docs/auth-requirements.md
+
+# Output:
+# Created PRD with 1 epic, 5 user stories
+# - E1: User Authentication (5 stories)
+#   - US-001: Login endpoint (priority 1)
+#   - US-002: Logout endpoint (priority 1)
+#   - US-003: Session management (priority 2)
+#   - US-004: Remember me (priority 3)
+#   - US-005: Password reset (priority 2)
+#
+# Review and approve? [y/n/edit]
+```

package/template/workers/dev-team/project-manager/skills/next-issue.md

@@ -0,0 +1,51 @@
+# next-issue
+
+Select next issue from project PRD/beads to work on.
+
+## Arguments
+
+`$ARGUMENTS` = `--project <name>` (required)
+
+Optional:
+- `--filter <label>` - Filter by label/tag
+- `--priority <high|medium|low>` - Filter by priority
+
+## Process
+
+1. Load project PRD from `projects/{project}/prd.json`
+2. Load beads from project via `bd ls --project {project}`
+3. Filter issues where `passes: false`
+4. Check dependencies - only issues where all `dependsOn` items pass
+5. Score by:
+   - Priority field (higher = first)
+   - Blocking count (more blockers = first)
+   - Complexity estimate (simpler = first for momentum)
+6. Present top 3 candidates to human
+7. Wait for human selection or approval of recommendation
+
+## Output
+
+Selected issue with:
+- Issue ID and title
+- Acceptance criteria
+- Suggested worker sequence (from `worker_hints` or auto-detected)
+- Files likely to be modified
+- Dependencies and blockers
+
+## Example
+
+```bash
+node dist/index.js next-issue --project auth-feature
+
+# Output:
+# Recommended: US-003 "Implement logout endpoint"
+# Priority: 1, Blocks: 2 other stories
+# Workers: backend-dev → qa-tester
+# Files: src/api/auth.ts, src/middleware/session.ts
+#
+# Alternatives:
+# - US-004 "Add remember me checkbox" (Priority: 2)
+# - US-005 "Session timeout handling" (Priority: 2)
+#
+# Proceed with US-003? [y/n/select other]
+```

package/template/workers/dev-team/project-manager/skills/project-status.md

@@ -0,0 +1,59 @@
+# project-status
+
+Show project progress, blockers, and next steps.
+
+## Arguments
+
+`$ARGUMENTS` = `--project <name>` (required)
+
+Optional:
+- `--verbose` - Show detailed story status
+- `--format <table|json|markdown>` - Output format
+
+## Process
+
+1. Load PRD from `projects/{project}/prd.json`
+2. Load beads status via `bd ls --project {project}`
+3. Calculate metrics:
+   - Total stories, completed, in-progress, blocked
+   - Completion percentage
+   - Blockers (failed stories, unmet dependencies)
+4. Identify:
+   - What's blocking progress
+   - Next recommended action
+   - Estimated remaining work
+5. Present status summary
+
+## Output
+
+Status report with:
+- Progress bar and percentage
+- Story breakdown by status
+- Blockers and recommendations
+- Next steps
+
+## Example
+
+```bash
+node dist/index.js project-status --project auth-feature
+
+# Output:
+# === auth-feature ===
+# Progress: ████████░░ 80% (4/5 stories)
+#
+# ✅ Completed (4):
+#   - US-001: Login endpoint
+#   - US-002: Logout endpoint
+#   - US-003: Session management
+#   - US-005: Password reset
+#
+# 🔄 In Progress (0)
+#
+# ❌ Pending (1):
+#   - US-004: Remember me (blocked by: none)
+#
+# 🚧 Blockers: None
+#
+# Next: Run task-executor on US-004
+# Estimated: 1 more iteration
+```

package/template/workers/dev-team/project-manager/skills/update-learnings.md

@@ -0,0 +1,65 @@
+# update-learnings
+
+Route learnings from completed tasks to appropriate knowledge locations.
+
+## Arguments
+
+`$ARGUMENTS` = learning report from task-executor (JSON or structured text)
+
+Optional:
+- `--project <name>` - Project context
+- `--dry-run` - Show routing without writing
+
+## Process
+
+1. Parse learning report
+2. Categorize each learning:
+   - **project-specific**: Unique to this project context
+   - **pattern**: Reusable code/design pattern
+   - **troubleshooting**: Error/fix that others may encounter
+   - **workflow**: Worker sequence that worked well
+3. Route to appropriate location:
+   - Project-specific → `projects/{name}/learnings/`
+   - Pattern → `knowledge/public/dev-team/patterns/{category}/`
+   - Troubleshooting → `knowledge/public/dev-team/troubleshooting/`
+   - Workflow → `knowledge/public/dev-team/workflows/`
+4. Format as markdown with standard template
+5. Present routing plan to human
+6. Write files after approval
+7. Update relevant CLAUDE.md if patterns affect guidance
+
+## Learning Categories
+
+| Category | Location | Example |
+|----------|----------|---------|
+| project | projects/{name}/learnings/ | "API uses custom auth header X-Token" |
+| pattern | knowledge/public/dev-team/patterns/ | "Retry pattern for flaky external APIs" |
+| troubleshoot | knowledge/public/dev-team/troubleshooting/ | "ESLint fails on CI but not local" |
+| workflow | knowledge/public/dev-team/workflows/ | "For DB-heavy: database-dev before architect" |
+
+## Output
+
+- Markdown files written to knowledge locations
+- Summary of what was written where
+
+## Example
+
+```bash
+node dist/index.js update-learnings --project auth-feature
+
+# Input (from task-executor):
+# {
+#   "task": "US-003",
+#   "learnings": [
+#     {"type": "pattern", "content": "Session tokens use JWT with 15m expiry"},
+#     {"type": "troubleshoot", "content": "Redis connection must be established before auth middleware"}
+#   ]
+# }
+
+# Output:
+# Routing learnings:
+# - [pattern] → knowledge/public/dev-team/patterns/backend/jwt-session-tokens.md
+# - [troubleshoot] → knowledge/public/dev-team/troubleshooting/redis-auth-order.md
+#
+# Approve routing? [y/n/edit]
+```

package/template/workers/dev-team/project-manager/src/index.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { nextIssue } from './skills/next-issue';
+import { createPrd } from './skills/create-prd';
+import { updateLearnings } from './skills/update-learnings';
+import { projectStatus } from './skills/project-status';
+
+const program = new Command();
+
+program
+  .name('project-manager')
+  .description('Project orchestration: PRD lifecycle, issue selection, learning aggregation')
+  .version('1.0.0');
+
+program
+  .command('next-issue')
+  .description('Select next issue from project to work on')
+  .requiredOption('--project <name>', 'Project name')
+  .option('--filter <label>', 'Filter by label')
+  .option('--priority <level>', 'Filter by priority (high|medium|low)')
+  .action(async (options) => {
+    await nextIssue(options);
+  });
+
+program
+  .command('create-prd')
+  .description('Create new PRD from requirements')
+  .requiredOption('--name <name>', 'Project name')
+  .option('--input <file>', 'Input requirements file')
+  .option('--template <type>', 'Template type (feature|bugfix|refactor)')
+  .action(async (options) => {
+    await createPrd(options);
+  });
+
+program
+  .command('update-learnings')
+  .description('Route learnings to appropriate knowledge locations')
+  .option('--project <name>', 'Project context')
+  .option('--dry-run', 'Show routing without writing')
+  .action(async (options) => {
+    await updateLearnings(options);
+  });
+
+program
+  .command('project-status')
+  .description('Show project progress and blockers')
+  .requiredOption('--project <name>', 'Project name')
+  .option('--verbose', 'Show detailed story status')
+  .option('--format <type>', 'Output format (table|json|markdown)')
+  .action(async (options) => {
+    await projectStatus(options);
+  });
+
+program.parse();

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

@@ -0,0 +1,207 @@
+#!/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: 'project-manager',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'next_issue',
+        description: 'Select next issue from project PRD/beads to work on',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            project: {
+              type: 'string',
+              description: 'Project name',
+            },
+            filter: {
+              type: 'string',
+              description: 'Filter by label (optional)',
+            },
+            priority: {
+              type: 'string',
+              enum: ['high', 'medium', 'low'],
+              description: 'Filter by priority (optional)',
+            },
+          },
+          required: ['project'],
+        },
+      },
+      {
+        name: 'create_prd',
+        description: 'Create new PRD from requirements',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Project name',
+            },
+            input: {
+              type: 'string',
+              description: 'Path to input requirements file (optional)',
+            },
+            template: {
+              type: 'string',
+              enum: ['feature', 'bugfix', 'refactor'],
+              description: 'Template type (optional, default: feature)',
+            },
+          },
+          required: ['name'],
+        },
+      },
+      {
+        name: 'update_learnings',
+        description: 'Route learnings to appropriate knowledge locations',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            project: {
+              type: 'string',
+              description: 'Project context (optional)',
+            },
+            learnings: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  type: {
+                    type: 'string',
+                    enum: ['project', 'pattern', 'troubleshoot', 'workflow'],
+                  },
+                  category: {
+                    type: 'string',
+                    description: 'Category for patterns (e.g., backend, frontend)',
+                  },
+                  content: {
+                    type: 'string',
+                    description: 'The learning content',
+                  },
+                },
+                required: ['type', 'content'],
+              },
+              description: 'Array of learnings to route',
+            },
+            dryRun: {
+              type: 'boolean',
+              description: 'Show routing without writing (optional)',
+            },
+          },
+          required: ['learnings'],
+        },
+      },
+      {
+        name: 'project_status',
+        description: 'Show project progress and blockers',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            project: {
+              type: 'string',
+              description: 'Project name',
+            },
+            verbose: {
+              type: 'boolean',
+              description: 'Show detailed story status (optional)',
+            },
+            format: {
+              type: 'string',
+              enum: ['table', 'json', 'markdown'],
+              description: 'Output format (optional, default: table)',
+            },
+          },
+          required: ['project'],
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'next_issue': {
+        // Import and call the skill
+        const { nextIssue } = await import('./skills/next-issue');
+        // Capture console output
+        const result = await captureOutput(() => nextIssue(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      case 'create_prd': {
+        const { createPrd } = await import('./skills/create-prd');
+        const result = await captureOutput(() => createPrd(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      case 'update_learnings': {
+        const { updateLearnings } = await import('./skills/update-learnings');
+        const result = await captureOutput(() => updateLearnings(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      case 'project_status': {
+        const { projectStatus } = await import('./skills/project-status');
+        const result = await captureOutput(() => projectStatus(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,
+    };
+  }
+});
+
+// Helper to capture console output
+async function captureOutput(fn: () => Promise<void>): 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');
+}
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/template/workers/dev-team/project-manager/src/skills/create-prd.ts

@@ -0,0 +1,86 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface CreatePrdOptions {
+  name: string;
+  input?: string;
+  template?: string;
+}
+
+export async function createPrd(options: CreatePrdOptions): Promise<void> {
+  const { name, input, template = 'feature' } = options;
+
+  const projectDir = path.join(process.cwd(), '..', '..', '..', 'projects', name);
+  const prdPath = path.join(projectDir, 'prd.json');
+
+  // Check if PRD already exists
+  if (fs.existsSync(prdPath)) {
+    console.error(`PRD already exists at ${prdPath}`);
+    console.log('Use project-status to view current state.');
+    process.exit(1);
+  }
+
+  // Read input requirements if provided
+  let requirements = '';
+  if (input && fs.existsSync(input)) {
+    requirements = fs.readFileSync(input, 'utf-8');
+    console.log(`Read requirements from ${input}`);
+  }
+
+  // Create project directory
+  if (!fs.existsSync(projectDir)) {
+    fs.mkdirSync(projectDir, { recursive: true });
+    console.log(`Created project directory: ${projectDir}`);
+  }
+
+  // Create skeleton PRD
+  const prd = {
+    project: name,
+    created: new Date().toISOString().split('T')[0],
+    template,
+    epics: [
+      {
+        id: 'E1',
+        title: 'Main Epic',
+        stories: [
+          {
+            id: 'US-001',
+            title: 'First User Story',
+            description: 'As a user, I want to...',
+            acceptance_criteria: [
+              'Criterion 1',
+              'Criterion 2'
+            ],
+            priority: 1,
+            passes: false,
+            worker_hints: ['architect', 'backend-dev', 'qa-tester']
+          }
+        ]
+      }
+    ]
+  };
+
+  // Write PRD
+  fs.writeFileSync(prdPath, JSON.stringify(prd, null, 2));
+  console.log(`\nCreated PRD at ${prdPath}`);
+
+  console.log('\n=== PRD Structure ===');
+  console.log(`Project: ${name}`);
+  console.log(`Template: ${template}`);
+  console.log(`Epics: 1`);
+  console.log(`Stories: 1 (placeholder)`);
+
+  console.log('\n[Human action required]');
+  console.log('Edit the PRD to add your user stories:');
+  console.log(`  ${prdPath}`);
+
+  if (requirements) {
+    console.log('\nInput requirements were loaded. Consider:');
+    console.log('  1. Breaking requirements into user stories');
+    console.log('  2. Adding acceptance criteria for each');
+    console.log('  3. Setting priorities and worker hints');
+  }
+
+  console.log('\nOnce ready, create beads with:');
+  console.log(`  bd init --project ${name}`);
+}