Workflow Utilities

Purpose

Provides reusable Python utilities for common workflow tasks that are used across multiple skills.

Scripts

deprecate_files.py

Archive deprecated files with timestamp into ARCHIVED/ directory.

python .claude/skills/workflow-utilities/scripts/deprecate_files.py \
  <todo_file> <description> <file1> [file2 ...]

Arguments:

• todo_file: Path to TODO file (for timestamp extraction)
• description: Short description (e.g., 'old-auth-flow')
• files: One or more file paths to deprecate

Creates:

• ARCHIVED/YYYYMMDDTHHMMSSZ_<description>.zip

directory_structure.py

Create standard directory structure with required files.

python .claude/skills/workflow-utilities/scripts/directory_structure.py \
  <directory>

Arguments:

• directory: Path to directory to create/populate

Creates:

• CLAUDE.md - Context-specific guidance
• README.md - Human-readable documentation
• ARCHIVED/ subdirectory (with its own CLAUDE.md and README.md)

todo_updater.py

Update task status and workflow progress in TODO file.

python .claude/skills/workflow-utilities/scripts/todo_updater.py \
  <todo_file> <task_id> <status> [context_usage]

Arguments:

• todo_file: Path to TODO file
• task_id: Task ID (e.g., 'impl_003')
• status: New status ('pending' | 'complete' | 'blocked')
• context_usage (optional): Context usage percentage

Updates:

• Task status in YAML frontmatter
• completed_at timestamp
• workflow_progress.last_task
• workflow_progress.last_update

archive_manager.py

List and extract archived files.

# List archives
python .claude/skills/workflow-utilities/scripts/archive_manager.py list [directory]

# Extract archive
python .claude/skills/workflow-utilities/scripts/archive_manager.py extract <archive> [output_dir]

workflow_registrar.py

Register new workflow in TODO.md master manifest.

python .claude/skills/workflow-utilities/scripts/workflow_registrar.py \
  <todo_file> <workflow_type> <slug> [--title TITLE]

Arguments:

• todo_file: Path to TODO_*.md file
• workflow_type: Workflow type ('feature' | 'release' | 'hotfix')
• slug: Workflow slug
• --title (optional): Workflow title (auto-generated if not provided)

Updates:

• Adds workflow to TODO.md workflows.active[] array
• Updates TODO.md last_update timestamp

When to use:

• After creating BMAD planning (Phase 1)
• After creating feature worktree (Phase 2)
• Ensures TODO.md tracks all active workflows

workflow_archiver.py

Archive completed workflow and update TODO.md manifest.

python .claude/skills/workflow-utilities/scripts/workflow_archiver.py \
  <todo_file> [--summary SUMMARY] [--version VERSION]

Arguments:

• todo_file: Path to TODO_*.md file to archive
• --summary (optional): Summary of what was completed
• --version (optional): Semantic version (e.g., '1.5.0')

Actions:

1. Moves TODO_*.md → ARCHIVED/TODO_*.md
2. Updates TODO.md: moves workflow from active[] to archived[] array
3. Updates TODO.md statistics (total_workflows_completed)
4. Extracts metadata from workflow file (version, summary)

When to use:

• Phase 4.3: After PR merged to contrib branch
• Before creating PR contrib → develop

sync_manifest.py

Synchronize TODO.md manifest with filesystem state.

# Preview changes
python .claude/skills/workflow-utilities/scripts/sync_manifest.py --dry-run

# Sync TODO.md
python .claude/skills/workflow-utilities/scripts/sync_manifest.py

Actions:

1. Scans current directory for TODO_*.md files (active)
2. Scans ARCHIVED/ for TODO_*.md files (archived)
3. Rebuilds TODO.md workflows.active[] and workflows.archived[] arrays
4. Updates statistics

When to use:

• Recovery: TODO.md out of sync with filesystem
• Verification: Check TODO.md reflects actual files
• Migration: Rebuilding TODO.md from scratch

Warning: Replaces TODO.md arrays with filesystem state. Manual metadata edits may be lost.

VCS Abstraction Layer (vcs/)

Provides unified interface for GitHub and Azure DevOps operations via CLI adapters.

Purpose:

• Abstract VCS provider differences (GitHub vs Azure DevOps)
• Enable workflow portability across VCS platforms
• Provide consistent interface for PR operations, issue management, and PR feedback

Location: .claude/skills/workflow-utilities/scripts/vcs/

Key files:

• provider.py - Auto-detect VCS provider from git remote URL
• base_adapter.py - Base adapter interface (abstract methods)
• github_adapter.py - GitHub CLI (gh) adapter implementation
• azure_adapter.py - Azure DevOps CLI (az) adapter implementation
• config.py - VCS configuration

Provider Detection:

from .vcs.provider import detect_from_remote, VCSProvider

# Auto-detect from git remote
provider = detect_from_remote()
# Returns: VCSProvider.GITHUB or VCSProvider.AZURE_DEVOPS

# Manual detection from URL
provider = detect_from_url("https://github.com/user/repo.git")
# Returns: VCSProvider.GITHUB

Base Adapter Interface:

All adapters implement these methods:

class BaseVCSAdapter(ABC):
    @abstractmethod
    def create_pr(self, title: str, body: str, source_branch: str, target_branch: str) -> str:
        """Create pull request, returns PR URL."""
        pass

    @abstractmethod
    def fetch_pr_comments(self, pr_number: int) -> list:
        """Fetch review comments from a pull request.

        Returns:
            List of comment dictionaries with keys:
                - author: Comment author
                - body: Comment text
                - file: File path (if file comment)
                - line: Line number (if file comment)
                - created_at: Comment timestamp
        """
        pass

    @abstractmethod
    def update_pr(self, pr_number: int, title: str = None, body: str = None) -> None:
        """Update pull request title or description."""
        pass

    @abstractmethod
    def get_pr_status(self, pr_number: int) -> dict:
        """Get pull request status (approval, merge state).

        Returns:
            Dictionary with keys:
                - state: PR state (open/closed/merged)
                - mergeable: Boolean indicating if PR can be merged
                - approved: Boolean indicating if PR is approved
                - reviews_required: Number of approvals required
        """
        pass

GitHub Adapter (github_adapter.py):

Uses GitHub CLI (gh) for all operations.

from .vcs.github_adapter import GitHubAdapter

adapter = GitHubAdapter()

# Create PR
pr_url = adapter.create_pr(
    title="feat: auth system (v1.6.0)",
    body="PR body content",
    source_branch="feature/20251103T143000Z_auth",
    target_branch="contrib/stharrold"
)
# Returns: "https://github.com/user/repo/pull/94"

# Fetch PR comments
comments = adapter.fetch_pr_comments(94)
# Returns: [
#   {
#     'author': 'reviewer1',
#     'body': 'Please add error handling here',
#     'file': 'src/auth.py',
#     'line': 42,
#     'created_at': '2025-11-08T10:30:00Z'
#   },
#   ...
# ]

# Update PR
adapter.update_pr(94, title="feat: auth system (v1.7.0)")

# Get PR status
status = adapter.get_pr_status(94)
# Returns: {
#   'state': 'open',
#   'mergeable': True,
#   'approved': True,
#   'reviews_required': 1
# }

Azure DevOps Adapter (azure_adapter.py):

Uses Azure CLI (az) for all operations.

from .vcs.azure_adapter import AzureDevOpsAdapter

adapter = AzureDevOpsAdapter()

# Create PR
pr_url = adapter.create_pr(
    title="feat: auth system (v1.6.0)",
    body="PR body content",
    source_branch="feature/20251103T143000Z_auth",
    target_branch="contrib/stharrold"
)
# Returns: "https://dev.azure.com/org/project/_git/repo/pullrequest/94"

# Fetch PR comments (threads)
comments = adapter.fetch_pr_comments(94)
# Returns: [
#   {
#     'author': 'reviewer1@example.com',
#     'body': 'Please add error handling here',
#     'file': 'src/auth.py',
#     'line': 42,
#     'created_at': '2025-11-08T10:30:00Z',
#     'status': 'active'  # Azure-specific: active/pending/resolved
#   },
#   ...
# ]

# Update PR
adapter.update_pr(94, title="feat: auth system (v1.7.0)")

# Get PR status
status = adapter.get_pr_status(94)
# Returns: {
#   'state': 'active',  # Azure-specific: active/completed/abandoned
#   'mergeable': True,
#   'approved': True,
#   'reviews_required': 2
# }

PR Feedback Methods (Added v5.2.0):

Three new methods for PR feedback handling:

1. fetch_pr_comments(pr_number)

   • GitHub: Uses gh pr view --json reviews,comments
   • Azure: Uses az repos pr show --query threads
   • Returns unified comment format (author, body, file, line, timestamp)
   • Used by generate_work_items_from_pr.py to extract unresolved conversations

2. update_pr(pr_number, title, body)

   • GitHub: Uses gh pr edit
   • Azure: Uses az repos pr update
   • Updates PR title or description
   • Used for updating PR with work-item links

3. get_pr_status(pr_number)

   • GitHub: Uses gh pr view --json state,mergeable,reviews
   • Azure: Uses az repos pr show --query status,mergeStatus
   • Returns approval and merge status
   • Used for validation before creating work-items

Integration Example (from git-workflow-manager):

from pathlib import Path
import sys

# Add vcs module to path
vcs_path = Path('.claude/skills/workflow-utilities/scripts')
sys.path.insert(0, str(vcs_path))

from vcs.provider import detect_from_remote, VCSProvider
from vcs.github_adapter import GitHubAdapter
from vcs.azure_adapter import AzureDevOpsAdapter

# Auto-detect provider
provider = detect_from_remote()

# Initialize adapter
if provider == VCSProvider.GITHUB:
    adapter = GitHubAdapter()
elif provider == VCSProvider.AZURE_DEVOPS:
    adapter = AzureDevOpsAdapter()
else:
    raise ValueError(f"Unsupported VCS provider: {provider}")

# Fetch unresolved PR comments
comments = adapter.fetch_pr_comments(94)
unresolved = [c for c in comments if not c.get('resolved', False)]

# For each unresolved comment, create work-item
for i, comment in enumerate(unresolved, start=1):
    # ... create GitHub issue or Azure DevOps task
    pass

When to use VCS abstraction:

• Creating PRs (Phase 4: Integration)
• Fetching PR feedback (Phase 4: PR Feedback)
• Updating PR status
• Any VCS-specific operation that needs to work across GitHub and Azure DevOps

Key features:

• Provider auto-detection from git remote
• Unified interface (same method signatures)
• CLI-based (no API tokens required in most cases)
• Error handling with helpful messages
• Portable across GitHub and Azure DevOps

Usage Examples

Deprecating Old Files

import subprocess

# Deprecate old implementation files
subprocess.run([
    'python',
    '.claude/skills/workflow-utilities/scripts/deprecate_files.py',
    'TODO_feature_20251022T143022Z_json-validator.md',
    'old-validator',
    'src/old_validator.py',
    'tests/test_old_validator.py'
], check=True)

Creating Standard Directories

import subprocess

# Create planning directory with standard structure
subprocess.run([
    'python',
    '.claude/skills/workflow-utilities/scripts/directory_structure.py',
    'planning/json-validator'
], check=True)

Updating TODO Tasks

import subprocess

# Mark task as complete
subprocess.run([
    'python',
    '.claude/skills/workflow-utilities/scripts/todo_updater.py',
    'TODO_feature_20251022T143022Z_json-validator.md',
    'impl_003',
    'complete',
    '35'  # context usage percentage
], check=True)

Managing Workflow Lifecycle

import subprocess

# Register new workflow in TODO.md (Phase 1/2)
subprocess.run([
    'python',
    '.claude/skills/workflow-utilities/scripts/workflow_registrar.py',
    'TODO_feature_20251103T143000Z_auth.md',
    'feature',
    'auth',
    '--title', 'User Authentication System'
], check=True)

# Archive completed workflow (Phase 4.3)
subprocess.run([
    'python',
    '.claude/skills/workflow-utilities/scripts/workflow_archiver.py',
    'TODO_feature_20251103T143000Z_auth.md',
    '--summary', 'Implemented OAuth2 authentication with Google and GitHub',
    '--version', '1.5.0'
], check=True)

# Sync TODO.md with filesystem (recovery)
subprocess.run([
    'python',
    '.claude/skills/workflow-utilities/scripts/sync_manifest.py'
], check=True)

Directory Standards

All directories created by these utilities follow the standard structure:

directory/
├── CLAUDE.md      # Context for Claude Code
├── README.md      # Human-readable documentation
└── ARCHIVED/      # Deprecated files (except if directory IS archived)
    ├── CLAUDE.md
    └── README.md

Integration with Other Skills

All skills can use these helper functions:

# Example from bmad-planner
from pathlib import Path
import subprocess

def create_planning_with_structure(feature_name):
    """Create planning directory with standard structure."""

    planning_dir = Path('planning') / feature_name

    # Create directory structure
    subprocess.run([
        'python',
        '.claude/skills/workflow-utilities/scripts/directory_structure.py',
        str(planning_dir)
    ], check=True)

    # Now create planning documents
    # ...

Best Practices

• Always use these utilities for consistency
• Don't manually create directory structures
• Use deprecation for old files, not deletion
• Update TODO file after each meaningful step
• Check archives before deleting files permanently