quber-workflow 0.1.2

Shared Claude Code workflow for Quber projects (Jira + GitHub automation)

Quber Workflow

Shared Claude Code workflow for Quber projects (Jira + GitHub automation).

Overview

quber-workflow provides a standardized Claude Code workflow across all Quber projects, including:

• Jira Workflow Agent - Automated Jira issue management
• GitHub Workflow Agent - Automated PR and branch workflows
• Skills - Bash scripts for Jira and GitHub operations
• GitHub Actions - Automated Jira status transitions
• Documentation - Workflow specs and PR evidence guidelines

Features

•  Deny-by-default permissions - Enforces proper agent delegation
•  Git worktree workflow - Prevents branch pollution
•  Jira automation - Status transitions on branch/PR events
•  PR evidence requirements - Embedded quality standards
•  Context-efficient - 95%+ reduction vs MCP servers

Installation

# Using pip
pip install quber-workflow

# Using uv (recommended)
uv pip install quber-workflow

Usage

Initialize New Project

# Navigate to your project directory
cd my-quber-project

# Initialize workflow
quber-workflow init \
  --project=my-project \
  --package=my_project \
  --repo=username/my-project \
  --jira-key=QUE

This creates:

• .claude/agents/ - jira-workflow and github-workflow agents
• .claude/skills/ - jira-operations and github-operations skills
• .claude/settings.json - deny-based permissions
• .github/workflows/jira-transition.yml - Jira automation
• docs/ - workflow specifications and guidelines

Update Existing Project

# Update workflow files to latest version
quber-workflow update

Migrate Existing Project

# Migrate with automatic backup
quber-workflow migrate

Environment Variables

Set these for Jira and GitHub operations:

# GitHub (for gh CLI)
export GH_TOKEN="ghp_..."
# or
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_..."

# Jira (for REST API)
export ATLASSIAN_SITE_NAME="yoursite.atlassian.net"
export ATLASSIAN_USER_EMAIL="[e-mail]"
export ATLASSIAN_API_TOKEN="your-api-token"

GitHub Secrets

Configure these secrets for GitHub Actions:

• JIRA_BASE_URL - Your Jira site URL
• JIRA_USER_EMAIL - Jira account email
• JIRA_API_TOKEN - Jira API token

Architecture

Agent-Based Workflow

Main Claude Agent (quber-analyst)
    \x00> jira-workflow agent (via Task tool)
       \x00> jira-operations skill (bash scripts)
           \x00> Jira REST API
    \x00> github-workflow agent (via Task tool)
        \x00> github-operations skill (bash scripts)
            \x00> gh CLI / GitHub API

Why This Approach?

• Minimal context overhead - ~100 tokens vs 46k with MCP servers
• On-demand loading - Skills load only when agents are invoked
• No external dependencies - Just bash, curl, jq, and gh CLI
• Easy debugging - Scripts are visible and testable
• Full control - Auditable code in your repository

Documentation

• GitHub Workflow Spec - PR and commit standards
• Issues Spec - Jira ticket specifications
• PR Evidence Guidelines - Evidence requirements
• PR Evidence Checklist - Quick reference

Development

Setup

# Clone repository
git clone https://github.com/xmandeng/quber-workflow.git
cd quber-workflow

# Install dependencies
uv sync

# Run tests
uv run pytest

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/

Build and Publish

# Build package
uv build

# Publish to Test PyPI
uv publish \
  --publish-url https://test.pypi.org/legacy/ \
  --username __token__ \
  --password $TEST_PYPI_TOKEN

# Publish to Production PyPI
uv publish --username __token__ --password $PYPI_TOKEN

Requirements

• Python >= 3.9
• gh CLI (for GitHub operations)
• jq (for JSON parsing)
• curl (for Jira REST API)

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Related Projects

• quber-analyst - Financial document analyzer
• quber-excel - Excel parser with spatial fidelity

Links

• PyPI: https://pypi.org/project/quber-workflow/
• Test PyPI: https://test.pypi.org/project/quber-workflow/
• Repository: https://github.com/xmandeng/quber-workflow
• Issues: https://github.com/xmandeng/quber-workflow/issues