@ngockhoale/ukit 1.6.8 → 2.0.2

package/templates/.claude/skills/executing-plans/SKILL.md

@@ -15,11 +15,23 @@ Load plan, review critically, execute tasks in batches, report for review betwee
 
 ## The Process
 
-### Step 1: Load and Review Plan
+### Step 1: Preflight, then Load and Review Plan
 1. Read plan file
-2. Review critically - identify any questions or concerns about the plan
-3. If concerns: Raise them with your human partner before starting
-4. If no concerns: Create TodoWrite and proceed
+2. Run the preflight checklist — each ✓ needs a real check, not an assumption:
+
+```
+Plan received
+✓ dependencies available   - referenced files/packages/tests exist
+✓ instructions executable  - each step is a concrete action, not a question
+✓ verification possible    - each step's check actually runs
+✓ no contradictory steps   - no step conflicts with an earlier one
+✓ no missing prerequisite  - nothing earlier is silently assumed done
+✓ environment compatible   - required tools/versions installed
+READY TO EXECUTE
+```
+
+3. If any ✓ fails: Raise it with your human partner before starting
+4. If READY TO EXECUTE: Create TodoWrite and proceed
 
 ### Step 2: Execute Batch
 **Default: First 3 tasks**
@@ -49,28 +61,28 @@ After all tasks complete and verified:
 - **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch
 - Follow that skill to verify tests, present options, execute choice
 
-## When to Stop and Ask for Help
+## Blocker Classifier
 
-**STOP executing immediately when:**
-- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear)
-- Plan has critical gaps preventing starting
-- You don't understand an instruction
-- Verification fails repeatedly
+**Classify every mid-batch blocker before reacting:**
 
-**Ask for clarification rather than guessing.**
-
-## When to Revisit Earlier Steps
+```
+BLOCKER TYPE
+🟡 Recoverable        → retry/fallback, note it, continue
+🟠 Planning defect     → return to Step 1 (Preflight), do not guess a fix
+🔵 Missing information → ask the human partner, do not proceed on assumption
+🔴 Hard stop           → execution unsafe/impossible, stop immediately, explain why
+```
 
-**Return to Review (Step 1) when:**
-- Partner updates the plan based on your feedback
-- Fundamental approach needs rethinking
+- Missing dependency → 🟠 · Test fails once → 🟡, repeatedly → 🔴
+- Instruction unclear → 🔵 · Critical gap blocks starting → 🔴
+- Partner revises the plan, or approach needs rethinking → return to Preflight
 
-**Don't force through blockers** - stop and ask.
+**Ask for clarification rather than guessing.**
 
 ## Remember
-- Review plan critically first
+- Preflight before executing
 - Follow plan steps exactly
 - Don't skip verifications
 - Reference skills when plan says to
 - Between batches: just report and wait
-- Stop when blocked, don't guess
+- Classify blockers before reacting, don't guess

package/templates/.claude/skills/file-organizer/SKILL.md

@@ -259,175 +259,7 @@ When a user requests file organization help:
    Want to organize another folder?
    ```
 
-## Examples
+## Examples and Reference
 
-### Example 1: Organizing Downloads (From Justin Dielmann)
-
-**User**: "My Downloads folder is a mess with 500+ files. Help me organize it."
-
-**Process**:
-1. Analyzes Downloads folder
-2. Finds patterns: work docs, personal photos, installers, random PDFs
-3. Proposes structure:
-   - Downloads/
-     - Work/
-     - Personal/
-     - Installers/ (DMG, PKG files)
-     - Archive/
-     - ToSort/ (things needing decisions)
-4. Asks for confirmation
-5. Moves files intelligently based on content and names
-6. Results: 500 files → 5 organized folders
-
-### Example 2: Finding and Removing Duplicates
-
-**User**: "Find duplicate files in my Documents and help me decide which to keep."
-
-**Output**:
-```markdown
-# Found 23 Sets of Duplicates (156 MB total)
-
-## Duplicate Set 1: "proposal.pdf"
-- `/Documents/proposal.pdf` (2.3 MB, modified: 2024-03-15)
-- `/Documents/old/proposal.pdf` (2.3 MB, modified: 2024-03-15)
-- `/Desktop/proposal.pdf` (2.3 MB, modified: 2024-03-10)
-
-**Recommendation**: Keep `/Documents/proposal.pdf` (most recent in correct location)
-Delete the other 2 copies?
-
-[Continue for all duplicates...]
-```
-
-### Example 3: Restructuring Projects Folder
-
-**User**: "Review my ~/Projects directory and suggest improvements."
-
-**Output**:
-```markdown
-# Analysis of ~/Projects
-
-## Current Structure Issues
-- Mix of active and archived projects (3+ years old)
-- No consistent naming convention
-- Some projects at root, others in random subfolders
-- Duplicate folders (project-name, project-name-old, project-name-v2)
-
-## Proposed Structure
-
-```
-Projects/
-├── Active/
-│   ├── client-work/
-│   ├── side-projects/
-│   └── learning/
-├── Archive/
-│   ├── 2022/
-│   ├── 2023/
-│   └── 2024/
-└── Templates/
-```
-
-## Specific Changes
-1. Move 12 projects not touched since 2022 → Archive/
-2. Consolidate 4 duplicate project folders
-3. Rename projects to consistent format: "client-name-project-name"
-4. Create Archive for old work
-
-Want me to implement this?
-```
-
-### Example 4: Organizing Photos by Date
-
-**User**: "Organize my photo folders by year and month."
-
-**Output**: Creates structure like:
-```
-Photos/
-├── 2023/
-│   ├── 01-January/
-│   ├── 02-February/
-│   └── ...
-├── 2024/
-│   ├── 01-January/
-│   └── ...
-└── Unsorted/
-```
-
-Then moves photos based on EXIF data or file modification dates.
-
-## Common Organization Tasks
-
-### Downloads Cleanup
-```
-Organize my Downloads folder - move documents to Documents, 
-images to Pictures, keep installers separate, and archive files 
-older than 3 months.
-```
-
-### Project Organization
-```
-Review my Projects folder structure and help me separate active 
-projects from old ones I should archive.
-```
-
-### Duplicate Removal
-```
-Find all duplicate files in my Documents folder and help me 
-decide which ones to keep.
-```
-
-### Desktop Cleanup
-```
-My Desktop is covered in files. Help me organize everything into 
-my Documents folder properly.
-```
-
-### Photo Organization
-```
-Organize all photos in this folder by date (year/month) based 
-on when they were taken.
-```
-
-### Work/Personal Separation
-```
-Help me separate my work files from personal files across my 
-Documents folder.
-```
-
-## Pro Tips
-
-1. **Start Small**: Begin with one messy folder (like Downloads) to build trust
-2. **Regular Maintenance**: Run weekly cleanup on Downloads
-3. **Consistent Naming**: Use "YYYY-MM-DD - Description" format for important files
-4. **Archive Aggressively**: Move old projects to Archive instead of deleting
-5. **Keep Active Separate**: Maintain clear boundaries between active and archived work
-6. **Trust the Process**: Let Claude handle the cognitive load of where things go
-
-## Best Practices
-
-### Folder Naming
-- Use clear, descriptive names
-- Avoid spaces (use hyphens or underscores)
-- Be specific: "client-proposals" not "docs"
-- Use prefixes for ordering: "01-current", "02-archive"
-
-### File Naming
-- Include dates: "2024-10-17-meeting-notes.md"
-- Be descriptive: "q3-financial-report.xlsx"
-- Avoid version numbers in names (use version control instead)
-- Remove download artifacts: "document-final-v2 (1).pdf" → "document.pdf"
-
-### When to Archive
-- Projects not touched in 6+ months
-- Completed work that might be referenced later
-- Old versions after migration to new systems
-- Files you're hesitant to delete (archive first)
-
-## Related Use Cases
-
-- Setting up organization for a new computer
-- Preparing files for backup/archiving
-- Cleaning up before storage cleanup
-- Organizing shared team folders
-- Structuring new project directories
+Four worked examples (Downloads cleanup, duplicate detection output, project-folder restructuring, photo organization by date), common request phrasings, pro tips, and folder/file naming best practices are in [`examples-and-practices.md`](examples-and-practices.md).
 

package/templates/.claude/skills/file-organizer/examples-and-practices.md

@@ -0,0 +1,173 @@
+# File Organizer — Examples and Practices
+
+## Examples
+
+### Example 1: Organizing Downloads (From Justin Dielmann)
+
+**User**: "My Downloads folder is a mess with 500+ files. Help me organize it."
+
+**Process**:
+1. Analyzes Downloads folder
+2. Finds patterns: work docs, personal photos, installers, random PDFs
+3. Proposes structure:
+   - Downloads/
+     - Work/
+     - Personal/
+     - Installers/ (DMG, PKG files)
+     - Archive/
+     - ToSort/ (things needing decisions)
+4. Asks for confirmation
+5. Moves files intelligently based on content and names
+6. Results: 500 files → 5 organized folders
+
+### Example 2: Finding and Removing Duplicates
+
+**User**: "Find duplicate files in my Documents and help me decide which to keep."
+
+**Output**:
+```markdown
+# Found 23 Sets of Duplicates (156 MB total)
+
+## Duplicate Set 1: "proposal.pdf"
+- `/Documents/proposal.pdf` (2.3 MB, modified: 2024-03-15)
+- `/Documents/old/proposal.pdf` (2.3 MB, modified: 2024-03-15)
+- `/Desktop/proposal.pdf` (2.3 MB, modified: 2024-03-10)
+
+**Recommendation**: Keep `/Documents/proposal.pdf` (most recent in correct location)
+Delete the other 2 copies?
+
+[Continue for all duplicates...]
+```
+
+### Example 3: Restructuring Projects Folder
+
+**User**: "Review my ~/Projects directory and suggest improvements."
+
+**Output**:
+```markdown
+# Analysis of ~/Projects
+
+## Current Structure Issues
+- Mix of active and archived projects (3+ years old)
+- No consistent naming convention
+- Some projects at root, others in random subfolders
+- Duplicate folders (project-name, project-name-old, project-name-v2)
+
+## Proposed Structure
+
+```
+Projects/
+├── Active/
+│   ├── client-work/
+│   ├── side-projects/
+│   └── learning/
+├── Archive/
+│   ├── 2022/
+│   ├── 2023/
+│   └── 2024/
+└── Templates/
+```
+
+## Specific Changes
+1. Move 12 projects not touched since 2022 → Archive/
+2. Consolidate 4 duplicate project folders
+3. Rename projects to consistent format: "client-name-project-name"
+4. Create Archive for old work
+
+Want me to implement this?
+```
+
+### Example 4: Organizing Photos by Date
+
+**User**: "Organize my photo folders by year and month."
+
+**Output**: Creates structure like:
+```
+Photos/
+├── 2023/
+│   ├── 01-January/
+│   ├── 02-February/
+│   └── ...
+├── 2024/
+│   ├── 01-January/
+│   └── ...
+└── Unsorted/
+```
+
+Then moves photos based on EXIF data or file modification dates.
+
+## Common Organization Tasks
+
+### Downloads Cleanup
+```
+Organize my Downloads folder - move documents to Documents, 
+images to Pictures, keep installers separate, and archive files 
+older than 3 months.
+```
+
+### Project Organization
+```
+Review my Projects folder structure and help me separate active 
+projects from old ones I should archive.
+```
+
+### Duplicate Removal
+```
+Find all duplicate files in my Documents folder and help me 
+decide which ones to keep.
+```
+
+### Desktop Cleanup
+```
+My Desktop is covered in files. Help me organize everything into 
+my Documents folder properly.
+```
+
+### Photo Organization
+```
+Organize all photos in this folder by date (year/month) based 
+on when they were taken.
+```
+
+### Work/Personal Separation
+```
+Help me separate my work files from personal files across my 
+Documents folder.
+```
+
+## Pro Tips
+
+1. **Start Small**: Begin with one messy folder (like Downloads) to build trust
+2. **Regular Maintenance**: Run weekly cleanup on Downloads
+3. **Consistent Naming**: Use "YYYY-MM-DD - Description" format for important files
+4. **Archive Aggressively**: Move old projects to Archive instead of deleting
+5. **Keep Active Separate**: Maintain clear boundaries between active and archived work
+6. **Trust the Process**: Let Claude handle the cognitive load of where things go
+
+## Best Practices
+
+### Folder Naming
+- Use clear, descriptive names
+- Avoid spaces (use hyphens or underscores)
+- Be specific: "client-proposals" not "docs"
+- Use prefixes for ordering: "01-current", "02-archive"
+
+### File Naming
+- Include dates: "2024-10-17-meeting-notes.md"
+- Be descriptive: "q3-financial-report.xlsx"
+- Avoid version numbers in names (use version control instead)
+- Remove download artifacts: "document-final-v2 (1).pdf" → "document.pdf"
+
+### When to Archive
+- Projects not touched in 6+ months
+- Completed work that might be referenced later
+- Old versions after migration to new systems
+- Files you're hesitant to delete (archive first)
+
+## Related Use Cases
+
+- Setting up organization for a new computer
+- Preparing files for backup/archiving
+- Cleaning up before storage cleanup
+- Organizing shared team folders
+- Structuring new project directories

package/templates/.claude/skills/pdf/SKILL.md

@@ -210,68 +210,7 @@ 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)
-```
+OCR on scanned PDFs, adding a watermark, extracting embedded images, and basic password protection: [`reference.md`](reference.md#common-quick-tasks).
 
 ## Quick Reference
 

package/templates/.claude/skills/pdf/reference.md

@@ -2,6 +2,71 @@
 
 This document contains advanced PDF processing features, detailed examples, and additional libraries not covered in the main skill instructions.
 
+## Common Quick 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)
+```
+
 ## pypdfium2 Library (Apache/BSD License)
 
 ### Overview

package/templates/.claude/skills/pdf-processing-pro/SKILL.md

@@ -147,54 +147,7 @@ python scripts/validate_pdf.py input.pdf
 
 ## Common workflows
 
-### Workflow 1: Process form submissions
-
-```bash
-# 1. Analyze form structure
-python scripts/analyze_form.py template.pdf --output schema.json
-
-# 2. Validate submission data
-python scripts/validate_form.py submission.json schema.json
-
-# 3. Fill form
-python scripts/fill_form.py template.pdf submission.json completed.pdf
-
-# 4. Validate output
-python scripts/validate_pdf.py completed.pdf
-```
-
-### Workflow 2: Extract data from reports
-
-```bash
-# 1. Extract tables
-python scripts/extract_tables.py monthly_report.pdf --output data.csv
-
-# 2. Extract text for analysis
-python scripts/extract_text.py monthly_report.pdf --output report.txt
-```
-
-### Workflow 3: Batch processing
-
-```python
-import glob
-from pathlib import Path
-import subprocess
-
-# Process all PDFs in directory
-for pdf_file in glob.glob("invoices/*.pdf"):
-    output_file = Path("processed") / Path(pdf_file).name
-
-    result = subprocess.run([
-        "python", "scripts/extract_text.py",
-        pdf_file,
-        "--output", str(output_file)
-    ], capture_output=True)
-
-    if result.returncode == 0:
-        print(f"✓ Processed: {pdf_file}")
-    else:
-        print(f"✗ Failed: {pdf_file} - {result.stderr}")
-```
+Three worked workflows (form submissions, report data extraction, batch processing): [`workflows-and-troubleshooting.md`](workflows-and-troubleshooting.md#common-workflows).
 
 ## Error handling
 
@@ -255,31 +208,7 @@ Optional for OCR:
 
 ## Troubleshooting
 
-### Common issues
-
-**"Module not found" errors**:
-```bash
-pip install -r requirements.txt
-```
-
-**Tesseract not found**:
-```bash
-# Install tesseract system package (see Dependencies)
-```
-
-**Memory errors with large PDFs**:
-```python
-# Process page by page instead of loading entire PDF
-with pdfplumber.open("large.pdf") as pdf:
-    for page in pdf.pages:
-        text = page.extract_text()
-        # Process page immediately
-```
-
-**Permission errors**:
-```bash
-chmod +x scripts/*.py
-```
+Common issues (missing modules, tesseract not found, memory errors on large PDFs, permission errors) and fixes: [`workflows-and-troubleshooting.md`](workflows-and-troubleshooting.md#troubleshooting).
 
 ## Getting help