@bastani/atomic 0.6.5 → 0.6.6-0

package/.agents/skills/impeccable/scripts/pin.mjs

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Pin/unpin sub-commands as standalone skill shortcuts.
+ *
+ * Usage:
+ *   node <scripts_path>/pin.mjs pin <command>
+ *   node <scripts_path>/pin.mjs unpin <command>
+ *
+ * `pin audit` creates a lightweight /audit skill that redirects to /impeccable audit.
+ * `unpin audit` removes that shortcut.
+ *
+ * The script discovers harness directories (.claude/skills, .cursor/skills, etc.)
+ * in the project root and creates/removes the pin in all of them.
+ */
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, readdirSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// All known harness directories
+const HARNESS_DIRS = [
+  '.claude', '.cursor', '.gemini', '.codex', '.agents',
+  '.trae', '.trae-cn', '.pi', '.opencode', '.kiro', '.rovodev',
+];
+
+// Valid sub-command names
+const VALID_COMMANDS = [
+  'craft', 'teach', 'extract', 'document', 'shape',
+  'critique', 'audit',
+  'polish', 'bolder', 'quieter', 'distill', 'harden', 'onboard', 'live',
+  'animate', 'colorize', 'typeset', 'layout', 'delight', 'overdrive',
+  'clarify', 'adapt', 'optimize',
+];
+
+// Marker to identify pinned skills (so unpin doesn't delete user skills)
+const PIN_MARKER = '<!-- impeccable-pinned-skill -->';
+
+/**
+ * Walk up from startDir to find a project root.
+ */
+function findProjectRoot(startDir = process.cwd()) {
+  let dir = resolve(startDir);
+  while (dir !== '/') {
+    if (
+      existsSync(join(dir, 'package.json')) ||
+      existsSync(join(dir, '.git')) ||
+      existsSync(join(dir, 'skills-lock.json'))
+    ) {
+      return dir;
+    }
+    const parent = resolve(dir, '..');
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return resolve(startDir);
+}
+
+/**
+ * Find harness skill directories that have an impeccable skill installed.
+ */
+function findHarnessDirs(projectRoot) {
+  const dirs = [];
+  for (const harness of HARNESS_DIRS) {
+    const skillsDir = join(projectRoot, harness, 'skills');
+    // Only pin in harness dirs that already have impeccable installed
+    const impeccableDir = join(skillsDir, 'impeccable');
+    if (existsSync(impeccableDir) || existsSync(join(skillsDir, 'i-impeccable'))) {
+      dirs.push(skillsDir);
+    }
+  }
+  return dirs;
+}
+
+/**
+ * Load command metadata (descriptions for pinned skills).
+ */
+function loadCommandMetadata() {
+  const metadataPath = join(__dirname, 'command-metadata.json');
+  if (existsSync(metadataPath)) {
+    return JSON.parse(readFileSync(metadataPath, 'utf-8'));
+  }
+  return {};
+}
+
+/**
+ * Generate a pinned skill's SKILL.md content.
+ */
+function generatePinnedSkill(command, metadata) {
+  const desc = metadata[command]?.description || `Shortcut for /impeccable ${command}.`;
+  const hint = metadata[command]?.argumentHint || '[target]';
+
+  return `---
+name: ${command}
+description: "${desc}"
+argument-hint: "${hint}"
+user-invocable: true
+---
+
+${PIN_MARKER}
+
+This is a pinned shortcut for \`{{command_prefix}}impeccable ${command}\`.
+
+Invoke {{command_prefix}}impeccable ${command}, passing along any arguments provided here, and follow its instructions.
+`;
+}
+
+/**
+ * Pin a command: create shortcut skill in all harness dirs.
+ */
+function pin(command, projectRoot) {
+  const metadata = loadCommandMetadata();
+  const harnessDirs = findHarnessDirs(projectRoot);
+
+  if (harnessDirs.length === 0) {
+    console.log('No harness directories with impeccable installed found.');
+    return false;
+  }
+
+  const content = generatePinnedSkill(command, metadata);
+  let created = 0;
+
+  for (const skillsDir of harnessDirs) {
+    // Check if skill already exists (and isn't a pin)
+    const skillDir = join(skillsDir, command);
+    if (existsSync(skillDir)) {
+      const existingMd = join(skillDir, 'SKILL.md');
+      if (existsSync(existingMd)) {
+        const existing = readFileSync(existingMd, 'utf-8');
+        if (!existing.includes(PIN_MARKER)) {
+          console.log(`  SKIP: ${skillDir} (non-pinned skill already exists)`);
+          continue;
+        }
+      }
+    }
+
+    mkdirSync(skillDir, { recursive: true });
+    writeFileSync(join(skillDir, 'SKILL.md'), content, 'utf-8');
+    console.log(`  + ${skillDir}`);
+    created++;
+  }
+
+  if (created > 0) {
+    console.log(`\nPinned '${command}' as a standalone shortcut in ${created} location(s).`);
+    console.log(`You can now use /${command} directly.`);
+  }
+
+  return created > 0;
+}
+
+/**
+ * Unpin a command: remove shortcut skill from all harness dirs.
+ */
+function unpin(command, projectRoot) {
+  const harnessDirs = findHarnessDirs(projectRoot);
+  let removed = 0;
+
+  for (const skillsDir of harnessDirs) {
+    const skillDir = join(skillsDir, command);
+    if (!existsSync(skillDir)) continue;
+
+    const skillMd = join(skillDir, 'SKILL.md');
+    if (!existsSync(skillMd)) continue;
+
+    // Safety: only remove if it's a pinned skill
+    const content = readFileSync(skillMd, 'utf-8');
+    if (!content.includes(PIN_MARKER)) {
+      console.log(`  SKIP: ${skillDir} (not a pinned skill)`);
+      continue;
+    }
+
+    rmSync(skillDir, { recursive: true, force: true });
+    console.log(`  - ${skillDir}`);
+    removed++;
+  }
+
+  if (removed > 0) {
+    console.log(`\nUnpinned '${command}' from ${removed} location(s).`);
+    console.log(`Use /impeccable ${command} to access it.`);
+  } else {
+    console.log(`No pinned '${command}' shortcut found.`);
+  }
+
+  return removed > 0;
+}
+
+// --- CLI ---
+const [,, action, command] = process.argv;
+
+if (!action || !command) {
+  console.log('Usage: node pin.mjs <pin|unpin> <command>');
+  console.log(`\nAvailable commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+if (action !== 'pin' && action !== 'unpin') {
+  console.error(`Unknown action: ${action}. Use 'pin' or 'unpin'.`);
+  process.exit(1);
+}
+
+if (!VALID_COMMANDS.includes(command)) {
+  console.error(`Unknown command: ${command}`);
+  console.error(`Available commands: ${VALID_COMMANDS.join(', ')}`);
+  process.exit(1);
+}
+
+const root = findProjectRoot();
+
+if (action === 'pin') {
+  pin(command, root);
+} else {
+  unpin(command, root);
+}

package/.agents/skills/init/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: init
 description: Generate CLAUDE.md and AGENTS.md by exploring the codebase
+metadata:
+  provider: atomic
 ---
 
 # Generate CLAUDE.md and AGENTS.md

package/.agents/skills/liteparse/SKILL.md

@@ -4,6 +4,7 @@ description: Use this skill when the user asks to parse, perform multi-format do
 compatibility: Requires Node 18+ and `@llamaindex/liteparse` installed globally via npm (`npm i -g @llamaindex/liteparse`)
 license: MIT
 metadata:
+  provider: atomic
   author: LlamaIndex
   version: "0.1.0"
 ---

package/.agents/skills/memory-systems/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: memory-systems
 description: Guides implementation of agent memory systems, compares production frameworks (Mem0, Zep/Graphiti, Letta, LangMem, Cognee), and designs persistence architectures for cross-session knowledge retention. Use when the user asks to "implement agent memory", "persist state across sessions", "build knowledge graph for agents", "track entities over time", "add long-term memory", "choose a memory framework", or mentions temporal knowledge graphs, vector stores, entity memory, adaptive memory, dynamic memory, or memory benchmarks (LoCoMo, LongMemEval). A core context engineering skill — also activates when the user mentions "context engineering" or "context-engineering" in the context of durable agent knowledge and cross-session persistence.
+metadata:
+  provider: atomic
 ---
 
 # Memory System Design

package/.agents/skills/multi-agent-patterns/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: multi-agent-patterns
 description: This skill should be used when the user asks to "design multi-agent system", "implement supervisor pattern", "create swarm architecture", "coordinate multiple agents", or mentions multi-agent patterns, context isolation, agent handoffs, sub-agents, or parallel agent execution. Part of the context engineering skill suite — also activates when the user mentions "context engineering" or "context-engineering" in the context of orchestrating context across multiple agents.
+metadata:
+  provider: atomic
 ---
 
 # Multi-Agent Architecture Patterns

package/.agents/skills/opentui/SKILL.md

@@ -2,6 +2,7 @@
 name: opentui
 description: Comprehensive OpenTUI skill for building terminal user interfaces. Covers the core imperative API, React reconciler, and Solid reconciler. Use for any TUI development task including components, layout, keyboard handling, animations, and testing.
 metadata:
+   provider: atomic
    references: core, react, solid
    internal: true
 ---

package/.agents/skills/pdf/SKILL.md

@@ -2,6 +2,8 @@
 name: pdf
 description: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.
 license: Proprietary. LICENSE.txt has complete terms
+metadata:
+  provider: atomic
 ---
 
 # PDF Processing Guide

package/.agents/skills/playwright-cli/SKILL.md

@@ -1,7 +1,9 @@
 ---
 name: playwright-cli
 description: Automate browser interactions, test web pages and work with Playwright tests.
-allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*) Bash(bunx:*) Bash(bun:*)
+allowed-tools: Bash(playwright-cli:*) Bash(npx:*) Bash(npm:*)
+metadata:
+  provider: atomic
 ---
 
 # Browser Automation with playwright-cli
@@ -38,6 +40,9 @@ playwright-cli dblclick e7
 # --submit presses Enter after filling the element
 playwright-cli fill e5 "user@example.com"  --submit
 playwright-cli drag e2 e8
+# drop files or data onto an element (from outside the page)
+playwright-cli drop e4 --path=./image.png
+playwright-cli drop e4 --data="text/plain=hello world"
 playwright-cli hover e4
 playwright-cli select e9 "option-value"
 playwright-cli upload ./document.pdf
@@ -150,7 +155,8 @@ playwright-cli unroute
 ```bash
 playwright-cli console
 playwright-cli console warning
-playwright-cli network
+playwright-cli requests
+playwright-cli request 5
 playwright-cli run-code "async page => await page.context().grantPermissions(['geolocation'])"
 playwright-cli run-code --filename=script.js
 playwright-cli tracing-start
@@ -158,6 +164,19 @@ playwright-cli tracing-stop
 playwright-cli video-start video.webm
 playwright-cli video-chapter "Chapter Title" --description="Details" --duration=2000
 playwright-cli video-stop
+
+# launch the dashboard for UI review / design feedback — user annotates the page, you receive the annotated screenshot, snapshot, and notes
+playwright-cli annotate
+
+# generate a Playwright locator for an element from its ref or selector
+playwright-cli generate-locator e5 --raw
+
+# show a persistent highlight overlay for an element, optionally with a custom style
+playwright-cli highlight e5
+playwright-cli highlight e5 --style="outline: 3px dashed red"
+# hide a single element highlight, or all page highlights when no target is given
+playwright-cli highlight e5 --hide
+playwright-cli highlight --hide
 ```
 
 ## Raw output
@@ -175,6 +194,11 @@ TOKEN=$(playwright-cli --raw cookie-get session_id)
 playwright-cli --raw localstorage-get theme
 ```
 
+For structured output wrapping every reply as JSON, pass --json
+```bash
+playwright-cli list --json
+```
+
 ## Open parameters
 ```bash
 # Use specific browser when creating session
@@ -188,14 +212,23 @@ playwright-cli open --persistent
 # Use persistent profile with custom directory
 playwright-cli open --profile=/path/to/profile
 
-# Connect to browser via extension
-playwright-cli attach --extension
+# Connect to browser via Playwright Extension
+playwright-cli attach --extension=chrome
+
+# Connect to a running Chrome or Edge by channel name
+playwright-cli attach --cdp=chrome
+playwright-cli attach --cdp=msedge
+
+# Connect to a running browser via CDP endpoint
+playwright-cli attach --cdp=http://localhost:9222
 
 # Start with config file
 playwright-cli open --config=my-config.json
 
 # Close the browser
 playwright-cli close
+# Detach from an attached browser (leaves the external browser running)
+playwright-cli -s=msedge detach
 # Delete user data for the default session
 playwright-cli delete-data
 ```
@@ -228,6 +261,9 @@ playwright-cli snapshot "#main"
 # limit snapshot depth for efficiency, take a partial snapshot afterwards
 playwright-cli snapshot --depth=4
 playwright-cli snapshot e34
+
+# include each element's bounding box as [box=x,y,width,height]
+playwright-cli snapshot --boxes
 ```
 
 ## Targeting elements
@@ -318,7 +354,7 @@ playwright-cli open https://example.com
 playwright-cli click e4
 playwright-cli fill e7 "test"
 playwright-cli console
-playwright-cli network
+playwright-cli requests
 playwright-cli close
 ```
 
@@ -331,12 +367,22 @@ playwright-cli tracing-stop
 playwright-cli close
 ```
 
+## Example: Interactive session
+
+Ask the user for UI review or design feedback. The user draws boxes on the live page and types comments; you receive the annotated screenshot, the snapshot of the marked region, and the user's notes. Use this whenever the user asks for "UI review", "design feedback", or to "ask the user what they think / want / mean":
+
+```bash
+playwright-cli open https://example.com
+playwright-cli annotate
+```
+
 ## Specific tasks
 
 * **Running and Debugging Playwright tests** [references/playwright-tests.md](references/playwright-tests.md)
 * **Request mocking** [references/request-mocking.md](references/request-mocking.md)
 * **Running Playwright code** [references/running-code.md](references/running-code.md)
 * **Browser session management** [references/session-management.md](references/session-management.md)
+* **Spec-driven testing (plan / generate / heal)** [references/spec-driven-testing.md](references/spec-driven-testing.md)
 * **Storage state (cookies, localStorage)** [references/storage-state.md](references/storage-state.md)
 * **Test generation** [references/test-generation.md](references/test-generation.md)
 * **Tracing** [references/tracing.md](references/tracing.md)

package/.agents/skills/playwright-cli/references/playwright-tests.md

@@ -14,7 +14,7 @@ PLAYWRIGHT_HTML_OPEN=never npm run special-test-command
 
 To debug a failing Playwright test, run it with `--debug=cli` option. This command will pause the test at the start and print the debugging instructions.
 
-**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed.
+**IMPORTANT**: run the command in the background and check the output until "Debugging Instructions" is printed. Make sure to stop the command after you have finished.
 
 Once instructions containing a session name are printed, use `playwright-cli` to attach the session and explore the page.
 

package/.agents/skills/playwright-cli/references/running-code.md

@@ -11,6 +11,16 @@ playwright-cli run-code "async page => {
 }"
 ```
 
+You can also load the function from a file:
+
+```bash
+playwright-cli run-code --filename=./my-script.js
+```
+
+
+The code must be a single function expression, it is wrapped in `(...)` and evaluated.
+import/export/require syntax is not supported.
+
 ## Geolocation
 
 ```bash

package/.agents/skills/playwright-cli/references/session-management.md

@@ -105,6 +105,62 @@ playwright-cli open https://example.com --persistent
 playwright-cli open https://example.com --profile=/path/to/profile
 ```
 
+## Attaching to a Running Browser
+
+Use `attach` to connect to a browser that is already running, instead of launching a new one.
+
+### Attach by channel name
+
+Connect to a running Chrome or Edge instance by its channel name. The browser must have remote debugging enabled — navigate to `chrome://inspect/#remote-debugging` in the target browser and check "Allow remote debugging for this browser instance".
+
+```bash
+# Attach to Chrome
+playwright-cli attach --cdp=chrome
+
+# Attach to Chrome Canary
+playwright-cli attach --cdp=chrome-canary
+
+# Attach to Microsoft Edge
+playwright-cli attach --cdp=msedge
+
+# Attach to Edge Dev
+playwright-cli attach --cdp=msedge-dev
+```
+
+Supported channels: `chrome`, `chrome-beta`, `chrome-dev`, `chrome-canary`, `msedge`, `msedge-beta`, `msedge-dev`, `msedge-canary`.
+
+When `--session` is not provided, the session is named after the channel (e.g. `--cdp=msedge` creates a session called `msedge`), so parallel attaches to Chrome and Edge don't collide on `default`. Pass `--session=<name>` to override.
+
+### Attach via CDP endpoint
+
+Connect to a browser that exposes a Chrome DevTools Protocol endpoint:
+
+```bash
+playwright-cli attach --cdp=http://localhost:9222
+```
+
+### Attach via browser extension
+
+Connect to a browser with the Playwright extension installed:
+
+```bash
+playwright-cli attach --extension
+```
+
+### Detach
+
+Tear down an attached session without affecting the external browser:
+
+```bash
+# Detach the default attached session
+playwright-cli detach
+
+# Detach a specific attached session
+playwright-cli -s=msedge detach
+```
+
+`detach` only works on sessions created via `attach`. For sessions created via `open`, use `close`.
+
 ## Default Browser Session
 
 When `-s` is omitted, commands use the default browser session: