interactive_adr_planning

Guide users through structured decision-making to create architectural decision records with research integration, option evaluation, and automatic ADR generation.

Instructions

Interactive guided ADR planning and creation tool - walks users through structured decision-making process with research integration, option evaluation, and automatic ADR generation. TIP: Start by reading @.mcp-server-context.md to understand project context and previous decisions.

Input Schema

TableJSON Schema

Name	Required	Description
`operation`	Yes	Interactive planning operation to perform
`sessionId`	No	Planning session ID (required for all operations except start_session)
`input`	No	User input for the current phase (varies by phase)
`projectPath`	Yes	Project root path
`autoResearch`	No	Automatically trigger research when needed
`generateTodos`	No	Automatically generate TODO items from decisions

Implementation Reference

src/tools/interactive-adr-planning-tool.ts:1358-1422 (handler)

Main exported handler function `interactiveAdrPlanning` that validates input with schema and dispatches to operation-specific handlers (startSession, continueSession, provideInput, etc.). Orchestrates the entire interactive ADR planning workflow.

export async function interactiveAdrPlanning(args: any): Promise<any> {
  try {
    const input = InteractiveAdrPlanningSchema.parse(args);

    switch (input.operation) {
      case 'start_session':
        return await startSession(input);

      case 'continue_session':
        return await continueSession(input);

      case 'provide_input':
        return await provideInput(input);

      case 'request_research':
        return await requestResearch(input);

      case 'evaluate_options':
        return await evaluateOptions(input);

      case 'make_decision':
        input.input = { selectedOption: input.input };
        return await provideInput(input);

      case 'assess_impact':
        input.input = { impacts: input.input };
        return await provideInput(input);

      case 'plan_implementation':
        input.input = { implementation: input.input };
        return await provideInput(input);

      case 'generate_adr':
        return await provideInput(input);

      case 'update_todos':
        return await updateTodos(input);

      case 'get_guidance':
        return await getGuidance(input);

      case 'save_session': {
        const session = sessions.get(input.sessionId!);
        if (!session) throw new McpAdrError('Session not found', 'SESSION_NOT_FOUND');
        await saveSession(session);
        return { success: true, message: 'Session saved' };
      }

      case 'complete_session':
        return await completeSession(input);

      default:
        throw new McpAdrError(`Unknown operation: ${input.operation}`, 'INVALID_OPERATION');
    }
  } catch (error) {
    if (error instanceof McpAdrError) {
      throw error;
    }
    throw new McpAdrError(
      `Interactive ADR planning failed: ${error instanceof Error ? error.message : String(error)}`,
      'PLANNING_ERROR'
    );
  }
}

src/tools/interactive-adr-planning-tool.ts:127-151 (schema)

Primary Zod input schema defining all supported operations and parameters for the interactive ADR planning tool.

const InteractiveAdrPlanningSchema = z.object({
  operation: z.enum([
    'start_session',
    'continue_session',
    'provide_input',
    'request_research',
    'evaluate_options',
    'make_decision',
    'assess_impact',
    'plan_implementation',
    'generate_adr',
    'update_todos',
    'get_guidance',
    'save_session',
    'complete_session',
  ]),
  sessionId: z.string().optional(),
  input: z.any().optional(),
  projectPath: z.string(),
  autoResearch: z.boolean().default(true).describe('Automatically trigger research when needed'),
  generateTodos: z
    .boolean()
    .default(true)
    .describe('Automatically generate TODO items from decisions'),
});

src/tools/tool-catalog.ts:441-461 (registration)

Central tool catalog registration defining metadata, category ('adr'), complexity, token cost estimates, related tools, and JSON input schema for MCP tool discovery and listing.

TOOL_CATALOG.set('interactive_adr_planning', {
  name: 'interactive_adr_planning',
  shortDescription: 'Interactive ADR planning session',
  fullDescription:
    'Guides through an interactive ADR planning session to identify and prioritize decisions.',
  category: 'adr',
  complexity: 'complex',
  tokenCost: { min: 3000, max: 6000 },
  hasCEMCPDirective: true, // Phase 4.2: CE-MCP directive added
  relatedTools: ['suggest_adrs', 'generate_adr_from_decision'],
  keywords: ['adr', 'planning', 'interactive', 'session'],
  requiresAI: true,
  inputSchema: {
    type: 'object',
    properties: {
      projectPath: { type: 'string' },
      sessionMode: { type: 'string', enum: ['guided', 'free-form'] },
    },
    required: ['projectPath'],
  },
});

src/tools/ce-mcp-tools.ts:1406-1409 (registration)
CE-MCP directive registration in getCEMCPDirective switch statement, providing optimized orchestration directive version of the tool.
```
case 'interactive_adr_planning':
  return createInteractiveAdrPlanningDirective(
    args as unknown as CEMCPInteractiveAdrPlanningArgs
  );
```

src/tools/interactive-adr-planning-tool.ts:45-124 (helper)

Internal PlanningSessionSchema used for session state persistence, including phases, context (problem, options, decisions), and metadata. Critical for multi-turn interactive workflow.

const PlanningSessionSchema = z.object({
  sessionId: z.string(),
  phase: z.enum([
    'problem_definition',
    'research_analysis',
    'option_exploration',
    'decision_making',
    'impact_assessment',
    'implementation_planning',
    'adr_generation',
    'completed',
  ]),
  context: z.object({
    projectPath: z.string(),
    adrDirectory: z.string().default('docs/adrs'),
    problemStatement: z.string().optional(),
    researchFindings: z
      .array(
        z.object({
          source: z.string(),
          insight: z.string(),
          relevance: z.string(),
        })
      )
      .default([]),
    options: z
      .array(
        z.object({
          name: z.string(),
          description: z.string(),
          pros: z.array(z.string()),
          cons: z.array(z.string()),
          risks: z.array(z.string()),
          effort: z.enum(['low', 'medium', 'high']),
          confidence: z.number().min(0).max(100),
        })
      )
      .default([]),
    selectedOption: z
      .object({
        name: z.string(),
        rationale: z.string(),
        tradeoffs: z.array(z.string()),
      })
      .optional(),
    impacts: z
      .object({
        technical: z.array(z.string()).default([]),
        business: z.array(z.string()).default([]),
        team: z.array(z.string()).default([]),
        risks: z.array(z.string()).default([]),
        dependencies: z.array(z.string()).default([]),
      })
      .optional(),
    implementation: z
      .object({
        phases: z.array(z.string()).default([]),
        tasks: z
          .array(
            z.object({
              description: z.string(),
              priority: z.enum(['low', 'medium', 'high', 'critical']),
              effort: z.string(),
              assignee: z.string().optional(),
            })
          )
          .default([]),
        timeline: z.string().optional(),
        successCriteria: z.array(z.string()).default([]),
      })
      .optional(),
    adrContent: z.string().optional(),
  }),
  metadata: z.object({
    createdAt: z.string(),
    updatedAt: z.string(),
    lastAction: z.string(),
    nextSteps: z.array(z.string()).default([]),
  }),
});

mcp-adr-analysis-server