@mclawnet/agent 0.5.9 → 0.6.2

package/skills/pair-programming/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: pair-programming
+description: Facilitate effective AI-assisted pair programming sessions with structured collaboration modes. Use when working through complex implementations, debugging sessions, refactoring tasks, or learning new codebases with an AI partner.
+---
+
+# Pair Programming
+
+Structured AI-assisted pair programming for productive collaboration on implementation, debugging, refactoring, and learning tasks.
+
+## Overview
+
+Pair programming with AI is most effective when roles are clear and the collaboration mode matches the task. This skill defines three modes — Driver, Navigator, and TDD — each with specific responsibilities, communication patterns, and quality checks. The goal is not to produce code faster, but to produce better code by combining human judgment with AI capabilities.
+
+## When to Use
+
+- Implementing complex features that benefit from real-time review
+- Debugging problems that require systematic exploration
+- Refactoring existing code while maintaining behavior
+- Learning a new codebase, framework, or pattern
+- Working through architectural decisions with concrete code
+- Situations where you want continuous quality feedback as you code
+
+## When NOT to Use
+
+- **Quick one-line fixes** — just make the change
+- **Code review of completed work** — use the `code-review` skill
+- **Writing tests for existing code** — use the `testing` skill
+- **Architecture planning without code** — use the `architecture` skill
+
+## Collaboration Modes
+
+### Driver Mode
+
+**You write code. AI navigates.**
+
+Best for: learning, implementing familiar features, hands-on debugging.
+
+**Your role (Driver):**
+- Write the actual code
+- Make implementation decisions
+- Control the pace
+- Ask questions when stuck
+
+**AI role (Navigator):**
+- Review each change as it's made
+- Spot potential bugs, edge cases, or security issues
+- Suggest improvements and alternatives
+- Keep the big picture in view — remind of requirements and constraints
+- Flag when the approach is drifting from the goal
+
+**Communication pattern:**
+- After each meaningful change, pause for navigator feedback
+- Navigator speaks up proactively when spotting issues
+- Driver can request: "review this", "suggest a better approach", "what am I missing?"
+
+### Navigator Mode
+
+**AI writes code. You direct.**
+
+Best for: rapid prototyping, boilerplate generation, exploring solutions.
+
+**Your role (Navigator):**
+- Define what to build and the acceptance criteria
+- Review every piece of generated code before accepting
+- Make architectural and design decisions
+- Redirect when implementation drifts from requirements
+- Approve or reject each change
+
+**AI role (Driver):**
+- Write implementation code as directed
+- Explain decisions and trade-offs as it codes
+- Present alternatives when there are multiple valid approaches
+- Stop and ask when requirements are ambiguous
+
+**Communication pattern:**
+- AI explains what it's about to do before writing code
+- You approve the approach, then AI implements
+- You review the result before moving to the next piece
+- You can say: "try a different approach", "simplify this", "add error handling"
+
+### TDD Mode
+
+**Alternate between writing tests and implementation.**
+
+Best for: building features with high correctness requirements, learning TDD.
+
+**Process:**
+
+1. **Red**: Write one failing test that describes the next small behavior
+2. **Verify**: Run the test and confirm it fails for the right reason
+3. **Green**: Write the minimum code to make the test pass
+4. **Verify**: Run all tests and confirm everything passes
+5. **Refactor**: Improve code structure without changing behavior
+6. **Verify**: Run all tests and confirm they still pass
+7. **Commit**: Save progress
+8. **Repeat**: Back to step 1 for the next behavior
+
+**Role alternation:**
+- Either person can write the test or the implementation
+- A good pattern: you write the test (defining the spec), AI writes the implementation
+- Or: AI writes the test, you verify it captures the right behavior, AI implements
+
+## Session Flow
+
+### Starting a Session
+
+1. **State the goal**: What are we building/fixing/improving?
+2. **Choose the mode**: Driver, Navigator, or TDD
+3. **Set scope**: What files/modules are in scope? What's off-limits?
+4. **Establish quality bar**: What does "done" look like?
+
+### During the Session
+
+**Every 15-20 minutes, check:**
+- Are we still on track toward the goal?
+- Has scope crept beyond what we started with?
+- Are tests passing?
+- Should we commit what we have?
+
+**Switching modes is OK:**
+- Start in Navigator mode for rapid scaffolding
+- Switch to Driver mode when you want to understand the details
+- Switch to TDD mode when correctness matters most
+
+### Ending a Session
+
+1. Run all tests
+2. Review the diff of everything changed
+3. Commit with a descriptive message
+4. Note any follow-up items
+
+## Quality Practices
+
+### Continuous Review
+
+Every change should be reviewed before moving on:
+
+- **Correctness**: Does it do what it should? Edge cases handled?
+- **Readability**: Will this make sense in a month?
+- **Simplicity**: Is there a simpler way to achieve the same result?
+- **Testability**: Can this be easily tested?
+
+### Red Flags to Watch For
+
+- **Growing complexity**: If the solution keeps getting more complicated, step back and reconsider the approach
+- **Working around the framework**: If you're fighting the language/framework, you may be using it wrong
+- **No tests**: If you've written more than 20 lines without a test, pause and add one
+- **Copy-paste code**: If you're copying blocks, extract a function
+- **Magic numbers/strings**: Name every constant
+
+### Communication Signals
+
+| Signal | Meaning |
+|---|---|
+| "I'm stuck" | Pause, explain the problem, brainstorm approaches |
+| "This feels wrong" | Step back, review the approach, consider alternatives |
+| "What if..." | Explore the idea before committing to code |
+| "Let's commit" | We have a working increment, save it |
+| "Let's refactor" | The code works but isn't clean, improve structure |
+| "Let me drive" | Switch to Driver mode |
+| "You drive" | Switch to Navigator mode |
+
+## Debugging Sessions
+
+When pair programming for debugging:
+
+1. **Reproduce**: Get a reliable reproduction of the bug
+2. **Hypothesize**: List 3 possible causes
+3. **Test**: Check the most likely hypothesis first
+4. **Narrow**: Binary search through the code to find the exact location
+5. **Fix**: Write a test that fails because of the bug, then fix the code
+6. **Verify**: Confirm the fix doesn't break anything else
+
+**Navigator's job during debugging:**
+- Track which hypotheses have been tested
+- Suggest new hypotheses based on evidence
+- Watch for confirmation bias (testing only what supports our theory)
+- Remind to write a regression test
+
+## Anti-Patterns
+
+### Rubber Duck Syndrome
+**Problem**: Using AI as a silent audience instead of an active partner.
+**Fix**: Ask for explicit review, suggestions, and alternatives. Use the navigator role.
+
+### Speed Over Quality
+**Problem**: Rushing to produce code without review.
+**Fix**: Review every function before moving to the next. Run tests frequently.
+
+### Scope Creep
+**Problem**: "While we're here, let's also fix X, Y, Z..."
+**Fix**: Note follow-ups, stay focused on the original goal. One commit per concern.
+
+### Not Committing
+**Problem**: 200 lines of uncommitted changes.
+**Fix**: Commit after each passing test or completed feature slice. Small, frequent commits.

package/skills/pdf/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: pdf
+description: Process PDF documents including text extraction, table parsing, creation, merging, splitting, and form filling. Use when working with PDF files for reading, generating, manipulating, or analyzing PDF content at scale.
+---
+
+# PDF Processing Guide
+
+## Overview
+
+This guide covers essential PDF processing operations using Python libraries and command-line tools. For advanced features, JavaScript libraries, and detailed examples, see reference.md. If you need to fill out a PDF form, read forms.md and follow its instructions.
+
+## When to Use
+
+- Extracting text or tables from PDF files
+- Creating new PDF documents programmatically
+- Merging, splitting, or rotating PDF pages
+- Filling out PDF forms
+- Adding watermarks or password protection
+- OCR on scanned PDF documents
+
+## When NOT to Use
+
+- **Word documents** — use the `docx` skill
+- **Spreadsheets** — use the `xlsx` skill
+- **Presentations** — use the `pptx` skill
+- **Simple text extraction** — if the content is also available as .txt or .md, read directly
+
+## Quick Start
+
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Read a PDF
+reader = PdfReader("document.pdf")
+print(f"Pages: {len(reader.pages)}")
+
+# Extract text
+text = ""
+for page in reader.pages:
+    text += page.extract_text()
+```
+
+## Python Libraries
+
+### pypdf - Basic Operations
+
+#### Merge PDFs
+```python
+from pypdf import PdfWriter, PdfReader
+
+writer = PdfWriter()
+for pdf_file in ["doc1.pdf", "doc2.pdf", "doc3.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)
+```
+
+#### Extract Metadata
+```python
+reader = PdfReader("document.pdf")
+meta = reader.metadata
+print(f"Title: {meta.title}")
+print(f"Author: {meta.author}")
+print(f"Subject: {meta.subject}")
+print(f"Creator: {meta.creator}")
+```
+
+#### Rotate Pages
+```python
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+page = reader.pages[0]
+page.rotate(90)  # Rotate 90 degrees clockwise
+writer.add_page(page)
+
+with open("rotated.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### pdfplumber - Text and Table Extraction
+
+#### Extract Text with Layout
+```python
+import pdfplumber
+
+with pdfplumber.open("document.pdf") as pdf:
+    for page in pdf.pages:
+        text = page.extract_text()
+        print(text)
+```
+
+#### Extract Tables
+```python
+with pdfplumber.open("document.pdf") as pdf:
+    for i, page in enumerate(pdf.pages):
+        tables = page.extract_tables()
+        for j, table in enumerate(tables):
+            print(f"Table {j+1} on page {i+1}:")
+            for row in table:
+                print(row)
+```
+
+#### Advanced Table Extraction
+```python
+import pandas as pd
+
+with pdfplumber.open("document.pdf") as pdf:
+    all_tables = []
+    for page in pdf.pages:
+        tables = page.extract_tables()
+        for table in tables:
+            if table:  # Check if table is not empty
+                df = pd.DataFrame(table[1:], columns=table[0])
+                all_tables.append(df)
+
+# Combine all tables
+if all_tables:
+    combined_df = pd.concat(all_tables, ignore_index=True)
+    combined_df.to_excel("extracted_tables.xlsx", index=False)
+```
+
+### reportlab - Create PDFs
+
+#### Basic PDF Creation
+```python
+from reportlab.lib.pagesizes import letter
+from reportlab.pdfgen import canvas
+
+c = canvas.Canvas("hello.pdf", pagesize=letter)
+width, height = letter
+
+# Add text
+c.drawString(100, height - 100, "Hello World!")
+c.drawString(100, height - 120, "This is a PDF created with reportlab")
+
+# Add a line
+c.line(100, height - 140, 400, height - 140)
+
+# Save
+c.save()
+```
+
+#### Create PDF with Multiple Pages
+```python
+from reportlab.lib.pagesizes import letter
+from reportlab.platypus import SimpleDocTemplate, Paragraph, Spacer, PageBreak
+from reportlab.lib.styles import getSampleStyleSheet
+
+doc = SimpleDocTemplate("report.pdf", pagesize=letter)
+styles = getSampleStyleSheet()
+story = []
+
+# Add content
+title = Paragraph("Report Title", styles['Title'])
+story.append(title)
+story.append(Spacer(1, 12))
+
+body = Paragraph("This is the body of the report. " * 20, styles['Normal'])
+story.append(body)
+story.append(PageBreak())
+
+# Page 2
+story.append(Paragraph("Page 2", styles['Heading1']))
+story.append(Paragraph("Content for page 2", styles['Normal']))
+
+# Build PDF
+doc.build(story)
+```
+
+## Command-Line Tools
+
+### pdftotext (poppler-utils)
+```bash
+# Extract text
+pdftotext input.pdf output.txt
+
+# Extract text preserving layout
+pdftotext -layout input.pdf output.txt
+
+# Extract specific pages
+pdftotext -f 1 -l 5 input.pdf output.txt  # Pages 1-5
+```
+
+### qpdf
+```bash
+# Merge PDFs
+qpdf --empty --pages file1.pdf file2.pdf -- merged.pdf
+
+# Split pages
+qpdf input.pdf --pages . 1-5 -- pages1-5.pdf
+qpdf input.pdf --pages . 6-10 -- pages6-10.pdf
+
+# Rotate pages
+qpdf input.pdf output.pdf --rotate=+90:1  # Rotate page 1 by 90 degrees
+
+# Remove password
+qpdf --password=mypassword --decrypt encrypted.pdf decrypted.pdf
+```
+
+### pdftk (if available)
+```bash
+# Merge
+pdftk file1.pdf file2.pdf cat output merged.pdf
+
+# Split
+pdftk input.pdf burst
+
+# Rotate
+pdftk input.pdf rotate 1east output rotated.pdf
+```
+
+## Common Tasks
+
+### Extract Text from Scanned PDFs
+```python
+# Requires: pip install pytesseract pdf2image
+import pytesseract
+from pdf2image import convert_from_path
+
+# Convert PDF to images
+images = convert_from_path('scanned.pdf')
+
+# OCR each page
+text = ""
+for i, image in enumerate(images):
+    text += f"Page {i+1}:\n"
+    text += pytesseract.image_to_string(image)
+    text += "\n\n"
+
+print(text)
+```
+
+### Add Watermark
+```python
+from pypdf import PdfReader, PdfWriter
+
+# Create watermark (or load existing)
+watermark = PdfReader("watermark.pdf").pages[0]
+
+# Apply to all pages
+reader = PdfReader("document.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    page.merge_page(watermark)
+    writer.add_page(page)
+
+with open("watermarked.pdf", "wb") as output:
+    writer.write(output)
+```
+
+### Extract Images
+```bash
+# Using pdfimages (poppler-utils)
+pdfimages -j input.pdf output_prefix
+
+# This extracts all images as output_prefix-000.jpg, output_prefix-001.jpg, etc.
+```
+
+### Password Protection
+```python
+from pypdf import PdfReader, PdfWriter
+
+reader = PdfReader("input.pdf")
+writer = PdfWriter()
+
+for page in reader.pages:
+    writer.add_page(page)
+
+# Add password
+writer.encrypt("userpassword", "ownerpassword")
+
+with open("encrypted.pdf", "wb") as output:
+    writer.write(output)
+```
+
+## Quick Reference
+
+| Task | Best Tool | Command/Code |
+|------|-----------|--------------|
+| Merge PDFs | pypdf | `writer.add_page(page)` |
+| Split PDFs | pypdf | One page per file |
+| Extract text | pdfplumber | `page.extract_text()` |
+| Extract tables | pdfplumber | `page.extract_tables()` |
+| Create PDFs | reportlab | Canvas or Platypus |
+| Command line merge | qpdf | `qpdf --empty --pages ...` |
+| OCR scanned PDFs | pytesseract | Convert to image first |
+| Fill PDF forms | pdf-lib or pypdf (see forms.md) | See forms.md |
+
+## Next Steps
+
+- For advanced pypdfium2 usage, see reference.md
+- For JavaScript libraries (pdf-lib), see reference.md
+- If you need to fill out a PDF form, follow the instructions in forms.md
+- For troubleshooting guides, see reference.md