### Quickstart: Output Example

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

Illustrates the expected output when running the quickstart command, showing the fetching and conversion process.

```bash
Fetching PROJ-123...
Fetched issue: PROJ-123 - Implement authentication system
Walking dependencies...
  Fetching subtask: PROJ-124 - Add OAuth2 support
  Fetching subtask: PROJ-125 - Update user model
  Fetching linked issue: PROJ-110 - Design auth flow (blocks)
✓ Fetched 4 issue(s)
Converting to beads format...
✓ Conversion complete!
Issues created in .beads/issues/
```

--------------------------------

### Install jira-beads-sync from Source

Source: https://github.com/conallob/jira-beads-sync/blob/main/GETTING_STARTED.md

Install the jira-beads-sync tool directly from its source code using the Go toolchain. Ensure Go 1.21 or later is installed.

```bash
go install github.com/conallob/jira-beads-sync/cmd/jira-beads-sync@latest
```

--------------------------------

### Starting a New Feature Workflow

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Guides through the initial steps of starting a new feature, including importing the Jira issue, checking dependencies, and suggesting a branch name. Use this when beginning a new task.

```text
User: I'm starting work on the payment screen
Claude: I'll help you follow the team workflow. Which Jira issue is this for?

You: MOBILE-234

Claude: [Imports MOBILE-234 following project guidelines]

MOBILE-234: Payment screen redesign
Priority: p1
Status: open

Following the project workflow:

1. ✓ Imported from Jira (with 3 subtasks)
2. Create branch: `git checkout -b feat/MOBILE-234-payment-screen`
3. Ready to mark as in progress

Dependencies check:
- MOBILE-220: Payment API (✓ complete)
- MOBILE-225: Design system (✓ complete)

All dependencies resolved! You're good to start.

Shall I mark MOBILE-234 as in progress?

You: Yes

Claude: ✓ Marked MOBILE-234 as in progress
       ✓ Synced to Jira

According to the acceptance criteria, you need to:
- Implement new payment form UI
- Add credit card validation
- Add PayPal integration
- Write integration tests

Good luck! Let me know when you complete MOBILE-234.
```

--------------------------------

### Install jira-beads-sync CLI

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/OPENCODE_GUIDE.md

Install the jira-beads-sync CLI using Homebrew or Go.

```bash
# Using Homebrew
brew install conallob/tap/jira-beads-sync
```

```bash
# Or from source
go install github.com/conallob/jira-beads-sync/cmd/jira-beads-sync@latest
```

--------------------------------

### Run Interactive Jira Configuration

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/configure-jira.md

Execute this command to start the interactive setup for Jira credentials. It prompts for your Jira URL, username, and API token.

```bash
jira-beads-sync configure
```

--------------------------------

### Run Quickstart in Custom Directory

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

Change to the desired project directory before running the quickstart command to specify the output location for downloaded issues.

```bash
# Change directory before running
cd /path/to/project
jira-beads-sync quickstart PROJ-123
# Creates .beads/issues/ in current directory
```

--------------------------------

### Install jira-beads-sync via Homebrew

Source: https://github.com/conallob/jira-beads-sync/blob/main/GETTING_STARTED.md

Use Homebrew to tap the repository and install the jira-beads-sync tool. This is the recommended installation method for macOS and Linux.

```bash
brew tap conallob/tap
brew install jira-beads-sync
```

--------------------------------

### Install from Binary (Linux)

Source: https://github.com/conallob/jira-beads-sync/blob/main/README.md

Steps to download and install the jira-beads-sync binary for Linux (x86_64).

```bash
# Linux (x86_64)
curl -LO https://github.com/conallob/jira-beads-sync/releases/latest/download/jira-beads-sync_Linux_x86_64.tar.gz
tar xzf jira-beads-sync_Linux_x86_64.tar.gz
sudo mv jira-beads-sync /usr/local/bin/
```

--------------------------------

### Install jira-beads-sync Plugin Locally

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Clone the plugin repository and start Claude Code with the plugin directory specified.

```bash
# Clone the repository
git clone https://github.com/conallob/jira-beads-sync.git

# Start Claude Code with plugin enabled
claude --plugin-dir /path/to/jira-beads-sync
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/conallob/jira-beads-sync/blob/main/CONTRIBUTING.md

Steps to clone the repository and install necessary Go dependencies, including the protobuf compiler plugin.

```bash
git clone https://github.com/conallob/jira-beads-sync.git
cd jira-beads-sync
go mod download
go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
```

--------------------------------

### Install jira-beads-sync CLI

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Install the jira-beads-sync CLI tool using Homebrew or Go. Ensure it's in your PATH.

```bash
# Using Homebrew
brew install conallob/tap/jira-beads-sync

# Or from source
go install github.com/conallob/jira-beads-sync/cmd/jira-beads-sync@latest
```

--------------------------------

### Fetch a Jira issue and its dependencies with `quickstart`

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Use the `quickstart` command to fetch a single Jira issue by its key or URL, along with its entire dependency tree (subtasks, linked issues, parents). The fetched issues are saved to `.beads/issues.jsonl` and `.beads/epics.jsonl`.

```bash
# Using an issue key (base URL taken from config)
jira-beads-sync quickstart PROJ-123
#jira-beads-sync quickstart
# ========================
#
# Using issue key: PROJ-123
#
# Fetching PROJ-123 and its dependencies...
# Fetching PROJ-123...
# Fetching PROJ-124...
# Fetching PROJ-125...
# Fetching PROJ-110...
#
# ✓ Fetched 4 issue(s)
#
# Converting to beads format...
#
# ✓ Conversion complete!
```

--------------------------------

### Install jira-beads-sync via Homebrew or Go

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Install the tool using Homebrew for macOS/Linux or the Go toolchain. Ensure you have Go installed for the latter method.

```bash
# Homebrew (macOS/Linux)
brew install conallob/tap/jira-beads-sync
```

```bash
# Go toolchain
go install github.com/conallob/jira-beads-sync/cmd/jira-beads-sync@latest
```

--------------------------------

### Install from Binary (macOS)

Source: https://github.com/conallob/jira-beads-sync/blob/main/README.md

Steps to download and install the jira-beads-sync binary for macOS on Apple Silicon.

```bash
# macOS (Apple Silicon)
curl -LO https://github.com/conallob/jira-beads-sync/releases/latest/download/jira-beads-sync_Darwin_arm64.tar.gz
tar xzf jira-beads-sync_Darwin_arm64.tar.gz
sudo mv jira-beads-sync /usr/local/bin/
```

--------------------------------

### Onboard New Developer with Epic

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Use `jira-beads-sync quickstart` to import an onboarding epic and set up initial tasks for a new developer.

```bash
jira-beads-sync quickstart ONBOARD-10
```

--------------------------------

### Verify Jira Configuration with Quickstart

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/configure-jira.md

Test your Jira configuration by running the quickstart command with a known issue key. This helps confirm that the credentials and URL are set up correctly.

```bash
jira-beads-sync quickstart <test-issue-key>
```

--------------------------------

### Quickstart: Import Epic and its Issues

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

Fetches an epic and all its associated stories and subtasks from Jira, converting them to beads format and saving them locally.

```bash
jira-beads-sync quickstart PROJ-100
```

--------------------------------

### Install Jira-Beads-Sync CLI Tool

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Provides commands for installing the jira-beads-sync CLI tool using Homebrew or Go.

```bash
brew install conallob/tap/jira-beads-sync
# or
go install github.com/conallob/jira-beads-sync/cmd/jira-beads-sync@latest
```

--------------------------------

### Workflow: Import and Annotate Issue

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/annotate-issue.md

This example shows a multi-step workflow: first importing an issue from Jira, then annotating it with a repository. This is useful for initial setup and association.

```bash
jira-beads-sync quickstart PROJ-100
```

```bash
jira-beads-sync annotate proj-100 https://github.com/org/mobile-app
```

--------------------------------

### Jira API Configuration Example (YAML)

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

An example configuration file demonstrating how to set up Jira API credentials and authentication method for the sync tool.

```yaml
jira:
  base_url: https://jira.example.com
  username: user@company.com
  api_token: your-token-here
  auth_method: bearer  # or "basic"
```

--------------------------------

### Combine Import and Show Commands

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

Chain the quickstart command with the 'bd show' command using '&&' to immediately view imported issues. This is useful for quick verification.

```bash
# Import and immediately view
jira-beads-sync quickstart PROJ-123 && bd show proj-123
```

--------------------------------

### Quickstart: Import Jira Issues by URL

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

Fetches a Jira issue and its dependencies from a full URL, converting them to beads format and saving them locally.

```bash
jira-beads-sync quickstart https://acme.atlassian.net/browse/PROJ-123
```

--------------------------------

### Quickstart: Import Jira Issue via URL

Source: https://github.com/conallob/jira-beads-sync/blob/main/GETTING_STARTED.md

Import a Jira issue by providing its full URL. This is an alternative to using just the issue key.

```bash
jira-beads-sync quickstart https://jira.example.com/browse/PROJ-123
```

--------------------------------

### Start Claude with Plugin

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Begin your session by launching Claude Code and specifying the plugin directory.

```bash
cd /path/to/your/project
claude --plugin-dir /path/to/jira-beads-sync
```

--------------------------------

### Install jira-beads-sync using macOS Apple Silicon binary

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Download and install the pre-built binary for macOS Apple Silicon. Ensure you have `curl` and `tar` installed.

```bash
# macOS Apple Silicon binary
curl -LO https://github.com/conallob/jira-beads-sync/releases/latest/download/jira-beads-sync_Darwin_arm64.tar.gz
tar xzf jira-beads-sync_Darwin_arm64.tar.gz
sudo mv jira-beads-sync /usr/local/bin/
```

--------------------------------

### Example Conversion Interaction

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/convert-jira-export.md

This example demonstrates a typical user interaction for converting a Jira export file and the expected output messages from the tool.

```bash
[Runs: jira-beads-sync convert jira-export.json]

Converting jira-export.json to beads format...
✓ Conversion complete!
  3 epic(s) written to .beads/epics/
  15 issue(s) written to .beads/issues/

The issues have been converted and saved to .beads/ directory.

To see the imported issues, run: bd list
```

--------------------------------

### Download and Install jira-beads-sync Binary (Linux)

Source: https://github.com/conallob/jira-beads-sync/blob/main/GETTING_STARTED.md

Download the pre-built binary for Linux (x86_64) and move it to your system's PATH. Ensure you have curl and tar installed.

```bash
curl -LO https://github.com/conallob/jira-beads-sync/releases/latest/download/jira-beads-sync_Linux_x86_64.tar.gz
tar xzf jira-beads-sync_Linux_x86_64.tar.gz
sudo mv jira-beads-sync /usr/local/bin/
```

--------------------------------

### Automate Issue Import with a Bash Script

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

This bash script demonstrates how to import multiple Jira issues by iterating through an array of issue keys and calling `jira-beads-sync quickstart` for each. It provides a basic example of scripting the import process.

```bash
#!/bin/bash
# Import issues from a list

ISSUES=(
  "PROJ-123"
  "PROJ-456"
  "PROJ-789"
)

for issue in "${ISSUES[@]}"; do
  echo "Importing $issue..."
  jira-beads-sync quickstart "$issue"
done

echo "✓ All issues imported"
bd list
```

--------------------------------

### Initial Jira Import with Quickstart

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

Perform a first-time import of issues, including epics and their associated stories and subtasks, from Jira. This command requires configuration to be set up beforehand.

```bash
jira-beads-sync quickstart PROJ-123
```

```bash
jira-beads-sync quickstart AUTH-100
```

```bash
jira-beads-sync quickstart PROJ-123
jira-beads-sync quickstart TEAM-456
jira-beads-sync quickstart INFRA-789
```

```bash
jira-beads-sync quickstart $EPIC_KEY
```

--------------------------------

### Jira Integration Markdown Example

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

Example of how to document Jira integration within a project's .claude/CLAUDE.md file. It outlines import, view, and sync functionalities.

```markdown
# Jira Integration

When working on Jira issues, sync them with beads:
- Import: Ask Claude to "import <jira-key> from Jira"
- View: Use `bd list` and `bd show <id>` to see imported issues
- Sync back: Ask Claude to "sync beads changes to Jira"
- The tool automatically fetches all dependencies and maintains bidirectional sync
```

--------------------------------

### Verify jira-beads-sync Installation

Source: https://github.com/conallob/jira-beads-sync/blob/main/GETTING_STARTED.md

Check if the jira-beads-sync tool is installed correctly by running the version command. This confirms the binary is accessible and executable.

```bash
jira-beads-sync version
```

--------------------------------

### Workflow: Start Work on a Feature

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

This workflow demonstrates starting work on a Jira issue, including importing it with dependencies, checking readiness, and updating its status.

```text
You: I'm starting work on PROJ-123

Claude: Let me import PROJ-123 and its dependencies.
[Imports issue and subtasks]

PROJ-123: Implement authentication system
├─ PROJ-124: Add OAuth2 support
├─ PROJ-125: Update user model
└─ Depends on: PROJ-110 (Design complete)

All dependencies are resolved. You can start with PROJ-124.

You: Great, mark PROJ-124 as in progress

Claude: [Updates status]
✓ PROJ-124 is now in progress

You: Show me the acceptance criteria

Claude: PROJ-124 acceptance criteria:
1. OAuth2 flow implemented
2. Token storage configured
3. Tests passing
```

--------------------------------

### Jira JQL Examples

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

Provides examples of common JQL queries for fetching specific sets of Jira issues. Remember to enclose the entire JQL in single quotes.

```bash
# Current user's open tasks: 'assignee = currentUser() AND status = Open'
```

```bash
# Sprint issues: 'project = MYPROJ AND sprint = 42'
```

```bash
# High priority bugs: 'project = MYPROJ AND issuetype = Bug AND priority = High'
```

```bash
# Updated recently: 'project = MYPROJ AND updated >= -7d'
```

```bash
# Multiple statuses: 'project = MYPROJ AND status IN ("To Do", "In Progress")'
```

--------------------------------

### jira-beads-sync configuration file example

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

An example of the configuration file (`~/.config/jira-beads-sync/config.yml`) that stores Jira connection details. This file can be manually edited or generated by the `configure` command.

```yaml
# Equivalent config file (~/.config/jira-beads-sync/config.yml)
cat ~/.config/jira-beads-sync/config.yml
#jira:
#  base_url: https://acme.atlassian.net
#  username: user@example.com
#  api_token: your-api-token-here
#  auth_method: basic   # or "bearer" for PAT-based auth
```

--------------------------------

### Quickstart: Import a Jira Issue

Source: https://github.com/conallob/jira-beads-sync/blob/main/GETTING_STARTED.md

Import a specific Jira issue and its related issues (subtasks, dependencies) into your local repository as YAML files. Replace `PROJ-123` with your actual Jira issue key.

```bash
jira-beads-sync quickstart PROJ-123
```

--------------------------------

### Import First Jira Issue

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Use the natural language prompt to import a Jira issue and its dependencies. Claude will execute the 'quickstart' command.

```text
You: Import PROJ-123 from Jira

Claude: I'll import PROJ-123 and its dependencies from Jira.
[Runs: jira-beads-sync quickstart PROJ-123]

✓ Fetched 5 issue(s)
✓ Conversion complete!

Issues imported:
- proj-123: "Implement authentication system"
- proj-124: "Add OAuth2 support" (subtask)
- proj-125: "Update user model" (subtask)
```

--------------------------------

### Quickstart Jira Sync

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Use a full Jira URL to quickly sync issues. The base URL is extracted automatically. Inspect the output using 'cat .beads/issues.jsonl'.

```bash
jira-beads-sync quickstart https://acme.atlassian.net/browse/PROJ-123
```

```bash
cat .beads/issues.jsonl
```

```bash
# {"id":"proj-123","title":"Implement authentication system","status":"in_progress","priority":1,...}
# {"id":"proj-124","title":"Add OAuth2 support","status":"open","priority":1,"dependsOn":["proj-123"],...}
```

```bash
jira-beads-sync quickstart PROJ-123 && bd show proj-123
```

--------------------------------

### Download and Install jira-beads-sync Binary (macOS)

Source: https://github.com/conallob/jira-beads-sync/blob/main/GETTING_STARTED.md

Download the pre-built binary for macOS (Apple Silicon) and move it to your system's PATH. Ensure you have curl and tar installed.

```bash
curl -LO https://github.com/conallob/jira-beads-sync/releases/latest/download/jira-beads-sync_Darwin_arm64.tar.gz
tar xzf jira-beads-sync_Darwin_arm64.tar.gz
sudo mv jira-beads-sync /usr/local/bin/
```

--------------------------------

### Start Claude with Jira Plugin (Development)

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

Launch the Claude application with the Jira-Beads-Sync plugin enabled when developing directly from the repository.

```bash
claude --plugin-dir .
```

--------------------------------

### Batch Issue Import Example

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Demonstrates importing multiple Jira issues in a single request to Claude.

```text
You: Import these issues: PROJ-123, PROJ-456, PROJ-789

Claude: I'll import all three issues...
[Runs multiple imports]
✓ Imported PROJ-123 (5 related issues)
✓ Imported PROJ-456 (3 related issues)
✓ Imported PROJ-789 (2 related issues)
Total: 10 unique issues
```

--------------------------------

### Troubleshoot 'command not found: jira-beads-sync'

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/OPENCODE_GUIDE.md

If the jira-beads-sync command is not found, ensure the binary is in your system's PATH. If not, add the installation directory to your PATH.

```bash
which jira-beads-sync
# If not found, add the install location to your PATH
export PATH="$PATH:$(go env GOPATH)/bin"
```

--------------------------------

### Cross-Project Issue Import Example

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Illustrates importing issues from different Jira projects and handling cross-project dependencies.

```text
You: Import the authentication epic from project AUTH and the API epic from project PLATFORM

Claude: Importing from multiple projects...
✓ AUTH-100 and 12 related issues
✓ PLATFORM-200 and 8 related issues

Cross-project dependency found: AUTH-105 depends on PLATFORM-201
Both issues imported successfully.
```

--------------------------------

### AI Interaction Example

Source: https://github.com/conallob/jira-beads-sync/blob/main/README.md

Shows how to interact with jira-beads-sync using natural language through an AI assistant like Claude Code.

```text
You: Import PROJ-123 from Jira

Claude: [Imports issue and dependencies]
        ✓ Fetched 5 issue(s)
        Ready to work!
```

--------------------------------

### Example Jira Issue Interaction

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Demonstrates a conversational interaction with Claude for fetching and understanding Jira issue details.

```text
You: Show me what PROJ-123 is about

Claude: Let me fetch that issue.
[Imports if not present]

PROJ-123: Implement authentication system

Description:
Add OAuth2 authentication to support third-party logins...

Acceptance Criteria:
- OAuth2 flow implemented
- Tests cover all scenarios
- Documentation updated

Related Issues:
- Blocked by: PROJ-110 (complete)
- Blocks: PROJ-130, PROJ-131

You: Has this been started?

Claude: PROJ-123 status: in_progress
Assigned to: alice
Last updated: 2 days ago

You: Show me the subtasks

Claude: PROJ-123 has 3 subtasks:
- PROJ-124: Add OAuth2 support (closed)
- PROJ-125: Update user model (in_progress)
- PROJ-126: Write tests (open)
```

--------------------------------

### Sprint Planning and Issue Listing

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Demonstrates the initial step of sprint planning by quickly starting a sprint issue and then listing all issues sorted by priority. Use this at the beginning of a sprint.

```bash
# 1. Sprint Planning
jira-beads-sync quickstart SPRINT-15
bd list --sort priority
```

--------------------------------

### Configure Jira Credentials Interactively

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

If no configuration is found via environment variables or config file, the tool will prompt you to run `jira-beads-sync configure` to set up your credentials interactively. This is the fallback method for initial setup.

```bash
$jira-beads-sync quickstart PROJ-123
No configuration found. Please run 'jira-beads-sync configure' first.
```

--------------------------------

### Example: Import Sprint Issues

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/fetch-by-label.md

Demonstrates importing all issues associated with a specific sprint label. The output shows the number of issues found and fetched, including dependencies, and the conversion to beads format.

```bash
jira-beads-sync fetch-by-label sprint-23
```

--------------------------------

### Natural Language Issue Importing Examples

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Demonstrates various natural language phrases that Claude understands for importing Jira issues and their dependencies.

```text
You: Import PROJ-123 from Jira

You: Fetch the Jira issue TEAM-456 and all its dependencies

You: Pull PROJ-789 from Jira into beads

You: Get me the Jira issue at https://jira.example.com/browse/PROJ-100

You: I need to work on PROJ-123, can you import it?
```

--------------------------------

### Example: Import Release Label Issues

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/fetch-by-label.md

Shows how to import issues for a release milestone using a release label. The output indicates the total number of issues imported and their availability in the .beads/issues/ directory.

```bash
jira-beads-sync fetch-by-label v2.0-release
```

--------------------------------

### Import a Feature Branch with CLI

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Use the CLI to import a Jira issue and its dependencies. Configure the tool first, then import using 'quickstart'. View and manage imported issues with 'bd list' and 'bd show'. Update issue status and switch to a new branch.

```bash
# Setup (one-time)
jira-beads-sync configure

# Import the feature issue
jira-beads-sync quickstart FEAT-100

# Output:
# Fetching FEAT-100...
# Fetched issue: FEAT-100 - New user dashboard
# Walking dependencies...
#   Fetching subtask: FEAT-101 - Design wireframes
#   Fetching subtask: FEAT-102 - Implement layout
#   Fetching subtask: FEAT-103 - Add user widgets
#   Fetching linked issue: FEAT-90 - User API (blocks)
# ✓ Fetched 5 issue(s)
# ✓ Conversion complete!

# View imported issues
bd list
# proj-123    FEAT-100  New user dashboard        open     p1
# proj-124    FEAT-101  Design wireframes         open     p2
# proj-125    FEAT-102  Implement layout          open     p2
# proj-126    FEAT-103  Add user widgets          open     p2
# proj-127    FEAT-90   User API                  closed   p1

# Check what to work on first
bd show proj-123
# Dependencies:
#   - proj-127 (FEAT-90) [closed] ✓

# Start working
bd update proj-123 --status in_progress
git checkout -b feat/user-dashboard
```

--------------------------------

### Local Issue Management with Beads

Source: https://github.com/conallob/jira-beads-sync/blob/main/README.md

Examples of using beads commands to manage imported Jira issues locally, including listing, showing details, and updating status.

```bash
bd list                              # List all issues
bd show proj-123                     # Show details
bd update proj-123 --status in_progress
```

--------------------------------

### CLAUDE.md Project Integration Example

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

This markdown snippet shows how to integrate Jira issue tracking commands into a project's .claude/CLAUDE.md file for a streamlined workflow.

```markdown
# Project: Acme Web Application

## Issue Tracking

This project uses Jira for issue tracking. Issues are synced with beads for local development.

### Workflow

When starting work on a feature:
1. Import the Jira issue: "Import PROJ-123 from Jira"
2. Review the issue: "Show me PROJ-123"
3. Create a feature branch: `git checkout -b feat/PROJ-123-description`
4. Mark as in progress: "Mark PROJ-123 as in progress"
5. Work on the feature
6. When done: "Close PROJ-123 and sync to Jira"

### Issue Commands

Quick reference for common operations:
- Import: "Import PROJ-123 from Jira"
- Status: "What's the status of PROJ-123?"
- Update: "Mark PROJ-123 as in progress"
- Complete: "Close PROJ-123"
- Sync: "Sync all changes to Jira"
- List: "Show me all open issues"

```

--------------------------------

### Opencode Natural Language Commands

Source: https://github.com/conallob/jira-beads-sync/blob/main/README.md

Examples of natural language commands to interact with Jira issues using Opencode. Add project instructions to enable CLI invocation.

```text
You: Import PROJ-123 from Jira
You: Fetch all issues for sprint-47
You: Sync my changes back to Jira
```

--------------------------------

### Example: Import Team Label Issues

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/fetch-by-label.md

Illustrates fetching issues tagged with a team-specific label. The output confirms the number of issues found with the label and the total number of issues imported, including dependencies.

```bash
jira-beads-sync fetch-by-label team-frontend
```

--------------------------------

### Workflow: Plan Sprint Work

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

This workflow shows how to import a sprint epic, determine priority order based on dependencies and priorities, and identify the next issue to start.

```text
You: Import the sprint epic SPRINT-42

Claude: Importing SPRINT-42 and all stories...
[Fetches 15 issues]

✓ Imported 15 issues:
- 3 epics
- 8 stories
- 4 subtasks

You: What's the priority order?

Claude: Based on priorities and dependencies:

P0 (Critical):
- PROJ-120: Fix authentication bug

P1 (High):
- PROJ-121: User dashboard
- PROJ-122: API endpoints

P2 (Medium):
- PROJ-123: Documentation
- PROJ-124: Refactoring

You: Let's start with PROJ-120

Claude: PROJ-120: Fix authentication bug
Status: open
Assignee: unassigned
No blocking dependencies - ready to start!
```

--------------------------------

### Conventional Commit Message Examples

Source: https://github.com/conallob/jira-beads-sync/blob/main/CONTRIBUTING.md

Examples of commit messages following the conventional commit format for different types of changes.

```git
feat: add support for Jira custom fields
fix: handle nil assignee in converter
docs: update installation instructions
```

--------------------------------

### Configure jira-beads-sync interactively

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Run the interactive wizard to set up Jira credentials. This command prompts for necessary information and saves the configuration to `~/.config/jira-beads-sync/config.yml`. It supports both basic and bearer token authentication methods.

```bash
# Interactive wizard
jira-beads-sync configure
# Jira Configuration
# ==================
#
# Jira Base URL (e.g., https://jira.example.com): https://acme.atlassian.net
#
# Authentication Method:
#   1. Basic Auth (username + API token) - for Jira Cloud with .atlassian.net
#   2. Bearer Token - for Jira Cloud with custom domain or Jira Server/Data Center
# Select authentication method (1 or 2) [1]: 1
#
# Jira Username/Email: user@example.com
# Jira API Token: **********************
# ✓ Configuration saved successfully
```

--------------------------------

### Configure jira-beads-sync Plugin Permanently

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Add the plugin directory to your Claude Code settings for permanent installation.

```json
# In your project's .claude/settings.json
{
  "pluginDirs": ["/path/to/jira-beads-sync"]
}
```

--------------------------------

### Generate Protobuf Files and Build Project

Source: https://github.com/conallob/jira-beads-sync/blob/main/CONTRIBUTING.md

Commands to generate Go code from protobuf definitions and to build the project.

```bash
make proto
make build
```

--------------------------------

### Manage Cross-Team Dependency

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Import a dependency issue and check its status. The command can be run again to get the latest status.

```bash
jira-beads-sync quickstart PLATFORM-456
```

--------------------------------

### Claude Code Natural Language Commands

Source: https://github.com/conallob/jira-beads-sync/blob/main/README.md

Examples of natural language commands to interact with Jira issues using Claude Code.

```text
You: Import PROJ-123 from Jira
You: Show me all open issues
You: Mark PROJ-124 as in progress
You: Sync changes back to Jira
```

--------------------------------

### Build the CLI Tool in Go

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

Use this command to compile the Go project into an executable binary. Specify the output file name with -o.

```bash
go build -o jira-beads-sync ./cmd/jira-beads-sync
```

--------------------------------

### Run All Verification Steps

Source: https://github.com/conallob/jira-beads-sync/blob/main/CONTRIBUTING.md

Command to execute all verification steps, including tests, formatting, and linting.

```bash
make verify
```

--------------------------------

### Import Jira Issue and Work Locally

Source: https://github.com/conallob/jira-beads-sync/blob/main/README.md

Demonstrates the basic workflow of importing a Jira issue, working with it locally using beads commands, and syncing changes back to Jira.

```bash
# Import a Jira issue with all its dependencies
jira-beads-sync quickstart PROJ-123

# Work locally with beads
bd list
bd show proj-123
bd update proj-123 --status in_progress

# Sync changes back to Jira
jira-beads-sync sync
```

--------------------------------

### Conditional Issue Import Example

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Shows how to request Claude to import a Jira issue only if it doesn't already exist locally, with an option to refresh.

```text
You: Import PROJ-123 if it's not already imported

Claude: Checking if PROJ-123 exists locally...
[Checks .beads/issues/]
PROJ-123 already exists. Would you like to refresh it?

You: Yes, refresh it

Claude: [Re-imports to get latest data]
✓ Updated PROJ-123 and 4 related issues
```

--------------------------------

### Error Handling: Issue Not Found

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/annotate-issue.md

Example of an error message when attempting to annotate an issue that does not exist. It suggests importing the issue first if it's from Jira.

```bash
Error: issue file not found: .beads/issues/proj-999.yaml

Make sure the issue exists (run quickstart to import from Jira first)

```

--------------------------------

### Annotate Issue with Simple Repository Name

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/annotate-issue.md

Example of annotating a Jira issue using a short repository name. The tool stores the provided name as is.

```bash
jira-beads-sync annotate proj-456 backend-api
```

--------------------------------

### Display Help Information

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

Shows general help information or specific help for a given command. Use this to understand available commands and their options.

```bash
jira-beads-sync help [command]
```

```bash
jira-beads-sync help
```

```bash
jira-beads-sync help quickstart
```

```bash
jira-beads-sync help sync
```

--------------------------------

### Integrate with beads: Show Dependencies

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Retrieve and display the dependencies for a specific Jira issue using the 'bd show <issue-key>' command.

```text
You: What are the dependencies for proj-123?

Claude: Let me check the dependencies:
[Runs: bd show proj-123]

PROJ-123 depends on:
- PROJ-110: Design auth flow
- PROJ-112: Database schema
```

--------------------------------

### Configure Jira Credentials

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

Initiates an interactive wizard to set up Jira API credentials and saves them to the configuration file.

```bash
jira-beads-sync configure
```

```bash
$ jira-beads-sync configure
Enter Jira Base URL (e.g., https://yourcompany.atlassian.net): https://acme.atlassian.net
Enter Jira Username (email): user@example.com
Enter Jira API Token: **********************
Configuration saved to /home/user/.config/jira-beads-sync/config.yml
```

--------------------------------

### Configure Jira Credentials

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Run the configuration command and follow the prompts to enter your Jira Base URL, Username, and API Token.

```text
You: Configure my Jira credentials

Claude: I'll help you configure Jira credentials.
[Runs: jira-beads-sync configure]

Enter Jira Base URL: https://yourcompany.atlassian.net
Enter Jira Username: user@example.com
Enter Jira API Token: **********************
Configuration saved!
```

--------------------------------

### Jira Issue JSONL Output Format

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Example of the JSON Lines format used for storing Jira issue data locally. Each line is a self-contained JSON object.

```jsonl
// .beads/issues.jsonl — one JSON object per line
{"id":"proj-2","title":"Create login API endpoint","description":"Implement POST /api/login endpoint","status":"open","priority":1,"epic":"proj-1","assignee":"john@example.com","labels":["api","backend"],"dependsOn":["proj-4"],"created":"2024-01-02T10:00:00Z","updated":"2024-01-02T10:00:00Z","metadata":{"jiraKey":"PROJ-2","jiraId":"10002","jiraIssueType":"Subtask"}}
```

```jsonl
// .beads/epics.jsonl — one JSON object per line
{"id":"proj-1","name":"Implement User Authentication","description":"Add authentication system","status":"in_progress","created":"2024-01-01T10:00:00Z","updated":"2024-01-05T14:30:00Z","metadata":{"jiraKey":"PROJ-1","jiraId":"10001","jiraIssueType":"Epic"}}
```

--------------------------------

### Annotate Issue with GitHub Repository

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/annotate-issue.md

Example of annotating a Jira issue with a full GitHub repository URL. The command updates the issue's metadata with the provided repository.

```bash
jira-beads-sync annotate proj-123 https://github.com/org/frontend
```

--------------------------------

### Format Code in Go

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

Use 'go fmt' to automatically format all Go source files in the project according to standard Go style.

```bash
go fmt ./...                     # Format all code
```

--------------------------------

### Import Jira Issue and Create Branch

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Initiates work on a Jira issue by importing it, suggesting a branch name, and preparing to update its status. This is useful for starting new features.

```bash
You: I'm working on the user dashboard

Claude: Let me help you get started. Which Jira issue are you working on?

You: PROJ-456

Claude: [Imports PROJ-456 based on CLAUDE.md instructions]

✓ Imported PROJ-456: "New user dashboard"

Following the project workflow, I've:
1. ✓ Imported the issue from Jira
2. Ready for you to create a feature branch:
   `git checkout -b feat/PROJ-456-user-dashboard`
3. Ready to mark as in progress

Would you like me to mark PROJ-456 as in progress?
```

--------------------------------

### Run Tests and Linting

Source: https://github.com/conallob/jira-beads-sync/blob/main/CONTRIBUTING.md

Commands to run project tests, format code, and lint the codebase.

```bash
make test
make fmt
make lint
```

--------------------------------

### Import Epic and Dependencies from Jira

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Import an entire epic from Jira, including all its related stories and subtasks, by walking the dependency tree. This is essential for comprehensive epic planning.

```bash
jira-beads-sync quickstart AUTH-100
```

--------------------------------

### Import Jira Issue Tree via Claude Code

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Uses the `/import-jira` slash command in Claude Code to import a Jira issue and its dependencies. It internally calls `jira-beads-sync quickstart`.

```bash
/import-jira PROJ-123
# Claude runs: jira-beads-sync quickstart PROJ-123
# ✓ Fetched 5 issue(s)
# ✓ Conversion complete!
```

```bash
/import-jira https://acme.atlassian.net/browse/AUTH-100
# Imports epic and all 18 related issues
```

--------------------------------

### Use Case: Polyrepo Tracking Annotations

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/annotate-issue.md

Illustrates how to use the annotate command for tracking issues across different repositories, including frontend, backend, and cross-repo scenarios.

```bash
# Frontend issues
jira-beads-sync annotate proj-123 https://github.com/org/frontend
jira-beads-sync annotate proj-124 https://github.com/org/frontend

# Backend issues
jira-beads-sync annotate proj-125 https://github.com/org/backend
jira-beads-sync annotate proj-126 https://github.com/org/backend

# Cross-repo issues
jira-beads-sync annotate proj-127 https://github.com/org/frontend
jira-beads-sync annotate proj-127 https://github.com/org/backend

```

--------------------------------

### Workflow: Daily Standup Preparation

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

This workflow covers preparing for a daily standup by checking current tasks, viewing their status and blockers, and updating an issue to 'closed' and syncing it to Jira.

```text
You: What Jira issues am I working on?

Claude: [Checks beads]
You're currently working on:
- PROJ-124: In progress (assigned to you)
- PROJ-125: In progress (assigned to you)

You: Show me the status of each

Claude:
PROJ-124: Add OAuth2 support (in_progress)
- Last updated: 2 hours ago
- Blocks: PROJ-126, PROJ-127

PROJ-125: Update user model (in_progress)
- Last updated: yesterday
- No blockers

You: I finished PROJ-124, close it and sync to Jira

Claude: [Closes issue and syncs]
✓ PROJ-124 marked as closed
✓ Synced to Jira
✓ Jira updated: PROJ-124 status changed to "Done"
```

--------------------------------

### Integrate with beads: List Open Issues

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

After importing issues, you can ask Claude to list open issues using the 'bd list --status open' command.

```text
You: Show me all open issues

Claude: Here are the open issues:
[Runs: bd list --status open]
```

--------------------------------

### Run Jira Beads Sync CLI

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/CLI_GUIDE.md

The general pattern for executing any jira-beads-sync command.

```bash
jira-beads-sync <command> [options] [arguments]
```

--------------------------------

### Sprint Planning with CLI

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Import an entire sprint's issues using the CLI. List issues by priority, export them to JSON, and use 'jq' to count issues by status for analysis.

```bash
# Import the sprint epic
jira-beads-sync quickstart SPRINT-23

# List by priority
bd list --sort priority

# Export to JSON for analysis
bd list --format json > sprint-23-issues.json

# Count issues by status
bd list --format json | jq 'group_by(.status) | map({status: .[0].status, count: length})'
```

--------------------------------

### Generate Protobuf Code

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

Use the Protocol Buffer compiler (protoc) to generate Go code from .proto files. Ensure the module path and proto path are correctly specified.

```bash
protoc --go_out=. --go_opt=module=github.com/conallob/jira-beads-sync --proto_path=proto proto/jira.proto proto/beads.proto
```

--------------------------------

### Run Jira Issue Import

Source: https://github.com/conallob/jira-beads-sync/blob/main/commands/import-jira.md

Use this command to fetch a Jira issue and its dependency tree, convert it to beads format, and import it into your local beads repository. Provide either a full Jira URL or an issue key.

```bash
jira-beads-sync quickstart <jira-url-or-key>
```

--------------------------------

### Load Jira Beads Sync Plugin for Claude Code

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Instructions for loading the jira-beads-sync plugin into Claude Code, either for a single session or permanently.

```bash
# Load the plugin when starting Claude Code
claude --plugin-dir /path/to/jira-beads-sync
```

```json
# Or permanently in .claude/settings.json:
# { "pluginDirs": ["/path/to/jira-beads-sync"] }
```

--------------------------------

### Run Tests in Go

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

Execute all tests within the Go project. Use -v for verbose output or -run to target specific test functions.

```bash
go test ./...                    # Run all tests
go test -v ./...                 # Run with verbose output
go test -run TestFunctionName    # Run specific test
```

--------------------------------

### Test Jira Credentials

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/OPENCODE_GUIDE.md

Test your Jira credentials by running the 'whoami' command.

```bash
jira-beads-sync whoami
```

--------------------------------

### Fetch Jira Issues by JQL

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/OPENCODE_GUIDE.md

Import Jira issues using a JQL query.

```bash
jira-beads-sync fetch-jql '<jql>'
```

```bash
# Example: jira-beads-sync fetch-jql 'project = PROJ AND assignee = currentUser()'
```

--------------------------------

### Review Sprint Progress

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/EXAMPLES.md

Import sprint issues and list completed, in-progress, and not-started tasks using `jira-beads-sync` and `bd list`.

```bash
jira-beads-sync quickstart SPRINT-23
bd list --format json
```

--------------------------------

### Run Tests with Race Detection

Source: https://github.com/conallob/jira-beads-sync/blob/main/CONTRIBUTING.md

Command to run Go tests with race detection enabled to find potential data races.

```bash
go test -race ./...
```

--------------------------------

### Run the CLI Tool in Go

Source: https://github.com/conallob/jira-beads-sync/blob/main/CLAUDE.md

Execute the Go CLI tool. Arguments can be passed after the command to specify operational modes or parameters.

```bash
go run ./cmd/jira-beads-sync [args]
```

--------------------------------

### Verify Jira connectivity with `whoami`

Source: https://context7.com/conallob/jira-beads-sync/llms.txt

Use the `whoami` command to test your Jira credentials and connectivity. It calls the Jira API's `/myself` endpoint and displays user information and instance details.

```bash
jira-beads-sync whoami
#jira-beads-sync whoami
# ======================
#
# Testing Jira connection...
#
# ✓ Authentication successful
#
# Jira User Information:
#   Display Name:  Jane Smith
#   Email:         jane@example.com
#   Account ID:    5b10ac8d82e05b22cc7d4ef5
#   Active:        true
#
# Jira Instance:
#   Base URL:      https://acme.atlassian.net
#   Username:      jane@example.com
```

--------------------------------

### Configure Jira Credentials

Source: https://github.com/conallob/jira-beads-sync/blob/main/docs/PLUGIN_GUIDE.md

Use these phrases to initiate Jira credential configuration.

```text
You: Configure Jira credentials
You: Set up my Jira API token
You: Help me connect to Jira
You: I need to configure jira-beads-sync
```