Skip to content

majiayu000/spellbook / skills/flowguard

flowguard

Verified

Guard 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.

FileKindSize
SKILL.mdskill md8.0 KB
agents/openai.yamlconfig212 B
references/state-contract.mdmarkdown4.2 KB
scripts/workflow_state_snapshot.shexecutablescript3.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
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall