@amrhas82/agentic-kit 1.2.1 → 1.7.0

package/packages/opencode/command/internal-comms.md

@@ -0,0 +1,142 @@
+---
+description: Write internal communications using company-approved formats and templates
+argument-hint: <communication-type> <details>
+---
+
+Write professional internal communications following company guidelines and preferred formats.
+
+## Communication Types
+
+**Use for:**
+- 3P updates (Progress, Plans, Problems)
+- Company newsletters
+- FAQ responses
+- Status reports
+- Leadership updates
+- Project updates
+- Incident reports
+- Team communications
+- Policy announcements
+
+## Guidelines by Type
+
+### 3P Updates (Progress, Plans, Problems)
+Format for team updates on project status:
+
+**Structure:**
+1. **Progress**: What was completed since last update
+2. **Plans**: What will be done next
+3. **Problems**: Any blockers or concerns
+
+**Tone:** Professional, concise, action-oriented
+**Length:** Brief, bullet points preferred
+**Audience:** Team members, project stakeholders
+
+### Company Newsletter
+Format for company-wide communications:
+
+**Structure:**
+1. **Header**: Clear, engaging title
+2. **Executive Summary**: Key highlights
+3. **Main Content**: Organized sections
+4. **Upcoming Events**: Forward-looking items
+5. **Closing**: Call to action or contact info
+
+**Tone:** Professional but accessible, inspiring
+**Length:** Comprehensive but scannable
+**Audience:** All employees
+
+### FAQ Responses
+Format for answering frequently asked questions:
+
+**Structure:**
+1. **Question Restatement**: Echo the ask
+2. **Direct Answer**: Clear, concise response
+3. **Additional Context**: Relevant details
+4. **Follow-up Resources**: Where to learn more
+
+**Tone:** Helpful, authoritative, patient
+**Length:** Complete but not overwhelming
+**Audience:** Individual asker, broader audience
+
+### Status Reports
+Format for project or team status updates:
+
+**Structure:**
+1. **Executive Summary**: Overall status (On Track/At Risk/Off Track)
+2. **Key Metrics**: Quantifiable progress
+3. **Recent Achievements**: Completed items
+4. **Upcoming Milestones**: Next steps
+5. **Risks/Issues**: Concerns and mitigation
+
+**Tone:** Objective, data-driven, transparent
+**Length:** Detailed enough for decision-making
+**Audience:** Management, stakeholders
+
+### Leadership Updates
+Format for executive communication:
+
+**Structure:**
+1. **Context**: Situation background
+2. **Decision**: What was decided and why
+3. **Implications**: Impact on organization
+4. **Next Steps**: Required actions
+5. **Timeline**: When changes take effect
+
+**Tone:** Authoritative, strategic, clear
+**Length:** Comprehensive for decision context
+**Audience:** Leadership team, managers
+
+## General Guidelines
+
+### Writing Process
+1. **Identify type**: Match request to appropriate format
+2. **Gather information**: Collect facts, metrics, quotes
+3. **Structure content**: Follow type-specific guidelines
+4. **Review tone**: Ensure appropriate voice
+5. **Verify accuracy**: Check facts and data
+6. **Edit for clarity**: Remove jargon, simplify
+
+### Tone Guidelines
+- **Professional but approachable**
+- **Clear and direct**
+- **Respectful of time**
+- **Action-oriented when needed**
+- **Transparent about challenges**
+
+### Formatting
+- Use clear headings and subheadings
+- Bullet points for lists
+- Short paragraphs (3-4 sentences max)
+- White space for readability
+- Consistent style throughout
+
+## Usage Examples
+
+**Create team update:**
+`/internal-comms "3P update project alpha status"`
+
+**Write company newsletter:**
+`/internal-comms "company newsletter Q4 achievements"`
+
+**Respond to FAQ:**
+`/internal-comms "FAQ remote work policy changes"`
+
+**Generate status report:**
+`/internal-comms "status report infrastructure migration"`
+
+**Leadership communication:**
+`/internal-comms "leadership update org restructuring"`
+
+## Quality Checklist
+
+- [ ] Appropriate format selected
+- [ ] Key information included
+- [ ] Tone matches audience
+- [ ] Clear action items (if applicable)
+- [ ] Facts verified
+- [ ] Length appropriate
+- [ ] Follows company style
+- [ ] Ready for distribution
+
+Remember: Clear internal communication builds trust and alignment across the organization.

package/packages/opencode/command/mcp-builder.md

@@ -0,0 +1,282 @@
+---
+description: Create high-quality MCP servers that enable LLMs to interact with external services through well-designed tools
+argument-hint: <service-to-integrate> <language-choice>
+---
+
+Build high-quality MCP (Model Context Protocol) servers that enable LLMs to effectively interact with external services and APIs.
+
+## MCP Development Workflow
+
+### Phase 1: Research and Planning
+
+#### 1.1 Agent-Centric Design Principles
+
+**Build for Workflows, Not Just API Endpoints:**
+- Don't simply wrap existing API endpoints - build thoughtful, high-impact workflow tools
+- Consolidate related operations (e.g., `schedule_event` that checks availability AND creates event)
+- Focus on tools that enable complete tasks, not just individual API calls
+- Consider what workflows agents actually need to accomplish
+
+**Optimize for Limited Context:**
+- Agents have constrained context windows - make every token count
+- Return high-signal information, not exhaustive data dumps
+- Provide "concise" vs "detailed" response format options
+- Default to human-readable identifiers over technical codes (names over IDs)
+- Consider the agent's context budget as a scarce resource
+
+**Design Actionable Error Messages:**
+- Error messages should guide agents toward correct usage patterns
+- Suggest specific next steps: "Try using filter='active_only' to reduce results"
+- Make errors educational, not just diagnostic
+- Help agents learn proper tool usage through clear feedback
+
+**Follow Natural Task Subdivisions:**
+- Tool names should reflect how humans think about tasks
+- Group related tools with consistent prefixes for discoverability
+- Design tools around natural workflows, not just API structure
+
+#### 1.2 Study MCP Protocol
+Fetch the latest MCP protocol documentation:
+```bash
+# Load comprehensive MCP specification
+https://modelcontextprotocol.io/llms-full.txt
+```
+
+#### 1.3 Framework Documentation
+
+**Python Implementation:**
+- Load: `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
+- Use FastMCP framework for Python servers
+
+**Node/TypeScript Implementation:**
+- Load: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
+- Use MCP SDK for Node/TypeScript servers
+
+#### 1.4 API Documentation Study
+Exhaustively study the service API:
+- Official API reference documentation
+- Authentication and authorization requirements
+- Rate limiting and pagination patterns
+- Error responses and status codes
+- Available endpoints and their parameters
+- Data models and schemas
+
+#### 1.5 Implementation Planning
+Create a comprehensive plan:
+
+**Tool Selection:**
+- List the most valuable endpoints/operations to implement
+- Prioritize tools that enable common and important use cases
+- Consider which tools work together for complex workflows
+
+**Shared Utilities:**
+- Identify common API request patterns
+- Design authentication handling
+- Create pagination helpers
+- Build error handling utilities
+
+### Phase 2: Development
+
+#### 2.1 Project Setup
+```bash
+# Python setup
+pip install fastmcp
+mkdir mcp-server
+cd mcp-server
+
+# Node/TypeScript setup
+npm init -y
+npm install @modelcontextprotocol/sdk
+mkdir mcp-server
+cd mcp-server
+```
+
+#### 2.2 Tool Design Patterns
+
+**Workflow-Focused Tools:**
+```python
+# ❌ BAD: Simple API wrapper
+@tool
+def get_user(user_id: str) -> dict:
+    return api.get(f"/users/{user_id}")
+
+# ✅ GOOD: Complete workflow tool
+@tool
+def get_user_profile(user_id: str, include_recent_activity: bool = False) -> dict:
+    """
+    Get comprehensive user profile information.
+    
+    Args:
+        user_id: User identifier
+        include_recent_activity: Include last 30 days of activity
+        
+    Returns:
+        Complete user profile with optional activity data
+    """
+    user = api.get(f"/users/{user_id}")
+    if include_recent_activity:
+        activity = api.get(f"/users/{user_id}/activity", params={"days": 30})
+        user["recent_activity"] = activity
+    
+    return user
+```
+
+**Context-Aware Responses:**
+```python
+@tool
+def search_items(query: str, max_results: int = 10) -> dict:
+    """
+    Search for items with intelligent result formatting.
+    
+    Args:
+        query: Search query
+        max_results: Maximum number of results (default: 10, max: 50)
+        
+    Returns:
+        Concise search results with key identifiers and summaries
+    """
+    results = api.get("/search", params={"q": query, "limit": max_results})
+    
+    # Return concise, actionable format
+    return {
+        "query": query,
+        "total_found": len(results),
+        "items": [
+            {
+                "id": item["id"],
+                "name": item["name"], 
+                "summary": item["description"][:100] + "...",
+                "relevance_score": item["score"]
+            }
+            for item in results
+        ]
+    }
+```
+
+#### 2.3 Error Handling
+```python
+@tool
+def create_event(event_data: dict) -> dict:
+    """
+    Create a calendar event with validation.
+    
+    Args:
+        event_data: Event details including title, start, end, attendees
+        
+    Returns:
+        Created event information
+        
+    Raises:
+        ValidationError: If event data is invalid (missing required fields, 
+                        scheduling conflicts, or invalid time format)
+    """
+    try:
+        # Validate event data
+        if not event_data.get("title"):
+            raise ValueError("Event title is required")
+            
+        # Check for conflicts
+        conflicts = check_schedule_conflicts(event_data)
+        if conflicts:
+            return {
+                "success": False,
+                "error": "Schedule conflict detected",
+                "conflicting_events": conflicts,
+                "suggestion": "Try adjusting the time or use check_availability tool first"
+            }
+            
+        # Create event
+        result = api.post("/events", json=event_data)
+        return {"success": True, "event": result}
+        
+    except ValidationError as e:
+        return {
+            "success": False, 
+            "error": str(e),
+            "suggestion": "Ensure all required fields are provided and times are in ISO format"
+        }
+```
+
+### Phase 3: Testing and Evaluation
+
+#### 3.1 Create Evaluation Scenarios
+```python
+# Test realistic agent workflows
+test_scenarios = [
+    {
+        "name": "Complete user onboarding workflow",
+        "steps": [
+            "create_user",
+            "send_welcome_email", 
+            "schedule_kickoff_call",
+            "add_to_team"
+        ]
+    },
+    {
+        "name": "Project management workflow",
+        "steps": [
+            "create_project",
+            "add_team_members",
+            "create_tasks", 
+            "set_milestones",
+            "generate_report"
+        ]
+    }
+]
+```
+
+#### 3.2 Agent Testing
+Test the MCP server with real LLM agents:
+- Verify tools work for actual use cases
+- Check error messages guide correct usage
+- Ensure responses are appropriate for agent context
+- Validate workflow completeness
+
+### Phase 4: Documentation and Deployment
+
+#### 4.1 Tool Documentation
+Each tool should include:
+- Clear description of purpose and use cases
+- Parameter documentation with types and descriptions
+- Return value documentation
+- Usage examples
+- Error handling guidance
+
+#### 4.2 Best Practices Checklist
+
+**Tool Design:**
+- [ ] Tools enable complete workflows, not just API calls
+- [ ] Error messages are actionable and educational
+- [ ] Responses are concise but informative
+- [ ] Tool names reflect natural task subdivisions
+- [ ] Related tools have consistent prefixes
+
+**Development:**
+- [ ] Comprehensive API coverage studied
+- [ ] Authentication handled securely
+- [ ] Rate limiting respected
+- [ ] Pagination implemented
+- [ ] Error handling robust
+- [ ] Type safety maintained
+
+**Testing:**
+- [ ] Realistic evaluation scenarios created
+- [ ] Agent feedback incorporated
+- [ ] Performance tested
+- [ ] Edge cases covered
+
+## Usage Examples
+
+**Create MCP server for calendar service:**
+`/mcp-builder "Google Calendar API" "python"`
+
+**Build integration for project management:**
+`/mcp-builder "Jira API" "typescript"`
+
+**Develop customer support tools:**
+`/mcp-builder "Zendesk API" "python"`
+
+**Create data analytics server:**
+`/mcp-builder "Analytics API" "typescript"`
+
+Remember: Quality MCP servers enable LLMs to accomplish real-world tasks effectively through well-designed, workflow-focused tools.

package/packages/opencode/command/pdf.md

@@ -0,0 +1,194 @@
+---
+description: Comprehensive PDF processing toolkit - extract text/tables, create PDFs, merge/split, handle forms
+argument-hint: <operation> <input-file>
+---
+
+**Available Operations:**
+- `extract` - Extract text from PDF
+- `merge` - Merge multiple PDFs
+- `split` - Split PDF into individual pages
+- `form-check` - Check if PDF has fillable fields
+- `form-extract` - Extract form field information
+- `form-fill` - Fill PDF form fields
+- `convert-images` - Convert PDF pages to images
+- `create` - Create new PDF from text
+
+## Basic Operations
+
+### Extract Text
+```python
+from pypdf import PdfReader
+
+reader = PdfReader("document.pdf")
+text = ""
+for page in reader.pages:
+    text += page.extract_text()
+print(f"Extracted {len(text)} characters")
+```
+
+### Merge PDFs
+```python
+from pypdf import PdfWriter, PdfReader
+
+writer = PdfWriter()
+for pdf_file in ["doc1.pdf", "doc2.pdf"]:
+    reader = PdfReader(pdf_file)
+    for page in reader.pages:
+        writer.add_page(page)
+
+with open("merged.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### Split PDF
+```python
+reader = PdfReader("input.pdf")
+for i, page in enumerate(reader.pages):
+    writer = PdfWriter()
+    writer.add_page(page)
+    with open(f"page_{i+1}.pdf", "wb") as output:
+        writer.write(output)
+```
+
+## Form Operations
+
+### Check Fillable Fields
+**CRITICAL:** First check if PDF has fillable form fields:
+```bash
+python scripts/check_fillable_fields.py <file.pdf>
+```
+
+### Extract Form Information
+If PDF has fillable fields, extract field data:
+```bash
+python scripts/extract_form_field_info.py <input.pdf> <field_info.json>
+```
+
+**Field Information Format:**
+```json
+[
+  {
+    "field_id": "unique-id",
+    "page": 1,
+    "rect": [left, bottom, right, top],
+    "type": "text|checkbox|radio_group|choice"
+  }
+]
+```
+
+### Fill Forms
+Use the extracted field information to programmatically fill the form:
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("form.pdf")
+writer = PdfWriter()
+
+# Copy all pages
+for page in reader.pages:
+    writer.add_page(page)
+
+# Update form fields
+field_data = {
+    "field_name": "value",
+    "checkbox_field": "Yes",
+    "dropdown": "Option 1"
+}
+
+writer.update_page_form_field_values(writer.pages[0], field_data)
+
+with open("filled_form.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Image Conversion
+
+### Convert to Images
+```python
+from pypdfium2 import PdfDocument
+from PIL import Image
+
+pdf = PdfDocument("document.pdf")
+for i, page in enumerate(pdf):
+    bitmap = page.render(scale=2.0)  # High resolution
+    img = bitmap.to_pil()
+    img.save(f"page_{i+1}.png")
+```
+
+## Advanced Features
+
+### PDFium2 for Fast Processing
+```python
+import pypdfium2 as pdfium
+
+pdf = pdfium.PdfDocument("document.pdf")
+for i, page in enumerate(pdf):
+    text = page.get_text()
+    bitmap = page.render(scale=1.5)
+    img = bitmap.to_pil()
+    img.save(f"page_{i+1}.jpg", quality=90)
+```
+
+### JavaScript with pdf-lib
+```javascript
+import { PDFDocument } from 'pdf-lib';
+import fs from 'fs';
+
+async function manipulatePDF() {
+    const pdfDoc = await PDFDocument.load(fs.readFileSync('input.pdf'));
+    const pageCount = pdfDoc.getPageCount();
+    
+    const newPage = pdfDoc.addPage([600, 400]);
+    newPage.drawText('Added content', { x: 100, y: 300, size: 16 });
+    
+    fs.writeFileSync('modified.pdf', await pdfDoc.save());
+}
+```
+
+## Common Patterns
+
+### Bounding Box Extraction
+For non-fillable forms, extract coordinates:
+```python
+# Scripts available for analyzing PDF structure
+# check_bounding_boxes.py - Visual analysis tool
+# create_validation_image.py - Generate preview with field locations
+```
+
+### Table Extraction
+```python
+# Use pdfplumber for structured table extraction
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    for page in pdf.pages:
+        tables = page.extract_tables()
+        for table in tables:
+            print(table)
+```
+
+### Error Handling
+```python
+try:
+    reader = PdfReader("file.pdf")
+    text = page.extract_text()
+except Exception as e:
+    print(f"Error processing PDF: {e}")
+```
+
+## Usage Examples
+
+**Extract text from report:**
+`/pdf extract monthly-report.pdf`
+
+**Merge multiple invoices:**
+`/pdf merge invoice1.pdf invoice2.pdf invoice3.pdf`
+
+**Check form fields:**
+`/pdf form-check application-form.pdf`
+
+**Convert to images for analysis:**
+`/pdf convert-images document.pdf`
+
+**Create simple PDF:**
+`/pdf create "Hello World" output.pdf`