Flow

Flow is a minimal Droid plugin for lightweight feature-based delivery sessions.

It keeps canonical state in .flow/sessions/<id>/session.json, renders session docs under .flow/sessions/<id>/docs/ for humans, and routes planning, execution, status, and reset through one Python runtime.

At a Glance

• Commands: /flow-plan, /flow-run, /flow-status, /flow-reset
• Canonical state: .flow/sessions/<id>/session.json
• Rendered docs: .flow/sessions/<id>/docs/index.md, .flow/sessions/<id>/docs/features/*.md, .flow/sessions/<id>/docs/decisions/*.md, and .flow/sessions/<id>/reviews/*.md
• Runtime entrypoint: scripts/flow_runtime.py
• Commands, droids, and hooks do not write .flow/ state directly

Install

From GitHub

droid plugin marketplace add https://github.com/ddv1982/flow-droid
droid plugin install flow@flow-droid

From a local checkout

droid plugin marketplace add /path/to/flow-droid
droid plugin install flow@flow-droid

Update

droid plugin update flow@flow-droid

Workflow

/flow-plan <goal>
/flow-plan   # review the draft features and approve the plan
/flow-run
/flow-status

• /flow-plan creates or reshapes the active session.
• /flow-plan can run bounded Exa/Ref-backed research when the user chooses Research and plan, then records a defensible implementation approach before approval.
• When /flow-plan is showing a draft review, the immediate follow-up is choosing one of the runtime-provided review actions. Typed replies like approve and approve <ids> remain fallback aliases.
• apply-plan is the transactional commit point for a replacement plan.
• /flow-run executes one active feature at a time, requires strict structured worker results, and does not complete a feature unless validation and required review gates pass.
• /flow-status reflects runtime-provided action guidance like recommendedAction and availableActions, not hand-reconstructed next steps.
• /flow-reset reopens one feature or archives the active session.
• The normal path is plan -> review -> approve -> run; feature trimming and research skipping are optional advanced choices.

Commands

Command	Purpose
/flow-plan	Create or refresh the active draft session
/flow-run	Run or continue the active feature
/flow-status	Show the active session or list sessions
/flow-reset	Reopen a feature or archive the active session

Runtime Model

The stable runtime entrypoint is scripts/flow_runtime.py.

The startup hook calls the installed plugin runtime directly.

The runtime is responsible for:

• creating or reusing sessions
• validating session payloads
• persisting session.json atomically
• rendering session docs
• selecting the next runnable feature
• applying planner and worker result payloads
• resetting or archiving sessions
• rendering startup and status summaries

Runtime CLI subcommands:

• plan-start
• plan-request
• apply-plan
• select-features
• approve-plan
• start-run
• complete-feature
• block-run
• block
• reset
• status
• status-summary
• workspace-fingerprint
• validate

Session Layout

.flow/
├── active
├── .gitignore
├── archive/
└── sessions/
    └── <session-id>/
        ├── session.json
        ├── docs/
        │   ├── index.md
        │   └── features/
        │       └── <feature-id>.md
        │   └── decisions/
        │       └── adr-001-<slug>.md
        └── reviews/
            └── <feature-id>-review.md

session.json stores:

• version
• id
• goal
• status
• approval
• planning
• plan
• execution
• notes
• artifacts
• timestamps

plan stores:

• summary
• overview
• requirements
• architectureDecisions as an ordered array of decision text strings
• features

Each feature stores:

• id
• title
• summary
• status
• fileTargets
• verification
• optional dependsOn containing feature ids from the same plan
• optional blockedBy containing feature ids from the same plan; not free-text blocker notes
• optional relatedDecisionIds using canonical ids like adr-001; planner payloads may instead provide relatedDecisions text and let the runtime resolve canonical ids
• optional result

Feature results store:

• summary
• artifactsChanged
• validationRun
• decisions
• notes
• verificationStatus
• followUps
• featureReviewSummary
• optional finalReviewSummary
• completedAt

Execution state also keeps a canonical currentFocus record so session overviews and status output can explain the next recommended feature and why it should be tackled next.

execution stores:

• activeFeatureId
• blockedReason
• blockedAt
• lastExecutionSummary

planning stores:

• intent
• lastPlanSummary

Droids

Flow uses two droids:

• flow-planner: returns a compact feature plan payload
• flow-worker: completes one active feature and returns a worker result payload

The runtime owns state transitions and validates returned payloads.

Planner payloads use a lighter validation contract:

• validationRun: array of strings only
• planner runs are read-only, so validationRun should usually be []

Worker result payloads are intentionally strict:

• artifactsChanged: array of { "path", optional "kind" }
• validationRun: array of { "command", "status", "summary" } where status is one of passed, failed, failed_existing, or partial
• decisions: array of { "summary" }
• featureResult.featureId: required and must match the active feature id
• featureReview: required for every feature
• finalReview: required only for the final remaining feature

Flow does not complete a feature unless validation passes and the required review payloads report passed.

Hooks

The session-start hook resolves the installed plugin runtime and calls status-summary so startup messaging stays aligned with /flow-status.

If startup status fails, the hook surfaces a concise error to stderr.

Development

Important files:

• pyproject.toml
• flow_runtime_lib/
• scripts/flow_runtime.py
• scripts/run_flow_runtime.sh
• scripts/flow_plan_fallback.py
• flow_runtime_lib/cli.py
• flow_runtime_lib/store.py
• flow_runtime_lib/schema/
• flow_runtime_lib/render.py
• flow_runtime_lib/engine/
• commands/flow-plan.md
• commands/flow-run.md
• commands/flow-status.md
• commands/flow-reset.md
• droids/flow-planner.md
• droids/flow-worker.md
• skills/using-flow/SKILL.md

Validation

python3 -c "import flow_runtime_lib; import flow_runtime_lib.schema.evidence"
python3 -m unittest tests.test_flow_command_contracts
bash tests/validate-plugin.sh
python3 tests/workflow-fixtures.py
python3 tests/command-order-scenarios.py
python3 tests/smoke-flow-session.py

Python packaging notes:

• flow_runtime_lib is the importable runtime package name.
• pyproject.toml declares flow_runtime_lib/ as the packaged source tree for tooling and installs.
• scripts/*.py entrypoints prepend the repo root so direct script execution resolves the package consistently.

Design Rules

• Runtime logic is authoritative.
• session.json is canonical.
• rendered session docs are derived.
• Commands and hooks delegate to the runtime.
• Droids return payloads and do not write session state directly.
• Plans are compact and feature-based.
• The runtime accepts worker results only for the active feature.