fix(slice 29 BC repair-2): close remaining HG-8 description + table refs

Second guard verdict (qitem-20260513074951-02713944) caught remaining
HG-8 broken-ref class: my earlier grep used backticked-only pattern
and missed references in `description:` frontmatter fields + tables
(no backticks). Comprehensive grep without the backtick constraint
caught the remaining 7 instances.

GUARD'S 4 SURFACED INSTANCES (+ 3 driver-discovered) ALL ADDRESSED:

1. plugin/openrig-user/SKILL.md:3 description "(use openrig-builder)"
   → "(work in the openrig product repo)"
2. plugin/openrig-architect/SKILL.md:3 description same pattern → same fix
3. plugin/openrig-operator/SKILL.md:4 description same → same fix
4. plugin/forming-an-openrig-mental-model/SKILL.md:4 description
   "(use mental-model-ha for that)" → rewritten path-agnostic
   ("HA-pair compaction recovery is the pair-of-seats coordination
   pattern; orientation is a solo task")
5. plugin/forming-an-openrig-mental-model/SKILL.md:168 bootstrap-
   table cell named openrig-builder/openrig-upgrade/mental-model-ha
   → rewritten to list the shipped bootstrap set (openrig-user,
   openrig-operator, openrig-architect, forming-an-openrig-mental-
   model + rest of openrig-core plugin skills)
6. canonical/core/openrig-architect/SKILL.md:3 (mirror) → same fix
7. plugin/openrig-user/SKILL.md:266 starter_ref name example
   `openrig-builder-base--claude-code` → renamed to
   `my-team-starter--claude-code` (generic example name)

DRIVER-DISCOVERED INSTANCES (same class; same fix applied):

8. plugin/agent-startup-and-context-ingestion/SKILL.md:74 prose
   "Per the externalized-memory-surfaces convention's 13-row inventory"
   → rewritten to describe the 3 primary memory surfaces inline
   without naming a non-shipped convention/skill
9. plugin/agent-startup-and-context-ingestion/SKILL.md:91 example-
   cells in startup-files-vs-skills table → replaced unshipped
   `vault-user` with shipped `dogfood`
10. canonical/process/writing-plans/SKILL.md:110 SUB-SKILL ref to
    `superpowers:subagent-driven-development` → rewritten path-agnostic
    ("Pair with whatever subagent-orchestration skill your runtime
    provides; the Obra Superpowers plugin ships one if you have that
    plugin installed")

VERIFICATION (re-run per guard's checklist):

1. HG-8 broad-grep (no backtick constraint):
   /usr/bin/find packages/daemon/{assets/plugins/openrig-core/skills,
     specs/agents/shared/skills} skills/_canonical -name SKILL.md
     -exec /usr/bin/grep -l -E '\b(mental-model-ha|scope-recovery|
     writing-skills-for-openrig|openrig-builder|openrig-upgrade|
     building-agent-software|looping-workflows|... + 30 more tokens|
     vault-user)\b' {} +
   → 0 hits across all 3 trees (plugin + canonical + skills/_canonical
   mirror; previously hits ranged across descriptions, tables, prose).

2. HG-6 + HG-7 reference grep:
   → 0 hits (preserved from BC-repair commit 35ac9f2).

3. npm run mirror-skills:check
   → exit 0.

4. Daemon focused suite (openrig-core-plugin + skill-library-routes +
   plugins-routes + plugin-files-routes):
   → 73/73 PASS. Frontmatter validity (HG-9) preserved including the
   description-field rewrites.

5. git diff --check 1a6cc52..HEAD → clean.

LESSON LEARNED (banked-feedback class):

The prior repair grep used \`backticked\` pattern only — missed
description-field plain-text refs. Guard caught the gap by running a
broader bare-name grep. Banked feedback_specific_review_recommendations_
get_acted_on applies here at a meta level: when guard surfaces 4
instances of a pattern, the REPAIR scope is the entire pattern class,
not just the 4 instances. The first repair committed only the
backtick-pattern subset; this repair-2 closes the description-
field + table-cell subset that the bare-name grep finds.

Banked as guidance for future cleanup-class repairs: when grep'ing for
ref-cleanup, use the BARE NAME pattern (\b<name>\b) not the backtick-
constrained one. Backticks are a style convention for body refs;
descriptions and prose use bare names. The bare-name grep is the
canonical HG-8 closure check.

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
This commit is contained in:
mvschwarzandClaude Opus 4.7 committed 2026-05-13 00:53:16 -07:00
1 parent 35ac9f294d
commit bb087c3ddb
9 files changed
+20 -19

No files matched your search

@@ -71,14 +71,15 @@ reentry case, distinct from reusable Agent Starters / priming packs):
## Memory surfaces consumed at startup
Per the externalized-memory-surfaces convention's 13-row inventory:
The primary surfaces a startup ingestion path reads:
- **Row 7** — AGENTS/role/CULTURE/startup overlays (primary)
- **Row 3** — startup replay context (primary)
- **Row 12** — restore/reentry packets and Agent Starters (cross-runtime startup path)
- AGENTS / role / CULTURE / startup overlays (the per-seat identity layer)
- startup replay context (what the agent did before the current boot)
- restore / reentry packets and Agent Starters (cross-runtime startup path)
The umbrella's authority-rank + read-vs-write columns govern which
surfaces a startup ingestion path can write vs only read.
Authority-rank + read-vs-write posture governs which surfaces a
startup-ingestion path can write vs only read; treat overlays as
write-restricted unless your role explicitly authors them.
## Startup files vs skills (the distinction)
@@ -88,7 +89,7 @@ Per `agent-startup-guide.md` (product reference doc) and the team handbook:
|---|---|
| Rig-specific, role-specific identity | Reusable SOPs / methodology / knowledge |
| Tell agent WHO it is, WHAT it's working on, HOW this team operates | Tell agent HOW to do something (transferable across rigs) |
| Examples: `role.md`, `CULTURE.md`, `startup/context.md` | Examples: `openrig-user`, `test-driven-development`, `vault-user` |
| Examples: `role.md`, `CULTURE.md`, `startup/context.md` | Examples: `openrig-user`, `test-driven-development`, `dogfood` |
| Authored per-rig | Authored once, used everywhere |
Don't put skill content in startup files. Don't put identity content
@@ -1,7 +1,7 @@
---
name: forming-an-openrig-mental-model
description: |
Use when an agent is newly oriented to OpenRig and needs to form an accurate mental model of the system fast — what rigs are, how skills load, what the topology shapes mean, what the product loop is. For agents booting into a new seat or returning to OpenRig work after time away. NOT for HA pair compaction recovery (use mental-model-ha for that) or for specific operational procedures.
Use when an agent is newly oriented to OpenRig and needs to form an accurate mental model of the system fast — what rigs are, how skills load, what the topology shapes mean, what the product loop is. For agents booting into a new seat or returning to OpenRig work after time away. NOT for HA-pair compaction recovery (that's the pair-of-seats coordination pattern; orientation is a solo task) or for specific operational procedures.
metadata:
openrig:
stage: factory-approved
@@ -165,7 +165,7 @@ cost when you reach for one.
| Home | Purpose |
|---|---|
| `<rig-cwd>/.claude/skills/`, `<rig-cwd>/.agents/skills/` | Where the harness actually loads from. Populated by `rig up`. |
| `~/.claude/skills/`, `~/.agents/skills/` | Your personal/global skills + OpenRig bootstrap (openrig-user, openrig-operator, openrig-builder, openrig-architect, openrig-upgrade, forming-an-openrig-mental-model, mental-model-ha). |
| `~/.claude/skills/`, `~/.agents/skills/` | Your personal/global skills + the OpenRig bootstrap set (openrig-user, openrig-operator, openrig-architect, forming-an-openrig-mental-model, plus the rest of the openrig-core plugin skills). |
| openrig-core plugin skills | Product built-in skills that ship with OpenRig (installed via the openrig-core plugin). |
| `~/.openrig/skills/` | Runtime install home for OpenRig-shipped skills. |
@@ -1,6 +1,6 @@
---
name: openrig-architect
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (work in the openrig product repo); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
metadata:
openrig:
stage: factory-approved
@@ -1,7 +1,7 @@
---
name: openrig-operator
description: |
Use when debugging host-side OpenRig runtime issues: daemon reachability, Codex permission or writable-root failures, command approval friction, rate limits/account switches, helper cleanup, or topology health confusion. NOT for ordinary CLI operation (use openrig-user) or for changing OpenRig itself (use openrig-builder).
Use when debugging host-side OpenRig runtime issues: daemon reachability, Codex permission or writable-root failures, command approval friction, rate limits/account switches, helper cleanup, or topology health confusion. NOT for ordinary CLI operation (use openrig-user) or for changing OpenRig itself (work in the openrig product repo).
metadata:
openrig:
stage: factory-approved
@@ -1,6 +1,6 @@
---
name: openrig-user
description: Use when operating OpenRig with the `rig` CLI and you need the shipped command surface for identity, inventory, communication, lifecycle, specs, recovery, or agent-facing JSON output. NOT for debugging host-side runtime issues (use openrig-operator) or for changing OpenRig itself (use openrig-builder).
description: Use when operating OpenRig with the `rig` CLI and you need the shipped command surface for identity, inventory, communication, lifecycle, specs, recovery, or agent-facing JSON output. NOT for debugging host-side runtime issues (use openrig-operator) or for changing OpenRig itself (work in the openrig product repo).
metadata:
openrig:
stage: factory-approved
@@ -263,7 +263,7 @@ Source `>= 6af2754` lets a RigSpec member set:
```yaml
starter_ref:
name: openrig-builder-base--claude-code
name: my-team-starter--claude-code
```
The daemon resolves the named entry from the Agent Starter registry, applies the
@@ -1,6 +1,6 @@
---
name: openrig-architect
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (work in the openrig product repo); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
metadata:
openrig:
stage: factory-approved
@@ -107,9 +107,9 @@ After saving the plan, offer execution choice:
**Which approach?"**
**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Spawn a fresh subagent for each task; code-review the result before merging
- Stay in this session
- Fresh subagent per task + code review
- Pair with whatever subagent-orchestration skill your runtime provides (e.g., the Obra Superpowers plugin ships one if you have that plugin installed)
**If Parallel Session chosen:**
- Guide them to open new session in worktree
@@ -1,6 +1,6 @@
---
name: openrig-architect
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (work in the openrig product repo); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
metadata:
openrig:
stage: factory-approved
@@ -107,9 +107,9 @@ After saving the plan, offer execution choice:
**Which approach?"**
**If Subagent-Driven chosen:**
- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development
- Spawn a fresh subagent for each task; code-review the result before merging
- Stay in this session
- Fresh subagent per task + code review
- Pair with whatever subagent-orchestration skill your runtime provides (e.g., the Obra Superpowers plugin ships one if you have that plugin installed)
**If Parallel Session chosen:**
- Guide them to open new session in worktree