/openspec-plus-proposal

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

OpenSpec Plus Proposal

Mission

Brainstorming-style interactive discovery for OpenSpec proposals. Produce a lean Why / What Changes / Capabilities / Impact proposal at intent level — never sliding into design, spec, or implementation.

OpenSpec provides the format and template (resolved dynamically in Phase 0). This skill provides the process discipline: five-lens Q&A, decomposition check, scope discipline, subagent review.

---

Inputs

• User request — authoritative for intent
• Existing proposals in `openspec/changes/` — for terminology and convention only
• NEVER read source code — proposal is intent, not implementation grounding

---

Workflow

Four phases. NEVER skip, merge, or reorder.

Phase -1: Auto-Update Check (once per session)
Phase 0: Schema & Template Resolution
Phase 1: Interactive Discovery (5-lens Q&A)
Phase 2: Write & Artifact Compliance Review

---

Workflow Visibility (MANDATORY)

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

---

Core Principles

• **Understand Before Defining** — seek the problem before describing the change; never jump to proposed solutions.
• **Goals Before Solutions** — solution language ("add Redis", "use Postgres") → redirect to the underlying problem and goal.
• **Scope Boundaries Are Critical** — non-goals as deliberate as in-scope items; strong non-goals reduce future scope creep.
• **YAGNI — No Speculative Scope** — every scope item traces to a stated user need or stakeholder concern.
• **Respect Project Standards** — read project instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, equivalents) at Phase 1 start; use project terminology; conflicts → surface to user, never silently override.

---

Phase -1: Auto-Update Check (MANDATORY — once per session)

**Run FIRST, before Phase 0. Skip if already run this session.**

1. Read `openspec/.plus/config.yaml`:

• `settings.autoUpdateCheck` is `false` → **skip Phase -1 entirely, proceed to Phase 0**
• Missing/unreadable, or not `false` → continue

2. Read `openspec/.plus/last-update-check`:

• File exists AND timestamp is within 7 days of today → **skip immediately, proceed to Phase 0**
• Missing or older than 7 days → continue:
• Fetch `https://api.github.com/repos/sudokar/openspec-plus/releases/latest` (single JSON object). Read the `tag_name` field and strip the leading `v` if present. This is the remote version.
• Compare remote version with `openspec/.plus/VERSION` (local)
• If remote > local → **prompt the user** using the question tool:

> 🔔 OpenSpec Plus **v{remote}** is available (you have **v{local}**).

• Option 1: **Upgrade (Recommended)**
• Option 2: **Upgrade later**
• If user selects **Upgrade** → display the install/update link: `https://github.com/sudokar/openspec-plus#-install--update` and STOP. Do NOT continue to Phase 0 — the user should run the install/update prompt first and restart the session.
• If user selects **Upgrade later** → proceed to Phase 0 normally.
• Write current timestamp to `openspec/.plus/last-update-check`

3. Network/file errors → silently continue. NEVER block the workflow for network issues — proceed to Phase 0.

Mark Phase -1 complete, proceed to Phase 0.

---

Phase 0: Schema & Template Resolution

Run FIRST (after Phase -1), before any questions:

1. Run:

   openspec instructions proposal --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**; every section = information you MUST collect during Phase 1. If a section needs data the five lenses don't cover, add questions for it. 2. Read `openspec/.plus/config.yaml` (missing/unreadable/unrecognized → defaults): `settings.questionMode` (`sequential` default; `batch` groups Phase 1's five lenses into fewer question-tool rounds instead of one at a time).

---

Phase 1: Interactive Discovery

**Pre-existing answers:** If recent conversation already answers any of the five lenses (Problem & Why, Goals, Scope & Capabilities, Non-Goals, Impact) — via prior exploration, a detailed initial request, or any other source — state the resolved answer in your analysis and SKIP that lens's question. Ask ONE question at a time only for unresolved or partial lenses (`batch` mode: present all unresolved lenses together instead — see below). NEVER re-ask answered questions.

Read in this order:

1. **Project-level instruction files first** — `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or equivalents at project root, `.claude/`, `.opencode/`, or `docs/`. These capture terminology conventions and project shape that should inform proposal language. 2. Existing proposals and changes in `openspec/changes/` for terminology and structural convention.

NEVER read source code.

If the request describes multiple independent subsystems (e.g., "add chat, file storage, billing, analytics"): STOP. Surface to user. Help decompose: what are the independent pieces, how do they relate, what order to build? Each sub-change gets its own proposal → spec → design → tasks cycle. Begin the first sub-change through normal flow. NEVER write a single proposal covering multiple independent subsystems.

Use the **question tool**, ONE question at a time. Cover these lenses until each is answered:

1. **