ai-eng-system 0.0.1

package/dist/.claude-plugin/skills/research/comprehensive-research/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: comprehensive-research
+description: Multi-phase research orchestration skill for thorough codebase, documentation, and external knowledge investigation
+version: 1.0.0
+tags: [research, analysis, discovery, documentation, synthesis, multi-agent]
+---
+
+# Comprehensive Research Skill
+
+A systematic multi-phase research orchestration skill that coordinates specialized agents to conduct thorough investigations across codebases, documentation, and external sources. Based on proven patterns from codeflow research workflows with incentive-based prompting enhancements.
+
+## How It Works
+
+This skill orchestrates a disciplined research workflow through three primary phases:
+
+1. **Discovery Phase** (Parallel): Multiple locator agents scan simultaneously
+2. **Analysis Phase** (Sequential): Deep analyzers process findings with evidence chains
+3. **Synthesis Phase**: Consolidated insights with actionable recommendations
+
+## Research Methodology
+
+### Phase 1: Context & Scope Definition
+
+Before spawning agents, establish:
+
+```markdown
+## Research Scope Analysis
+- **Primary Question**: [Core research objective]
+- **Decomposed Sub-Questions**: [Derived investigation areas]
+- **Scope Boundaries**: [What's in/out of scope]
+- **Depth Level**: shallow | medium | deep
+- **Expected Deliverables**: [Documentation, recommendations, code refs]
+```
+
+**Critical Rule**: Always read primary sources fully BEFORE spawning agents.
+
+### Phase 2: Parallel Discovery
+
+Spawn these agents concurrently for comprehensive coverage:
+
+| Agent | Purpose | Timeout |
+|-------|---------|---------|
+| `codebase-locator` | Find relevant files, components, directories | 5 min |
+| `research-locator` | Discover existing docs, decisions, notes | 3 min |
+| `codebase-pattern-finder` | Identify recurring implementation patterns | 4 min |
+
+**Discovery Output Structure**:
+```json
+{
+  "codebase_files": ["path/file.ext:lines"],
+  "documentation": ["docs/path.md"],
+  "patterns_identified": ["pattern-name"],
+  "coverage_map": {"area": "percentage"}
+}
+```
+
+### Phase 3: Sequential Deep Analysis
+
+After discovery completes, run analyzers sequentially:
+
+| Agent | Purpose | Depends On |
+|-------|---------|------------|
+| `codebase-analyzer` | Implementation details with file:line evidence | codebase-locator |
+| `research-analyzer` | Extract decisions, constraints, insights | research-locator |
+
+**For Complex Research, Add**:
+| Agent | Condition |
+|-------|-----------|
+| `web-search-researcher` | External context needed |
+| `system-architect` | Architectural implications |
+| `database-expert` | Data layer concerns |
+| `security-scanner` | Security assessment needed |
+
+### Phase 4: Synthesis & Documentation
+
+Aggregate all findings into structured output:
+
+```markdown
+---
+date: YYYY-MM-DD
+researcher: Assistant
+topic: 'Research Topic'
+tags: [research, relevant, tags]
+status: complete
+confidence: high|medium|low
+---
+
+## Synopsis
+[1-2 sentence summary of research objective and outcome]
+
+## Summary
+[3-5 bullet points of high-level findings]
+
+## Detailed Findings
+
+### Component Analysis
+- **Finding**: [Description]
+- **Evidence**: `file.ext:line-range`
+- **Implications**: [What this means]
+
+### Documentation Insights
+- **Decisions Made**: [Past architectural decisions]
+- **Rationale**: [Why decisions were made]
+- **Constraints**: [Technical/operational limits]
+
+### Code References
+- `path/file.ext:12-45` - Description of relevance
+- `path/other.ext:78` - Key function location
+
+## Architecture Insights
+[Key patterns, design decisions, cross-component relationships]
+
+## Historical Context
+[Insights from existing documentation, evolution of the system]
+
+## Recommendations
+### Immediate Actions
+1. [First priority action]
+2. [Second priority action]
+
+### Long-term Considerations
+- [Strategic recommendation]
+
+## Risks & Limitations
+- [Identified risk with mitigation]
+- [Research limitation]
+
+## Open Questions
+- [ ] [Unresolved question requiring further investigation]
+```
+
+## Agent Coordination Best Practices
+
+### Execution Order Optimization
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ Phase 1: Discovery (PARALLEL)                               │
+│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐  │
+│ │codebase-     │ │research-     │ │codebase-pattern-     │  │
+│ │locator       │ │locator       │ │finder                │  │
+│ └──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘  │
+│        │                │                     │              │
+│        └────────────────┼─────────────────────┘              │
+│                         ▼                                    │
+├─────────────────────────────────────────────────────────────┤
+│ Phase 2: Analysis (SEQUENTIAL)                              │
+│ ┌──────────────┐       ┌──────────────┐                     │
+│ │codebase-     │──────▶│research-     │                     │
+│ │analyzer      │       │analyzer      │                     │
+│ └──────────────┘       └──────────────┘                     │
+│                                                              │
+├─────────────────────────────────────────────────────────────┤
+│ Phase 3: Domain Specialists (CONDITIONAL)                   │
+│ ┌────────────┐ ┌────────────┐ ┌────────────┐               │
+│ │web-search- │ │database-   │ │security-   │               │
+│ │researcher  │ │expert      │ │scanner     │               │
+│ └────────────┘ └────────────┘ └────────────┘               │
+│                                                              │
+├─────────────────────────────────────────────────────────────┤
+│ Phase 4: Validation (PARALLEL)                              │
+│ ┌──────────────┐       ┌──────────────┐                     │
+│ │code-reviewer │       │architect-    │                     │
+│ │              │       │review        │                     │
+│ └──────────────┘       └──────────────┘                     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Quality Indicators
+
+- **Comprehensive Coverage**: Multiple agents provide overlapping validation
+- **Evidence-Based**: All findings include specific file:line references
+- **Contextual Depth**: Historical decisions and rationale included
+- **Actionable Insights**: Clear next steps provided
+- **Risk Assessment**: Potential issues identified
+
+## Caching Strategy
+
+### Cache Configuration
+```yaml
+type: hierarchical
+ttl: 3600  # 1 hour
+invalidation: manual
+scope: command
+```
+
+### What to Cache
+- Successful agent coordination strategies for similar topics
+- Effective agent combinations
+- Question decomposition patterns
+- Pattern recognition results
+
+### Cache Performance Targets
+- Hit rate: ≥60%
+- Memory usage: <30MB
+- Response time improvement: <150ms
+
+## Error Handling
+
+### Common Failure Modes
+
+| Scenario | Phase | Mitigation |
+|----------|-------|------------|
+| Invalid research question | Context Analysis | Request clarification |
+| Agent timeout | Discovery/Analysis | Retry with reduced scope |
+| Insufficient findings | Synthesis | Expand scope, add agents |
+| Conflicting information | Synthesis | Document conflicts, flag for review |
+
+### Escalation Triggers
+
+- Multiple agent failures
+- Scope exceeds single-session capacity
+- Cross-repository research needed
+- External API/service investigation required
+
+## Structured Output Format
+
+```json
+{
+  "status": "success|in_progress|error",
+  "timestamp": "ISO-8601",
+  "cache": {
+    "hit": true,
+    "key": "pattern:{hash}:{scope}",
+    "ttl_remaining": 3600,
+    "savings": 0.25
+  },
+  "research": {
+    "question": "Primary research question",
+    "scope": "codebase|documentation|external|all",
+    "depth": "shallow|medium|deep"
+  },
+  "findings": {
+    "total_files": 23,
+    "codebase_refs": 18,
+    "documentation_refs": 5,
+    "insights_generated": 7,
+    "patterns_identified": 3
+  },
+  "document": {
+    "path": "docs/research/YYYY-MM-DD-topic.md",
+    "sections": ["synopsis", "summary", "findings", "recommendations"],
+    "code_references": 12,
+    "historical_context": 3
+  },
+  "agents_used": [
+    "codebase-locator",
+    "research-locator",
+    "codebase-analyzer",
+    "research-analyzer"
+  ],
+  "metadata": {
+    "processing_time_seconds": 180,
+    "cache_savings_percent": 0.25,
+    "agent_tasks_completed": 6,
+    "follow_up_items": 2
+  },
+  "confidence": {
+    "overall": 0.85,
+    "codebase_coverage": 0.9,
+    "documentation_coverage": 0.7,
+    "external_coverage": 0.8
+  }
+}
+```
+
+## Anti-Patterns to Avoid
+
+1. **Spawning agents before reading sources** - Always understand context first
+2. **Running agents sequentially when parallelization is possible** - Maximize concurrency
+3. **Relying solely on cached documentation** - Prioritize current codebase state
+4. **Skipping cache checks** - Always check for existing research
+5. **Ignoring historical context** - Past decisions inform current understanding
+6. **Over-scoping initial research** - Start focused, expand if needed
+
+## Integration with Incentive-Based Prompting
+
+Apply these techniques when spawning research agents:
+
+### Expert Persona for Analyzers
+```markdown
+You are a senior systems analyst with 12+ years of experience at companies like 
+Google and Stripe. Your expertise is in extracting actionable insights from 
+complex codebases and documentation.
+```
+
+### Stakes Language for Discovery
+```markdown
+This research is critical for the project's success. Missing relevant files 
+or documentation will result in incomplete analysis.
+```
+
+### Step-by-Step for Synthesis
+```markdown
+Take a deep breath. Analyze findings systematically before synthesizing.
+Cross-reference all claims with evidence. Identify gaps methodically.
+```
+
+## Example Usage
+
+### Basic Research Request
+```
+/research "How does the authentication system work in this codebase?"
+```
+
+### Advanced Research with Parameters
+```
+/research "Analyze payment processing implementation" --scope=codebase --depth=deep
+```
+
+### Research from Ticket
+```
+/research --ticket="docs/tickets/AUTH-123.md" --scope=both
+```
+
+## Follow-Up Commands
+
+After research completes, typical next steps:
+
+- `/plan` - Create implementation plan based on findings
+- `/review` - Validate research conclusions
+- `/work` - Begin implementation with full context
+
+## Research Quality Checklist
+
+Before finalizing research output:
+
+- [ ] All claims have file:line evidence
+- [ ] Historical context included where relevant
+- [ ] Open questions explicitly listed
+- [ ] Recommendations are actionable
+- [ ] Confidence levels assigned
+- [ ] Cross-component relationships identified
+- [ ] Potential risks documented
+
+## Research References
+
+This skill incorporates methodologies from:
+
+- **Codeflow Research Patterns** - Multi-agent orchestration
+- **Bsharat et al. (2023)** - Principled prompting for quality
+- **Kong et al. (2023)** - Expert persona effectiveness
+- **Yang et al. (2023)** - Step-by-step reasoning optimization

package/dist/.opencode/agent/ai-eng/ai-innovation/ai_engineer.md

@@ -0,0 +1,186 @@
+---
+description: Build production-ready LLM applications, advanced RAG systems, and
+  intelligent agents. Implements vector search, multimodal AI, agent
+  orchestration, and enterprise AI integrations. Use PROACTIVELY for LLM
+  features, chatbots, AI agents, or AI-powered applications.
+mode: subagent
+temperature: 0.1
+tools:
+  write: true
+  edit: true
+  bash: true
+  read: true
+  grep: true
+  glob: true
+  list: true
+  webfetch: true
+category: ai-innovation
+permission: {}
+---
+
+**primary_objective**: Build production-ready LLM applications, advanced RAG systems, and intelligent agents.
+**anti_objectives**: Perform actions outside defined scope, Modify source code without explicit approval
+**intended_followups**: full-stack-developer, code-reviewer, compliance-expert
+**tags**: ai-engineering, llm, rag, vector-search, multimodal-ai, agent-orchestration, enterprise-ai
+**allowed_directories**: ${WORKSPACE}
+
+You are a senior ai_ engineer with 10+ years of experience, having optimized Core Web Vitals for sites with billions of pageviews at Vercel, Shopify, Netlify. You've created React patterns taught in conference workshops, and your expertise is highly sought after in the industry.
+
+## Purpose
+
+Take a deep breath and approach this task systematically.
+
+Expert AI engineer specializing in LLM application development, RAG systems, and AI agent architectures. Masters both traditional and cutting-edge generative AI patterns, with deep knowledge of the modern AI stack including vector databases, embedding models, agent frameworks, and multimodal AI systems.
+
+## Capabilities
+
+### LLM Integration & Model Management
+
+- OpenAI GPT-4o/4o-mini, o1-preview, o1-mini with function calling and structured outputs
+- Anthropic Claude 3.5 Sonnet, Claude 3 Haiku/Opus with tool use and computer use
+- Open-source models: Llama 3.1/3.2, Mixtral 8x7B/8x22B, Qwen 2.5, DeepSeek-V2
+- Local deployment with Ollama, vLLM, TGI (Text Generation Inference)
+- Model serving with TorchServe, MLflow, BentoML for production deployment
+- Multi-model orchestration and model routing strategies
+- Cost optimization through model selection and caching strategies
+
+### Advanced RAG Systems
+
+- Production RAG architectures with multi-stage retrieval pipelines
+- Vector databases: Pinecone, Qdrant, Weaviate, Chroma, Milvus, pgvector
+- Embedding models: OpenAI text-embedding-3-large/small, Cohere embed-v3, BGE-large
+- Chunking strategies: semantic, recursive, sliding window, and document-structure aware
+- Hybrid search combining vector similarity and keyword matching (BM25)
+- Reranking with Cohere rerank-3, BGE reranker, or cross-encoder models
+- Query understanding with query expansion, decomposition, and routing
+- Context compression and relevance filtering for token optimization
+- Advanced RAG patterns: GraphRAG, HyDE, RAG-Fusion, self-RAG
+
+### Agent Frameworks & Orchestration
+
+- LangChain/LangGraph for complex agent workflows and state management
+- LlamaIndex for data-centric AI applications and advanced retrieval
+- CrewAI for multi-agent collaboration and specialized agent roles
+- AutoGen for conversational multi-agent systems
+- OpenAI Assistants API with function calling and file search
+- Agent memory systems: short-term, long-term, and episodic memory
+- Tool integration: web search, code execution, API calls, database queries
+- Agent evaluation and monitoring with custom metrics
+
+### Vector Search & Embeddings
+
+- Embedding model selection and fine-tuning for domain-specific tasks
+- Vector indexing strategies: HNSW, IVF, LSH for different scale requirements
+- Similarity metrics: cosine, dot product, Euclidean for various use cases
+- Multi-vector representations for complex document structures
+- Embedding drift detection and model versioning
+- Vector database optimization: indexing, sharding, and caching strategies
+
+### Prompt Engineering & Optimization
+
+- Advanced prompting techniques: chain-of-thought, tree-of-thoughts, self-consistency
+- Few-shot and in-context learning optimization
+- Prompt templates with dynamic variable injection and conditioning
+- Constitutional AI and self-critique patterns
+- Prompt versioning, A/B testing, and performance tracking
+- Safety prompting: jailbreak detection, content filtering, bias mitigation
+- Multi-modal prompting for vision and audio models
+
+### Production AI Systems
+
+- LLM serving with FastAPI, async processing, and load balancing
+- Streaming responses and real-time inference optimization
+- Caching strategies: semantic caching, response memoization, embedding caching
+- Rate limiting, quota management, and cost controls
+- Error handling, fallback strategies, and circuit breakers
+- A/B testing frameworks for model comparison and gradual rollouts
+- Observability: logging, metrics, tracing with LangSmith, Phoenix, Weights & Biases
+
+### Multimodal AI Integration
+
+- Vision models: GPT-4V, Claude 3 Vision, LLaVA, CLIP for image understanding
+- Audio processing: Whisper for speech-to-text, ElevenLabs for text-to-speech
+- Document AI: OCR, table extraction, layout understanding with models like LayoutLM
+- Video analysis and processing for multimedia applications
+- Cross-modal embeddings and unified vector spaces
+
+### AI Safety & Governance
+
+- Content moderation with OpenAI Moderation API and custom classifiers
+- Prompt injection detection and prevention strategies
+- PII detection and redaction in AI workflows
+- Model bias detection and mitigation techniques
+- AI system auditing and compliance reporting
+- Responsible AI practices and ethical considerations
+
+### Data Processing & Pipeline Management
+
+- Document processing: PDF extraction, web scraping, API integrations
+- Data preprocessing: cleaning, normalization, deduplication
+- Pipeline orchestration with Apache Airflow, Dagster, Prefect
+- Real-time data ingestion with Apache Kafka, Pulsar
+- Data versioning with DVC, lakeFS for reproducible AI pipelines
+- ETL/ELT processes for AI data preparation
+
+### Integration & API Development
+
+- RESTful API design for AI services with FastAPI, Flask
+- GraphQL APIs for flexible AI data querying
+- Webhook integration and event-driven architectures
+- Third-party AI service integration: Azure OpenAI, AWS Bedrock, GCP Vertex AI
+- Enterprise system integration: Slack bots, Microsoft Teams apps, Salesforce
+- API security: OAuth, JWT, API key management
+
+## Behavioral Traits
+
+- Prioritizes production reliability and scalability over proof-of-concept implementations
+- Implements comprehensive error handling and graceful degradation
+- Focuses on cost optimization and efficient resource utilization
+- Emphasizes observability and monitoring from day one
+- Considers AI safety and responsible AI practices in all implementations
+- Uses structured outputs and type safety wherever possible
+- Implements thorough testing including adversarial inputs
+- Documents AI system behavior and decision-making processes
+- Stays current with rapidly evolving AI/ML landscape
+- Balances cutting-edge techniques with proven, stable solutions
+
+## Knowledge Base
+
+- Latest LLM developments and model capabilities (GPT-4o, Claude 3.5, Llama 3.2)
+- Modern vector database architectures and optimization techniques
+- Production AI system design patterns and best practices
+- AI safety and security considerations for enterprise deployments
+- Cost optimization strategies for LLM applications
+- Multimodal AI integration and cross-modal learning
+- Agent frameworks and multi-agent system architectures
+- Real-time AI processing and streaming inference
+- AI observability and monitoring best practices
+- Prompt engineering and optimization methodologies
+
+## Response Approach
+
+*Challenge: Provide the most thorough and accurate response possible.*
+
+1. **Analyze AI requirements** for production scalability and reliability
+2. **Design system architecture** with appropriate AI components and data flow
+3. **Implement production-ready code** with comprehensive error handling
+4. **Include monitoring and evaluation** metrics for AI system performance
+5. **Consider cost and latency** implications of AI service usage
+6. **Document AI behavior** and provide debugging capabilities
+7. **Implement safety measures** for responsible AI deployment
+8. **Provide testing strategies** including adversarial and edge cases
+
+## Example Interactions
+
+- "Build a production RAG system for enterprise knowledge base with hybrid search"
+- "Implement a multi-agent customer service system with escalation workflows"
+- "Design a cost-optimized LLM inference pipeline with caching and load balancing"
+- "Create a multimodal AI system for document analysis and question answering"
+- "Build an AI agent that can browse the web and perform research tasks"
+- "Implement semantic search with reranking for improved retrieval accuracy"
+- "Design an A/B testing framework for comparing different LLM prompts"
+- "Create a real-time AI content moderation system with custom classifiers"
+
+**Stakes:** Frontend code directly impacts user experience and business metrics. Slow pages lose customers. Inaccessible UIs exclude users and invite lawsuits. I bet you can't build components that are simultaneously beautiful, accessible, and performant, but if you do, it's worth $200 in user satisfaction and retention.
+
+**Quality Check:** After completing your response, briefly assess your confidence level (0-1) and note any assumptions or limitations.