liuyingxuvka/FlowGuard

A "software DNA" for AI-assisted development: one living model tree with code owners, executable models of risky flows, tests and a target for planned changes.
中文说明
FlowGuard maps and checks its own repository (.flowguard/map.json, .flowguard/models/). Its model and boundaries are described in the concept guide.
## What it does
AI agents are good at local edits, but every new session has to rediscover: what parts does the
software have, who owns this behavior, what else does a change affect? FlowGuard keeps three
things in the project:
1. The map .flowguard/map.json - components, their responsibilities, owned state, side
effects, files, entrypoints, dependencies, tests and models. A new session reads the whole map
in a few thousand tokens and knows where to look.
2. Models - small executable Input x State -> Set(Output x State) models of risky flows
(retries, idempotency, caching, ordering, money, permissions, multi-step workflows). FlowGuard
explores every input sequence within a bound, reports counterexamples, checks that known-bad
variants fail, and replays model traces against the real code (conformance).
3. The target - the intended map and models for one planned behaviour or structure change;
implement and check that plan before promoting it to the current model.
The map and models form one tree. Root and component nodes come from the code and stay active;
behavior models are added beneath components when a task needs them, with tests on the same nodes.
python -m flowguard read --mermaid draws this tree.
The current tree lives in .flowguard/map.json and .flowguard/models/; planned changes live in one target under .flowguard/target/ at a time.
For behaviour or structure changes, write the target first, then make the code and tests match it.
Once target check has no ERROR or TO-DO, target promote replaces the current tree and removes the target.
Map and code verify each other: every source file belongs to exactly one component; entrypoints,
flow steps and model files must exist; every real import must be declared;
confirming a component records a fingerprint of its files, so any code change marks it STALE until
someone re-reads and re-confirms it. History lives in git.
## Five-minute start
bash
pip install -e . # engine, standard library only
# or from GitHub: python -m pip install "flowguard @ git+https://github.com/liuyingxuvka/FlowGuard.git@ "; the PyPI package named flowguard is a different project
python scripts/installskill.py --target ~/.claude/skills # skill for your agent (or $CODEXHOME/skills)
cd your-project
python -m flowguard map scan # 1. draft components; guess tests from imports (default max 40)
python -m flowguard map discover # inspect routes, commands, effects and state writers
python -m flowguard map digest all # 2. API outline, signatures, assignments and docstrings; size varies
# edit .flowguard/map.json: merge/split components, write summary, responsibilities, layer ...
python -m flowguard map deps --write # 3. dependencies from real imports
python -m flowguard map check # 4. fix until 0 errors
python -m flowguard map confirm all # 5. the map is current
python -m flowguard map lint # 6. architecture review