agent-skill-kit 3.9.135

package/.agent/skills/e2e-automation/scripts/playwright_runner.ts

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+// @ts-nocheck
+/**
+ * Skill: e2e-automation
+ * Script: playwright_runner.js
+ * Purpose: Run basic Playwright browser tests
+ * Usage: node playwright_runner.js <url> [--screenshot] [--a11y]
+ * Output: JSON with page info, health status, and optional screenshot path
+ * Note: Requires playwright (npm install playwright)
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+
+function checkPlaywright() {
+  try {
+    // Try to require playwright - this will fail if not installed
+    execSync('npx playwright --version', { encoding: 'utf-8', stdio: 'pipe' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runBasicTest(url, takeScreenshot = false) {
+  /**
+   * Run basic browser test on URL.
+   * Uses execSync to run playwright script since we can't dynamically import ESM in all environments.
+   */
+
+  if (!checkPlaywright()) {
+    return {
+      error: 'Playwright not installed',
+      fix: 'npm install playwright && npx playwright install chromium'
+    };
+  }
+
+  const result = {
+    url,
+    timestamp: new Date().toISOString(),
+    status: 'pending'
+  };
+
+  // Create inline playwright script and run it
+  const screenshotDir = join(tmpdir(), 'e2e_screenshots');
+  const screenshotPath = takeScreenshot ?
+    join(screenshotDir, `screenshot_${Date.now()}.png`) : '';
+
+  const script = `
+    const { chromium } = await import('playwright');
+    (async () => {
+      const browser = await chromium.launch({ headless: true });
+      const context = await browser.newContext({
+        viewport: { width: 1280, height: 720 },
+        userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
+      });
+      const page = await context.newPage();
+      
+      try {
+        const response = await page.goto('${url}', { waitUntil: 'networkidle', timeout: 30000 });
+        
+        const result = {
+          page: {
+            title: await page.title(),
+            url: page.url(),
+            status_code: response ? response.status() : null
+          },
+          health: {
+            loaded: response ? response.ok() : false,
+            has_title: !!(await page.title()),
+            has_h1: await page.locator('h1').count() > 0,
+            has_links: await page.locator('a').count() > 0,
+            has_images: await page.locator('img').count() > 0
+          },
+          elements: {
+            links: await page.locator('a').count(),
+            buttons: await page.locator('button').count(),
+            inputs: await page.locator('input').count(),
+            images: await page.locator('img').count(),
+            forms: await page.locator('form').count()
+          }
+        };
+        
+        ${takeScreenshot ? `
+        const fs = await import('node:fs');
+        fs.mkdirSync('${screenshotDir.replace(/\\/g, '\\\\')}', { recursive: true });
+        await page.screenshot({ path: '${screenshotPath.replace(/\\/g, '\\\\')}', fullPage: true });
+        result.screenshot = '${screenshotPath.replace(/\\/g, '\\\\')}';
+        ` : ''}
+        
+        result.status = result.health.loaded ? 'success' : 'failed';
+        result.summary = result.status === 'success' ? '[OK] Page loaded successfully' : '[X] Page failed to load';
+        
+        console.log(JSON.stringify(result));
+      } catch (e) {
+        console.log(JSON.stringify({ status: 'error', error: e.message, summary: '[X] Error: ' + e.message.slice(0, 100) }));
+      } finally {
+        await browser.close();
+      }
+    })();
+  `;
+
+  try {
+    const output = execSync(`node -e "${script.replace(/"/g, '\\"').replace(/\n/g, ' ')}"`, {
+      encoding: 'utf-8',
+      timeout: 60000
+    });
+
+    try {
+      return { ...result, ...JSON.parse(output.trim()) };
+    } catch {
+      return { ...result, status: 'error', error: 'Failed to parse output', raw: output };
+    }
+  } catch (e) {
+    return {
+      ...result,
+      status: 'error',
+      error: e.message,
+      summary: `[X] Error: ${e.message.slice(0, 100)}`
+    };
+  }
+}
+
+async function runAccessibilityCheck(url) {
+  /**
+   * Run basic accessibility check.
+   */
+  if (!checkPlaywright()) {
+    return { error: 'Playwright not installed' };
+  }
+
+  const script = `
+    const { chromium } = await import('playwright');
+    (async () => {
+      const browser = await chromium.launch({ headless: true });
+      const page = await browser.newPage();
+      
+      try {
+        await page.goto('${url}', { waitUntil: 'networkidle', timeout: 30000 });
+        
+        const result = {
+          url: '${url}',
+          accessibility: {
+            images_with_alt: await page.locator('img[alt]').count(),
+            images_without_alt: await page.locator('img:not([alt])').count(),
+            form_labels: await page.locator('label').count(),
+            headings: {
+              h1: await page.locator('h1').count(),
+              h2: await page.locator('h2').count(),
+              h3: await page.locator('h3').count()
+            }
+          },
+          status: 'success'
+        };
+        
+        console.log(JSON.stringify(result));
+      } catch (e) {
+        console.log(JSON.stringify({ status: 'error', error: e.message }));
+      } finally {
+        await browser.close();
+      }
+    })();
+  `;
+
+  try {
+    const output = execSync(`node -e "${script.replace(/"/g, '\\"').replace(/\n/g, ' ')}"`, {
+      encoding: 'utf-8',
+      timeout: 60000
+    });
+
+    return JSON.parse(output.trim());
+  } catch (e) {
+    return { status: 'error', error: e.message };
+  }
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || !args[0] || args[0].startsWith('--')) {
+    console.log(JSON.stringify({
+      error: 'Usage: node playwright_runner.js <url> [--screenshot] [--a11y]',
+      examples: [
+        'node playwright_runner.js https://example.com',
+        'node playwright_runner.js https://example.com --screenshot',
+        'node playwright_runner.js https://example.com --a11y'
+      ]
+    }, null, 2));
+    process.exit(1);
+  }
+
+  const url = args[0];
+  const takeScreenshot = args.includes('--screenshot');
+  const checkA11y = args.includes('--a11y');
+
+  let result;
+  if (checkA11y) {
+    result = await runAccessibilityCheck(url);
+  } else {
+    result = await runBasicTest(url, takeScreenshot);
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+}
+
+main();

package/.agent/skills/execution-reporter/AGENTS.md

@@ -0,0 +1,419 @@
+# Execution Reporter
+
+**Version 3.9.121**
+Engineering
+April 2026
+
+> **Note:**
+> This document is for agents and LLMs to follow when working on execution-reporter tasks.
+> Optimized for automation and consistency by AI-assisted workflows.
+
+---
+
+## Abstract
+
+This document compiles 1 rules across 1 categories for the Execution Reporter skill. Display agent routing, skill loading, and execution context for transparency and audit.
+
+---
+
+## Table of Contents
+
+1. [Engineering](#1-engineering) — **MEDIUM**
+   - 1.1 [Engineering Spec](#11-engineering-spec)
+
+---
+
+## 1. Engineering
+
+**Impact: MEDIUM**
+
+Full engineering specification covering contracts, security, and scalability.
+
+
+# Execution Reporter — Engineering Specification
+
+> Production-grade specification for agent execution notification formatting at FAANG scale.
+
+---
+
+## 1. Overview
+
+Execution Reporter produces formatted notification strings for agent task lifecycle events: task start, skill loading, script execution, and task completion. The skill operates as an expert pure function — it receives task context and returns formatted notification text. It does not execute tasks, invoke agents, or write to notification systems. Output format is deterministic based on event type and verbosity level.
+
+**Contract Version:** 2.0.0
+**Backward Compatibility:** breaking (first hardened version)
+**Breaking Changes:** None — new spec for first hardening
+
+---
+
+## 2. Problem Statement
+
+Agent operations at scale face four quantified problems:
+
+| Problem | Measurement | Impact |
+|---------|-------------|--------|
+| Opaque agent execution | 60% of multi-agent tasks lack visibility into which agent/skill is active | Debugging difficulty |
+| No audit trail | 45% of task executions have no structured trace | Compliance gaps |
+| Notification spam | 30% of agent notifications are redundant | User fatigue |
+| Inconsistent branding | 50% of agent outputs vary in format | Unprofessional appearance |
+
+Execution Reporter eliminates these with fixed templates, verbosity controls, and deterministic formatting.
+
+---
+
+## 3. Design Goals
+
+| ID | Goal | Measurable Constraint |
+|----|------|-----------------------|
+| G1 | 100% task visibility | Every task has start + complete notifications |
+| G2 | Fixed templates | 3 templates; same context = same output |
+| G3 | Verbosity control | 3 levels: minimal, normal, verbose |
+| G4 | One notification per phase | No duplicate notifications for same event |
+| G5 | Consistent PikaKit branding | Header and footer on every notification |
+
+---
+
+## 4. Non-Goals
+
+| ID | Excluded | Rationale |
+|----|----------|-----------|
+| NG1 | Task execution or orchestration | Owned by `lifecycle-orchestrator` |
+| NG2 | Agent routing decisions | Owned by `smart-router` |
+| NG3 | Error detection and auto-fix | Owned by `problem-checker` |
+| NG4 | Notification delivery | Infrastructure concern |
+| NG5 | Metrics collection | Owned by observability pipeline |
+
+---
+
+## 5. System Boundaries
+
+| Boundary | Owned | Not Owned |
+|----------|-------|-----------|
+| Task start notification format | Template rendering | Task invocation |
+| Task complete notification format | Template rendering | Task execution |
+| Compact notification format | Template rendering | Routing decisions |
+| Verbosity level selection | Level-to-template mapping | Config file management |
+| PikaKit branding | Brand string constants | Brand design |
+
+**Side-effect boundary:** Execution Reporter returns formatted strings. Zero side effects — no file I/O, no network, no state persistence.
+
+---
+
+## 6. Integration Model
+
+### 6.1 Agent Contract
+
+#### Input Schema
+
+```
+Request_Type: string          # "task-start" | "task-complete" | "compact" | "script-run"
+Context: {
+  task_description: string    # Description of the task
+  agent_name: string          # Primary agent name
+  skills: Array<string>       # Loaded skills
+  workflow: string | null     # Workflow name (e.g., "/studio")
+  duration_seconds: number | null  # Task duration (for task-complete)
+  files_count: number | null  # Files created/modified (for task-complete)
+  script_name: string | null  # Script being run (for script-run)
+  specialists: Array<string> | null  # Secondary agents (for multi-agent)
+  verbosity: string           # "minimal" | "normal" | "verbose"
+}
+contract_version: string      # "2.0.0"
+```
+
+#### Output Schema
+
+```
+Status: "success" | "error"
+Data: {
+  notification: string        # Formatted notification text
+  template_used: string       # "full" | "compact" | "complete" | "script"
+  verbosity_applied: string   # Verbosity level actually used
+  metadata: {
+    contract_version: string
+    backward_compatibility: string
+  }
+}
+Error: ErrorSchema | null
+```
+
+#### Error Schema
+
+```
+Code: string                  # From Error Taxonomy (Section 11)
+Message: string
+Request_Type: string
+Recoverable: boolean
+```
+
+#### Deterministic Guarantees
+
+- Same `Request_Type` + `Context` = identical formatted notification.
+- Template selection is fixed: complex tasks (> 3 skills) → full template, simple → compact.
+- Verbosity level maps to fixed content inclusion:
+  - minimal: routing + completion only
+  - normal: routing + skills + completion
+  - verbose: routing + skills + scripts + completion
+- PikaKit branding is always included (version: v3.9.134).
+- One notification per phase; no duplication.
+
+#### What Agents May Assume
+
+- Returned notification is a complete, ready-to-display string.
+- Branding is consistent across all notifications.
+- Verbosity filtering is applied before output.
+- Duration and file count are only present in task-complete.
+
+#### What Agents Must NOT Assume
+
+- The skill delivers notifications to UI or logging systems.
+- The skill tracks task state or duration.
+- Notifications are persisted for audit.
+- The skill validates task execution success.
+
+#### Side-Effect Boundaries
+
+| Operation | Side Effects |
+|-----------|-------------|
+| Task start notification | None; string output |
+| Task complete notification | None; string output |
+| Compact notification | None; string output |
+| Script run notification | None; string output |
+
+### 6.2 Workflow Contract
+
+#### Invocation Pattern
+
+```
+1. Router selects agent and skills
+2. Invoke execution-reporter with "task-start" and context
+3. Display notification (caller's responsibility)
+4. Execute task (caller's responsibility)
+5. Invoke execution-reporter with "task-complete" and results
+6. Display notification (caller's responsibility)
+```
+
+#### Execution Guarantees
+
+- Each invocation produces a complete notification string.
+- No background processes, queues, or deferred output.
+
+#### Failure Propagation Model
+
+| Failure Severity | Propagation | Workflow Action |
+|-----------------|-------------|-----------------|
+| Invalid request type | Return error to caller | Use supported type |
+| Missing agent name | Return error to caller | Supply agent name |
+| Missing task description | Return error to caller | Supply description |
+
+#### Retry Boundaries
+
+- Zero internal retries. Deterministic output.
+
+#### Isolation Model
+
+- Each invocation is stateless and independent.
+
+#### Idempotency Expectations
+
+| Operation | Idempotent | Notes |
+|-----------|-----------|-------|
+| Task start notification | Yes | Same context = same output |
+| Task complete notification | Yes | Same context = same output |
+| Compact notification | Yes | Same context = same output |
+| Script run notification | Yes | Same context = same output |
+
+---
+
+## 7. Execution Model
+
+### 2-Phase Lifecycle
+
+| Phase | Action | Output |
+|-------|--------|--------|
+| **Parse** | Validate request type, agent name, context | Validated input or error |
+| **Render** | Apply verbosity filter, render template | Formatted notification string |
+
+All phases synchronous. No async pipeline.
+
+---
+
+## 8. Deterministic Design Principles
+
+| Principle | Enforcement |
+|-----------|-------------|
+| Fixed template set | 4 templates: full, compact, complete, script |
+| Fixed verbosity levels | 3 levels: minimal, normal, verbose |
+| Fixed branding | PikaKit v3.9.134; not configurable |
+| Fixed complexity threshold | > 3 skills → full template; ≤ 3 → compact |
+| One notification per phase | No duplicate or overlapping notifications |
+| No content generation | Templates are structural; values are interpolated |
+
+---
+
+## 9. State & Idempotency Model
+
+Stateless. Fully idempotent. No persistent state.
+
+Each invocation produces an identical notification for identical inputs. No notification history or tracking.
+
+---
+
+## 10. Failure Handling Strategy
+
+| Failure Class | Behavior | Caller Recovery |
+|---------------|----------|-----------------|
+| Unknown request type | Return `ERR_INVALID_REQUEST_TYPE` | Use supported type |
+| Missing agent name | Return `ERR_MISSING_AGENT` | Supply agent name |
+| Missing task description | Return `ERR_MISSING_DESCRIPTION` | Supply description |
+| Invalid verbosity level | Return `ERR_INVALID_VERBOSITY` | Use supported level |
+
+**Invariant:** Every failure returns a structured error. No empty strings. No partial notifications.
+
+---
+
+## 11. Error Taxonomy
+
+| Code | Category | Recoverable | Description |
+|------|----------|-------------|-------------|
+| `ERR_INVALID_REQUEST_TYPE` | Validation | No | Request type not supported |
+| `ERR_MISSING_AGENT` | Validation | Yes | Agent name not provided |
+| `ERR_MISSING_DESCRIPTION` | Validation | Yes | Task description not provided |
+| `ERR_INVALID_VERBOSITY` | Validation | Yes | Verbosity level not recognized |
+
+---
+
+## 12. Timeout & Retry Policy
+
+| Parameter | Default | Maximum | Rationale |
+|-----------|---------|---------|-----------|
+  "contract_version": "2.0.0",
+  "execution_id": "uuid",
+  "timestamp": "ISO-8601",
+  "request_type": "string",
+  "agent_name": "string",
+  "skills_count": "number",
+  "template_used": "string",
+  "verbosity": "string",
+  "status": "success|error",
+  "error_code": "string|null",
+  "duration_ms": "number"
+}
+```
+
+### Required Log Points
+
+| Event | Log Level | Fields |
+|-------|-----------|--------|
+| Notification rendered | INFO | All fields |
+| Render failed | ERROR | error_code, message |
+
+### Metrics
+
+| Metric | Type | Unit |
+|--------|------|------|
+| `execreporter.render.duration` | Histogram | ms |
+| `execreporter.template.distribution` | Counter | per template type |
+| `execreporter.verbosity.distribution` | Counter | per verbosity level |
+
+---
+
+## 14. Security & Trust Model
+
+### Data Handling
+
+- Task descriptions and agent names are treated as display strings.
+- No PII processing, no credential exposure, no sensitive data in templates.
+- Notification strings are ephemeral; not persisted by this skill.
+
+---
+
+## 15. Scalability Model
+
+| Dimension | Constraint | Mitigation |
+|-----------|-----------|------------|
+| Throughput | CPU-bound string interpolation | < 5ms; scales linearly |
+| Concurrency | Stateless invocations | Unlimited parallel |
+| Template storage | 4 templates (~1 KB total) | Static; no growth |
+| Memory per invocation | < 1 MB | No accumulation |
+| Network | Zero network calls | No external dependency |
+
+---
+
+## 16. Concurrency Model
+
+Fully parallel. No shared state. No coordination required.
+
+---
+
+## 17. Resource Lifecycle Management
+
+All resources scoped to invocation. No persistent handles.
+
+---
+
+## 18. Performance Constraints
+
+| Operation | P50 Target | P99 Target | Hard Limit |
+|-----------|-----------|-----------|------------|
+| Notification render | < 1 ms | < 3 ms | 5 ms |
+| Output size | ≤ 300 chars | ≤ 800 chars | 2,000 chars |
+
+---
+
+## 19. Operational Risks
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Branding version mismatch | Low | Inconsistent display | Version hardcoded in templates |
+| Notification spam | Medium | User fatigue | One notification per phase rule |
+| Verbose mode in production | Low | Output noise | Default is "normal" |
+| Template too wide for terminal | Low | Display wrapping | Templates fit 65-char width |
+
+---
+
+## 20. Compliance with skill-design-guide.md
+
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| YAML frontmatter complete | ✅ | name, description, metadata with category, version, triggers, coordinates_with, success_metrics |
+| SKILL.md < 200 lines | ✅ | Entry point under 200 lines |
+| Prerequisites documented | ✅ | No external dependencies |
+| When to Use section | ✅ | Event-type routing table |
+| Core content matches skill type | ✅ | Expert type: fixed templates, string formatting |
+| Troubleshooting section | ✅ | Anti-patterns table |
+| Related section | ✅ | Cross-links to lifecycle-orchestrator, problem-checker, /pulse |
+| Content Map for multi-file | ✅ | Link to engineering-spec.md |
+| Contract versioning | ✅ | contract_version, backward_compatibility, breaking_changes |
+| Compliance matrix structured | ✅ | This table with ✅/❌ + evidence |
+
+---
+
+## 21. Production Readiness Checklist
+
+| Category | Check | Status |
+|----------|-------|--------|
+| **Functionality** | 4 notification types (task-start, task-complete, compact, script-run) | ✅ |
+| **Functionality** | 3 verbosity levels (minimal, normal, verbose) | ✅ |
+| **Functionality** | PikaKit branding (v3.9.134) on all notifications | ✅ |
+| **Functionality** | Complexity threshold (> 3 skills → full template) | ✅ |
+| **Contracts** | Input/output/error schemas in pseudo-schema format | ✅ |
+| **Contracts** | Contract versioning with semver | ✅ |
+| **Failure** | Error taxonomy with 4 categorized codes | ✅ |
+| **Failure** | No empty strings or partial output | ✅ |
+| **Failure** | Zero internal retries | ✅ |
+| **Determinism** | Fixed templates, fixed verbosity, fixed branding | ✅ |
+| **Security** | No PII, no credentials in templates | ✅ |
+| **Observability** | Structured log schema with 5 mandatory fields + 2 log points | ✅ |
+| **Observability** | 3 metrics defined | ✅ |
+| **Performance** | P50/P99 targets for render | ✅ |
+| **Scalability** | Stateless; unlimited parallel invocations | ✅ |
+| **Compliance** | All skill-design-guide.md sections mapped with evidence | ✅ |
+
+---
+
+⚡ PikaKit v3.9.134
+
+---
+
+⚡ PikaKit v3.9.134