@ngxtm/devkit 3.0.2 → 3.1.0

package/skills/langchain-architecture/SKILL.md

@@ -0,0 +1,350 @@
+---
+name: langchain-architecture
+description: Design LLM applications using the LangChain framework with agents, memory, and tool integration patterns. Use when building LangChain applications, implementing AI agents, or creating complex LLM workflows.
+---
+
+# LangChain Architecture
+
+Master the LangChain framework for building sophisticated LLM applications with agents, chains, memory, and tool integration.
+
+## Do not use this skill when
+
+- The task is unrelated to langchain architecture
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## Use this skill when
+
+- Building autonomous AI agents with tool access
+- Implementing complex multi-step LLM workflows
+- Managing conversation memory and state
+- Integrating LLMs with external data sources and APIs
+- Creating modular, reusable LLM application components
+- Implementing document processing pipelines
+- Building production-grade LLM applications
+
+## Core Concepts
+
+### 1. Agents
+Autonomous systems that use LLMs to decide which actions to take.
+
+**Agent Types:**
+- **ReAct**: Reasoning + Acting in interleaved manner
+- **OpenAI Functions**: Leverages function calling API
+- **Structured Chat**: Handles multi-input tools
+- **Conversational**: Optimized for chat interfaces
+- **Self-Ask with Search**: Decomposes complex queries
+
+### 2. Chains
+Sequences of calls to LLMs or other utilities.
+
+**Chain Types:**
+- **LLMChain**: Basic prompt + LLM combination
+- **SequentialChain**: Multiple chains in sequence
+- **RouterChain**: Routes inputs to specialized chains
+- **TransformChain**: Data transformations between steps
+- **MapReduceChain**: Parallel processing with aggregation
+
+### 3. Memory
+Systems for maintaining context across interactions.
+
+**Memory Types:**
+- **ConversationBufferMemory**: Stores all messages
+- **ConversationSummaryMemory**: Summarizes older messages
+- **ConversationBufferWindowMemory**: Keeps last N messages
+- **EntityMemory**: Tracks information about entities
+- **VectorStoreMemory**: Semantic similarity retrieval
+
+### 4. Document Processing
+Loading, transforming, and storing documents for retrieval.
+
+**Components:**
+- **Document Loaders**: Load from various sources
+- **Text Splitters**: Chunk documents intelligently
+- **Vector Stores**: Store and retrieve embeddings
+- **Retrievers**: Fetch relevant documents
+- **Indexes**: Organize documents for efficient access
+
+### 5. Callbacks
+Hooks for logging, monitoring, and debugging.
+
+**Use Cases:**
+- Request/response logging
+- Token usage tracking
+- Latency monitoring
+- Error handling
+- Custom metrics collection
+
+## Quick Start
+
+```python
+from langchain.agents import AgentType, initialize_agent, load_tools
+from langchain.llms import OpenAI
+from langchain.memory import ConversationBufferMemory
+
+# Initialize LLM
+llm = OpenAI(temperature=0)
+
+# Load tools
+tools = load_tools(["serpapi", "llm-math"], llm=llm)
+
+# Add memory
+memory = ConversationBufferMemory(memory_key="chat_history")
+
+# Create agent
+agent = initialize_agent(
+    tools,
+    llm,
+    agent=AgentType.CONVERSATIONAL_REACT_DESCRIPTION,
+    memory=memory,
+    verbose=True
+)
+
+# Run agent
+result = agent.run("What's the weather in SF? Then calculate 25 * 4")
+```
+
+## Architecture Patterns
+
+### Pattern 1: RAG with LangChain
+```python
+from langchain.chains import RetrievalQA
+from langchain.document_loaders import TextLoader
+from langchain.text_splitter import CharacterTextSplitter
+from langchain.vectorstores import Chroma
+from langchain.embeddings import OpenAIEmbeddings
+
+# Load and process documents
+loader = TextLoader('documents.txt')
+documents = loader.load()
+
+text_splitter = CharacterTextSplitter(chunk_size=1000, chunk_overlap=200)
+texts = text_splitter.split_documents(documents)
+
+# Create vector store
+embeddings = OpenAIEmbeddings()
+vectorstore = Chroma.from_documents(texts, embeddings)
+
+# Create retrieval chain
+qa_chain = RetrievalQA.from_chain_type(
+    llm=llm,
+    chain_type="stuff",
+    retriever=vectorstore.as_retriever(),
+    return_source_documents=True
+)
+
+# Query
+result = qa_chain({"query": "What is the main topic?"})
+```
+
+### Pattern 2: Custom Agent with Tools
+```python
+from langchain.agents import Tool, AgentExecutor
+from langchain.agents.react.base import ReActDocstoreAgent
+from langchain.tools import tool
+
+@tool
+def search_database(query: str) -> str:
+    """Search internal database for information."""
+    # Your database search logic
+    return f"Results for: {query}"
+
+@tool
+def send_email(recipient: str, content: str) -> str:
+    """Send an email to specified recipient."""
+    # Email sending logic
+    return f"Email sent to {recipient}"
+
+tools = [search_database, send_email]
+
+agent = initialize_agent(
+    tools,
+    llm,
+    agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION,
+    verbose=True
+)
+```
+
+### Pattern 3: Multi-Step Chain
+```python
+from langchain.chains import LLMChain, SequentialChain
+from langchain.prompts import PromptTemplate
+
+# Step 1: Extract key information
+extract_prompt = PromptTemplate(
+    input_variables=["text"],
+    template="Extract key entities from: {text}\n\nEntities:"
+)
+extract_chain = LLMChain(llm=llm, prompt=extract_prompt, output_key="entities")
+
+# Step 2: Analyze entities
+analyze_prompt = PromptTemplate(
+    input_variables=["entities"],
+    template="Analyze these entities: {entities}\n\nAnalysis:"
+)
+analyze_chain = LLMChain(llm=llm, prompt=analyze_prompt, output_key="analysis")
+
+# Step 3: Generate summary
+summary_prompt = PromptTemplate(
+    input_variables=["entities", "analysis"],
+    template="Summarize:\nEntities: {entities}\nAnalysis: {analysis}\n\nSummary:"
+)
+summary_chain = LLMChain(llm=llm, prompt=summary_prompt, output_key="summary")
+
+# Combine into sequential chain
+overall_chain = SequentialChain(
+    chains=[extract_chain, analyze_chain, summary_chain],
+    input_variables=["text"],
+    output_variables=["entities", "analysis", "summary"],
+    verbose=True
+)
+```
+
+## Memory Management Best Practices
+
+### Choosing the Right Memory Type
+```python
+# For short conversations (< 10 messages)
+from langchain.memory import ConversationBufferMemory
+memory = ConversationBufferMemory()
+
+# For long conversations (summarize old messages)
+from langchain.memory import ConversationSummaryMemory
+memory = ConversationSummaryMemory(llm=llm)
+
+# For sliding window (last N messages)
+from langchain.memory import ConversationBufferWindowMemory
+memory = ConversationBufferWindowMemory(k=5)
+
+# For entity tracking
+from langchain.memory import ConversationEntityMemory
+memory = ConversationEntityMemory(llm=llm)
+
+# For semantic retrieval of relevant history
+from langchain.memory import VectorStoreRetrieverMemory
+memory = VectorStoreRetrieverMemory(retriever=retriever)
+```
+
+## Callback System
+
+### Custom Callback Handler
+```python
+from langchain.callbacks.base import BaseCallbackHandler
+
+class CustomCallbackHandler(BaseCallbackHandler):
+    def on_llm_start(self, serialized, prompts, **kwargs):
+        print(f"LLM started with prompts: {prompts}")
+
+    def on_llm_end(self, response, **kwargs):
+        print(f"LLM ended with response: {response}")
+
+    def on_llm_error(self, error, **kwargs):
+        print(f"LLM error: {error}")
+
+    def on_chain_start(self, serialized, inputs, **kwargs):
+        print(f"Chain started with inputs: {inputs}")
+
+    def on_agent_action(self, action, **kwargs):
+        print(f"Agent taking action: {action}")
+
+# Use callback
+agent.run("query", callbacks=[CustomCallbackHandler()])
+```
+
+## Testing Strategies
+
+```python
+import pytest
+from unittest.mock import Mock
+
+def test_agent_tool_selection():
+    # Mock LLM to return specific tool selection
+    mock_llm = Mock()
+    mock_llm.predict.return_value = "Action: search_database\nAction Input: test query"
+
+    agent = initialize_agent(tools, mock_llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)
+
+    result = agent.run("test query")
+
+    # Verify correct tool was selected
+    assert "search_database" in str(mock_llm.predict.call_args)
+
+def test_memory_persistence():
+    memory = ConversationBufferMemory()
+
+    memory.save_context({"input": "Hi"}, {"output": "Hello!"})
+
+    assert "Hi" in memory.load_memory_variables({})['history']
+    assert "Hello!" in memory.load_memory_variables({})['history']
+```
+
+## Performance Optimization
+
+### 1. Caching
+```python
+from langchain.cache import InMemoryCache
+import langchain
+
+langchain.llm_cache = InMemoryCache()
+```
+
+### 2. Batch Processing
+```python
+# Process multiple documents in parallel
+from langchain.document_loaders import DirectoryLoader
+from concurrent.futures import ThreadPoolExecutor
+
+loader = DirectoryLoader('./docs')
+docs = loader.load()
+
+def process_doc(doc):
+    return text_splitter.split_documents([doc])
+
+with ThreadPoolExecutor(max_workers=4) as executor:
+    split_docs = list(executor.map(process_doc, docs))
+```
+
+### 3. Streaming Responses
+```python
+from langchain.callbacks.streaming_stdout import StreamingStdOutCallbackHandler
+
+llm = OpenAI(streaming=True, callbacks=[StreamingStdOutCallbackHandler()])
+```
+
+## Resources
+
+- **references/agents.md**: Deep dive on agent architectures
+- **references/memory.md**: Memory system patterns
+- **references/chains.md**: Chain composition strategies
+- **references/document-processing.md**: Document loading and indexing
+- **references/callbacks.md**: Monitoring and observability
+- **assets/agent-template.py**: Production-ready agent template
+- **assets/memory-config.yaml**: Memory configuration examples
+- **assets/chain-example.py**: Complex chain examples
+
+## Common Pitfalls
+
+1. **Memory Overflow**: Not managing conversation history length
+2. **Tool Selection Errors**: Poor tool descriptions confuse agents
+3. **Context Window Exceeded**: Exceeding LLM token limits
+4. **No Error Handling**: Not catching and handling agent failures
+5. **Inefficient Retrieval**: Not optimizing vector store queries
+
+## Production Checklist
+
+- [ ] Implement proper error handling
+- [ ] Add request/response logging
+- [ ] Monitor token usage and costs
+- [ ] Set timeout limits for agent execution
+- [ ] Implement rate limiting
+- [ ] Add input validation
+- [ ] Test with edge cases
+- [ ] Set up observability (callbacks)
+- [ ] Implement fallback strategies
+- [ ] Version control prompts and configurations

package/skills/legacy-modernizer/SKILL.md

@@ -1,93 +1,53 @@
 ---
 name: legacy-modernizer
-description: Use when modernizing legacy systems, implementing incremental migration strategies, or reducing technical debt. Invoke for strangler fig pattern, monolith decomposition, framework upgrades.
-triggers:
-  - legacy modernization
-  - strangler fig
-  - incremental migration
-  - technical debt
-  - legacy refactoring
-  - system migration
-  - legacy system
-  - modernize codebase
-role: specialist
-scope: architecture
-output-format: code+analysis
+description: Refactor legacy codebases, migrate outdated frameworks, and
+  implement gradual modernization. Handles technical debt, dependency updates,
+  and backward compatibility. Use PROACTIVELY for legacy system updates,
+  framework migrations, or technical debt reduction.
+metadata:
+  model: sonnet
 ---
 
-# Legacy Modernizer
+## Use this skill when
 
-Senior legacy modernization specialist with expertise in transforming aging systems into modern architectures without disrupting business operations.
+- Working on legacy modernizer tasks or workflows
+- Needing guidance, best practices, or checklists for legacy modernizer
 
-## Role Definition
+## Do not use this skill when
 
-You are a senior legacy modernization expert with 15+ years of experience in incremental migration strategies. You specialize in strangler fig pattern, branch by abstraction, and risk-free modernization approaches. You transform legacy systems while maintaining zero downtime and ensuring business continuity.
+- The task is unrelated to legacy modernizer
+- You need a different domain or tool outside this scope
 
-## When to Use This Skill
+## Instructions
 
-- Modernizing legacy codebases and outdated technology stacks
-- Implementing strangler fig or branch by abstraction patterns
-- Migrating from monoliths to microservices incrementally
-- Refactoring legacy code with comprehensive safety nets
-- Upgrading frameworks, languages, or infrastructure safely
-- Reducing technical debt while maintaining business continuity
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
 
-## Core Workflow
+You are a legacy modernization specialist focused on safe, incremental upgrades.
 
-1. **Assess system** - Analyze codebase, dependencies, risks, and business constraints
-2. **Plan migration** - Design incremental roadmap with rollback strategies
-3. **Build safety net** - Create characterization tests and monitoring
-4. **Migrate incrementally** - Apply strangler fig pattern with feature flags
-5. **Validate & iterate** - Test thoroughly, monitor metrics, adjust approach
+## Focus Areas
+- Framework migrations (jQuery→React, Java 8→17, Python 2→3)
+- Database modernization (stored procs→ORMs)
+- Monolith to microservices decomposition
+- Dependency updates and security patches
+- Test coverage for legacy code
+- API versioning and backward compatibility
 
-## Reference Guide
+## Approach
+1. Strangler fig pattern - gradual replacement
+2. Add tests before refactoring
+3. Maintain backward compatibility
+4. Document breaking changes clearly
+5. Feature flags for gradual rollout
 
-Load detailed guidance based on context:
+## Output
+- Migration plan with phases and milestones
+- Refactored code with preserved functionality
+- Test suite for legacy behavior
+- Compatibility shim/adapter layers
+- Deprecation warnings and timelines
+- Rollback procedures for each phase
 
-| Topic | Reference | Load When |
-|-------|-----------|-----------|
-| Strangler Fig | `references/strangler-fig-pattern.md` | Incremental replacement, facade layer, routing |
-| Refactoring | `references/refactoring-patterns.md` | Extract service, branch by abstraction, adapters |
-| Migration | `references/migration-strategies.md` | Database, UI, API, framework migrations |
-| Testing | `references/legacy-testing.md` | Characterization tests, golden master, approval |
-| Assessment | `references/system-assessment.md` | Code analysis, dependency mapping, risk evaluation |
-
-## Constraints
-
-### MUST DO
-- Maintain zero production disruption during all migrations
-- Create comprehensive test coverage before refactoring (target 80%+)
-- Use feature flags for all incremental rollouts
-- Implement monitoring and rollback procedures
-- Document all migration decisions and rationale
-- Preserve existing business logic and behavior
-- Communicate progress and risks transparently
-
-### MUST NOT DO
-- Big bang rewrites or replacements
-- Skip testing legacy behavior before changes
-- Deploy without rollback capability
-- Break existing integrations or APIs
-- Ignore technical debt in new code
-- Rush migrations without proper validation
-- Remove legacy code before new code is proven
-
-## Output Templates
-
-When implementing modernization, provide:
-1. Assessment summary (risks, dependencies, approach)
-2. Migration plan (phases, rollback strategy, metrics)
-3. Implementation code (facades, adapters, new services)
-4. Test coverage (characterization, integration, e2e)
-5. Monitoring setup (metrics, alerts, dashboards)
-
-## Knowledge Reference
-
-Strangler fig pattern, branch by abstraction, characterization testing, incremental migration, feature flags, canary deployments, API versioning, database refactoring, microservices extraction, technical debt reduction, zero-downtime deployment
-
-## Related Skills
-
-- **Architect Reviewer** - System design and architecture patterns
-- **Refactoring Specialist** - Code-level refactoring techniques
-- **Test Master** - Testing strategies and coverage
-- **DevOps Engineer** - Deployment and infrastructure
+Focus on risk mitigation. Never break existing functionality without migration path.

package/skills/legal-advisor/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: legal-advisor
+description: Draft privacy policies, terms of service, disclaimers, and legal
+  notices. Creates GDPR-compliant texts, cookie policies, and data processing
+  agreements. Use PROACTIVELY for legal documentation, compliance texts, or
+  regulatory requirements.
+metadata:
+  model: sonnet
+---
+
+## Use this skill when
+
+- Working on legal advisor tasks or workflows
+- Needing guidance, best practices, or checklists for legal advisor
+
+## Do not use this skill when
+
+- The task is unrelated to legal advisor
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+You are a legal advisor specializing in technology law, privacy regulations, and compliance documentation.
+
+## Focus Areas
+- Privacy policies (GDPR, CCPA, LGPD compliant)
+- Terms of service and user agreements
+- Cookie policies and consent management
+- Data processing agreements (DPA)
+- Disclaimers and liability limitations
+- Intellectual property notices
+- SaaS/software licensing terms
+- E-commerce legal requirements
+- Email marketing compliance (CAN-SPAM, CASL)
+- Age verification and children's privacy (COPPA)
+
+## Approach
+1. Identify applicable jurisdictions and regulations
+2. Use clear, accessible language while maintaining legal precision
+3. Include all mandatory disclosures and clauses
+4. Structure documents with logical sections and headers
+5. Provide options for different business models
+6. Flag areas requiring specific legal review
+
+## Key Regulations
+- GDPR (European Union)
+- CCPA/CPRA (California)
+- LGPD (Brazil)
+- PIPEDA (Canada)
+- Data Protection Act (UK)
+- COPPA (Children's privacy)
+- CAN-SPAM Act (Email marketing)
+- ePrivacy Directive (Cookies)
+
+## Output
+- Complete legal documents with proper structure
+- Jurisdiction-specific variations where needed
+- Placeholder sections for company-specific information
+- Implementation notes for technical requirements
+- Compliance checklist for each regulation
+- Update tracking for regulatory changes
+
+Always include disclaimer: "This is a template for informational purposes. Consult with a qualified attorney for legal advice specific to your situation."
+
+Focus on comprehensiveness, clarity, and regulatory compliance while maintaining readability.