From 1f50483030e8b5733e65cb74a06ccc85f8046490 Mon Sep 17 00:00:00 2001 From: Matt Van Horn Date: Sun, 8 Mar 2026 12:51:29 -0700 Subject: [PATCH 1/2] docs(agent-browser): add inspection and debugging commands Documents all missing agent-browser CLI commands for debugging workflows. Adds 9 new command categories: eval, console/errors, network, storage, device settings, element debugging, recording/tracing, tabs, and advanced mouse controls. Closes #170 Co-Authored-By: Claude Opus 4.6 --- .../skills/agent-browser/SKILL.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) diff --git a/plugins/compound-engineering/skills/agent-browser/SKILL.md b/plugins/compound-engineering/skills/agent-browser/SKILL.md index 3ff264e5..ebb781bd 100644 --- a/plugins/compound-engineering/skills/agent-browser/SKILL.md +++ b/plugins/compound-engineering/skills/agent-browser/SKILL.md @@ -202,6 +202,107 @@ Returns: } ``` +## Inspection & Debugging + +### JavaScript Evaluation + +```bash +agent-browser eval "document.title" # Evaluate JS expression +agent-browser eval "JSON.stringify(localStorage)" # Return serialized data +agent-browser eval "document.querySelectorAll('a').length" # Count elements +``` + +### Console & Errors + +```bash +agent-browser console # Show browser console output +agent-browser console --clear # Show and clear console +agent-browser errors # Show JavaScript errors only +agent-browser errors --clear # Show and clear errors +``` + +## Network + +```bash +agent-browser network requests # List captured requests +agent-browser network requests --filter "api" # Filter by URL pattern +agent-browser route "**/*.png" abort # Block matching requests +agent-browser route "https://api.example.com/*" fulfill --status 200 --body '{"mock":true}' # Mock response +agent-browser unroute "**/*.png" # Remove route handler +``` + +## Storage + +### Cookies + +```bash +agent-browser cookies get # Get all cookies +agent-browser cookies get --name "session" # Get specific cookie +agent-browser cookies set --name "token" --value "abc" # Set cookie +agent-browser cookies clear # Clear all cookies +``` + +### Local & Session Storage + +```bash +agent-browser storage local # Get all localStorage +agent-browser storage local --key "theme" # Get specific key +agent-browser storage session # Get all sessionStorage +agent-browser storage session --key "cart" # Get specific key +``` + +## Device & Settings + +```bash +agent-browser set viewport 1920 1080 # Set viewport size +agent-browser set device "iPhone 14" # Emulate device +agent-browser set geo --lat 47.6 --lon -122.3 # Set geolocation +agent-browser set offline true # Enable offline mode +agent-browser set offline false # Disable offline mode +agent-browser set media "prefers-color-scheme" "dark" # Set media feature +agent-browser set headers '{"X-Custom":"value"}' # Set extra HTTP headers +agent-browser set credentials "user" "pass" # Set HTTP auth credentials +``` + +## Element Debugging + +```bash +agent-browser highlight @e1 # Highlight element visually +agent-browser get box @e1 # Get bounding box (x, y, width, height) +agent-browser get styles @e1 # Get computed styles +agent-browser is visible @e1 # Check if element is visible +agent-browser is enabled @e1 # Check if element is enabled +agent-browser is checked @e1 # Check if checkbox/radio is checked +``` + +## Recording & Tracing + +```bash +agent-browser trace start # Start recording trace +agent-browser trace stop trace.zip # Stop and save trace file +agent-browser record start # Start recording video +agent-browser record stop video.webm # Stop and save recording +``` + +## Tabs & Windows + +```bash +agent-browser tab list # List open tabs +agent-browser tab new https://example.com # Open URL in new tab +agent-browser tab close # Close current tab +agent-browser tab 2 # Switch to tab by index +``` + +## Advanced Mouse + +```bash +agent-browser mouse move 100 200 # Move mouse to coordinates +agent-browser mouse down # Press mouse button +agent-browser mouse up # Release mouse button +agent-browser mouse wheel 0 500 # Scroll (deltaX, deltaY) +agent-browser drag @e1 @e2 # Drag from element to element +``` + ## vs Playwright MCP | Feature | agent-browser (CLI) | Playwright MCP | From b2f1d9671f123b5d801ff83403e7332938125780 Mon Sep 17 00:00:00 2001 From: Matt Van Horn Date: Sun, 8 Mar 2026 22:39:51 -0700 Subject: [PATCH 2/2] feat(skills): add ce-audit skill for knowledge freshness auditing Detect stale learnings in docs/solutions/ by cross-referencing documented solutions against the current codebase. Checks for deleted files, renamed modules, restructured directories, and significantly modified code. Outputs a structured freshness report with actionable recommendations (archive, review, or export). Addresses #221. Co-Authored-By: Claude Opus 4.6 --- .claude-plugin/marketplace.json | 4 +- .../.claude-plugin/plugin.json | 4 +- plugins/compound-engineering/CHANGELOG.md | 8 + plugins/compound-engineering/README.md | 3 +- .../skills/ce-audit/SKILL.md | 207 ++++++++++++++++++ 5 files changed, 221 insertions(+), 5 deletions(-) create mode 100644 plugins/compound-engineering/skills/ce-audit/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a6aea30c..760181bc 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,8 +11,8 @@ "plugins": [ { "name": "compound-engineering", - "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 22 commands, and 20 skills.", - "version": "2.38.1", + "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents, 22 commands, and 21 skills.", + "version": "2.39.0", "author": { "name": "Kieran Klaassen", "url": "https://github.com/kieranklaassen", diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index e659557f..98b7e6ea 100644 --- a/plugins/compound-engineering/.claude-plugin/plugin.json +++ b/plugins/compound-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "compound-engineering", - "version": "2.38.1", - "description": "AI-powered development tools. 29 agents, 22 commands, 20 skills, 1 MCP server for code review, research, design, and workflow automation.", + "version": "2.39.0", + "description": "AI-powered development tools. 29 agents, 22 commands, 21 skills, 1 MCP server for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", "email": "kieran@every.to", diff --git a/plugins/compound-engineering/CHANGELOG.md b/plugins/compound-engineering/CHANGELOG.md index e7664980..e566bab4 100644 --- a/plugins/compound-engineering/CHANGELOG.md +++ b/plugins/compound-engineering/CHANGELOG.md @@ -5,6 +5,14 @@ All notable changes to the compound-engineering plugin will be documented in thi The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [2.39.0] - 2026-03-08 + +### Added + +- **`ce-audit` skill** - Knowledge freshness auditor that detects stale learnings in `docs/solutions/` by cross-referencing documented solutions against the current codebase. Checks for deleted files, renamed modules, restructured directories, and significantly modified code. Outputs a structured report with actionable recommendations (archive, review, or export). Addresses [#221](https://github.com/EveryInc/compound-engineering-plugin/issues/221). + +--- + ## [2.38.1] - 2026-03-01 ### Fixed diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 33a4ea15..88099e96 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -8,7 +8,7 @@ AI-powered development tools that get smarter with every use. Make each unit of |-----------|-------| | Agents | 29 | | Commands | 22 | -| Skills | 20 | +| Skills | 21 | | MCP Servers | 1 | ## Agents @@ -120,6 +120,7 @@ Core workflow commands use `ce:` prefix to unambiguously identify them as compou | Skill | Description | |-------|-------------| | `andrew-kane-gem-writer` | Write Ruby gems following Andrew Kane's patterns | +| `ce-audit` | Audit docs/solutions/ for stale learnings against the current codebase | | `compound-docs` | Capture solved problems as categorized documentation | | `create-agent-skills` | Expert guidance for creating Claude Code skills | | `dhh-rails-style` | Write Ruby/Rails code in DHH's 37signals style | diff --git a/plugins/compound-engineering/skills/ce-audit/SKILL.md b/plugins/compound-engineering/skills/ce-audit/SKILL.md new file mode 100644 index 00000000..51fa2fbc --- /dev/null +++ b/plugins/compound-engineering/skills/ce-audit/SKILL.md @@ -0,0 +1,207 @@ +--- +name: ce-audit +description: Audit docs/solutions/ for stale learnings by cross-referencing against the current codebase. Use when learnings have accumulated and may be outdated. +argument-hint: "[optional: specific category or file pattern]" +allowed-tools: + - Read + - Bash + - Grep + - Glob + - Agent +--- + +# Knowledge Freshness Auditor + +Detect stale learnings in `docs/solutions/` by cross-referencing documented solutions against the current state of the codebase. Learnings decay as code evolves - files get deleted, modules get renamed, directories get restructured. This skill finds the drift. + +## When to Use + +- After major refactors or migrations +- Periodically (monthly or quarterly) to maintain knowledge quality +- Before `/ce:compound` to avoid duplicating outdated knowledge +- When `learnings-researcher` surfaces a result that feels wrong + +## Process + +### Step 1: Discover Learnings + +Scan `docs/solutions/` for all markdown files with YAML frontmatter. + +```bash +find docs/solutions/ -name '*.md' -not -name 'README.md' -not -path '*/patterns/*' 2>/dev/null +``` + +If no files found, report: + +``` +No learnings found in docs/solutions/. +Run /ce:compound after solving problems to start building your knowledge base. +``` + +Count total files and report: `Found N learnings to audit.` + +If an argument was provided (category or file pattern), filter to only matching files. + +### Step 2: Extract References from Each Learning + +For each learning file, read it and extract: + +1. **File paths** mentioned in the content (e.g., `app/models/user.rb`, `src/components/Auth.tsx`) +2. **Module/class names** from the `module` frontmatter field +3. **Component references** from the `component` frontmatter field +4. **Code snippets** - extract key identifiers (class names, method names, function names) +5. **Date** from the `date` frontmatter field (when the learning was written) +6. **Tags** from the `tags` frontmatter field + +Use Grep and Read in parallel across multiple files to minimize tool calls. + +### Step 3: Cross-Reference Against Codebase + +For each learning, check these staleness signals. Run checks in parallel where possible. + +#### Signal 1: Referenced Files (High weight) + +```bash +# For each file path mentioned in the learning +test -f "referenced/file/path.rb" && echo "EXISTS" || echo "MISSING" +``` + +- **MISSING** = strong staleness signal +- **EXISTS** = check modification date (Signal 3) + +#### Signal 2: Module/Class Existence (High weight) + +```bash +# Search for the module or class name in the codebase +grep -r "class ModuleName\|module ModuleName" --include='*.rb' --include='*.py' --include='*.ts' --include='*.js' . 2>/dev/null | grep -v node_modules | grep -v docs/ +``` + +- **Not found** = module was likely renamed or removed +- **Found in different location** = module was moved (learning may need path update) + +#### Signal 3: File Modification Since Learning (Medium weight) + +For referenced files that still exist: + +```bash +# Check if file was significantly modified after the learning was written +git log --since="LEARNING_DATE" --stat -- "referenced/file/path.rb" 2>/dev/null | head -20 +``` + +- **No changes** = file is stable, learning likely still valid +- **Minor changes** (< 20 lines) = probably fine +- **Major changes** (> 50 lines or multiple commits) = learning may be outdated + +#### Signal 4: Directory Restructuring (Medium weight) + +```bash +# Check if the parent directory of referenced files has been restructured +git log --since="LEARNING_DATE" --diff-filter=R --name-status -- "referenced/directory/" 2>/dev/null +``` + +- **Renames detected** = directory was restructured, learning paths may be wrong + +#### Signal 5: Age Without Validation (Low weight) + +Calculate days since the learning was written. Learnings older than 90 days that have no other staleness signals get a mild "consider reviewing" flag - not a staleness marker. + +### Step 4: Score and Classify + +For each learning, assign a freshness score based on the signals: + +| Classification | Criteria | +|---------------|----------| +| **Fresh** | All referenced files exist, no major modifications, module/class found | +| **Possibly Stale** | Some referenced files modified significantly, OR directory restructured, OR module found in different location | +| **Likely Stale** | Referenced files deleted, OR module/class not found in codebase | + +### Step 5: Generate Report + +Output a structured report grouped by classification: + +``` +Knowledge Freshness Audit +========================= +Scanned: N learnings in docs/solutions/ +Date: YYYY-MM-DD + +FRESH (X) + [list files - no action needed] + +POSSIBLY STALE (Y) + docs/solutions/category/filename.md + - Referenced file path/to/file.rb modified significantly (Z commits, W lines changed since LEARNING_DATE) + - Module OldName found at new location path/to/new_location.rb + Action: Review and update if the solution approach has changed + + docs/solutions/category/filename2.md + - Parent directory src/old-path/ was restructured + Action: Verify file paths in the learning still apply + +LIKELY STALE (Z) + docs/solutions/category/filename3.md + - Referenced file app/models/old_model.rb no longer exists + - Class OldModel not found in codebase + Action: Archive or rewrite. The code this learning references has been removed. + +SUMMARY + Fresh: X (N%) + Possibly Stale: Y (N%) + Likely Stale: Z (N%) +``` + +### Step 6: Suggest Actions + +After the report, present options: + +``` +What would you like to do? + +1. Archive likely stale learnings (move to docs/solutions/_archived/) +2. Review possibly stale learnings one by one +3. Export report to docs/solutions/_audit-log/YYYY-MM-DD.md +4. Done - no action needed +``` + +Handle each option: + +**Option 1: Archive** +- Create `docs/solutions/_archived/` if it doesn't exist +- Move likely stale files there, preserving directory structure +- Add an `archived_date` and `archive_reason` field to each file's frontmatter +- Report what was moved + +**Option 2: Review one by one** +- For each possibly stale learning, show the learning content alongside the staleness signals +- Ask: "Update this learning? (y/n/skip)" +- If yes, help the user update the file paths, module names, or solution content +- If no, mark as reviewed (add `last_audited: YYYY-MM-DD` to frontmatter) + +**Option 3: Export report** +- Save the full report to `docs/solutions/_audit-log/YYYY-MM-DD.md` +- Useful for tracking knowledge health over time + +**Option 4: Done** +- End the audit + +## Interaction Method + +Present numbered options and wait for user response. If the environment does not support interactive prompts, default to generating the report only (Steps 1-5) and skip Step 6. + +## Performance Notes + +- For repositories with many learnings (50+), batch file existence checks into a single bash command rather than checking one at a time +- Use `git log --name-only` with date ranges rather than per-file queries when possible +- Run Grep searches for multiple modules in parallel +- Skip `node_modules/`, `vendor/`, `.git/`, and other dependency directories when searching for modules + +## Integration Points + +**Works with:** +- `compound-docs` - audits the files that compound-docs creates +- `learnings-researcher` - surfaces freshness warnings when retrieving learnings +- `/ce:compound` - run audit before compounding to avoid duplicating stale knowledge + +**Does not modify:** +- Learning content (unless user explicitly chooses Option 2) +- The `learnings-researcher` agent (future enhancement: add freshness warnings)