@bizimind/pmx

v0.1.2

Published

3 months ago

PMX - Project Management Extended: GitHub Projects V2 CLI with advanced workflow control

0High
0Medium
0Low

ori-s

pmx bizimind github project cli automation ai-agents

PMX - Project Management Extended

A powerful CLI tool for managing GitHub Projects V2 with fine-grained permission control, designed for AI agent workflows and human collaboration.

Features

🤖 Profile-Based Security - Fine-grained command and property-level access control
🔐 Flexible Permissions - Allow/require rules with implicit defaults
📋 Complete Project Management - Create, read, update, delete, and transition items
🎨 Rich Output Formats - Table, JSON output options with batch operations
⚡ Fast & Reliable - Built with TypeScript, Zod validation, and GraphQL
🛠️ IDE Support - JSON Schema generation for YAML profile auto-completion
📊 Workflow Integration - Supports complete product development workflows

Installation

# Clone repository
git clone https://github.com/ori-shalom/bizimind.git
cd bizimind/packages/project-cli

# Install dependencies
pnpm install

# Build and link globally
pnpm build
npm link

# Verify installation
pmx --help

Quick Start

1. Setup

You'll need:

GitHub Personal Access Token with project scope
Project ID from your GitHub project (format: PVT_xxxxx)

Set environment variables:

export PMX_GH_TOKEN="ghp_your_personal_access_token"
export PMX_GH_PROJECT="PVT_your_project_id"

# Optional: Default profile for agent permissions
export PMX_PROFILE="profiles/my-agent.yml"

2. Basic Usage

# Create a new item
pmx add -s tasks -t "Implement feature" -b "Feature description"

# List items
pmx ls
pmx ls -s in-progress  # Filter by status

# Move items through workflow
pmx mv -s code-review PVTI_abc123

# Update item properties
pmx set -p p1 -m l PVTI_abc123

# Get item details
pmx get PVTI_abc123

# Batch operations
pmx mv -s done PVTI_abc123 PVTI_def456
pmx rm -y $(pmx ls -s done -q)

Profile-Based Permissions

Profiles enable fine-grained permission control for AI agents and users, defining what commands can be executed and how they interact with project items.

Profile Structure

# yaml-language-server: $schema=../profile-schema.json

name: agent-name
description: Agent description
project: PVT_your_project_id

commands:
  <command>:
    <property>:
      allow: <value> # Allowed argument values
      require: <value> # Required current state
      default: <value> # Default value if not provided

Permission Properties

status: Item workflow status (draft-ideas, tasks, in-progress, code-review, done, etc.)
priority: Item priority level (p0, p1, p2)
size: Item size estimate (xs, s, m, l, xl)

Permission Semantics

allow: Restricts what argument values can be passed
require: Requires specific current item state before operation
default: Provides default when user omits argument
Implicit default: Single allowed value becomes automatic default

Example Profiles

Idea Generator (can only create draft ideas):

commands:
  add:
    status:
      allow: draft-ideas
    priority:
      allow: p2
  ls:
    status:
      allow: draft-ideas

Developer (task workflow management):

commands:
  get: # Unrestricted viewing
  mv:
    - status:
        require: tasks
        allow: in-progress
    - status:
        require: in-progress
        allow: code-review
  set:
    size:
      allow: [xs, s, m, l, xl]

Full Access (unrestricted):

commands:
  get:
  add:
  ls:
  set:
  mv:
  rm:

Command Reference

Global Options

-P, --profile FILE   # Profile configuration file path
-v, --verbose        # Enable detailed logging
-j, --json           # Output results in JSON format
-h, --help           # Show command help

`pmx add` - Create Items

pmx add [options]

Options:
  -s, --status <status>      Item status (required unless profile default)
  -t, --title <title>        Item title (required)
  -b, --body <body>          Item description
  -p, --priority <priority>  Item priority (p0, p1, p2)
  -m, --size <size>          Size estimate (xs, s, m, l, xl)

Examples:
  pmx add -s tasks -t "New Feature" -b "Description" -p p1 -m m
  cat feature.md | pmx add -s tasks -t "Implement feature"  # Pipe body
  pmx -P agent.yml add -t "Auto-generated idea"           # With profile

`pmx ls` - List Items

pmx ls [options]

Options:
  -s, --status <status>      Filter by status
  -p, --priority <priority>  Filter by priority
  -l, --limit <number>       Limit results (default: 50)
  -q, --quiet               Output only item IDs for scripting

Examples:
  pmx ls                                      # List all items
  pmx ls -s in-progress                      # Filter by status
  pmx ls --json -l 10                       # JSON output with limit
  pmx mv -s done $(pmx ls -s demo -q)       # Command chaining

`pmx get` - Get Item Details

pmx get <id>

Example:
  pmx get PVTI_abc123

`pmx set` - Update Item Properties

pmx set [options] <id> [id2] [id3]...

Options:
  -t, --title <title>        New title
  -b, --body <body>          New description
  -p, --priority <priority>  New priority
  -m, --size <size>          New size estimate

Examples:
  pmx set -p p0 -m xl PVTI_abc123                    # Single item
  pmx set -p p1 PVTI_abc123 PVTI_def456             # Multiple items
  pmx set -p p0 $(pmx ls -s tasks -q)               # Batch with filter

`pmx mv` - Move Items

pmx mv [options] <id> [id2] [id3]...

Options:
  -s, --status <status>      New status (required)

Examples:
  pmx mv -s code-review PVTI_abc123                 # Single item
  pmx mv -s done PVTI_abc123 PVTI_def456            # Multiple items
  pmx mv -s done $(pmx ls -s demo -q)               # Batch move

`pmx rm` - Remove Items

pmx rm [options] <id> [id2] [id3]...

Options:
  -y, --confirm              Skip confirmation prompt

Examples:
  pmx rm PVTI_abc123                                 # With confirmation
  pmx rm -y PVTI_abc123 PVTI_def456                 # Skip confirmation
  pmx rm -y $(pmx ls -s done -q)                    # Batch remove

Workflow Statuses

PMX supports complete product development workflows:

Idea Pipeline: draft-ideas, deduped-ideas, reviewed-ideas, approved-ideas

Design Pipeline: draft-design, reviewed-design, approved-design

Implementation Pipeline: tasks, in-progress, code-review, demo, done

Environment Variables

# Required
PMX_GH_TOKEN              # GitHub personal access token with project scope

# Optional
PMX_GH_PROJECT            # Default project ID (format: PVT_xxxxx)
PMX_PROFILE               # Default profile path
PMX_LOG_LEVEL             # Logging level (debug|info|warn|error)

Security

PMX uses profile-based security to ensure agents and users can only perform authorized actions:

Command-level access - Control which commands are available
Property-level validation - Restrict argument values
State-based requirements - Ensure operations are contextually valid
Implicit defaults - Reduce configuration complexity

License

MIT License - see LICENSE file for details.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme