mirror of
https://github.com/mvschwarz/openrig.git
synced 2026-11-09 17:32:41 -10:00
fix(slice 29 BC repair): close HG-8 broken-ref blockers across plugin + canonical surfaces
Guard verdict on qitem-20260513073618-c42951df (BLOCKING-CONCERN at
baacfe8) identified 4 specific HG-8 violations + the broader pattern
of dangling skill cross-references that point at skills not shipped
in either tree. This commit closes both layers.
GUARD-SURFACED ISSUES (4; all addressed):
1. plugin/seat-continuity-and-handover/SKILL.md:139 See Also pointed
at `mental-model-ha` (not a shipped skill). Removed from See Also +
removed from sibling_skills.
2. plugin/agent-startup-and-context-ingestion/SKILL.md:102 See Also
pointed at `writing-skills-for-openrig` (not shipped). Rewritten
to reference https://agentskills.io/specification (the cross-runtime
skill standard) — an operator-reachable public URL.
3. plugin/forming-an-openrig-mental-model/SKILL.md:267 NOT-for section
said HA pair compaction recovery is `mental-model-ha`. Rewritten
to describe the pattern path-agnostically (solo orientation vs.
pair-of-seats coordination).
4. plugin/forming-an-openrig-mental-model/SKILL.md:15 frontmatter
carried an authoring breadcrumb (`lab/skill-management-research/
cycles/...`). Removed; replaced with a path-agnostic distinction
between mental-model-of-OpenRig and HA-pair preservation.
BROADER HG-8 REPAIR (sibling_skills + body refs to unshipped skills):
Comprehensive sweep using the actual shipped-skills list (8 plugin +
26 canonical = 34 shipped) found additional dangling references the
guard would have flagged on next review. Cleaned:
plugin sibling_skills lists trimmed to shipped peers only:
- openrig-user: removed openrig-builder, openrig-upgrade, ai-dev-workflows
- openrig-architect: removed openrig-builder, openrig-upgrade, ai-dev-workflows;
also dropped two N-internal `notes:` and `naming_note:` blocks that
referenced internal "Phase 3c graduation" + product-source-rename
coordination (internal authoring history, no operator value)
- openrig-operator: removed openrig-builder, openrig-upgrade, ai-dev-workflows
- queue-handoff: sibling_skills emptied (all entries pointed at
unshipped control-plane-* / workflow-runtime / attention-queue
/ dispatching-parallel-agents / etc.)
- claude-compaction-restore: removed mental-model-ha, scope-recovery
- agent-startup-and-context-ingestion: removed mental-model-ha, scope-recovery
- seat-continuity-and-handover: removed mental-model-ha, scope-recovery
canonical sibling_skills lists trimmed:
- core/openrig-architect: same trim as plugin mirror (removed builder/
upgrade/ai-dev-workflows + dropped the two N-internal notes blocks)
- core/rig-lifecycle: replaced 7 unshipped refs (topology-mutation-and-
seat-management, seat-scaling-and-specialization, cross-host-rig-
commands, sidecar-operator, rig-bundles-and-shareable-artifacts,
specification-system, extension-and-user-workspace) with 3 shipped
peers (openrig-user, openrig-operator, seat-continuity-and-handover)
body content cleanup (See Also + prose):
- plugin/openrig-user: "Use control-plane-capabilities for rigx" +
"Use openrig-builder when changing OpenRig behavior" → rewritten as
"not a guide to OpenRig internals; for that, work in the openrig
product repo"
- plugin/queue-handoff See Also: removed `looping-workflows` entry
(skill not shipped) — only `rig queue --help` remains
- plugin/openrig-architect: building-agent-software bullet rewritten
as path-agnostic prose about agent-facing software design
- plugin/openrig-operator: "Use openrig-builder for build lane
selection" → "Changes to the OpenRig product happen in the openrig
product repo — operate that as a normal software project"
- plugin/agent-startup-and-context-ingestion: Don't-use-this-when
bullet about writing-skills-for-openrig rewritten to reference the
agentskills.io specification directly
- canonical/core/openrig-architect: same body cleanup as plugin mirror
- canonical/core/rig-lifecycle See Also: removed unshipped entries
(session-source-fork, permission-and-capability-preflight, rig-
lifecycle-as-primitive-dossier)
VERIFICATION:
HG-6 + HG-7 grep (must return 0 hits):
- /usr/bin/find ... -exec grep -l "<internal-docs>|<work-tree>|internal docs|
claude-compact-in-place|session-compaction-and-restore|permission-
posture|openrig-compaction-instructions" ... → 0 hits both plugin
+ canonical trees.
HG-8 grep (body refs to unshipped skill names):
- /usr/bin/find ... -exec grep "\`(mental-model-ha|scope-recovery|
writing-skills-for-openrig|openrig-builder|openrig-upgrade|...)
\`" ... → 0 hits both trees.
mirror-skills:check → exit 0 (canonical edits propagated to
skills/_canonical/).
Daemon focused suite (openrig-core-plugin + skill-library-routes +
plugins-routes + plugin-files-routes) → 73/73 PASS. Frontmatter
validity preserved (HG-9).
Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>
This commit is contained in:
mvschwarzandClaude Opus 4.7 committed
1 parent
baacfe808d
commit
35ac9f294d
12 files changed
+27
-92
No files matched your search
+2
-4
@@ -11,8 +11,6 @@ metadata:
|
||||
surfaces convention. Load at agent start; revisit after compaction.
|
||||
sibling_skills:
|
||||
- claude-compaction-restore
|
||||
- mental-model-ha
|
||||
- scope-recovery
|
||||
- seat-continuity-and-handover
|
||||
transfer_test: pending
|
||||
---
|
||||
@@ -46,7 +44,7 @@ is scattered or stale, agents execute the wrong thing very efficiently.
|
||||
|
||||
- The agent is being created via Agent Starter — the starter's manifest carries startup context
|
||||
- The work is artifact-backed mental-model rebuild from a packet — that's `claude-compaction-restore`
|
||||
- The intent is to ship reusable startup content as a skill — that's `writing-skills-for-openrig`
|
||||
- The intent is to ship reusable startup content as a skill — write the skill against the agentskills.io specification, not as inline startup prose
|
||||
|
||||
## Failure modes (4)
|
||||
|
||||
@@ -99,7 +97,7 @@ culture / pod / member / operator) handles the layering.
|
||||
|
||||
## See also
|
||||
|
||||
- `writing-skills-for-openrig` skill — authoring discipline for skill content (what doesn't belong in startup)
|
||||
- `forming-an-openrig-mental-model` skill — orientation for new agents
|
||||
- `claude-compaction-restore` skill — restore-time startup ingestion after compaction
|
||||
- `seat-continuity-and-handover` skill — packet shape that survives seat resets
|
||||
- https://agentskills.io/specification — the cross-runtime skill standard (what skill content should and shouldn't be)
|
||||
@@ -11,8 +11,6 @@ metadata:
|
||||
is wired into Claude Code's settings (e.g. ~/.claude/settings.json)
|
||||
so the restore packet is generated automatically before compaction.
|
||||
sibling_skills:
|
||||
- mental-model-ha
|
||||
- scope-recovery
|
||||
- agent-startup-and-context-ingestion
|
||||
- seat-continuity-and-handover
|
||||
---
|
||||
|
||||
+6
-9
@@ -9,17 +9,13 @@ metadata:
|
||||
distribution_scope: product-bound
|
||||
source_evidence: |
|
||||
Authored 2026-05-02 in response to founder-observed pattern: agents
|
||||
reaching for mental-model-ha on the words "mental model" when they're
|
||||
actually trying to form an initial mental model of OpenRig. This skill
|
||||
serves the legitimate need that mental-model-ha was being mis-routed for.
|
||||
See lab/skill-management-research/cycles/2026-05-02-forming-an-openrig-mental-model.md.
|
||||
Distinct from HA-pair mental-model preservation (which is a
|
||||
pair-of-seats coordination pattern). This skill serves the legitimate
|
||||
need to form an initial mental model of OpenRig as a system.
|
||||
sibling_skills:
|
||||
- openrig-user
|
||||
- openrig-operator
|
||||
- openrig-builder
|
||||
- openrig-architect
|
||||
- openrig-upgrade
|
||||
- ai-dev-workflows
|
||||
transfer_test: pending
|
||||
---
|
||||
|
||||
@@ -264,8 +260,9 @@ touching YAML for high-stakes rigs.
|
||||
|
||||
## What this skill is NOT for
|
||||
|
||||
- **HA pair compaction recovery.** That's `mental-model-ha`. Different
|
||||
skill, different scenario.
|
||||
- **HA pair compaction recovery.** Forming an initial mental model is a
|
||||
solo orientation task — different from the pair-of-seats coordination
|
||||
pattern that preserves a shared mental model across compactions.
|
||||
- **Operating a specific rig.** Specific rigs have their own DESIGN.md and
|
||||
CULTURE.md. Read those.
|
||||
- **Authoring a new rig.** Use the `openrig-architect` skill for that.
|
||||
|
||||
@@ -11,15 +11,8 @@ metadata:
|
||||
sibling_skills:
|
||||
- openrig-user
|
||||
- openrig-operator
|
||||
- openrig-builder
|
||||
- openrig-upgrade
|
||||
- forming-an-openrig-mental-model
|
||||
- ai-dev-workflows
|
||||
transfer_test: pending
|
||||
notes: |
|
||||
Description was already correct (starts with "Use when..."; lists specific authoring triggers including the diagnose-bad-rig case). Final sentence ("Covers the full authoring lifecycle from user intent to validated, launchable rig.") is workflow-summary-adjacent; on next iteration, consider trimming. For factory-adoption cycle, kept as-is to match product source-of-truth.
|
||||
naming_note: |
|
||||
Founder noted (2026-05-02 conversation): "openrig-architect is actually called rig-architect but it's meant to be openrig-architect." The factory/canonical-home skill name is now `openrig-architect` (renamed during Phase 3c graduation; sibling_skills lists across N1 reflect this). Product source path remains `openrig/packages/daemon/specs/agents/shared/skills/rig-architect/` until a coordinated product-source rename — that change requires updating product source + AgentSpec uses.skills references + downstream consumers; defer to a dedicated coordination cycle.
|
||||
---
|
||||
|
||||
# OpenRig Architect
|
||||
@@ -55,7 +48,7 @@ Load these before starting any design work. The quality of your output depends o
|
||||
**Read if present on this host:**
|
||||
|
||||
4. **Host-level doctrine file** (if your team maintains one — e.g., a HOST-TOPOLOGY doc that defines canonical rig classes, context-sharing patterns, and authoring SOPs for high-stakes rigs). If present, it supersedes the baseline process below for complex or high-stakes rigs (≥4 members, HA, managed-app, or shared/copied). Solo operators and small/focused rigs use the baseline below directly.
|
||||
5. **`building-agent-software` skill** if available in your skill catalog. Design principles for agent-facing tools and surfaces. Relevant when your rig ships a new CLI, service, or managed app.
|
||||
5. **Agent-facing software design principles** if your rig ships a new CLI, service, or managed app that agents will operate. Treat the operating surface as a context-engineering problem: every error message and help text gives the agent information to act on.
|
||||
|
||||
**Load as needed:**
|
||||
- Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
|
||||
|
||||
@@ -13,11 +13,8 @@ metadata:
|
||||
transfer_test: pending
|
||||
sibling_skills:
|
||||
- openrig-user
|
||||
- openrig-builder
|
||||
- openrig-architect
|
||||
- openrig-upgrade
|
||||
- forming-an-openrig-mental-model
|
||||
- ai-dev-workflows
|
||||
---
|
||||
|
||||
# OpenRig Operator
|
||||
@@ -45,8 +42,10 @@ Use this skill when you see:
|
||||
|
||||
Do not use this skill for normal product workflow routing, queue handling, or ordinary peer communication. Use `openrig-user` for that.
|
||||
|
||||
Do not use this skill to decide how to change OpenRig behavior. Use `openrig-builder` for build
|
||||
lane selection, feature lifecycle, doctrine rollout, and topology/build-system decisions.
|
||||
Do not use this skill to decide how to change OpenRig behavior. Changes
|
||||
to the OpenRig product (CLI, daemon, UI, specs) happen in the openrig
|
||||
product repo — operate that as a normal software project, not via
|
||||
this troubleshooting skill.
|
||||
|
||||
## First Checks
|
||||
|
||||
|
||||
@@ -10,11 +10,8 @@ metadata:
|
||||
Bootstrap skill — NPM install lands this in personal homes (~/.claude/skills/, ~/.agents/skills/) so agents have it at every boot.
|
||||
sibling_skills:
|
||||
- openrig-operator
|
||||
- openrig-builder
|
||||
- openrig-architect
|
||||
- openrig-upgrade
|
||||
- forming-an-openrig-mental-model
|
||||
- ai-dev-workflows
|
||||
transfer_test: pending
|
||||
notes: |
|
||||
Description was already correct (starts with "Use when..."; lists triggering domains without summarizing workflow). No frontmatter rewrite needed.
|
||||
@@ -27,8 +24,9 @@ metadata:
|
||||
This is an as-built guide to the shipped `rig` CLI.
|
||||
Use current code and `rig ... --help` as ground truth if anything here ever conflicts with older planning docs.
|
||||
|
||||
This is not the config-layer or builder guide. Use `control-plane-capabilities` for `rigx` and
|
||||
experimental overlays. Use `openrig-builder` when changing OpenRig behavior or doctrine.
|
||||
This is the daily-driving CLI guide for an OpenRig operator. It is not
|
||||
a guide to OpenRig internals or to changing OpenRig behavior — for that,
|
||||
work in the openrig product repo.
|
||||
|
||||
## Runtime-Gated Coordination Primitives
|
||||
|
||||
|
||||
@@ -8,23 +8,7 @@ metadata:
|
||||
distribution_scope: product-bound
|
||||
source_evidence: |
|
||||
Daemon-backed `rig queue` shipped in v0.2.0 (PL-004 Phase A) with handed-off-to / handed-off-from / state field shape. `rig queue` is canonical for new work; `rigx queue` is recovery-only fallback. The daemon enforces hot-potato strict-rejection at the API.
|
||||
sibling_skills:
|
||||
- workflow-runtime
|
||||
- watchdog
|
||||
- alignment-trace
|
||||
- looping-workflows
|
||||
- human-in-the-loop
|
||||
- attention-queue
|
||||
- dispatching-parallel-agents
|
||||
- subagent-driven-development
|
||||
- structured-ack-dispatch
|
||||
- control-plane-capabilities
|
||||
- status-not-chat-orchestrator
|
||||
- control-plane-queue
|
||||
- control-plane-watchdog
|
||||
- control-plane-workflows
|
||||
- control-plane-delivery-loop
|
||||
- control-plane-rollout-manager
|
||||
sibling_skills: []
|
||||
transfer_test: pending
|
||||
---
|
||||
|
||||
@@ -135,5 +119,4 @@ edge directly — don't fall back to stale pre-upgrade assumptions.
|
||||
|
||||
## See also
|
||||
|
||||
- `looping-workflows` skill — operating discipline for self-driving rig-shaped loops; queue-handoff is its current handoff substrate
|
||||
- `rig queue --help` — full CLI surface for queue items, handoffs, and closure-reason discipline
|
||||
-3
@@ -12,8 +12,6 @@ metadata:
|
||||
follow-on.
|
||||
sibling_skills:
|
||||
- claude-compaction-restore
|
||||
- mental-model-ha
|
||||
- scope-recovery
|
||||
- agent-startup-and-context-ingestion
|
||||
transfer_test: pending
|
||||
---
|
||||
@@ -136,5 +134,4 @@ enough to receive new work or needs re-handover.
|
||||
## See also
|
||||
|
||||
- `claude-compaction-restore` skill — packet-driven restore after Claude compaction
|
||||
- `mental-model-ha` skill — HA-pair pattern for preserving mental model across seat resets
|
||||
- `agent-startup-and-context-ingestion` skill — ingestion path for restore packets at agent boot
|
||||
@@ -11,15 +11,8 @@ metadata:
|
||||
sibling_skills:
|
||||
- openrig-user
|
||||
- openrig-operator
|
||||
- openrig-builder
|
||||
- openrig-upgrade
|
||||
- forming-an-openrig-mental-model
|
||||
- ai-dev-workflows
|
||||
transfer_test: pending
|
||||
notes: |
|
||||
Description was already correct (starts with "Use when..."; lists specific authoring triggers including the diagnose-bad-rig case). Final sentence ("Covers the full authoring lifecycle from user intent to validated, launchable rig.") is workflow-summary-adjacent; on next iteration, consider trimming. For factory-adoption cycle, kept as-is to match product source-of-truth.
|
||||
naming_note: |
|
||||
Founder noted (2026-05-02 conversation): "openrig-architect is actually called rig-architect but it's meant to be openrig-architect." The factory/canonical-home skill name is now `openrig-architect` (renamed during Phase 3c graduation; sibling_skills lists across N1 reflect this). Product source path remains `openrig/packages/daemon/specs/agents/shared/skills/rig-architect/` until a coordinated product-source rename — that change requires updating product source + AgentSpec uses.skills references + downstream consumers; defer to a dedicated coordination cycle.
|
||||
---
|
||||
|
||||
# OpenRig Architect
|
||||
@@ -55,7 +48,7 @@ Load these before starting any design work. The quality of your output depends o
|
||||
**Read if present on this host:**
|
||||
|
||||
4. **Host-level doctrine file** (if your team maintains one — e.g., a HOST-TOPOLOGY doc that defines canonical rig classes, context-sharing patterns, and authoring SOPs for high-stakes rigs). If present, it supersedes the baseline process below for complex or high-stakes rigs (≥4 members, HA, managed-app, or shared/copied). Solo operators and small/focused rigs use the baseline below directly.
|
||||
5. **`building-agent-software` skill** if available in your skill catalog. Design principles for agent-facing tools and surfaces. Relevant when your rig ships a new CLI, service, or managed app.
|
||||
5. **Agent-facing software design principles** if your rig ships a new CLI, service, or managed app that agents will operate. Treat the operating surface as a context-engineering problem: every error message and help text gives the agent information to act on.
|
||||
|
||||
**Load as needed:**
|
||||
- Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
|
||||
|
||||
@@ -10,13 +10,9 @@ metadata:
|
||||
Lifecycle Reboot/Recovery Scenario Matrix (Tier 1 complete; Tier 2
|
||||
human-gated). Codex auth-refusal surfaces as attention_required.
|
||||
sibling_skills:
|
||||
- topology-mutation-and-seat-management
|
||||
- seat-scaling-and-specialization
|
||||
- cross-host-rig-commands
|
||||
- sidecar-operator
|
||||
- rig-bundles-and-shareable-artifacts
|
||||
- specification-system
|
||||
- extension-and-user-workspace
|
||||
- openrig-user
|
||||
- openrig-operator
|
||||
- seat-continuity-and-handover
|
||||
transfer_test: pending
|
||||
---
|
||||
|
||||
@@ -116,8 +112,5 @@ different claims; don't conflate.
|
||||
|
||||
- `openrig-user` skill — CLI surface for `rig up / down / restore / etc.`
|
||||
- `openrig-operator` skill — operator-level discipline for OpenRig itself
|
||||
- `seat-continuity-and-handover` skill — sub-primitive: occupant-creation modes for restore (`resume` / `rebuild` / `fresh` / `failed`)
|
||||
- `session-source-fork` skill — `forked` continuity outcome for fork-based restore
|
||||
- `permission-and-capability-preflight` skill — provider-auth blocker → escalation path
|
||||
- `rig-lifecycle` skill — primitive dossier with full slice closure history + Total-Host Restore Product Rail v2 detail
|
||||
- `seat-continuity-and-handover` skill — occupant-creation modes for restore (`resume` / `rebuild` / `fresh` / `failed`)
|
||||
- `openrig/docs/as-built/architecture.md` (product reference doc) — daemon enforcement of restore-honesty rule
|
||||
@@ -11,15 +11,8 @@ metadata:
|
||||
sibling_skills:
|
||||
- openrig-user
|
||||
- openrig-operator
|
||||
- openrig-builder
|
||||
- openrig-upgrade
|
||||
- forming-an-openrig-mental-model
|
||||
- ai-dev-workflows
|
||||
transfer_test: pending
|
||||
notes: |
|
||||
Description was already correct (starts with "Use when..."; lists specific authoring triggers including the diagnose-bad-rig case). Final sentence ("Covers the full authoring lifecycle from user intent to validated, launchable rig.") is workflow-summary-adjacent; on next iteration, consider trimming. For factory-adoption cycle, kept as-is to match product source-of-truth.
|
||||
naming_note: |
|
||||
Founder noted (2026-05-02 conversation): "openrig-architect is actually called rig-architect but it's meant to be openrig-architect." The factory/canonical-home skill name is now `openrig-architect` (renamed during Phase 3c graduation; sibling_skills lists across N1 reflect this). Product source path remains `openrig/packages/daemon/specs/agents/shared/skills/rig-architect/` until a coordinated product-source rename — that change requires updating product source + AgentSpec uses.skills references + downstream consumers; defer to a dedicated coordination cycle.
|
||||
---
|
||||
|
||||
# OpenRig Architect
|
||||
@@ -55,7 +48,7 @@ Load these before starting any design work. The quality of your output depends o
|
||||
**Read if present on this host:**
|
||||
|
||||
4. **Host-level doctrine file** (if your team maintains one — e.g., a HOST-TOPOLOGY doc that defines canonical rig classes, context-sharing patterns, and authoring SOPs for high-stakes rigs). If present, it supersedes the baseline process below for complex or high-stakes rigs (≥4 members, HA, managed-app, or shared/copied). Solo operators and small/focused rigs use the baseline below directly.
|
||||
5. **`building-agent-software` skill** if available in your skill catalog. Design principles for agent-facing tools and surfaces. Relevant when your rig ships a new CLI, service, or managed app.
|
||||
5. **Agent-facing software design principles** if your rig ships a new CLI, service, or managed app that agents will operate. Treat the operating surface as a context-engineering problem: every error message and help text gives the agent information to act on.
|
||||
|
||||
**Load as needed:**
|
||||
- Domain-specific skills when designing specialist agents — find shipped skills inside the OpenRig installation under the `specs/agents/` tree
|
||||
|
||||
@@ -10,13 +10,9 @@ metadata:
|
||||
Lifecycle Reboot/Recovery Scenario Matrix (Tier 1 complete; Tier 2
|
||||
human-gated). Codex auth-refusal surfaces as attention_required.
|
||||
sibling_skills:
|
||||
- topology-mutation-and-seat-management
|
||||
- seat-scaling-and-specialization
|
||||
- cross-host-rig-commands
|
||||
- sidecar-operator
|
||||
- rig-bundles-and-shareable-artifacts
|
||||
- specification-system
|
||||
- extension-and-user-workspace
|
||||
- openrig-user
|
||||
- openrig-operator
|
||||
- seat-continuity-and-handover
|
||||
transfer_test: pending
|
||||
---
|
||||
|
||||
@@ -116,8 +112,5 @@ different claims; don't conflate.
|
||||
|
||||
- `openrig-user` skill — CLI surface for `rig up / down / restore / etc.`
|
||||
- `openrig-operator` skill — operator-level discipline for OpenRig itself
|
||||
- `seat-continuity-and-handover` skill — sub-primitive: occupant-creation modes for restore (`resume` / `rebuild` / `fresh` / `failed`)
|
||||
- `session-source-fork` skill — `forked` continuity outcome for fork-based restore
|
||||
- `permission-and-capability-preflight` skill — provider-auth blocker → escalation path
|
||||
- `rig-lifecycle` skill — primitive dossier with full slice closure history + Total-Host Restore Product Rail v2 detail
|
||||
- `seat-continuity-and-handover` skill — occupant-creation modes for restore (`resume` / `rebuild` / `fresh` / `failed`)
|
||||
- `openrig/docs/as-built/architecture.md` (product reference doc) — daemon enforcement of restore-honesty rule
|
||||
Reference in new issue
Block a user