Auto-Workflow

Config-driven Jira-to-PR pipeline powered by Claude Code. Polls Jira for "In Progress" tickets, gathers context (issue details, images, videos, Figma specs), implements the feature using headless Claude, runs tests, commits, pushes, creates PR, and moves Jira to Code Review. All automated on a VPS.

How It Works

Jira (In Progress)  →  VPS (Claude Code)  →  PR + Code Review
     ↑                      ↓
  You plan &             Implements,
  assign tickets         tests, pushes

Quick Start

Two deployment modes. Pick based on whether you want the workflow on a remote VPS or on your own Mac.

git clone https://github.com/tomdwipo/auto-workflow.git
cd auto-workflow
cp setup-template.yaml my-setup.yaml
nano my-setup.yaml    # Add Jira + Git credentials (+ VPS if remote)

Remote VPS (always-on, credentials on the server):

./install.sh my-setup.yaml

The installer SSHs into your VPS, installs deps, and wires up a cron scheduler.

Local Mac (credentials stay on your device, runs while Mac is awake):

./install.sh my-setup.yaml --local

The installer sets up everything locally with a launchd agent — no SSH, no remote server.

Which mode?

	Local Mac	Remote VPS
Credentials stored	On your Mac only	On the VPS
Runs when Mac sleeps	No	Yes
Scheduler	launchd (~/Library/LaunchAgents)	cron
Needs SSH / remote server	No	Yes
Best for	Solo dev, security-conscious	24/7 automation

Supported Project Types

Type	Test Command	Extra Setup
Android	./gradlew testDebugUnitTest	Java 17 + Android SDK (auto-installed)
Node.js	npm test	None
Python	pytest	None
Go	go test ./...	None
React	npm test -- --watchAll=false	None
iOS	xcodebuild test	Xcode on VPS (manual)

See docs/examples/ for ready-to-use config snippets.

What install.sh Does

Both modes follow the same 10 steps; the only differences are where files go and which scheduler is used.

1. Reads your YAML config + env var overrides
2. Installs dependencies (git, node, yq, ffmpeg, Claude Code, etc.)
3. Installs MCP servers (Jira, Bitbucket/GitHub, Figma, video-to-image)
4. Clones your project repo (skipped if project.local_dir already exists in --local mode)
5. Generates workflow-config.yaml → deploys
6. Generates .mcp.json with your API tokens → deploys (chmod 600 in local mode)
7. Deploys workflow scripts + safety hooks
8. Sets up scheduler — cron (VPS) or launchd (local, ~/Library/LaunchAgents/com.tomdwipo.auto-workflow.plist)
9. Runs verification (23 checks local / 22 checks VPS)
10. Prints next-step instructions

iOS App (Optional)

Native SwiftUI app at app/VPSController/ — control the pipeline from your iPhone.

• Dashboard: status, enable/disable, trigger, ticket list
• Terminal: execute commands, run Claude prompts
• Plan Feature: interactive planning → breakdown → Jira task creation
• TRD Builder: build Technical Requirements Documents via chat

Open app/VPSController/VPSController.xcodeproj in Xcode, enter your VPS host in Settings — it auto-detects project config from VPS.

Human Review Gates

  HUMAN              MACHINE            HUMAN
  ─────              ───────            ─────
  Plan &         →   Implement    →     Code Review
  Assign             Test & Push        Merge (human only)
  Tickets            Create PR          QA & Release

The machine never merges PRs. You control what gets planned, what gets started, and what ships.

Architecture

See docs/ARCHITECTURE.md for the full pipeline, MCP servers, per-ticket state, retry logic, and safety hooks.

Requirements

Component	Version
VPS	Ubuntu 22+ / Debian 12+ (or any Linux with apt/dnf)
Mac	For running install.sh + iOS app
SSH	Key-based auth (recommended) or password
Claude Code	Pro/Team plan (auto-installed)
Jira	Cloud with API token
Git	Bitbucket or GitHub with app password/PAT

Environment Variable Overrides

Secrets can be passed via env vars instead of putting them in the YAML:

JIRA_API_TOKEN=xxx GIT_APP_PASSWORD=yyy ./install.sh my-setup.yaml

Variable	Overrides
JIRA_API_TOKEN	jira.api_token
GIT_APP_PASSWORD	git.app_password
FIGMA_TOKEN	figma.access_token
VPS_PASSWORD	SSH password (use key auth instead)

Control Commands

After setup, the same ~/w helper controls both modes.

Local Mac:

bash ~/w on           # Enable
bash ~/w off          # Disable
bash ~/w s            # JSON status
bash ~/w tickets      # Human-readable status
bash ~/w run          # Trigger now
bash ~/w log 30       # Last 30 log lines
bash ~/w rerun XX-1   # Retry a ticket

Pause / resume the scheduler:

launchctl unload  ~/Library/LaunchAgents/com.tomdwipo.auto-workflow.plist   # pause
launchctl load    ~/Library/LaunchAgents/com.tomdwipo.auto-workflow.plist   # resume
launchctl list | grep com.tomdwipo.auto-workflow

Remote VPS:

ssh your-vps "bash ~/w on"          # Enable
ssh your-vps "bash ~/w off"         # Disable
ssh your-vps "bash ~/w s"           # JSON status
ssh your-vps "bash ~/w tickets"     # Human-readable status
ssh your-vps "bash ~/w run"         # Trigger now
ssh your-vps "bash ~/w log 30"      # Last 30 log lines
ssh your-vps "bash ~/w rerun XX-1"  # Retry a ticket

Navigation

Document	Description
docs/ARCHITECTURE.md	Pipeline design, MCP servers, per-ticket state, safety hooks
docs/SETUP_GUIDE.md	Credential setup, install steps, troubleshooting
workflow/README.md	Script details, standalone deployment without install.sh
docs/examples/	Config snippets: Android, Node.js, Python, Go, React
CLAUDE.md	Developer guidance for Claude Code

License

MIT