@specforge/mcp 2.1.6 → 2.3.0

package/dist/tools/core/workflow-guide.js

@@ -0,0 +1,332 @@
+// mcp/src/tools/core/workflow-guide.ts
+/**
+ * Workflow Guide Tool
+ *
+ * Guides AI agents through SpecForge workflows, providing step-by-step
+ * instructions and contextual next actions.
+ */
+import { createOperationRouter } from './router.js';
+import { WORKFLOW_TYPES, getWorkflowDefinition, } from '../../lib/workflow-definitions.js';
+export const workflowGuideTool = {
+    name: 'workflow_guide',
+    description: `Get guidance for SpecForge workflows. Operations:
+- guide: Get full workflow instructions for a workflow type
+- status: Get current workflow state and progress
+- next: Get the specific next action to take`,
+    inputSchema: {
+        type: 'object',
+        properties: {
+            operation: {
+                type: 'string',
+                enum: ['guide', 'status', 'next'],
+                description: 'The operation to perform',
+            },
+            workflowType: {
+                type: 'string',
+                enum: WORKFLOW_TYPES,
+                description: 'Workflow type (required for guide): creation, implementation, review, finalize',
+            },
+            specificationId: {
+                type: 'string',
+                description: 'Specification ID (uses working context if not provided)',
+            },
+        },
+        required: ['operation'],
+    },
+};
+function validateRequired(args, ...fields) {
+    for (const field of fields) {
+        if (args[field] === undefined || args[field] === null || args[field] === '') {
+            throw new Error(`${field} is required`);
+        }
+    }
+}
+/**
+ * Determine the current and next step based on context and progress
+ */
+function determineStep(context, progress) {
+    const hasActiveSession = context.activeSession != null;
+    const hasSpec = context.specificationId != null;
+    const hasEpic = context.epicId != null;
+    const hasTicket = context.ticketId != null;
+    // If we have an active session, we're in implementation workflow
+    if (hasActiveSession) {
+        // Check if we're in the middle of implementing
+        if (progress && progress.tickets.active > 0) {
+            return {
+                currentStep: 'implement',
+                nextStep: 'Continue implementing, report progress, then validate and complete',
+            };
+        }
+        return {
+            currentStep: 'session_active',
+            nextStep: 'Continue with session - implement the ticket and complete when done',
+        };
+    }
+    // Creation workflow logic
+    if (!hasSpec) {
+        return {
+            currentStep: 'no_specification',
+            nextStep: 'Create or select a specification to work on',
+        };
+    }
+    if (!progress) {
+        return {
+            currentStep: 'specification_selected',
+            nextStep: 'Plan and create epics for the specification',
+        };
+    }
+    // Check overall progress
+    const allEpicsDone = progress.epics.done === progress.epics.total && progress.epics.total > 0;
+    const allTicketsDone = progress.tickets.done === progress.tickets.total && progress.tickets.total > 0;
+    if (allEpicsDone && allTicketsDone) {
+        return {
+            currentStep: 'implementation_complete',
+            nextStep: 'Run finalize workflow - verify, create PR, end session',
+        };
+    }
+    if (progress.epics.total === 0) {
+        return {
+            currentStep: 'no_epics',
+            nextStep: 'Plan and create the first epic',
+        };
+    }
+    if (progress.tickets.total === 0) {
+        return {
+            currentStep: 'no_tickets',
+            nextStep: 'Plan and create tickets for the current epic',
+        };
+    }
+    if (progress.tickets.ready > 0) {
+        return {
+            currentStep: 'tickets_ready',
+            nextStep: 'Start a session and implement the next ready ticket',
+        };
+    }
+    if (progress.tickets.done < progress.tickets.total) {
+        return {
+            currentStep: 'tickets_blocked',
+            nextStep: 'Resolve blocked tickets or check dependencies',
+        };
+    }
+    return {
+        currentStep: 'unknown',
+        nextStep: 'Check workflow status and context',
+    };
+}
+/**
+ * Generate actionable next step recommendation
+ */
+function generateNextAction(status) {
+    const { currentStep, currentState } = status;
+    switch (currentStep) {
+        case 'no_specification':
+            return {
+                step: 'create_specification',
+                reason: 'No specification is selected in the working context',
+                action: {
+                    description: 'Create a new specification with full context',
+                    tool: 'specification',
+                    operation: 'create',
+                    suggestedArgs: {
+                        projectId: currentState.workingContext.projectId,
+                    },
+                },
+                beforeProceeding: [
+                    'Gather requirements from user',
+                    'Understand the problem being solved',
+                    'Define scope and goals',
+                ],
+            };
+        case 'no_epics':
+        case 'specification_selected':
+            return {
+                step: 'create_epic',
+                reason: 'Specification exists but has no epics',
+                action: {
+                    description: 'Plan epic structure then create the first epic',
+                    tool: 'epic',
+                    operation: 'create',
+                    suggestedArgs: {
+                        specificationId: currentState.workingContext.specificationId,
+                    },
+                },
+                beforeProceeding: [
+                    'Discuss epic breakdown with user',
+                    'Identify logical phases',
+                    'Consider dependencies between epics',
+                ],
+            };
+        case 'no_tickets':
+            return {
+                step: 'create_ticket',
+                reason: 'Epic exists but has no tickets',
+                action: {
+                    description: 'Plan ticket structure then create tickets one at a time',
+                    tool: 'ticket',
+                    operation: 'create',
+                    suggestedArgs: {
+                        epicId: currentState.workingContext.epicId,
+                    },
+                },
+                beforeProceeding: [
+                    'Break epic into focused tickets',
+                    'Define acceptance criteria for each',
+                    'Map out dependencies',
+                ],
+            };
+        case 'tickets_ready':
+            return {
+                step: 'start_implementation',
+                reason: `${currentState.progress?.tickets.ready} ticket(s) are ready to implement`,
+                action: {
+                    description: 'Start a session and begin implementing',
+                    tool: 'session',
+                    operation: 'start',
+                },
+                beforeProceeding: [
+                    'Get full implementation context with context.implementation',
+                    'Review acceptance criteria',
+                    'Ask user about unclear requirements',
+                ],
+                context: 'Use workflow.next_actionable to find the best ticket to start',
+            };
+        case 'session_active':
+        case 'implement':
+            return {
+                step: 'continue_implementation',
+                reason: 'Active session in progress',
+                action: {
+                    description: 'Continue implementing the current ticket',
+                    tool: 'session',
+                    operation: 'progress',
+                    suggestedArgs: {
+                        ticketId: currentState.activeSession?.ticketId,
+                    },
+                },
+                beforeProceeding: ['Review where you left off', 'Check ticket requirements'],
+                context: `Working on: ${currentState.activeSession?.ticketTitle}`,
+            };
+        case 'tickets_blocked':
+            return {
+                step: 'resolve_blockers',
+                reason: 'All remaining tickets are blocked by dependencies',
+                action: {
+                    description: 'Check blocked tickets and resolve dependencies',
+                    tool: 'workflow',
+                    operation: 'blocked',
+                    suggestedArgs: {
+                        specificationId: currentState.workingContext.specificationId,
+                    },
+                },
+                beforeProceeding: [
+                    'Review what tickets are blocking',
+                    'Check if any dependencies can be resolved',
+                ],
+            };
+        case 'implementation_complete':
+            return {
+                step: 'finalize',
+                reason: 'All epics and tickets are complete',
+                action: {
+                    description: 'Run finalize workflow to create PR',
+                    tool: 'workflow_guide',
+                    operation: 'guide',
+                    suggestedArgs: {
+                        workflowType: 'finalize',
+                    },
+                },
+                beforeProceeding: [
+                    'Run full test suite',
+                    'Check documentation is updated',
+                    'Review all changes',
+                ],
+            };
+        default:
+            return {
+                step: 'check_status',
+                reason: 'Current state is unclear',
+                action: {
+                    description: 'Get working context to understand current state',
+                    tool: 'context',
+                    operation: 'working',
+                },
+            };
+    }
+}
+export function createWorkflowGuideOperations(apiClient) {
+    return {
+        guide: async (args, _userId) => {
+            validateRequired(args, 'workflowType');
+            const workflowType = args.workflowType;
+            const workflow = getWorkflowDefinition(workflowType);
+            if (!workflow) {
+                throw new Error(`Unknown workflow type: ${workflowType}. Valid types: ${WORKFLOW_TYPES.join(', ')}`);
+            }
+            return workflow;
+        },
+        status: async (args, _userId) => {
+            // Get working context
+            const context = (await apiClient.call('get_working_context', {}));
+            // Determine workflow type from context
+            const hasActiveSession = context.activeSession != null;
+            const workflowType = hasActiveSession ? 'implementation' : 'creation';
+            // Get progress if we have a specification
+            let progress = null;
+            const specId = args.specificationId || context.specificationId;
+            if (specId) {
+                try {
+                    const spec = (await apiClient.call('get_specification', {
+                        specificationId: specId,
+                        summary: true,
+                    }));
+                    progress = {
+                        epics: {
+                            total: spec.epicCount ?? 0,
+                            done: spec.completedEpicCount ?? 0,
+                        },
+                        tickets: {
+                            total: spec.ticketCount ?? 0,
+                            done: spec.completedTicketCount ?? 0,
+                            ready: spec.readyTicketCount ?? 0,
+                            active: spec.activeTicketCount ?? 0,
+                        },
+                    };
+                }
+                catch {
+                    // Specification might not exist yet
+                    progress = null;
+                }
+            }
+            // Determine current and next step
+            const { currentStep, nextStep } = determineStep(context, progress);
+            return {
+                workflow: workflowType,
+                currentState: {
+                    activeSession: context.activeSession,
+                    workingContext: {
+                        projectId: context.projectId,
+                        specificationId: context.specificationId,
+                        epicId: context.epicId,
+                        ticketId: context.ticketId,
+                    },
+                    progress,
+                },
+                currentStep,
+                nextStep,
+            };
+        },
+        next: async (args, userId) => {
+            // Get current status first
+            const statusHandler = createWorkflowGuideOperations(apiClient).status;
+            const status = (await statusHandler(args, userId));
+            // Generate actionable next step
+            return generateNextAction(status);
+        },
+    };
+}
+export function createWorkflowGuideHandler(apiClient) {
+    const operations = createWorkflowGuideOperations(apiClient);
+    return createOperationRouter('workflow_guide', operations);
+}
+//# sourceMappingURL=workflow-guide.js.map

package/dist/tools/core/workflow-guide.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-guide.js","sourceRoot":"","sources":["../../../src/tools/core/workflow-guide.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAML,gBAAgB,EAKjB,MAAM,wBAAwB,CAAC;AAmBhC;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AA6ED,wBAAgB,QAAQ,IAAI,IAAI,EAAE,CA8tEjC;AAED;;GAEG;AACH,KAAK,WAAW,GAAG,CACjB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AA6EtB;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GACnB,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAogC7B;AAqCD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,CAAC,CA4DlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,GAAG,gBAAgB,CAAC,CAOrC;AAGD,OAAO,EACL,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAML,gBAAgB,EAKjB,MAAM,wBAAwB,CAAC;AAsBhC;;GAEG;AACH,MAAM,WAAW,IAAI;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH;AA6ED,wBAAgB,QAAQ,IAAI,IAAI,EAAE,CA2xEjC;AAED;;GAEG;AACH,KAAK,WAAW,GAAG,CACjB,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC1B,OAAO,CAAC,OAAO,CAAC,CAAC;AA6EtB;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS,GACnB,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAq+B7B;AAqCD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,CAAC,CA4DlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,SAAS,EACpB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,GAAE,OAAe,GACrB,OAAO,CAAC,OAAO,GAAG,gBAAgB,CAAC,CAOrC;AAGD,OAAO,EACL,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,KAAK,gBAAgB,GACtB,MAAM,wBAAwB,CAAC"}

package/dist/tools/index.js

@@ -17,6 +17,9 @@
 import { ValidationError, ApiError, validateToolArgs, formatMCPError, transformError, validateTicket, filterWarningsByStrictness, } from '../validation/index.js';
 import { resolvePatternsWithCache, getPatternOverrides, flattenCodeStandards, } from '../patterns/index.js';
 import { getResponseModeFromArgs, formatWriteResponse, } from '../lib/response.js';
+import { createFeedbackHandler } from './core/feedback.js';
+import { createWorkflowGuideHandler } from './core/workflow-guide.js';
+import { WORKFLOW_TYPES } from '../lib/workflow-definitions.js';
 /**
  * Get list of all available tools
  *
@@ -1049,7 +1052,7 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
         // ========================================================================
         {
             name: 'create_specification',
-            description: 'Create a new specification with optional nested epics and tickets for bulk creation',
+            description: 'Create a new specification with full context. Create epics separately using epic.create for better quality.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1166,32 +1169,6 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
                         type: 'string',
                         description: 'Who this specification is for (developers, users, stakeholders, etc.)',
                     },
-                    epics: {
-                        type: 'array',
-                        description: 'Nested epics to create (bulk creation)',
-                        items: {
-                            type: 'object',
-                            properties: {
-                                title: { type: 'string' },
-                                description: { type: 'string' },
-                                objective: { type: 'string' },
-                                tickets: {
-                                    type: 'array',
-                                    items: {
-                                        type: 'object',
-                                        properties: {
-                                            title: { type: 'string' },
-                                            description: { type: 'string' },
-                                            acceptanceCriteria: { type: 'array', items: { type: 'string' } },
-                                            estimatedHours: { type: 'number' },
-                                        },
-                                        required: ['title'],
-                                    },
-                                },
-                            },
-                            required: ['title', 'description', 'objective'],
-                        },
-                    },
                     // Pattern inheritance fields (specification level)
                     codeStandards: {
                         type: 'object',
@@ -1240,7 +1217,7 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
         },
         {
             name: 'create_epic',
-            description: 'Create a new epic in a specification with optional nested tickets for bulk creation',
+            description: 'Create a new epic in a specification with full context. Create tickets separately using ticket.create for better quality.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -1338,30 +1315,6 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
                         type: 'number',
                         description: 'Total estimated hours for epic',
                     },
-                    tickets: {
-                        type: 'array',
-                        description: 'Nested tickets to create (bulk creation) with optional inline dependencies',
-                        items: {
-                            type: 'object',
-                            properties: {
-                                title: { type: 'string' },
-                                description: { type: 'string' },
-                                acceptanceCriteria: { type: 'array', items: { type: 'string' } },
-                                estimatedHours: { type: 'number' },
-                                complexity: { type: 'string', enum: ['small', 'medium', 'large', 'xlarge'] },
-                                priority: { type: 'string', enum: ['high', 'medium', 'low'] },
-                                implementation: { type: 'object', description: 'Implementation details' },
-                                technicalDetails: { type: 'object', description: 'Technical details' },
-                                tags: { type: 'array', items: { type: 'string' } },
-                                dependsOn: {
-                                    type: 'array',
-                                    items: { type: 'number' },
-                                    description: 'Indexes of other tickets in this array that this ticket depends on',
-                                },
-                            },
-                            required: ['title'],
-                        },
-                    },
                     // Pattern inheritance fields (epic level)
                     sharedPatterns: {
                         type: 'object',
@@ -2328,6 +2281,115 @@ At least one scope filter (projectId, specificationId, or epicId) is required.`,
                 required: [],
             },
         },
+        // ========================================================================
+        // Feedback Tool (Local-only)
+        // ========================================================================
+        {
+            name: 'feedback',
+            description: `Submit and manage feedback about MCP tools. Operations:
+- submit: Submit new feedback (requires category, summary)
+- list: List recent feedback entries
+- get: Get a specific feedback entry by ID`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    operation: {
+                        type: 'string',
+                        enum: ['submit', 'list', 'get'],
+                        description: 'The operation to perform',
+                    },
+                    // For submit operation
+                    category: {
+                        type: 'string',
+                        enum: ['bug', 'feature_request', 'usability', 'documentation', 'performance'],
+                        description: 'Feedback category (required for submit)',
+                    },
+                    summary: {
+                        type: 'string',
+                        description: 'Brief summary of the feedback (required for submit)',
+                    },
+                    severity: {
+                        type: 'string',
+                        enum: ['critical', 'high', 'medium', 'low'],
+                        description: 'Severity level (default: medium)',
+                    },
+                    tool: {
+                        type: 'string',
+                        description: 'Which MCP tool this relates to',
+                    },
+                    toolOperation: {
+                        type: 'string',
+                        description: 'Specific operation within the tool',
+                    },
+                    details: {
+                        type: 'string',
+                        description: 'Extended description',
+                    },
+                    expected: {
+                        type: 'string',
+                        description: 'Expected behavior',
+                    },
+                    actual: {
+                        type: 'string',
+                        description: 'Actual behavior',
+                    },
+                    errorMessage: {
+                        type: 'string',
+                        description: 'Error message if reporting a bug',
+                    },
+                    ticketId: {
+                        type: 'string',
+                        description: 'Related ticket ID',
+                    },
+                    // For list operation
+                    limit: {
+                        type: 'number',
+                        description: 'Maximum entries to return (default: 10)',
+                    },
+                    categoryFilter: {
+                        type: 'string',
+                        enum: ['bug', 'feature_request', 'usability', 'documentation', 'performance'],
+                        description: 'Filter by category',
+                    },
+                    // For get operation
+                    feedbackId: {
+                        type: 'string',
+                        description: 'Feedback ID to retrieve (required for get)',
+                    },
+                },
+                required: ['operation'],
+            },
+        },
+        // ========================================================================
+        // Workflow Guide Tool
+        // ========================================================================
+        {
+            name: 'workflow_guide',
+            description: `Get guidance for SpecForge workflows. Operations:
+- guide: Get full workflow instructions for a workflow type
+- status: Get current workflow state and progress
+- next: Get the specific next action to take`,
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    operation: {
+                        type: 'string',
+                        enum: ['guide', 'status', 'next'],
+                        description: 'The operation to perform',
+                    },
+                    workflowType: {
+                        type: 'string',
+                        enum: WORKFLOW_TYPES,
+                        description: 'Workflow type (required for guide): creation, implementation, review, finalize',
+                    },
+                    specificationId: {
+                        type: 'string',
+                        description: 'Specification ID (uses working context if not provided)',
+                    },
+                },
+                required: ['operation'],
+            },
+        },
     ];
     // Apply format parameter to all read operations
     return tools.map(tool => READ_TOOL_NAMES.has(tool.name) ? addFormatParameter(tool) : tool);
@@ -2898,7 +2960,6 @@ export function createToolHandlers(apiClient) {
                 priority: args.priority,
                 tags: args.tags,
                 estimatedHours: args.estimatedHours,
-                epics: args.epics,
                 // FI-003 fields
                 nonFunctionalRequirements: args.nonFunctionalRequirements,
                 successMetrics: args.successMetrics,
@@ -2921,48 +2982,6 @@ export function createToolHandlers(apiClient) {
         create_epic: async (_client, args) => {
             validateRequired(args, 'specificationId', 'title', 'description', 'objective');
             const responseMode = getResponseModeFromArgs(args);
-            // Validate inline dependencies if tickets are provided with dependsOn
-            if (args.tickets && Array.isArray(args.tickets)) {
-                const tickets = args.tickets;
-                const ticketCount = tickets.length;
-                for (let i = 0; i < ticketCount; i++) {
-                    const ticket = tickets[i];
-                    if (ticket.dependsOn && Array.isArray(ticket.dependsOn)) {
-                        for (const depIndex of ticket.dependsOn) {
-                            // Check bounds
-                            if (typeof depIndex !== 'number' || depIndex < 0 || depIndex >= ticketCount) {
-                                throw new Error(`tickets[${i}].dependsOn: index ${depIndex} is out of bounds (must be 0-${ticketCount - 1})`);
-                            }
-                            // Check self-reference
-                            if (depIndex === i) {
-                                throw new Error(`tickets[${i}].dependsOn: ticket cannot depend on itself`);
-                            }
-                        }
-                    }
-                }
-                // Check for circular dependencies using DFS
-                const hasCycle = (startIdx, visited, path) => {
-                    if (path.has(startIdx))
-                        return true;
-                    if (visited.has(startIdx))
-                        return false;
-                    visited.add(startIdx);
-                    path.add(startIdx);
-                    const deps = tickets[startIdx].dependsOn || [];
-                    for (const depIdx of deps) {
-                        if (hasCycle(depIdx, visited, path))
-                            return true;
-                    }
-                    path.delete(startIdx);
-                    return false;
-                };
-                const visited = new Set();
-                for (let i = 0; i < ticketCount; i++) {
-                    if (hasCycle(i, visited, new Set())) {
-                        throw new Error(`Circular dependency detected in tickets array`);
-                    }
-                }
-            }
             const result = await apiClient.call('create_epic', {
                 specificationId: args.specificationId,
                 title: args.title,
@@ -2977,7 +2996,6 @@ export function createToolHandlers(apiClient) {
                 tags: args.tags,
                 estimatedHours: args.estimatedHours,
                 order: args.order,
-                tickets: args.tickets,
                 // FI-003 fields
                 guardrails: args.guardrails,
                 risks: args.risks,
@@ -3344,6 +3362,23 @@ export function createToolHandlers(apiClient) {
                 verbose: args.verbose,
             });
         },
+        // ========================================================================
+        // Feedback Tool (Local-only)
+        // ========================================================================
+        feedback: async (_client, args) => {
+            // Get user ID from API client config (or use a default)
+            const userId = 'local-user';
+            const handler = createFeedbackHandler();
+            return await handler(args, userId);
+        },
+        // ========================================================================
+        // Workflow Guide Tool
+        // ========================================================================
+        workflow_guide: async (_client, args) => {
+            const userId = 'local-user';
+            const handler = createWorkflowGuideHandler(apiClient);
+            return await handler(args, userId);
+        },
     };
 }
 /**