AGENT SKILL

setup-freeflow

Use when activating Freeflow in a repository, repairing its repository or personal configuration, or checking whether the current host is delivering Freeflow context.

License 许可
MIT
最近更新
2026-11-15
Stars
★ 5
Forks
0

01 前言 Front Matter

name
setup-freeflow
description
Use when activating Freeflow in a repository, repairing its repository or personal configuration, or checking whether the current host is delivering Freeflow context.

02 资源文件 1

03 SKILL.md 正文

Setup Freeflow

Create or repair the smallest valid layered setup. Keep repository activation, personal overrides, and host runtime delivery as separate facts.

  • .freeflow/config.json is the required shared repository activation config.
  • .freeflow/local.json is an optional per-checkout personal override. It cannot activate Freeflow by itself.
  • Runtime delivery depends on the current host's installed and trusted adapter.

Answer setup questions and delivery checks read-only. An explicit action request authorizes the smallest selected setup change under the state rules below. When repository config is missing, first activation authorizes minimal shared config; it does not authorize personal overrides, optional capabilities, replacement of invalid config, or edits to repo-owned host instructions.

Read the activation contract before changing setup state. Read host setup when runtime delivery, lifecycle, or host trust matters. Read Output Router setup only when the user explicitly requests it during setup or repair; later tuning belongs to Output Router.

Establish Mutation Authority

Classify the current state before editing:

  • Unconfigured: repository config is missing or invalid, so no Freeflow mode is effective. An explicit setup request may create minimal config when it is missing. Replacing or reinterpreting invalid config still requires the specific authority described below.
  • Configured but ineffective: valid repository activation exists, but Freeflow is disabled, Skills are dormant, or invalid local config blocks runtime. No mode is effective. An explicit request governs the selected enablement, configuration, or repair; any dormant resolved mode does not.
  • Effective: Freeflow Skills report an effective mode. Obey it. Conversation remains read-only; Workflow or Strict Workflow allows agent-performed mutation only for the separately requested setup or repair.

User-operated host settings are direct user actions, not agent-performed config edits. Prefer them when available and do not claim their state changed until the host reports it.

Inspect The Layers

Before editing:

  1. inspect .freeflow/config.json and .freeflow/local.json independently;
  2. identify which requested values are shared repository state and which are personal overrides;
  3. inspect repo instructions only when a conflict would change setup behavior;
  4. identify the host and available delivery evidence when runtime status matters.

A valid repository config establishes activation. A missing local config inherits shared values. An invalid existing local config blocks effective Freeflow instead of falling back silently.

If setup is already valid and no change was requested, preserve it and report the effective sources. Do not rewrite config merely to normalize formatting or materialize defaults.

Configure Shared Activation

For a new default setup, write:

{
  "defaultMode": "workflow"
}

During first activation, an explicitly requested conversation or strict-workflow mode becomes the shared repository default. Preserve valid existing settings and add no unrequested keys or empty sections.

If repository config is invalid or conflicts with accepted source truth, use Decision Gate before replacing or reinterpreting it.

Do not create or append Freeflow instructions in AGENTS.md, CLAUDE.md, .claude/rules/, or another host-owned instruction surface.

Add Personal Overrides Only When Requested

Use .freeflow/local.json for an explicitly selected per-checkout override of enabled, interactionContract, skills.enabled, or defaultMode. Omitted values inherit from repository config and built-in defaults.

In Pi, /freeflow settings edits personal overrides and /freeflow settings repo edits shared settings. Prefer those controls when available.

Before writing local config in a Git checkout, verify it is untracked and ignored. Do not modify shared ignore policy merely to store a personal preference; use the host's safe settings path or local Git exclusion. Refuse to overwrite a tracked local config.

If local config is invalid, report that it blocks effective runtime. Repair or remove it only with authorization; never discard it and fall back silently.

Keep Optional Setup Explicit

Do not ask an automatic capabilities question. Configure Output Router only when explicitly requested, using Output Router setup. Preserve valid existing capability config during idempotent setup.

Establish Same-Turn Context

After successful verification, apply newly effective context directly for the remainder of the setup turn:

  • read the Interaction Contract when it is effective;
  • read Workflow and Mode Contract when Skills are effective;
  • read an explicitly configured capability skill only when runtime state says it is effective.

This direct read establishes same-turn guidance; it does not prove that a lifecycle adapter ran. After first activation, use host setup to name the exact host-native lifecycle action for automatic delivery and resource refresh, state what applies before that boundary, and keep delivery confirmed, unavailable, or unconfirmed from evidence.

Verify And Report

Verify:

  • repository config parses and contains a valid defaultMode;
  • local config is missing or valid, personal, untracked, and ignored when applicable;
  • effective enabled, Interaction Contract, Skills, and configured default values have the expected sources;
  • Skills-disabled mode remains resolved but dormant;
  • optional capability config changed only when requested;
  • no repo-owned host instructions or unrelated files changed.

Report separately:

  1. shared repository activation;
  2. personal override state and effective sources;
  3. effective capability state;
  4. same-turn direct context reads;
  5. automatic runtime delivery as confirmed, unavailable, or unconfirmed.

04 同仓库更多 Skills

hassan-mohiddin
hassan-mohiddin/freeflow

write-skill

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.

★ 5
hassan-mohiddin
hassan-mohiddin/freeflow

verify-work

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.

★ 5
hassan-mohiddin
hassan-mohiddin/freeflow

setup-freeflow

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.

★ 5
hassan-mohiddin
hassan-mohiddin/freeflow

research-work

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.

★ 5
hassan-mohiddin
hassan-mohiddin/freeflow

execute-work

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.

★ 5
hassan-mohiddin
hassan-mohiddin/freeflow

evaluate-behavior

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.

★ 5