@amrhas82/agentic-kit 1.2.1 → 1.7.0

package/packages/opencode/command/verification-before-completion.md

@@ -0,0 +1,151 @@
+---
+description: Evidence before claims - verify work completion with fresh verification commands
+argument-hint: <work-claiming-to-complete>
+---
+
+**Core principle:** Evidence before claims, always.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Claims & Verification
+
+| Claim | Requires Verification | Not Sufficient |
+|-------|----------------------|----------------|
+| Tests pass | `npm test` output: 0 failures | "Previously passed" |
+| Linter clean | ESLint output: 0 errors | "Should be clean" |
+| Build succeeds | Build command: exit 0 | "Linter passed" |
+| Bug fixed | Test original symptom: passes | "Code changed" |
+| Regression test works | Red-green cycle verified | "Test passes" |
+| Requirements met | Line-by-line checklist completion | "Tests pass" |
+
+## Key Verification Patterns
+
+### Test Verification
+```bash
+# ✅ CORRECT
+npm test
+# See: "34/34 tests passing"
+"All tests pass"
+
+# ❌ WRONG  
+"Should pass now"
+"Looks correct"
+```
+
+### Build Verification
+```bash
+# ✅ CORRECT  
+npm run build
+# See: exit code 0
+"Build succeeds"
+
+# ❌ WRONG
+"Looks good"  
+"Linter was clean"
+```
+
+### Bug Fix Verification
+```bash
+# ✅ CORRECT
+# Re-create original bug scenario
+# See: bug no longer occurs
+"Bug fixed: original error no longer reproduces"
+
+# ❌ WRONG
+"Made the changes"
+"Code looks right"
+```
+
+### Regression Test (TDD Red-Green)
+```bash
+# ✅ CORRECT
+# Step 1: Write failing test
+# Step 2: Run test (must fail)
+# Step 3: Write minimal fix
+# Step 4: Run test (must pass) 
+# Step 5: Revert fix → Run (must fail)
+# Step 6: Restore fix → Run (must pass)
+"Red-green cycle verified"
+```
+
+### Requirements Verification
+```bash
+# ✅ CORRECT
+# Re-read requirements
+# Create verification checklist
+# Check each requirement against implementation
+# Report completion or gaps
+
+"Requirements verification complete:"
+"✅ Feature A implemented"
+"✅ Feature B implemented"  
+"❌ Feature C incomplete"
+```
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- **ANY wording implying success without verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+
+## Usage Examples
+
+**Before claiming tests pass:**
+`/verification-before-completion "all unit tests passing"`
+
+**Before claiming build succeeds:**
+`/verification-before-completion "production build working"`
+
+**Before claiming bug fixed:**
+`/verification-before-completion "original error resolved"`
+
+**Before claiming requirements met:**
+`/verification-before-completion "feature specification fulfilled"`
+
+**Before committing code:**
+`/verification-before-completion "ready for commit"`
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This prevents false completion claims and maintains trust through evidence-based reporting.

package/packages/opencode/command/webapp-testing.md

@@ -0,0 +1,275 @@
+---
+description: Test local web applications using Playwright - verify functionality, debug UI, capture screenshots
+argument-hint: <webapp-url-or-local-server>
+---
+
+Test local web applications using native Python Playwright scripts with bundled helper utilities.
+
+## Available Operations
+
+- `static` - Test static HTML files
+- `dynamic` - Test dynamic web applications  
+- `debug` - Debug UI behavior and capture logs
+- `screenshot` - Capture browser screenshots
+- `server` - Manage server lifecycle for testing
+
+## Decision Tree
+
+```
+Task → Is it static HTML?
+    ├─ Yes → Read HTML file directly to identify selectors
+    │         ├─ Success → Write Playwright script using selectors
+    │         └─ Fails/Incomplete → Treat as dynamic (below)
+    │
+    └─ No (dynamic webapp) → Is the server already running?
+        ├─ No → Run: python scripts/with_server.py --help
+        │        Then use the helper + write simplified Playwright script
+        │
+        └─ Yes → Reconnaissance-then-action:
+            1. Navigate and wait for networkidle
+            2. Take screenshot or inspect DOM
+            3. Identify selectors from rendered state
+            4. Execute actions with discovered selectors
+```
+
+## Basic Playwright Setup
+
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=True)  # Always chromium in headless
+    page = browser.new_page()
+    page.goto('http://localhost:5173')  # Your local server
+    page.wait_for_load_state('networkidle')  # CRITICAL: Wait for JS execution
+    
+    # Your automation logic here
+    
+    browser.close()
+```
+
+## Server Management with with_server.py
+
+**Single server:**
+```bash
+python scripts/with_server.py \
+  --server "npm run dev" \
+  --port 5173 \
+  -- python your_automation.py
+```
+
+**Multiple servers (backend + frontend):**
+```bash
+python scripts/with_server.py \
+  --server "cd backend && python server.py" --port 3000 \
+  --server "cd frontend && npm run dev" --port 5173 \
+  -- python your_automation.py
+```
+
+**Always run `--help` first:**
+```bash
+python scripts/with_server.py --help
+```
+
+## Reconnaissance-Then-Action Pattern
+
+### 1. Inspect Rendered DOM
+```python
+# Take full page screenshot
+page.screenshot(path='/tmp/inspect.png', full_page=True)
+
+# Get page content
+content = page.content()
+
+# Discover all buttons, links, inputs
+page.locator('button').all()
+page.locator('a').all() 
+page.locator('input').all()
+```
+
+### 2. Identify Selectors
+Common selector strategies:
+- **Text-based**: `page.locator('text=Login')`
+- **Role-based**: `page.locator('role=button')`
+- **CSS selectors**: `page.locator('.button-primary')`
+- **IDs**: `page.locator('#submit-form')`
+
+### 3. Execute Actions
+```python
+# Click elements
+page.click('button:has-text("Submit")')
+
+# Fill forms
+page.fill('input[name="email"]', 'user@example.com')
+page.fill('input[type="password"]', 'password123')
+
+# Select from dropdown
+page.select_option('select[name="country"]', 'US')
+
+# Wait for elements
+page.wait_for_selector('.loading-spinner', state='hidden')
+```
+
+## Common Patterns
+
+### Form Interaction
+```python
+# Complete multi-step form
+page.goto('http://localhost:3000/form')
+page.wait_for_load_state('networkidle')
+
+# Fill form fields
+page.fill('input[name="firstName"]', 'John')
+page.fill('input[name="lastName"]', 'Doe')
+page.fill('input[name="email"]', 'john.doe@example.com')
+
+# Select dropdown
+page.select_option('select[name="country"]', 'United States')
+
+# Submit form
+page.click('button[type="submit"]')
+
+# Verify success
+page.wait_for_selector('.success-message')
+assert page.locator('.success-message').text_content() == 'Form submitted successfully!'
+```
+
+### Navigation Testing
+```python
+# Test navigation between pages
+page.click('a[href="/dashboard"]')
+page.wait_for_load_state('networkidle')
+
+# Verify URL changed
+assert page.url == 'http://localhost:3000/dashboard'
+
+# Check page content
+assert page.locator('h1:has-text("Dashboard")').is_visible()
+```
+
+### Data Loading and Waiting
+```python
+# Wait for data to load
+page.wait_for_selector('.data-table')
+page.wait_for_load_state('networkidle')
+
+# Check table content
+table = page.locator('.data-table')
+rows = table.locator('tbody tr')
+
+# Verify data loaded
+assert rows.count() > 0
+
+# Check specific data
+assert page.locator('text=John Doe').is_visible()
+```
+
+### Error Handling
+```python
+# Test error states
+page.goto('http://localhost:3000/invalid-page')
+page.wait_for_load_state('networkidle')
+
+# Check for error message
+error_message = page.locator('.error-message')
+assert error_message.is_visible()
+assert '404' in error_message.text_content()
+```
+
+## Debugging and Logging
+
+### Console Logs
+```python
+from playwright.sync_api import sync_playwright
+
+with sync_playwright() as p:
+    browser = p.chromium.launch(headless=False)  # Non-headless for debugging
+    page = browser.new_page()
+    
+    # Capture console messages
+    page.on('console', lambda msg: print(f'Browser console: {msg.text}'))
+    
+    # Capture JavaScript errors
+    page.on('pageerror', lambda error: print(f'Page error: {error}'))
+    
+    page.goto('http://localhost:5173')
+    browser.close()
+```
+
+### Screenshot Capture
+```python
+# Capture on failure
+try:
+    page.click('button')
+except Exception as e:
+    page.screenshot(path='/tmp/failure.png', full_page=True)
+    raise e
+
+# Full page screenshot
+page.screenshot(path='/tmp/full-page.png', full_page=True)
+
+# Element screenshot
+element = page.locator('.widget')
+element.screenshot(path='/tmp/widget.png')
+```
+
+## Best Practices
+
+### Critical Rules
+- **Always** wait for `networkidle` on dynamic apps before DOM inspection
+- Use `sync_playwright()` for synchronous scripts
+- Always close the browser when done
+- Use descriptive selectors (text, role, CSS, or IDs)
+- Add appropriate waits: `wait_for_selector()` or `wait_for_timeout()`
+
+### Performance Tips
+- Use headless mode for CI/automation: `headless=True`
+- Close unused pages to free memory
+- Use specific selectors over generic ones
+- Avoid unnecessary waits
+
+### Selector Strategy
+```python
+# Prefer these (most reliable):
+page.locator('text=Submit')           # Text content
+page.locator('role=button')           # ARIA role
+page.locator('#submit-form')          # ID
+page.locator('.button-primary')       # CSS class
+
+# Avoid these (less reliable):
+page.locator('button:nth-child(2)')   # Position-based
+page.locator('a[href*="login"]')      # Partial attribute match
+```
+
+## Reference Examples
+
+**Element Discovery:**
+```python
+# Find all interactive elements
+buttons = page.locator('button').all()
+for button in buttons:
+    print(f"Button: {button.text_content()}")
+```
+
+**Static HTML Testing:**
+```python
+# For local HTML files
+page.goto('file:///path/to/local/file.html')
+page.wait_for_load_state('networkidle')
+```
+
+## Usage Examples
+
+**Test React app:**
+`/webapp-testing "http://localhost:3000"`
+
+**Test with server management:**
+`/webapp-testing "npm run dev --port 3000"`
+
+**Debug UI issues:**
+`/webapp-testing "http://localhost:5173 --debug"`
+
+**Capture screenshots:**
+`/webapp-testing "http://localhost:3000 --screenshot"`
+
+Remember: Use bundled scripts as black boxes for complex workflows - they handle common patterns reliably.

package/packages/opencode/command/xlsx.md

@@ -0,0 +1,254 @@
+---
+description: Create, edit, and analyze spreadsheets with formulas, formatting, data analysis, and visualization
+argument-hint: <operation> <spreadsheet-file>
+---
+
+**Available Operations:**
+- `create` - Generate new spreadsheet with formulas
+- `read` - Analyze existing data
+- `edit` - Modify while preserving formulas
+- `analyze` - Data analysis and visualization
+- `recalc` - Recalculate all formulas
+
+## Core Requirements
+
+### Zero Formula Errors
+Every Excel file MUST be delivered with ZERO formula errors (#REF!, #DIV/0!, #VALUE!, #N/A, #NAME?)
+
+### Always Use Formulas, Not Hardcoded Values
+**❌ WRONG:** Calculate in Python and hardcode results
+```python
+# Bad: Hardcoding calculated values
+total = df['Sales'].sum()
+sheet['B10'] = total  # Hardcodes 5000
+
+# Bad: Computing in Python
+growth = (df.iloc[-1]['Revenue'] - df.iloc[0]['Revenue']) / df.iloc[0]['Revenue']  
+sheet['C5'] = growth  # Hardcodes 0.15
+```
+
+**✅ CORRECT:** Use Excel formulas
+```python
+# Good: Let Excel calculate the sum
+sheet['B10'] = '=SUM(B2:B9)'
+
+# Good: Growth rate as Excel formula
+sheet['C5'] = '=(C4-C2)/C2'
+```
+
+## Library Selection
+
+**pandas:** Best for data analysis, bulk operations, and simple export
+**openpyxl:** Best for complex formatting, formulas, and Excel-specific features
+
+## Reading and Analyzing Data
+
+### Data Analysis with pandas
+```python
+import pandas as pd
+
+# Read Excel
+df = pd.read_excel('file.xlsx')  # Default: first sheet
+all_sheets = pd.read_excel('file.xlsx', sheet_name=None)  # All sheets as dict
+
+# Analyze
+df.head()      # Preview data
+df.info()      # Column info  
+df.describe()  # Statistics
+df.isnull().sum()  # Missing values
+
+# Write Excel
+df.to_excel('output.xlsx', index=False)
+```
+
+### Advanced Data Operations
+```python
+# Specific columns and data types
+df = pd.read_excel('file.xlsx', usecols=['A', 'C', 'E'], dtype={'id': str})
+
+# Parse dates
+df = pd.read_excel('file.xlsx', parse_dates=['date_column'])
+
+# Handle large files
+df = pd.read_excel('large_file.xlsx', read_only=True)
+```
+
+## Creating New Excel Files
+
+### With openpyxl (Recommended for formulas)
+```python
+from openpyxl import Workbook
+from openpyxl.styles import Font, PatternFill, Alignment
+
+wb = Workbook()
+sheet = wb.active
+
+# Add data
+sheet['A1'] = 'Hello'
+sheet['B1'] = 'World'
+sheet.append(['Row', 'of', 'data'])
+
+# Add formula
+sheet['B2'] = '=SUM(A1:A10)'
+
+# Formatting
+sheet['A1'].font = Font(bold=True, color='FF0000')
+sheet['A1'].fill = PatternFill('solid', start_color='FFFF00')
+sheet['A1'].alignment = Alignment(horizontal='center')
+
+# Column width
+sheet.column_dimensions['A'].width = 20
+
+wb.save('output.xlsx')
+```
+
+## Editing Existing Files
+
+### Preserve Formulas and Formatting
+```python
+from openpyxl import load_workbook
+
+# Load existing file
+wb = load_workbook('existing.xlsx')
+sheet = wb.active  # or wb['SheetName']
+
+# Working with multiple sheets
+for sheet_name in wb.sheetnames:
+    sheet = wb[sheet_name]
+    print(f"Sheet: {sheet_name}")
+
+# Modify cells
+sheet['A1'] = 'New Value'
+sheet.insert_rows(2)  # Insert row at position 2
+sheet.delete_cols(3)  # Delete column 3
+
+# Add new sheet
+new_sheet = wb.create_sheet('NewSheet')
+new_sheet['A1'] = 'Data'
+
+wb.save('modified.xlsx')
+```
+
+## Financial Model Standards
+
+### Color Coding (Industry Standard)
+- **Blue text (RGB: 0,0,255)**: Hardcoded inputs
+- **Black text (RGB: 0,0,0)**: All formulas and calculations
+- **Green text (RGB: 0,128,0)**: Links to other worksheets
+- **Red text (RGB: 255,0,0)**: External links to other files
+- **Yellow background (RGB: 255,255,0)**: Key assumptions
+
+### Number Formatting
+- **Years**: Format as text strings ("2024" not "2,024")
+- **Currency**: Use $#,##0 format with units in headers
+- **Zeros**: Use number formatting to display as "-"
+- **Percentages**: Default to 0.0% format
+- **Multiples**: Format as 0.0x for ratios (EV/EBITDA, P/E)
+- **Negative numbers**: Use parentheses (123) not minus -123
+
+### Formula Construction
+```python
+# Place assumptions in separate cells
+sheet['B6'] = 0.05  # Growth rate assumption
+sheet['B5'] = 1000  # Base value
+
+# Use cell references in formulas
+sheet['B7'] = '=B5*(1+$B$6)'  # Calculates with assumption
+
+# Comment hardcoded values
+sheet['B8'] = 5000  # Revenue
+sheet['B8'].comment = 'Source: Company 10-K, FY2024, Page 45'
+```
+
+## Recalculating Formulas
+
+### Using recalc.py Script
+**MANDATORY:** Recalculate formulas after creating/modifying Excel files
+```bash
+python recalc.py output.xlsx
+```
+
+**With timeout:**
+```bash
+python recalc.py output.xlsx 30
+```
+
+### Understanding Output
+```json
+{
+  "status": "success",           // or "errors_found"
+  "total_errors": 0,              // Total error count
+  "total_formulas": 42,           // Number of formulas in file
+  "error_summary": {              // Only if errors found
+    "#REF!": {
+      "count": 2,
+      "locations": ["Sheet1!B5", "Sheet1!C10"]
+    }
+  }
+}
+```
+
+### Common Errors to Fix
+- **#REF!**: Invalid cell references
+- **#DIV/0!**: Division by zero  
+- **#VALUE!**: Wrong data type in formula
+- **#NAME?**: Unrecognized formula name
+
+## Formula Verification Checklist
+
+### Essential Checks
+- [ ] Test 2-3 sample references before building full model
+- [ ] Verify Excel columns match (column 64 = BL, not BK)
+- [ ] Remember Excel rows are 1-indexed (DataFrame row 5 = Excel row 6)
+- [ ] Check denominators before division operations
+- [ ] Test formulas with edge cases (zero, negative, large values)
+
+### Formula Testing Strategy
+```python
+# Test on sample data first
+sheet['A1'] = 100
+sheet['A2'] = 50
+sheet['A3'] = '=A1+A2'  # Should equal 150
+
+# Verify formula works before applying broadly
+for row in range(2, 100):
+    sheet[f'C{row}'] = f'=A{row}+B{row}'
+```
+
+## Best Practices
+
+### Library Usage
+**pandas:**
+- Specify data types: `dtype={'id': str}`
+- Read specific columns: `usecols=['A', 'C', 'E']`
+- For large files, use `read_only=True`
+
+**openpyxl:**
+- Use `data_only=True` to read calculated values
+- **Warning**: If opened with `data_only=True` and saved, formulas are replaced with values
+- Cell indices are 1-based (row=1, column=1 = cell A1)
+
+### Error Prevention
+- Check for NaN values with `pd.notna()`
+- Verify all cell references exist before using in formulas
+- Use correct cross-sheet reference format (Sheet1!A1)
+- Add comments for complex formulas and assumptions
+
+## Usage Examples
+
+**Create financial model:**
+`/xlsx create financial-model.xlsx`
+
+**Analyze existing data:**
+`/xlsx read sales-data.xlsx`
+
+**Edit while preserving formulas:**
+`/xlsx edit budget-template.xlsx`
+
+**Data analysis and visualization:**
+`/xlsx analyze quarterly-results.xlsx`
+
+**Recalculate formulas:**
+`/xlsx recalc updated-model.xlsx`
+
+Remember: The spreadsheet should be dynamic and recalculable when source data changes.