state-management

Pipeline state management for tracking gate progress, prerequisites, and results. Used by all gate agents to coordinate pipeline execution.

⭐5stars🔀0forks📁View on GitHub🕐Updated Dec 27, 2025

When & Why to Use This Skill

This Claude skill provides a robust pipeline state management framework designed to track gate progress, verify prerequisites, and coordinate complex execution workflows. It enables seamless orchestration of multi-stage processes—such as linting, testing, and security audits—by maintaining a centralized state machine that ensures tasks are executed in the correct sequence with full observability.

Use Cases

  • Automated CI/CD Orchestration: Managing the sequential execution of software quality gates, ensuring that downstream tasks like 'packaging' only run after 'linting' and 'testing' have passed.
  • Multi-Agent Workflow Coordination: Synchronizing multiple AI agents working on different parts of a software pipeline by providing a shared source of truth for task status and results.
  • Release Readiness Tracking: Generating real-time summaries and detailed JSON reports to monitor the health and progress of a project's release cycle.
  • Dependency-Based Task Execution: Using automated prerequisite checks to prevent redundant executions and ensure that all environmental or code-quality requirements are met before proceeding.
namestate-management
descriptionPipeline state management for tracking gate progress, prerequisites, and results. Used by all gate agents to coordinate pipeline execution.

State Management Skill

Scripts for reading and writing pipeline state, checking prerequisites, and initializing pipelines.

Scripts

init_pipeline.py

Initialize a new pipeline run.

python .claude/skills/state-management/scripts/init_pipeline.py [--target-package NAME] [--target-version VERSION]

Creates a new pipeline_state.json with fresh UUID and timestamps.

read_state.py

Get current pipeline state.

python .claude/skills/state-management/scripts/read_state.py [--gate GATE_NAME] [--format json|summary]

Options:

  • --gate: Get status of specific gate only
  • --format: Output format (default: json)

write_state.py

Update gate status after execution.

python .claude/skills/state-management/scripts/write_state.py <gate> <PASS|FAIL> [--details JSON]

Arguments:

  • gate: Gate name (e.g., lint-test, coverage)
  • status: PASS or FAIL
  • --details: JSON string with gate-specific details

check_prerequisites.py

Verify prerequisites for a gate.

python .claude/skills/state-management/scripts/check_prerequisites.py <gate>

Returns:

  • Exit code 0: Prerequisites met, gate can run
  • Exit code 1: Prerequisites NOT met, lists blocking gates

State File Location

state/pipeline_state.json

State Schema

{
  "pipeline_id": "uuid-string",
  "started_at": "2024-01-15T10:30:00Z",
  "current_gate": "coverage",
  "target_package": "my-package",
  "target_version": "1.2.0",
  "gates": {
    "lint-test": {
      "status": "PASS|FAIL|PENDING|RUNNING",
      "started_at": "ISO8601",
      "completed_at": "ISO8601",
      "duration_seconds": 45.2,
      "details": {
        "lint_errors": 0,
        "type_errors": 0,
        "tests_passed": 142,
        "tests_failed": 0
      }
    }
  }
}

Gate Prerequisites

Gate Required Prerequisites
lint-test None
coverage lint-test PASS
cross-platform lint-test, coverage PASS
python-matrix lint-test, coverage, cross-platform PASS
security lint-test, coverage, cross-platform, python-matrix PASS
api-compat lint-test, coverage, cross-platform, python-matrix, security PASS
packaging lint-test, coverage, cross-platform, python-matrix, security, api-compat PASS
github-pr ALL gates (1-7) PASS

Usage Examples

Starting a new pipeline

# Initialize
python .claude/skills/state-management/scripts/init_pipeline.py --target-package mylib --target-version 1.0.0

# Check status
python .claude/skills/state-management/scripts/read_state.py

Running a gate

# Check if gate can run
python .claude/skills/state-management/scripts/check_prerequisites.py coverage
if [ $? -eq 0 ]; then
    # Run the gate...
    python .claude/skills/state-management/scripts/write_state.py coverage PASS --details '{"total_coverage": 87.3}'
fi

Getting summary

python .claude/skills/state-management/scripts/read_state.py --format summary

Output:

Pipeline: abc123
Started: 2024-01-15 10:30:00

Gates:
  1. lint-test:      PASS (45s)
  2. coverage:       PASS (32s)
  3. cross-platform: RUNNING
  4. python-matrix:  PENDING
  5. security:       PENDING
  6. api-compat:     PENDING
  7. packaging:      PENDING
  8. github-pr:      PENDING