DocShop v3 Development Assistant
Expert guidance for developing DocShop v3, a sophisticated macOS Swift application providing intelligent documentation management with AI-powered analysis and multi-agent orchestration.
What This Skill Does
This skill helps you navigate and contribute to the DocShop v3 codebase, which features:
Multi-agent AI orchestration for document processingIntelligent document ingestion and analysis pipelineGraph database integration for relationship trackingEmbedded HTTP API servermacOS-native Swift/SwiftUI interfaceSiri Shortcuts and Share Sheet integrationProject Architecture
Core Components
**Multi-Agent System:**
`AgentOrchestrator.swift` - Central coordination engine for all agents and projects`DevelopmentAgent.swift` - Base agent implementation for task execution`TaskDistributor.swift` - Intelligent task assignment based on agent capabilities`ContextManager.swift` - Maintains project context and agent alignment`ProgressTracker.swift` - Monitors progress and benchmarks**Document Processing Pipeline:**
1. `DocumentImporter.swift` - Initial ingestion and validation
2. `SmartDocumentProcessor.swift` - **CURRENTLY DISABLED** (generates garbage output)
3. `DocumentProcessor.swift` - Core processing logic
4. `DocumentChunker.swift` - Breaks documents into chunks
5. `AIDocumentAnalyzer.swift` - AI-powered analysis and categorization
6. `DocumentSearchIndex.swift` - Maintains searchable index
**Data Models** (in `DocShop/Models/`):
`Project.swift` - Central project entity with relationships`DocumentMetaData.swift` - Enhanced metadata with categorization`IngestedDocument.swift` - Processed document representation`AgentTypes.swift` - Agent specializations and capabilities`AgentContextTypes.swift` - Context management types**API System:**
`APIServer.swift` - HTTP server setup and routing (Hummingbird framework)`DocumentAPI.swift` - Document endpoints`FilesystemAPI.swift` - File operations`ShellAPI.swift` - Shell command execution**Storage:**
`ProjectStorage.swift` - Project persistence`DocumentStorage.swift` - Document storage`Neo4jManager.swift` - Graph database integrationDevelopment Workflow
Step 1: Understand the Build System
This is an Xcode project using Swift Package Manager:
```bash
Build the project
xcodebuild -project DocShop.xcodeproj -scheme DocShop -configuration Debug build
Run tests
xcodebuild test -project DocShop.xcodeproj -scheme DocShop -destination 'platform=macOS'
Clean build
xcodebuild -project DocShop.xcodeproj -scheme DocShop clean
```
**Dependencies:**
SwiftSoup (HTML parsing)Hummingbird (HTTP server)VisualEffects (UI effects)FoundationModels (AI/ML)Step 2: Follow Key Development Patterns
**Agent System Usage:**
```swift
// Always use AgentOrchestrator as the central coordinator
let orchestrator = AgentOrchestrator.shared
let project = await orchestrator.createProject(from: documents, requirements: requirements)
await orchestrator.assignAgentsToProject(project)
```
**Document Processing:**
```swift
// NOTE: SmartDocumentProcessor is disabled
let chunks = DocumentChunker.shared.chunkDocument(document)
let analysis = await AIDocumentAnalyzer.shared.analyzeDocument(document)
```
**Context Management:**
```swift
let context = await contextManager.buildProjectContext(for: project)
await agent.updateContext(context)
```
Step 3: Testing Strategy
Tests are organized by domain in `DocShop/Models/Tests/`:
`AgentContextTypesTests.swift` - Agent context validation`DocumentModelTests.swift` - Document model behavior`ProjectRelationshipTests.swift` - Project relationship integrityStep 4: Important Constraints
**Critical Warnings:**
**DO NOT re-enable `SmartDocumentProcessor`** - It generates garbage output and requires significant debugging firstThe system uses `@MainActor` extensively - ensure all UI updates happen on the main actorNeo4j integration requires local database setupRequires macOS-specific entitlements (see `DocShop.entitlements`)**Architecture Guidelines:**
Use `AgentOrchestrator` as the single coordination point for all agent operationsRoute all document processing through the established pipeline stagesManage agent context exclusively through `ContextManager`Follow the existing async/await patterns throughoutStep 5: Extensions & Integrations
The project includes:
**DocShopIntent** - Siri Shortcuts for document import**DocShopShareExtension** - System share sheet integration**Multi-agent workspace** in `DocShop-v3-testing/` with individual agent environmentsCommon Development Tasks
**Adding a New Agent Type:**
1. Define capabilities in `AgentTypes.swift`
2. Create agent implementation extending `DevelopmentAgent.swift`
3. Register with `TaskDistributor.swift`
4. Update `AgentOrchestrator` coordination logic
**Extending Document Processing:**
1. Add processing step to the pipeline
2. Update `DocumentMetaData.swift` if new metadata is needed
3. Integrate with `DocumentSearchIndex.swift` for searchability
4. Add corresponding tests in `DocumentModelTests.swift`
**API Endpoint Development:**
1. Define route in `APIServer.swift`
2. Implement handler in appropriate API file (`DocumentAPI.swift`, etc.)
3. Use Hummingbird request/response patterns
4. Document endpoint behavior
**Multi-Agent Development:**
Refer to agent workspace READMEs in `DocShop-v3-testing/agent-workspaces/`Consult agent implementation docs in `Documentation/03-Multi-Agent-System/`Check individual agent Swift files in respective workspace directoriesAdditional Resources
Comprehensive documentation in `Documentation/` directoryAnalysis reports and implementation guides in `Documentation/`Individual agent environments in `DocShop-v3-testing/`Best Practices
Always coordinate through `AgentOrchestrator` for agent operationsUse the existing async/await concurrency model consistentlyMaintain clear separation between processing pipeline stagesWrite tests for new models and relationshipsKeep UI updates on `@MainActor`Document new agent capabilities and API endpoints