quber-workflow 0.3.1

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

Quber Workflow

Shared Claude Code workflow for Quber projects with Jira and GitHub automation.

What is Quber Workflow?

quber-workflow provides a standardized Claude Code workflow system for managing development workflows across Quber projects. It integrates Jira issue tracking with GitHub's pull request workflow through Claude Code agents and skills, with built-in LangSmith tracing for cost accountability.

Key Features

• Jinja2 Template System - All managed files rendered from templates with project-specific config
• Automated Jira Management - Agents handle issue creation, updates, and transitions
• GitHub PR Automation - Streamlined pull request creation and management
• LangSmith Tracing - Full token usage tracking for main agents and subagents
• Agent Teams Support - Experimental multi-agent coordination with subagent tracing
• Deny-by-Default Security - Enforces proper agent delegation and permissions
• Quality Standards - Built-in PR evidence requirements and workflow specs
• Lightweight - 95%+ reduction in context usage vs MCP servers

Installation

pip install quber-workflow

Or using uv:

uv pip install quber-workflow

Quick Start

1. Initialize a New Project

Navigate to your project directory and run:

quber-workflow init \
  --project my-project \
  --repo username/my-project \
  --jira-prefix PROJ \
  --jira-label my-project \
  --jira-url https://yoursite.atlassian.net

Or use interactive mode (prompts for missing values):

quber-workflow init

Or use a YAML config file:

quber-workflow init --config workflow.yaml

This creates:

.claude/
├── agents/
│   ├── jira-workflow.md       # Jira operations agent
│   ├── github-workflow.md     # GitHub operations agent
│   └── epic-manager.md       # Epic governance agent
├── hooks/
│   ├── stop_hook.sh           # LangSmith tracing (main session)
│   └── subagent_stop_hook.sh  # LangSmith tracing (subagents)
├── skills/
│   ├── github-operations/     # GitHub CLI scripts + SKILL.md
│   └── jira-operations/       # Jira REST API scripts + SKILL.md
├── settings.json              # Permissions, hooks, agent teams
└── .quber-workflow.yaml       # Saved config for updates
.github/workflows/
└── jira-transition.yml        # Automated Jira status updates
docs/
├── GITHUB_WORKFLOW_SPEC.md
├── ISSUES_SPEC.md
├── PR_EVIDENCE_GUIDELINES.md
└── PR_EVIDENCE_CHECKLIST.md
CLAUDE.md                      # Agent delegation rules
.env.example                   # Environment variable template

2. Configure Environment Variables

Copy .env.example to .env and fill in your credentials:

# GitHub CLI authentication
GH_TOKEN=ghp_...

# Jira REST API authentication
ATLASSIAN_USER_EMAIL=[e-mail]
ATLASSIAN_API_TOKEN=your-api-token
ATLASSIAN_SITE_NAME=https://yoursite.atlassian.net

# LangSmith tracing (enabled by default)
TRACE_TO_LANGSMITH=true
LANGSMITH_API_KEY=lsv2_pt_...
CC_LANGSMITH_PROJECT=my-project
CC_LANGSMITH_RUN_NAME=my-project

3. Configure GitHub Secrets

For the Jira transition workflow, add these repository secrets:

• JIRA_BASE_URL - Your Jira instance URL (e.g., https://yoursite.atlassian.net)
• JIRA_USER_EMAIL - Your Jira account email
• JIRA_API_TOKEN - Jira API token

Init Options

Flag	Default	Description
--project	Current directory name	Project name
--repo	(required)	GitHub repo (owner/repo)
--jira-prefix	QUE	Jira project prefix for issue keys
--jira-label	Same as project	Label auto-applied to Jira issues
--jira-url	(required)	Jira instance URL
--no-epic-manager	Enabled	Disable epic-manager agent
--no-langsmith	Enabled	Disable LangSmith tracing hooks
--no-agent-teams	Enabled	Disable experimental agent teams
--enable-logfire	Disabled	Enable Pydantic Logfire observability
--config	—	YAML config file (overrides all flags)

Usage

Update Workflow Files

Update to the latest workflow templates:

quber-workflow update

This re-renders templates from saved config while preserving your customizations.

Migrate from Manual Setup

If you previously set up workflows manually, migrate to the managed version:

quber-workflow migrate

This creates backups before migrating your existing setup.

Clean Git Exclusions

Remove workflow entries from .git/info/exclude:

quber-workflow clean

How It Works

Architecture

┌─────────────────────────────────────┐
│   Main Claude Agent (Your Project)  │
└────────────┬────────────────────────┘
             │
     ┌───────┴────────┐
     │                │
┌────▼─────┐   ┌─────▼────────┐
│  Jira    │   │   GitHub     │
│ Workflow │   │  Workflow    │
│  Agent   │   │   Agent      │
└────┬─────┘   └─────┬────────┘
     │               │
┌────▼─────┐   ┌─────▼────────┐
│  Jira    │   │   GitHub     │
│Operations│   │ Operations   │
│  Skill   │   │    Skill     │
└────┬─────┘   └─────┬────────┘
     │               │
┌────▼─────┐   ┌─────▼────────┐
│   Jira   │   │   GitHub     │
│ REST API │   │   gh CLI     │
└──────────┘   └──────────────┘

LangSmith Tracing

When enabled (default), every Claude Code response and subagent invocation is traced to LangSmith with full token usage data:

• Main session traces — Stop hook processes the session transcript
• Subagent traces — SubagentStop hook processes each subagent's transcript independently
• Run naming — Main session: {project}, Subagents: {project}({agent_type}) (e.g., quber-analyst(Explore))
• Parent linking — Subagent traces include parent_session_id in metadata

Why This Approach?

Minimal Context Usage

• Skills: ~100 tokens when loaded on-demand
• MCP Servers: ~46,000 tokens loaded upfront
• Result: 99%+ reduction in context overhead

Full Control

• All scripts visible in your repository
• Easy to audit, modify, and test
• No black-box dependencies

Cost Accountability

• Every LLM call (main + subagent) traced with token counts
• Per-project visibility in LangSmith dashboard
• Cache usage tracking (read + creation)

Requirements

Runtime

• Python 3.9+
• Claude Code CLI
• gh CLI (GitHub operations)
• jq (JSON parsing in hook and skill scripts)
• curl (Jira REST API, LangSmith API)
• uuidgen (LangSmith trace ID generation)

Development

See CONTRIBUTING.md for development setup.

Commands Reference

Command	Description
quber-workflow init	Initialize workflow in a new project
quber-workflow update	Update workflow files to latest version
quber-workflow migrate	Migrate from manual setup (creates backups)
quber-workflow clean	Remove workflow entries from git exclude

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for:

• Development environment setup
• Running tests and code quality checks
• Publishing releases
• Project structure

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/
• Repository: https://github.com/xmandeng/quber-workflow
• Issues: https://github.com/xmandeng/quber-workflow/issues