Tool Context Documentation System - Implementation Plan
Overviewโ
This document outlines the design and implementation plan for a persistent context documentation system that captures tool execution results and project-specific patterns for reuse in future sessions.
Problem Statementโ
When tools like bootstrap_validation_loop run, they generate valuable context including:
- Platform detection results
- Validated patterns and deployment strategies
- Environment-specific configurations
- Learnings from execution (successes/failures)
- Architectural decisions
Currently, this context is lost after the session ends. Developers have to re-discover or re-analyze the same information in future sessions, especially problematic for:
- LLMs with limited context windows (e.g., Gemini)
- Long-term project maintenance
- Team onboarding
- CI/CD pipeline consistency
Solution: Tool Context Documentsโ
Generate persistent, project-specific context documents that can be:
- Automatically created by tools during execution
- Stored in a predictable location within the project
- Easily referenced by developers and LLMs in future prompts
- Version controlled alongside code and ADRs
Context Document Schemaโ
Standard Structureโ
All context documents follow a consistent markdown format:
# Tool Context: {Tool Name}
> **Generated**: {ISO timestamp}
> **Tool Version**: {version}
> **Project**: {project name/path}
## Quick Reference
Brief summary for immediate use (1-2 paragraphs)
## Execution Summary
- **Status**: Success | Failed | Partial
- **Confidence**: {0-100}%
- **Key Findings**: Bullet list of main outcomes
## Detected Context
### Platform/Environment
- Primary: {platform}
- Confidence: {percentage}
- Evidence: {key evidence files/indicators}
### Project Configuration
- Architecture: {detected architecture}
- Technologies: {list}
- Deployment Target: {target}
### Validated Pattern (if applicable)
- **Pattern Name**: {e.g., Multicluster GitOps, Industrial Edge, Medical Diagnosis}
- **Version**: {pattern version}
- **Pattern Type**: {platform type}
- **Base Repository**: {GitHub URL}
- **Documentation**: {pattern docs URL}
- **Authoritative Sources**: {list of required sources}
- **Why Chosen**: {rationale for this pattern}
- **Deployment Phases**: {number of phases}
- **Validation Checks**: {number of checks}
## Generated Artifacts
List of files/ADRs/configs created by this tool execution
## Key Decisions
Architectural and deployment decisions made during execution
## Learnings & Recommendations
### Successes โ
- What worked well
### Failures โ ๏ธ
- What didn't work
- Recommendations for fixes
### Environment-Specific Notes
- Special considerations for this environment
## Usage in Future Sessions
### How to Reference This Context
```text
Example prompt:
"Using the context from docs/context/bootstrap-{timestamp}.md,
continue the deployment process for {platform}"
```
Related Documentsโ
- ADRs:
{links} - Other context docs:
{links} - Configuration files:
{links}
Raw Data (Optional)โ
Full execution output
{
// Complete execution result for debugging
}
Auto-generated by {tool_name} v{version}
### Schema Fields
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `tool_name` | string | Yes | Name of the tool that generated this |
| `generated` | ISO datetime | Yes | When this context was created |
| `tool_version` | semver | Yes | Tool version for compatibility |
| `project` | string | Yes | Project identifier |
| `status` | enum | Yes | Success, Failed, Partial |
| `confidence` | number (0-100) | No | Confidence in results |
| `detected_context` | object | Yes | Platform, tech stack, architecture |
| `artifacts` | array[string] | No | Files/ADRs created |
| `decisions` | array[Decision] | No | Key architectural decisions |
| `learnings` | array[Learning] | No | Successes, failures, recommendations |
| `related_docs` | array[string] | No | Links to ADRs, configs, etc. |
---
## Storage Strategy
### Directory Structure
docs/ โโโ context/ โ โโโ README.md # Overview of context system โ โโโ bootstrap/ โ โ โโโ latest.md # Symlink to most recent โ โ โโโ bootstrap-20250119T143022.md # Timestamped execution โ โ โโโ bootstrap-20250115T091533.md # Historical context โ โโโ deployment/ โ โ โโโ latest.md โ โ โโโ deployment-analysis-20250119.md โ โโโ environment/ โ โ โโโ latest.md โ โ โโโ environment-analysis-20250118.md โ โโโ research/ โ โ โโโ latest.md โ โ โโโ openshift-research-20250119.md โ โ โโโ kubernetes-research-20250117.md โ โโโ planning/ โ โโโ latest.md โ โโโ adr-planning-session-20250116.md
### File Naming Convention
**Format**: `{tool-category}-{detail}-{ISO-date}.md`
**Examples**:
- `bootstrap-openshift-20250119T143022.md`
- `deployment-readiness-check-20250119T101500.md`
- `research-validated-patterns-20250118T154433.md`
- `planning-microservices-architecture-20250115.md`
### Retention Policy
- **latest.md**: Always points to most recent context for that category
- **Historical**: Keep last 10 executions per category
- **Archive**: Move older contexts to `docs/context/archive/` after 30 days
- **Cleanup**: Add cleanup script to prune old contexts
---
## Tools Benefiting from Context Generation
### 1. Bootstrap & Deployment Tools
#### `bootstrap_validation_loop`
**Context Generated**:
- Platform detection (OpenShift, Kubernetes, Docker, etc.)
- Validated pattern selection and configuration
- Research report from authoritative sources
- Deployment plan with architecture diagrams
- Environment snapshot (running services, versions)
- Execution learnings (what worked, what failed)
- Bootstrap ADR path and status
**Context Document**: `docs/context/bootstrap/bootstrap-{platform}-{timestamp}.md`
**Value**: Developers can reference the exact validated pattern, deployment steps, and environment configuration in future sessions without re-running detection.
---
#### `deployment_readiness`
**Context Generated**:
- Readiness assessment (pass/fail for deployment gates)
- Missing prerequisites and blockers
- Deployment risks and mitigation strategies
- Compliance checks (security, performance, architecture)
**Context Document**: `docs/context/deployment/readiness-{timestamp}.md`
**Value**: Track deployment readiness over time, understand what changed between attempts.
---
#### `deployment_analysis`
**Context Generated**:
- Current deployment state analysis
- Resource utilization and health
- Deployment history and patterns
- Recommended optimizations
**Context Document**: `docs/context/deployment/analysis-{timestamp}.md`
**Value**: Maintain historical deployment insights for troubleshooting and optimization.
---
### 2. Environment & Research Tools
#### `environment_analysis`
**Context Generated**:
- Detected environment configuration
- Available tools and versions
- Infrastructure capabilities
- Environment-specific constraints
**Context Document**: `docs/context/environment/analysis-{timestamp}.md`
**Value**: Preserve environment details for consistent deployments across sessions.
---
#### `perform_research` / `research_integration`
**Context Generated**:
- Research questions asked
- Sources consulted (authoritative docs, GitHub, Stack Overflow)
- Research findings and confidence scores
- Technology decisions based on research
- Cached research results
**Context Document**: `docs/context/research/{topic}-research-{timestamp}.md`
**Value**: Avoid re-researching the same topics, maintain knowledge base of research findings.
---
### 3. Planning & Decision Tools
#### `interactive_adr_planning`
**Context Generated**:
- Planning session decisions
- Architectural options considered
- Trade-offs analyzed
- Selected approach and rationale
- ADRs created from planning
**Context Document**: `docs/context/planning/session-{timestamp}.md`
**Value**: Preserve planning decisions and rationale for future reference and ADR updates.
---
#### `adr_validation`
**Context Generated**:
- Validation results (ADR compliance)
- Detected inconsistencies or gaps
- Recommendations for improvements
- ADR quality scores
**Context Document**: `docs/context/validation/adr-validation-{timestamp}.md`
**Value**: Track ADR quality over time, maintain validation history.
---
### 4. Git & Workflow Tools
#### `smart_git_push`
**Context Generated**:
- Git workflow patterns used
- Commit conventions followed
- Branch strategies detected
- Push validation results
**Context Document**: `docs/context/git/workflow-{timestamp}.md`
**Value**: Maintain consistent git practices across sessions.
---
## Implementation Plan
### Phase 1: Core Infrastructure (Week 1)
#### 1.1 Create Context Manager Utility
**File**: `src/utils/context-document-manager.ts`
```typescript
export interface ToolContextMetadata {
toolName: string;
toolVersion: string;
generated: string; // ISO timestamp
projectPath: string;
projectName: string;
status: 'success' | 'failed' | 'partial';
confidence?: number;
}
export interface ToolContextDocument {
metadata: ToolContextMetadata;
quickReference: string;
executionSummary: {
status: string;
confidence?: number;
keyFindings: string[];
};
detectedContext: Record<string, any>;
generatedArtifacts?: string[];
keyDecisions?: Array<{
decision: string;
rationale: string;
alternatives?: string[];
}>;
learnings?: {
successes: string[];
failures: string[];
recommendations: string[];
environmentSpecific: string[];
};
relatedDocuments?: {
adrs: string[];
configs: string[];
otherContexts: string[];
};
rawData?: any;
}
export class ToolContextManager {
private contextDir: string;
constructor(projectPath: string) {
this.contextDir = path.join(projectPath, 'docs', 'context');
}
async initialize(): Promise<void>;
async saveContext(
category: string,
document: ToolContextDocument
): Promise<string>;
async loadLatestContext(category: string): Promise<ToolContextDocument | null>;
async loadContextByTimestamp(
category: string,
timestamp: string
): Promise<ToolContextDocument | null>;
async listContexts(category: string): Promise<string[]>;
async updateLatestSymlink(category: string, filePath: string): Promise<void>;
async cleanupOldContexts(
category: string,
keepCount: number = 10
): Promise<void>;
generateMarkdown(document: ToolContextDocument): string;
}
Tests: tests/utils/context-document-manager.test.ts
1.2 Create README for Context Systemโ
File: docs/context/README.md
Explain:
- Purpose of context documents
- How to use them in prompts
- File organization
- Retention policy
- Examples of referencing context
Phase 2: Bootstrap Tool Integration (Week 2)โ
2.1 Integrate Context Generation into Bootstrap Toolโ
File: src/tools/bootstrap-validation-loop-tool.ts
Add context generation at key points:
import { ToolContextManager, ToolContextDocument } from '../utils/context-document-manager.js';
// In BootstrapValidationLoop class
private contextManager: ToolContextManager;
constructor(projectPath: string, adrDirectory: string, maxIterations: number = 5) {
// ... existing initialization
this.contextManager = new ToolContextManager(projectPath);
}
// After deployment plan generation (line ~270)
async saveBootstrapContext(
platformDetection: PlatformDetectionResult,
validatedPattern: ValidatedPattern | null,
deploymentPlan: DynamicDeploymentPlan,
bootstrapAdrPath: string
): Promise<void> {
const contextDoc: ToolContextDocument = {
metadata: {
toolName: 'bootstrap_validation_loop',
toolVersion: '1.0.0',
generated: new Date().toISOString(),
projectPath: this.projectPath,
projectName: path.basename(this.projectPath),
status: 'success',
confidence: platformDetection.confidence * 100,
},
quickReference: `
Detected ${platformDetection.primaryPlatform} (${(platformDetection.confidence * 100).toFixed(0)}% confidence).
Using validated pattern: ${validatedPattern?.name || 'Dynamic AI Analysis'}.
Bootstrap ADR: ${bootstrapAdrPath}
`,
executionSummary: {
status: 'Platform detected and deployment plan generated',
confidence: platformDetection.confidence * 100,
keyFindings: [
`Primary platform: ${platformDetection.primaryPlatform}`,
`Validated pattern: ${validatedPattern?.name || 'N/A'}`,
`Required files: ${deploymentPlan.requiredFiles.length}`,
`Deployment steps: ${deploymentPlan.deploymentSteps.length}`,
],
},
detectedContext: {
platform: {
primary: platformDetection.primaryPlatform,
all: platformDetection.detectedPlatforms.map(p => p.type),
confidence: platformDetection.confidence,
evidence: platformDetection.evidence.slice(0, 10),
},
validatedPattern: validatedPattern ? {
name: validatedPattern.name,
version: validatedPattern.version,
platformType: validatedPattern.platformType,
baseRepository: validatedPattern.baseCodeRepository.url,
authoritativeSources: validatedPattern.authoritativeSources.map(s => ({
type: s.type,
url: s.url,
required: s.requiredForDeployment,
})),
} : null,
deploymentPlan: {
recommendedPlatform: deploymentPlan.recommendedPlatform,
confidence: deploymentPlan.confidence,
source: deploymentPlan.source,
requiredFiles: deploymentPlan.requiredFiles.map(f => ({
path: f.path,
purpose: f.purpose,
required: f.required,
})),
environmentVariables: deploymentPlan.environmentVariables.map(e => ({
name: e.name,
required: e.required,
isSecret: e.isSecret,
})),
deploymentSteps: deploymentPlan.deploymentSteps.length,
estimatedDuration: deploymentPlan.estimatedDuration,
},
},
generatedArtifacts: [
bootstrapAdrPath,
path.join(this.projectPath, 'bootstrap.sh'),
path.join(this.projectPath, 'validate_bootstrap.sh'),
],
keyDecisions: [
{
decision: `Use ${platformDetection.primaryPlatform} as deployment platform`,
rationale: `Detected with ${(platformDetection.confidence * 100).toFixed(0)}% confidence based on project structure and configuration files`,
},
],
relatedDocuments: {
adrs: [bootstrapAdrPath],
configs: deploymentPlan.requiredFiles.map(f => f.path),
otherContexts: [],
},
};
await this.contextManager.saveContext('bootstrap', contextDoc);
}
Call this method after creating the bootstrap ADR (around line 270):
// After line 270: bootstrapAdrPath created
await this.saveBootstrapContext(
this.platformDetection!,
this.validatedPattern,
this.deploymentPlan!,
bootstrapAdrPath
);
2.2 Update Bootstrap Results to Include Context Pathโ
Modify the return type of executeLoop to include context document path:
return {
success,
iterations: this.currentIteration,
finalResult,
adrUpdates,
executionHistory: this.executionHistory,
deploymentPlan: this.deploymentPlan,
bootstrapAdrPath,
contextDocumentPath: contextDocPath, // NEW
requiresHumanApproval: true,
};
Phase 3: Extend to Other Tools (Week 3-4)โ
Apply similar context generation to:
- deployment_readiness โ
docs/context/deployment/readiness-{timestamp}.md - environment_analysis โ
docs/context/environment/analysis-{timestamp}.md - perform_research โ
docs/context/research/{topic}-{timestamp}.md - interactive_adr_planning โ
docs/context/planning/session-{timestamp}.md
Each tool should:
- Use
ToolContextManagerto save context - Generate appropriate
ToolContextDocument - Return context document path in results
- Update
latest.mdsymlink for the category
Phase 4: Usage Patterns & Documentation (Week 4)โ
4.1 Create Usage Guideโ
File: docs/how-to-guides/using-tool-context-documents.md
Content:
- How to reference context in prompts
- Examples for different LLMs (Claude, Gemini, GPT-4)
- Best practices for context injection
- How to find the right context document
- How context improves consistency
4.2 Update Tool Documentationโ
Add sections to each tool's documentation:
- Context Generation: What context this tool creates
- Using Context: How to reference generated context in future sessions
- Context Location: Where to find the context document
4.3 LLM Integration Examplesโ
For Gemini (limited context):
System instructions:
"Before generating ADRs or deployment plans, always check for and read:
1. docs/context/bootstrap/latest.md - For platform and deployment context
2. docs/context/environment/latest.md - For environment configuration
3. docs/context/research/latest.md - For research findings
These context documents contain project-specific validated patterns and decisions."
For Claude (via CLAUDE.md):
## Tool Context Documents
This project uses tool context documents to preserve execution results and decisions.
**Location**: `docs/context/`
**Key Documents**:
- `docs/context/bootstrap/latest.md` - Latest bootstrap/deployment context
- `docs/context/environment/latest.md` - Environment analysis
- `docs/context/research/latest.md` - Research findings
**Usage**: When starting a new session related to deployment, architecture, or infrastructure:
1. Read the relevant latest.md file in docs/context/
2. Use the context to inform decisions and maintain consistency
3. Reference specific decisions and validated patterns from context docs