# Openspec Workflows

> Create OpenSpec changes from implementation plans, and validate existing changes before implementation. Use when the user wants to turn a plan document into an OpenSpec change proposal, or validate that a change is safe to implement (breaking changes, dependency analysis). Use when this capability is needed.

- Skill: `tomevault-io/openspec-workflows` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/openspec-workflows`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/openspec-workflows/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/openspec-workflows

---


Two workflows for managing OpenSpec changes at the proposal stage.

**Input**: Optionally specify a workflow name (`create` or `validate`) and a target (plan path or change ID). If omitted, ask the user which workflow they need.

## Workflow Selection

Determine which workflow to run:

| User Intent | Workflow | Reference |
|---|---|---|
| Turn a plan into an OpenSpec change | **Create Change from Plan** | `references/create-change-from-plan.md` |
| Validate a change before implementation | **Validate Change** | `references/validate-change.md` |

If the user's intent is unclear, use **AskUserQuestion** to ask which workflow they need.

## Create Change from Plan

Turns an implementation plan document into a fully formed OpenSpec change with proposal, specs, design, and tasks — including GitHub issue creation for public repos.

**When to use**: The user has a plan document (typically in `specfact-cli-internal/docs/internal/implementation/`) and wants to create an OpenSpec change from it.

**Load** `references/create-change-from-plan.md` and follow the full workflow.

**Key steps**:
1. Select and parse the plan document
2. Cross-reference against existing plans and validate targets
3. Resolve any issues interactively
4. Create the OpenSpec change via `opsx:ff` skill
5. Review and improve: enforce TDD-first, add git worktree tasks (worktree creation first, PR last, cleanup after merge), validate against `openspec/config.yaml`
6. Create GitHub issue (public repos only)

## Validate Change

Performs dry-run simulation to detect breaking changes, analyze dependencies, and verify format compliance before implementation begins.

**When to use**: The user wants to validate that an existing change is safe to implement — check for breaking interface changes, missing dependency updates, and format compliance.

**Load** `references/validate-change.md` and follow the full workflow.

**Key steps**:
1. Select the change (by ID or interactive list)
2. Parse all change artifacts (proposal, tasks, design, spec deltas)
3. Simulate interface changes in a temporary workspace
4. Analyze dependencies and detect breaking changes
5. Present findings and get user decision if breaking changes found
6. Run `openspec validate <change-id> --strict`
7. Create `CHANGE_VALIDATION.md` report

## Guardrails

- Read `openspec/config.yaml` for project context and rules
- Read `CLAUDE.md` for project conventions
- Never modify production code during validation — use temp workspaces
- Never proceed with ambiguities — ask for clarification
- Enforce TDD-first ordering in tasks (per config.yaml)
- Enforce git worktree workflow: worktree creation first task, PR creation last task, worktree cleanup after merge — never switch the primary checkout away from `dev`
- Only create GitHub issues in the target repository specified by the plan

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/nold-ai) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->