feat: SKILL.md template system, 3-tier testing, DX tools (v0.3.3) (#41)

* refactor: extract command registry to commands.ts, add SNAPSHOT_FLAGS metadata

- NEW: browse/src/commands.ts — command sets + COMMAND_DESCRIPTIONS + load-time validation (zero side effects)
- server.ts imports from commands.ts instead of declaring sets inline
- snapshot.ts: SNAPSHOT_FLAGS array drives parseSnapshotArgs (metadata-driven, no duplication)
- All 186 existing tests pass

* feat: SKILL.md template system with auto-generated command references

- SKILL.md.tmpl + browse/SKILL.md.tmpl with {{COMMAND_REFERENCE}} and {{SNAPSHOT_FLAGS}} placeholders
- scripts/gen-skill-docs.ts generates SKILL.md from templates (supports --dry-run)
- Build pipeline runs gen:skill-docs before binary compilation
- Generated files have AUTO-GENERATED header, committed to git

* test: Tier 1 static validation — 34 tests for SKILL.md command correctness

- test/helpers/skill-parser.ts: extracts $B commands from code blocks, validates against registry
- test/skill-parser.test.ts: 13 parser/validator unit tests
- test/skill-validation.test.ts: 13 tests validating all SKILL.md files + registry consistency
- test/gen-skill-docs.test.ts: 8 generator tests (categories, sorting, freshness)

* feat: DX tools (skill:check, dev:skill) + Tier 2 E2E test scaffolding

- scripts/skill-check.ts: health summary for all SKILL.md files (commands, templates, freshness)
- scripts/dev-skill.ts: watch mode for template development
- test/helpers/session-runner.ts: Agent SDK wrapper for E2E skill tests
- test/skill-e2e.test.ts: 2 E2E tests + 3 stubs (auto-skip inside Claude Code sessions)
- E2E tests must run from plain terminal: SKILL_E2E=1 bun test test/skill-e2e.test.ts

* ci: SKILL.md freshness check on push/PR + TODO updates

- .github/workflows/skill-docs.yml: fails if generated SKILL.md files are stale
- TODO.md: add E2E cost tracking and model pinning to future ideas

* fix: restore rich descriptions lost in auto-generation

- Snapshot flags: add back value hints (-d <N>, -s <sel>, -o <path>)
- Snapshot flags: restore parenthetical context (@e refs, @c refs, etc.)
- Commands: is → includes valid states enum
- Commands: console → notes --errors filter behavior
- Commands: press → lists common keys (Enter, Tab, Escape)
- Commands: cookie-import-browser → describes picker UI
- Commands: dialog-accept → specifies alert/confirm/prompt
- Tips: restore → arrow (was downgraded to ->)

* test: quality evals for generated SKILL.md descriptions

Catches the exact regressions we shipped and caught in review:
- Snapshot flags must include value hints (-d <N>, -s <sel>, -o <path>)
- is command must list all valid states (visible/hidden/enabled/...)
- press command must list example keys (Enter, Tab, Escape)
- console command must describe --errors behavior
- Snapshot -i must mention @e refs, -C must mention @c refs
- All descriptions must be >= 8 chars (no empty stubs)
- Tips section must use → not ->

* feat: LLM-as-judge evals for SKILL.md documentation quality

4 eval tests using Anthropic API (claude-haiku, ~$0.01-0.03/run):
- Command reference table: clarity/completeness/actionability >= 4/5
- Snapshot flags section: same thresholds
- browse/SKILL.md overall quality
- Regression: generated version must score >= hand-maintained baseline

Requires ANTHROPIC_API_KEY. Auto-skips without it.
Run: bun run test:eval (or ANTHROPIC_API_KEY=sk-... bun test test/skill-llm-eval.test.ts)

* chore: bump version to 0.3.3, update changelog

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add ARCHITECTURE.md, update CLAUDE.md and CONTRIBUTING.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: conductor.json lifecycle hooks + .env propagation across worktrees

bin/dev-setup now copies .env from main worktree so API keys carry
over to Conductor workspaces automatically. conductor.json wires up
setup and archive hooks.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: complete CHANGELOG for v0.3.3 (architecture, conductor, .env)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

browse/src/snapshot.ts

@@ -40,6 +40,31 @@ interface SnapshotOptions {
   cursorInteractive?: boolean; // -C / --cursor-interactive: scan cursor:pointer etc.
 }
 
+/**
+ * Snapshot flag metadata — single source of truth for CLI parsing and doc generation.
+ *
+ * Imported by:
+ *   - gen-skill-docs.ts (generates {{SNAPSHOT_FLAGS}} tables)
+ *   - skill-parser.ts (validates flags in SKILL.md examples)
+ */
+export const SNAPSHOT_FLAGS: Array<{
+  short: string;
+  long: string;
+  description: string;
+  takesValue?: boolean;
+  valueHint?: string;
+  optionKey: keyof SnapshotOptions;
+}> = [
+  { short: '-i', long: '--interactive', description: 'Interactive elements only (buttons, links, inputs) with @e refs', optionKey: 'interactive' },
+  { short: '-c', long: '--compact', description: 'Compact (no empty structural nodes)', optionKey: 'compact' },
+  { short: '-d', long: '--depth', description: 'Limit depth', takesValue: true, valueHint: '<N>', optionKey: 'depth' },
+  { short: '-s', long: '--selector', description: 'Scope to CSS selector', takesValue: true, valueHint: '<sel>', optionKey: 'selector' },
+  { short: '-D', long: '--diff', description: 'Diff against previous snapshot (what changed?)', optionKey: 'diff' },
+  { short: '-a', long: '--annotate', description: 'Annotated screenshot with ref labels', optionKey: 'annotate' },
+  { short: '-o', long: '--output', description: 'Output path for screenshot', takesValue: true, valueHint: '<path>', optionKey: 'outputPath' },
+  { short: '-C', long: '--cursor-interactive', description: 'Cursor-interactive elements (@c refs — divs with pointer, onclick)', optionKey: 'cursorInteractive' },
+];
+
 interface ParsedNode {
   indent: number;
   role: string;
@@ -50,49 +75,24 @@ interface ParsedNode {
 }
 
 /**
- * Parse CLI args into SnapshotOptions
+ * Parse CLI args into SnapshotOptions — driven by SNAPSHOT_FLAGS metadata.
  */
 export function parseSnapshotArgs(args: string[]): SnapshotOptions {
   const opts: SnapshotOptions = {};
   for (let i = 0; i < args.length; i++) {
-    switch (args[i]) {
-      case '-i':
-      case '--interactive':
-        opts.interactive = true;
-        break;
-      case '-c':
-      case '--compact':
-        opts.compact = true;
-        break;
-      case '-d':
-      case '--depth':
-        opts.depth = parseInt(args[++i], 10);
+    const flag = SNAPSHOT_FLAGS.find(f => f.short === args[i] || f.long === args[i]);
+    if (!flag) throw new Error(`Unknown snapshot flag: ${args[i]}`);
+    if (flag.takesValue) {
+      const value = args[++i];
+      if (!value) throw new Error(`Usage: snapshot ${flag.short} <value>`);
+      if (flag.optionKey === 'depth') {
+        (opts as any)[flag.optionKey] = parseInt(value, 10);
         if (isNaN(opts.depth!)) throw new Error('Usage: snapshot -d <number>');
-        break;
-      case '-s':
-      case '--selector':
-        opts.selector = args[++i];
-        if (!opts.selector) throw new Error('Usage: snapshot -s <selector>');
-        break;
-      case '-D':
-      case '--diff':
-        opts.diff = true;
-        break;
-      case '-a':
-      case '--annotate':
-        opts.annotate = true;
-        break;
-      case '-o':
-      case '--output':
-        opts.outputPath = args[++i];
-        if (!opts.outputPath) throw new Error('Usage: snapshot -o <path>');
-        break;
-      case '-C':
-      case '--cursor-interactive':
-        opts.cursorInteractive = true;
-        break;
-      default:
-        throw new Error(`Unknown snapshot flag: ${args[i]}`);
+      } else {
+        (opts as any)[flag.optionKey] = value;
+      }
+    } else {
+      (opts as any)[flag.optionKey] = true;
     }
   }
   return opts;