Adopt OpenSpec in Any Repo with a One-Time Agent Skill

Where this fits

You have a repository that has been running for months or years, and you want to introduce OpenSpec for change proposals. Manually reconstructing the system's current behavior from code, docs, and git history is tedious and error-prone. The openspec-adopt skill automates that one-time bootstrap: it scaffolds the openspec/ layout, writes baseline specs describing the system as it exists today, and delivers everything as a clean, documentation-only pull request.

Why agents benefit

• Deterministic preflight checks: The skill stops visibly if openspec/ already exists or if the pinned CLI (@fission-ai/openspec@1.11.0) is missing—no silent partial changes.
• Faithful baseline extraction: It reads code structure, existing docs, and git history to produce baseline specs that reflect reality, not assumptions.
• Safe, reviewable output: The entire result is a documentation-only PR, so human reviewers can focus on the spec content without mixing in code changes.
• No toolchain side effects: Uses openspec init --tools none, avoiding unnecessary integration with build tools or package managers.
• Repeatable across repos: The same skill can be invoked on any target repository with a single command, making it a reusable pattern for large codebases.

Practical scenarios

Onboarding a legacy monorepo

A team maintains a 5-year-old monorepo with scattered READMEs and no central architecture doc. Running /openspec-adopt <org/repo> generates baseline specs for each service, capturing current endpoints, data models, and key flows—giving the team a starting point for future change proposals.

Preparing an open-source project for contributors

An open-source maintainer wants to lower the barrier for contributions. By adopting OpenSpec, they get a structured way to propose changes. The skill writes initial specs from the existing codebase, so new contributors can immediately see how the system is organized and where to add proposals.

Migrating from ad-hoc ADRs

A startup has been using lightweight ADRs but wants to move to OpenSpec's proposal lifecycle. The skill reads those ADRs and the current code to produce baseline specs that align with what's actually deployed, making the migration seamless and auditable.

Add it to your agent workflow

Install the skill globally with:

npx skills add ConnorGriffin/skills --skill openspec-adopt

Then invoke it on any target repository:

/openspec-adopt my-org/my-repo

The agent will check prerequisites, scaffold the tree, write baseline specs, and open a documentation-only PR for review.

Compare before adopting

Before relying on this skill, compare it against alternatives: check its GitHub activity (20 stars, active author), the freshness of its pinned CLI version, and whether it fits your team's spec workflow. Also consider if you need a more custom baseline generation or prefer a manual approach. The skill's strict “stop if anything is off” behavior makes it safe to try without side effects.

Why it is worth tracking

This skill addresses a real pain point—bootstrapping OpenSpec on existing codebases—and does so with a disciplined, non-destructive procedure. Its quality signals include a clear README, a pinned CLI version, and a design that favors explicit failure over guesswork. As OpenSpec adoption grows, this skill becomes a natural companion for teams looking to standardize change proposals. Evaluate it the next time you need to bring a legacy repo under spec control. For more context, see OpenAgentSkill's entry.