devflow-engine 1.0.0

DevFlow v2 CLI-first engine (projects, stories, execution store, review packets)

DevFlow Engine

CLI-first Python engine for DevFlow. The PyPI distribution is devflow-engine; it installs the devflow command.

Goals

• Project lifecycle: draft shell -> bind workspace/repo -> init/register/list/remove
• Story lifecycle: index/validate/register/execute
• Planning support: repo analysis -> source docs -> scopes -> approved scope -> idea(s) -> DevFlow stories
• Implementation workflow: "green" gate = tests + typecheck + lint
• Review workflow: story-driven compliance/soundness/security review packets persisted in SQLite
• Error workflow: error queue + remediation runs
• Execution store: .devflow/execution.sqlite

Documentation

• docs/story-implementation-planning-node.md — per-story planning/gating node before TestDesign/Red, with dependency findings, queue decisions, and registry expectations consumed by downstream implementation nodes.
• docs/llm-input-primitives-v0.02.md — v0.02 LLM-facing input primitive contract for idea and story.

Install

Install the CLI from PyPI:

pipx install devflow-engine
# or
python -m pip install devflow-engine

Run the CLI:

devflow --help

Development

This repo is intended to be developed with uv.

cd devflow_engine
uv venv
uv pip install -e '.[dev]'

Print the v0.02 LLM input guidance:

devflow llm guide
devflow llm guide --primitive idea --json

Happy path

1. project shell created in control plane
2. workspace/repo bound to project
3. registration DAG runs via devflow project add
4. project reaches ready_for_source_scope
5. source docs -> scopes
6. approved scope -> idea(s)
7. idea -> DevFlow stories
8. story -> implementation
9. implementation -> review

Quickstart

Register an existing repo with DevFlow:

devflow project add --path /absolute/path/to/repo --name my-repo --json

Submit an idea or a ready story:

devflow idea submit --project /absolute/path/to/repo --from idea.json --json
# or
devflow story submit --project /absolute/path/to/repo --from story.json --json

Run delivery and inspect health:

devflow run start --project /absolute/path/to/repo --json
devflow run health --project /absolute/path/to/repo --json

Triage and repair failures:

devflow doctor --project /absolute/path/to/repo --json
devflow recovery run --project /absolute/path/to/repo --json
devflow error solve --project /absolute/path/to/repo --json

When you have a deterministic project-code repro, pass it to error solving:

devflow error solve \
  --project /absolute/path/to/repo \
  --repro-command 'uv run pytest' \
  --json

Inspect per-node outputs from a stored run:

# dump a specific run by run_id
python scripts/dump_run_node_outputs.py \
  --run-id <run_uuid>

# or dump the latest run for any DAG by dag_id
python scripts/dump_run_node_outputs.py \
  --dag-id implementation_dag

# second-most-recent run for that DAG
python scripts/dump_run_node_outputs.py \
  --dag-id implementation_dag \
  --latest-index 2

Dumps are written under .devflow/node_output_dumps/<dag>/<label>/<timestamp>/ by default. The navigation path intentionally stays human-readable and omits run IDs / object IDs where possible:

• <dag> comes from runs.dag_id unless it looks like an ID, in which case the folder falls back to dag
• <label> is derived from readable config fields such as label, name, title, idea_title, scope_title, or story_title
• the exact run_id still lands in manifest.json inside the dump directory

Use --output-root /tmp/devflow-dumps to write somewhere else.

Run the source -> scope scaffold end-to-end:

devflow source-scope run \
  --project-id proj_demo \
  --intake-id source_demo \
  --text "Customers approve quotes online. Approved quotes create jobs. Completed jobs create invoices and customers can pay online."

Gate a pre-shaped normalized packet + scope outline deterministically:

devflow source-scope gate \
  --project-id proj_demo \
  --source-packet .devflow/path/to/normalized_source_packet.json \
  --scope-outline .devflow/path/to/scope_outline.json

Story contracts

Story contracts are YAML documents containing:

• id, title
• planes: required plane write-ups (product, ux, technical, security, compliance, operations)
• plane_oracles: list of {plane, anchor} entries used as verification anchors

The contract validator enforces presence of required planes + non-empty plane_oracles.

Execution store

All runs/events/errors/review packets are stored in:

• .devflow/execution.sqlite

This database is created automatically on first CLI usage.

Workers / Background services

Supabase execution-event listener (devflow worker supabase-events)

This is the DFE-side listener/dispatcher for the devflow_execution_events Supabase table. It is the single long-running process that bridges the control-plane (Supabase) to the local DevFlow engine — picking up queued events and dispatching the appropriate DFE workflow for each.

Normal operation (continuous loop with Realtime):

devflow worker supabase-events

Starts an indefinite polling loop. While running it also opens a Supabase Realtime WebSocket subscription on devflow_execution_events. New INSERT events on that table wake the dispatch loop immediately rather than waiting for the next poll interval (default: 3 s). If the WebSocket connection drops it reconnects automatically in the background; polling continues as the fallback during any gap.

Process a single queued event and exit:

devflow worker supabase-events --once

Useful for manual trigger / smoke testing.

Disable Realtime (polling only):

devflow worker supabase-events --no-realtime

Runs the same polling loop but skips the WebSocket listener entirely. Use this when the websockets Python package is unavailable, or when you need to debug without a live connection.

Additional options:

Flag	Default	Description
--sleep-seconds N	3.0	Idle sleep between polls (also caps realtime wake latency)
--max-iterations N	unlimited	Stop after N loop iterations
--json	off	Emit JSON summary on exit

When queued events are not being picked up — checklist:

1. Verify the worker is running: there should be a live devflow worker supabase-events process.
2. Check Supabase credentials: SUPABASE_URL and SUPABASE_SERVICE_KEY (or equivalent config) must be set and valid.
3. Confirm the event row in devflow_execution_events has status = queued and run_id IS NULL — events with any other status are skipped.
4. Check that the event's event_type is in the supported set (see docs/queue-worker-infra.md → Supported event types).
5. Run with --once to get an immediate result and check stderr/stdout for errors.
6. If Realtime is misbehaving (false wake-ups or missed wakes), try --no-realtime to isolate the issue to the polling path.

See docs/queue-worker-infra.md for full architecture details.

Design notes

• docs/scope-idea-agentification.md — current scope->idea agentic runtime notes
• docs/ui-grounding-curtis-medium-tier-doctrine.md — follow-on UI grounding / wireframe planning doctrine from the Curtis pass, including the proposed ui_screen_inventory.json contract and the default medium-tier minimum for customer-facing wireframes