npm - @amrhas82/agentic-kit - Versions diffs - 1.2.1 → 1.7.0 - Mend

@amrhas82/agentic-kit 1.2.1 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1036) hide show

package/packages/opencode/command/pptx.md ADDED Viewed

@@ -0,0 +1,272 @@
+---
+description: Create, edit, and analyze PowerPoint presentations with HTML conversion, XML manipulation, and design principles
+argument-hint: <operation> <presentation-file>
+---
+**Available Operations:**
+- `create` - Generate new presentation from scratch
+- `edit` - Modify existing presentation content
+- `analyze` - Extract and analyze content
+- `convert` - Transform between formats
+- `extract` - Get raw text or metadata
+## Text Extraction and Analysis
+### Convert to Markdown
+```bash
+# Convert presentation to markdown for text analysis
+python -m markitdown path-to-file.pptx
+```
+### Raw XML Access
+For comments, speaker notes, layouts, animations, and complex formatting:
+```bash
+# Unpack presentation to access raw XML
+python ooxml/scripts/unpack.py <presentation.pptx> <output_dir>
+```
+**Key XML Structure:**
+- `ppt/presentation.xml` - Main metadata and slide references
+- `ppt/slides/slide{N}.xml` - Individual slide contents
+- `ppt/notesSlides/notesSlide{N}.xml` - Speaker notes
+- `ppt/comments/modernComment_*.xml` - Slide comments
+- `ppt/slideLayouts/` - Layout templates
+- `ppt/slideMasters/` - Master slide templates
+- `ppt/theme/theme1.xml` - Theme and styling
+- `ppt/media/` - Images and media files
+## Creating New Presentations
+### Design-First Approach
+**CRITICAL:** Before creating any presentation:
+1. **Analyze content purpose** - What is this presentation about?
+2. **Check for branding** - Company/organization colors and identity
+3. **Match palette to content** - Select colors reflecting the subject
+4. **State your approach** - Explain design choices before implementation
+### Color Palette Selection
+**Creative color strategies:**
+- Think beyond defaults - match specific topic and mood
+- Consider industry, energy level, target audience
+- Try unexpected combinations - be adventurous
+- Build 3-5 color palettes (dominant + supporting + accent)
+- Ensure strong contrast for readability
+**Example Palettes:**
+1. **Classic Blue**: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
+2. **Teal & Coral**: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
+3. **Bold Red**: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
+4. **Warm Blush**: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
+5. **Burgundy Luxury**: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
+### Typography Standards
+**Web-safe fonts only:**
+- Arial, Helvetica, Times New Roman, Georgia
+- Courier New, Verdana, Tahoma, Trebuchet MS, Impact
+**Visual hierarchy principles:**
+- Clear size, weight, and color differentiation
+- Strong contrast for readability
+- Consistent spacing and alignment
+- Clean, professional appearance
+### HTML-to-PPTX Workflow
+For creating presentations from scratch, use html2pptx conversion:
+```python
+# Convert HTML slides to PowerPoint with accurate positioning
+from scripts.html2pptx import HTML2PPTX
+converter = HTML2PPTX()
+presentation = converter.convert_from_html('slides.html')
+presentation.save('output.pptx')
+```
+**HTML slide structure:**
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <style>
+        .slide {
+            width: 1920px;
+            height: 1080px;
+            padding: 60px;
+            font-family: Arial, sans-serif;
+        }
+        .title-slide { background: #1C2833; color: white; }
+        .content-slide { background: white; color: #2E4053; }
+        h1 { font-size: 48px; font-weight: bold; }
+        h2 { font-size: 36px; margin-bottom: 30px; }
+        p { font-size: 24px; line-height: 1.4; }
+    </style>
+</head>
+<body>
+    <div class="slide title-slide">
+        <h1>Presentation Title</h1>
+        <p>Subtitle</p>
+    </div>
+    <div class="slide content-slide">
+        <h2>Section Title</h2>
+        <p>Content paragraph</p>
+    </div>
+</body>
+</html>
+```
+## Editing Existing Presentations
+### Adding Content
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+from pptx.dml.color import RGBColor
+# Load existing presentation
+prs = Presentation('existing.pptx')
+# Add new slide
+slide_layout = prs.slide_layouts[1]  # Title and content layout
+slide = prs.slides.add_slide(slide_layout)
+# Add title
+title = slide.shapes.title
+title.text = "New Slide Title"
+# Add content
+content = slide.placeholders[1]
+content.text = "New slide content here"
+# Format text
+for paragraph in content.text_frame.paragraphs:
+    for run in paragraph.runs:
+        run.font.size = Pt(24)
+        run.font.color.rgb = RGBColor(46, 64, 83)  # Slate gray
+prs.save('updated.pptx')
+```
+### Modifying Layouts
+```python
+# Access slide layouts
+for layout in prs.slide_layouts:
+    print(f"Layout: {layout.name}")
+# Use specific layout
+bullet_slide_layout = prs.slide_layouts[1]
+slide = prs.slides.add_slide(bullet_slide_layout)
+```
+### Working with Images
+```python
+# Add image to slide
+slide = prs.slides.add_slide(prs.slide_layouts[6])  # Blank layout
+# Add image with specific position and size
+left = Inches(2)
+top = Inches(2)
+width = Inches(6)
+height = Inches(4)
+pic = slide.shapes.add_picture('image.jpg', left, top, width, height)
+```
+## Analyzing Presentation Content
+### Extract Theme Information
+```python
+import xml.etree.ElementTree as ET
+# Read theme file for colors and fonts
+tree = ET.parse('unpacked_ppt/ppt/theme/theme1.xml')
+root = tree.getroot()
+# Extract color scheme
+for color_scheme in root.findall('.//{http://schemas.openxmlformats.org/drawingml/2006/main}clrScheme'):
+    colors = {}
+    for color in color_scheme:
+        print(f"Color: {color.tag}")
+```
+### Typography Analysis
+```python
+# Analyze font usage across slides
+for slide_num in range(1, len(prs.slides) + 1):
+    slide_path = f'unpacked_ppt/ppt/slides/slide{slide_num}.xml'
+    if os.path.exists(slide_path):
+        tree = ET.parse(slide_path)
+        root = tree.getroot()
+        # Find font references
+        for font_ref in root.findall('.//{http://schemas.openxmlformats.org/drawingml/2006/main}rPr'):
+            font = font_ref.get('{http://schemas.openxmlformats.org/drawingml/2006/main}latin')
+            if font:
+                print(f"Slide {slide_num} font: {font.get('{http://schemas.openxmlformats.org/drawingml/2006/main}typeface')}")
+```
+## Advanced Features
+### Adding Speaker Notes
+```python
+# Access speaker notes
+notes_slide = prs.notes_slide
+text_frame = notes_slide.notes_text_frame
+text_frame.text = "Speaker notes for this slide"
+```
+### Comments and Annotations
+```python
+# Comments are stored in XML
+# Access via unpacked XML structure
+comments_path = 'unpacked_ppt/ppt/comments/modernComment_1.xml'
+# Process comment XML structure
+```
+### Working with Animations
+```python
+# Animations are complex XML structures
+# Access via unpacked presentation
+animation_path = 'unpacked_ppt/ppt/slides/slide1.xml'
+# Parse animation elements
+```
+## Quality Standards
+### Design Requirements
+- [ ] State content-informed design approach before coding
+- [ ] Use only web-safe fonts
+- [ ] Create clear visual hierarchy
+- [ ] Ensure strong contrast and readability
+- [ ] Maintain consistency across slides
+- [ ] Match colors to content and purpose
+### Content Structure
+- [ ] Clear slide titles and flow
+- [ ] Appropriate amount of text per slide
+- [ ] Logical information hierarchy
+- [ ] Consistent formatting throughout
+- [ ] Professional appearance
+## Usage Examples
+**Create new presentation:**
+`/pptx create "project-proposal.pptx"`
+**Analyze existing slide deck:**
+`/pptx analyze "quarterly-review.pptx"`
+**Extract text content:**
+`/pptx extract "presentation.pptx"`
+**Edit and modify:**
+`/pptx edit "template.pptx"`
+**Convert HTML to PowerPoint:**
+`/pptx convert "slides.html" "output.pptx"`
+Remember: Focus on content-driven design that enhances the message while maintaining professional appearance.

package/packages/{ampcode/skills/root-cause-tracing/SKILL.md → opencode/command/root-cause-tracing.md} RENAMED Viewed

@@ -1,39 +1,20 @@
 ---
-name: root-cause-tracing
-description: Use when errors occur deep in execution and you need to trace back to find the original trigger - systematically traces bugs backward through call stack, adding instrumentation when needed, to identify source of invalid data or incorrect behavior
+description: Systematically trace bugs backward through call stack to find original trigger, never just fix symptoms
+argument-hint: <error-or-bug-to-trace>
 ---
-# Root Cause Tracing
-## Overview
-Bugs often manifest deep in the call stack (git init in wrong directory, file created in wrong location, database opened with wrong path). Your instinct is to fix where the error appears, but that's treating a symptom.
 **Core principle:** Trace backward through the call chain until you find the original trigger, then fix at the source.
 ## When to Use
-```dot
-digraph when_to_use {
-    "Bug appears deep in stack?" [shape=diamond];
-    "Can trace backwards?" [shape=diamond];
-    "Fix at symptom point" [shape=box];
-    "Trace to original trigger" [shape=box];
-    "BETTER: Also add defense-in-depth" [shape=box];
-    "Bug appears deep in stack?" -> "Can trace backwards?" [label="yes"];
-    "Can trace backwards?" -> "Trace to original trigger" [label="yes"];
-    "Can trace backwards?" -> "Fix at symptom point" [label="no - dead end"];
-    "Trace to original trigger" -> "BETTER: Also add defense-in-depth";
-}
-```
 **Use when:**
 - Error happens deep in execution (not at entry point)
 - Stack trace shows long call chain
 - Unclear where invalid data originated
 - Need to find which test/code triggers the problem
+**Don't fix symptoms:** Find the root cause that created the conditions for the bug.
 ## The Tracing Process
 ### 1. Observe the Symptom
@@ -70,7 +51,7 @@ Project.create('name', context.tempDir); // Accessed before beforeEach!
 ## Adding Stack Traces
-When you can't trace manually, add instrumentation:
+When manual tracing isn't enough, add instrumentation:
 ```typescript
 // Before the problematic operation
@@ -94,22 +75,39 @@ async function gitInit(directory: string) {
 npm test 2>&1 | grep 'DEBUG git init'
 ```
-**Analyze stack traces:**
-- Look for test file names
-- Find the line number triggering the call
-- Identify the pattern (same test? same parameter?)
 ## Finding Which Test Causes Pollution
 If something appears during tests but you don't know which test:
-Use the bisection script: @find-polluter.sh
+**Use bisection approach:**
 ```bash
+# Run tests one by one until you find the polluter
 ./find-polluter.sh '.git' 'src/**/*.test.ts'
 ```
-Runs tests one-by-one, stops at first polluter. See script for usage.
+**Manual approach:**
+```bash
+# Add logging to find the culprit
+echo "DEBUG: About to run operation" >&2
+npm test 2>&1 | grep -A5 -B5 "DEBUG:"
+```
+## Key Principles
+### The Golden Rule
+```
+NEVER fix just where the error appears.
+Trace back to find the original trigger.
+```
+### Layered Defense
+```
+1. Find immediate cause
+2. Trace backward to source
+3. Fix at source
+4. Add validation at each layer
+5. Bug becomes impossible
+```
 ## Real Example: Empty projectDir
@@ -126,38 +124,12 @@ Runs tests one-by-one, stops at first polluter. See script for usage.
 **Fix:** Made tempDir a getter that throws if accessed before beforeEach
-**Also added defense-in-depth:**
+**Defense-in-depth added:**
 - Layer 1: Project.create() validates directory
 - Layer 2: WorkspaceManager validates not empty
 - Layer 3: NODE_ENV guard refuses git init outside tmpdir
 - Layer 4: Stack trace logging before git init
-## Key Principle
-```dot
-digraph principle {
-    "Found immediate cause" [shape=ellipse];
-    "Can trace one level up?" [shape=diamond];
-    "Trace backwards" [shape=box];
-    "Is this the source?" [shape=diamond];
-    "Fix at source" [shape=box];
-    "Add validation at each layer" [shape=box];
-    "Bug impossible" [shape=doublecircle];
-    "NEVER fix just the symptom" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
-    "Found immediate cause" -> "Can trace one level up?";
-    "Can trace one level up?" -> "Trace backwards" [label="yes"];
-    "Can trace one level up?" -> "NEVER fix just the symptom" [label="no"];
-    "Trace backwards" -> "Is this the source?";
-    "Is this the source?" -> "Trace backwards" [label="no - keeps going"];
-    "Is this the source?" -> "Fix at source" [label="yes"];
-    "Fix at source" -> "Add validation at each layer";
-    "Add validation at each layer" -> "Bug impossible";
-}
-```
-**NEVER fix just where the error appears.** Trace back to find the original trigger.
 ## Stack Trace Tips
 **In tests:** Use `console.error()` not logger - logger may be suppressed
@@ -165,10 +137,75 @@ digraph principle {
 **Include context:** Directory, cwd, environment variables, timestamps
 **Capture stack:** `new Error().stack` shows complete call chain
+## Common Tracing Patterns
+### Long Call Chains
+```typescript
+// Entry point
+await performOperation(input);
+// Deep in stack
+async function performOperation(input) {
+  await validateInput(input);     // Layer 1
+  await processData(input);       // Layer 2
+  await persistResults(input);    // Layer 3
+  await notifyCompletion(input);  // Layer 4 - ERROR HERE
+}
+// Trace backward:
+// notifyCompletion → persistResults → processData → validateInput → performOperation
+// Find where invalid input originated
+```
+### Data Flow Issues
+```typescript
+// Error: null pointer in deep function
+function deepFunction(obj) {
+  obj.property.method(); // obj is null
+}
+// Trace:
+// Where did obj come from?
+// What called deepFunction?
+// What should obj contain?
+// Where was it created/modified?
+```
+### Test Pollution
+```typescript
+// Side effect in one test affects others
+test('test A', () => {
+  createFile('test.txt'); // Leaves file behind
+});
+test('test B', () => {
+  readFile('test.txt'); // Fails because test A didn't clean up
+});
+// Use find-polluter.sh to identify test A
+```
+## Usage Examples
+**Complex error:**
+`/root-cause-tracing "database connection fails after API call"`
+**Test pollution:**
+`/root-cause-tracing "filesystem pollution during test suite"`
+**Deep stack error:**
+`/root-cause-tracing "TypeError in third-party library deep call chain"`
+**Data corruption:**
+`/root-cause-tracing "user data corrupted in final processing step"`
 ## Real-World Impact
-From debugging session (2025-10-03):
-- Found root cause through 5-level trace
-- Fixed at source (getter validation)
+**Benefits:**
+- Fixed root cause through 5-level trace
+- Fixed at source (getter validation)
 - Added 4 layers of defense
 - 1847 tests passed, zero pollution
+- Prevented future occurrences through validation
+Remember: Symptoms are clues, not the problem. Always trace backward to find and fix the source.

package/packages/opencode/command/skill-creator.md ADDED Viewed

@@ -0,0 +1,196 @@
+---
+description: Guide for creating effective skills that extend Claude's capabilities with specialized knowledge
+argument-hint: <skill-concept>
+---
+Create effective skills that extend Claude's capabilities with specialized knowledge, workflows, and tool integrations.
+## What Skills Provide
+1. **Specialized workflows** - Multi-step procedures for specific domains
+2. **Tool integrations** - Instructions for working with specific file formats or APIs
+3. **Domain expertise** - Company-specific knowledge, schemas, business logic
+4. **Bundled resources** - Scripts, references, and assets for complex tasks
+## Anatomy of a Skill
+```
+skill-name/
+├── SKILL.md (required)
+│   ├── YAML frontmatter metadata (required)
+│   │   ├── name: (required)
+│   │   └── description: (required)
+│   └── Markdown instructions (required)
+└── Bundled Resources (optional)
+    ├── scripts/          - Executable code (Python/Bash/etc.)
+    ├── references/       - Documentation for context loading
+    └── assets/           - Files used in output (templates, icons, fonts)
+```
+### SKILL.md Structure
+**YAML Frontmatter:**
+```yaml
+---
+name: skill-name
+description: This skill should be used when [specific use case]. [What it does].
+license: License information
+---
+```
+**Content Guidelines:**
+- Be specific about what the skill does and when to use it
+- Use third-person perspective ("This skill should be used when...")
+- Keep body under 5k words for context efficiency
+- Include concrete examples and patterns
+- Progressive disclosure: core info in SKILL.md, detailed info in references/
+### Bundled Resources
+#### Scripts (`scripts/`)
+- **Purpose:** Deterministic, reusable code that gets rewritten repeatedly
+- **When to include:** Same code patterns across projects, need reliability
+- **Examples:** PDF rotation, data transformation, file processing
+- **Benefits:** Token efficient, deterministic, executable without context loading
+#### References (`references/`)
+- **Purpose:** Documentation loaded as needed into context
+- **When to include:** Large documentation, schemas, API specs, company policies
+- **Best practices:**
+  - Keep SKILL.md lean (<5k words)
+  - Move detailed info to references files
+  - Use grep patterns for large files (>10k words)
+- **Examples:** Financial schemas, API documentation, domain knowledge
+#### Assets (`assets/`)
+- **Purpose:** Files used in output, not loaded into context
+- **When to include:** Templates, images, boilerplate code, fonts
+- **Examples:** HTML templates, PowerPoint slides, brand assets, sample documents
+- **Benefits:** Separates output resources from documentation
+## Skill Creation Process
+### Step 1: Understanding with Concrete Examples
+Understand concrete usage patterns before building:
+**Questions to ask:**
+- What functionality should this skill support?
+- Can you give examples of how this skill would be used?
+- What are the most common workflows?
+- What knowledge gaps exist that this skill should fill?
+**Validation:** Generate examples and validate with user feedback
+### Step 2: Define Scope and Boundaries
+**Scope definition:**
+- What is IN the skill's domain?
+- What is OUT of scope?
+- When should this skill trigger vs. other skills?
+**Naming guidelines:**
+- Use descriptive, domain-specific names
+- Avoid generic names ("file-handler" vs. "document-processor")
+- Consider workflow names users would recognize
+### Step 3: Structure the Knowledge
+**Progressive disclosure:**
+1. **Metadata** (100 words) - Always loaded
+2. **SKILL.md body** (<5k words) - When skill triggers
+3. **Bundled resources** (unlimited) - As needed
+**Content organization:**
+- Core procedural knowledge in SKILL.md
+- Detailed reference material in references/
+- Reusable code patterns in scripts/
+- Output templates in assets/
+### Step 4: Write Effective Instructions
+**Instruction quality:**
+- Clear, actionable steps
+- Concrete examples with actual code
+- Common patterns and anti-patterns
+- Edge cases and error handling
+- Integration points with other tools
+**Examples structure:**
+```markdown
+## Usage Examples
+**Basic usage:**
+`/skill-name input-file`
+**Advanced workflow:**
+`/skill-name complex-input --option value`
+**Common patterns:**
+```typescript
+// Example code showing the pattern
+```
+```
+### Step 5: Add Bundled Resources
+**Scripts inclusion criteria:**
+- Code rewritten repeatedly across projects
+- Deterministic operations requiring reliability
+- Complex multi-step workflows
+**References inclusion criteria:**
+- Documentation >10k words
+- Technical specifications and schemas
+- Company policies and procedures
+- API documentation and examples
+**Assets inclusion criteria:**
+- Templates used in output
+- Brand materials and styling
+- Boilerplate code structures
+- Sample documents for modification
+### Step 6: Test and Refine
+**Testing approach:**
+- Create example use cases
+- Validate with real scenarios
+- Check instruction clarity
+- Verify bundled resource integration
+**Quality checklist:**
+- [ ] Name and description are specific and accurate
+- [ ] Instructions are actionable and clear
+- [ ] Examples demonstrate real usage
+- [ ] Bundled resources are properly organized
+- [ ] Progressive disclosure works effectively
+## Best Practices
+**Do:**
+- Be specific about use cases and boundaries
+- Include concrete examples and patterns
+- Use progressive disclosure for complex topics
+- Bundle resources when reused across projects
+- Test with real scenarios
+**Don't:**
+- Make instructions too generic
+- Include everything in SKILL.md
+- Create skills for single-use cases
+- Over-bundle resources unnecessarily
+- Skip validation with actual examples
+## Usage Examples
+**Create new skill:**
+`/skill-creator "document processing skill for PDF forms"`
+**Improve existing skill:**
+`/skill-creator "enhance PDF processing with better error handling"`
+**Bundle resources:**
+`/skill-creator "create skill with scripts and reference docs"`
+Remember: Skills are "onboarding guides" for specialized domains—they should transform Claude from general-purpose to specialized expert.