Claude Skill

openspec-adopt

Adopt OpenSpec in a repo that lacks it: scaffold the openspec/ layout, write baseline specs describing the system as it exists today (from code, docs, and git history), and deliver the whole thing as a documentation-only PR. One-time per repo. Trigger when the user asks to adopt

LLM Mart · 0 points · 13 0 0

Virus-scanned Reviewed automatically before listing.

Full trust report

Download ConnorGriffin-skills-skills_drivers_openspec-adopt-afea794.zip · 1 KB

connorgriffin/skills 20 5 forks Updated 14d ago

Part of connorgriffin/skills — 25 skills

Install

skills CLI npx skills add https://github.com/ConnorGriffin/skills/tree/main/skills/drivers/openspec-adopt

Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install connorgriffin-skills@llmmart

Git git clone https://github.com/ConnorGriffin/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole connorgriffin/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

openspec-adopt

One-time OpenSpec adoption for a repo. Scaffolds the documentation baseline before any change proposals reference it.

Procedure

Check it is actually absent. An existing openspec/ means this skill has nothing to do; point at it and stop.
Require the pinned CLI. OpenSpec is target-repository development tooling. Confirm that global @fission-ai/openspec@1.11.0 is available as openspec; if it is absent, stop visibly before changing the target repository. Do not substitute another version or a package-runner invocation.
Initialize the v1 tree. Run openspec init --tools none at the target repository root. If initialization fails, stop visibly; do not construct a replacement tree. This produces openspec/config.yaml, openspec/specs/, and openspec/changes/archive/ without editor integrations.
Record repository context and operations. Put the repo purpose, tech stack, conventions, and commit/PR standards in openspec/config.yaml's context: and rules:. Source them from README, CONTRIBUTING, CI workflows, and observed code idioms. Record the repository's chosen archive timing and landing path at operations.archive.guidance; this is a repository-local convention, not a rule supplied by this skill.
Choose spec domains. Select two to four domains that partition the system by behavior. Name them for what the system does, not for directories. Examples: authentication, persistence, deployment, external integration.
Write baseline specs. For each domain, specs/<domain>/spec.md describing current behavior and contracts: what exists, what invariants hold, what other systems depend on. Ground every claim in code you read or history you checked; a baseline is worthless if it guesses. Reference concrete files only where the file is the contract (a schema, a versions manifest).
Validate the result. Run openspec validate --all --strict at the target repository root and fix every reported issue; do not deliver a baseline the CLI rejects.
Deliver as a PR. Branch, commit the initialized tree and baselines, gh pr create, documentation-only, no code changes. The PR body states the baseline is a starting point and invites corrections from the people who know the system.

Rules

Never bundle adoption with a functional change; the baseline gets reviewed on its own.
Never write a baseline for a repo you have not read; if the repo is too large to ground properly, propose fewer domains and say what was left unspecified.
Specs describe behavior and contracts, not implementation walkthroughs.
Do not add generated agent integrations, openspec/AGENTS.md, or openspec/project.md.

Files (skills)

agents

openai.yaml 215 B

interface:
  display_name: "OpenSpec Adopt"
  short_description: "Scaffold OpenSpec baseline specs describing the system as it exists today"
  default_prompt: "Use /openspec-adopt to set up OpenSpec for this repo."

SKILL.md 3.1 KB

---
name: openspec-adopt
description: "Adopt OpenSpec in a repo that lacks it: scaffold the openspec/ layout, write baseline specs describing the system as it exists today (from code, docs, and git history), and deliver the whole thing as a documentation-only PR. One-time per repo. Trigger when the user asks to adopt openspec, add openspec to a repo, scaffold openspec, or write baseline specs. Invoked as /openspec-adopt <org/repo or path>."
---

# openspec-adopt

One-time OpenSpec adoption for a repo. Scaffolds the documentation baseline before any change proposals reference it.

## Procedure

1. **Check it is actually absent.** An existing `openspec/` means this skill has nothing to do; point at it and stop.

2. **Require the pinned CLI.** OpenSpec is target-repository development tooling. Confirm that global `@fission-ai/openspec@1.11.0` is available as `openspec`; if it is absent, stop visibly before changing the target repository. Do not substitute another version or a package-runner invocation.

3. **Initialize the v1 tree.** Run `openspec init --tools none` at the target repository root. If initialization fails, stop visibly; do not construct a replacement tree. This produces `openspec/config.yaml`, `openspec/specs/`, and `openspec/changes/archive/` without editor integrations.

4. **Record repository context and operations.** Put the repo purpose, tech stack, conventions, and commit/PR standards in `openspec/config.yaml`'s `context:` and `rules:`. Source them from README, CONTRIBUTING, CI workflows, and observed code idioms. Record the repository's chosen archive timing and landing path at `operations.archive.guidance`; this is a repository-local convention, not a rule supplied by this skill.

5. **Choose spec domains.** Select two to four domains that partition the system by behavior. Name them for what the system does, not for directories. Examples: authentication, persistence, deployment, external integration.

6. **Write baseline specs.** For each domain, `specs/<domain>/spec.md` describing current behavior and contracts: what exists, what invariants hold, what other systems depend on. Ground every claim in code you read or history you checked; a baseline is worthless if it guesses. Reference concrete files only where the file is the contract (a schema, a versions manifest).

7. **Validate the result.** Run `openspec validate --all --strict` at the target repository root and fix every reported issue; do not deliver a baseline the CLI rejects.

8. **Deliver as a PR.** Branch, commit the initialized tree and baselines, `gh pr create`, documentation-only, no code changes. The PR body states the baseline is a starting point and invites corrections from the people who know the system.

## Rules

* Never bundle adoption with a functional change; the baseline gets reviewed on its own.
* Never write a baseline for a repo you have not read; if the repo is too large to ground properly, propose fewer domains and say what was left unspecified.
* Specs describe behavior and contracts, not implementation walkthroughs.
* Do not add generated agent integrations, `openspec/AGENTS.md`, or `openspec/project.md`.