gh-pmu

Praxis Management Utility — a GitHub CLI extension for project workflows, sub-issue hierarchies, and batch operations.

Note: gh-pmu is designed for Kanban-style GitHub Projects with status-based columns (Backlog, In Progress, In Review, Done). It integrates seamlessly with the IDPF-Praxis framework for structured development workflows, but works standalone without any framework.

Features

📋 Project Management - List, view, create, and update issues with project field values in one command

🔗 Sub-Issue Hierarchy - Create and manage parent-child issue relationships with progress tracking

⚡ Batch Operations - Intake untracked issues, triage with rules, split checklists into sub-issues

📊 Board View - Terminal Kanban board visualization

🚀 Workflow Commands - Branch management with artifact generation

🔄 Cross-Repository - Work with sub-issues across multiple repositories

Installation

gh extension install rubrical-works/gh-pmu

Upgrade

gh extension upgrade gh-pmu

Quick Start

# Initialize configuration
gh pmu init

# List issues with project metadata
gh pmu list

# View issue with project fields and sub-issue progress
gh pmu view 42

# Update status
gh pmu move 42 --status in_progress

# Create sub-issue
gh pmu sub create --parent 42 --title "Subtask"

# Start a branch (release, patch, or feature workflow)
gh pmu branch start --name release/v1.2.0
gh pmu move 42 --branch current
gh pmu branch close

Standalone Usage

gh pmu works as a standalone tool without any framework integration. The optional framework field in .gh-pmu.json enables workflow restrictions when used with process frameworks like IDPF.

Standalone (default):

• All commands work normally
• No workflow routing or approval gates
• Simple project management

With framework integration:

• Adds workflow restrictions and checkpoint discipline
• Structured patterns (epic→story hierarchies)
• Domain specialist role system

To use standalone, simply omit the framework field from your config:

{
  "project": {
    "owner": "your-org",
    "number": 1
  },
  "repositories": ["your-org/your-repo"],
  "fields": {
    "status": {
      "values": {"backlog": "Backlog", "in_progress": "In progress", "in_review": "In review", "done": "Done"}
    },
    "priority": {
      "values": {"p0": "P0", "p1": "P1", "p2": "P2"}
    }
  }
}

Documentation

Guide	Description
Configuration	Setup .gh-pmu.yml, field aliases, triage rules
Commands	Complete command reference with examples
Sub-Issues	Parent-child hierarchies, epics, progress tracking
Batch Operations	Intake, triage, and split workflows
Workflows	Branch management
gh vs gh pmu	When to use each CLI
Development	Building, testing, contributing

Commands

Project:    init, list, view, create, edit, comment, move, close, board, field
Sub-Issues: sub add, sub create, sub list, sub remove
Batch:      intake, triage, split
Labels:     label sync, label list, label add, label update, label delete
Workflows:  branch, validation, accept
Config:     config verify
Utilities:  filter, history

Run gh pmu --help for full command list.

Unique Capabilities

Flags and features not available in base gh CLI:

Command	Unique Flags	Purpose
list	--status, --priority, --has-sub-issues	Filter by project fields
view	--body-file, --body-stdout, --comments	Export body, show comments
create	--status, --priority, --branch, --from-file	Set project fields on create
edit	--body-file, --body-stdin, --remove-label	Round-trip body editing
close	--update-status	Move to 'done' before closing
move	--recursive, --dry-run, --depth, --branch	Cascade updates to sub-issues
sub create	--inherit-labels, --inherit-milestone	Inherit from parent issue
split	--from, --dry-run	Create sub-issues from checklist
branch	start, add, close, reopen, --tag	Branch-based deployment workflow

See gh vs gh pmu for detailed comparison.

Framework Integration

gh-pmu is the backbone of project management for framework-driven development. When paired with a process framework like IDPF-Praxis, it provides:

• Branch-tracked development — every feature, release, and patch gets a tracked branch with automatic sub-issue management
• Epic-to-story hierarchies — epics decompose into stories, each tracked through the full lifecycle (Backlog → In Progress → In Review → Done)
• Workflow enforcement — status transition validation prevents accidental state changes and ensures work follows the defined process
• Acceptance criteria gates — issues cannot be closed until all acceptance criteria are checked, maintaining quality standards
• Artifact generation — release notes and changelogs are generated automatically from tracked issues

For teams using IDPF-Praxis for structured development, gh-pmu replaces the need for external project management tools by keeping everything in GitHub — issues, project boards, branch tracking, and release management — all accessible from the terminal.

Attribution

This project builds upon work from @yahsan2:

• gh-pm
• gh-sub-issue

License

MIT