/openspec-plus-design

name: openspec-plus-design
description: "MANDATORY skill that activates whenever the OpenSpec design phase begins. Triggers: /opsx-new or /opsx-continue runs; openspec-new-change, openspec-continue-change, or openspec-explore is active; `openspec instructions design` is invoked; or the user wants to create, update, review, refine, or discuss an OpenSpec design document."
metadata:
  version: 1.6.1
  priority: high
  disable-user-invocation: true

OpenSpec Plus Design

Mission

Strengthen OpenSpec design with brainstorming patterns. Prevent premature architectural convergence — explore alternatives, compare tradeoffs, recommend, get user selection, build incrementally, validate vs proposal (and any existing spec) before writing design.md.

---

> **This skill is RIGID. Do NOT write any design file before all workflow phases complete through Phase 3 section approvals. After writing, reviewer subagent is MANDATORY — skipping review is a skill violation.**

**Red flags — STOP, you are about to violate this skill:**

• "There's only one obvious approach"
• "I'll generate the full design and let the user review at the end"
• "The user is in a hurry, I'll skip selection"
• "I'll group all sections into one approval question"
• "I have approval for the direction, so I can write the whole document now"
• "The proposal (and spec, if it exists) is fresh, I don't need the reviewer subagent"
• "Spec doesn't exist yet, I can sneak some requirements into the design"
• "The design looks fine to me, I'll skip the reviewer subagent"
• "Reviewer flagged minor issues, I'll re-dispatch after fixing to confirm"

---

Inputs Available

OpenSpec allows either order after proposal:

• `proposal → spec → design` (spec exists)
• `proposal → design → spec` (no spec yet)

When this skill runs:

• ALWAYS read approved proposal — authoritative for intent and capabilities
• If spec exists, ALWAYS read it — design MUST align with it
• If no spec yet, design works from proposal capabilities only — do NOT capture detailed requirements (that's spec phase, runs after design)
• Design MUST align with proposal AND any existing spec

---

Workflow

Five phases. NEVER skip, merge, or reorder.

Phase 0: Schema & Template Resolution
Phase 1: Explore Design Approaches
Phase 2: Select Design Direction
Phase 3: Build Design Sections
Phase 4: Generate Design

---

Workflow Visibility (MANDATORY)

Display workflow phases via task tool at start; update as each phase completes.

---

Core Principles

• **Explore Before Converging** — never commit to first approach; always explore alternatives.
• **User Owns The Final Direction** — model recommends, user decides.
• **Build Design Collaboratively** — in `sequential` mode, NEVER generate full design at once; build incrementally, review each section with user (`batch` mode: generate all, one consolidated review — see Phase 3).
• **Design Before Documentation** — validate design (including alignment with proposal and any existing spec) before writing design.md.
• **YAGNI — Complexity Must Be Justified** — every abstraction, layer, indirection MUST serve a real present need.
• **Improve, Don't Refactor** — targeted improvements to existing code only when they serve the change; never propose unrelated refactoring.
• **Respect Project Standards** — read project instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, equivalents) at Phase 1 start; design MUST respect project conventions; conflicts → surface to user, never silently override.

Use Stable Libraries Before Custom

Survey ecosystem before proposing custom code. For each significant component (parsing, validation, HTTP, retries, scheduling, queuing, auth, crypto, dates, money, observability, etc.):

1. Identify 2-3 candidate libraries 2. Evaluate by: maintenance, stability (semver, breaking changes), popularity, license, security (CVEs, audits), compatibility (runtime, version, existing deps) 3. Library fits → propose with rationale; don't write custom for the same purpose 4. Choosing custom → justify why no library fits (domain-specific, license, dep tree, no maintained option, perf constraints unmet)

Respect any approved-library list from project instruction files. Don't propose libraries the project rejected.

**Human-In-The-Loop Approval:** For ANY new library introduction or replacement, surface to user via question tool: 2-3 candidates evaluated, recommended choice + rationale, accepted tradeoffs, alternatives rejected + why. Do NOT commit a library in the design until user approves. Libraries already in use don't need re-approval.

• **Stay At Architecture Level** — design captures HOW (architecture, patterns, integration); NEVER capture WHAT (detailed requirements, scenarios, acceptance criteria) — that's spec phase.

---

Phase 0: Schema & Template Resolution

Run FIRST, before any exploration:

1. Run:

   openspec instructions design --change <name> --json

Extract: `template` (structural authority; sections you MUST fill), `instruction` (per-section guidance; what content each section needs), `rules` (project constraints to honor). Parse template sections (H2/H3 headers + HTML comments) — these are your **information requirements**; Phase 3 design concerns MUST produce enough substance to fill every section. If the template has sections the hardcoded 5+1 concerns don't cover, add dynamic concerns during Phase 3. 2. Read `openspec/.plus/config.yaml` (missing/unreadable/unrecognized → defaults): `settings.questionMode` (`sequential` default; `batch` groups Phase 1/Library Resolution questions and collapses Phase 3 into one generate-all-then-review round — see Phase 1 and Phase 3 below).

---

Phase 1: Explore Design Approaches

**Pre-existing answers:** If recent conversation already covers architectural decisions, approaches discussed, constraints noted, or integration seams — via prior exploration, a detailed initial request, or any other source — incorpor