Freeflow
Lightweight workflow for coding agents.
Agent workflow tools tend to choose one side of the problem: sharp point skills, full lifecycle methodology, or enforcement-heavy runtimes. The missing layer is a small workflow spine that prevents silent product decisions, source-truth rewrites, fake verification, and messy handoffs without turning every change into a process operating system.
Workflow
Freeflow is a workflow layer, not a new agent. It helps the agent choose the right amount of process for the task.
Modes
conversation: answer, explain, critique, or explore without workflow pressure.workflow: default for consequential work; use the workflow spine and scale detail to risk.strict-workflow: high-risk or hard-to-reverse work with stronger gates.
Use strict-workflow for security, privacy, billing, public APIs, migrations, data loss, compatibility, permissions, deployment, or irreversible architecture.
Map
flowchart LR
Request{request}
Talk[conversation<br/>answer directly]
Discover[discover<br/>research / grill]
Spec[spec]
Plan[plan]
Build[build<br/>execute / diagnose]
Check[review + verify]
Close[commit / handoff]
Request -->|question| Talk
Request -->|work| Discover
Discover --> Spec --> Plan --> Build --> Check --> Close
Check -. new evidence or failed check .-> Discover
The map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates.
Backward Edge
Loop back when new evidence changes the path:
flowchart LR
Trigger{new evidence<br/>conflict<br/>failed check<br/>owner decision}
Decide{changes<br/>next action?}
Continue[continue]
Reenter[clarify / research<br/>revise spec or plan<br/>diagnose / split / stop]
Trigger --> Decide
Decide -->|no| Continue
Decide -->|yes| Reenter
Reenter -. resume .-> Decide
The agent should not silently choose the backward destination when the choice changes product behavior, scope, compatibility, public APIs, security, privacy, billing, data loss, permissions, or irreversible architecture.
Bypass
Bypass skips ceremony, not judgment.
Use bypass only to skip an unnecessary gate. It does not skip user-owned decisions, source-truth conflicts, risky checks, or fresh verification before completion claims.
Install
Codex
Register the GitHub repo as a Codex marketplace, refresh it, then install Freeflow:
codex plugin marketplace add https://github.com/hassan-mohiddin/freeflow.git
codex plugin marketplace upgrade freeflow
codex plugin add freeflow@freeflow
codex plugin list | rg freeflow
In the Codex app, add the same GitHub marketplace URL from /plugins, then search for freeflow.
Claude Code
Register the marketplace:
/plugin marketplace add hassan-mohiddin/freeflow
/plugin install freeflow
Or install directly from GitHub:
/plugin install hassan-mohiddin/freeflow
Other Agents
Copy the plugins/freeflow/skills/ directory into the agent's skills/plugin system and make sure the agent can read SKILL.md files with bundled references/.
Usage
Use natural language first:
Use Freeflow workflow mode for this task.
Keep this in conversation mode.
Use strict-workflow for this billing change.
Verify before claiming completion.
Capture the durable decision.
Slash-style prompts are model-routed in v0.1:
/workflow conversation
/workflow workflow
/workflow strict-workflow
/write-spec
/write-plan
/execute-plan
/verify-work
/commit-work
/handoff
Freeflow does not ship native slash handlers yet. The commands work as skill-routing language.
Docs
Evidence
Freeflow does not claim to beat Matt Pocock's skills or Obra's Superpowers. Those are references for skill sharpness and lifecycle discipline. Current evals compare baseline agent behavior against Freeflow instructions/skills, then verify command coverage.
