bacchus-labs/running-workflows

Running Workflows

Purpose

Standardized way to launch the workflow engine CLI, background it, and monitor progress. Keeps the main conversation available while workflows run.

When to Use

• User asks to "run a workflow", "implement a spec", or "execute spec-implementation"
• You need to invoke the workflow engine CLI (wrangler-workflow)
• Monitoring a running or paused workflow

When NOT to Use

• Implementing a single issue (use implementing-issue)
• Writing plans without execution (use writing-plans)

1. Launching a Workflow

Resolve the CLI

The engine CLI lives relative to the wrangler plugin root:

# From the project root (dev checkout):
node workflows/engine/dist/cli.js

# Or via the bin wrapper:
bin/wrangler-workflow

If the engine is not built, build it first:

cd workflows/engine && npm run build

Run Command

node workflows/engine/dist/cli.js run <spec-file> [options]

Options:

• --dry-run -- Analyze and plan only, do not execute or publish
• --resume <session-id> -- Resume a paused workflow from its last checkpoint

Examples:

# Full run
node workflows/engine/dist/cli.js run .wrangler/specifications/SPEC-000049-feature.md

# Dry run (plan only)
node workflows/engine/dist/cli.js run .wrangler/specifications/SPEC-000049-feature.md --dry-run

# Resume paused workflow
node workflows/engine/dist/cli.js run .wrangler/specifications/SPEC-000049-feature.md --resume wf-2026-02-16-ba6fcb97

MUST Background by Default

Always launch workflows in the background using the Bash tool's run_in_background parameter. Workflows take 5-30 minutes. Do NOT block the conversation.

Bash(command: "node workflows/engine/dist/cli.js run <spec-file>", run_in_background: true, timeout: 600000)

After launching, immediately tell the user:

• The workflow is running in the background
• The session ID (from initial output or context.json)
• How to check status: "Ask me anytime for a progress update"

2. Checking Progress

MCP Tool (Preferred)

Use the session_status MCP tool for a structured status report:

session_status({ sessionId: "wf-2026-02-16-ba6fcb97" })

If you omit sessionId, it auto-detects the most recent wf-* session:

session_status({})

The tool returns structured metadata including:

• status: running/paused/completed/failed
• activeStep: Current step derived from audit log (reliable, not stale context.json)
• phasesCompleted: Phases finished (derived from audit log)
• tasksCompleted / tasksPending / totalTasks: Task progress
• duration: Human-readable elapsed time
• specFile, worktreePath, branchName: Session context
• blocker: Details if the workflow is paused
• checkpoint: Resume state if available
• lastActivity: What happened most recently
• auditEntryCount: Total audit entries

Bash Helper Script (Alternative)

For terminal use outside of Claude Code, a helper script is available:

bin/check-workflow-status <session-id>
bin/check-workflow-status              # auto-detects most recent wf-* session

This outputs a formatted summary including process PID and CPU/memory usage.

Manual Status Check

If neither tool is available, check session files directly:

Session directory: .wrangler/sessions/<session-id>/

audit.jsonl -- Activity Log (Source of Truth)

The audit log is the most reliable source of current workflow state. Each line is a JSON object recording a step transition:

{"step":"analyze","status":"started","timestamp":"2026-02-16T21:58:15.127Z"}
{"step":"analyze","status":"completed","timestamp":"2026-02-16T21:59:28.160Z","metadata":{...}}
{"step":"implement","status":"started","timestamp":"2026-02-16T22:03:48.990Z"}

Steps you will see: init, analyze, plan, execute, implement (per-task), review (per-task), fix-issues (if review found problems), verify, publish.

context.json -- Overall State

Contains status, tasksCompleted, tasksPending, specFile, worktreePath, branchName. Note: currentPhase and phasesCompleted may be stale -- derive these from audit.jsonl instead.

checkpoint.json / blocker.json

Present when the workflow paused. Checkpoint contains resume state; blocker contains the reason for pausing.

Interpreting Progress

| Status | Meaning | Action | |---------------------|---------|--------| | running | Workflow is actively executing | Wait, check audit log for current step | | paused | Hit a blocker or loop exhaustion | Read blocker, consider --resume | | completed | All phases finished successfully | Check worktree for PR | | failed | Unrecoverable error | Read audit log for error details |

Reporting to User

When the user asks for a progress update, call session_status({}) and report:

1. Status: running/paused/completed/failed
2. Active step: What's happening right now
3. Progress: X of Y tasks completed (if in execute phase)
4. Last activity: Most recent audit entry
5. Duration: How long it has been running

Example report:

Workflow wf-2026-02-16-ba6fcb97 is running.

Phase: execute (analyze -> plan -> [execute] -> verify -> publish)
Progress: 3/8 tasks completed
Last activity: Implementing task-004 (started 2m ago)
Running for: 12 minutes

The workflow is working in an isolated worktree at .worktrees/feature-name/.

3. Handling Completion

When the workflow finishes (check via TaskOutput or periodic polling):

If completed:

• Report success to user
• Show the branch name and worktree path
• Note if a PR was created
• Suggest reviewing the changes

If paused:

• Read blocker.json for the reason
• Report to user with context
• Offer to resume: --resume <session-id>

If failed:

• Read the last audit entries for error context
• Report the failure to user
• Suggest debugging steps

4. Resuming Paused Workflows

node workflows/engine/dist/cli.js run <spec-file> --resume <session-id>

The engine picks up from the last checkpoint, skipping completed phases and tasks.

Workflow Phases Reference

The spec-implementation workflow runs these phases in order:

1. analyze -- Reads the spec, produces structured task breakdown
2. plan -- Creates MCP issues from the analysis
3. execute -- Implements each task (per-task loop with implement -> review -> fix cycle)
4. verify -- Runs full test suite, checks all requirements met
5. publish -- Creates GitHub PR from the completed work

Each phase produces audit entries and updates context.json.