042-planning-openspec
This skill automates the conversion of implementation plans from `*.plan.md` files into OpenSpec change artifacts. Use it when you need to validate OpenSpec CLI availability, initialize or reuse an OpenSpec project, and create or update change proposals with design specifications and task checklists. The workflow includes input analysis, installation guidance for macOS/Linux/Windows, project bootstrapping, and validation commands, with concrete examples from the `examples/requirements-examples/problem1/requirements/openspec` directory structure.
git clone --depth 1 https://github.com/jabrena/cursor-rules-java /tmp/042-planning-openspec && cp -r /tmp/042-planning-openspec/skills/042-planning-openspec ~/.claude/skills/042-planning-openspecSKILL.md
# OpenSpec Change Planning from `*.plan.md` Guide the process of turning an implementation plan (`*.plan.md`) into an OpenSpec change workflow. **This is an interactive SKILL**. It verifies CLI availability, initializes OpenSpec when needed, and then creates or updates a change with proposal, design, tasks, and spec deltas. **What is covered in this Skill?** - Input analysis from `*.plan.md` (scope, change-id candidate, affected capabilities) - Installation and availability checks for OpenSpec CLI - Recommended installation paths on macOS, Linux, and Windows using npm - OpenSpec project bootstrapping with `openspec init` - Existing-project workflow using `openspec list`, `openspec status`, `openspec show` - Validation and completion flow with `openspec validate --all` and `openspec archive` - Example-root workflow at `examples/requirements-examples/problem1/requirements/openspec` ## Constraints Always execute OpenSpec commands from the parent directory that contains the `openspec/` folder. Do not invent requirements not present in the `*.plan.md`; convert plan intent into explicit OpenSpec change artifacts. - **MUST**: Start by reading and summarizing the provided `*.plan.md` - **MUST**: Check CLI availability with `openspec --version` before any OpenSpec operation - **MUST**: If OpenSpec is missing, provide macOS, Linux, and Windows install guidance via npm command - **MUST**: Offer `openspec init` when no OpenSpec project exists - **MUST**: When creating a new OpenSpec project, run plain `openspec init` only (do not use `--tools ...` options) - **MUST**: Use a stable change-id (for example: `add-dark-mode`) for status/show/archive commands - **MUST**: Run `openspec validate --all` before archiving - **MUST**: When a feature/change is completed (all checklist tasks done), guide the user to archive it (for example: `openspec archive us-001-god-analysis-api`) - **MUST**: In `tasks.md`, generate a single OpenSpec checklist (`- [ ]` / `- [x]`) only; do not add a second table-based task list - **MUST**: Explain whether the workflow creates a new change or updates an existing one - **EDGE CASE**: If request scope is ambiguous, stop and ask a clarifying question before applying changes - **EDGE CASE**: If required inputs, files, or tooling are missing, report what is missing and ask whether to proceed with setup guidance ## When to use this skill - Convert `*.plan.md` into OpenSpec - Add change proposal from plan - Update existing OpenSpec project - Initialize OpenSpec in requirements folder - Validate and archive OpenSpec change ## Workflow 1. **Read and summarize plan input** Read `references/042-planning-openspec.md` and the provided `*.plan.md`, then summarize scope and identify candidate change-id and affected capabilities. 2. **Check OpenSpec CLI and install gate** Run `openspec --version`; if missing, provide npm installation guidance for macOS, Linux, and Windows before proceeding. 3. **Initialize or detect OpenSpec project** From the parent directory containing `openspec/`, run project checks and offer `openspec init` (without `--tools`) when initialization is needed. 4. **Create or update change artifacts** Explain whether this is a new or existing change, then create/update proposal, design, tasks, and spec deltas using a stable change-id. 5. **Validate and close workflow** Run `openspec validate --all`; when checklist tasks are complete, guide the user to archive the change with `openspec archive <change-id>`. ## Reference For detailed guidance, examples, and constraints, see [references/042-planning-openspec.md](references/042-planning-openspec.md).
Use when you need to generate a checklist document with Java system prompts, following the embedded template exactly and producing INVENTORY-SKILLS-JAVA.md in the project root. This should trigger for requests such as Create Java system prompts checklist; Generate INVENTORY-SKILLS-JAVA.md; Use @001-skills-inventory. Part of cursor-rules-java project
Use when you need to generate a checklist document with embedded agents inventory, following the embedded template exactly and producing INVENTORY-AGENTS-JAVA.md in the project root. This should trigger for requests such as Create embedded agents inventory checklist; Generate INVENTORY-AGENTS-JAVA.md; Use @002-agents-inventory. Part of cursor-rules-java project
Use when you need to install the embedded robot agents into either .cursor/agents or .claude/agents, selecting the destination interactively and copying the embedded agent definitions from project assets. This should trigger for requests such as Install embedded agents; Bootstrap .cursor/agents; Bootstrap .claude/agents; Copy robot agents. Part of cursor-rules-java project
Guides the creation of agile epics with comprehensive definition including business value, success criteria, and breakdown into user stories. Use when the user wants to create an agile epic, define large bodies of work, break down features into user stories, or document strategic initiatives. This should trigger for requests such as Create an agile epic; Write an epic; I need to create an epic; Define an epic; Epic definition. Part of cursor-rules-java project
Guides the creation of detailed agile feature documentation from an existing epic. Use when the user wants to split an epic into feature files, derive features with scope and acceptance criteria, or plan feature documentation for stakeholders or engineering. This should trigger for requests such as Create features from an epic; Split epic into features; Feature files from epic; Derive features from epic. Part of cursor-rules-java project
Guides the creation of agile user stories and Gherkin feature files. Use when the user wants to create a user story, write acceptance criteria, define Gherkin scenarios, or author BDD feature files. This should trigger for requests such as Create a user story; Write a user story; I need to write a user story. Part of cursor-rules-java project
Use when you need to generate Architecture Decision Records (ADRs) for a Java project through an interactive, conversational process that systematically gathers context, stakeholders, options, and outcomes to produce well-structured ADR documents. This should trigger for requests such as Generate ADR; Create Architecture Decision Record; Document architecture decision; Architecture Decision Record for Java. Part of cursor-rules-java project
Facilitates conversational discovery to create Architectural Decision Records (ADRs) for functional requirements covering CLI, REST/HTTP APIs, or both. Use when the user wants to document command-line or HTTP service architecture, capture functional requirements, create ADRs for CLI or API projects, or design interfaces with documented decisions. This should trigger for requests such as Create ADR for functional requirements; Document functional requirements; Capture functional requirements; Generate functional requirements in an ADR. Part of cursor-rules-java project