majiayu000/spellbook / skills/flowguard
flowguard
VerifiedGuard long, ambiguous, or stateful AI-agent work from drift. Use when the user asks to run or continue a multi-step task, autonomous loop, bug fix, repo change, PR readiness check, compaction handoff, resume from previous context, cost-control checkpoint, or any task likely to span many tool calls, files, sessions, agents, or verification gates.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| agents/openai.yaml | config | 212 B |
| references/state-contract.md | markdown | 4.2 KB |
| scripts/workflow_state_snapshot.shexecutable | script | 3.2 KB |
references/state-contract.md
View on GitHub# Flowguard State Contract
Use these compact formats when a task needs durable state across long loops, compaction, session boundaries, or automation. Keep entries factual and evidence-backed.
## Preflight
```text
route: execute_direct | plan_first | clarify_first
goal:
context:
constraints:
done_when:
out_of_scope:
verification_commands:
stop_conditions:
handoff_location:
objective_restatement:
plan_5_steps_or_less:
context_audit:
keep:
externalize:
discard:
stale_or_conflicting:
```
Use `clarify_first` when missing data would cause destructive, expensive, security-sensitive, or large-scope work.
## Checkpoint
```text
checkpoint_time:
current_step:
modified_files:
commands_run:
fresh_evidence:
decisions:
context_audit:
review_gate_decision:
blockers:
next_step:
scope_change:
```
Create a checkpoint before compaction, after a meaningful verification result, before changing execution direction, and after any user correction.
## Handoff
```text
task:
latest_user_request:
cwd:
repo_root:
branch:
head:
dirty_state_summary:
modified_files:
constraint_set_or_spec:
l1_l7_summary:
key_decisions:
current_priority:
objective_restatement:
plan_5_steps_or_less:
context_audit:
keep:
externalize:
discard:
stale_or_conflicting:
verification_commands:
fresh_verification_evidence:
review_gate_decision:
blockers:
next_action:
stop_conditions:
lane_map:
artifacts:
memory_used:
staleness_checks:
```
Required fields for compaction safety: `modified_files`, `constraint_set_or_spec`, `verification_commands`, `key_decisions`, `current_priority`, and `l1_l7_summary` when VibeGuard applies.
Context audit fields are required when the handoff follows a long loop,
multi-agent run, compaction, or queue. Externalize raw logs, broad search
results, stale plans, and large tool output into artifacts or durable notes
instead of carrying them in active context.
## Resume Checklist
1. Re-read applicable `AGENTS.md` before editing.
2. Read the handoff or prior checkpoint.
3. Run the installed Flowguard snapshot script with an explicit target repo path, for example `/path/to/installed/flowguard/scripts/workflow_state_snapshot.sh /path/to/target/repo`.
4. Compare cwd, repo root, branch, head, dirty files, and artifacts against the handoff.
5. Treat memory as a hint until verified against current files, git, runtime, or remote truth.
6. Reconcile any newer user instruction before continuing older work.
7. Re-establish the current route: `execute_direct`, `plan_first`, or `clarify_first`.
8. Re-state the current objective and a plan of no more than five steps before editing.
If the handoff and local truth disagree, update the plan before editing. If the disagreement changes goal, scope, safety, or done-when, stop and ask.
## Loop Guard
Stop the autonomous loop and reassess when:
- The same hypothesis or fix fails 3 times.
- Tool results contradict the active plan.
- The work crosses into files or systems not named in scope.
- A dependency, runtime, remote service, or test fixture changed underneath the task.
- The next step requires credentials, secrets, payment/auth logic, destructive data changes, deploys, force-push, or production writes.
- Cost or time exceeds the stated budget.
When stopped, report: current hypothesis, evidence for and against it, changed files, commands run, and the smallest next decision needed.
## Verification Evidence
Evidence must come from the current session. Acceptable examples:
- command output with command name and result
- test/build/lint summary
- HTTP response or health check with URL and status
- screenshot or visual check for UI work
- git status/diff summary for file state
Do not use "earlier passed", "should work", or stale memory as completion evidence.
## Automation Readiness
Do not schedule an agent workflow until the manual form has succeeded repeatedly.
Read-only automation candidates:
- state snapshot
- stale worktree report
- handoff draft
- verification summary
- failed-log digest
- review-pack drafts
- context-audit summaries
Require explicit user confirmation or a separate trusted contract for:
- code edits
- dependency upgrades
- database writes
- credential or secret changes
- deploys
- PR submission or merge
- force push
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |