Flowmind Author

/flowmind-author — Write, Validate, Fix, Promote, Measure

Intent Router

Write a Flow

Load the authoring guide first:

# Canonical reference
cat ~/lev/docs/design/design-flowmind-authoring-guide.md

The Golden Rule

If you can express the check as bash -c "..." && echo pass || echo fail, it is a lev.validate node. Full stop.

The Two Primitives

Everything else is topology over these two primitives.

Required Fields

name: my-flow           # unique identifier
entry: first_node       # where execution starts

policy:
  determinism: true     # enforce reproducibility

knobs:                  # parameterize the flow
  my_param:
    type: string        # MUST have type declaration
    default: value

nodes:
  first_node:
    type: action
    description: |      # instruction-shaped, not vague
      What this node does and why.
    op: lev.validate    # or lev.exec
    ...

Flow Patterns (from authoring guide)

Validate a Flow

Run the audit flow against any .flow.yaml:

# Audit all flows in the repo
lev exec "audit all flows" \
  --flow ~/.lev/flows/lev-flowmind-audit.flow.yaml

# Audit a specific directory
lev exec "audit sdlc flows" \
  --flow ~/.lev/flows/lev-flowmind-audit.flow.yaml \
  --set scan_path=plugins/sdlc/flows/

# Audit a single flow
lev exec "audit this flow" \
  --flow ~/.lev/flows/lev-flowmind-audit.flow.yaml \
  --set scan_path=path/to/my.flow.yaml

What the Audit Checks

1. Syntax: Valid YAML, required fields, reachable nodes, terminal nodes
2. Spec parity: op: is lev.validate or lev.exec, branch keys valid, knobs typed
3. Patterns: Golden rule enforced, iteration bounded, prompts exist
4. Telemetry: Terminal nodes present, descriptions are instructional
5. Parity: Duplicate flows across plugin directories flagged

Fix a Flow

When the audit finds violations, use the remediation meta-prompt pattern:

VIOLATION: {description}
FLOW: {flow_file}
CANON RULE: {gate_id}

REASONING CHAIN:
1. Read {flow_file}
2. Identify the specific violation
3. Determine fix strategy
4. Apply fix (touch ONLY the flow file)
5. Verify with deterministic command

For project-specific constraint flows (like NAAC), the meta-prompt KB lives at: .lev/flows/prompts/naac-auditr-revival/kb-remediation-metaprompts.md

General FlowMind fixes:

• Missing entry: → add entry field pointing to first node
• Orphaned node → wire it into a branch path or remove it
• lev.exec for deterministic check → change to lev.validate
• Untyped knob → add type: declaration
• Missing prompt file → create at path referenced by prompt: field

Promote a Flow

Flows follow the same promotion ladder as other Lev artifacts:

workshop (experimental)
  → poc (proven in one project)
  → plugin (proven across projects)
  → core (canonical)

Promotion requires a typed PromotionDecision:

• gate_pass_ratio == 1.0 for all authoritative gates
• blocking_findings == []
• Evidence artifacts exist
• Transition is on an allowed edge

Measure a Flow

After execution, check FlowTelemetry:

• total_tokens — cost signal
• wall_time_ms — performance signal
• outcome — green/red/partial
• gate_pass_ratio — quality signal

Over N runs, flows build a track record. Successful patterns get promoted; failing patterns get mutated or retired.

Related

Reference Documents