openspec-plus-proposal

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.