Skip to content

The open-source app everyone uses to manage agents at work

chore(github): expand issue forms (#7628)

Devin Foleya4fa0eaf5ea6
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 6109c8decb..bf06469f84 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -6,14 +6,34 @@ body:
attributes:
value: |
Thanks for taking the time to file a bug. Please fill out the sections below so we can reproduce and triage quickly.
+
+ > **⚠️ Privacy notice:** Several fields below accept logs, config, or transcript output that may contain **personally identifiable information (PII)** — usernames in file paths, API keys, tokens, company names, agent output, or task content. Before pasting:
+ > 1. Review for sensitive data
+ > 2. Redact usernames, paths, API keys, tokens (e.g. replace `/Users/yourname/` with `/Users/REDACTED/`)
+ > 3. For heavy output, consider running it through an anonymizer such as **[presidio-anonymizer](https://microsoft.github.io/presidio/)** (open-source, local-only) or **[scrub](https://github.com/dssg/scrub)**
+
+ - type: checkboxes
+ id: preflight
+ attributes:
+ label: Pre-submission checklist
+ description: Please confirm each of these before filing.
+ options:
+ - label: I have searched existing open and closed issues and this is not a duplicate.
+ required: true
+ - label: I am on the latest released version of Paperclip (or can reproduce on `master`).
+ required: true
+ - label: I have confirmed the error originates in Paperclip itself — not in my agent adapter, API provider, or local configuration.
+ required: true
+
- type: textarea
id: what-happened
attributes:
label: What happened?
- description: A clear description of the bug.
+ description: A clear description of the bug. Be specific about which Paperclip command, endpoint, or UI action was involved.
placeholder: When I do X, Y happens instead of Z.
validations:
required: true
+
- type: textarea
id: expected
attributes:
@@ -21,17 +41,19 @@ body:
description: What should have happened instead.
validations:
required: true
+
- type: textarea
id: repro
attributes:
label: Steps to reproduce
- description: Numbered steps a maintainer can follow to reproduce the bug.
+ description: Numbered steps a maintainer can follow to reproduce the bug. Start from a clean install where possible.
value: |
1.
2.
3.
validations:
required: true
+
- type: input
id: paperclip-version
attributes:
@@ -40,6 +62,7 @@ body:
placeholder: e.g. 0.42.0 or 78dc3625ac
validations:
required: true
+
- type: dropdown
id: deployment
attributes:
@@ -51,25 +74,101 @@ body:
- Other
validations:
required: true
+
+ - type: dropdown
+ id: install_method
+ attributes:
+ label: Installation method
+ options:
+ - npm / pnpm global install
+ - Docker
+ - Built from source (pnpm dev / pnpm build)
+ - Other
+ validations:
+ required: false
+
+ - type: checkboxes
+ id: adapters
+ attributes:
+ label: Agent adapter(s) involved
+ description: Select all that apply. If unsure, leave unchecked and describe in additional context.
+ options:
+ - label: Claude Code
+ - label: Codex
+ - label: Cursor
+ - label: Droid
+ - label: Hermes
+ - label: Custom / external plugin adapter
+ - label: Not adapter-specific (core bug)
+
+ - type: dropdown
+ id: database
+ attributes:
+ label: Database mode
+ options:
+ - Embedded PGlite (default — `DATABASE_URL` unset)
+ - External Postgres
+ - Not database-related
+ validations:
+ required: false
+
+ - type: dropdown
+ id: access_context
+ attributes:
+ label: Access context
+ description: Whose credentials were being used when the bug occurred?
+ options:
+ - Board (human operator)
+ - Agent (bearer API key via `agent_api_keys`)
+ - Both
+ - Unclear / not applicable
+ validations:
+ required: false
+
- type: input
id: node-version
attributes:
label: Node.js version
description: Output of `node --version`.
placeholder: e.g. v20.18.0
+
- type: input
id: os
attributes:
label: Operating system
placeholder: e.g. macOS 14.5 (Apple Silicon), Ubuntu 22.04
+
- type: textarea
id: logs
attributes:
label: Relevant logs or output
- description: Paste error messages, stack traces, or API responses. Will be rendered as a code block.
+ description: |
+ Paste error messages, stack traces, or API responses. Will be rendered as a code block.
+
+ **⚠️ PII warning:** Server logs often contain file paths with your username (e.g. `/Users/yourname/...`). Redact before pasting.
render: shell
+
+ - type: textarea
+ id: config
+ attributes:
+ label: Relevant config (if applicable)
+ description: |
+ If the bug is config-related, paste the relevant snippet.
+
+ **⚠️ PII warning:** Paperclip config may contain API keys, encrypted-secrets paths, company names, or tokens. **Remove all secrets before pasting.**
+ render: json
+
- type: textarea
id: context
attributes:
label: Additional context
description: Screenshots, related issues, or anything else that might help.
+
+ - type: checkboxes
+ id: pii_confirmed
+ attributes:
+ label: Privacy checklist
+ description: Please confirm you've reviewed your submission for sensitive data.
+ options:
+ - label: I have reviewed all pasted output for PII (usernames, file paths, API keys, tokens, company names) and redacted where necessary.
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/docs_issue.yml b/.github/ISSUE_TEMPLATE/docs_issue.yml
new file mode 100644
index 0000000000..00acd18a68
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/docs_issue.yml
@@ -0,0 +1,44 @@
+name: Documentation issue
+description: Report incorrect, missing, or unclear documentation
+labels: [documentation]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Help improve the docs. Point us at what's wrong, missing, or confusing.
+
+ - type: dropdown
+ id: type
+ attributes:
+ label: Issue type
+ options:
+ - Incorrect information
+ - Missing documentation
+ - Unclear or confusing
+ - Outdated (no longer matches behavior)
+ - Typo or formatting
+ validations:
+ required: true
+
+ - type: input
+ id: location
+ attributes:
+ label: Where is the issue?
+ description: File path, URL, or section name.
+ placeholder: "e.g. README.md#installation, doc/DEVELOPING.md, docs/plugins.md"
+ validations:
+ required: true
+
+ - type: textarea
+ id: description
+ attributes:
+ label: What's wrong?
+ description: Describe the documentation issue.
+ validations:
+ required: true
+
+ - type: textarea
+ id: suggestion
+ attributes:
+ label: Suggested fix
+ description: If you know what the correct information should be, include it here.
diff --git a/.github/ISSUE_TEMPLATE/enhancement.yml b/.github/ISSUE_TEMPLATE/enhancement.yml
new file mode 100644
index 0000000000..dde3af63c4
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/enhancement.yml
@@ -0,0 +1,92 @@
+name: Enhancement proposal
+description: Propose an improvement to an existing Paperclip feature
+labels: [enhancement]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ An enhancement improves something that already exists — better output, broader edge-case handling, clearer UX, performance. It does not add new commands, endpoints, or concepts. If you are proposing something new, use the **Feature request** template instead.
+
+ - type: checkboxes
+ id: preflight
+ attributes:
+ label: Pre-submission checklist
+ description: Please confirm each of these before filing.
+ options:
+ - label: I have confirmed this improves existing behavior — it does not add a new command, endpoint, or concept.
+ required: true
+ - label: I have searched existing open and closed issues and this has not already been proposed.
+ required: true
+
+ - type: input
+ id: what_is_improved
+ attributes:
+ label: What existing behavior does this improve?
+ description: Name the specific command, endpoint, UI view, or behavior being enhanced.
+ placeholder: "e.g. /api/companies response shape, board task list sorting, adapter startup log output"
+ validations:
+ required: true
+
+ - type: dropdown
+ id: subsystem
+ attributes:
+ label: Subsystem affected
+ options:
+ - server/ — REST API & orchestration services
+ - ui/ — React + Vite board UI
+ - packages/db — Drizzle schema, migrations
+ - packages/shared — types, constants, validators, API paths
+ - packages/adapters — agent adapter implementations
+ - packages/plugins — plugin system
+ - Cross-cutting (multiple of the above)
+ - Unsure
+ validations:
+ required: true
+
+ - type: textarea
+ id: current_behavior
+ attributes:
+ label: Current behavior
+ description: Describe exactly how it works today. Include example output or a screenshot if helpful.
+ placeholder: |
+ Currently, when I call ..., the response is ...
+ validations:
+ required: true
+
+ - type: textarea
+ id: proposed_behavior
+ attributes:
+ label: Proposed behavior
+ description: Describe exactly how it should work after the enhancement. Include example output.
+ placeholder: |
+ After this enhancement, the response would be ...
+ validations:
+ required: true
+
+ - type: textarea
+ id: reason
+ attributes:
+ label: Reason and benefit
+ description: |
+ Why is the current behavior a problem, and what is the concrete benefit of the proposed behavior?
+
+ Vague answers like "it would be better" or "more user-friendly" are not enough.
+ validations:
+ required: true
+
+ - type: textarea
+ id: breaking_changes
+ attributes:
+ label: Breaking changes
+ description: |
+ Does this change any behavior, response shape, or output format that users or agents might rely on?
+ If yes, describe exactly what changes and how backward compatibility is maintained.
+ Write "None" only if you are certain.
+ validations:
+ required: true
+
+ - type: textarea
+ id: additional_context
+ attributes:
+ label: Additional context
+ description: Screenshots, related issues, or anything else.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml
index 39d0a06762..e4e09edc69 100644
--- a/.github/ISSUE_TEMPLATE/feature_request.yml
+++ b/.github/ISSUE_TEMPLATE/feature_request.yml
@@ -6,6 +6,22 @@ body:
attributes:
value: |
Feature work on core Paperclip is coordinated against `ROADMAP.md` and Discord `#dev`. Please skim those before filing — see [CONTRIBUTING.md](https://github.com/paperclipai/paperclip/blob/master/CONTRIBUTING.md) for the full guidance.
+ - type: dropdown
+ id: subsystem
+ attributes:
+ label: Subsystem affected
+ description: Which part of the codebase would this primarily live in?
+ options:
+ - server/ — REST API & orchestration services
+ - ui/ — React + Vite board UI
+ - packages/db — Drizzle schema, migrations
+ - packages/shared — types, constants, validators, API paths
+ - packages/adapters — agent adapter implementations
+ - packages/plugins — plugin system
+ - Cross-cutting (multiple of the above)
+ - Unsure
+ validations:
+ required: true
- type: textarea
id: problem
attributes: