Agent Workflow

Portable, model-agnostic agent workflows for any codebase. Define reusable AI agent teams and multi-stage workflows, plug in any model provider, and run structured automation across your projects.

What it does

25 specialist agents — architecture, frontend, backend, security, UX, testing, model improvement, docs, and more
19 composable workflows — build features, review PRs, debug failures, improve model routing, make architecture decisions, investigate performance, and check release readiness
BYO model first — use any OpenAI-compatible model gateway, plus optional OpenAI, Bedrock, or Kiro adapters
Any MCP client — run the same workflows from terminal, VS Code, Cursor, Codex, or automation
Adaptive routing — send cheap stages to local/BYO models, promote stages from feedback, and use stronger providers where needed
Cost-optimized routing — fast models for simple tasks, reasoning models for complex ones
Durable execution — queued stages, receipts, artifacts, and exportable reports
Multi-project governance — read-only health, provider, policy-drift, queue, role, artifact lifecycle, and remediation reporting
Trusted workflow bundles — detached Ed25519 signatures, public-key trust policy, and tamper detection
Dynamic multi-handoff planning — construct policy-checked workflows from natural-language goals while preserving mandatory safety stages
Context Intelligence Gateway — route large reads through cited summaries, project-isolated caching, holdout gates, and exact-read escape hatches
Proactive workflow optimization — wake on evidence events, enforce project budgets and quiet hours, rank recommendations, simulate changes in shadow mode, and record promotion or rollback receipts
Governed assistant integration — exchange non-executable intent envelopes and bounded status summaries while separately signing and allowlisting fleet host actions
Repository-wide public/private boundary — validate that code, prompts, tests, fixtures, docs, and release metadata remain portable and scrubbed

Quick Start

Install without cloning:

npm install --global @jasonneo99/agent-workflow
agentflow-setup
agentflow doctor
agentflow ide-onboard --project /path/to/your/project --write --check

For one-off use, run npx --package @jasonneo99/agent-workflow agentflow -- list. The package exposes agentflow, agentflow-mcp, and agentflow-setup, and includes the compiled runtime, agents, workflows, and templates. Publishing remains an explicit release action.

Develop from a clone:

git clone https://github.com/jasonneo99/agent-workflow.git
cd agent-workflow
npm install
cp .env.example .env
npm run setup

The interactive setup walks you through provider selection and configuration. Once complete:

# Verify your provider is working
npm run provider-check

# Start enterprise storage for durable runs
docker compose -f infra/docker-compose.yml up -d
npm run doctor
npm run migrate-storage
npm run bootstrap-storage
npm run validate

# Initialize tailored agent workflow files in your project
npm run onboard-project -- --project /path/to/your/project --profile enterprise --write
npm run ide-onboard -- --project /path/to/your/project --write --check

# Run your first workflow (dry run)
npm run agentflow -- orchestrate --project /path/to/your/project --task "Review code quality" --dry-run

# Run it for real
npm run agentflow -- run-and-watch production-readiness --project /path/to/your/project --task "Review production readiness, UX, SEO, mobile experience, security, and launch risks"

For a no-services setup, initialize a project with --profile simple and use npm run compile to produce file-based briefs.

onboard-project is dry-run by default. Add --write to create AGENTS.md and tailored .agent-workflow/ files, including .agent-workflow/bundle-state.json for future upgrade previews; existing files are skipped unless --force is provided. Use init-project only when you want the generic template instead of stack-detected onboarding.

Providers

Provider	Models	Config
`auto`	Smart per-stage routing across configured providers	Any configured provider
`mock`	None (deterministic)	No config needed
`local`	Ollama, LM Studio, or llama.cpp-compatible localhost runtime	`LOCAL_MODEL_BASE_URL` + `LOCAL_MODEL_NAME`
`byo`	Any remote or enterprise OpenAI-compatible gateway	`BYO_MODEL_BASE_URL` + `BYO_MODEL_NAME`
`openai`	Models available to the configured OpenAI project	`OPENAI_API_KEY`
`codex-cli`	Codex CLI using ChatGPT subscription authentication	`codex login`
`anthropic`	Claude through the Anthropic Messages API	`ANTHROPIC_API_KEY`
`bedrock`	Nova Pro/Lite, Claude, Llama, Mistral	AWS credentials
`openai-compatible`	Legacy BYO-compatible alias	`OPENAI_COMPATIBLE_BASE_URL` + model name
`kiro`	Optional Kiro CLI adapter	`kiro-cli login` or `KIRO_API_KEY`

Run npm run setup for guided configuration, or configure one of the following in the untracked local .env. Never commit provider keys or CLI authentication caches. provider-use persists the primary selection and checks readiness:

# Smart routing across configured providers
npm run agentflow -- provider-use auto --check
# Configure AGENTFLOW_AUTO_PROVIDERS with the ready providers you want considered.

# Deterministic tests with no external model call
npm run agentflow -- provider-use mock --check

# Local model runtime: Ollama, LM Studio, llama.cpp-compatible endpoints
LOCAL_MODEL_BASE_URL=http://localhost:11434/v1
LOCAL_MODEL_NAME=auto
LOCAL_MODEL_API_KEY=
DEFAULT_MODEL_PROVIDER=local
# Then run: npm run provider-check

# BYO model gateway: vLLM, LiteLLM, internal routers, etc.
BYO_MODEL_BASE_URL=http://localhost:11434/v1
BYO_MODEL_NAME=auto
BYO_MODEL_API_KEY=
npm run agentflow -- provider-use byo --check

# OpenAI API (usage-based Platform billing)
OPENAI_API_KEY=...
OPENAI_MODEL=auto
npm run agentflow -- provider-use openai --check

# Codex CLI (ChatGPT subscription authentication)
npm run agentflow -- provider-use codex-cli --login --check
# Headless node: add --device-auth to the same command.

# Anthropic Claude
ANTHROPIC_API_KEY=...
ANTHROPIC_MODEL=auto
npm run agentflow -- provider-use anthropic --check

# AWS Bedrock
aws sso login # when your AWS profile uses SSO
AWS_REGION=us-east-1
BEDROCK_MODEL=auto
npm run agentflow -- provider-use bedrock --check

# Legacy OpenAI-compatible endpoint (prefer `byo` for new setups)
OPENAI_COMPATIBLE_BASE_URL=http://localhost:11434/v1
OPENAI_COMPATIBLE_MODEL=auto
OPENAI_COMPATIBLE_API_KEY=
npm run agentflow -- provider-use openai-compatible --check

# Kiro CLI
kiro-cli login
KIRO_CLI_BIN=kiro-cli
KIRO_AGENT=
npm run agentflow -- provider-use kiro --check

Shell assignments shown on separate lines belong in .env; do not paste those lines directly into a shell. After any change, npm run provider-check verifies the selected provider. A one-stage live contract test is available through npm run provider-smoke. For authentication details, headless setup, model overrides, adaptive routing, and troubleshooting for every provider, see the Provider Matrix.

Use npm run agentflow -- local-llm-checklist -p . when you also want proof that local routing is visible to Agent Workflow, has produced a low-risk route receipt, and has useful smoke-run history for the next model download or routing fix.

Model Tier Routing

Agents are assigned cost tiers (fast, standard, reasoning). With DEFAULT_MODEL_PROVIDER=auto, Agent Workflow chooses a ready provider for each tier. Local/BYO models are preferred for cheaper stages, OpenAI is preferred for reasoning when configured, and Bedrock is included when AWS credentials are valid.

Provider adapters then route to the right model. For catalog-backed providers, MODEL=auto refreshes the live model catalog exposed to your API key, AWS profile, or local endpoint and picks a model per tier, so newly available releases can be used without changing Agent Workflow source. Set per-tier model environment variables only when you want to pin exact models.

Use AGENTFLOW_MODEL_POLICY to tune the catalog selector without hard-coding model IDs: lowest-cost, balanced, best-coding (default), or maximum-reasoning.

Tier	Use case	Default routing behavior
`fast`	Triage, docs, test running	Provider adapter chooses a low-cost/low-effort path where supported
`standard`	Implementation, frontend, backend	Provider adapter uses its configured default model
`reasoning`	Architecture, security, UX review	Provider adapter chooses higher effort/capability where supported

Override per-tier models where the provider supports it, such as OPENAI_MODEL_FAST, OPENAI_MODEL_STANDARD, OPENAI_MODEL_REASONING, BYO_MODEL_FAST, BYO_MODEL_STANDARD, BYO_MODEL_REASONING, BEDROCK_MODEL_FAST, BEDROCK_MODEL_STANDARD, and BEDROCK_MODEL_REASONING.

Architecture

agents/          — Reusable agent cards (YAML)
workflows/       — Multi-stage workflow definitions (YAML)
packages/        — Runtime: providers, context gateway, dynamic workflows, optimizer, policy, storage
apps/cli/        — CLI, dashboard, and background worker entry points
apps/mcp/        — MCP server for IDE integration
infra/           — Docker Compose for enterprise storage (Postgres, Redis, MinIO)
templates/       — Project initialization templates

Commands

npm run setup                  # Interactive onboarding
npm run check                  # Contributor checks before opening a PR
npm run validate-boundary      # Reject personal, machine-specific, secret-shaped, or unscrubbed tracked content
npm run release:check -- --allow-current-version # Verify release readiness without changing files
npm run release:prepare -- --dry-run # Preview signed npm release prep
npm run provider-check         # Verify model provider
npm run validate               # Validate agent/workflow definitions
npm run agentflow -- contract-test # Contract-test definitions and mock provider output
npm run bundle-manifest        # Inspect versioned bundle checksums
npm run agentflow -- bundle-compat # Check runtime, Node.js, MCP compatibility, and migration notes
npm run agentflow -- bundle-upgrade-preview -p . # Preview project bundle migration notes without changing files
npm run agentflow -- definition-migrations -p . # Show definition changes, upgrade steps, validation, and rollback
npm run agentflow -- bundle-adopt -p . --force # Record current bundle as the reviewed project baseline
npm run doctor                 # Check local services
npm run dashboard              # Inspect runs, providers, model catalog, usage, projects, roles, artifacts, graph, and bundle readiness

# Project operations
npm run init-project -- -p .   # Install agent workflow into a project
npm run onboard-project -- -p . # Analyze stack and recommend tailored config
npm run index-project -- -p .  # Index project files for context
npm run context-report -- -p . # Inspect privacy-safe shadow routing evidence
npm run context-status -- -p . # Inspect gateway readiness, cache, calibration, and review queues
npm run context-calibrate -- -p . # Run the versioned repository holdout and regression gate
npm run context-route -- -p . --file src/example.ts --question "Where is this used?" # Preview a routed read
npm run context-holdout -- -p . --cases .agent-workflow/evals/context-holdout.json # Gate enforcement with local evidence
npm run context-host-setup -- --host claude -p . # Preview a Claude Code read hook
npm run context-host-setup -- --host cursor -p . # Preview a Cursor read hook
npm run context-host-setup -- --host codex -p . # Preview a Codex routed-context hook
npm run context-host-doctor -- -p . # Verify installed host hooks and gateway readiness
npm run context-codegen -- -p . --spec "Generate tests" --reference tests/example.test.ts --target tests/new.test.ts
npm run canary:dynamic         # Run a deterministic dynamic multi-handoff planning canary
npm run index-project -- -p . --incremental # Refresh only changed files after a baseline exists
npm run index-project -- -p . --incremental --since-commit origin/main # CI-style changed-file refresh
npm run index-project -- -p . --incremental --watch # Keep local context warm
npm run compile -- -w build-feature -p . -t "task"  # Compile a workflow brief, including approved local tuning notes
npm run agentflow -- schemas       # List JSON Schemas for agents, workflows, project config, schedules, and bundle state
npm run agentflow -- schemas -p . --write-vscode # Add YAML validation to VS Code/Cursor workspace settings
npm run agentflow -- workflow-graph -w build-feature -p . # Preview stages, approvals, agents, and context budgets
npm run agentflow -- workflow-graph -w build-feature -p . --mermaid # Renderable workflow graph
npm run agentflow -- discover-projects --roots ~/Projects --spotlight auto # Dry-run local project discovery without indexing contents
npm run agentflow -- adopt-discovered-projects --roots ~/Projects --all --index # Dry-run index/register plan for initialized candidates
npm run bundle-registry      # Inspect trusted bundle registry entries and local install status
npm run bundle-pin -- -p .   # Dry-run a project-local bundle version pin
npm run bundle-lifecycle-plan -- -p . # Dry-run reviewed upgrade command plan

# Workflow execution (requires enterprise storage)
npm run dev:agentflow       # Start dashboard, worker, learning daemon, and local storage when URLs are localhost
npm run dev:agentflow:stop  # Stop the local dashboard, worker, and learning daemon
npm run dev:agentflow:launchd:install   # macOS: start at login and restart after crashes
npm run dev:agentflow:launchd:uninstall # macOS: remove the LaunchAgent
npm run agentflow -- learning-daemon --all-projects --mode apply-approved --once # Refresh learning state for all registered projects once
npm run agentflow -- learning-action-receipts -p . --health # Inspect learning receipt health and duplicate pressure
npm run agentflow -- learning-action-receipts -p . --compact # Backup and compact duplicate daemon-owned learning receipts
npm run repository-maintenance -- -p . --check # Scan hygiene/security and reject source-size regressions
npm run worker -- --watch --worker-id local-dev # Start a named worker for queue ownership visibility
npm run worker -- --watch --project /path/to/project --concurrency 3 --limit 12 # Scope a worker lane to one project
npm run worker -- --watch --project /path/to/project # Use project worker_pool defaults from .agent-workflow/project.yaml
npm run worker -- --watch --worker-id frontend-lane --project /path/to/project --concurrency 2 # Add another visible worker lane
AGENTFLOW_PROJECT=/path/to/project AGENTFLOW_WORKER_POOL_PROFILE=split-review npm run dev:agentflow # Start the dashboard plus named project worker lanes
npm run agentflow -- recover-leases # Requeue expired worker-owned tasks
npm run agentflow -- orchestrate -p . -t "task"     # Auto-plan and run
npm run agentflow -- run-and-watch build-feature -p . -t "task" # Incrementally index, run, export, summarize
npm run agentflow -- run-and-watch build-feature -p . -t "task" --worker-concurrency 3 # Process stages concurrently within policy
npm run agentflow -- run-and-watch build-feature -p . -t "task" --full-index # Force a clean full context refresh
npm run agentflow -- run build-feature -p . -t "task"  # Run specific workflow
npm run agentflow -- run build-feature -p . -t "task" --policy-profile staging # Apply target guardrails
npm run agentflow -- agent-task security -p . -t "task"  # Run single agent
npm run worker -- --limit 6    # Process queued tasks
npm run worker:daemon          # Continuously process queued tasks locally

# Inspection
npm run status                 # List recent runs
npm run agentflow -- resume-run --run <id> # Resume unfinished stages from the last completed checkpoint
npm run agentflow -- replay-run --run <id> # Queue a fresh replay from stored run metadata
npm run agentflow -- approvals # Review pending agent-requested actions
npm run agentflow -- approvals --approve <id> --actor "Your Name" --actor-role approver # Record role-aware approval
npm run agentflow -- approvals --approve-execute <id> --actor "Your Name" --actor-role approver # Approve and run now
npm run agentflow -- approval-rules -p . # List always-approved shell/fswrite rules
npm run agentflow -- approval-rules -p . --remove <rule-id> # Remove an always-approved rule
npm run agentflow -- roles -p . # Inspect team role config and recent approval decisions by role
npm run agentflow -- artifact-lifecycle -p . # Inspect read-only artifact inventory and lifecycle hints
npm run agentflow -- artifact-lifecycle -p . --prune-plan # Preview exact artifact prune candidates without deleting anything
npm run agentflow -- server-mutation-controls # Audit server-mode mutation auth, role, idempotency, gates, and receipts
npm run agentflow -- server-approval-preview --project-id <project-id> --approval-id <approval-id> --decision approve-and-execute # Preview remote approval/action controls without mutation
npm run agentflow -- server-approval-action-plan # Inspect the receipt/idempotency plan before remote approval mutations
npm run agentflow -- server-approval-action-test-adapter # Prove approval/action replay receipts with fixture data and no live side effects
npm run agentflow -- server-approval-action --project-id <project-id> --approval-id <approval-id> --decision approve-and-execute --idempotency-key <key> # Validate locally; HTTP mutation remains gated off by default
npm run agentflow -- request-approval -p . --type deployment --target production --rationale "Ready to ship" # Queue a deployment approval
npm run agentflow -- gate -r <id> -p . # Enforce project-local quality/cost gates
npm run agentflow -- observe -r <id> --json # Export OpenTelemetry-style spans and metrics
npm run export-run -- --run <id> --scrub # Export a shareable redacted report
npm run agentflow -- quality-report -r <id>  # View cost, routing, fallback, and quality scores
npm run agentflow -- evaluate -s evaluations/synthetic-provider-comparison.yaml -p . --dry-run # Preview an eval matrix
npm run agentflow -- run-and-watch model-improvement -p . -t "Improve quality while reducing cost" # Diagnose prompt, context, eval, routing, retrieval, or fine-tune paths
npm run agentflow -- feedback -r <id> --rating accepted  # Teach future runs from outcomes
npm run agentflow -- preference-scorecard -p . # See agent/provider/tier performance
npm run agentflow -- tuning-proposals -p . # Generate reviewable tuning suggestions
npm run agentflow -- queue-tuning-approvals -p . --ids all # Dry-run approval queue
npm run agentflow -- tuning-approvals -p . --approve tune-001 # Approve a queued item
npm run agentflow -- generate-tuning-patches -p . # Dry-run reviewable patch-plan files
npm run agentflow -- model-improvement-plan -p . # Dry-run scrubbed eval/dataset plan files
npm run agentflow -- local-holdout-comparison -p . # Compare local LLM routing against a hosted baseline before promotion
npm run agentflow -- local-holdout-results -p . # Capture local-vs-hosted promotion evidence
npm run agentflow -- local-holdout-promote -p . --approved # Dry-run reviewed low-risk local routing preference
npm run agentflow -- local-llm-benchmarks -p . # Prepare tiny local-only benchmark receipts for installed candidates
npm run agentflow -- local-llm-cache-trends -p . --write # Append compact local model cache and routing trend history
npm run agentflow -- local-llm-checklist -p . # Verify local endpoint, catalog selection, routing visibility, and first low-risk local receipt
npm run agentflow -- local-llm-cost-ledger -p . --write # Append configurable local-vs-hosted savings estimates
npm run agentflow -- local-llm-setup-guide -p . # Detect local runtimes and write safe project-local setup guidance
npm run agentflow -- local-llm-download-recommendations -p . # Recommend local model downloads from hardware, task mix, and runtime catalog
npm run agentflow -- local-llm-install-plan -p . --write # Write reviewed local model download and verification commands
npm run agentflow -- local-llm-inventory -p . # Inspect local model cache size, last-used evidence, and prune candidates
npm run agentflow -- local-llm-prune-plan -p . --write # Write reviewed local model cache cleanup commands without deleting anything
npm run agentflow -- local-llm-routing-recommendations -p . --write # Recommend local routing expand, hold, or retreat decisions
npm run agentflow -- local-llm-routing-note-plan -p . --write # Write reviewed project-local routing-note plans from expand/retreat recommendations
npm run agentflow -- apply-local-llm-routing-note-plan -p . --approved --write # Append reviewed local routing notes with rollback receipts
npm run agentflow -- local-llm-smoke -p . # Run one safe fast-tier provider-smoke stage to create route receipt evidence
npm run agentflow -- agent-improvement-report -p . --write # Refresh local agent-card improvement recommendations
npm run agentflow -- agent-improvement-patches -p . --write # Generate validated agent-card YAML patch previews
npm run agentflow -- agent-improvement-evals -p . --write # Score agent-card patches against holdout run evidence
npm run agentflow -- agent-improvement-promotions -p . --write # Queue eval-passing agent-card promotions with receipts
npm run agentflow -- candidate-comparison-plan -p . # Dry-run baseline/candidate eval suites
npm run agentflow -- promotion-note-plan -p . # Dry-run reviewed routing-note plan from promotable comparisons
npm run agentflow -- apply-tuning-patches -p . # Dry-run applied local tuning notes
npm run agentflow -- apply-tuning-proposals -p . --ids all # Dry-run project-local tuning overlays
npm run artifacts -- -r <id>   # View run artifacts
npm run agentflow -- dashboard # Start local web dashboard

Open /studio on the dashboard host for the task-first Agent Workflow Studio. Studio presents editable multi-agent plans, live workflow stages, a task thread, real Git diffs, governed file and command evidence, inline approvals, checkpoint-aware controls, indexed-project switching, and server-sent updates in one workspace. Natural-language tasks compile into validated dynamic workflows; choosing a fixed workflow remains available as an explicit override.

If a workflow, worker, dashboard action, or MCP call returns Approval required, show that approval id to the user in their current context. The workflow may keep running around it, but that specific side effect stays skipped until approved, rejected, dismissed as stale, always-approved, or executed through agentflow_approvals or the dashboard. MCP clients should ask the user in chat, then call agentflow_approvals with approveAndExecute, approve, reject, dismiss, always, or execute. For local inline approvals, prefer approve-and-execute for executable side effects; use approve-only when a team wants a separate operator step.

The dashboard includes a Graph view for inspecting workflow stages, primary agents, subagents, context budgets, approval points, and policy fit before queueing work.

The dashboard includes an Evaluations view for comparing provider, model tier, prompt, quality, latency, fallback, estimated cost, and feedback results. It also includes a Model Improvement view for scorecard health, eval coverage, tuning proposal mix, routing recommendations, and promotion readiness. The Comparisons view shows written candidate comparison plans, generated private eval suites, baseline/candidate variants, quality and latency deltas, gate readiness, promotion recommendations, and promotion gate commands.

Execution policy profiles (local, staging, and production) control autonomy, commands, and write access without creating separate workflow storage. Every queued run records the resolved policy snapshot used by its worker. Narrow approval rules can auto-execute recurring low-risk actions after the normal allowlist/blocklist checks pass. See Autonomy Policy.

IDE Clients

Agent Workflow is not tied to a specific coding environment. Use the CLI directly, or expose the same workflows through MCP in VS Code, Cursor, Codex, or another MCP-capable client.

See docs/mcp-clients.md for VS Code, Cursor, and Codex config examples.

If an MCP client reports Transport closed, restart that client or Codex task to create a fresh stdio subprocess. Agent Workflow writes metadata-only MCP lifecycle breadcrumbs to .agent-workflow/runtime/mcp/stdio.log and launcher breadcrumbs to .agent-workflow/runtime/mcp/launcher.log; it avoids .env values, provider keys, database URLs, storage secrets, prompt bodies, and artifacts. Run npm run runtime-monitor -- --check-mcp to verify the launcher and MCP tool list independently of the Codex private stdio connection.

Docs

User Guide: full install and usage guide
Provider Matrix: BYO, OpenAI, Bedrock, OpenAI-compatible, and Kiro setup
MCP Client Setup: VS Code, Cursor, Codex, and generic MCP clients
Definition Migrations: upgrade and rollback guidance for reusable agent/workflow contracts
Contract Tests: verify custom agents, workflows, and provider adapters
Model Improvement Workflow: diagnose quality and cost issues without exporting private data by default
Model Improvement Walkthrough: follow the local feedback, comparison, and promotion-note loop end to end
Assistant integration: use a compatible conversational layer over governed workflows, durable evidence, learning, and approvals
Dynamic Workflows: reusable archetypes and policy-preserving on-the-fly workflow construction
Context Intelligence Gateway: cited summaries, cache isolation, holdout evidence, and enforcement modes
Workflow Optimizer: daemon wakeups, budgets, ranking, simulation, receipts, health, and shared-brain contracts
Contributing: local checks, contribution boundaries, and PR guidance
Security Policy: responsible disclosure, scope, and local automation safety boundaries
Release Guide: contributor checks, maintainer signing, and Trusted Publishing
Integration Examples: copyable model-provider and IDE/client examples
Scrubbed Examples: synthetic exports safe for docs and issue reports
Bundle Manifest: versioned reusable agent/workflow bundle checksum
Agent Roster: available agents
Architecture: runtime and storage design
Roadmap: shared-platform direction and next implementation phases
Evaluation Harness: provider, tier, and prompt comparison suites
Open Source Boundary: what belongs in the framework versus private product agent engines
Autonomy Policy: automation levels and guardrails

Enterprise Storage

For durable execution with run history, a dashboard, and artifact storage:

docker compose -f infra/docker-compose.yml up -d
npm run migrate-storage
npm run bootstrap-storage
npm run doctor

To preview a local-to-shared storage move, use read-only migration planning:

npm run storage-migrate -- --target-host ${AGENTFLOW_SHARED_STORAGE_HOST} --mode merge-preview --write-plan
npm run agentflow -- storage-merge-manifest \
  --source-database-url postgres://agentflow:agentflow@127.0.0.1:15432/agentflow \
  --target-database-url postgres://agentflow:agentflow@${AGENTFLOW_SHARED_STORAGE_HOST}:15432/agentflow \
  --write

The merge manifest maps projects by root_uri and classifies source-only, existing, conflicting, and project-id-rewrite rows before any shared-storage merge is allowed. It also flags historical runs or tasks that reference missing or changed legacy agent/workflow definitions so current shared bundle definitions are not overwritten blindly.

When the reviewed manifest and backups are ready, dry-run and then explicitly execute the insert-only merge:

npm run storage-merge-import -- --manifest .agent-workflow/migrations/storage-merge-manifest-YYYY-MM-DDTHH-MM-SS.json
npm run storage-merge-import -- --manifest .agent-workflow/migrations/storage-merge-manifest-YYYY-MM-DDTHH-MM-SS.json --execute

Afterward, inspect primary shared-storage proof and fallback posture:

npm run storage-merge-evidence
npm run offline-fallback
npm run agentflow -- storage-project-conflicts \
  --source-database-url postgres://agentflow:agentflow@127.0.0.1:15432/agentflow \
  --target-database-url "$DATABASE_URL"
npm run agentflow -- storage-project-decision \
  --root /path/to/project \
  --action preserve-target-project \
  --source-project-id <source-id> \
  --target-project-id <target-id> \
  --note "Reviewed source/target metadata; shared target is canonical."
npm run object-artifact-proof
npm run object-artifact-proof -- --enumerate-buckets
npm run object-artifact-proof -- --enumerate-buckets --verify --write

storage-merge-evidence includes a switch-over checklist for the latest saved manifest/import/backup/object evidence. It samples historical durable tables and classifies remaining conflicts by operator risk. Project row conflicts are critical because they decide the canonical project record. project_files and project_index_state conflicts are treated as refreshable index/cache evidence that can be regenerated after switch-over. Shared-primary status stays in attention while critical row conflicts, unresolved legacy definition references, stale imports, missing backups, or object bucket parity proof remain.

If shared storage is unavailable, record local fallback work before switching:

npm run offline-fallback -- --record start-local --note "shared host unavailable; start localhost fallback"
npm run offline-fallback -- --record offline-run --project /path/to/project --run-id <run-id>
npm run offline-fallback -- --record sync-back --note "Merge localhost fallback rows back to shared storage"
npm run offline-sync
npm run offline-sync -- --scheduler-check
npm run offline-sync -- --execute

For file-based output only (no Docker required), use --profile simple during project init.

Adding Your Own Agents

Create a YAML file in your project's .agent-workflow/agents/ directory:

id: my-specialist
display_name: My Specialist
category: development
purpose: Do a specific thing well.
model_tier: standard    # fast | standard | reasoning
autonomy: 3
use_when:
  - relevant keyword
can:
  - specific_capability
outputs:
  schema: structured_summary
prompt: |
  Your agent instructions here.

The reusable bundle currently includes 19 workflows. Focused definitions cover roadmap curation, CI triage, security audits, product discovery, dependency upgrades, data migrations, performance investigations, accessibility reviews, incident response, and architecture decisions alongside the core delivery and operations workflows. Run npm run list to see the current catalog.

Adding Workflows

Create a YAML file in workflows/:

id: my-workflow
name: My Custom Workflow
description: What this workflow does.
lead: workflow-orchestrator
stages:
  - id: analyze
    agent: technical-architect
    goal: Understand the problem.
    context:
      max_tokens: 4000
    output: analysis
  - id: implement
    agent: implementation-agent
    goal: Make the changes.
    context:
      max_tokens: 6000
    output: change_summary

Cost Optimization

Model tier routing — fast agents use cheap models, reasoning agents use capable ones
Incremental context indexing — reuses unchanged summaries, refreshes changed files first, and prunes deleted summaries after a baseline exists
Dashboard savings estimates — shows real-provider mix, latency, compact prompt tokens, and estimated indexed-context tokens avoided, with mock/test runs excluded by default
Dashboard control center — left-nav pages for Queue, Projects, Runs, Providers, Catalog, Settings, and home health cards
Project dashboard — inspect per-project context files, indexed summaries, memory, recent runs, and project-scoped quick actions
Editor validation — ship JSON Schemas for agents, workflows, project config, and schedules, with VS Code/Cursor YAML associations
Queue control panel — inspect queued/running/failed workflow runs, process worker batches, requeue interrupted stages, retry failed stages, or cancel active work
Approval inbox — review, approve, or reject agent-requested commands and file writes when project policy requires approval
Reusable approval rules — auto-execute narrowly scoped low-risk local actions without expanding the project policy boundary
OpenTelemetry-style observability — export run spans and metrics without prompt or artifact payload bodies
Local dev supervisor — run npm run dev:agentflow to start the dashboard, worker, learning daemon, and heartbeat monitoring; local Docker storage starts only when configured storage URLs are localhost, or when AGENTFLOW_START_LOCAL_STORAGE=1
macOS LaunchAgent — install dev:agentflow as a per-user launchd service for login startup and crash restart; Settings shows plist status, install/refresh/uninstall controls, and launchd stdout/stderr links
Background worker heartbeat — run npm run worker:daemon and see live worker status in the dashboard
Conditional skipping — orchestration skips redundant steps when prior steps found nothing
Persistent memory — stores findings so future runs skip re-discovering known-good areas
Batched workflows — production-readiness runs 4 specialist reviews in one pass with shared context

Contributing

Fork the repo
Create a feature branch
Check the Open Source Boundary before adding product-specific agent behavior
Run npm run check before submitting
Open a PR with a clear description of what changed and why

See CONTRIBUTING.md for setup, agent/workflow guidance, docs expectations, and release boundaries.

License

MIT

Name		Name	Last commit message	Last commit date
.agent-workflow		.agent-workflow
.claude		.claude
.codex		.codex
.cursor		.cursor
.github/workflows		.github/workflows
agents		agents
apps		apps
docs		docs
evals		evals
evaluations		evaluations
infra		infra
migrations		migrations
packages		packages
policies		policies
registries		registries
schemas		schemas
scripts		scripts
templates		templates
workflows		workflows
.env.example		.env.example
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
agent-workflow.bundle.json		agent-workflow.bundle.json
agent-workflow.bundle.sig.json		agent-workflow.bundle.sig.json
package-lock.json		package-lock.json
package.json		package.json
repository-maintenance-baseline.json		repository-maintenance-baseline.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Agent Workflow

What it does

Quick Start

Providers

Model Tier Routing

Architecture

Commands

IDE Clients

Docs

Enterprise Storage

Adding Your Own Agents

Adding Workflows

Cost Optimization

Contributing

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Agent Workflow

What it does

Quick Start

Providers

Model Tier Routing

Architecture

Commands

IDE Clients

Docs

Enterprise Storage

Adding Your Own Agents

Adding Workflows

Cost Optimization

Contributing

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages