feat: integrate framework files into monorepo under packages/mosaic/framework/

Moves all Mosaic framework runtime files from the separate bootstrap repo into the monorepo as canonical source. The @mosaic/mosaic npm package now ships the complete framework — bin scripts, runtime configs, tools, and templates — enabling standalone installation via npm install. Structure: packages/mosaic/framework/ ├── bin/ 28 CLI scripts (mosaic, mosaic-doctor, mosaic-sync-skills, etc.) ├── runtime/ Runtime adapters (claude, codex, opencode, pi, mcp) ├── tools/ Shell tooling (git, prdy, orchestrator, quality, etc.) ├── templates/ Agent and repo templates ├── defaults/ Default identity files (AGENTS.md, STANDARDS.md, SOUL.md, etc.) ├── install.sh Legacy bash installer └── remote-install.sh One-liner remote installer Key files with Pi support and recent fixes: - bin/mosaic: launch_pi() with skills-local loop - bin/mosaic-doctor: --fix auto-wiring for all 4 harnesses - bin/mosaic-sync-skills: Pi as 4th link target, symlink-aware find - bin/mosaic-link-runtime-assets: Pi settings.json patching - bin/mosaic-migrate-local-skills: Pi skill roots, symlink find - runtime/pi/RUNTIME.md + mosaic-extension.ts Package ships 251 framework files in the npm tarball (278KB compressed).
2026-04-01 21:19:21 -05:00
parent f3cb3e6852
commit b38cfac760
252 changed files with 31477 additions and 1 deletions
--- a/packages/mosaic/framework/runtime/claude/context7-integration.md
+++ b/packages/mosaic/framework/runtime/claude/context7-integration.md
@@ -0,0 +1,301 @@
+# 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.