# Building With Viewflow

> Building With Viewflow is an Agent Skill for development published in the viewflow/viewflow repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Use when building a Django app with the Viewflow library — workflows (BPMN), CRUD viewsets, FSM state transitions, jsonstore process data, or Viewflow forms. Loads Viewflow conventions and the full docs.

- Skill name: `building-with-viewflow`
- Category: [Development](https://www.openparable.com/skill/development/1)
- Source: https://github.com/viewflow/viewflow/blob/HEAD/skill/SKILL.md
- Repository: viewflow/viewflow (2,865 GitHub stars when collected)

## SKILL.md

# Building with Viewflow

Viewflow is a low-code library for Django. It adds workflows (BPMN), CRUD,
forms, and reporting on top of normal Django models and views.

## How to use this skill

1. Fetch `https://docs.viewflow.io/llms-full.txt` — the whole documentation in
   one file. Search it before guessing an API. It is the source of truth.
2. For a quick orientation, fetch `https://docs.viewflow.io/AGENTS.md`.
3. Follow the conventions below.

## Conventions

- Install: `pip install django-viewflow`. Add `"viewflow"` (and
  `"viewflow.workflow"` for workflows) to `INSTALLED_APPS`.
- Workflows are `flow.Flow` subclasses; wire nodes with `this.<name>`. Store
  process data in `viewflow.jsonstore` fields on a proxy `Process` model — no
  per-field migrations.
- Mount with `Site`/`Application` viewsets, not hand-written URL patterns.
- For state transitions without the workflow engine, use `viewflow.fsm.State`
  and `@state.transition(source=..., target=...)`. The target state is set
  before the method body runs and rolls back on exception.
- A transition permission is a query, not a gate: the method runs regardless.
  Check `flow.<transition>.has_perm(user)` in the view and raise
  `PermissionDenied`.
- Workflow permissions are `view_<model>` and `manage_<model>`; canceling a
  process needs `manage`.
- Don't edit `viewflow/` in the open-source repo — it is generated.

## Examples

See `https://docs.viewflow.io/AGENTS.md` for minimal flow, URL, and FSM
examples, and https://github.com/viewflow/cookbook for full sample projects.

---

Source: https://www.openparable.com/skill/development/building-with-viewflow (OpenParable). Cite the canonical URL above.
