@amrhas82/agentic-kit 1.2.1 → 1.5.0

package/packages/opencode/command/canvas-design.md

@@ -0,0 +1,155 @@
+---
+description: Create beautiful visual art in PNG and PDF documents using design philosophy and minimal text
+argument-hint: <visual-concept> <output-format>
+---
+
+Create original visual designs through design philosophies expressed visually, not through text-heavy layouts.
+
+## Two-Phase Process
+
+### Phase 1: Design Philosophy Creation
+Create a visual philosophy (4-6 paragraphs) that guides the aesthetic:
+
+**Name the movement** (1-2 words): "Brutalist Joy" / "Chromatic Silence" / "Metabolist Dreams"
+
+**Articulate the philosophy** expressing how it manifests through:
+- Space and form
+- Color and material
+- Scale and rhythm
+- Composition and balance
+- Visual hierarchy
+
+**Critical principles:**
+- **Emphasize craftsmanship** - Work should appear meticulously crafted by a master
+- **Minimal text** - Text as rare, powerful gesture, never explanatory blocks
+- **Spatial expression** - Ideas communicate through form, color, composition
+- **Artistic freedom** - Provide interpretive room for visual execution
+- **Pure design** - Create art objects, not documents with decoration
+
+### Phase 2: Canvas Creation
+Express the philosophy visually using design tools, creating .png or .pdf outputs.
+
+## Design Philosophy Examples
+
+### "Concrete Poetry"
+**Philosophy:** Communication through monumental form and bold geometry.
+**Visual expression:** Massive color blocks, sculptural typography (huge single words, tiny labels), Brutalist spatial divisions. Ideas expressed through visual weight and spatial tension, not explanation. Text as rare, powerful gesture - never paragraphs, only essential words integrated into the visual architecture. Every element placed with the precision of a master craftsman.
+
+### "Chromatic Language"  
+**Philosophy:** Color as the primary information system.
+**Visual expression:** Geometric precision where color zones create meaning. Typography minimal - small sans-serif labels letting chromatic fields communicate. Think Josef Albers' interaction meets data visualization. Information encoded spatially and chromatically. Words only to anchor what color already shows. The result of painstaking chromatic calibration.
+
+### "Analog Meditation"
+**Philosophy:** Quiet visual contemplation through texture and breathing room.
+**Visual expression:** Paper grain, ink bleeds, vast negative space. Photography and illustration dominate. Typography whispered (small, restrained, serving the visual). Japanese photobook aesthetic. Images breathe across pages. Text appears sparingly - short phrases, never explanatory blocks. Each composition balanced with the care of a meditation practice.
+
+### "Organic Systems"
+**Philosophy:** Natural clustering and modular growth patterns.
+**Visual expression:** Rounded forms, organic arrangements, color from nature through architecture. Information shown through visual diagrams, spatial relationships, iconography. Text only for key labels floating in space. The composition tells the story through expert spatial orchestration.
+
+### "Geometric Silence"
+**Philosophy:** Pure order and restraint.
+**Visual expression:** Grid-based precision, bold photography or stark graphics, dramatic negative space. Typography precise but minimal - small essential text, large quiet zones. Swiss formalism meets Brutalist material honesty. Structure communicates, not words. Every alignment the work of countless refinements.
+
+## Visual Design Principles
+
+### Color Strategy
+- **Palette selection** based on philosophy (warm/cool, high/low contrast)
+- **Color relationships** (complementary, analogous, triadic)
+- **Tone and mood** matching the conceptual intent
+- **Minimal color** with maximum impact
+
+### Typography Hierarchy
+- **Scale relationships** (large headers, small captions)
+- **Font pairing** (serif/sans-serif, weight contrasts)
+- **Text as visual element** integrated into composition
+- **Rare, essential text** - never explanatory paragraphs
+
+### Spatial Composition
+- **Balance and symmetry** or intentional asymmetry
+- **Negative space** as active design element
+- **Scale relationships** between elements
+- **Visual flow** guiding viewer's eye
+
+### Form and Shape
+- **Geometric vs organic** forms matching philosophy
+- **Repetition and pattern** creating rhythm
+- **Contrast and harmony** in shapes
+- **Structural elements** supporting composition
+
+## Canvas Creation Techniques
+
+### Layout Approaches
+```python
+# Grid-based layout
+- Divide canvas into sections
+- Use mathematical proportions (golden ratio, thirds)
+- Create visual hierarchy through placement
+
+# Organic layout  
+- Flowing, curved compositions
+- Natural clustering of elements
+- Asymmetrical balance
+```
+
+### Visual Elements
+- **Photography** with artistic treatment
+- **Illustrations** (vector or raster)
+- **Geometric shapes** and patterns
+- **Texture and material** effects
+- **Color fields** and gradients
+
+### Text Integration
+- **Essential labels** only
+- **Visual typography** as design element
+- **Scale contrast** (large impact words, small details)
+- **Minimal copy** supporting visual message
+
+## Quality Standards
+
+### Design Execution
+- **Professional finish** - no amateur elements
+- **Consistent style** throughout composition
+- **Technical precision** in alignment and proportions
+- **Original concepts** avoiding clichés
+
+### Visual Hierarchy
+- **Clear focal points** - viewer knows where to look first
+- **Supporting elements** in proper scale relationships
+- **Flow and rhythm** through the composition
+- **Coherent color scheme** reinforcing the concept
+
+### Craftsmanship
+- **Attention to detail** in every element
+- **Refined execution** showing professional skill
+- **Conceptual clarity** expressing the philosophy
+- **Emotional impact** through visual choices
+
+## Usage Examples
+
+**Create poster art:**
+`/canvas-design "jazz concert poster" "png"`
+
+**Design magazine layout:**
+`/canvas-design "architectural review spread" "pdf"`
+
+**Generate brand visual:**
+`/canvas-design "tech startup identity" "png"`
+
+**Design book cover:**
+`/canvas-design "literary fiction novel" "pdf"`
+
+**Create artwork series:**
+`/canvas-design "urban landscapes" "png"`
+
+## Deduced Conceptual Thread
+
+**Critical step:** Identify the subtle conceptual reference within the art itself - a sophisticated, niche element that enhances depth without announcing itself. Someone familiar with the subject should feel it intuitively, while others experience masterful abstract composition.
+
+**Examples:**
+- Jazz influences in geometric compositions
+- Architectural references in spatial layouts  
+- Literary themes in typographic treatments
+- Musical rhythm in visual patterns
+
+Remember: Focus on visual expression through form, space, color, and composition - minimal text, maximum design impact.

package/packages/opencode/command/code-review.md

@@ -0,0 +1,92 @@
+---
+description: Request structured code review to catch issues before they cascade
+argument-hint: <branch-or-pr-name>
+---
+
+Dispatch structured code review to catch issues before they cascade.
+
+**Core principle:** Review early, review often.
+
+## When to Request Review
+
+**Mandatory:**
+- After each task in subagent-driven development
+- After completing major feature
+- Before merge to main
+
+**Optional but valuable:**
+- When stuck (fresh perspective)
+- Before refactoring (baseline check)
+- After fixing complex bug
+
+## How to Request
+
+**1. Get git SHAs:**
+```bash
+BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+**2. Review scope:** $ARGUMENTS
+
+**3. Key areas to focus on:**
+
+**Summary & Purpose:**
+- What changed and why it matters
+- Is the implementation aligned with the requirements
+
+**Correctness & Quality:**
+- Logic errors and edge cases
+- Test coverage and test quality
+- Code readability and maintainability
+
+**Risks & Concerns:**
+- Security implications
+- Performance bottlenecks
+- Breaking changes or migration issues
+- Dependency risks
+
+**Architecture & Design:**
+- Code organization and structure
+- Separation of concerns
+- Reusability and extensibility
+- API design consistency
+
+**Follow-up Actions:**
+- Concrete TODOs with owners
+- Priority levels (Critical/Important/Minor)
+- Testing requirements
+
+## Act on feedback:
+- Fix Critical issues immediately
+- Fix Important issues before proceeding
+- Note Minor issues for later
+- Push back if reviewer is wrong (with reasoning)
+
+## Integration with Workflows
+
+**Subagent-Driven Development:**
+- Review after EACH task
+- Catch issues before they compound
+- Fix before moving to next task
+
+**Executing Plans:**
+- Review after each batch (3 tasks)
+- Get feedback, apply, continue
+
+**Ad-Hoc Development:**
+- Review before merge
+- Review when stuck
+
+## Red Flags
+
+**Never:**
+- Skip review because "it's simple"
+- Ignore Critical issues
+- Proceed with unfixed Important issues
+- Argue with valid technical feedback
+
+**If reviewer wrong:**
+- Push back with technical reasoning
+- Show code/tests that prove it works
+- Request clarification

package/packages/{ampcode/skills/condition-based-waiting/SKILL.md → opencode/command/condition-based-waiting.md}

@@ -1,31 +1,12 @@
 ---
-name: condition-based-waiting
-description: Use when tests have race conditions, timing dependencies, or inconsistent pass/fail behavior - replaces arbitrary timeouts with condition polling to wait for actual state changes, eliminating flaky tests from timing guesses
+description: Replace arbitrary timeouts with condition polling to eliminate flaky tests from timing guesses
+argument-hint: <condition-to-wait-for>
 ---
 
-# Condition-Based Waiting
-
-## Overview
-
-Flaky tests often guess at timing with arbitrary delays. This creates race conditions where tests pass on fast machines but fail under load or in CI.
-
 **Core principle:** Wait for the actual condition you care about, not a guess about how long it takes.
 
 ## When to Use
 
-```dot
-digraph when_to_use {
-    "Test uses setTimeout/sleep?" [shape=diamond];
-    "Testing timing behavior?" [shape=diamond];
-    "Document WHY timeout needed" [shape=box];
-    "Use condition-based waiting" [shape=box];
-
-    "Test uses setTimeout/sleep?" -> "Testing timing behavior?" [label="yes"];
-    "Testing timing behavior?" -> "Document WHY timeout needed" [label="yes"];
-    "Testing timing behavior?" -> "Use condition-based waiting" [label="no"];
-}
-```
-
 **Use when:**
 - Tests have arbitrary delays (`setTimeout`, `sleep`, `time.sleep()`)
 - Tests are flaky (pass sometimes, fail under load)
@@ -36,7 +17,9 @@ digraph when_to_use {
 - Testing actual timing behavior (debounce, throttle intervals)
 - Always document WHY if using arbitrary timeout
 
-## Core Pattern
+## Quick Patterns
+
+Replace timing guesses with condition polling:
 
 ```typescript
 // ❌ BEFORE: Guessing at timing
@@ -44,25 +27,21 @@ await new Promise(r => setTimeout(r, 50));
 const result = getResult();
 expect(result).toBeDefined();
 
-// ✅ AFTER: Waiting for condition
+// ✅ AFTER: Waiting for condition  
 await waitFor(() => getResult() !== undefined);
 const result = getResult();
 expect(result).toBeDefined();
 ```
 
-## Quick Patterns
-
-| Scenario | Pattern |
-|----------|---------|
-| Wait for event | `waitFor(() => events.find(e => e.type === 'DONE'))` |
-| Wait for state | `waitFor(() => machine.state === 'ready')` |
-| Wait for count | `waitFor(() => items.length >= 5)` |
-| Wait for file | `waitFor(() => fs.existsSync(path))` |
-| Complex condition | `waitFor(() => obj.ready && obj.value > 10)` |
+**Common scenarios:**
+- Wait for event: `waitFor(() => events.find(e => e.type === 'DONE'))`
+- Wait for state: `waitFor(() => machine.state === 'ready')`
+- Wait for count: `waitFor(() => items.length >= 5)`
+- Wait for file: `waitFor(() => fs.existsSync(path))`
+- Complex condition: `waitFor(() => obj.ready && obj.value > 10)`
 
 ## Implementation
 
-Generic polling function:
 ```typescript
 async function waitFor<T>(
   condition: () => T | undefined | null | false,
@@ -82,11 +61,31 @@ async function waitFor<T>(
     await new Promise(r => setTimeout(r, 10)); // Poll every 10ms
   }
 }
-```
 
-See @example.ts for complete implementation with domain-specific helpers (`waitForEvent`, `waitForEventCount`, `waitForEventMatch`) from actual debugging session.
+// Domain-specific helpers
+async function waitForEvent(eventManager: any, eventType: string) {
+  return waitFor(() => 
+    eventManager.events.find((e: any) => e.type === eventType),
+    `event ${eventType}`
+  );
+}
+
+async function waitForEventCount(eventManager: any, eventType: string, count: number) {
+  return waitFor(() => 
+    eventManager.events.filter((e: any) => e.type === eventType).length >= count,
+    `${count} events of type ${eventType}`
+  );
+}
+
+async function waitForEventMatch(eventManager: any, eventType: string, matcher: any) {
+  return waitFor(() => 
+    eventManager.events.find((e: any) => e.type === eventType && matcher(e)),
+    `event ${eventType} matching criteria`
+  );
+}
+```
 
-## Common Mistakes
+## Common Mistakes to Avoid
 
 **❌ Polling too fast:** `setTimeout(check, 1)` - wastes CPU
 **✅ Fix:** Poll every 10ms
@@ -113,8 +112,22 @@ await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
 
 ## Real-World Impact
 
-From debugging session (2025-10-03):
-- Fixed 15 flaky tests across 3 files
+**Benefits:**
+- Fixed 15 flaky tests across multiple files
 - Pass rate: 60% → 100%
-- Execution time: 40% faster
+- Execution time: 40% faster  
 - No more race conditions
+
+## Usage Examples
+
+**Wait for async operation:**
+`/condition-based-waiting "database connection established"`
+
+**Wait for UI state:**
+`/condition-based-waiting "login button enabled"`
+
+**Wait for file changes:**
+`/condition-based-waiting "build output file created"`
+
+**Complex condition:**
+`/condition-based-waiting "user authenticated AND profile loaded"`

package/packages/opencode/command/docx.md

@@ -0,0 +1,255 @@
+---
+description: Create, edit, and manipulate Word documents with JavaScript library and XML manipulation
+argument-hint: <operation> <document>
+---
+
+**Available Operations:**
+- `create` - Generate new Word document
+- `edit` - Modify existing document  
+- `comments` - Add/manage document comments
+- `track-changes` - Implement tracked changes
+- `extract` - Extract content from document
+- `convert` - Convert between formats
+
+## JavaScript/Node.js Library (Recommended)
+
+### Setup
+```javascript
+const { Document, Packer, Paragraph, TextRun, Table, ImageRun, 
+        Header, Footer, AlignmentType, PageOrientation } = require('docx');
+
+// Create & Save
+const doc = new Document({ sections: [{ children: [] }] });
+Packer.toBuffer(doc).then(buffer => fs.writeFileSync("output.docx", buffer));
+```
+
+### Text & Formatting
+**CRITICAL:** Never use `\n` for line breaks - always use separate Paragraph elements
+```javascript
+// ✅ CORRECT
+new Paragraph({ children: [new TextRun("Line 1")] }),
+new Paragraph({ children: [new TextRun("Line 2")] })
+
+// Basic formatting
+new Paragraph({
+  alignment: AlignmentType.CENTER,
+  spacing: { before: 200, after: 200 },
+  children: [
+    new TextRun({ text: "Bold", bold: true }),
+    new TextRun({ text: "Italic", italics: true }),
+    new TextRun({ text: "Underlined", underline: { type: "double" } }),
+    new TextRun({ text: "Colored", color: "FF0000", size: 28 }),
+    new TextRun({ text: "Highlighted", highlight: "yellow" }),
+    new TextRun({ text: "Strikethrough", strike: true })
+  ]
+})
+```
+
+### Tables
+```javascript
+const table = new Table({
+  width: {
+    size: 100,
+    type: WidthType.PERCENTAGE
+  },
+  rows: [
+    new TableRow({
+      children: [
+        new TableCell({ children: [new Paragraph("Header 1")] }),
+        new TableCell({ children: [new Paragraph("Header 2")] })
+      ]
+    }),
+    new TableRow({
+      children: [
+        new TableCell({ children: [new Paragraph("Cell 1")] }),
+        new TableCell({ children: [new Paragraph("Cell 2")] })
+      ]
+    })
+  ]
+});
+```
+
+### Headers & Footers
+```javascript
+const doc = new Document({
+  sections: [{
+    headers: {
+      default: new Header({
+        children: [new Paragraph("Document Title")]
+      })
+    },
+    footers: {
+      default: new Footer({
+        children: [new Paragraph("Page ")]
+      })
+    },
+    children: []
+  }]
+});
+```
+
+### Images
+```javascript
+const image = fs.readFileSync("image.jpg");
+const doc = new Document({
+  sections: [{
+    children: [
+      new Paragraph({
+        children: [
+          new ImageRun({
+            data: image,
+            transformation: {
+              width: 300,
+              height: 200
+            }
+          })
+        ]
+      })
+    ]
+  }]
+});
+```
+
+## Raw XML Manipulation
+
+### Basic Structure
+```xml
+<w:p>
+  <w:r><w:t>Text content</w:t></w:r>
+</w:p>
+```
+
+### Headings & Styles
+```xml
+<w:p>
+  <w:pPr>
+    <w:pStyle w:val="Title"/>
+    <w:jc w:val="center"/>
+  </w:pPr>
+  <w:r><w:t>Document Title</w:t></w:r>
+</w:p>
+
+<w:p>
+  <w:pPr><w:pStyle w:val="Heading2"/></w:pPr>
+  <w:r><w:t>Section Heading</w:t></w:r>
+</w:p>
+```
+
+### Text Formatting (XML)
+```xml
+<!-- Bold -->
+<w:r><w:rPr><w:b/><w:bCs/></w:rPr><w:t>Bold</w:t></w:r>
+
+<!-- Italic -->
+<w:r><w:rPr><w:i/><w:iCs/></w:rPr><w:t>Italic</w:t></w:r>
+
+<!-- Colors -->
+<w:r><w:rPr><w:color w:val="FF0000"/></w:rPr><w:t>Red Text</w:t></w:r>
+
+<!-- Multiple formatting -->
+<w:r>
+  <w:rPr>
+    <w:b/><w:i/><w:color w:val="0000FF"/>
+    <w:sz w:val="28"/><w:szCs w:val="28"/>
+  </w:rPr>
+  <w:t>Bold, italic, blue text</w:t>
+</w:r>
+```
+
+## Python Document Library
+
+### Basic Document Operations
+```python
+from skills.docx.scripts.document import Document
+
+# Initialize
+doc = Document('workspace/unpacked')
+doc = Document('workspace/unpacked', author="John Doe", initials="JD")
+
+# Find nodes
+node = doc["word/document.xml"].get_node(tag="w:del", attrs={"w:id": "1"})
+node = doc["word/document.xml"].get_node(tag="w:p", line_number=10)
+
+# Add comments
+doc.add_comment(start=node, end=node, text="Comment text")
+doc.reply_to_comment(parent_comment_id=0, text="Reply text")
+
+# Track changes
+doc["word/document.xml"].suggest_deletion(node)  # Delete content
+doc["word/document.xml"].revert_insertion(ins_node)  # Reject insertion
+doc["word/document.xml"].revert_deletion(del_node)  # Reject deletion
+
+# Save
+doc.save()
+```
+
+## Document Comments
+
+### XML Pattern
+```xml
+<w:commentRangeStart w:id="0"/>
+<w:r><w:t>Commented text</w:t></w:r>
+<w:commentRangeEnd w:id="0"/>
+
+<w:comment w:id="0" w:author="Author" w:date="2024-01-01T10:00:00Z">
+  <w:p>
+    <w:r><w:t>Comment text</w:t></w:r>
+  </w:p>
+</w:comment>
+```
+
+## Tracked Changes (Redlining)
+
+### Insertions
+```xml
+<w:ins w:author="Author" w:date="2024-01-01T10:00:00Z" w:id="1">
+  <w:r><w:t>Inserted text</w:t></w:r>
+</w:ins>
+```
+
+### Deletions
+```xml
+<w:del w:author="Author" w:date="2024-01-01T10:00:00Z" w:id="1">
+  <w:r><w:t>Deleted text</w:t></w:r>
+</w:del>
+```
+
+## Best Practices
+
+### Character Encoding
+- Escape special characters: `"` → `“`, `'` → `’`
+- Use `xml:space='preserve'` for leading/trailing spaces
+- RSIDs must be 8-digit hex values
+
+### Schema Compliance
+- Element ordering: `<w:pStyle>`, `<w:numPr>`, `<w:spacing>`, `<w:ind>`, `<w:jc>`
+- Track revisions placement: Add `<w:trackRevisions/>` after `<w:proofState>`
+
+### Images
+- Add to `word/media/` directory
+- Reference in `document.xml`
+- Set dimensions to prevent overflow
+
+## Usage Examples
+
+**Create simple document:**
+`/docx create report.docx`
+
+**Add comments to existing:**
+`/docx comments document.docx`
+
+**Implement tracked changes:**
+`/docx track-changes draft.docx`
+
+**Extract content:**
+`/docx extract source.docx output.txt`
+
+**Convert between formats:**
+`/docx convert input.html output.docx`
+
+## Validation
+
+For production documents, validate against Office Open XML schemas:
+- Use the OOXML validation scripts in the ooxml/ directory
+- Check for schema compliance and redlining patterns
+- Verify character encoding and XML structure