@specforge/canary-cli 0.1.0

package/dist/lib/strategy-analyzer.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Strategy Auto-Detection Analyzer
+ *
+ * Pure function that determines the optimal Agent Teams strategy
+ * based on a specification's structure: epic count, ticket distribution,
+ * and cross-epic dependency density.
+ *
+ * Decision matrix (from design doc):
+ *   - 1 epic, ≤3 tickets           → single-session
+ *   - 1 epic, >3 tickets           → spec-as-team
+ *   - N epics, 0 cross-deps        → epic-as-team
+ *   - N epics, >50% cross-deps     → spec-as-team
+ *   - N epics, moderate cross-deps  → epic-as-team with merged pairs
+ */
+/** Tickets with cross-epic deps / total tickets. Above this → spec-as-team. */
+export declare const CROSS_DEP_THRESHOLD = 0.5;
+/** Max tickets for a single-session recommendation (single epic only). */
+export declare const SINGLE_SESSION_MAX_TICKETS = 3;
+export interface SpecSummary {
+    id: string;
+    title: string;
+    epicCount: number;
+}
+export interface EpicSummary {
+    id: string;
+    title: string;
+    ticketCount: number;
+}
+export interface TicketSummary {
+    id: string;
+    epicId: string;
+    dependencies: string[];
+}
+/**
+ * A dependency edge between two tickets in different epics.
+ */
+export interface DependencyEdge {
+    fromEpicId: string;
+    toEpicId: string;
+    fromTicketId: string;
+    toTicketId: string;
+}
+export type Strategy = 'single-session' | 'spec-as-team' | 'epic-as-team';
+export interface StrategyRecommendation {
+    strategy: Strategy;
+    reasoning: string;
+    /** Epic ID groups that should be merged into a single team (for moderate cross-deps). */
+    mergedEpics?: string[][];
+}
+/**
+ * Analyze a specification's structure and recommend an Agent Teams strategy.
+ *
+ * This is a **pure function** — no side effects, no API calls.
+ * All data must be pre-fetched and passed in.
+ *
+ * @throws {Error} If the specification has no epics or no tickets.
+ */
+export declare function analyzeStrategy(spec: SpecSummary, epics: EpicSummary[], ticketsByEpic: Map<string, TicketSummary[]>, dependencyEdges: DependencyEdge[]): StrategyRecommendation;
+//# sourceMappingURL=strategy-analyzer.d.ts.map

package/dist/lib/strategy-analyzer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy-analyzer.d.ts","sourceRoot":"","sources":["../../src/lib/strategy-analyzer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAMH,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAEvC,0EAA0E;AAC1E,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAM5C,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,MAAM,MAAM,QAAQ,GAAG,gBAAgB,GAAG,cAAc,GAAG,cAAc,CAAC;AAE1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,WAAW,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC;CAC1B;AAMD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,WAAW,EACjB,KAAK,EAAE,WAAW,EAAE,EACpB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,EAC3C,eAAe,EAAE,cAAc,EAAE,GAChC,sBAAsB,CA+DxB"}

package/dist/lib/strategy-analyzer.js

@@ -0,0 +1,91 @@
+const CROSS_DEP_THRESHOLD = 0.5;
+const SINGLE_SESSION_MAX_TICKETS = 3;
+function analyzeStrategy(spec, epics, ticketsByEpic, dependencyEdges) {
+  const totalTickets = epics.reduce((sum, e) => sum + e.ticketCount, 0);
+  if (epics.length === 0 || totalTickets === 0) {
+    throw new Error("Cannot analyze empty specification");
+  }
+  if (epics.length === 1) {
+    const epic = epics[0];
+    if (epic.ticketCount <= SINGLE_SESSION_MAX_TICKETS) {
+      return {
+        strategy: "single-session",
+        reasoning: `Small specification with ${epic.ticketCount} ticket${epic.ticketCount === 1 ? "" : "s"} in single epic`
+      };
+    }
+    return {
+      strategy: "spec-as-team",
+      reasoning: `Single epic with ${epic.ticketCount} tickets benefits from parallel workers`
+    };
+  }
+  const crossDepTicketIds = /* @__PURE__ */ new Set();
+  for (const edge of dependencyEdges) {
+    crossDepTicketIds.add(edge.fromTicketId);
+    crossDepTicketIds.add(edge.toTicketId);
+  }
+  const crossDepRatio = totalTickets > 0 ? crossDepTicketIds.size / totalTickets : 0;
+  if (dependencyEdges.length === 0) {
+    return {
+      strategy: "epic-as-team",
+      reasoning: `Multiple independent epics (${epics.length}) can be parallelized as separate teams`
+    };
+  }
+  if (crossDepRatio > CROSS_DEP_THRESHOLD) {
+    const pct2 = Math.round(crossDepRatio * 100);
+    return {
+      strategy: "spec-as-team",
+      reasoning: `Heavy cross-epic dependencies (${pct2}%) require unified team coordination`
+    };
+  }
+  const mergedEpics = buildMergedEpicGroups(epics, dependencyEdges);
+  const pct = Math.round(crossDepRatio * 100);
+  return {
+    strategy: "epic-as-team",
+    reasoning: `Multiple epics with moderate cross-dependencies (${pct}%); tightly coupled epics merged into ${mergedEpics.length} group${mergedEpics.length === 1 ? "" : "s"}`,
+    mergedEpics
+  };
+}
+function buildMergedEpicGroups(epics, edges) {
+  const parent = /* @__PURE__ */ new Map();
+  function find(x) {
+    let root = x;
+    while (parent.get(root) !== root) {
+      root = parent.get(root);
+    }
+    let current = x;
+    while (current !== root) {
+      const next = parent.get(current);
+      parent.set(current, root);
+      current = next;
+    }
+    return root;
+  }
+  function union(a, b) {
+    const ra = find(a);
+    const rb = find(b);
+    if (ra !== rb) {
+      parent.set(ra, rb);
+    }
+  }
+  for (const epic of epics) {
+    parent.set(epic.id, epic.id);
+  }
+  for (const edge of edges) {
+    union(edge.fromEpicId, edge.toEpicId);
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const epic of epics) {
+    const root = find(epic.id);
+    if (!groups.has(root)) {
+      groups.set(root, []);
+    }
+    groups.get(root).push(epic.id);
+  }
+  return Array.from(groups.values()).filter((g) => g.length > 1);
+}
+export {
+  CROSS_DEP_THRESHOLD,
+  SINGLE_SESSION_MAX_TICKETS,
+  analyzeStrategy
+};
+//# sourceMappingURL=strategy-analyzer.js.map

package/dist/lib/strategy-analyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/lib/strategy-analyzer.ts"],"sourcesContent":["/**\n * Strategy Auto-Detection Analyzer\n *\n * Pure function that determines the optimal Agent Teams strategy\n * based on a specification's structure: epic count, ticket distribution,\n * and cross-epic dependency density.\n *\n * Decision matrix (from design doc):\n *   - 1 epic, ≤3 tickets           → single-session\n *   - 1 epic, >3 tickets           → spec-as-team\n *   - N epics, 0 cross-deps        → epic-as-team\n *   - N epics, >50% cross-deps     → spec-as-team\n *   - N epics, moderate cross-deps  → epic-as-team with merged pairs\n */\n\n// ---------------------------------------------------------------------------\n// Tuning constants\n// ---------------------------------------------------------------------------\n\n/** Tickets with cross-epic deps / total tickets. Above this → spec-as-team. */\nexport const CROSS_DEP_THRESHOLD = 0.5;\n\n/** Max tickets for a single-session recommendation (single epic only). */\nexport const SINGLE_SESSION_MAX_TICKETS = 3;\n\n// ---------------------------------------------------------------------------\n// Input types\n// ---------------------------------------------------------------------------\n\nexport interface SpecSummary {\n  id: string;\n  title: string;\n  epicCount: number;\n}\n\nexport interface EpicSummary {\n  id: string;\n  title: string;\n  ticketCount: number;\n}\n\nexport interface TicketSummary {\n  id: string;\n  epicId: string;\n  dependencies: string[]; // ticket IDs this ticket depends on\n}\n\n/**\n * A dependency edge between two tickets in different epics.\n */\nexport interface DependencyEdge {\n  fromEpicId: string;\n  toEpicId: string;\n  fromTicketId: string;\n  toTicketId: string;\n}\n\n// ---------------------------------------------------------------------------\n// Output types\n// ---------------------------------------------------------------------------\n\nexport type Strategy = 'single-session' | 'spec-as-team' | 'epic-as-team';\n\nexport interface StrategyRecommendation {\n  strategy: Strategy;\n  reasoning: string;\n  /** Epic ID groups that should be merged into a single team (for moderate cross-deps). */\n  mergedEpics?: string[][];\n}\n\n// ---------------------------------------------------------------------------\n// Core analyzer\n// ---------------------------------------------------------------------------\n\n/**\n * Analyze a specification's structure and recommend an Agent Teams strategy.\n *\n * This is a **pure function** — no side effects, no API calls.\n * All data must be pre-fetched and passed in.\n *\n * @throws {Error} If the specification has no epics or no tickets.\n */\nexport function analyzeStrategy(\n  spec: SpecSummary,\n  epics: EpicSummary[],\n  ticketsByEpic: Map<string, TicketSummary[]>,\n  dependencyEdges: DependencyEdge[],\n): StrategyRecommendation {\n  // --- Guard: empty specification ---\n  const totalTickets = epics.reduce((sum, e) => sum + e.ticketCount, 0);\n\n  if (epics.length === 0 || totalTickets === 0) {\n    throw new Error('Cannot analyze empty specification');\n  }\n\n  // --- Single epic path ---\n  if (epics.length === 1) {\n    const epic = epics[0];\n\n    if (epic.ticketCount <= SINGLE_SESSION_MAX_TICKETS) {\n      return {\n        strategy: 'single-session',\n        reasoning: `Small specification with ${epic.ticketCount} ticket${epic.ticketCount === 1 ? '' : 's'} in single epic`,\n      };\n    }\n\n    return {\n      strategy: 'spec-as-team',\n      reasoning: `Single epic with ${epic.ticketCount} tickets benefits from parallel workers`,\n    };\n  }\n\n  // --- Multiple epics path ---\n\n  // Count tickets that have at least one dependency on a ticket in another epic.\n  const crossDepTicketIds = new Set<string>();\n\n  for (const edge of dependencyEdges) {\n    crossDepTicketIds.add(edge.fromTicketId);\n    crossDepTicketIds.add(edge.toTicketId);\n  }\n\n  const crossDepRatio = totalTickets > 0 ? crossDepTicketIds.size / totalTickets : 0;\n\n  // No cross-epic dependencies → each epic can run independently.\n  if (dependencyEdges.length === 0) {\n    return {\n      strategy: 'epic-as-team',\n      reasoning: `Multiple independent epics (${epics.length}) can be parallelized as separate teams`,\n    };\n  }\n\n  // Heavy cross-epic dependencies → single unified team.\n  if (crossDepRatio > CROSS_DEP_THRESHOLD) {\n    const pct = Math.round(crossDepRatio * 100);\n    return {\n      strategy: 'spec-as-team',\n      reasoning: `Heavy cross-epic dependencies (${pct}%) require unified team coordination`,\n    };\n  }\n\n  // Moderate cross-epic dependencies → epic-as-team with merged pairs.\n  const mergedEpics = buildMergedEpicGroups(epics, dependencyEdges);\n  const pct = Math.round(crossDepRatio * 100);\n\n  return {\n    strategy: 'epic-as-team',\n    reasoning: `Multiple epics with moderate cross-dependencies (${pct}%); tightly coupled epics merged into ${mergedEpics.length} group${mergedEpics.length === 1 ? '' : 's'}`,\n    mergedEpics,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Build groups of epics that should be merged into a single team\n * because they share bidirectional (or dense) dependency edges.\n *\n * Uses a simple union-find to cluster epics connected by dependency edges.\n */\nfunction buildMergedEpicGroups(\n  epics: EpicSummary[],\n  edges: DependencyEdge[],\n): string[][] {\n  // Union-Find (disjoint set)\n  const parent = new Map<string, string>();\n\n  function find(x: string): string {\n    let root = x;\n    while (parent.get(root) !== root) {\n      root = parent.get(root)!;\n    }\n    // Path compression\n    let current = x;\n    while (current !== root) {\n      const next = parent.get(current)!;\n      parent.set(current, root);\n      current = next;\n    }\n    return root;\n  }\n\n  function union(a: string, b: string): void {\n    const ra = find(a);\n    const rb = find(b);\n    if (ra !== rb) {\n      parent.set(ra, rb);\n    }\n  }\n\n  // Initialize each epic as its own set.\n  for (const epic of epics) {\n    parent.set(epic.id, epic.id);\n  }\n\n  // Merge epics that share dependency edges.\n  for (const edge of edges) {\n    union(edge.fromEpicId, edge.toEpicId);\n  }\n\n  // Collect groups (only groups with >1 epic are meaningful merges).\n  const groups = new Map<string, string[]>();\n  for (const epic of epics) {\n    const root = find(epic.id);\n    if (!groups.has(root)) {\n      groups.set(root, []);\n    }\n    groups.get(root)!.push(epic.id);\n  }\n\n  return Array.from(groups.values()).filter(g => g.length > 1);\n}\n"],"mappings":"AAoBO,MAAM,sBAAsB;AAG5B,MAAM,6BAA6B;AA2DnC,SAAS,gBACd,MACA,OACA,eACA,iBACwB;AAExB,QAAM,eAAe,MAAM,OAAO,CAAC,KAAK,MAAM,MAAM,EAAE,aAAa,CAAC;AAEpE,MAAI,MAAM,WAAW,KAAK,iBAAiB,GAAG;AAC5C,UAAM,IAAI,MAAM,oCAAoC;AAAA,EACtD;AAGA,MAAI,MAAM,WAAW,GAAG;AACtB,UAAM,OAAO,MAAM,CAAC;AAEpB,QAAI,KAAK,eAAe,4BAA4B;AAClD,aAAO;AAAA,QACL,UAAU;AAAA,QACV,WAAW,4BAA4B,KAAK,WAAW,UAAU,KAAK,gBAAgB,IAAI,KAAK,GAAG;AAAA,MACpG;AAAA,IACF;AAEA,WAAO;AAAA,MACL,UAAU;AAAA,MACV,WAAW,oBAAoB,KAAK,WAAW;AAAA,IACjD;AAAA,EACF;AAKA,QAAM,oBAAoB,oBAAI,IAAY;AAE1C,aAAW,QAAQ,iBAAiB;AAClC,sBAAkB,IAAI,KAAK,YAAY;AACvC,sBAAkB,IAAI,KAAK,UAAU;AAAA,EACvC;AAEA,QAAM,gBAAgB,eAAe,IAAI,kBAAkB,OAAO,eAAe;AAGjF,MAAI,gBAAgB,WAAW,GAAG;AAChC,WAAO;AAAA,MACL,UAAU;AAAA,MACV,WAAW,+BAA+B,MAAM,MAAM;AAAA,IACxD;AAAA,EACF;AAGA,MAAI,gBAAgB,qBAAqB;AACvC,UAAMA,OAAM,KAAK,MAAM,gBAAgB,GAAG;AAC1C,WAAO;AAAA,MACL,UAAU;AAAA,MACV,WAAW,kCAAkCA,IAAG;AAAA,IAClD;AAAA,EACF;AAGA,QAAM,cAAc,sBAAsB,OAAO,eAAe;AAChE,QAAM,MAAM,KAAK,MAAM,gBAAgB,GAAG;AAE1C,SAAO;AAAA,IACL,UAAU;AAAA,IACV,WAAW,oDAAoD,GAAG,yCAAyC,YAAY,MAAM,SAAS,YAAY,WAAW,IAAI,KAAK,GAAG;AAAA,IACzK;AAAA,EACF;AACF;AAYA,SAAS,sBACP,OACA,OACY;AAEZ,QAAM,SAAS,oBAAI,IAAoB;AAEvC,WAAS,KAAK,GAAmB;AAC/B,QAAI,OAAO;AACX,WAAO,OAAO,IAAI,IAAI,MAAM,MAAM;AAChC,aAAO,OAAO,IAAI,IAAI;AAAA,IACxB;AAEA,QAAI,UAAU;AACd,WAAO,YAAY,MAAM;AACvB,YAAM,OAAO,OAAO,IAAI,OAAO;AAC/B,aAAO,IAAI,SAAS,IAAI;AACxB,gBAAU;AAAA,IACZ;AACA,WAAO;AAAA,EACT;AAEA,WAAS,MAAM,GAAW,GAAiB;AACzC,UAAM,KAAK,KAAK,CAAC;AACjB,UAAM,KAAK,KAAK,CAAC;AACjB,QAAI,OAAO,IAAI;AACb,aAAO,IAAI,IAAI,EAAE;AAAA,IACnB;AAAA,EACF;AAGA,aAAW,QAAQ,OAAO;AACxB,WAAO,IAAI,KAAK,IAAI,KAAK,EAAE;AAAA,EAC7B;AAGA,aAAW,QAAQ,OAAO;AACxB,UAAM,KAAK,YAAY,KAAK,QAAQ;AAAA,EACtC;AAGA,QAAM,SAAS,oBAAI,IAAsB;AACzC,aAAW,QAAQ,OAAO;AACxB,UAAM,OAAO,KAAK,KAAK,EAAE;AACzB,QAAI,CAAC,OAAO,IAAI,IAAI,GAAG;AACrB,aAAO,IAAI,MAAM,CAAC,CAAC;AAAA,IACrB;AACA,WAAO,IAAI,IAAI,EAAG,KAAK,KAAK,EAAE;AAAA,EAChC;AAEA,SAAO,MAAM,KAAK,OAAO,OAAO,CAAC,EAAE,OAAO,OAAK,EAAE,SAAS,CAAC;AAC7D;","names":["pct"]}

package/dist/lib/workflow-definitions.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Workflow Definitions
+ *
+ * Contains the workflow definitions as data structures for guiding AI agents
+ * through SpecForge workflows.
+ */
+export interface WorkflowStep {
+    step: number;
+    name: string;
+    description: string;
+    tools: string[];
+    tips: string[];
+}
+export interface WorkflowDefinition {
+    name: string;
+    description: string;
+    philosophy: string[];
+    steps: WorkflowStep[];
+    antiPatterns: string[];
+}
+export interface ReviewChecklistItem {
+    name: string;
+    description: string;
+}
+export interface ReviewWorkflowDefinition extends WorkflowDefinition {
+    checklist: ReviewChecklistItem[];
+}
+export interface FinalizeWorkflowDefinition extends WorkflowDefinition {
+    prerequisites: string[];
+}
+export declare const CREATION_WORKFLOW: WorkflowDefinition;
+export declare const IMPLEMENTATION_WORKFLOW: WorkflowDefinition;
+export declare const REVIEW_WORKFLOW: ReviewWorkflowDefinition;
+export declare const FINALIZE_WORKFLOW: FinalizeWorkflowDefinition;
+/**
+ * Get a workflow definition by type
+ */
+export declare function getWorkflowDefinition(workflowType: string): WorkflowDefinition | ReviewWorkflowDefinition | FinalizeWorkflowDefinition | null;
+export declare const WORKFLOW_TYPES: readonly ["creation", "implementation", "review", "finalize"];
+export type WorkflowType = (typeof WORKFLOW_TYPES)[number];
+//# sourceMappingURL=workflow-definitions.d.ts.map

package/dist/lib/workflow-definitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-definitions.d.ts","sourceRoot":"","sources":["../../src/lib/workflow-definitions.ts"],"names":[],"mappings":"AACA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAyB,SAAQ,kBAAkB;IAClE,SAAS,EAAE,mBAAmB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,0BAA2B,SAAQ,kBAAkB;IACpE,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,eAAO,MAAM,iBAAiB,EAAE,kBA+G/B,CAAC;AAEF,eAAO,MAAM,uBAAuB,EAAE,kBAgKrC,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,wBAmG7B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,0BAmG/B,CAAC;AAEF;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,GACnB,kBAAkB,GAAG,wBAAwB,GAAG,0BAA0B,GAAG,IAAI,CAanF;AAED,eAAO,MAAM,cAAc,+DAAgE,CAAC;AAC5F,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC"}