@bastani/atomic 0.7.17 → 0.8.0-0

package/dist/builtin/workflows/skills/playwright-cli/references/tracing.md

@@ -0,0 +1,139 @@
+# Tracing
+
+Capture detailed execution traces for debugging and analysis. Traces include DOM snapshots, screenshots, network activity, and console logs.
+
+## Basic Usage
+
+```bash
+# Start trace recording
+playwright-cli tracing-start
+
+# Perform actions
+playwright-cli open https://example.com
+playwright-cli click e1
+playwright-cli fill e2 "test"
+
+# Stop trace recording
+playwright-cli tracing-stop
+```
+
+## Trace Output Files
+
+When you start tracing, Playwright creates a `traces/` directory with several files:
+
+### `trace-{timestamp}.trace`
+
+**Action log** - The main trace file containing:
+- Every action performed (clicks, fills, navigations)
+- DOM snapshots before and after each action
+- Screenshots at each step
+- Timing information
+- Console messages
+- Source locations
+
+### `trace-{timestamp}.network`
+
+**Network log** - Complete network activity:
+- All HTTP requests and responses
+- Request headers and bodies
+- Response headers and bodies
+- Timing (DNS, connect, TLS, TTFB, download)
+- Resource sizes
+- Failed requests and errors
+
+### `resources/`
+
+**Resources directory** - Cached resources:
+- Images, fonts, stylesheets, scripts
+- Response bodies for replay
+- Assets needed to reconstruct page state
+
+## What Traces Capture
+
+| Category | Details |
+|----------|---------|
+| **Actions** | Clicks, fills, hovers, keyboard input, navigations |
+| **DOM** | Full DOM snapshot before/after each action |
+| **Screenshots** | Visual state at each step |
+| **Network** | All requests, responses, headers, bodies, timing |
+| **Console** | All console.log, warn, error messages |
+| **Timing** | Precise timing for each operation |
+
+## Use Cases
+
+### Debugging Failed Actions
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://app.example.com
+
+# This click fails - why?
+playwright-cli click e5
+
+playwright-cli tracing-stop
+# Open trace to see DOM state when click was attempted
+```
+
+### Analyzing Performance
+
+```bash
+playwright-cli tracing-start
+playwright-cli open https://slow-site.com
+playwright-cli tracing-stop
+
+# View network waterfall to identify slow resources
+```
+
+### Capturing Evidence
+
+```bash
+# Record a complete user flow for documentation
+playwright-cli tracing-start
+
+playwright-cli open https://app.example.com/checkout
+playwright-cli fill e1 "4111111111111111"
+playwright-cli fill e2 "12/25"
+playwright-cli fill e3 "123"
+playwright-cli click e4
+
+playwright-cli tracing-stop
+# Trace shows exact sequence of events
+```
+
+## Trace vs Video vs Screenshot
+
+| Feature | Trace | Video | Screenshot |
+|---------|-------|-------|------------|
+| **Format** | .trace file | .webm video | .png/.jpeg image |
+| **DOM inspection** | Yes | No | No |
+| **Network details** | Yes | No | No |
+| **Step-by-step replay** | Yes | Continuous | Single frame |
+| **File size** | Medium | Large | Small |
+| **Best for** | Debugging | Demos | Quick capture |
+
+## Best Practices
+
+### 1. Start Tracing Before the Problem
+
+```bash
+# Trace the entire flow, not just the failing step
+playwright-cli tracing-start
+playwright-cli open https://example.com
+# ... all steps leading to the issue ...
+playwright-cli tracing-stop
+```
+
+### 2. Clean Up Old Traces
+
+Traces can consume significant disk space:
+
+```bash
+# Remove traces older than 7 days
+find .playwright-cli/traces -mtime +7 -delete
+```
+
+## Limitations
+
+- Traces add overhead to automation
+- Large traces can consume significant disk space
+- Some dynamic content may not replay perfectly

package/dist/builtin/workflows/skills/playwright-cli/references/video-recording.md

@@ -0,0 +1,143 @@
+# Video Recording
+
+Capture browser automation sessions as video for debugging, documentation, or verification. Produces WebM (VP8/VP9 codec).
+
+## Basic Recording
+
+```bash
+# Open browser first
+playwright-cli open
+
+# Start recording
+playwright-cli video-start demo.webm
+
+# Add a chapter marker for section transitions
+playwright-cli video-chapter "Getting Started" --description="Opening the homepage" --duration=2000
+
+# Navigate and perform actions
+playwright-cli goto https://example.com
+playwright-cli snapshot
+playwright-cli click e1
+
+# Add another chapter
+playwright-cli video-chapter "Filling Form" --description="Entering test data" --duration=2000
+playwright-cli fill e2 "test input"
+
+# Stop and save
+playwright-cli video-stop
+```
+
+## Best Practices
+
+### 1. Use Descriptive Filenames
+
+```bash
+# Include context in filename
+playwright-cli video-start recordings/login-flow-2024-01-15.webm
+playwright-cli video-start recordings/checkout-test-run-42.webm
+```
+
+### 2. Record entire hero scripts.
+
+When recording a video for the user or as a proof of work, it is best to create a code snippet and execute it with run-code.
+It allows pulling appropriate pauses between the actions and annotating the video. There are new Playwright APIs for that.
+
+1) Perform scenario using CLI and take note of all locators and actions. You'll need those locators to request their bounding boxes for highlight.
+2) Create a file with the intended script for video (below). Use pressSequentially w/ delay for nice typing, make reasonable pauses.
+3) Use playwright-cli run-code --filename your-script.js
+
+**Important**: Overlays are `pointer-events: none` — they do not interfere with page interactions. You can safely keep sticky overlays visible while clicking, filling, or performing any actions on the page.
+
+```js
+async page => {
+  await page.screencast.start({ path: 'video.webm', size: { width: 1280, height: 800 } });
+  await page.goto('https://demo.playwright.dev/todomvc');
+
+  // Show a chapter card — blurs the page and shows a dialog.
+  // Blocks until duration expires, then auto-removes.
+  // Use this for simple use cases, but always feel free to hand-craft your own beautiful
+  // overlay via await page.screencast.showOverlay().
+  await page.screencast.showChapter('Adding Todo Items', {
+    description: 'We will add several items to the todo list.',
+    duration: 2000,
+  });
+
+  // Perform action
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Walk the dog', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1000);
+
+  // Show next chapter
+  await page.screencast.showChapter('Verifying Results', {
+    description: 'Checking the item appeared in the list.',
+    duration: 2000,
+  });
+
+  // Add a sticky annotation that stays while you perform actions.
+  // Overlays are pointer-events: none, so they won't block clicks.
+  const annotation = await page.screencast.showOverlay(`
+    <div style="position: absolute; top: 8px; right: 8px;
+      padding: 6px 12px; background: rgba(0,0,0,0.7);
+      border-radius: 8px; font-size: 13px; color: white;">
+      ✓ Item added successfully
+    </div>
+  `);
+
+  // Perform more actions while the annotation is visible
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).pressSequentially('Buy groceries', { delay: 60 });
+  await page.getByRole('textbox', { name: 'What needs to be done?' }).press('Enter');
+  await page.waitForTimeout(1500);
+
+  // Remove the annotation when done
+  await annotation.dispose();
+
+  // You can also highlight relevant locators and provide contextual annotations.
+  const bounds = await page.getByText('Walk the dog').boundingBox();
+  await page.screencast.showOverlay(`
+    <div style="position: absolute;
+      top: ${bounds.y}px;
+      left: ${bounds.x}px;
+      width: ${bounds.width}px;
+      height: ${bounds.height}px;
+      border: 1px solid red;">
+    </div>
+    <div style="position: absolute;
+      top: ${bounds.y + bounds.height + 5}px;
+      left: ${bounds.x + bounds.width / 2}px;
+      transform: translateX(-50%);
+      padding: 6px;
+      background: #808080;
+      border-radius: 10px;
+      font-size: 14px;
+      color: white;">Check it out, it is right above this text
+    </div>
+  `, { duration: 2000 });
+
+  await page.screencast.stop();
+}
+```
+
+Embrace creativity, overlays are powerful.
+
+### Overlay API Summary
+
+| Method | Use Case |
+|--------|----------|
+| `page.screencast.showChapter(title, { description?, duration?, styleSheet? })` | Full-screen chapter card with blurred backdrop — ideal for section transitions |
+| `page.screencast.showOverlay(html, { duration? })` | Custom HTML overlay — use for callouts, labels, highlights |
+| `disposable.dispose()` | Remove a sticky overlay added without duration |
+| `page.screencast.hideOverlays()` / `page.screencast.showOverlays()` | Temporarily hide/show all overlays |
+
+## Tracing vs Video
+
+| Feature | Video | Tracing |
+|---------|-------|---------|
+| Output | WebM file | Trace file (viewable in Trace Viewer) |
+| Shows | Visual recording | DOM snapshots, network, console, actions |
+| Use case | Demos, documentation | Debugging, analysis |
+| Size | Larger | Smaller |
+
+## Limitations
+
+- Recording adds slight overhead to automation
+- Large recordings can consume significant disk space

package/dist/builtin/workflows/skills/prompt-engineer/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: prompt-engineer
+description: Create, improve, or optimize prompts using best practices.
+---
+
+# Prompt Engineering Skill
+
+This skill provides comprehensive guidance for creating effective prompts for language models using proven best practices. Use this skill whenever working on prompt design, optimization, or troubleshooting.
+
+## Overview
+
+Apply proven prompt engineering techniques to create high-quality, reliable prompts that produce consistent, accurate outputs while minimizing hallucinations and implementing appropriate security measures.
+
+## When to Use This Skill
+
+Trigger this skill when users request:
+
+- Help writing a prompt for a specific task
+- Improving an existing prompt that isn't performing well
+- Making outputs more consistent, accurate, or secure
+- Creating system prompts for specialized roles
+- Implementing specific techniques (chain-of-thought, multishot, XML tags)
+- Reducing hallucinations or errors in outputs
+- Debugging prompt performance issues
+
+## Workflow
+
+### Step 1: Understand Requirements
+
+Ask clarifying questions to understand:
+
+- **Task goal**: What should the prompt accomplish?
+- **Use case**: One-time use, API integration, or production system?
+- **Constraints**: Output format, length, style, tone requirements
+- **Quality needs**: Consistency, accuracy, security priorities
+- **Complexity**: Simple task or multi-step workflow?
+
+### Step 2: Identify Applicable Techniques
+
+Based on requirements, determine which techniques to apply:
+
+**Core techniques (for all prompts):**
+
+- Be clear and direct
+- Use XML tags for structure
+
+**Specialized techniques:**
+
+- **Role-specific expertise** → System prompts
+- **Complex reasoning** → Chain of thought
+- **Format consistency** → Multishot prompting
+- **Multi-step tasks** → Prompt chaining
+- **Long documents** → Long context tips
+- **Deep analysis** → Extended thinking
+- **Factual accuracy** → Hallucination reduction
+- **Output consistency** → Consistency techniques
+- **Security concerns** → Jailbreak mitigation
+
+### Step 3: Load Relevant References
+
+Read the appropriate reference file(s) based on techniques needed:
+
+**For basic prompt improvement:**
+
+```
+Read references/core_prompting.md
+```
+
+Covers: clarity, system prompts, XML tags
+
+**For complex tasks:**
+
+```
+Read references/advanced_patterns.md
+```
+
+Covers: chain of thought, multishot, chaining, long context, extended thinking
+
+**For specific quality issues:**
+
+```
+Read references/quality_improvement.md
+```
+
+Covers: hallucinations, consistency, security
+
+### Step 4: Design the Prompt
+
+Apply techniques from references to create the prompt structure:
+
+**Basic Template:**
+
+```
+[System prompt - optional, for role assignment]
+
+<context>
+Relevant background information
+</context>
+
+<instructions>
+Clear, specific task instructions
+Use numbered steps for multi-step tasks
+</instructions>
+
+<examples>
+  <example>
+    <input>Sample input</input>
+    <output>Expected output</output>
+  </example>
+  [2-4 more examples if using multishot]
+</examples>
+
+<output_format>
+Specify exact format (JSON, XML, markdown, etc.)
+</output_format>
+
+[Actual task/question]
+```
+
+**Key Design Principles:**
+
+1. **Clarity**: Be explicit and specific
+2. **Structure**: Use XML tags to organize
+3. **Examples**: Provide 3-5 concrete examples for complex formats
+4. **Context**: Give relevant background
+5. **Constraints**: Specify output requirements clearly
+
+### Step 5: Add Quality Controls
+
+Based on quality needs, add appropriate safeguards:
+
+**For factual accuracy:**
+
+- Grant permission to say "I don't know"
+- Request quote extraction before analysis
+- Require citations for claims
+- Limit to provided information sources
+
+**For consistency:**
+
+- Provide explicit format specifications
+- Use response prefilling
+- Include diverse examples
+- Consider prompt chaining
+
+**For security:**
+
+- Add harmlessness screening
+- Establish clear ethical boundaries
+- Implement input validation
+- Use layered protection
+
+### Step 6: Optimize and Test
+
+**Optimization checklist:**
+
+- [ ] Could someone with minimal context follow the instructions?
+- [ ] Are all terms and requirements clearly defined?
+- [ ] Is the desired output format explicitly specified?
+- [ ] Are examples diverse and relevant?
+- [ ] Are XML tags used consistently?
+- [ ] Is the prompt as concise as possible while remaining clear?
+
+**Testing approach:**
+
+- Run prompt multiple times with varied inputs
+- Check consistency across runs
+- Verify outputs match expected format
+- Test edge cases
+- Validate quality controls work
+
+### Step 7: Iterate Based on Results
+
+**Debugging process:**
+
+1. Identify failure points
+2. Review relevant reference material
+3. Apply appropriate techniques
+4. Test and measure improvement
+5. Repeat until satisfactory
+
+**Common Issues and Solutions:**
+
+| Issue                   | Solution                                    | Reference              |
+| ----------------------- | ------------------------------------------- | ---------------------- |
+| Inconsistent format     | Add examples, use prefilling                | quality_improvement.md |
+| Hallucinations          | Add uncertainty permission, quote grounding | quality_improvement.md |
+| Missing steps           | Break into subtasks, use chaining           | advanced_patterns.md   |
+| Wrong tone              | Add role to system prompt                   | core_prompting.md      |
+| Misunderstands task     | Add clarity, provide context                | core_prompting.md      |
+| Complex reasoning fails | Add chain of thought                        | advanced_patterns.md   |
+
+## Important Principles
+
+**Progressive Disclosure**
+Start with core techniques and add advanced patterns only when needed. Don't over-engineer simple prompts.
+
+**Documentation**
+When delivering prompts, explain which techniques were used and why. This helps users understand and maintain them.
+
+**Validation**
+Always validate critical outputs, especially for high-stakes applications. No prompting technique eliminates all errors.
+
+**Experimentation**
+Prompt engineering is iterative. Small changes can have significant impacts. Test variations and measure results.
+
+## Quick Reference Guide
+
+### Technique Selection Matrix
+
+| User Need                     | Primary Technique       | Reference File         |
+| ----------------------------- | ----------------------- | ---------------------- |
+| Better clarity                | Be clear and direct     | core_prompting.md      |
+| Domain expertise              | System prompts          | core_prompting.md      |
+| Organized structure           | XML tags                | core_prompting.md      |
+| Complex reasoning             | Chain of thought        | advanced_patterns.md   |
+| Format consistency            | Multishot prompting     | advanced_patterns.md   |
+| Multi-step process            | Prompt chaining         | advanced_patterns.md   |
+| Long documents (100K+ tokens) | Long context tips       | advanced_patterns.md   |
+| Deep analysis                 | Extended thinking       | advanced_patterns.md   |
+| Reduce false information      | Hallucination reduction | quality_improvement.md |
+| Consistent outputs            | Consistency techniques  | quality_improvement.md |
+| Security/safety               | Jailbreak mitigation    | quality_improvement.md |
+
+### When to Combine Techniques
+
+- **Structured analysis**: XML tags + Chain of thought
+- **Consistent formatting**: Multishot + Response prefilling
+- **Complex workflows**: Prompt chaining + XML tags
+- **Factual reports**: Quote grounding + Citation verification
+- **Production systems**: System prompts + Input validation + Consistency techniques
+
+## Resources
+
+This skill includes three comprehensive reference files:
+
+### references/core_prompting.md
+
+Essential techniques for all prompts:
+
+- Being clear and direct
+- System prompts and role assignment
+- Using XML tags effectively
+
+### references/advanced_patterns.md
+
+Sophisticated techniques for complex tasks:
+
+- Chain of thought prompting
+- Multishot prompting
+- Prompt chaining
+- Long context handling
+- Extended thinking
+
+### references/quality_improvement.md
+
+Techniques for specific quality issues:
+
+- Reducing hallucinations
+- Increasing consistency
+- Mitigating jailbreaks and prompt injections
+
+Load these files as needed based on the workflow steps above.