Flowguard
Lifecycle guard for work that can drift, lose context, or compound errors. Routes first, verifies live state, runs bounded loops, leaves resumable handoff.
Does not replace the user's chosen workflow (writing, learning, audit, etc.) — only wraps execution discipline.
Operating contract
- No long loop until route, scope, and stop conditions are explicit.
- Memory and handoffs are hints until git, files, runtime, or remote state are verified.
- No completion claims without fresh verification evidence.
- No scope expansion or destructive surfaces without re-route.
Route first
| Route |
Use when |
execute_direct |
Goal, constraints, done-when clear; small scope |
plan_first |
Many files/sessions, migrations, risky sequencing |
clarify_first |
Missing goal, files, constraints, or destructive permission |
Wrong assumption → large rewrite, prod risk, or data loss → clarify_first.
Startup
- Search for existing plans, artifacts, or prior work.
- Load applicable
AGENTS.md for editable paths.
- Snapshot (from installed flowguard dir):
/path/to/flowguard/scripts/workflow_state_snapshot.sh /path/to/target/repo
- Verify cwd, branch, dirty files if resuming — do not trust memory alone.
- Capture goal, context, constraints, done-when; clarify if risky gaps.
Preflight
State compact preflight (references/state-contract.md § Preflight). High-risk kickoff → expand with references/task-contract.yaml.
Phase work (load on demand)
| Phase |
Read |
| Context compaction |
references/strategic-compact.md |
| Prioritize findings / regression |
references/scoring-matrix.md, references/review-template.md |
| Implement loop |
references/execution-loop.md |
| Handoff / resume |
references/state-contract.md |
Validation
bash -n flowguard/scripts/workflow_state_snapshot.sh
Resources
scripts/workflow_state_snapshot.sh — read-only repo snapshotreferences/state-contract.md — preflight, checkpoint, handoff, resumereferences/strategic-compact.md — boundary compactionreferences/execution-loop.md — loop, verification, multi-agentreferences/task-contract.yaml — high-risk kickoff checklistreferences/scoring-matrix.md — finding priorityreferences/review-template.md — regression template
1---2name: flowguard3description: Guard long, ambiguous, or stateful AI-agent work from drift. Use for multi-step implementation, compaction at phase boundaries, task contracts, handoff/resume, or work spanning many tool calls, files, or sessions — not single-shot article writing, topic learning, or codebase audit.4---56# Flowguard78Lifecycle guard for work that can **drift**, lose context, or compound errors. Routes first, verifies live state, runs bounded loops, leaves resumable handoff.910Does **not** replace the user's chosen workflow (writing, learning, audit, etc.) — only wraps execution discipline.1112## Operating contract1314- No long loop until route, scope, and stop conditions are explicit.15- Memory and handoffs are hints until git, files, runtime, or remote state are verified.16- No completion claims without fresh verification evidence.17- No scope expansion or destructive surfaces without re-route.1819## Route first2021| Route | Use when |22|-------|----------|23| `execute_direct` | Goal, constraints, done-when clear; small scope |24| `plan_first` | Many files/sessions, migrations, risky sequencing |25| `clarify_first` | Missing goal, files, constraints, or destructive permission |2627Wrong assumption → large rewrite, prod risk, or data loss → `clarify_first`.2829## Startup30311. Search for existing plans, artifacts, or prior work.322. Load applicable `AGENTS.md` for editable paths.333. Snapshot (from installed flowguard dir):3435```bash36/path/to/flowguard/scripts/workflow_state_snapshot.sh /path/to/target/repo37```38394. Verify cwd, branch, dirty files if resuming — do not trust memory alone.405. Capture goal, context, constraints, done-when; clarify if risky gaps.4142## Preflight4344State compact preflight (`references/state-contract.md` § Preflight). High-risk kickoff → expand with `references/task-contract.yaml`.4546## Phase work (load on demand)4748| Phase | Read |49|-------|------|50| Context compaction | `references/strategic-compact.md` |51| Prioritize findings / regression | `references/scoring-matrix.md`, `references/review-template.md` |52| Implement loop | `references/execution-loop.md` |53| Handoff / resume | `references/state-contract.md` |5455## Validation5657```bash58bash -n flowguard/scripts/workflow_state_snapshot.sh59```6061## Resources6263- `scripts/workflow_state_snapshot.sh` — read-only repo snapshot64- `references/state-contract.md` — preflight, checkpoint, handoff, resume65- `references/strategic-compact.md` — boundary compaction66- `references/execution-loop.md` — loop, verification, multi-agent67- `references/task-contract.yaml` — high-risk kickoff checklist68- `references/scoring-matrix.md` — finding priority69- `references/review-template.md` — regression template
zhijunio