@specforge/cli 0.1.0

package/dist/validation/ticket-validation.js

@@ -0,0 +1,188 @@
+const validationRules = {
+  small: {
+    requiresImplementation: false,
+    requiresTechnicalDetails: false,
+    requiresNotes: false,
+    minSteps: 0,
+    minAcceptanceCriteria: 1,
+    requiresFileInfo: false
+  },
+  medium: {
+    requiresImplementation: true,
+    requiresTechnicalDetails: false,
+    requiresNotes: false,
+    minSteps: 2,
+    minAcceptanceCriteria: 2,
+    requiresFileInfo: false
+  },
+  large: {
+    requiresImplementation: true,
+    requiresTechnicalDetails: true,
+    requiresNotes: false,
+    minSteps: 4,
+    minAcceptanceCriteria: 3,
+    requiresFileInfo: true
+  },
+  xlarge: {
+    requiresImplementation: true,
+    requiresTechnicalDetails: true,
+    requiresNotes: true,
+    minSteps: 6,
+    minAcceptanceCriteria: 5,
+    requiresFileInfo: true
+  }
+};
+function validateTicket(ticket) {
+  const warnings = [];
+  const complexity = ticket.complexity || "medium";
+  const rules = validationRules[complexity];
+  if (rules.requiresImplementation) {
+    if (!ticket.implementation?.steps?.length) {
+      warnings.push({
+        code: "MISSING_IMPLEMENTATION",
+        message: `${complexity} tickets should have implementation steps`,
+        field: "implementation",
+        severity: "warning"
+      });
+    } else if (ticket.implementation.steps.length < rules.minSteps) {
+      warnings.push({
+        code: "INSUFFICIENT_STEPS",
+        message: `${complexity} tickets should have at least ${rules.minSteps} implementation steps (found ${ticket.implementation.steps.length})`,
+        field: "implementation.steps",
+        severity: "recommendation"
+      });
+    }
+  }
+  if (rules.requiresTechnicalDetails && !ticket.technicalDetails) {
+    warnings.push({
+      code: "MISSING_TECHNICAL_DETAILS",
+      message: `${complexity} tickets should have technicalDetails`,
+      field: "technicalDetails",
+      severity: "warning"
+    });
+  }
+  if (rules.requiresFileInfo) {
+    const hasFiles = (ticket.implementation?.filesToCreate?.length ?? 0) > 0 || (ticket.implementation?.filesToModify?.length ?? 0) > 0;
+    if (!hasFiles) {
+      warnings.push({
+        code: "MISSING_FILE_INFO",
+        message: `${complexity} tickets should specify files to create/modify`,
+        field: "implementation",
+        severity: "recommendation"
+      });
+    }
+  }
+  if (rules.requiresNotes && !ticket.notes) {
+    warnings.push({
+      code: "MISSING_NOTES",
+      message: `${complexity} tickets should have notes with context`,
+      field: "notes",
+      severity: "info"
+    });
+  }
+  const criteriaCount = ticket.acceptanceCriteria?.length || 0;
+  if (criteriaCount < rules.minAcceptanceCriteria) {
+    warnings.push({
+      code: "INSUFFICIENT_ACCEPTANCE_CRITERIA",
+      message: `${complexity} tickets should have at least ${rules.minAcceptanceCriteria} acceptance criteria (found ${criteriaCount})`,
+      field: "acceptanceCriteria",
+      severity: "recommendation"
+    });
+  }
+  const completenessScore = calculateCompletenessScore(ticket, rules);
+  return {
+    valid: true,
+    warnings,
+    completenessScore
+  };
+}
+function calculateCompletenessScore(ticket, rules) {
+  let score = 0;
+  let maxScore = 0;
+  if (rules.requiresImplementation) {
+    maxScore += 30;
+    if (ticket.implementation?.steps?.length) {
+      const stepRatio = Math.min(ticket.implementation.steps.length / rules.minSteps, 1);
+      score += 30 * stepRatio;
+    }
+  }
+  if (rules.requiresTechnicalDetails) {
+    maxScore += 25;
+    if (ticket.technicalDetails) {
+      score += 15;
+      const hasFiles = (ticket.implementation?.filesToCreate?.length ?? 0) > 0 || (ticket.implementation?.filesToModify?.length ?? 0) > 0;
+      if (hasFiles) score += 10;
+    }
+  }
+  if (rules.requiresNotes) {
+    maxScore += 15;
+    if (ticket.notes) score += 15;
+  }
+  maxScore += 30;
+  const criteriaRatio = Math.min(
+    (ticket.acceptanceCriteria?.length || 0) / rules.minAcceptanceCriteria,
+    1
+  );
+  score += 30 * criteriaRatio;
+  return maxScore > 0 ? Math.round(score / maxScore * 100) : 100;
+}
+function filterWarningsByStrictness(warnings, strictness) {
+  switch (strictness) {
+    case "lenient":
+      return warnings.filter((w) => w.severity === "warning");
+    case "normal":
+      return warnings.filter((w) => w.severity !== "info");
+    case "strict":
+      return warnings;
+  }
+}
+function getComplexityRules(complexity) {
+  return validationRules[complexity];
+}
+function isValidComplexity(value) {
+  return value === "small" || value === "medium" || value === "large" || value === "xlarge";
+}
+function getComplexityDescription(complexity) {
+  const descriptions = {
+    small: "Simple tasks that can be completed quickly with minimal documentation",
+    medium: "Standard tasks requiring basic implementation planning",
+    large: "Complex tasks requiring detailed implementation and technical specs",
+    xlarge: "Major features requiring comprehensive documentation and planning"
+  };
+  return descriptions[complexity];
+}
+function suggestComplexity(ticket) {
+  let score = 0;
+  const stepCount = ticket.implementation?.steps?.length || 0;
+  if (stepCount >= 6) score += 3;
+  else if (stepCount >= 4) score += 2;
+  else if (stepCount >= 2) score += 1;
+  if (ticket.technicalDetails) {
+    score += 1;
+    if (ticket.technicalDetails.endpoints?.length) score += 1;
+    if (ticket.technicalDetails.database) score += 1;
+  }
+  if ((ticket.implementation?.filesToCreate?.length ?? 0) > 0 || (ticket.implementation?.filesToModify?.length ?? 0) > 0) {
+    score += 1;
+  }
+  if (ticket.notes) {
+    score += 1;
+  }
+  const criteriaCount = ticket.acceptanceCriteria?.length || 0;
+  if (criteriaCount >= 5) score += 2;
+  else if (criteriaCount >= 3) score += 1;
+  if (score >= 8) return "xlarge";
+  if (score >= 5) return "large";
+  if (score >= 2) return "medium";
+  return "small";
+}
+export {
+  filterWarningsByStrictness,
+  getComplexityDescription,
+  getComplexityRules,
+  isValidComplexity,
+  suggestComplexity,
+  validateTicket,
+  validationRules
+};
+//# sourceMappingURL=ticket-validation.js.map

package/dist/validation/ticket-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/validation/ticket-validation.ts"],"sourcesContent":["/**\n * Ticket Complexity Validation\n *\n * Provides complexity-based validation rules that return warnings rather than\n * errors. This encourages completeness without blocking ticket creation.\n *\n * @see MCI-023-04-complexity-validation-rules\n */\n\nimport type {\n  TicketImplementation,\n  TicketTechnicalDetails,\n} from '../types/index.js';\n\n// =============================================================================\n// Types\n// =============================================================================\n\n/**\n * Ticket complexity levels\n */\nexport type TicketComplexity = 'small' | 'medium' | 'large' | 'xlarge';\n\n/**\n * Validation warning severity levels\n */\nexport type WarningSeverity = 'info' | 'warning' | 'recommendation';\n\n/**\n * Validation strictness levels\n */\nexport type StrictnessLevel = 'lenient' | 'normal' | 'strict';\n\n/**\n * Single validation warning\n */\nexport interface ValidationWarning {\n  /** Warning code for programmatic handling */\n  code: string;\n  /** Human-readable message */\n  message: string;\n  /** Field that triggered the warning */\n  field?: string;\n  /** Severity level */\n  severity: WarningSeverity;\n}\n\n/**\n * Complete validation result\n */\nexport interface TicketValidationResult {\n  /** Always true - warnings don't block creation */\n  valid: true;\n  /** List of warnings */\n  warnings: ValidationWarning[];\n  /** Completeness score (0-100) */\n  completenessScore: number;\n}\n\n/**\n * Validation rules for a complexity level\n */\nexport interface ComplexityRules {\n  /** Whether implementation steps are recommended */\n  requiresImplementation: boolean;\n  /** Whether technical details are recommended */\n  requiresTechnicalDetails: boolean;\n  /** Whether notes are recommended */\n  requiresNotes: boolean;\n  /** Minimum recommended implementation steps */\n  minSteps: number;\n  /** Minimum recommended acceptance criteria */\n  minAcceptanceCriteria: number;\n  /** Whether file information is recommended */\n  requiresFileInfo: boolean;\n}\n\n// =============================================================================\n// Validation Rules Configuration\n// =============================================================================\n\n/**\n * Validation rules by complexity\n *\n * These rules define what fields are recommended for each complexity level.\n * Small tickets have minimal requirements, while xlarge tickets need\n * comprehensive documentation.\n */\nexport const validationRules: Record<TicketComplexity, ComplexityRules> = {\n  small: {\n    requiresImplementation: false,\n    requiresTechnicalDetails: false,\n    requiresNotes: false,\n    minSteps: 0,\n    minAcceptanceCriteria: 1,\n    requiresFileInfo: false,\n  },\n  medium: {\n    requiresImplementation: true,\n    requiresTechnicalDetails: false,\n    requiresNotes: false,\n    minSteps: 2,\n    minAcceptanceCriteria: 2,\n    requiresFileInfo: false,\n  },\n  large: {\n    requiresImplementation: true,\n    requiresTechnicalDetails: true,\n    requiresNotes: false,\n    minSteps: 4,\n    minAcceptanceCriteria: 3,\n    requiresFileInfo: true,\n  },\n  xlarge: {\n    requiresImplementation: true,\n    requiresTechnicalDetails: true,\n    requiresNotes: true,\n    minSteps: 6,\n    minAcceptanceCriteria: 5,\n    requiresFileInfo: true,\n  },\n};\n\n// =============================================================================\n// Validation Functions\n// =============================================================================\n\n/**\n * Ticket data for validation\n */\nexport interface TicketValidationInput {\n  complexity?: TicketComplexity;\n  implementation?: TicketImplementation | null;\n  technicalDetails?: TicketTechnicalDetails | null;\n  notes?: string | null;\n  acceptanceCriteria?: string[];\n}\n\n/**\n * Validate a ticket against complexity-based rules\n *\n * Returns warnings for missing or incomplete fields based on the ticket's\n * complexity level. Does not block ticket creation - all validations\n * produce warnings, not errors.\n *\n * @param ticket - The ticket data to validate\n * @returns Validation result with warnings and completeness score\n *\n * @example\n * ```typescript\n * const result = validateTicket({\n *   complexity: 'large',\n *   implementation: { steps: [{ order: 1, title: 'Setup', action: 'create', detail: '...' }] },\n *   acceptanceCriteria: ['Works correctly']\n * });\n *\n * if (result.warnings.length > 0) {\n *   console.log('Suggestions:', result.warnings.map(w => w.message));\n * }\n * console.log('Completeness:', result.completenessScore + '%');\n * ```\n */\nexport function validateTicket(ticket: TicketValidationInput): TicketValidationResult {\n  const warnings: ValidationWarning[] = [];\n  const complexity = ticket.complexity || 'medium';\n  const rules = validationRules[complexity];\n\n  // Check implementation\n  if (rules.requiresImplementation) {\n    if (!ticket.implementation?.steps?.length) {\n      warnings.push({\n        code: 'MISSING_IMPLEMENTATION',\n        message: `${complexity} tickets should have implementation steps`,\n        field: 'implementation',\n        severity: 'warning',\n      });\n    } else if (ticket.implementation.steps.length < rules.minSteps) {\n      warnings.push({\n        code: 'INSUFFICIENT_STEPS',\n        message: `${complexity} tickets should have at least ${rules.minSteps} implementation steps (found ${ticket.implementation.steps.length})`,\n        field: 'implementation.steps',\n        severity: 'recommendation',\n      });\n    }\n  }\n\n  // Check technical details\n  if (rules.requiresTechnicalDetails && !ticket.technicalDetails) {\n    warnings.push({\n      code: 'MISSING_TECHNICAL_DETAILS',\n      message: `${complexity} tickets should have technicalDetails`,\n      field: 'technicalDetails',\n      severity: 'warning',\n    });\n  }\n\n  // Check file info\n  if (rules.requiresFileInfo) {\n    const hasFiles =\n      (ticket.implementation?.filesToCreate?.length ?? 0) > 0 ||\n      (ticket.implementation?.filesToModify?.length ?? 0) > 0;\n    if (!hasFiles) {\n      warnings.push({\n        code: 'MISSING_FILE_INFO',\n        message: `${complexity} tickets should specify files to create/modify`,\n        field: 'implementation',\n        severity: 'recommendation',\n      });\n    }\n  }\n\n  // Check notes\n  if (rules.requiresNotes && !ticket.notes) {\n    warnings.push({\n      code: 'MISSING_NOTES',\n      message: `${complexity} tickets should have notes with context`,\n      field: 'notes',\n      severity: 'info',\n    });\n  }\n\n  // Check acceptance criteria\n  const criteriaCount = ticket.acceptanceCriteria?.length || 0;\n  if (criteriaCount < rules.minAcceptanceCriteria) {\n    warnings.push({\n      code: 'INSUFFICIENT_ACCEPTANCE_CRITERIA',\n      message: `${complexity} tickets should have at least ${rules.minAcceptanceCriteria} acceptance criteria (found ${criteriaCount})`,\n      field: 'acceptanceCriteria',\n      severity: 'recommendation',\n    });\n  }\n\n  // Calculate completeness score\n  const completenessScore = calculateCompletenessScore(ticket, rules);\n\n  return {\n    valid: true,\n    warnings,\n    completenessScore,\n  };\n}\n\n/**\n * Calculate how complete a ticket is (0-100)\n *\n * Weights different fields based on complexity requirements.\n * A fully complete ticket for its complexity level scores 100.\n *\n * @param ticket - The ticket data\n * @param rules - Complexity rules to evaluate against\n * @returns Completeness score from 0 to 100\n */\nfunction calculateCompletenessScore(\n  ticket: TicketValidationInput,\n  rules: ComplexityRules\n): number {\n  let score = 0;\n  let maxScore = 0;\n\n  // Implementation (30 points max)\n  if (rules.requiresImplementation) {\n    maxScore += 30;\n    if (ticket.implementation?.steps?.length) {\n      const stepRatio = Math.min(ticket.implementation.steps.length / rules.minSteps, 1);\n      score += 30 * stepRatio;\n    }\n  }\n\n  // Technical details (25 points max)\n  if (rules.requiresTechnicalDetails) {\n    maxScore += 25;\n    if (ticket.technicalDetails) {\n      score += 15;\n      const hasFiles =\n        (ticket.implementation?.filesToCreate?.length ?? 0) > 0 ||\n        (ticket.implementation?.filesToModify?.length ?? 0) > 0;\n      if (hasFiles) score += 10;\n    }\n  }\n\n  // Notes (15 points max)\n  if (rules.requiresNotes) {\n    maxScore += 15;\n    if (ticket.notes) score += 15;\n  }\n\n  // Acceptance criteria (30 points max)\n  maxScore += 30;\n  const criteriaRatio = Math.min(\n    (ticket.acceptanceCriteria?.length || 0) / rules.minAcceptanceCriteria,\n    1\n  );\n  score += 30 * criteriaRatio;\n\n  return maxScore > 0 ? Math.round((score / maxScore) * 100) : 100;\n}\n\n/**\n * Filter warnings by strictness level\n *\n * Allows callers to filter out lower-priority warnings based on their\n * desired strictness level.\n *\n * - lenient: Only show 'warning' severity (most important issues only)\n * - normal: Show 'warning' and 'recommendation' (default)\n * - strict: Show all warnings including 'info' level\n *\n * @param warnings - Array of validation warnings\n * @param strictness - Desired strictness level\n * @returns Filtered array of warnings\n *\n * @example\n * ```typescript\n * const result = validateTicket(ticket);\n * const warnings = filterWarningsByStrictness(result.warnings, 'lenient');\n * // Only includes warnings with severity 'warning'\n * ```\n */\nexport function filterWarningsByStrictness(\n  warnings: ValidationWarning[],\n  strictness: StrictnessLevel\n): ValidationWarning[] {\n  switch (strictness) {\n    case 'lenient':\n      return warnings.filter((w) => w.severity === 'warning');\n    case 'normal':\n      return warnings.filter((w) => w.severity !== 'info');\n    case 'strict':\n      return warnings;\n  }\n}\n\n/**\n * Get the rules for a specific complexity level\n *\n * Useful for displaying requirements to users or for custom validation.\n *\n * @param complexity - The complexity level\n * @returns Rules for that complexity level\n */\nexport function getComplexityRules(complexity: TicketComplexity): ComplexityRules {\n  return validationRules[complexity];\n}\n\n/**\n * Check if a complexity value is valid\n *\n * @param value - The value to check\n * @returns True if value is a valid TicketComplexity\n */\nexport function isValidComplexity(value: unknown): value is TicketComplexity {\n  return value === 'small' || value === 'medium' || value === 'large' || value === 'xlarge';\n}\n\n/**\n * Get human-readable description of complexity level\n *\n * @param complexity - The complexity level\n * @returns Description of what this complexity level means\n */\nexport function getComplexityDescription(complexity: TicketComplexity): string {\n  const descriptions: Record<TicketComplexity, string> = {\n    small: 'Simple tasks that can be completed quickly with minimal documentation',\n    medium: 'Standard tasks requiring basic implementation planning',\n    large: 'Complex tasks requiring detailed implementation and technical specs',\n    xlarge: 'Major features requiring comprehensive documentation and planning',\n  };\n  return descriptions[complexity];\n}\n\n/**\n * Suggest appropriate complexity based on ticket content\n *\n * Analyzes the provided ticket data and suggests an appropriate\n * complexity level. Useful for auto-suggesting complexity during\n * ticket creation.\n *\n * @param ticket - The ticket data\n * @returns Suggested complexity level\n */\nexport function suggestComplexity(ticket: TicketValidationInput): TicketComplexity {\n  let score = 0;\n\n  // Implementation steps add complexity\n  const stepCount = ticket.implementation?.steps?.length || 0;\n  if (stepCount >= 6) score += 3;\n  else if (stepCount >= 4) score += 2;\n  else if (stepCount >= 2) score += 1;\n\n  // Technical details add complexity\n  if (ticket.technicalDetails) {\n    score += 1;\n    if (ticket.technicalDetails.endpoints?.length) score += 1;\n    if (ticket.technicalDetails.database) score += 1;\n  }\n\n  // File operations on the implementation indicate more complex work\n  if (\n    (ticket.implementation?.filesToCreate?.length ?? 0) > 0 ||\n    (ticket.implementation?.filesToModify?.length ?? 0) > 0\n  ) {\n    score += 1;\n  }\n\n  // Notes indicate more complex work\n  if (ticket.notes) {\n    score += 1;\n  }\n\n  // Acceptance criteria count\n  const criteriaCount = ticket.acceptanceCriteria?.length || 0;\n  if (criteriaCount >= 5) score += 2;\n  else if (criteriaCount >= 3) score += 1;\n\n  // Map score to complexity\n  if (score >= 8) return 'xlarge';\n  if (score >= 5) return 'large';\n  if (score >= 2) return 'medium';\n  return 'small';\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@specforge/cli",
+  "version": "0.1.0",
+  "description": "MCP server for SpecForge - AI agent integration",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "bin": {
+    "specforge": "./bin/specforge"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly --outDir dist",
+    "typecheck": "tsc --noEmit",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:planning": "vitest run --config vitest.planning.config.ts",
+    "test:coverage": "vitest run --coverage",
+    "test:real": "vitest run --config vitest.real.config.ts",
+    "test:real:watch": "vitest --config vitest.real.config.ts",
+    "test:smoke": "vitest run --config vitest.real.config.ts src/__tests__/real/smoke",
+    "seed:planning": "tsx src/__tests__/integration/seed-planning-session.ts",
+    "seed:implementation": "tsx src/__tests__/integration/seed-implementation-session.ts",
+    "seed:review": "tsx src/__tests__/integration/seed-review-session.ts",
+    "seed:canary": "tsx src/__tests__/integration/seed-ticket-status-canary.ts",
+    "test:implementation": "vitest run --config vitest.implementation.config.ts",
+    "test:review": "vitest run --config vitest.review.config.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@specforge/types": "workspace:*",
+    "@toon-format/toon": "^2.1.0",
+    "chalk": "^5.6.2",
+    "cli-table3": "^0.6.5",
+    "commander": "^12.1.0",
+    "inquirer": "^9.3.8",
+    "minimatch": "^10.1.1",
+    "ora": "^8.2.0"
+  },
+  "devDependencies": {
+    "@types/inquirer": "^9.0.9",
+    "@types/minimatch": "^5.1.2",
+    "@types/node": "^20.0.0",
+    "@vitest/coverage-v8": "4.0.18",
+    "mock-fs": "^5.5.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.7.0",
+    "typescript": "^5.0.0",
+    "vitest": "4.0.18"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src/cli/templates"
+  ],
+  "keywords": [
+    "mcp",
+    "specforge",
+    "ai",
+    "claude",
+    "cursor",
+    "copilot"
+  ],
+  "license": "MIT"
+}

package/src/cli/templates/agents/content/core/sfag-orchestrator.ts

@@ -0,0 +1,165 @@
+/**
+ * SFAG-Orchestrator Agent Template v2
+ *
+ * Strategic task decomposition with concrete decision trees.
+ * Knows when to delegate, to whom, and in what order.
+ */
+
+import type { AgentTemplate } from '../../../../commands/scaffold/agent-types.js';
+
+export const SFAG_ORCHESTRATOR: AgentTemplate = {
+  name: 'sfag-orchestrator',
+  description: 'Decompose complex tasks and coordinate specialized agents',
+  triggerDescription: `Use this agent when a task spans multiple domains and requires coordination between specialized agents. The orchestrator decides WHAT to delegate, to WHOM, and in WHAT ORDER.
+
+<example>
+Context: User requests a full feature that needs spec + implementation + tests
+user: "Preciso de um módulo completo de pagamentos — desde a spec até deploy"
+assistant: "This spans multiple domains. Launching sfag-orchestrator to decompose and coordinate."
+</example>
+
+<example>
+Context: User has a complex task touching schema, API, frontend, and tests
+user: "Adiciona um sistema de comentários — precisa de tabela, API, componente, e testes"
+assistant: "Multi-domain task detected. Launching sfag-orchestrator to plan the execution."
+</example>
+
+<example>
+Context: User needs analysis across multiple dimensions
+user: "Faz uma análise completa desse módulo — segurança, performance, e qualidade"
+assistant: "Launching sfag-orchestrator to coordinate a multi-perspective analysis."
+</example>`,
+  model: 'opus',
+  color: 'magenta',
+  category: 'Orchestration',
+  memory: 'project',
+  content: `# SpecForge Orchestrator Agent
+
+You are the brain. You don't write code. You don't write specs. You decide WHO does WHAT and WHEN, then you make it happen.
+
+## Context Bootstrapping
+
+Before any decision, read the project context from the local config:
+\`\`\`
+Read .specforge.json from project root → extract:
+  - project.id → projectId
+  - activeSpecification.id → specificationId (may be null if no spec exists yet)
+  - agentTeams config (if Agent Teams mode)
+\`\`\`
+All tool calls that need projectId/specificationId use these values. No session store, no get_working_context.
+
+## Available Agents
+
+| Agent | What it does | When to use |
+|-------|-------------|-------------|
+| **sfag-spec-creator** | Dense interrogation → SpecForge spec | When requirements are unclear or no spec exists |
+| **sfag-ticket-implementer** | Lifecycle-tracked ticket implementation | When a spec exists and tickets are ready |
+| **sfag-package-researcher** | Web research for packages/APIs/docs | When external knowledge is needed before implementation |
+
+## Decision Tree
+
+When a task arrives, follow this tree:
+
+### 1. Does a specification exist for this work?
+
+**NO →** Route to \`sfag-spec-creator\` first. Full stop. No implementation without a spec.
+
+**YES →** Continue to step 2.
+
+### 2. Does the task require external package/API knowledge?
+
+**YES →** Launch \`sfag-package-researcher\` BEFORE implementation. Feed research output into implementation context.
+
+**NO →** Continue to step 3.
+
+### 3. Are tickets created and ready?
+
+**NO →** Check if the spec needs more tickets. If yes, route back to \`sfag-spec-creator\` for ticket creation. If tickets exist but are blocked, diagnose with:
+\`\`\`
+get_blocked_tickets({ specificationId })
+get_dependency_tree({ specificationId })
+\`\`\`
+
+**YES →** Route to \`sfag-ticket-implementer\`. Give it the ticket ID or let it pick from actionable tickets.
+
+### 4. Is this a multi-ticket task?
+
+**YES →** Determine execution order:
+\`\`\`
+get_critical_path({ specificationId })
+get_next_actionable_tickets({ specificationId })
+\`\`\`
+Launch \`sfag-ticket-implementer\` for each ticket in dependency order. Between tickets, verify the previous completed successfully before starting the next.
+
+**NO →** Single ticket, single launch.
+
+## Coordination Patterns
+
+### Pattern A: Greenfield Feature
+\`\`\`
+sfag-spec-creator (interrogation → spec + epics + tickets)
+  ↓
+sfag-package-researcher (if unknown packages involved)
+  ↓
+sfag-ticket-implementer (ticket 1 → ticket 2 → ... → ticket N)
+\`\`\`
+
+### Pattern B: Add to Existing Spec
+\`\`\`
+Check spec status → create new epic/tickets if needed
+  ↓
+sfag-ticket-implementer (new tickets only)
+\`\`\`
+
+### Pattern C: Research-First Implementation
+\`\`\`
+sfag-package-researcher (gather docs, patterns, gotchas)
+  ↓
+Feed research into ticket notes/context
+  ↓
+sfag-ticket-implementer (implement with research context)
+\`\`\`
+
+### Pattern D: Multi-Domain Parallel
+When tickets are independent (no dependency chain):
+\`\`\`
+sfag-ticket-implementer (ticket A) ─┐
+sfag-ticket-implementer (ticket B) ─┼→ verify all complete
+sfag-ticket-implementer (ticket C) ─┘
+\`\`\`
+
+## Your Responsibilities
+
+### Before Delegation
+- Understand the full scope of the request
+- Check SpecForge state: existing specs, ticket statuses, blockers
+- Identify the right pattern (A, B, C, or D)
+- Load relevant context for the agents you're about to launch
+
+### During Execution
+- Monitor agent outputs for problems
+- If an agent hits a blocker, decide: fix it, skip it, or escalate to user
+- Track which tickets completed and which are next
+- Maintain the execution plan — update if dependencies shift
+
+### After Completion
+- Verify all delegated work completed (check ticket statuses)
+- Report summary to user: what was done, what's pending, what's blocked
+- Suggest next steps if work remains
+
+## What You Are NOT
+
+- You are NOT an implementer. Don't write code. Delegate to ticket-implementer.
+- You are NOT a spec creator. Don't interrogate requirements. Delegate to spec-creator.
+- You are NOT a researcher. Don't search the web. Delegate to package-researcher.
+- You ARE the one who decides the plan, sequences the work, and ensures nothing falls through the cracks.
+
+## Anti-Patterns
+
+- ❌ Don't launch ticket-implementer without a spec. Spec-creator goes first.
+- ❌ Don't implement tickets out of dependency order. Check the critical path.
+- ❌ Don't assume packages are known. If the ticket references an unfamiliar package, research first.
+- ❌ Don't run everything sequentially when tickets are independent. Parallel when possible.
+- ❌ Don't silently skip blockers. Report them to the user with diagnosis.
+`,
+};