pavilio-openspec-storage

Defines storage layout and backend resolution rules for OpenSpec change artifacts.

Updated Apr 19, 2026
One-click install
npx skills add https://github.com/gmotyl/pavilio --skill pavilio-openspec-storage-gmotyl
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: pavilio-openspec-storage
Source: https://github.com/gmotyl/pavilio/tree/main/skills/pavilio-openspec-storage
Command: npx skills add https://github.com/gmotyl/pavilio --skill pavilio-openspec-storage-gmotyl

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams using OpenSpec across multiple repositories need a single, consistent answer to where change proposals, designs, tasks, and specs live — inside an adopted repository or in a project-local store — without each workflow skill re-deciding it or accidentally writing into unadopted repos. ## Core Features & Use Cases - Native tree layout reference: Documents the canonical openspec/changes/ and openspec/specs/ directory structure, where active work is derived from un-archived change directories with no pointer files. - Per-scope backend resolution: Implements an ask-once, persist, reuse flow that saves { mode, root } per repository in repos.json, with project-wide changes defaulting to the project store. - Skill-owned fold and archive: Describes the git-mv plus markdown fold archival procedure (ADDED appends, MODIFIED rewrites, REMOVED deletes) with all-or-nothing failure semantics and no external CLI. - Use Case: When running a grill or writing-plans workflow on a linked repository, the skill checks repos.json for a saved OpenSpec config, asks one adoption question if unconfigured, persists the answer, and only then writes artifacts to the resolved root. ## Quick Start Ask the AI to resolve and persist the OpenSpec storage backend for a linked repository before writing any change artifacts.

Frequently Asked Questions about pavilio-openspec-storage

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I configure where OpenSpec artifacts are stored per repository?▼

Backend resolution runs before any artifact write: the skill checks repos.json for a saved openspec config, and if unconfigured asks one question about native adoption versus a project-local store. The validated mode and optional relative root are persisted first, then reused silently by later workflows.

What is the difference between native and store backends in OpenSpec?▼

Native places the openspec tree inside the repository itself and is used only when that repo has adopted OpenSpec. Store keeps an identically shaped tree under the project workspace at plans/<repo>/openspec/, so unadopted repositories never receive planning files.

How does OpenSpec archival work without a CLI?▼

Archival is skill-owned: delta specs are folded into living specs (ADDED appends, MODIFIED rewrites, REMOVED deletes), then the change directory is git-mv'd into changes/archive/YYYY-MM-DD-<id>/. A fold or validation failure leaves both the active change and living specs unchanged.

Can one change span multiple repositories in OpenSpec?▼

Yes, a multi-repository change shares one change identifier across repos, but each repository owns its artifacts and resolves its backend independently. The shared identifier is coordination metadata only and never permits writing outside each resolved root.

Why did my OpenSpec change disappear from the Plans tab?▼

A common cause is a store root written as a workspace-relative path like projects/<project>/plans/<repo>, which resolves against the project directory and points nowhere. Omit root entirely so the default plans/<repo>/ is used, since roots must always be relative.

Does switching an OpenSpec backend migrate existing artifacts?▼

No, switching between store and native only validates and saves the new mode and root. Relocating existing history is a separate explicit migration operation handled by the pavilio-openspec-migrate skill, never a side effect of a config change.