From e80cc265eba87341e8da7a8b4ec5df9b6b7a6104 Mon Sep 17 00:00:00 2001 From: Alexander Greim Date: Thu, 4 Dec 2025 22:15:46 +0100 Subject: [PATCH 01/11] docs: establish Interplay constitution v1.0.0 (initial ratification) - Define 5 core principles: incremental dev, collaboration, musical reliability, pattern simplicity, learning docs - Document technology stack and architectural constraints (Go 1.25.4, MIDI, CGO) - Establish phase-based development workflow - Define governance and amendment process with semantic versioning --- .specify/memory/constitution.md | 168 ++++++++++++++++++++++++++++++++ 1 file changed, 168 insertions(+) create mode 100644 .specify/memory/constitution.md diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md new file mode 100644 index 0000000..655e366 --- /dev/null +++ b/.specify/memory/constitution.md @@ -0,0 +1,168 @@ +# Interplay Constitution + + + +## Core Principles + +### I. Incremental Development + +Every feature is built one small piece at a time. Before implementation: +- Each component must be explained in context +- Go concepts (goroutines, channels, interfaces, etc.) introduced when needed +- Review and iterate together before moving forward +- Make conscious architectural decisions collaboratively + +**Rationale**: This is a learning-focused project. Understanding precedes implementation. Incremental progress ensures both the AI assistant and developer maintain full comprehension of the system as it grows. + +### II. Collaborative Decision-Making + +The developer maintains final architectural control. Before significant changes: +- Discuss approach and evaluate alternatives with explicit trade-offs +- AI proposes solutions but MUST wait for developer approval on architecture +- Explain "why this way?" for all design decisions +- Developer decides scheduling and priority + +**Rationale**: This project is as much about learning Go as building a tool. Architectural autonomy ensures the codebase reflects the developer's understanding and vision, not just AI suggestions. + +### III. Real-Time Musical Reliability + +Timing and musical feel are non-negotiable. All features must: +- Maintain accurate MIDI timing (currently 16th-note precision) +- Preserve playback continuity during pattern changes +- Apply humanization/swing consistently and predictably +- Handle MIDI I/O without blocking the playback goroutine + +**Rationale**: Interplay targets live performance. Timing glitches destroy musical flow. Pattern changes queue at loop boundaries specifically to avoid synchronization complexity while maintaining reliability. + +### IV. Pattern-Based Simplicity + +The pattern loop is the synchronization primitive. Design choices: +- Changes queue and apply at loop iteration boundaries (start of bar) +- No crossfading, no immediate synchronization needed +- Thread-safe pattern state with mutex protection +- Background playback goroutine remains simple and focused + +**Rationale**: Loop boundaries eliminate complex real-time synchronization. This architectural constraint trades flexibility for reliability and simplicity, which are paramount for live use. + +### V. Learning-First Documentation + +Documentation must teach, not just describe. Requirements: +- `CLAUDE.md` contains development approach, architectural decisions, and phase roadmap +- Code comments explain "why" for non-obvious Go idioms or trade-offs +- README serves user needs (quick start, MIDI setup, command reference) +- Design decisions are documented with alternatives considered + +**Rationale**: This project has dual goals - functional tool AND learning experience. Documentation ensures knowledge transfers across sessions and provides context for future decisions. + +## Development Constraints + +### Technology Stack (MUST) + +- **Language**: Go 1.25.4 (stdlib + minimal dependencies) +- **MIDI Library**: `gitlab.com/gomidi/midi/v2` with `rtmididrv` (CGO required) +- **AI Integration**: Anthropic Claude API via `anthropic-sdk-go` (optional runtime dependency) +- **Distribution**: Platform-specific binaries (macOS/Windows/Linux) due to CGO +- **Testing**: Standard Go testing (`go test ./...`) + +### Architecture Constraints (MUST) + +- **Core modules are permanent**: `midi/`, `sequence/`, `playback/`, `main.go` +- **Pattern state**: Mutex-protected shared state between command handler and playback goroutine +- **Concurrency model**: Main goroutine (commands) + playback goroutine (continuous loop) +- **Pattern swapping**: Current ← Next at loop boundary only +- **No external state**: Patterns stored as JSON in `patterns/` directory + +### Musical Constraints (SHOULD) + +- **Default pattern**: 16 steps (1 bar of 16th notes at configurable BPM) +- **Variable length**: Patterns support 1-64 steps via `length` command +- **Note format**: Human-readable (e.g., "C3", "D#4") converted to MIDI internally +- **Humanization**: Enabled by default with subtle settings (±8 velocity, ±10ms timing, ±5% gate) +- **Swing**: Off by default, configurable 0-75% + +## Development Workflow + +### Phase-Based Development (MUST) + +Development proceeds in phases documented in `CLAUDE.md`: +- **Phase 1**: Simple pattern loop (complete) +- **Phase 2**: Musical enhancements (complete) +- **Phase 3**: AI integration (complete) +- **Phase 4**: Advanced MIDI features (planned) +- **Phase 5**: Live performance features (future) + +Each phase must be complete before the next begins. Phases are reviewed and updated as understanding evolves. + +### Code Review Process (MUST) + +Before merging code: +- Propose code in small, digestible chunks +- Developer reviews, understands, and may modify +- Clarify anything unclear before proceeding +- Test incrementally (manual testing acceptable, automated tests optional) +- Commit messages follow conventional format: `feat:`, `fix:`, `docs:`, `refactor:` + +### AI Assistance Protocol (MUST) + +When using AI assistance (Claude Code or AI mode): +- AI proposes, developer approves architectural changes +- Trade-offs must be explicit before implementation +- "Why this way?" questions are always welcome and must be answered +- Developer controls what goes into the codebase + +## Governance + +### Amendment Process + +This constitution may be amended when: +1. A design decision establishes a new project-wide principle +2. A constraint proves limiting and alternatives are evaluated +3. Development phases reveal new architectural insights + +Amendments require: +- Documentation of reasoning and alternatives considered +- Update to this constitution with version bump +- Review of dependent templates (plan, spec, tasks) +- Git commit documenting the change + +### Versioning + +Constitution uses semantic versioning: +- **MAJOR**: Backward-incompatible governance changes (e.g., removing a principle) +- **MINOR**: New principle added or section materially expanded +- **PATCH**: Clarifications, wording improvements, non-semantic refinements + +### Compliance + +Development sessions should: +- Reference this constitution when making architectural decisions +- Justify any departures from established principles +- Propose amendments when constraints prove too limiting +- Keep `CLAUDE.md` in sync with architectural evolution + +**Version**: 1.0.0 | **Ratified**: 2025-12-04 | **Last Amended**: 2025-12-04 From 709e347f2afbaedacae8bddedb999d876460336e Mon Sep 17 00:00:00 2001 From: Alexander Greim Date: Thu, 4 Dec 2025 22:40:04 +0100 Subject: [PATCH 02/11] docs: amend constitution to v1.1.0 (add AI-first creativity principle) - Add new Principle VI: AI-First Creativity (elevate AI from optional to core) - Enhance Principle III: Musical Intelligence with Creative Freedom - Expand musical constraints to embrace creative dissonance - Update technology stack: AI is now a core feature - Add ai/ module to permanent architecture - Align constitution with README.md AI-first positioning --- .specify/memory/constitution.md | 75 +++++++++++++++++++++++---------- README.md | 53 ++++++++++++++--------- 2 files changed, 86 insertions(+), 42 deletions(-) diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 655e366..9a233a2 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -4,26 +4,36 @@ SYNC IMPACT REPORT ================== -Version Change: Initial → 1.0.0 -Ratification Date: 2025-12-04 -Reason: Initial constitution ratification for Interplay project +Version Change: 1.0.0 → 1.1.0 +Amendment Date: 2025-12-04 +Reason: MINOR version bump - Added new AI-First Creativity principle and expanded Musical Constraints -New Principles Established: -1. Incremental Development - Build one small piece at a time with explanations -2. Collaborative Decision-Making - Developer maintains architectural control with AI assistance -3. Real-Time Musical Reliability - Priority on live performance and musical timing -4. Pattern-Based Simplicity - Queue changes for loop boundaries, avoid complex synchronization -5. Learning-First Documentation - Explain concepts as they're introduced +Modified Principles: +- Principle III: "Real-Time Musical Reliability" → Enhanced to include musical intelligence and creative dissonance +- Technology Stack: AI Integration changed from "optional runtime dependency" to "core feature" + +Added Sections: +- New Principle VI: AI-First Creativity - Elevates AI assistance from optional to foundational +- Musical Constraints: Expanded to include musical intelligence, dissonance, and creative tension + +Removed Sections: None Templates Requiring Updates: -- ✅ plan-template.md: Constitution Check section present and ready -- ✅ spec-template.md: User scenarios and requirements align with incremental approach -- ✅ tasks-template.md: Phased approach supports incremental implementation +- ✅ plan-template.md: Constitution Check section accommodates new principles +- ✅ spec-template.md: User scenarios support AI-first approach +- ✅ tasks-template.md: Phased approach compatible with AI-first development +- ✅ README.md: Already updated to reflect AI-first positioning Follow-up TODOs: None +Rationale: +- README.md now positions Interplay as "AI-assisted creative tool" (AI-first) +- Musical intelligence with creative dissonance is now a core value +- AI mode described as "where the magic happens", not optional +- This constitutional amendment aligns governance with product positioning + Next Steps: -- Commit with: "docs: establish Interplay constitution v1.0.0 (initial ratification)" +- Commit with: "docs: amend constitution to v1.1.0 (add AI-first creativity principle)" ================== --> @@ -49,15 +59,17 @@ The developer maintains final architectural control. Before significant changes: **Rationale**: This project is as much about learning Go as building a tool. Architectural autonomy ensures the codebase reflects the developer's understanding and vision, not just AI suggestions. -### III. Real-Time Musical Reliability +### III. Musical Intelligence with Creative Freedom -Timing and musical feel are non-negotiable. All features must: +Musical coherence and creative expression are equally valued. All features must: - Maintain accurate MIDI timing (currently 16th-note precision) - Preserve playback continuity during pattern changes +- Understand musical concepts: harmony, rhythm, tension, resolution +- Embrace dissonance, unconventional harmonies, and creative tension as valid musical tools - Apply humanization/swing consistently and predictably - Handle MIDI I/O without blocking the playback goroutine -**Rationale**: Interplay targets live performance. Timing glitches destroy musical flow. Pattern changes queue at loop boundaries specifically to avoid synchronization complexity while maintaining reliability. +**Rationale**: Interplay targets creative music-making, not just technically correct sequences. The AI must help users stay musically coherent while encouraging experimentation with dissonance when that serves the creative vision. Timing glitches destroy musical flow, but creative dissonance enhances it. ### IV. Pattern-Based Simplicity @@ -79,31 +91,46 @@ Documentation must teach, not just describe. Requirements: **Rationale**: This project has dual goals - functional tool AND learning experience. Documentation ensures knowledge transfers across sessions and provides context for future decisions. +### VI. AI-First Creativity + +AI assistance is a core feature, not an optional add-on. Design requirements: +- AI mode is the primary creative interface for pattern building +- Natural language interaction must translate musical intent to MIDI patterns +- Direct commands remain available for precision control and fallback +- AI must understand musical concepts and explain its creative decisions +- System must function without AI (degraded experience, not broken) + +**Rationale**: Interplay is positioned as an "AI-assisted creative tool" where AI collaboration transforms the creative process. Users should be able to express musical ideas in natural language ("make it darker", "add tension") and receive musically intelligent responses. Manual commands serve precision needs and ensure the tool works without an API key. + ## Development Constraints ### Technology Stack (MUST) - **Language**: Go 1.25.4 (stdlib + minimal dependencies) - **MIDI Library**: `gitlab.com/gomidi/midi/v2` with `rtmididrv` (CGO required) -- **AI Integration**: Anthropic Claude API via `anthropic-sdk-go` (optional runtime dependency) +- **AI Integration**: Anthropic Claude API via `anthropic-sdk-go` (core feature, graceful degradation without API key) - **Distribution**: Platform-specific binaries (macOS/Windows/Linux) due to CGO - **Testing**: Standard Go testing (`go test ./...`) ### Architecture Constraints (MUST) -- **Core modules are permanent**: `midi/`, `sequence/`, `playback/`, `main.go` +- **Core modules are permanent**: `midi/`, `sequence/`, `playback/`, `main.go`, `ai/` - **Pattern state**: Mutex-protected shared state between command handler and playback goroutine -- **Concurrency model**: Main goroutine (commands) + playback goroutine (continuous loop) +- **Concurrency model**: Main goroutine (commands/AI) + playback goroutine (continuous loop) - **Pattern swapping**: Current ← Next at loop boundary only - **No external state**: Patterns stored as JSON in `patterns/` directory +- **AI integration**: Separate module that calls sequence manipulation functions -### Musical Constraints (SHOULD) +### Musical Constraints (MUST) +- **Musical intelligence**: AI must understand harmony, rhythm, tension, and resolution +- **Creative dissonance**: System embraces dissonant notes, chromatic passages, and unconventional harmonies as creative tools - **Default pattern**: 16 steps (1 bar of 16th notes at configurable BPM) - **Variable length**: Patterns support 1-64 steps via `length` command - **Note format**: Human-readable (e.g., "C3", "D#4") converted to MIDI internally - **Humanization**: Enabled by default with subtle settings (±8 velocity, ±10ms timing, ±5% gate) - **Swing**: Off by default, configurable 0-75% +- **Musical explanations**: AI should explain creative choices (e.g., "This Db creates tension before resolution") ## Development Workflow @@ -129,11 +156,12 @@ Before merging code: ### AI Assistance Protocol (MUST) -When using AI assistance (Claude Code or AI mode): +When using AI assistance (Claude Code or in-app AI mode): - AI proposes, developer approves architectural changes - Trade-offs must be explicit before implementation - "Why this way?" questions are always welcome and must be answered - Developer controls what goes into the codebase +- AI musical suggestions should include reasoning ## Governance @@ -143,6 +171,7 @@ This constitution may be amended when: 1. A design decision establishes a new project-wide principle 2. A constraint proves limiting and alternatives are evaluated 3. Development phases reveal new architectural insights +4. Product positioning changes require principle updates Amendments require: - Documentation of reasoning and alternatives considered @@ -163,6 +192,6 @@ Development sessions should: - Reference this constitution when making architectural decisions - Justify any departures from established principles - Propose amendments when constraints prove too limiting -- Keep `CLAUDE.md` in sync with architectural evolution +- Keep `CLAUDE.md` and `README.md` in sync with constitutional principles -**Version**: 1.0.0 | **Ratified**: 2025-12-04 | **Last Amended**: 2025-12-04 +**Version**: 1.1.0 | **Ratified**: 2025-12-04 | **Last Amended**: 2025-12-04 diff --git a/README.md b/README.md index e103026..65da320 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,21 @@ 🚧 **Work in Progress** -Interplay is a conversational MIDI sequencer for live music creation and improvisation. It uses pattern-based looping and natural language control to make exploring musical ideas intuitive and immediate. +**Interplay is an AI-assisted creative tool for rapid music creation with MIDI synthesizers.** Connect any MIDI device—hardware synth, drum machine, or software instrument—and collaborate with AI to build musical loops through conversation and commands. No configuration, no music theory required, just ideas and creative exploration. ## What is Interplay? -Interplay lets you create and modify musical patterns through simple commands and natural conversation with AI. Patterns loop continuously, with changes queued and applied at loop boundaries—giving you real-time control without worrying about timing. +Interplay transforms your creative process by combining AI musical intelligence with direct MIDI control. Talk to the AI in natural language about your musical ideas—"make it darker," "add tension," "create a bass line"—and it translates your intent into patterns that play immediately on your synthesizer. For precision work, drop into command mode for exact control over every note. + +**How it works:** +- **AI-first creativity**: Describe what you want musically, and AI builds patterns that match your vision +- **Plug and play**: Connect your MIDI synth, select it from the list, and start creating +- **Musical intelligence**: AI understands harmony, rhythm, tension, and resolution—while embracing dissonance as a creative tool +- **Rapid iteration**: Build and modify 16-step patterns in real-time with instant feedback +- **Pattern-based looping**: Changes apply at loop boundaries—no timing anxiety, just creative flow +- **Hybrid control**: Switch seamlessly between AI conversation and direct commands (`set 1 C3`, `tempo 120`) + +Interplay works with your synthesizer's full MIDI capabilities—notes, velocity, gate length, and synth-specific parameters. The AI helps you stay musically coherent while encouraging experimentation with dissonance, unconventional harmonies, and creative tension when that's what your music needs. **Current Status:** Phase 3 Complete - AI integration with hybrid command/natural language control @@ -85,33 +95,35 @@ Control patterns with simple text commands: Full command list: type `help` -### AI Mode (Optional) +### AI Mode - Creative Collaboration -Interplay includes AI-powered natural language control. To enable: +Interplay's AI mode is where the magic happens. Talk to the AI about your musical ideas in natural language, and it responds with patterns that match your creative vision. +**Setup** (one-time): ```bash export ANTHROPIC_API_KEY="your-api-key-here" ``` -AI features require an [Anthropic API](https://www.anthropic.com/api) account (separate from Claude Pro subscription). +Get your API key from [Anthropic](https://www.anthropic.com/api) (separate from Claude Pro subscription). **Enter AI mode:** ``` > ai -AI> make it darker +AI> create a dark bass line ``` -In AI mode, you get the best of both worlds: -- **Direct commands still work** - `set 1 C2`, `tempo 120`, `show`, etc. execute immediately -- **Natural language** - "make it darker", "add some movement", "what scale is this?" +**What you can do:** +- **Musical creativity**: "make it darker", "add tension", "add some movement", "create dissonance" +- **Music theory**: "what scale is this?", "transpose up a fifth", "add a passing note" +- **Direct commands**: `set 1 C2`, `tempo 120`, `show` - execute immediately without AI call +- **Pattern exploration**: "try something unexpected", "make it more minimal", "add complexity" - **Press Enter** to show the current pattern -- Type `exit` to return to normal mode -The AI understands musical concepts and translates your intent into pattern changes: +The AI understands musical concepts—harmony, rhythm, tension, resolution—and helps you explore both consonant and dissonant ideas: ``` -AI> make it darker -I'll transpose it down an octave to make it darker and more brooding. +AI> create a dark bass line +I'll create a brooding bass pattern in C minor with some rhythmic interest. Executing 4 command(s): > set 1 C2 > set 5 G2 @@ -119,17 +131,20 @@ Executing 4 command(s): > set 13 F2 Try it out! -AI> what scale is this in? -This is in C minor! You have C, G, and F - all from the C natural minor scale. +AI> add some tension +Let me add a dissonant note to create tension before the resolution. +Executing 1 command(s): + > set 7 Db2 +This creates a half-step clash that builds anticipation! -AI> set 2 D2 -Set step 2 to D2 (MIDI 38) +AI> what scale is this in? +This is in C minor with a chromatic passing tone (Db). The dissonance adds tension! AI> -[Shows current pattern] +[Shows current pattern with the tension-building dissonance] ``` -**Without an API key**, all manual commands work normally - you just won't have AI assistance. +**Alternative: Manual mode** - All commands work without an API key if you prefer direct control without AI assistance. Type `help` for the full command list. ## Learn More From 44c8a1f6f92b1374fdd064fe9f3e93df69afbddd Mon Sep 17 00:00:00 2001 From: Alexander Greim Date: Thu, 4 Dec 2025 22:43:17 +0100 Subject: [PATCH 03/11] feat: add speckit workflow infrastructure - Add constitution v1.1.0 with AI-first and musical intelligence principles - Add spec/plan/task templates for structured development - Add slash commands for feature specification and planning - Add feature creation scripts --- .claude/commands/speckit.analyze.md | 184 ++++ .claude/commands/speckit.checklist.md | 294 +++++++ .claude/commands/speckit.clarify.md | 181 ++++ .claude/commands/speckit.constitution.md | 82 ++ .claude/commands/speckit.implement.md | 135 +++ .claude/commands/speckit.plan.md | 89 ++ .claude/commands/speckit.specify.md | 258 ++++++ .claude/commands/speckit.tasks.md | 137 +++ .claude/commands/speckit.taskstoissues.md | 30 + .specify/scripts/bash/check-prerequisites.sh | 166 ++++ .specify/scripts/bash/common.sh | 156 ++++ .specify/scripts/bash/create-new-feature.sh | 297 +++++++ .specify/scripts/bash/setup-plan.sh | 61 ++ .specify/scripts/bash/update-agent-context.sh | 799 ++++++++++++++++++ .specify/templates/agent-file-template.md | 28 + .specify/templates/checklist-template.md | 40 + .specify/templates/plan-template.md | 104 +++ .specify/templates/spec-template.md | 115 +++ .specify/templates/tasks-template.md | 251 ++++++ 19 files changed, 3407 insertions(+) create mode 100644 .claude/commands/speckit.analyze.md create mode 100644 .claude/commands/speckit.checklist.md create mode 100644 .claude/commands/speckit.clarify.md create mode 100644 .claude/commands/speckit.constitution.md create mode 100644 .claude/commands/speckit.implement.md create mode 100644 .claude/commands/speckit.plan.md create mode 100644 .claude/commands/speckit.specify.md create mode 100644 .claude/commands/speckit.tasks.md create mode 100644 .claude/commands/speckit.taskstoissues.md create mode 100755 .specify/scripts/bash/check-prerequisites.sh create mode 100755 .specify/scripts/bash/common.sh create mode 100755 .specify/scripts/bash/create-new-feature.sh create mode 100755 .specify/scripts/bash/setup-plan.sh create mode 100755 .specify/scripts/bash/update-agent-context.sh create mode 100644 .specify/templates/agent-file-template.md create mode 100644 .specify/templates/checklist-template.md create mode 100644 .specify/templates/plan-template.md create mode 100644 .specify/templates/spec-template.md create mode 100644 .specify/templates/tasks-template.md diff --git a/.claude/commands/speckit.analyze.md b/.claude/commands/speckit.analyze.md new file mode 100644 index 0000000..98b04b0 --- /dev/null +++ b/.claude/commands/speckit.analyze.md @@ -0,0 +1,184 @@ +--- +description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal + +Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/speckit.tasks` has successfully produced a complete `tasks.md`. + +## Operating Constraints + +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). + +**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.analyze`. + +## Execution Steps + +### 1. Initialize Analysis Context + +Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: + +- SPEC = FEATURE_DIR/spec.md +- PLAN = FEATURE_DIR/plan.md +- TASKS = FEATURE_DIR/tasks.md + +Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command). +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +### 2. Load Artifacts (Progressive Disclosure) + +Load only the minimal necessary context from each artifact: + +**From spec.md:** + +- Overview/Context +- Functional Requirements +- Non-Functional Requirements +- User Stories +- Edge Cases (if present) + +**From plan.md:** + +- Architecture/stack choices +- Data Model references +- Phases +- Technical constraints + +**From tasks.md:** + +- Task IDs +- Descriptions +- Phase grouping +- Parallel markers [P] +- Referenced file paths + +**From constitution:** + +- Load `.specify/memory/constitution.md` for principle validation + +### 3. Build Semantic Models + +Create internal representations (do not include raw artifacts in output): + +- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`) +- **User story/action inventory**: Discrete user actions with acceptance criteria +- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases) +- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements + +### 4. Detection Passes (Token-Efficient Analysis) + +Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary. + +#### A. Duplication Detection + +- Identify near-duplicate requirements +- Mark lower-quality phrasing for consolidation + +#### B. Ambiguity Detection + +- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria +- Flag unresolved placeholders (TODO, TKTK, ???, ``, etc.) + +#### C. Underspecification + +- Requirements with verbs but missing object or measurable outcome +- User stories missing acceptance criteria alignment +- Tasks referencing files or components not defined in spec/plan + +#### D. Constitution Alignment + +- Any requirement or plan element conflicting with a MUST principle +- Missing mandated sections or quality gates from constitution + +#### E. Coverage Gaps + +- Requirements with zero associated tasks +- Tasks with no mapped requirement/story +- Non-functional requirements not reflected in tasks (e.g., performance, security) + +#### F. Inconsistency + +- Terminology drift (same concept named differently across files) +- Data entities referenced in plan but absent in spec (or vice versa) +- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note) +- Conflicting requirements (e.g., one requires Next.js while other specifies Vue) + +### 5. Severity Assignment + +Use this heuristic to prioritize findings: + +- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality +- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion +- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case +- **LOW**: Style/wording improvements, minor redundancy not affecting execution order + +### 6. Produce Compact Analysis Report + +Output a Markdown report (no file writes) with the following structure: + +## Specification Analysis Report + +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | + +(Add one row per finding; generate stable IDs prefixed by category initial.) + +**Coverage Summary Table:** + +| Requirement Key | Has Task? | Task IDs | Notes | +|-----------------|-----------|----------|-------| + +**Constitution Alignment Issues:** (if any) + +**Unmapped Tasks:** (if any) + +**Metrics:** + +- Total Requirements +- Total Tasks +- Coverage % (requirements with >=1 task) +- Ambiguity Count +- Duplication Count +- Critical Issues Count + +### 7. Provide Next Actions + +At end of report, output a concise Next Actions block: + +- If CRITICAL issues exist: Recommend resolving before `/speckit.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" + +### 8. Offer Remediation + +Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) + +## Operating Principles + +### Context Efficiency + +- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation +- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis +- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow +- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts + +### Analysis Guidelines + +- **NEVER modify files** (this is read-only analysis) +- **NEVER hallucinate missing sections** (if absent, report them accurately) +- **Prioritize constitution violations** (these are always CRITICAL) +- **Use examples over exhaustive rules** (cite specific instances, not generic patterns) +- **Report zero issues gracefully** (emit success report with coverage statistics) + +## Context + +$ARGUMENTS diff --git a/.claude/commands/speckit.checklist.md b/.claude/commands/speckit.checklist.md new file mode 100644 index 0000000..970e6c9 --- /dev/null +++ b/.claude/commands/speckit.checklist.md @@ -0,0 +1,294 @@ +--- +description: Generate a custom checklist for the current feature based on user requirements. +--- + +## Checklist Purpose: "Unit Tests for English" + +**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. + +**NOT for verification/testing**: + +- ❌ NOT "Verify the button clicks correctly" +- ❌ NOT "Test error handling works" +- ❌ NOT "Confirm the API returns 200" +- ❌ NOT checking if code/implementation matches the spec + +**FOR requirements quality validation**: + +- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness) +- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) +- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency) +- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage) +- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases) + +**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works. + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Execution Steps + +1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list. + - All file paths must be absolute. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST: + - Be generated from the user's phrasing + extracted signals from spec/plan/tasks + - Only ask about information that materially changes checklist content + - Be skipped individually if already unambiguous in `$ARGUMENTS` + - Prefer precision over breadth + + Generation algorithm: + 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). + 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. + 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit. + 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria. + 5. Formulate questions chosen from these archetypes: + - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?") + - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?") + - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?") + - Audience framing (e.g., "Will this be used by the author only or peers during PR review?") + - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?") + - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?") + + Question formatting rules: + - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters + - Limit to A–E options maximum; omit table if a free-form answer is clearer + - Never ask the user to restate what they already said + - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." + + Defaults when interaction impossible: + - Depth: Standard + - Audience: Reviewer (PR) if code-related; Author otherwise + - Focus: Top 2 relevance clusters + + Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more. + +3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: + - Derive checklist theme (e.g., security, review, deploy, ux) + - Consolidate explicit must-have items mentioned by user + - Map focus selections to category scaffolding + - Infer any missing context from spec/plan/tasks (do NOT hallucinate) + +4. **Load feature context**: Read from FEATURE_DIR: + - spec.md: Feature requirements and scope + - plan.md (if exists): Technical details, dependencies + - tasks.md (if exists): Implementation tasks + + **Context Loading Strategy**: + - Load only necessary portions relevant to active focus areas (avoid full-file dumping) + - Prefer summarizing long sections into concise scenario/requirement bullets + - Use progressive disclosure: add follow-on retrieval only if gaps detected + - If source docs are large, generate interim summary items instead of embedding raw text + +5. **Generate checklist** - Create "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if it doesn't exist + - Generate unique checklist filename: + - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) + - Format: `[domain].md` + - If file exists, append to existing file + - Number items sequentially starting from CHK001 + - Each `/speckit.checklist` run creates a NEW file (never overwrites existing checklists) + + **CORE PRINCIPLE - Test the Requirements, Not the Implementation**: + Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: + - **Completeness**: Are all necessary requirements present? + - **Clarity**: Are requirements unambiguous and specific? + - **Consistency**: Do requirements align with each other? + - **Measurability**: Can requirements be objectively verified? + - **Coverage**: Are all scenarios/edge cases addressed? + + **Category Structure** - Group items by requirement quality dimensions: + - **Requirement Completeness** (Are all necessary requirements documented?) + - **Requirement Clarity** (Are requirements specific and unambiguous?) + - **Requirement Consistency** (Do requirements align without conflicts?) + - **Acceptance Criteria Quality** (Are success criteria measurable?) + - **Scenario Coverage** (Are all flows/cases addressed?) + - **Edge Case Coverage** (Are boundary conditions defined?) + - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?) + - **Dependencies & Assumptions** (Are they documented and validated?) + - **Ambiguities & Conflicts** (What needs clarification?) + + **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: + + ❌ **WRONG** (Testing implementation): + - "Verify landing page displays 3 episode cards" + - "Test hover states work on desktop" + - "Confirm logo click navigates home" + + ✅ **CORRECT** (Testing requirements quality): + - "Are the exact number and layout of featured episodes specified?" [Completeness] + - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] + - "Are hover state requirements consistent across all interactive elements?" [Consistency] + - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] + - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] + - "Are loading states defined for asynchronous episode data?" [Completeness] + - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] + + **ITEM STRUCTURE**: + Each item should follow this pattern: + - Question format asking about requirement quality + - Focus on what's WRITTEN (or not written) in the spec/plan + - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] + - Reference spec section `[Spec §X.Y]` when checking existing requirements + - Use `[Gap]` marker when checking for missing requirements + + **EXAMPLES BY QUALITY DIMENSION**: + + Completeness: + - "Are error handling requirements defined for all API failure modes? [Gap]" + - "Are accessibility requirements specified for all interactive elements? [Completeness]" + - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" + + Clarity: + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" + - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" + - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" + + Consistency: + - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" + - "Are card component requirements consistent between landing and detail pages? [Consistency]" + + Coverage: + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" + - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" + - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" + + Measurability: + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" + - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" + + **Scenario Classification & Coverage** (Requirements Quality Focus): + - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios + - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" + - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]" + - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]" + + **Traceability Requirements**: + - MINIMUM: ≥80% of items MUST include at least one traceability reference + - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]` + - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]" + + **Surface & Resolve Issues** (Requirements Quality Problems): + Ask questions about the requirements themselves: + - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]" + - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]" + - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" + - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" + - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" + + **Content Consolidation**: + - Soft cap: If raw candidate items > 40, prioritize by risk/impact + - Merge near-duplicates checking the same requirement aspect + - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]" + + **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test: + - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior + - ❌ References to code execution, user actions, system behavior + - ❌ "Displays correctly", "works properly", "functions as expected" + - ❌ "Click", "navigate", "render", "load", "execute" + - ❌ Test cases, test plans, QA procedures + - ❌ Implementation details (frameworks, APIs, algorithms) + + **✅ REQUIRED PATTERNS** - These test requirements quality: + - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" + - ✅ "Is [vague term] quantified/clarified with specific criteria?" + - ✅ "Are requirements consistent between [section A] and [section B]?" + - ✅ "Can [requirement] be objectively measured/verified?" + - ✅ "Are [edge cases/scenarios] addressed in requirements?" + - ✅ "Does the spec define [missing aspect]?" + +6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### ` lines with globally incrementing IDs starting at CHK001. + +7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize: + - Focus areas selected + - Depth level + - Actor/timing + - Any explicit user-specified must-have items incorporated + +**Important**: Each `/speckit.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows: + +- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`) +- Simple, memorable filenames that indicate checklist purpose +- Easy identification and navigation in the `checklists/` folder + +To avoid clutter, use descriptive types and clean up obsolete checklists when done. + +## Example Checklist Types & Sample Items + +**UX Requirements Quality:** `ux.md` + +Sample items (testing the requirements, NOT the implementation): + +- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" +- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" +- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" +- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" +- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" +- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]" + +**API Requirements Quality:** `api.md` + +Sample items: + +- "Are error response formats specified for all failure scenarios? [Completeness]" +- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" +- "Are authentication requirements consistent across all endpoints? [Consistency]" +- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" +- "Is versioning strategy documented in requirements? [Gap]" + +**Performance Requirements Quality:** `performance.md` + +Sample items: + +- "Are performance requirements quantified with specific metrics? [Clarity]" +- "Are performance targets defined for all critical user journeys? [Coverage]" +- "Are performance requirements under different load conditions specified? [Completeness]" +- "Can performance requirements be objectively measured? [Measurability]" +- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" + +**Security Requirements Quality:** `security.md` + +Sample items: + +- "Are authentication requirements specified for all protected resources? [Coverage]" +- "Are data protection requirements defined for sensitive information? [Completeness]" +- "Is the threat model documented and requirements aligned to it? [Traceability]" +- "Are security requirements consistent with compliance obligations? [Consistency]" +- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" + +## Anti-Examples: What NOT To Do + +**❌ WRONG - These test implementation, not requirements:** + +```markdown +- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001] +- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003] +- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010] +- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005] +``` + +**✅ CORRECT - These test requirements quality:** + +```markdown +- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001] +- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003] +- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010] +- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005] +- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap] +- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001] +``` + +**Key Differences:** + +- Wrong: Tests if the system works correctly +- Correct: Tests if the requirements are written correctly +- Wrong: Verification of behavior +- Correct: Validation of requirement quality +- Wrong: "Does it do X?" +- Correct: "Is X clearly specified?" diff --git a/.claude/commands/speckit.clarify.md b/.claude/commands/speckit.clarify.md new file mode 100644 index 0000000..6b28dae --- /dev/null +++ b/.claude/commands/speckit.clarify.md @@ -0,0 +1,181 @@ +--- +description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. +handoffs: + - label: Build Technical Plan + agent: speckit.plan + prompt: Create a plan for the spec. I am building with... +--- + +## User Input + +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Outline + +Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file. + +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/speckit.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. + +Execution steps: + +1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: + - `FEATURE_DIR` + - `FEATURE_SPEC` + - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) + - If JSON parsing fails, abort and instruct user to re-run `/speckit.specify` or verify feature branch environment. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). + + Functional Scope & Behavior: + - Core user goals & success criteria + - Explicit out-of-scope declarations + - User roles / personas differentiation + + Domain & Data Model: + - Entities, attributes, relationships + - Identity & uniqueness rules + - Lifecycle/state transitions + - Data volume / scale assumptions + + Interaction & UX Flow: + - Critical user journeys / sequences + - Error/empty/loading states + - Accessibility or localization notes + + Non-Functional Quality Attributes: + - Performance (latency, throughput targets) + - Scalability (horizontal/vertical, limits) + - Reliability & availability (uptime, recovery expectations) + - Observability (logging, metrics, tracing signals) + - Security & privacy (authN/Z, data protection, threat assumptions) + - Compliance / regulatory constraints (if any) + + Integration & External Dependencies: + - External services/APIs and failure modes + - Data import/export formats + - Protocol/versioning assumptions + + Edge Cases & Failure Handling: + - Negative scenarios + - Rate limiting / throttling + - Conflict resolution (e.g., concurrent edits) + + Constraints & Tradeoffs: + - Technical constraints (language, storage, hosting) + - Explicit tradeoffs or rejected alternatives + + Terminology & Consistency: + - Canonical glossary terms + - Avoided synonyms / deprecated terms + + Completion Signals: + - Acceptance criteria testability + - Measurable Definition of Done style indicators + + Misc / Placeholders: + - TODO markers / unresolved decisions + - Ambiguous adjectives ("robust", "intuitive") lacking quantification + + For each category with Partial or Missing status, add a candidate question opportunity unless: + - Clarification would not materially change implementation or validation strategy + - Information is better deferred to planning phase (note internally) + +3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: + - Maximum of 10 total questions across the whole session. + - Each question must be answerable with EITHER: + - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words"). + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation. + - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved. + - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness). + - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests. + - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic. + +4. Sequential questioning loop (interactive): + - Present EXACTLY ONE question at a time. + - For multiple‑choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice). + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |