How to Report a Bug or Issue in OpenSpec: 3 Methods Explained

OpenSpec provides three ways to report bugs: GitHub Issues, Discord, and the openspec feedback CLI command that auto-populates issue templates with the feedback label.

The Fission-AI/OpenSpec repository offers multiple channels to surface problems, ranging from automated CLI workflows to manual issue creation. Whether you encounter a CLI crash, a documentation typo, or unexpected behavior in the /opsx commands, you can choose the method that best fits your workflow. All routes ultimately funnel into the same GitHub issue tracker, ensuring your report reaches the maintainers.

Using the OpenSpec Feedback Command (CLI)

The openspec feedback command provides the fastest path to report a bug or issue in OpenSpec. Implemented in src/commands/feedback.ts, this utility attempts to create a GitHub issue automatically using the gh CLI, and falls back to a manual copy-paste workflow when the tool is unavailable.

How the Feedback Command Works

When you run openspec feedback, the code in src/commands/feedback.ts (lines 122-140) first checks for the presence of the GitHub CLI. If authenticated, it creates an issue with the feedback label pre-applied. If gh is missing or not authenticated, the command prints a formatted issue template and prompts you to copy-paste it manually into the repository.

The command is registered in src/cli/index.ts at lines 409-415, making it available as a top-level subcommand.

Simple Title-Only Reports

For quick reports where a title suffices, pass a single string argument:

openspec feedback "Broken /opsx:apply on Nix projects"

This creates an issue with the title provided and auto-assigns the feedback label.

Detailed Reports with Body

For complex bugs, include a detailed description using the --body flag:

openspec feedback "Bug: /opsx:propose hangs" \
  --body "Running /opsx:propose on a fresh repo never returns. Steps to reproduce:\n1. \`openspec init\`\n2. In the AI chat type \`/opsx:propose add-feature\`\n3. The command stalls after 'Generating proposal'.\n\nEnvironment: macOS 14, Node 20.19, OpenSpec v1.5.0.\n\nExpected: command should return a proposal markdown file.\nActual: no output, process stays alive."

Use newline characters (\n) to format the body text with proper line breaks.

Fallback When GitHub CLI Is Unavailable

If the gh CLI is not installed or authenticated, the feedback command outputs a formatted template for manual submission:

# When gh CLI is missing

openspec feedback "Missing gh CLI fallback test"

# Output:

# ----------------------------------------------------

# Labels: feedback

# Title: Missing gh CLI fallback test

# Body:

# <your description>

# ----------------------------------------------------

# Please copy-paste the above into a new GitHub issue.

Copy this block and paste it into a new issue at the repository URL.

Opening Issues Directly on GitHub

You can manually report a bug or issue in OpenSpec by visiting the issue tracker directly at https://github.com/Fission-AI/OpenSpec/issues. When creating an issue manually:

1. Click New Issue
2. Fill in the title and description
3. Add the feedback label (or any appropriate category label)

This method is documented in docs/faq.md under the section "Where do I ask questions or report bugs?" and reinforced in docs/README.md, which notes: "Found something wrong? Open an issue or PR."

Using Discord for Quick Discussion

For informal questions, rapid clarification, or "I just saw a typo" moments, the OpenSpec community Discord offers a lightweight alternative. The Discord link is documented in docs/faq.md alongside the GitHub Issues guidance.

While Discord threads are not tracked as formally as GitHub issues, maintainers monitor the channel and will create corresponding tracker issues for verified bugs. This is ideal when you need immediate feedback before writing a formal report.

Summary

• openspec feedback – The fastest method; auto-creates GitHub issues with the feedback label via src/commands/feedback.ts, with graceful fallback to manual copy-paste.
• GitHub Issues – The canonical tracker at Fission-AI/OpenSpec/issues; use for detailed bug reports and feature requests.
• Discord – Best for informal discussion and quick questions; documented in docs/faq.md.

Frequently Asked Questions

What is the fastest way to report a bug in OpenSpec?

The openspec feedback CLI command is the fastest method. It automatically populates the issue title and body, applies the feedback label, and creates the issue via the GitHub CLI if available. This eliminates the need to navigate to the browser and manually format your report.

Does the openspec feedback command require GitHub CLI authentication?

Yes, for automatic issue creation. The command logic in src/commands/feedback.ts attempts to invoke the gh CLI (lines 122-140). If gh is not installed or not authenticated, the command falls back to printing a formatted issue template that you can manually copy and paste into the GitHub web interface.

Where can I find the official bug reporting guidelines?

Official channels are documented in docs/faq.md under the section "Where do I ask questions or report bugs?" and in docs/README.md. These files outline the three supported methods: GitHub Issues, Discord, and the openspec feedback command. Additionally, the feedback workflow template is defined in src/core/templates/workflows/feedback.ts.

What information should I include in an OpenSpec bug report?

Include your environment details (OS, Node.js version, OpenSpec version), steps to reproduce, expected behavior, and actual behavior. When using the CLI command, utilize the --body flag to provide structured formatting with newlines. Detailed context helps maintainers triage issues faster in the GitHub tracker.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}