create-hq 5.0.0

package/template/workers/dev-team/task-executor/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@hq/task-executor",
+  "version": "1.0.0",
+  "description": "Execute issues by routing to workers and managing execution loop",
+  "main": "dist/index.js",
+  "bin": {
+    "task-executor": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "dev": "ts-node src/index.ts",
+    "mcp": "node dist/mcp-server.js"
+  },
+  "keywords": ["hq", "worker", "task-executor", "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/task-executor/skills/analyze-issue.md

@@ -0,0 +1,101 @@
+# analyze-issue
+
+Analyze issue to determine required workers and execution sequence.
+
+## Arguments
+
+`$ARGUMENTS` = `--issue <id> --project <name>` (required)
+
+Optional:
+- `--repo <path>` - Target repository for file analysis
+
+## Process
+
+1. **Load Issue**
+   - Read from PRD or beads
+   - Parse title, description, acceptance criteria
+
+2. **Check Worker Hints**
+   - If `worker_hints` field exists, use as base
+   - Validate hints are valid worker IDs
+
+3. **Auto-Detect Workers**
+   If no hints, analyze based on:
+   - Keywords in title/description
+   - File patterns in acceptance criteria
+   - Project type (frontend/backend/fullstack)
+
+4. **Determine Sequence**
+   Standard sequences:
+   - architect always first (if system design needed)
+   - database-dev before backend-dev (if schema changes)
+   - backend-dev before frontend-dev (if API needed)
+   - qa-tester always last
+   - code-reviewer after all dev workers
+
+5. **Estimate Scope**
+   - Files likely to be modified
+   - Complexity score (simple/medium/complex)
+   - Estimated phases
+
+6. **Present Analysis**
+   - Show worker sequence
+   - Show reasoning
+   - Ask for confirmation
+
+## Worker Detection Rules
+
+| Pattern | Workers |
+|---------|---------|
+| "API", "endpoint", "route" | backend-dev |
+| "database", "schema", "migration" | database-dev |
+| "component", "UI", "page" | frontend-dev |
+| "animation", "transition", "polish" | motion-designer |
+| "CI/CD", "deploy", "pipeline" | infra-dev |
+| "test", "coverage", "accessibility" | qa-tester |
+| "architecture", "design", "refactor" | architect |
+
+## Output
+
+Analysis report:
+```json
+{
+  "issue": "US-003",
+  "title": "Implement logout endpoint",
+  "workers": ["backend-dev", "qa-tester"],
+  "sequence": [
+    {"worker": "backend-dev", "phase": "Create logout API endpoint"},
+    {"worker": "qa-tester", "phase": "Verify logout functionality"}
+  ],
+  "estimated_files": ["src/api/auth.ts", "src/middleware/session.ts"],
+  "complexity": "simple",
+  "reasoning": "Detected 'endpoint' keyword, no frontend changes mentioned"
+}
+```
+
+## Example
+
+```bash
+node dist/index.js analyze-issue --issue US-003 --project auth-feature
+
+# Output:
+# === Analysis: US-003 ===
+#
+# Title: Implement logout endpoint
+#
+# Detected patterns:
+#   - "endpoint" → backend-dev
+#   - No UI changes → skip frontend-dev
+#
+# Recommended sequence:
+#   1. backend-dev: Create logout API endpoint
+#   2. qa-tester: Verify logout functionality
+#
+# Estimated files:
+#   - src/api/auth.ts
+#   - src/middleware/session.ts
+#
+# Complexity: simple (2 phases, ~2 files)
+#
+# [Confirm sequence? y/n/modify]
+```

package/template/workers/dev-team/task-executor/skills/execute.md

@@ -0,0 +1,133 @@
+# execute
+
+Execute issue end-to-end: analyze, spawn workers, validate, report learnings.
+
+## Arguments
+
+`$ARGUMENTS` = `--issue <id> --project <name>` (required)
+
+Optional:
+- `--repo <path>` - Target repository path
+- `--skip-validation` - Skip back pressure checks (not recommended)
+
+## Process
+
+1. **Load Issue**
+   - Read issue from PRD or beads
+   - Validate issue exists and is not already passing
+
+2. **Analyze & Plan**
+   - Determine required workers (from hints or auto-detect)
+   - Order workers by dependency
+   - Estimate scope and files affected
+   - Present plan to human for approval
+
+3. **For Each Worker Phase**
+   ```
+   a. BEFORE: Show "Spawning {worker} for {description}"
+      → Wait for human: approve / inject context / skip
+
+   b. EXECUTE: Spawn worker via Claude Task tool
+      - Pass focused context (issue spec + relevant files)
+      - Worker executes with its own context isolation
+
+   c. AFTER: Show results
+      - Files changed
+      - Test results
+      - Any warnings or notes
+      → Wait for human: approve / request changes / rollback
+
+   d. VALIDATE: Run back pressure checks
+      - npm run typecheck
+      - npm run lint
+      - npm run test (if applicable)
+      → If fail: surface error, offer retry or fix
+
+   e. COMMIT: Create commit for this phase
+      → Human approves commit message
+   ```
+
+4. **On Completion**
+   - Mark issue as passing in PRD/beads
+   - Extract learnings from execution
+   - Format learnings report
+   - Return to project-manager
+
+5. **On Failure**
+   - Log failure point and error
+   - Offer options: retry / rollback / escalate
+   - Never auto-proceed on ambiguity
+
+## Worker Spawn Pattern
+
+Using Claude Code's Task tool:
+```typescript
+// Spawn a worker as subagent
+Task({
+  description: "Backend dev: implement API endpoint",
+  prompt: `
+    Execute backend-dev worker for issue ${issueId}
+
+    Context:
+    - Issue: ${issue.title}
+    - Acceptance criteria: ${issue.acceptance_criteria}
+    - Files to modify: ${files.join(', ')}
+
+    Instructions:
+    1. Read the target files
+    2. Implement the required changes
+    3. Run typecheck and lint
+    4. Report completion with changes made
+  `,
+  subagent_type: "general-purpose"
+})
+```
+
+## Output
+
+Execution report with:
+- Issue status (pass/fail)
+- Phases completed
+- Files changed
+- Validation results
+- Learnings extracted
+- Commit hashes
+
+## Example
+
+```bash
+node dist/index.js execute --issue US-003 --project auth-feature --repo repos/private/my-app
+
+# Output:
+# === Executing US-003: Implement logout endpoint ===
+#
+# Planned phases:
+# 1. backend-dev: Create logout API endpoint
+# 2. qa-tester: Verify logout functionality
+#
+# [Approve plan? y/n]
+# > y
+#
+# Phase 1: Spawning backend-dev...
+# [Approve? y/inject/skip]
+# > y
+#
+# backend-dev completed:
+#   Changed: src/api/auth.ts (+25 lines)
+#   Tests: 3 passing
+#
+# [Approve changes? y/n/rollback]
+# > y
+#
+# Validation:
+#   ✅ typecheck passed
+#   ✅ lint passed
+#   ✅ tests passed
+#
+# Phase 2: Spawning qa-tester...
+# ...
+#
+# === Issue US-003 Complete ===
+# Learnings:
+#   - [pattern] Session invalidation via Redis DEL command
+```

package/template/workers/dev-team/task-executor/skills/report-learnings.md

@@ -0,0 +1,106 @@
+# report-learnings
+
+Extract and format learnings from task execution.
+
+## Arguments
+
+`$ARGUMENTS` = execution context (from execute skill)
+
+Optional:
+- `--verbose` - Include detailed execution trace
+
+## Process
+
+1. **Review Execution**
+   - Phases completed
+   - Errors encountered
+   - Retries needed
+   - Time per phase
+
+2. **Extract Learnings**
+   Categories:
+   - **Pattern**: Reusable code/design pattern discovered
+   - **Troubleshoot**: Error/fix that others may encounter
+   - **Workflow**: Worker sequence that worked well
+   - **Project**: Context specific to this project
+
+3. **Analyze Effectiveness**
+   - Did worker sequence work well?
+   - Any phases that should be reordered?
+   - Context that helped or hurt?
+
+4. **Format Report**
+   - Structured JSON for project-manager
+   - Human-readable summary
+
+5. **Surface for Approval**
+   - Show extracted learnings
+   - Human confirms or edits
+   - Ready for update-learnings skill
+
+## Learning Extraction Rules
+
+| Signal | Learning Type |
+|--------|---------------|
+| New code pattern | pattern |
+| Error + fix | troubleshoot |
+| Sequence worked well | workflow |
+| Project-specific context | project |
+
+## Output
+
+Learnings report:
+```json
+{
+  "task": "US-003",
+  "project": "auth-feature",
+  "execution": {
+    "phases": 2,
+    "retries": 0,
+    "duration": "5m"
+  },
+  "learnings": [
+    {
+      "type": "pattern",
+      "category": "backend",
+      "content": "Session invalidation via Redis DEL command with TTL fallback"
+    },
+    {
+      "type": "workflow",
+      "content": "For auth endpoints: backend-dev → qa-tester is sufficient, no architect needed"
+    }
+  ],
+  "recommendations": [
+    "Consider adding session tests to smoke-test suite"
+  ]
+}
+```
+
+## Example
+
+```bash
+node dist/index.js report-learnings
+
+# Output:
+# === Learnings from US-003 ===
+#
+# Execution summary:
+#   - 2 phases completed
+#   - 0 retries needed
+#   - Duration: 5 minutes
+#
+# Extracted learnings:
+#
+# 1. [pattern/backend]
+#    Session invalidation via Redis DEL command with TTL fallback
+#    Source: backend-dev phase, src/api/auth.ts:45-52
+#
+# 2. [workflow]
+#    For auth endpoints: backend-dev → qa-tester is sufficient
+#    Reasoning: No system design needed for simple endpoints
+#
+# Recommendations:
+#   - Consider adding session tests to smoke-test suite
+#
+# [Approve learnings? y/n/edit]
+```

package/template/workers/dev-team/task-executor/skills/validate-completion.md

@@ -0,0 +1,121 @@
+# validate-completion
+
+Run back pressure checks on completed work.
+
+## Arguments
+
+`$ARGUMENTS` = `--repo <path>` (required)
+
+Optional:
+- `--checks <list>` - Comma-separated checks to run (default: all)
+- `--strict` - Fail on warnings
+
+## Process
+
+1. **Run Type Check**
+   ```bash
+   npm run typecheck
+   ```
+   - Must pass with zero errors
+   - Warnings logged but don't fail
+
+2. **Run Linter**
+   ```bash
+   npm run lint
+   ```
+   - Must pass with zero errors
+   - Auto-fix if possible
+
+3. **Run Tests**
+   ```bash
+   npm test
+   ```
+   - All tests must pass
+   - New code should have coverage
+
+4. **Run Build** (if applicable)
+   ```bash
+   npm run build
+   ```
+   - Build must succeed
+   - No runtime errors
+
+5. **E2E Manifest Check** (if project has E2E tests)
+   Skip if the repo does not have an E2E test infrastructure.
+   ```bash
+   npm run check-coverage
+   ```
+   - All app routes must have test coverage in manifest
+   - Exit code 1 = uncovered pages exist
+   ```bash
+   npm run generate-manifest && git diff --quiet tests/e2e/manifest.json
+   ```
+   - If diff is non-empty, manifest is stale
+   - Fail with: "Run `npm run generate-manifest` and commit the updated manifest"
+
+6. **Report Results**
+   - Show pass/fail for each check
+   - Surface errors clearly
+   - Suggest fixes if possible
+
+## Checks
+
+| Check | Command | Required |
+|-------|---------|----------|
+| typecheck | npm run typecheck | Yes |
+| lint | npm run lint | Yes |
+| test | npm test | Yes (if tests exist) |
+| build | npm run build | No (optional) |
+| e2e-manifest | npm run check-coverage + generate-manifest drift | Yes (if E2E tests exist) |
+
+## Output
+
+Validation report:
+```
+Validation Results:
+  typecheck: passed (0 errors)
+  lint: passed (0 errors, 2 warnings)
+  test: passed (45 tests, 100% passing)
+  build: skipped
+  e2e-manifest: passed (all pages covered, manifest fresh)
+
+Overall: PASS
+```
+
+Or on failure:
+```
+Validation Results:
+  typecheck: passed
+  lint: failed (3 errors)
+     - src/api/auth.ts:42 - Unexpected any
+     - src/api/auth.ts:58 - Missing return type
+     - src/api/auth.ts:72 - Unused variable 'temp'
+  test: skipped (lint failed)
+
+Overall: FAIL
+Suggestion: Fix lint errors, then re-run
+```
+
+## Example
+
+```bash
+node dist/index.js validate-completion --repo ~/repos/my-app
+
+# Output:
+# Running validation checks...
+#
+# [1/3] typecheck...
+#   passed (0 errors)
+#
+# [2/3] lint...
+#   passed (0 errors, 2 warnings)
+#   Warnings:
+#     - src/api/auth.ts:42 - Consider using explicit type
+#     - src/api/auth.ts:58 - Prefer const over let
+#
+# [3/3] test...
+#   passed (45 tests)
+#
+# Overall: PASS
+# Ready to commit.
+```

package/template/workers/dev-team/task-executor/src/index.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { execute } from './skills/execute';
+import { analyzeIssue } from './skills/analyze-issue';
+import { validateCompletion } from './skills/validate-completion';
+import { reportLearnings } from './skills/report-learnings';
+
+const program = new Command();
+
+program
+  .name('task-executor')
+  .description('Execute issues by routing to workers and managing execution loop')
+  .version('1.0.0');
+
+program
+  .command('execute')
+  .description('Execute issue end-to-end: analyze, spawn workers, validate, report')
+  .requiredOption('--issue <id>', 'Issue ID')
+  .requiredOption('--project <name>', 'Project name')
+  .option('--repo <path>', 'Target repository path')
+  .option('--skip-validation', 'Skip back pressure checks')
+  .action(async (options) => {
+    await execute(options);
+  });
+
+program
+  .command('analyze-issue')
+  .description('Analyze issue to determine worker sequence')
+  .requiredOption('--issue <id>', 'Issue ID')
+  .requiredOption('--project <name>', 'Project name')
+  .option('--repo <path>', 'Target repository for file analysis')
+  .action(async (options) => {
+    await analyzeIssue(options);
+  });
+
+program
+  .command('validate-completion')
+  .description('Run back pressure checks on completed work')
+  .requiredOption('--repo <path>', 'Repository path')
+  .option('--checks <list>', 'Comma-separated checks to run')
+  .option('--strict', 'Fail on warnings')
+  .action(async (options) => {
+    await validateCompletion(options);
+  });
+
+program
+  .command('report-learnings')
+  .description('Extract and format learnings from execution')
+  .option('--verbose', 'Include detailed execution trace')
+  .action(async (options) => {
+    await reportLearnings(options);
+  });
+
+program.parse();

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

@@ -0,0 +1,139 @@
+#!/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: 'task-executor',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: 'execute',
+        description: 'Execute issue end-to-end: analyze, spawn workers, validate, report',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            issue: { type: 'string', description: 'Issue ID' },
+            project: { type: 'string', description: 'Project name' },
+            repo: { type: 'string', description: 'Target repository path' },
+            skipValidation: { type: 'boolean', description: 'Skip back pressure checks' },
+          },
+          required: ['issue', 'project'],
+        },
+      },
+      {
+        name: 'analyze_issue',
+        description: 'Analyze issue to determine worker sequence',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            issue: { type: 'string', description: 'Issue ID' },
+            project: { type: 'string', description: 'Project name' },
+            repo: { type: 'string', description: 'Target repository for file analysis' },
+          },
+          required: ['issue', 'project'],
+        },
+      },
+      {
+        name: 'validate_completion',
+        description: 'Run back pressure checks on completed work',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            repo: { type: 'string', description: 'Repository path' },
+            checks: { type: 'string', description: 'Comma-separated checks to run' },
+            strict: { type: 'boolean', description: 'Fail on warnings' },
+          },
+          required: ['repo'],
+        },
+      },
+      {
+        name: 'report_learnings',
+        description: 'Extract and format learnings from execution',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            verbose: { type: 'boolean', description: 'Include detailed execution trace' },
+          },
+        },
+      },
+    ],
+  };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'execute': {
+        const { execute } = await import('./skills/execute');
+        const result = await captureOutput(() => execute(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      case 'analyze_issue': {
+        const { analyzeIssue } = await import('./skills/analyze-issue');
+        const result = await captureOutput(() => analyzeIssue(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      case 'validate_completion': {
+        const { validateCompletion } = await import('./skills/validate-completion');
+        const result = await captureOutput(() => validateCompletion(args as any));
+        return { content: [{ type: 'text', text: result }] };
+      }
+
+      case 'report_learnings': {
+        const { reportLearnings } = await import('./skills/report-learnings');
+        const result = await captureOutput(() => reportLearnings(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);