adr-skills

Instructions

Implementation Reference

• adr.js:42-84 (handler)

  The implementation of the ADR review logic which calls the Claude API.

  export async function reviewADR(adr) {
    const stream = client.messages.stream({
      model: 'claude-opus-4-6',
      max_tokens: 2048,
      thinking: { type: 'adaptive' },
      system: `You are a senior software architect reviewing Architecture Decision Records for quality and completeness.
  Evaluate the ADR critically and return a JSON review with this exact structure:
  
  {
    "score": <integer 0-100>,
    "summary": "One-sentence overall assessment",
    "issues": [
      { "severity": "high|medium|low", "field": "context|decision|consequences|title", "message": "specific problem description" }
    ],
    "suggestions": [
      "Concrete, actionable improvement suggestion"
    ]
  }
  
  Evaluate against these criteria:
  - Context: Is the problem clearly stated? Are constraints and forces explained?
  - Decision: Are alternatives considered and rejected? Is the rationale explicit?
  - Consequences: Are both positive and negative outcomes listed? Are risks acknowledged?
  - Title: Does it capture the decision, not just the topic?`,
      messages: [
        {
          role: 'user',
          content: `Review this ADR for quality:\n\n# ${adr.title}\n\n## Context\n${adr.context}\n\n## Decision\n${adr.decision}\n\n## Consequences\n${adr.consequences}`,
        },
      ],
    });
  
    const response = await stream.finalMessage();
  
    for (const block of response.content) {
      if (block.type === 'text') {
        const match = block.text.match(/\{[\s\S]*\}/);
        if (match) return JSON.parse(match[0]);
      }
    }
  
    throw new Error('Failed to parse review JSON from AI response');
  }

• index.js:157-192 (registration)

  Registration of the `review_adr` tool and its MCP handler.

  server.registerTool('review_adr', {
    description: 'AI quality review of an ADR — scores completeness, flags missing context, unconsidered alternatives, and optimistic consequences',
    inputSchema: {
      adr_id: z.number().describe('ADR ID to review'),
    },
  }, async ({ adr_id }) => {
    if (!process.env.ANTHROPIC_API_KEY) {
      throw new Error('ANTHROPIC_API_KEY is required for AI review');
    }
  
    const adr = getADR(adr_id);
    if (!adr) throw new Error(`ADR ${adr_id} not found`);
  
    const review = await reviewADR(adr);
  
    const severityIcon = { high: '🔴', medium: '🟡', low: '🟢' };
    const issueLines = (review.issues ?? [])
      .map(i => `${severityIcon[i.severity] ?? '•'} [${i.field}] ${i.message}`)
      .join('\n') || 'No issues found';
  
    const suggestionLines = (review.suggestions ?? [])
      .map((s, i) => `${i + 1}. ${s}`)
      .join('\n') || 'No suggestions';
  
    const output = `## ADR-${adr_id} Review — Score: ${review.score}/100
  
  **${review.summary}**
  
  ### Issues
  ${issueLines}
  
  ### Suggestions
  ${suggestionLines}`;
  
    return { content: [{ type: 'text', text: output }] };
  });