@hyperscale-it/agent-workflow

Workflow runtime, dashboard, and preview registry CLIs for agent-facing workflow operation.

This package is the npm-side home of workflow mechanism code. Business workflow definitions, business node skills, and host application preview launchers stay outside this package.

Commands

Expected usage from agent skills or plugin commands:

PROJECT_ROOT="$PWD" pnpm --package=@hyperscale-it/agent-workflow dlx workflow-task <command> [options]
PROJECT_ROOT="$PWD" pnpm --package=@hyperscale-it/agent-workflow dlx generate-branch-name [options]
PROJECT_ROOT="$PWD" pnpm --package=@hyperscale-it/agent-workflow dlx workflow-dashboard activate [options]
PROJECT_ROOT="$PWD" pnpm --package=@hyperscale-it/agent-workflow dlx workflow-dashboard recover --project-root <repo-root> [options]
PROJECT_ROOT="$PWD" pnpm --package=@hyperscale-it/agent-workflow dlx workflow-preview <command> [options]

Dependency version pinning

All dependencies in package.json are exact versions (no ^ / ~ ranges).

Plugin skills and hooks invoke this package through pnpm dlx on every task-create / activate / resume / dashboard recovery. If dependencies were declared as ranges, each dlx run could resolve a newer matching version after an upstream publish, which:

• changes the install content hash and misses the local pnpm store / dlx cache;
• makes skill execution slower and less predictable across machines and sessions;
• can introduce non-deterministic runtime behavior without a package version bump.

Pinning freezes the dependency graph for a given package release so repeated pnpm --package=@hyperscale-it/agent-workflow dlx … hits the same cached install until this package intentionally bumps those pins (and ships a new version).

When upgrading dependencies, bump the exact versions deliberately, run the package smoke checks, then publish a new @hyperscale-it/agent-workflow release—do not reintroduce open ranges for skill-facing installs.

Branch Name Resolution

generate-branch-name requires PROJECT_ROOT and returns the first available task branch for the generated <feat|fix|chore>/<task-name>.<env> name by checking local branch refs and querying the live origin with git ls-remote. When the preferred branch is occupied, it tries -2, -3, and so on through -50.

JSON output includes the final branch, preferred_branch, branch_adjusted, and branch_adjustment_reason.

Package Boundary

Included:

• Workflow DSL task runtime.
• Task creation, validation, status inspection, ready/next inspection, and state marking.
• Task activation preflight under workflow-task activate-preflight.
• Local dashboard server startup and recovery (workflow-dashboard activate / recover).
• Preview registry management for <task-directory>/.workflow-dashboard/previews.yaml.
• Task branch-name generation with local and live origin collision resolution.

Excluded:

• Concrete business workflow YAML definitions.
• Concrete workflow node skills.
• Host application preview launchers.
• Business dev server, mock, route, or verification logic.

Preview Registry

Dashboard reads preview entries from:

<task-directory>/.workflow-dashboard/previews.yaml

The registry is managed by workflow-preview:

workflow-preview add --task-dir <task-dir> --id app --title Preview --url http://127.0.0.1:3000
workflow-preview list --task-dir <task-dir>
workflow-preview remove --task-dir <task-dir> --id app

Dashboard

workflow-dashboard activate starts or restarts a local pm2-managed dashboard process for a task and prints a local URL such as http://127.0.0.1:5090.

workflow-dashboard recover reuses or restarts that process for the active task recorded in tasks/index.yaml#active_task.