chore(skills): vendoring metadata + OPENRIG sidecars for two process skills

Apply the existing writing-skills-for-openrig doctrine (SKILL.md §"Vendored skills") to the two process skills where modifications + supplementary content were already in place but undocumented. agent-browser: add-supplementary-files pattern; the LOCAL-INSIGHTS.md sibling captures field-tested gotchas (command-compatibility matrix, etc) that the upstream Vercel skill doesn't cover. SKILL.md body had a pointer to it already; frontmatter now declares the vendoring relationship and a new OPENRIG.md sidecar narrates the relationship in human-readable form. executing-plans: modify-the-file pattern; OpenRig restructured upstream's all-tasks-at-once shape into batch-with-checkpoint (default 3 tasks/batch + report + continue cycle) to fit the driver/guard/qa rhythm. Removed the upstream subagent-alternative pointer. OPENRIG.md captures the diff and the why. Establishes OPENRIG.md as the per-skill sidecar convention for vendored skills with non-trivial OpenRig relationship. Empty for openrig-native skills; minimal for vendored-unchanged; narrative for vendored-modified or vendored-supplemented. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
2026-11-09 11:51:37 -10:00 · 2026-05-13 18:05:37 -07:00
1 parent 7e55d9d373
commit 647864fe19
@@ -0,0 +1,40 @@
+---
+skill: agent-browser
+openrig-relationship: vendored-supplemented
+---
+
+# OpenRig and this skill
+
+## Origin
+
+- **Upstream**: Vercel agent-browser CLI (https://github.com/vercel/agent-browser)
+- **Vendoring pattern**: `add-supplementary-files`
+- **Last upstream check**: 2026-05-13 (initial relationship declaration)
+
+## How OpenRig uses this skill
+
+OpenRig ships `agent-browser` so any agent dispatched by an OpenRig topology can drive a real browser (snapshots, form fills, screenshots, scraping, web-app testing) without operators having to separately install a browser-automation skill. It's referenced from any agent profile whose role includes web work.
+
+## OpenRig-specific modifications
+
+This is the canonical example of the **add-supplementary-files** pattern (see `writing-skills-for-openrig` SKILL.md §"Vendored skills"). The upstream skill is kept structurally intact; OpenRig adds a companion file that captures local-use insights without polluting the upstream content.
+
+| Surface | What changed | Why |
+|---|---|---|
+| `SKILL.md` body | A short "## Local Dev Insights" section was added near the end with an `**IMPORTANT:** Read LOCAL-INSIGHTS.md` pointer. | Without the pointer, agents loading the skill wouldn't know the companion file exists. The pointer is the only structural modification needed for the supplementary pattern to be discoverable. |
+| `LOCAL-INSIGHTS.md` (new sibling, ~189 lines) | Field-tested gotchas, command-compatibility matrices, corrections discovered through hands-on use that the upstream skill doesn't cover. | E.g., not all `get` subcommands accept `@refs` — `get text @e1` works but `get html @e1` fails silently. The compatibility matrix saves agents from the most common confusion class. |
+
+Nothing else in `SKILL.md` diverges from upstream content as of the last upstream check.
+
+## Companion files
+
+- `LOCAL-INSIGHTS.md` — load-bearing supplementary content. The SKILL.md body explicitly points readers here for hands-on gotchas the upstream skill doesn't cover.
+
+## When to re-sync upstream
+
+Watch for new `agent-browser` CLI releases (Vercel). When the command surface changes meaningfully:
+
+1. Re-sync `SKILL.md` body from upstream, preserving the "Local Dev Insights" pointer section.
+2. Update `LOCAL-INSIGHTS.md` compatibility matrix to reflect new behavior (some `get` subcommands may gain `@ref` support, breaking the current matrix).
+3. Bump `last_upstream_check` in `SKILL.md` frontmatter.
+4. Note any structural shape changes in `divergence_notes`.
@@ -2,6 +2,16 @@
 name: agent-browser
 description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
 allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*)
+metadata:
+  openrig:
+    vendored_from: "Vercel agent-browser (https://github.com/vercel/agent-browser)"
+    vendoring_pattern: add-supplementary-files
+    last_upstream_check: "2026-05-13 (initial vendoring declaration)"
+    divergence_notes: |
+      Upstream SKILL.md content tracks upstream; a small "Local Dev Insights"
+      pointer section was added near the end of the body to surface the sibling
+      LOCAL-INSIGHTS.md companion file. See OPENRIG.md for the full OpenRig
+      relationship to this skill.
 ---

 # Browser Automation with agent-browser
@@ -0,0 +1,56 @@
+---
+skill: executing-plans
+openrig-relationship: vendored-modified
+---
+
+# OpenRig and this skill
+
+## Origin
+
+- **Upstream**: Obra Superpowers (https://github.com/obra/superpowers)
+- **Vendoring pattern**: `modify-the-file`
+- **Last upstream check**: 2026-05-13 (initial relationship declaration)
+
+## How OpenRig uses this skill
+
+This is the canonical "execute a plan that another seat wrote" skill for OpenRig implementation agents. The driver/guard/qa pattern depends on this skill to keep plan-execution checkpointable and reviewable. Without the batch-with-checkpoint structure, the orchestration loop loses its in-flight review surface.
+
+## OpenRig-specific modifications
+
+The skill was restructured from upstream's all-tasks-at-once execution shape into a batch-with-checkpoint shape:
+
+| Aspect | Upstream | OpenRig |
+|---|---|---|
+| Execution unit | All tasks in plan, sequentially | Batch (default 3 tasks per batch) |
+| Reporting cadence | Once at end (after all tasks complete) | Between every batch |
+| Architect-review surface | None inside the skill | Step 3 "Report" + Step 4 "Continue" cycle |
+| Subagent alternative | Suggests `superpowers:subagent-driven-development` as a better choice when subagents are available | **Removed**. OpenRig topologies already supply separate pods for review; the subagent pointer added cognitive overhead with no win. |
+| Stop conditions | "Hit a blocker" | "Hit a blocker **mid-batch**" |
+| Step 5 "Complete Development" | Step 3 in upstream | Renumbered to Step 5 to make room for the batch-and-report cycle |
+
+The `## Integration` section preserves the upstream sub-skill pointers (`using-git-worktrees`, `writing-plans`, `finishing-a-development-branch`) — those are also vendored from obra-superpowers and present in OpenRig under the same names.
+
+## Why these modifications
+
+- **Batch-and-report cadence fits the OpenRig driver/guard/qa rhythm.** Architect feedback is in-the-loop rather than after-the-fact. A driver who reports between batches gives guard + qa room to surface direction corrections before more work compounds the wrong direction.
+- **The subagent-driven-development pointer doesn't fit the OpenRig posture.** OpenRig already provides parallel-pod review via separate seats; routing through subagents is structurally redundant.
+- **"Mid-batch" precision in stop conditions** matches the batch unit. A driver hitting a blocker between tasks should still report — the unit of "stop and ask" is the batch, not the whole plan.
+
+## Companion files
+
+None at the moment.
+
+## When to re-sync upstream
+
+Watch for upstream changes to:
+
+- **Plan-execution discipline** — stop conditions, verification rules, blocker-handling cadence.
+- **The relationship to writing-plans + finishing-a-development-branch** — if upstream changes how these compose, OpenRig should consider whether the new shape is worth adopting.
+
+When upstream changes:
+
+1. Pull non-conflicting changes into the OpenRig copy.
+2. Preserve the batch-with-checkpoint structure unless founder direction reverses.
+3. Re-check that the subagent-alternative pointer hasn't crept back in.
+4. Bump `last_upstream_check` in `SKILL.md` frontmatter.
+5. Note any structural shape changes in `divergence_notes`.
@@ -1,6 +1,16 @@
 ---
 name: executing-plans
 description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+metadata:
+  openrig:
+    vendored_from: "Obra Superpowers (https://github.com/obra/superpowers)"
+    vendoring_pattern: modify-the-file
+    last_upstream_check: "2026-05-13 (initial vendoring declaration)"
+    divergence_notes: |
+      Restructured from upstream's all-tasks-at-once execution into batch-with-
+      checkpoint execution (default 3 tasks per batch + report + continue cycle).
+      Removed the upstream suggestion to use superpowers:subagent-driven-development
+      as an alternative. See OPENRIG.md for full divergence details.
 ---

 # Executing Plans
@@ -0,0 +1,40 @@
+---
+skill: agent-browser
+openrig-relationship: vendored-supplemented
+---
+
+# OpenRig and this skill
+
+## Origin
+
+- **Upstream**: Vercel agent-browser CLI (https://github.com/vercel/agent-browser)
+- **Vendoring pattern**: `add-supplementary-files`
+- **Last upstream check**: 2026-05-13 (initial relationship declaration)
+
+## How OpenRig uses this skill
+
+OpenRig ships `agent-browser` so any agent dispatched by an OpenRig topology can drive a real browser (snapshots, form fills, screenshots, scraping, web-app testing) without operators having to separately install a browser-automation skill. It's referenced from any agent profile whose role includes web work.
+
+## OpenRig-specific modifications
+
+This is the canonical example of the **add-supplementary-files** pattern (see `writing-skills-for-openrig` SKILL.md §"Vendored skills"). The upstream skill is kept structurally intact; OpenRig adds a companion file that captures local-use insights without polluting the upstream content.
+
+| Surface | What changed | Why |
+|---|---|---|
+| `SKILL.md` body | A short "## Local Dev Insights" section was added near the end with an `**IMPORTANT:** Read LOCAL-INSIGHTS.md` pointer. | Without the pointer, agents loading the skill wouldn't know the companion file exists. The pointer is the only structural modification needed for the supplementary pattern to be discoverable. |
+| `LOCAL-INSIGHTS.md` (new sibling, ~189 lines) | Field-tested gotchas, command-compatibility matrices, corrections discovered through hands-on use that the upstream skill doesn't cover. | E.g., not all `get` subcommands accept `@refs` — `get text @e1` works but `get html @e1` fails silently. The compatibility matrix saves agents from the most common confusion class. |
+
+Nothing else in `SKILL.md` diverges from upstream content as of the last upstream check.
+
+## Companion files
+
+- `LOCAL-INSIGHTS.md` — load-bearing supplementary content. The SKILL.md body explicitly points readers here for hands-on gotchas the upstream skill doesn't cover.
+
+## When to re-sync upstream
+
+Watch for new `agent-browser` CLI releases (Vercel). When the command surface changes meaningfully:
+
+1. Re-sync `SKILL.md` body from upstream, preserving the "Local Dev Insights" pointer section.
+2. Update `LOCAL-INSIGHTS.md` compatibility matrix to reflect new behavior (some `get` subcommands may gain `@ref` support, breaking the current matrix).
+3. Bump `last_upstream_check` in `SKILL.md` frontmatter.
+4. Note any structural shape changes in `divergence_notes`.
@@ -2,6 +2,16 @@
 name: agent-browser
 description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
 allowed-tools: Bash(npx agent-browser:*), Bash(agent-browser:*)
+metadata:
+  openrig:
+    vendored_from: "Vercel agent-browser (https://github.com/vercel/agent-browser)"
+    vendoring_pattern: add-supplementary-files
+    last_upstream_check: "2026-05-13 (initial vendoring declaration)"
+    divergence_notes: |
+      Upstream SKILL.md content tracks upstream; a small "Local Dev Insights"
+      pointer section was added near the end of the body to surface the sibling
+      LOCAL-INSIGHTS.md companion file. See OPENRIG.md for the full OpenRig
+      relationship to this skill.
 ---

 # Browser Automation with agent-browser
@@ -0,0 +1,56 @@
+---
+skill: executing-plans
+openrig-relationship: vendored-modified
+---
+
+# OpenRig and this skill
+
+## Origin
+
+- **Upstream**: Obra Superpowers (https://github.com/obra/superpowers)
+- **Vendoring pattern**: `modify-the-file`
+- **Last upstream check**: 2026-05-13 (initial relationship declaration)
+
+## How OpenRig uses this skill
+
+This is the canonical "execute a plan that another seat wrote" skill for OpenRig implementation agents. The driver/guard/qa pattern depends on this skill to keep plan-execution checkpointable and reviewable. Without the batch-with-checkpoint structure, the orchestration loop loses its in-flight review surface.
+
+## OpenRig-specific modifications
+
+The skill was restructured from upstream's all-tasks-at-once execution shape into a batch-with-checkpoint shape:
+
+| Aspect | Upstream | OpenRig |
+|---|---|---|
+| Execution unit | All tasks in plan, sequentially | Batch (default 3 tasks per batch) |
+| Reporting cadence | Once at end (after all tasks complete) | Between every batch |
+| Architect-review surface | None inside the skill | Step 3 "Report" + Step 4 "Continue" cycle |
+| Subagent alternative | Suggests `superpowers:subagent-driven-development` as a better choice when subagents are available | **Removed**. OpenRig topologies already supply separate pods for review; the subagent pointer added cognitive overhead with no win. |
+| Stop conditions | "Hit a blocker" | "Hit a blocker **mid-batch**" |
+| Step 5 "Complete Development" | Step 3 in upstream | Renumbered to Step 5 to make room for the batch-and-report cycle |
+
+The `## Integration` section preserves the upstream sub-skill pointers (`using-git-worktrees`, `writing-plans`, `finishing-a-development-branch`) — those are also vendored from obra-superpowers and present in OpenRig under the same names.
+
+## Why these modifications
+
+- **Batch-and-report cadence fits the OpenRig driver/guard/qa rhythm.** Architect feedback is in-the-loop rather than after-the-fact. A driver who reports between batches gives guard + qa room to surface direction corrections before more work compounds the wrong direction.
+- **The subagent-driven-development pointer doesn't fit the OpenRig posture.** OpenRig already provides parallel-pod review via separate seats; routing through subagents is structurally redundant.
+- **"Mid-batch" precision in stop conditions** matches the batch unit. A driver hitting a blocker between tasks should still report — the unit of "stop and ask" is the batch, not the whole plan.
+
+## Companion files
+
+None at the moment.
+
+## When to re-sync upstream
+
+Watch for upstream changes to:
+
+- **Plan-execution discipline** — stop conditions, verification rules, blocker-handling cadence.
+- **The relationship to writing-plans + finishing-a-development-branch** — if upstream changes how these compose, OpenRig should consider whether the new shape is worth adopting.
+
+When upstream changes:
+
+1. Pull non-conflicting changes into the OpenRig copy.
+2. Preserve the batch-with-checkpoint structure unless founder direction reverses.
+3. Re-check that the subagent-alternative pointer hasn't crept back in.
+4. Bump `last_upstream_check` in `SKILL.md` frontmatter.
+5. Note any structural shape changes in `divergence_notes`.
@@ -1,6 +1,16 @@
 ---
 name: executing-plans
 description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+metadata:
+  openrig:
+    vendored_from: "Obra Superpowers (https://github.com/obra/superpowers)"
+    vendoring_pattern: modify-the-file
+    last_upstream_check: "2026-05-13 (initial vendoring declaration)"
+    divergence_notes: |
+      Restructured from upstream's all-tasks-at-once execution into batch-with-
+      checkpoint execution (default 3 tasks per batch + report + continue cycle).
+      Removed the upstream suggestion to use superpowers:subagent-driven-development
+      as an alternative. See OPENRIG.md for full divergence details.
 ---

 # Executing Plans