VIA

Vision Into Action

A verifiable agentic delivery framework.

VIA turns product vision into action through explicit, reviewable, and reproducible workflows.

At the execution layer, VIA turns editable TOML flows into deterministic, resumable Codex workflows. Flows compose agent actions, nested flows, and argv-based process nodes. The CLI owns compilation, attempts, output validation, persisted state, and publication; the coordinator owns Codex threads and user communication.

Why VIA?

VIA stands for Vision Into Action:

• Vision — the initial idea, goal, or desired change.
• Into — the path through requirements, design, specification, and planning.
• Action — implementation, review, QA, verification, and integration.

The word via also means the path or means by which a result is achieved.

Requirements

• Python 3.14+
• uv
• Codex CLI for package discovery and agent activation

Install for development

uv sync
uv run via --help

Flow-first quick start

Create flow.toml and any referenced actions, then validate it:

uv run via flow validate ./flow.toml

Create a run directly from the flow:

uv run via run create \
  --flow ./flow.toml \
  --input brief=file:brief.md \
  --publish-root changes/example

via run create --flow compiles internally. The immutable graph.toml is stored inside the run directory; callers do not manage an intermediate graph. via flow compile and via run create --graph remain advanced/debugging interfaces.

The coordinator then uses operation IDs:

uv run via run pull <run-id> --limit 4 --json
uv run via run bind <run-id> <operation-id> --thread-id <thread-id>
uv run via run check <run-id> <operation-id>
uv run via run finish <run-id> <operation-id>
uv run via run execute <run-id> <operation-id>
uv run via run approve <run-id> <source-node-id>

pull atomically reserves ready work and allocates UUIDv7 operation IDs and node-attempt numbers. Coordinators never guess either value. Action agents validate their own result.toml with check; finish is the authoritative gate. Process nodes use execute.

Skills

The bundled via-software package turns product vision into reviewed software changes through requirements, design, implementation, architecture review, and code review. It also provides optional knowledge integration and review actions; project flows own their placement and any additional QA or acceptance stages.

• $via-plan, $via-prd, and $via-design are independent methodology skills with interview, write, and review modes. They do not automatically start VIA or require a reviewer.
• $via-knowledge integrates accepted human decisions into canonical product, domain, architecture, and decision docs, or independently reviews that update.
• $via-run maps a natural-language request and files to a flow run, then coordinates claimed operations.
• $via-package authors reusable flows, actions, skills, and agents.

Install bundled packages into a project:

uv run via package install via-core
uv run via package install via-software

Quality gate

uv run pytest -q
uv run ruff check src tests
uv run mypy src

See documentation, especially the flow reference, run reference, and planning and running guide.