Skip to content

openspec: convert skills to runbooks #761

Description

@toejough

Observed

The engram repository includes six in-repo skills for OpenSpec operations:

  • openspec:apply
  • openspec:archive
  • openspec:explore
  • openspec:propose
  • openspec:sync
  • openspec:update

These are currently stored as SKILL.md files in .claude/skills/openspec-*/ and are candidates for the runbook-note conversion pattern established in #756 (parent issue for converting remaining skills).

Repro

To verify the six openspec skills still exist as-is:

  1. Locate the skill files: git ls-files .claude/skills/openspec-*/SKILL.md
  2. Confirm all six are present:
    • .claude/skills/openspec-apply-change/SKILL.md
    • .claude/skills/openspec-archive-change/SKILL.md
    • .claude/skills/openspec-explore/SKILL.md
    • .claude/skills/openspec-propose/SKILL.md
    • .claude/skills/openspec-sync-specs/SKILL.md
    • .claude/skills/openspec-update-change/SKILL.md

Expected

Convert the six openspec skills into runbook vault notes following the pattern established by #757/#758/#759 (route, please, curate) and #760 (recall/learn/write-memory production promotion):

  1. Produce validated runbook bodies — from-scratch conversion (no prior eval fixture exists, unlike route which had runbook-shim-follow-frame eval work) for each of the six skills: one top-level runbook per skill plus wikilinked sub-runbooks where a single body doesn't fit comfortably within one query item.
  2. Retrieval validation — confirm task-phrase and situation-phrase queries surface each converted runbook top-ranked (task 3.3's pattern: no LLM spend, pure retrieval check).
  3. Promotion — move validated runbook bodies into agent-instructions/skills/openspec-<name>/ directory (mirroring the pattern used for recall/learn/write-memory) and retire the original SKILL.md reference, updating any imports or skill references.
  4. Verification re-run — optionally, run a shim-only eval stage against one or more of the converted runbooks (following dev/eval/cumulative/runbook_vs_skill/phase2/probe_phase2.py --shim-only methodology) to confirm agent-following parity with the original skill behavior; note any new red_flags field entries needed for patterns the openspec skills already call out.

Context

This is a sibling issue split from #756 (parent: "Convert route, please, and curate skills to runbooks"), following the same conversion work that has been applied to recall (#760), learn (#760), write-memory (#760), and route (#757, promoting a validated eval fixture), plus in-progress work on please (#758) and curate (#759).

Unlike #757 (route), which promoted a validated runbook body from prior runbook-shim-follow-frame eval work, the openspec skills have no existing validated runbook bodies yet — this is a from-scratch conversion proposal with no prior eval work behind it. The skills themselves live in this repo (owned by engram), so the conversion work is in-scope for engram, not a vendor proposal.

Related:

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestneeds-triageMaintainer needs to evaluate this issue

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions