playbooks

home / skills / bahayonghang / my-claude-code-settings / interview-openspec

interview-openspec skill

/content/skills/workflow-skills/interview-openspec

This skill guides you through a phased OpenSpec interview to generate proposal, specs, design, and tasks artifacts for new changes.

npx playbooks add skill bahayonghang/my-claude-code-settings --skill interview-openspec

Review the files below or copy the command above to add this skill to your agents.

Files (6)
SKILL.md
2.0 KB
---
name: interview-openspec
description: Create OpenSpec artifacts (proposal, specs, design, tasks) through Socratic interview. Use when starting a new OpenSpec change that needs structured requirements elicitation.
argument-hint: [change-name-or-description]
allowed-tools: Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion, TodoWrite
---

# OpenSpec Interview

Phased Socratic interview that produces OpenSpec artifacts incrementally. Each phase maps to one artifact; user may exit after any phase.

## Steps

1. If `$ARGUMENTS` is empty, use `AskUserQuestion` to ask what to build. Derive kebab-case name.
2. Run `openspec new change "<name>"` and `openspec status --change "<name>" --json`.
3. Read `resources/INTERVIEW_PRINCIPLES.md` and `resources/OPENSPEC_INTERVIEW_DIMENSIONS.md`.
4. Execute 4 interview phases. Each phase: ask via `AskUserQuestion` (2-4 convergent options), then write artifact. If user says "skip", advance with gathered info.
   - **Phase 1 → proposal.md**: Business goals, MVP scope, risk preview, capability identification.
   - **Phase 2 → specs/\<cap\>/spec.md**: Requirements per capability in WHEN/THEN scenarios (ADDED/MODIFIED/REMOVED).
   - **Phase 3 → design.md**: Technical decisions, architecture tradeoffs (Context/Goals/Non-Goals/Decisions).
   - **Phase 4 → tasks.md**: Implementation breakdown as hierarchical checkbox list.
5. Use `openspec instructions <artifact> --change "<name>" --json` before writing each artifact. Fallback: `resources/ARTIFACT_TEMPLATES.md`.
6. If high-risk operations detected, read `resources/RISK_PROTECTION.md` and get explicit authorization.
7. On completion, run `openspec status --change "<name>"`. Guide user to `/opsx:apply` or `/opsx:verify`. See `resources/EXAMPLES.md` for a full walkthrough.

## Constraints

- Double-quote paths, use `/` separator. Prefer `rg` over `grep`.
- **Never** auto-execute Git write operations (`commit`, `push`).
- All questions via `AskUserQuestion` with clickable `options` — no plain-text A/B/C.

Overview

This skill conducts a phased Socratic interview to produce OpenSpec artifacts incrementally. It guides you from an initial proposal through specs, design, and implementation tasks, letting you stop after any phase. The skill enforces safety checks and artifact templates so outputs match OpenSpec conventions.

How this skill works

When invoked it prompts you to name the change (or derives a kebab-case name from your input) and initializes a change record with openspec commands. It runs four interview phases: proposal, capability specs, design, and tasks, asking concise multiple-choice questions and writing each artifact using OpenSpec instructions or fallback templates. It detects high-risk operations and requests explicit authorization before proceeding.

When to use it

  • Starting a new OpenSpec change that needs structured requirements elicitation.
  • When you need a clear, phased output: proposal.md, spec.md, design.md, and tasks.md.
  • If multiple stakeholders must converge on goals, scope, and risks before implementation.
  • When you want machine-friendly artifacts aligned to OpenSpec tooling and review workflows.

Best practices

  • Answer the Socratic prompts in the order presented to preserve context and artifact traceability.
  • Provide concrete examples and priorities when selecting options to get more actionable specs.
  • Use the built-in risk prompts and authorize explicitly for high-risk items; do not skip safety checkpoints.
  • Keep capability names short and kebab-case; the skill derives file paths from those names.
  • Review each generated artifact and iterate by re-running relevant phase questions rather than editing raw files directly.

Example use cases

  • Kick off a feature change by producing a proposal with business goals and MVP scope.
  • Elicit WHEN/THEN requirements for a specific capability and generate specs/<cap>/spec.md.
  • Capture architectural decisions and tradeoffs in design.md for cross-team design review.
  • Break a change into hierarchical checkbox tasks.md for planning and handoff to engineering.

FAQ

Can I stop after one phase and return later?

Yes. Each phase produces a standalone artifact and you can resume later from any subsequent phase.

Will this skill push commits or modify git history?

No. It never auto-executes Git write operations like commit or push; generated artifacts are written but not auto-pushed.

How are risky operations handled?

The skill reads the risk protection guidance and asks for explicit authorization before including high-risk actions in artifacts.