arggon-harness 0.1.0

package/src/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/src/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/src/skills/spec-init/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: spec-init
+description: Initialize the spec/ directory structure for a new project. Use when the user says "spec-init", "initialize spec", "set up spec workflow", or wants to bootstrap the spec-native workflow on a new project.
+---
+
+# Spec Init
+
+Initialize the spec/ directory structure and generate project config from codebase context.
+
+## When to Use
+
+- User says "spec-init", "initialize spec", "set up spec"
+- User is adopting the spec-native workflow on a new project
+- User wants to create the spec/ directory structure
+
+## Workflow
+
+1. **Check for existing spec/config.yaml**
+   - If `spec/config.yaml` exists, ask the user: "spec/config.yaml already exists. Overwrite?"
+   - If the user declines, abort without creating or modifying any files.
+   - If the user confirms, proceed with `force: true` when calling the tool.
+   - If `spec/config.yaml` does not exist, proceed without prompting.
+
+2. **Gather codebase context via @explore agent**
+   - Delegate to the @explore agent with this task:
+     "Analyze this codebase and produce a markdown summary covering:
+     (a) Project purpose — what the project does in 1-2 sentences
+     (b) Technology stack — languages, frameworks, key dependencies
+     (c) Architecture overview — high-level structure, key modules, patterns
+     (d) Domain description — business domain, key entities, workflows
+     Keep the summary under 50KB."
+   - The explore agent returns the context as markdown.
+
+3. **Synthesize context**
+   - Review the explore agent output.
+   - Ensure it covers all four sections (purpose, stack, architecture, domain).
+   - If any section is missing, ask the user to provide it.
+   - Ensure the total context is under 50KB.
+
+4. **Call spec_init tool**
+   - Call `spec_init` with:
+     - `context`: the synthesized markdown
+     - `schema`: "spec-driven" (or user-specified schema)
+     - `rules`: optional, from user input or defaults
+     - `force`: true only if user confirmed overwrite in step 1
+   - The tool creates spec/, spec/changes/, spec/main/, spec/archive/ and writes config.yaml and registry.yaml.
+
+5. **Report results**
+   - Show the user what was created:
+     - spec/ directory structure
+     - spec/config.yaml with project context
+     - spec/registry.yaml with empty changes list
+   - Suggest next step: "Run /spec-propose to create your first change."
+
+## Guardrails
+
+- This skill ONLY initializes files under spec/. It MUST NOT create or modify files under .opencode/ (commands, skills, plugins).
+- Always confirm with the user before overwriting an existing spec/config.yaml.
+- Context must be under 50KB — if the explore agent returns more, summarize it.
+- If the explore agent fails or returns low-quality context, ask the user to provide context manually.
+- Do not skip the overwrite check — it protects existing project configuration.

package/src/skills/spec-onboard/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: spec-onboard
+description: Guided onboarding tutorial through a complete spec-native workflow cycle. Use when the user is new to spec-native and wants to learn the workflow by doing a real example.
+---
+
+# Spec Onboard
+
+Guided onboarding through a complete spec-native workflow.
+
+## When to Use
+
+- User is new to spec-native
+- User says "onboard", "tutorial", "show me how"
+- User wants to learn by doing
+
+## Duration
+
+~15-20 minutes
+
+## Workflow
+
+### Phase 1: Welcome (1 min)
+
+Explain the journey:
+1. Pick a small task from the codebase
+2. Explore the problem
+3. Create a spec change
+4. Build artifacts (proposal, specs, design, tasks)
+5. Implement the tasks
+6. Verify and archive
+
+### Phase 2: Task Selection (2 min)
+
+Scan codebase for small improvements:
+- TODO/FIXME comments
+- Missing error handling
+- Functions without tests
+- Type issues (any types)
+- Debug artifacts (console.log, debugger)
+
+Present 3-4 suggestions with:
+- Location
+- Scope
+- Rationale
+
+Let user choose (or suggest the smallest).
+
+### Phase 3: Explore Demo (2 min)
+
+Briefly demonstrate explore mode:
+- Read relevant files
+- Show spec/config.yaml as project configuration reference
+- Draw ASCII diagram of current state
+- Note considerations
+- Explain: "This is explore mode — thinking before doing"
+
+### Phase 4: Create Change (1 min)
+
+- Call `spec_change_new` with chosen task
+- Show the folder structure created
+- Explain: "A change is a self-contained unit of work"
+
+### Phase 5: Proposal (2 min)
+
+- Call `spec_artifact_instr` for proposal
+- Draft proposal together:
+  - Why: Explain the problem
+  - What: List capabilities
+  - Impact: Files affected
+- Explain each section
+- Save to proposal.yaml
+- Pause for user approval
+
+### Phase 6: Specs (2 min)
+
+- Call `spec_artifact_instr` for specs
+- Explain requirement/scenario format
+- Draft spec with one requirement:
+  - Description with SHALL/MUST
+  - Scenario with given/when/then
+  - Verify block with assertion
+- Save to specs/<capability>.yaml
+- Explain: "Specs are behavior contracts"
+
+### Phase 7: Design (1 min)
+
+- Call `spec_artifact_instr` for design
+- Explain: "Design captures HOW, not WHAT"
+- Draft design.md:
+  - Context
+  - Goals/Non-goals
+  - One decision
+- Save to design.yaml
+- Note: "For simple changes, you can skip design"
+
+### Phase 8: Tasks (2 min)
+
+- Call `spec_artifact_instr` for tasks
+- Explain task breakdown
+- Generate 2-3 tasks:
+  - Each with ID, description, depends_on
+  - Acceptance criteria
+  - Estimated time
+- Save to tasks.yaml
+- Explain: "Tasks are your implementation checklist"
+
+### Phase 9: Apply (3 min)
+
+- Call `spec_task_progress`
+- Implement first task with narration:
+  - "The spec says X, so I'm doing Y"
+  - Show the code changes
+  - Mark task complete
+- Explain: "Apply implements tasks in order"
+
+### Phase 10: Verify (1 min)
+
+- Call `spec_verify`
+- Show verification report
+- Explain each dimension
+- Note: "Verification catches issues before archive"
+
+### Phase 11: Archive (1 min)
+
+- Call `spec_specs_apply` to sync specs
+- Call `spec_change_archive` to archive
+- Explain: "Archive preserves the decision history"
+
+### Phase 12: Recap (1 min)
+
+Summarize the cycle:
+```
+propose -> apply -> verify -> archive
+   ^                         |
+   +-------------------------+
+```
+
+Show command reference:
+```
+/spec-propose    Create a new change
+/spec-explore    Think through a problem
+/spec-apply      Implement tasks
+/spec-sync       Sync specs to main
+/spec-archive    Archive completed change
+/spec-verify     Verify implementation
+/spec-status     Check progress
+```
+
+Suggest: "Try /spec-propose on your real work now!"
+
+## Teaching Pattern
+
+Follow EXPLAIN -> DO -> SHOW -> PAUSE at key transitions.
+
+## Scope Guardrail
+
+If user picks something too large:
+- Gently suggest slicing smaller
+- "That's a great project! For onboarding, let's pick something we can finish in 15 minutes."
+- Soft guardrail — user can override
+
+## Graceful Exits
+
+If user wants to stop:
+- "Your change is saved. Use /spec-apply to resume later."
+
+If user just wants commands:
+- Show command reference table
+- Exit gracefully
+
+## Guardrails
+
+- Follow EXPLAIN -> DO -> SHOW -> PAUSE
+- Keep narration light during implementation
+- Don't skip phases (teaching the workflow is the goal)
+- Use real codebase tasks, not fake examples
+- Handle exits gracefully
+- Never pressure to continue

package/src/skills/spec-status/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: spec-status
+description: Show the status of spec changes including artifact completion, task progress, and verification state. Use when the user wants to check on the progress of a change or see all active changes.
+---
+
+# Spec Status
+
+Show the status of spec changes.
+
+## When to Use
+
+- User wants to check progress
+- User says "status", "progress", "where am I"
+- User wants to see all active changes
+
+## Workflow
+
+### Single Change
+
+1. **Get change name**
+   - If user specified, use it
+   - If only one active, use it
+   - Otherwise, list and ask
+
+2. **Get status**
+   - Call `spec_change_status`
+   - Show:
+     - Change name and schema
+     - Artifact completion (checkmark/cross for each)
+     - Next artifacts to create
+     - Overall completion status
+
+3. **Get task progress**
+   - Call `spec_task_progress`
+   - Show:
+     - Total tasks
+     - Completed tasks
+     - Pending tasks
+     - Percentage complete
+
+4. **Check integrity**
+   - Call `spec_integrity_check`
+   - Show: valid/invalid, mismatches
+
+5. **Show summary**
+   - Overall status: "Ready for apply" / "In progress" / "Ready for archive"
+   - Next suggested action
+
+### All Changes
+
+1. **List all changes**
+   - Call `spec_change_list`
+   - Show table:
+     ```
+     | Name          | Schema      | Progress | Status |
+     |---------------|-------------|----------|--------|
+     | add-user-auth | spec-driven | 75%      | active |
+     | fix-payment   | tdd         | 100%     | active |
+     ```
+
+2. **Highlight next actions**
+   - For each change, suggest next step:
+     - "Run /spec-apply" if artifacts complete
+     - "Run /spec-archive" if tasks complete
+     - "Run /spec-verify" before archive
+
+## Guardrails
+
+- Keep output concise
+- Use tables for multiple changes
+- Highlight next actions
+- Don't overwhelm with details

package/src/skills/spec-sync/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: spec-sync
+description: Sync delta specs from a change to main specs without archiving. Use when the user wants to update the main specifications with changes from a spec change, but keep the change active for further work.
+---
+
+# Spec Sync
+
+Sync delta specs from a change to main specs.
+
+## When to Use
+
+- User wants to update main specs
+- User says "sync", "merge specs", "update specs"
+- User wants to apply deltas without archiving
+
+## Workflow
+
+1. **Select change**
+   - If user specified, use it
+   - Otherwise, call `spec_change_list` and ask
+
+2. **Check for delta specs**
+   - Read the change's specs/ directory
+   - List delta spec files
+   - If no deltas, inform user and stop
+
+3. **Preview changes**
+   - Call `spec_specs_apply` with `dryRun: true`
+   - Show what will be applied:
+     - Capabilities affected
+     - Operations (add/modify/remove/rename)
+     - Requirements impacted
+
+4. **Confirm with user**
+   - Show preview
+   - Ask: "Apply these changes to main specs?"
+   - If no, stop
+
+5. **Apply deltas**
+   - Call `spec_specs_apply` with `dryRun: false`
+   - This merges deltas into spec/main/*.yaml
+
+6. **Show summary**
+   - List capabilities updated
+   - Show operation counts (added, modified, removed, renamed)
+   - Note: Change remains active (not archived)
+   - Suggest: "Run /spec-archive when fully done"
+
+## Sync Behavior
+
+- **add**: Add requirement to main (error if exists)
+- **modify**: Replace requirement in main (must include full content)
+- **remove**: Remove requirement from main
+- **rename**: Rename requirement ID
+
+## Guardrails
+
+- Always preview before applying
+- Confirm with user before applying
+- Don't archive the change (that's /spec-archive)
+- Preserve existing content not mentioned in deltas
+- Operation should be idempotent
+- Read spec/config.yaml for project context before syncing

package/src/templates/config.yaml

@@ -0,0 +1,14 @@
+schema: <schema-name>
+
+context: |
+  <project-context-markdown>
+
+rules:
+  proposal:
+    - <proposal-rule>
+  specs:
+    - <specs-rule>
+  design:
+    - <design-rule>
+  tasks:
+    - <tasks-rule>