bootstrap/runtime/claude/context7-integration.md

# Context7 Integration for Atomic Code Implementer

## Overview

The atomic-code-implementer agent uses Context7 MCP server to dynamically fetch up-to-date documentation for libraries and frameworks. This integration provides real-time access to the latest API documentation, best practices, and code examples.

## Integration Points

### 1. Preset-Driven Documentation Lookup

Each preset configuration includes a `context7Libraries` array that specifies which libraries to fetch documentation for:

```json
{
  "context7Libraries": [
    "@nestjs/common",
    "@nestjs/core", 
    "@nestjs/typeorm",
    "typeorm",
    "class-validator"
  ]
}
```

When a preset is loaded, the agent automatically resolves and fetches documentation for all specified libraries.

### 2. Error-Driven Documentation Lookup

When build errors, type errors, or runtime issues occur, the agent can automatically lookup documentation for:

- Error resolution patterns
- API migration guides
- Breaking change documentation
- Best practice guidelines

### 3. Implementation-Driven Lookup

During atomic task implementation, the agent can fetch:

- Framework-specific implementation patterns
- Library-specific configuration examples
- Performance optimization techniques
- Security best practices

## Context7 Usage Patterns

### Library Resolution

```javascript
// Resolve library ID from preset configuration
const libraryId = await mcp__context7__resolve_library_id({
  libraryName: "@nestjs/common"
});
```

### Documentation Retrieval

```javascript
// Get comprehensive documentation
const docs = await mcp__context7__get_library_docs({
  context7CompatibleLibraryID: "/nestjs/nest",
  topic: "controllers",
  tokens: 8000
});
```

### Error-Specific Lookups

```javascript
// Look up specific error patterns
const errorDocs = await mcp__context7__get_library_docs({
  context7CompatibleLibraryID: "/typescript/typescript",
  topic: "type errors",
  tokens: 5000
});
```

## Automatic Lookup Triggers

### 1. Preset Loading Phase
When an atomic task is started:
1. Detect tech stack from file extensions
2. Load appropriate preset configuration
3. Extract `context7Libraries` array
4. Resolve all library IDs
5. Fetch relevant documentation based on task context

### 2. Error Detection Phase  
When quality hooks detect issues:
1. Parse error messages for library/framework references
2. Resolve documentation for problematic libraries
3. Look up error-specific resolution patterns
4. Apply common fixes based on documentation

### 3. Implementation Phase
During code implementation:
1. Detect new library imports or API usage
2. Automatically fetch documentation for unknown patterns
3. Provide implementation examples and best practices
4. Validate against latest API specifications

## Context7 Library Mappings

### NestJS Backend
```json
{
  "@nestjs/common": "/nestjs/nest",
  "@nestjs/typeorm": "/nestjs/typeorm", 
  "typeorm": "/typeorm/typeorm",
  "class-validator": "/typestack/class-validator",
  "bcrypt": "/kelektiv/node.bcrypt.js"
}
```

### React Frontend
```json
{
  "react": "/facebook/react",
  "react-dom": "/facebook/react",
  "@tanstack/react-query": "/tanstack/query",
  "tailwindcss": "/tailwindlabs/tailwindcss",
  "@testing-library/react": "/testing-library/react-testing-library"
}
```

### Python FastAPI
```json
{
  "fastapi": "/tiangolo/fastapi",
  "sqlalchemy": "/sqlalchemy/sqlalchemy",
  "pydantic": "/samuelcolvin/pydantic",
  "pytest": "/pytest-dev/pytest"
}
```

## Integration Workflow

### Sequential Thinking Enhanced Lookup

```markdown
1. **Preset Analysis Phase**
   - Use sequential thinking to determine optimal documentation needs
   - Analyze task requirements for specific library features
   - Prioritize documentation lookup based on complexity

2. **Dynamic Documentation Loading**
   - Load core framework documentation first
   - Fetch specialized library docs based on task specifics
   - Cache documentation for session reuse

3. **Implementation Guidance**
   - Use retrieved docs to guide implementation decisions
   - Apply documented best practices and patterns
   - Validate implementation against official examples
```

### Error Resolution Workflow

```markdown
1. **Error Detection**
   - Parse error messages for library/API references
   - Identify deprecated or changed APIs
   - Extract relevant context from error stack traces

2. **Documentation Lookup**
   - Resolve library documentation for error context
   - Fetch migration guides for breaking changes
   - Look up troubleshooting and FAQ sections

3. **Automated Remediation**
   - Apply documented fixes and workarounds
   - Update code to use current APIs
   - Add proper error handling based on docs
```

## Configuration Examples

### Preset Configuration with Context7

```json
{
  "name": "NestJS HIPAA Healthcare",
  "techStack": {
    "framework": "NestJS",
    "database": "TypeORM + PostgreSQL"
  },
  "context7Libraries": [
    "@nestjs/common",
    "@nestjs/typeorm", 
    "typeorm",
    "bcrypt",
    "helmet"
  ],
  "context7Topics": {
    "security": ["authentication", "authorization", "encryption"],
    "database": ["migrations", "relationships", "transactions"], 
    "testing": ["unit tests", "integration tests", "mocking"]
  },
  "context7AutoLookup": {
    "onError": true,
    "onImport": true,
    "onDeprecation": true
  }
}
```

### Agent Integration Points

```markdown
## Context7 Integration in atomic-code-implementer.md

### Phase 1: Preset Loading
```javascript
// Load preset and resolve documentation
const preset = loadPreset(detectedTechStack, domainContext);
const libraryDocs = await loadContext7Documentation(preset.context7Libraries);
```

### Phase 2: Implementation Guidance
```javascript
// Get implementation examples during coding
const implementationDocs = await mcp__context7__get_library_docs({
  context7CompatibleLibraryID: "/nestjs/nest",
  topic: "controllers authentication",
  tokens: 6000
});
```

### Phase 3: Error Resolution
```javascript
// Look up error-specific documentation
if (buildError.includes("TypeError: Cannot read property")) {
  const errorDocs = await mcp__context7__get_library_docs({
    context7CompatibleLibraryID: extractLibraryFromError(buildError),
    topic: "common errors troubleshooting",
    tokens: 4000
  });
}
```
```

## Best Practices

### 1. Documentation Caching
- Cache resolved library IDs for session duration
- Store frequently accessed documentation locally
- Implement intelligent cache invalidation

### 2. Context-Aware Lookups
- Tailor documentation queries to specific atomic task context
- Use targeted topics rather than generic documentation
- Prioritize relevant sections based on implementation needs

### 3. Error-Driven Learning
- Maintain error pattern → documentation mapping
- Learn from successful error resolutions
- Build knowledge base of common issues and solutions

### 4. Performance Optimization
- Batch documentation requests when possible
- Use appropriate token limits for different use cases
- Implement request deduplication

## Troubleshooting

### Common Issues

1. **Library Not Found**
   ```javascript
   // Fallback to generic search
   const fallbackId = await mcp__context7__resolve_library_id({
     libraryName: `${libraryName} documentation`
   });
   ```

2. **Documentation Too Generic**
   ```javascript
   // Use more specific topics
   const specificDocs = await mcp__context7__get_library_docs({
     context7CompatibleLibraryID: libraryId,
     topic: `${specificFeature} implementation examples`,
     tokens: 8000
   });
   ```

3. **Rate Limiting**
   ```javascript
   // Implement exponential backoff
   const docs = await retryWithBackoff(() => 
     mcp__context7__get_library_docs(params)
   );
   ```

This integration ensures the atomic code implementer always has access to the most current and relevant documentation, enabling it to produce high-quality, up-to-date implementations while following current best practices.