feat: add prompt request workflow for AI-assisted contributions (#71)

sozercan · web-flow · commit 12bf4f57717c · 2026-01-13T09:48:40.000-08:00
diff --git a/.github/ISSUE_TEMPLATE/prompt_request.yml b/.github/ISSUE_TEMPLATE/prompt_request.yml
@@ -0,0 +1,137 @@
+name: Prompt Request
+description: Propose a change via an AI prompt that can be reviewed and executed
+title: "[Prompt]: "
+labels: ["prompt-request", "ai-assisted"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        ## What is a Prompt Request?
+
+        Instead of submitting code directly, share the **AI prompt** that generates the changes you want. This allows maintainers to:
+        - Understand the **intent** behind changes
+        - Review the **reasoning** before code is generated
+        - Run the prompt themselves to verify and merge
+        - Iterate on the prompt before implementation
+
+        This is especially useful for AI-assisted development where the prompt often captures intent better than the resulting code diff.
+
+  - type: checkboxes
+    id: existing-issue
+    attributes:
+      label: Is there an existing issue or PR for this?
+      description: Please search to see if this has already been addressed.
+      options:
+        - label: I have searched the existing issues and PRs
+          required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context & Motivation
+      description: What problem does this prompt solve? Why should this change be made?
+      placeholder: |
+        Describe the motivation for this change. Link to related issues if applicable.
+        Ex: "The current search doesn't handle empty results gracefully..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: prompt
+    attributes:
+      label: AI Prompt
+      description: |
+        The exact prompt to run with an AI coding assistant (GitHub Copilot, Claude, Cursor, etc.).
+        Include all necessary context the AI would need.
+      placeholder: |
+        Add graceful empty state handling to SearchView.swift.
+        
+        Requirements:
+        - Show an illustration when search returns no results
+        - Display helpful message suggesting different search terms
+        - Follow existing empty state patterns in LibraryView
+        - Use SF Symbols for the illustration
+        - Ensure VoiceOver accessibility
+    validations:
+      required: true
+
+  - type: dropdown
+    id: ai-tool
+    attributes:
+      label: Recommended AI Tool
+      description: Which AI tool is this prompt designed for?
+      options:
+        - GitHub Copilot (Agent Mode)
+        - Claude (via Cursor/Claude Code)
+        - Any compatible AI assistant
+        - Not sure / Tool-agnostic
+    validations:
+      required: true
+
+  - type: textarea
+    id: files
+    attributes:
+      label: Target Files (Optional)
+      description: List specific files the prompt should modify, if known.
+      placeholder: |
+        - Views/macOS/Search/SearchView.swift
+        - Views/macOS/Components/EmptyStateView.swift (new)
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: How will we know the prompt produced correct results?
+      placeholder: |
+        - [ ] Empty state appears when search returns 0 results
+        - [ ] Message is helpful and not generic
+        - [ ] VoiceOver reads the empty state correctly
+        - [ ] Unit tests pass
+        - [ ] No SwiftLint warnings
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Feature Area
+      description: Which part of the app does this affect?
+      options:
+        - Playback / Audio
+        - Library / Playlists
+        - Search
+        - Home / Browse
+        - Now Playing / Player Bar
+        - UI / Visual
+        - Performance
+        - Documentation
+        - Testing
+        - Build / CI
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternative Approaches
+      description: Other prompts or approaches you considered.
+      placeholder: Describe other ways this could be achieved.
+
+  - type: checkboxes
+    id: verification
+    attributes:
+      label: Verification
+      description: Please confirm the following.
+      options:
+        - label: I have tested this prompt locally (or explained why I couldn't)
+        - label: The prompt follows project conventions in AGENTS.md
+        - label: No secrets, API keys, or sensitive data are included in the prompt
+          required: true
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional Context
+      description: Any other information that would help when running the prompt.
+      placeholder: Screenshots, expected behavior, edge cases to consider, etc.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -2,6 +2,30 @@
 
 <!-- Provide a brief description of the changes in this PR -->
 
+## AI Prompt (Optional)
+
+<!-- 
+If this PR was generated with AI assistance (GitHub Copilot, Claude, Cursor, etc.), 
+share the prompt that created these changes. This helps reviewers:
+- Understand your intent better than code alone
+- Validate the approach before reviewing implementation
+- Run the prompt themselves to verify or iterate
+
+If you want to submit a "prompt request" (prompt-only, no code), please open a
+new issue using the "Prompt Request" issue template instead of a pull request.
+-->
+
+<details>
+<summary>🤖 AI Prompt Used</summary>
+
+```
+<!-- Paste your prompt here, or write "N/A - Manual implementation" -->
+```
+
+**AI Tool:** <!-- e.g., GitHub Copilot, Claude, Cursor -->
+
+</details>
+
 ## Type of Change
 
 <!-- Mark the relevant option with an 'x' -->
diff --git a/AGENTS.md b/AGENTS.md
@@ -119,6 +119,8 @@ If you discover new response structures or endpoint behaviors, update [docs/api-
 
 > 📝 **Document Architectural Decisions** — For significant design changes, create an ADR in `docs/adr/` following the format in [docs/adr/README.md](docs/adr/README.md).
 
+> 🤖 **Document Your Prompts** — When completing a task, summarize the key prompt(s) used so the human can include them in the PR. This supports the project's "prompt request" workflow where prompts are reviewed alongside (or instead of) code. See [CONTRIBUTING.md](CONTRIBUTING.md#ai-assisted-contributions--prompt-requests).
+
 > ⚡ **Performance Awareness** — For non-trivial features, run performance tests and verify no anti-patterns. When adding parsers or API calls, include `measure {}` tests.
 
 > 🔧 **Improve API Explorer, Don't Write One-Off Scripts** — When exploring or debugging API-related functionality, **always enhance `Tools/api-explorer.swift`** instead of writing temporary scripts. This ensures the tool grows with the project, maintains consistency, and provides reusable functionality for future API work. If you need to fetch raw JSON, test a new endpoint, or debug response parsing, add that capability to the API explorer.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -186,6 +186,55 @@ final class MyServiceTests: XCTestCase {
 3. **Tests Must Pass** — Run `xcodebuild -scheme Kaset -destination 'platform=macOS' test`
 4. **Linting** — Run `swiftlint --strict && swiftformat .` before submitting
 5. **Small PRs** — Keep changes focused and reviewable
+6. **Share AI Prompts** — If you used AI assistance, include the prompt in your PR (see below)
+
+## AI-Assisted Contributions & Prompt Requests
+
+We embrace AI-assisted development! Whether you use GitHub Copilot, Claude, Cursor, or other AI tools, we welcome contributions that leverage these capabilities.
+
+### What is a Prompt Request?
+
+A **prompt request** is a contribution where you share the AI prompt that generates code, rather than (or in addition to) the code itself. This approach:
+
+- **Captures intent** — The prompt often explains *why* better than a code diff
+- **Enables review before implementation** — Maintainers can validate the approach
+- **Supports iteration** — Prompts can be refined before code is generated
+- **Improves reproducibility** — Anyone can run the prompt to verify results
+
+### Contributing with AI Assistance
+
+#### Option 1: Traditional PR with AI Prompt Disclosure
+
+Submit code as usual, but include the AI prompt in the PR template's "AI Prompt" section. This helps reviewers understand your approach and intent.
+
+#### Option 2: Prompt Request (Prompt-Only)
+
+Create an issue using the **Prompt Request** template if you:
+- Have a well-crafted prompt but haven't run it yet
+- Want feedback on your approach before implementation
+- Prefer maintainers to run and merge the prompt themselves
+
+### Best Practices for AI Prompts
+
+1. **Be specific** — Include file paths, function names, and concrete requirements
+2. **Reference project conventions** — Mention AGENTS.md and relevant patterns
+3. **Define acceptance criteria** — How will we know it worked?
+4. **Include context** — Link to issues, docs, or examples
+5. **Test locally when possible** — Verify the prompt produces working code
+
+### Example Prompt
+
+```
+Add haptic feedback to the shuffle button in PlayerBar.swift.
+
+Requirements:
+- Use HapticService.toggle() on button tap
+- Only trigger haptic on state change (not when already shuffled)
+- Follow existing haptic patterns used in volume controls
+- Add unit test in PlayerServiceTests.swift
+
+Reference: Core/Services/HapticService.swift for existing patterns
+```
 
 ## Testing
 
diff --git a/README.md b/README.md
@@ -84,5 +84,7 @@ open "kaset://play?v=dQw4w9WgXcQ"
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, architecture, and coding guidelines.
 
+We welcome AI-assisted contributions! You can submit traditional PRs or **prompt requests** — share the AI prompt that generates your changes, and maintainers can review the intent before running the code. See the [AI-Assisted Contributions](CONTRIBUTING.md#ai-assisted-contributions--prompt-requests) section for details.
+
 ## Disclaimer
 Kaset is an unofficial application and not affiliated with YouTube or Google Inc. in any way. "YouTube", "YouTube Music" and the "YouTube Logo" are registered trademarks of Google Inc.
diff --git a/docs/adr/0009-prompt-request-workflow.md b/docs/adr/0009-prompt-request-workflow.md
@@ -0,0 +1,66 @@
+# ADR-0009: Prompt Request Workflow
+
+## Status
+
+Accepted
+
+## Context
+
+AI coding assistants (GitHub Copilot, Claude, Cursor, etc.) are increasingly capable of generating high-quality code from natural language prompts. Traditional pull requests focus on reviewing the resulting code diff, but this approach has limitations in the AI-assisted development era:
+
+1. **Code diffs hide intent** — A large code change doesn't clearly communicate *why* the change was made or what problem it solves.
+2. **Review friction** — Reviewers must reverse-engineer the contributor's goals from the code.
+3. **Reproducibility** — Others cannot easily regenerate or iterate on AI-generated code without knowing the original prompt.
+4. **Barrier to contribution** — Contributors comfortable with prompts but not Swift development may have valuable ideas they can't easily contribute.
+
+The concept of "prompt requests" (attributed to Peter Steinberger / @steipete) proposes sharing the AI prompt that generates code changes, allowing review of intent before or alongside implementation.
+
+## Decision
+
+We adopt a **prompt request workflow** that allows contributions in three forms:
+
+### 1. Traditional PRs (with optional prompt disclosure)
+
+Standard code contributions where contributors may optionally share the AI prompt used to generate the code in the PR template.
+
+### 2. PRs with Prompt Disclosure (Encouraged)
+
+For AI-generated code, we encourage (but don't require) sharing the prompt that produced the changes. This helps reviewers:
+- Understand the contributor's intent
+- Validate the prompt logic before reviewing implementation details
+- Suggest improvements to the prompt rather than line-by-line code fixes
+
+### 3. Prompt-Only Contributions (Prompt Requests)
+
+Contributors can submit a prompt via the "Prompt Request" issue template without generating code. Maintainers can:
+- Review the prompt for feasibility and alignment with project goals
+- Iterate on the prompt with the contributor
+- Run the approved prompt to generate and merge the code
+
+### Implementation
+
+- **Issue Template**: New `prompt_request.yml` template for prompt-only contributions
+- **PR Template**: Added "AI Prompt" section for disclosing prompts used
+- **CONTRIBUTING.md**: New section documenting the workflow
+- **AGENTS.md**: Guidance for AI agents to document prompts for PR inclusion
+
+## Consequences
+
+### Positive
+
+- **Faster contribution review** — Intent is clear from the prompt, reducing back-and-forth
+- **Lower barrier to entry** — Contributors can propose changes without writing Swift
+- **Better reproducibility** — Prompts can be re-run to verify or update changes
+- **Knowledge sharing** — Effective prompts become reusable patterns
+- **AI agent compatibility** — AI assistants can be instructed to document their prompts
+
+### Negative
+
+- **Additional overhead** — Contributors must document prompts (though this is optional for manual code)
+- **Prompt variation** — Same prompt may produce different results across AI tools or versions
+- **Security consideration** — Prompts must be reviewed to ensure they don't inadvertently request credential exposure
+
+### Neutral
+
+- **Not a replacement** — Prompt requests supplement, not replace, traditional code review
+- **Tool-agnostic** — The workflow doesn't mandate specific AI tools
diff --git a/docs/adr/README.md b/docs/adr/README.md
@@ -43,3 +43,4 @@ What becomes easier or more difficult because of this change?
 | [0006](0006-swift-testing-migration.md) | Swift Testing Migration | Accepted |
 | [0007](0007-sparkle-auto-updates.md) | Sparkle Auto-Updates | Accepted |
 | [0008](0008-nonisolated-network-helpers.md) | Nonisolated Network Helpers for MainActor Classes | Accepted |
+| [0009](0009-prompt-request-workflow.md) | Prompt Request Workflow | Accepted |
