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.

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. Problem & Why — what problem exists, why it matters, what happens without action
2. Goals (not solutions) — desired outcome; if request is phrased as a solution, what is the underlying goal
3. Scope & Capabilities — high-level changes; capabilities added, modified, or removed
4. Non-Goals — what is explicitly NOT in scope; scope creep to prevent
5. Impact — affected systems, files, teams, or workflows

In sequential mode (default), NEVER batch questions. NEVER assume answers. Always include your recommended answer with rationale on every question — never a bare question without a recommendation.

batch mode (settings.questionMode: batch): present all unresolved lenses together — one question-tool call per lens up to its multi-question cap, or one combined numbered message if the tool allows only one question per call. Wait for one combined reply; map answers back by lens. Same real answers and recommendations as sequential — never skip or assume a lens.

If the user's answer introduces a new decision point or leaves something partially unresolved, follow that branch with a targeted follow-up before advancing to the next lens (in batch mode, defer the follow-up to the next batch round). A lens is fully resolved only when no dependent decision within it remains open.

If a fact can be determined from existing artifacts, project files, or the environment, look it up — do not ask the user for discoverable information.

Once all five lenses answered, summarize for the user: problem (one sentence), outcome (one sentence), in-scope capabilities, non-goals, impact areas. In sequential mode, explicitly ask the user to confirm shared understanding before proceeding to Phase 2 — do NOT advance on silence or implied agreement. In batch mode, skip this extra question — the summary was already built from the user's one combined reply; proceed to Phase 2.

Phase 1 Complete Checks:

• Mid-discovery scope check: re-evaluate — did scope grow beyond a single cohesive change during Q&A? If so, decompose before writing.
• Template coverage check: verify every template section (from Phase 0) has collected substance to fill it; ask targeted questions if any section lacks substance (batch: combine into one round).
• Rules compliance check: review rules from Phase 0; if any rule constrains what can be proposed, surface the conflict to the user before writing (batch: fold multiple conflicts into one round).