hassan-mohiddin/freeflow

Use whenever work leaves your working tree: staging and committing, writing a commit message, pushing, opening, updating or merging a pull request, finishing, keeping or deleting a branch or worktree; preparing or publishing a release (version bump, changelog, release notes, tag, package publish); and deploying, rolling out, rolling back or restoring production. Read it before running git commit, git push, a merge, a tag or a publish command, even when the user only says commit or ship. It checks the branch, the staged files and the remote before each step, and exactly what each step includes.

Use whenever what to do, or how, is not settled yet: exploring a problem, comparing options or approaches, questioning assumptions, brainstorming, planning an approach, designing or changing modules, interfaces, data models, state, error handling or dependencies, or revisiting a direction after new evidence. Read it at a task's first request, before your first tool call, to decide with the user what you will do, where you stop and which choices are theirs before anything is built, fixed or changed. Also use mid-work when a choice the user owns comes up (behavior, names, defaults, scope, cost, risk) or sources conflict; when a question needs a quick experiment before building on it; when a discussion or its decisions must outlast the conversation; and when the user asks to skip or lighten optional steps such as a plan, a review or a record.

Use when testing, evaluating or comparing how an agent behaves: whether a skill triggers, whether a change to a prompt, skill, model, setting or extension changes outcomes, measuring a reviewer or checker, or benchmarking agents on coding tasks, conversations or pipelines. Also use when writing or checking an eval's JSON files, running an eval and reading its results, and deciding what a result can claim, how many cases and trials it needs and what it costs.

Use for any task that uses tools: reading or searching a repository, running commands, diagnosing, and any work that changes code, files or settings: implementing a feature, fixing a bug, adding or changing behavior, configuring, prototyping, refactoring, simplifying or cleaning up code, deleting dead code, or maintaining a project. Also use when something fails, breaks, regresses or slows down and the cause is unknown, or a fix did not hold; when migrating users, data, a schema, a service or traffic to a replacement and removing the old path; when adding edge-case handling or code comments; and when handing work to subagents or parallel workers, or working from another agent's brief. Read it before your first tool call on a task, even a small or read-only one: it reads the request for its asks and implied requirements, finds what the change touches before you edit, and reports the result.

Use when a question has to be answered from evidence gathered and checked first: an in-depth report on a codebase, library, agent harness or tool; a survey, literature or systematic review of papers, docs or prior work; finding out what sources say before relying on them, and rechecking a published study's numbers; a study or experiment whose plan is fixed before the data, or a quick check on about twenty tasks of whether a change helped; writing a paper from results with its figures, references and PDF, and answering its reviewers. Also use when citing code at a pinned commit, deciding how strong a claim's evidence is, checking that each number traces to its log and each citation supports its claim, designing a measurement or a model judge, and computing statistics for a result (intervals, paired comparisons, clustered runs, rater agreement, pass@k, multiple comparisons, power, meta-analysis). Comparing options from facts already in hand is Discuss Work's; checking whether a change works is Verify Work's.

Use whenever finished work or a document is judged fit to use: reviewing code, a diff, a commit or a pull request; reviewing a spec, plan, design, ADR, handoff, skill, final report, status note or Working Record; reviewing changes to authentication, permissions, secrets, untrusted input or other security boundaries; reviewing an eval case, suite, grader or rubric before paying for its runs; preparing, dispatching or skipping an independent review; choosing a model as judge or relying on its verdict; and weighing a review report that came back.

Use when installing, activating or turning off Freeflow in a repository, changing or repairing its repository or personal configuration (.freeflow/config.json, .freeflow/local.json), setting up the Freeflow store that keeps task memory (local only, or local + cloud with a private repository, in a cloud session too) and moving older task records into it, or checking whether the current host is loading Freeflow's guidance and skills.

Use when a task needs memory beyond the conversation: starting, updating, checkpointing or recovering its Working Record; choosing, taking, switching or releasing a task from Freeflow's task menu, or one another session holds; moving a task into or out of a project; when work may not fit in what is left of the context, or will outlast this context cycle; when Freeflow says compaction is near, after a compaction, a summary, a clear or a move into a new session; before pausing, handing off or transferring work; when a task ID, a project, the Freeflow store or its sync, or parallel sessions are involved; when a record says Schema 4; and when editing a record or running its working-record script. It decides what the record says, and every lifecycle change goes through its script.

Use whenever you need to know whether something works or a claim is true: running tests, builds, linters or type checks; reproducing a bug or checking a fix; trying the real path in the running software, a browser or a CLI; measuring performance; and reading what the output actually shows, including failures and conflicting results. Read it before saying a change works, is fixed or is done, and to check your own change or document before reporting it done. Also use when writing, designing or changing a test, fixture or regression check; when a claim depends on an integration, host lifecycle, an installed package, rendered UI or browser behavior, or performance; and when setting up, following or updating a project's saved steps for launching its software and trying each feature as a user would, or rechecking them after the software changed.

Use when writing, updating or reviewing a document someone will act on: a spec, PRD, issue, requirements, API or interface contract, technical design, decision record or ADR; a comparison of options; an implementation, remediation, migration or operations plan; a README, user guide, developer docs, subsystem doc, overview, folder README, feature file or a skill's design record; or when a code change makes existing docs wrong, or a project has no developer docs yet. It covers where a document goes, its header and status, and the checks to run after writing it.

Use when creating, revising, merging or splitting a skill or any other text an agent acts on: a SKILL.md and its description, the references and scripts in a skill, AGENTS.md, CLAUDE.md, system or runtime prompts, tool descriptions, subagent briefs or judge prompts. Also use when deciding where an instruction should live, and when a skill is read at the wrong time, not read at all, or read but not followed.