quber-workflow 0.3.2
Shared Claude Code workflow for Quber projects (Jira + GitHub automation)
Requires Python: >=3.9
Keywords: automation, claude, github, jira, workflow

# Quber Workflow

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

[![PyPI](https://img.shields.io/pypi/v/quber-workflow)](https://pypi.org/project/quber-workflow/)
[![Python](https://img.shields.io/pypi/pyversions/quber-workflow)](https://pypi.org/project/quber-workflow/)
[![License](https://img.shields.io/github/license/xmandeng/quber-workflow)](LICENSE)

## 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

```bash
pip install quber-workflow
```

Or using `uv`:

```bash
uv pip install quber-workflow
```

## Quick Start

### 1. Initialize a New Project

Navigate to your project directory and run:

```bash
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):

```bash
quber-workflow init
```

Or use a YAML config file:

```bash
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:

```bash
# GitHub CLI authentication
GH_TOKEN=ghp_...

# Jira REST API authentication
ATLASSIAN_USER_EMAIL=you@example.com
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:

```bash
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:

```bash
quber-workflow migrate
```

This creates backups before migrating your existing setup.

### Clean Git Exclusions

Remove workflow entries from `.git/info/exclude`:

```bash
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](https://docs.anthropic.com/en/docs/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](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](CONTRIBUTING.md) for:

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

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Related Projects

- [quber-analyst](https://github.com/xmandeng/quber-analyst) - Financial document analyzer
- [quber-excel](https://github.com/xmandeng/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