@hassangameryt/freeflow 0.2.0 → 0.4.0

package/plugins/freeflow/skills/handoff/references/templates.md

@@ -1,64 +0,0 @@
-# Handoff Templates
-
-Use this only after destination is clear: temp handoff or memory handoff.
-
-Handoffs are memory, not authority. Keep them compact, evidence-linked, and easy for a fresh agent to verify.
-
-## Temp Handoff
-
-Use for immediate continuation after compaction, pausing, or a fresh chat.
-
-```md
-# Temp Handoff
-
-Date: YYYY-MM-DD
-
-## Goal
-
-## Current State
-
-## Decisions Made
-
-## Evidence To Reopen
-
-## Next Action
-
-## Watchouts
-```
-
-Keep `Current State` focused on what the next agent needs before acting. Do not include a transcript, full file tree, or broad repo summary.
-
-## Memory Handoff
-
-Use for durable project memory under the repo's existing handoff location.
-
-```md
-# Project Handoff
-
-Date: YYYY-MM-DD
-
-## Purpose
-
-## Stable Context
-
-## Decisions Made
-
-## Live Evidence
-
-## Next Focus
-
-## Stop Conditions
-
-## Superseded Or Deferred Work
-```
-
-Use `Live Evidence` for paths, tests, specs, ADRs, or commands the next agent should inspect. Say explicitly that live repo evidence overrides stale handoff text.
-
-## Resume Checklist
-
-When resuming from either handoff:
-
-- Reopen linked live files before consequential edits.
-- Verify completion claims before repeating them.
-- Treat source-truth conflicts as interview-gate triggers.
-- Ask before changing product, policy, security, privacy, billing, data-loss, compatibility, public API, or hard-to-reverse architecture.

package/plugins/freeflow/skills/interview-gate/SKILL.md

@@ -1,90 +0,0 @@
----
-name: interview-gate
-description: Use when context is low, scope is ambiguous, implementation/review/verification reveals unknowns, the user asks a question or suggests a path that could be misread as correction/permission, or the agent may be about to make a user-owned decision.
----
-
-# Interview Gate
-
-Stop before silent decisions.
-
-Known material method substitutions are decision points. If the requested, planned, or skill-required method and the fallback are already known, ask before source inspection, fallback work, or report drafting. Do not inspect files merely to make the fallback response more precise.
-
-## Stop First: Question or Decision Point
-
-If the user asks a question, answer it. Do not treat the question as criticism, permission, or a request to change behavior. Do not create, update, or delete files.
-
-If the answer reveals missing work, report the gap. Do not fill it unless the user asks you to.
-
-When the user asks "why did you", "did you", "what happened", or similar, answer what happened and why. Do not infer scolding, apologize, revert, edit, or promise future behavior changes unless the user asks.
-
-When the user suggests "this is better, right", "shouldn't we", or a similar option, treat it as a hypothesis. Evaluate against evidence and say yes, no, or partly. Do not agree just to be agreeable.
-
-If adopting a suggestion would change scope, source truth, workflow, files, or user-visible behavior, ask before acting.
-
-If the user is deciding the next path, answer the decision first. Do not turn "should we", "do we need", "let's X before Y", or "what next" into file changes unless the action and destination are explicit.
-
-Existing practice is evidence, not approval. "We usually do X" does not authorize X when another live rule or destination would also fit.
-
-Fire this gate from any workflow state when the next action depends on:
-
-- Product behavior.
-- Scope or priority.
-- Domain meaning.
-- Artifact creation, destination, or durability.
-- Compatibility.
-- Public API or user-facing behavior.
-- Irreversible architecture.
-- Security, privacy, billing, or data-loss behavior.
-- Changing docs, tests, specs, policies, ADRs, or handoffs to fit a new implementation request.
-- A user request, handoff, plan, or review comment contradicts current repo evidence.
-- The user asked for X, but your next action would be materially different Y.
-- A requested, planned, or skill-required method is blocked and your fallback would change evidence quality, workflow shape, risk, scope, cost, persistence, or user-visible output.
-
-## Inspect Before Asking
-
-If the answer is discoverable, inspect first:
-
-- Code.
-- Tests.
-- Docs.
-- Logs.
-- Issues.
-- ADRs or decision records.
-- Current external docs when facts may have changed.
-
-Ask the user only for decisions that remain user-owned.
-
-## Conflict Pattern
-
-If the requested path conflicts with evidence, rules, constraints, or your intended next action:
-
-- Stop before acting.
-- Name the requested path and the conflicting path.
-- Name the blocking constraint.
-- Say why the difference changes the next action.
-- Ask which path to follow.
-- Give a recommendation when the evidence supports one.
-
-Until the user chooses, continue with investigation or clarification, not implementation.
-
-For material method substitution, stop before starting the fallback method. The constraint itself is enough to ask when the fallback would change evidence quality, workflow shape, confidence, or output.
-
-Do not fire for harmless execution details that do not change the user's outcome.
-
-Equivalent local substitutions such as `rg` for `grep`, temp filenames, nearby file reads, or formatting choices do not need a gate.
-
-## Question Pattern
-
-Ask one question at a time.
-
-For each question:
-
-- State the uncertainty.
-- Explain why it changes the next action.
-- Give your recommended answer when possible.
-
-Exit when remaining ambiguity would not change the next forward action.
-
-## Backward Flow
-
-When implementation, review, or verification reveals a gap, return here before changing direction. Do not patch forward silently.

package/plugins/freeflow/skills/mode-contract/SKILL.md

@@ -1,79 +0,0 @@
----
-name: mode-contract
-description: Use when a user asks to set, change, infer, or discuss conversation/workflow/strict-workflow mode, or when task risk suggests recommending a workflow mode.
----
-
-# Mode Contract
-
-Use exactly three modes.
-
-## Modes
-
-**Conversation mode**: discussion, explanation, critique, exploration, quick analysis.
-
-- Answer questions; do not act on them.
-- No workflow pressure.
-- No required artifacts.
-- No plan/spec requirement.
-- Ask only when needed for the answer.
-
-**Workflow mode**: normal consequential work.
-
-- Use the workflow as a guide.
-- Ask or inspect when ambiguity would change the next action.
-- Create artifacts only when they preserve decisions, reduce risk, or enable handoff.
-- Verify before completion claims.
-
-**Strict-workflow mode**: high-risk or hard-to-reverse work.
-
-- Use stronger gates.
-- Require explicit decisions for security, privacy, billing, data loss, migrations, public APIs, compatibility, deployment, and large architecture changes.
-- Require explicit confirmation before changing source-of-truth artifacts such as docs, tests, specs, policies, ADRs, or handoffs when they contradict the requested implementation.
-- Recommend this mode when risk warrants it, but do not silently switch unless the user configured it as default.
-
-## Inference
-
-- If the user is talking or asking a conceptual question, use conversation mode.
-- If the user asks to implement, fix, research for action, review, or plan, use workflow mode.
-- If the task is high-risk, recommend strict-workflow mode and ask for confirmation.
-- If implementation would require overriding existing docs, tests, specs, policies, or established behavior, recommend strict-workflow mode and ask before editing.
-
-## User Control
-
-The user owns mode changes. You may recommend a mode; the user decides.
-
-## Commands And Defaults
-
-Keep two scopes separate:
-
-- `defaultMode`: persisted repo default in `.freeflow/config.json`.
-- Current mode: task, conversation, or session override. Do not persist it in repo config.
-
-Recognize only:
-
-```text
-/workflow conversation
-/workflow workflow
-/workflow strict-workflow
-/workflow reset
-```
-
-The three mode-setting commands switch mode for the current task, conversation, or host session only. `/workflow reset` clears the current override and returns to `defaultMode`; it is a command, not a fourth mode.
-
-Do not persist current mode, create repo state files, or edit config unless the user explicitly asks to change the repo default.
-
-Phrases like "from now on", "until I say otherwise", or "for this repo" still do not persist mode unless paired with an explicit default change request.
-
-When the repo default matters, read `.freeflow/config.json`. If it is missing or invalid, fall back to `workflow` and report the config issue when relevant.
-
-Persist only explicit default requests, such as "make strict-workflow the default for this repo." Update `.freeflow/config.json` with only:
-
-```json
-{
-  "defaultMode": "strict-workflow"
-}
-```
-
-Use the requested valid mode. Do not add current mode, task, phase, version, or activation-path fields.
-
-Direct skill calls are manual state selection. If the user calls a workflow segment directly, operate in that segment while still using the interview gate for user-owned decisions.

package/plugins/freeflow/skills/output-router/SKILL.md

@@ -1,69 +0,0 @@
----
-name: output-router
-description: Use when choosing between native tools and Freeflow routed tools, retrieving repo/vault evidence, running likely-large or noisy commands, recovering vaulted output, configuring outputRouter, or handling optional native read/bash safety-net routing.
----
-
-# Output Router
-
-Route output deliberately. Native tools stay direct unless explicit config enables the safety net.
-
-## Tool Choice
-
-- Need existing repo or vault information: use `freeflow_retrieve`.
-- Need candidate paths first: use `freeflow_retrieve action=locate`.
-- Need a best evidence packet: use `freeflow_retrieve action=query`.
-- Need exact known repo/vault lines: use `freeflow_retrieve action=retrieve` with `source.path` or `source.kind=vault`, plus `lineRange` when exact lines matter.
-- Need more around prior evidence: use `freeflow_retrieve action=expand`.
-- Need to explain a routed result or vault id: use `freeflow_retrieve action=explain`.
-- Need to run a likely-large or noisy command: use `freeflow_run`.
-- Need a whole known file/artifact: use native read.
-- Need direct shell behavior or expected-small exact output: use native bash.
-- Need to edit files: use native edit/write.
-
-## Hard Rules
-
-- Do not pretend routed output is native output.
-- Do not silently shorten native output. If the safety net transforms it, the result must say Freeflow routed it and include recovery instructions.
-- Capture raw output before transforming it.
-- Treat `preserve: full` as exact fidelity, not unlimited context injection. Over cap, return exact chunks or retrieval pointers.
-- Freeflow mode changes guidance strength only. It must not enable `postToolRouting`.
-- Keep `toolStatus`, `execution.status`, and `routing.status` separate.
-
-## Safety Policy
-
-Read `references/safety-policy.md` before changing routing policy, reviewing router behavior, or routing exactness-sensitive output.
-
-## Recovery Pattern
-
-For routed command or native safety-net output, recover exact text with:
-
-```json
-{
-  "action": "retrieve",
-  "source": { "kind": "vault", "outputId": "ffout_...", "stream": "stdout|stderr|combined|raw" },
-  "lineRange": { "start": 1, "end": 20 },
-  "preserve": "full"
-}
-```
-
-Use `query` first when the needed lines are unknown. Use `expand` when a previous evidence packet is too narrow.
-
-## Config
-
-The router works with built-in defaults. Persist `outputRouter` config only when explicitly requested; `setup-freeflow` owns repo setup/config changes.
-
-Supported repo keys are `postToolRouting`, `largeOutputBytes`, `largeOutputLines`, `vaultRoot`, `vaultRetentionDays`, `generatedPaths`, and `noisyCommandHints`.
-
-`outputRouter.postToolRouting` controls native read/bash safety-net routing:
-
-- `off`: native outputs pass through unchanged.
-- `safety-net`: large/noisy native read/bash output may be vaulted and labeled.
-- `strict`: reserved for stronger future guards; do not invent blocking behavior.
-
-Rules:
-
-- Minimal setup stays only `defaultMode`.
-- Do not dump defaults or create an empty `outputRouter` object.
-- `generatedPaths` affects broad scans only; explicit path retrieval remains available.
-- Freeflow mode changes guidance strength only. It must not enable `postToolRouting`.
-- Invalid config must fall back safely with a warning.

package/plugins/freeflow/skills/output-router/references/safety-policy.md

@@ -1,33 +0,0 @@
-# Output Router Safety Policy
-
-Use this reference for exactness-sensitive output routing.
-
-## Main Rule
-
-Do not silently summarize or compress exactness-sensitive output.
-
-Exactness-sensitive output includes:
-
-- user-requested exact/full output,
-- small outputs,
-- verification output needed for completion claims,
-- failure evidence needed for diagnosis,
-- source-truth conflict evidence,
-- security, privacy, billing, data-loss, or public API evidence,
-- anything marked `preserve: full`.
-
-## Required Behavior
-
-- Capture raw evidence before transformation whenever output is routed.
-- Label every transformed native result as Freeflow-routed output.
-- Include an `outputId` and exact recovery instructions for routed output.
-- Preserve exact failure and verification evidence lines; do not paraphrase them.
-- Pass small native outputs through unchanged.
-- For huge exactness-sensitive output, use vaulting and exact chunk retrieval instead of lossy summarization.
-- If post-tool safety-net routing fails, fail open: return the native output unchanged when possible and include a warning.
-
-## Non-Goals
-
-- This policy does not enable post-tool routing by itself.
-- This policy does not authorize model-assisted summarization inside the router runtime.
-- This policy does not require existing Freeflow skills to depend on the router runtime.

package/plugins/freeflow/skills/research/ARTIFACT-DESTINATIONS.md

@@ -1,58 +0,0 @@
-# Artifact Destinations
-
-Use this when a research checkpoint or decision must survive beyond chat.
-
-## Destination Test
-
-Before writing, answer:
-
-- What needs to survive?
-- Who will treat the destination as authority?
-- Which existing artifact already owns this kind of truth?
-- Would writing here create a new convention?
-- Would a future agent know to look here?
-
-If the owner is unclear, ask before writing.
-
-## Common Destinations
-
-| Research output | Prefer | Avoid |
-| --- | --- | --- |
-| Domain term or meaning | Existing `CONTEXT.md`, glossary, or domain doc | README fallback; creating domain memory without asking |
-| Feature behavior, scope, acceptance | Existing or requested spec | ADR unless the ADR test passes |
-| Future implementation path | Plan | Hidden plan inside a research note |
-| Evidence summary before requirements settle | Existing research/design notes, or ask | Creating `docs/research/` by default |
-| Immediate continuation state | Handoff | Durable decision memory |
-| Hard-to-reverse surprising tradeoff from alternatives | ADR | Product note that hides rationale |
-| Rejected approach | ADR if tradeoff-heavy; otherwise spec/decision note | Changelog or README by default |
-| No durable value | Chat checkpoint | New file for ceremony |
-
-## ADR Test
-
-Use an ADR only when all are true:
-
-- Hard to reverse.
-- Surprising without context.
-- Chosen from real alternatives.
-
-Otherwise use the owning spec, decision note, domain doc, handoff, or chat.
-
-## Stop Rules
-
-Do not create a new `CONTEXT.md`, glossary, `docs/decisions/`, `docs/specs/`, `docs/research/`, or ADR folder just because the checkpoint needs memory.
-
-A missing destination convention is a decision point.
-
-Do not put volatile file lists, command output, temporary TODOs, or implementation inventory in durable decision memory. Put continuation state in a handoff or plan when needed.
-
-## Question Shape
-
-When destination is ambiguous, ask one direct question:
-
-```text
-I have a checkpoint worth preserving: [what].
-The narrowest destination is [recommended artifact] because [why].
-Should I save it there?
-```
-
-Do not write the artifact before the user chooses the destination.

package/plugins/freeflow/skills/research/CHECKPOINTS.md

@@ -1,74 +0,0 @@
-# Research Checkpoints
-
-A checkpoint is the output of research. It preserves the current understanding and names the next route.
-
-Research does not end by silently writing a spec, plan, or implementation.
-
-## Chat Or Artifact
-
-Keep the checkpoint in chat when the work is short-lived and the next turn can safely continue from conversation context.
-
-Save the checkpoint when it must guide later work, another agent, a future session, or a durable artifact.
-
-Use the narrowest owning artifact:
-
-- Spec: behavior, scope, requirements, acceptance, product decisions.
-- Plan: future implementation path and checks.
-- Handoff: immediate continuation state.
-- Decision note or ADR: durable tradeoff or rejected approach.
-- Domain memory: stable term or domain meaning.
-- Research note: evidence summary that must be reused before requirements are settled.
-
-If no clear destination exists, ask before writing.
-
-## Shape
-
-Use this shape. Omit sections that do not apply.
-
-```text
-Question / goal: ...
-Evidence: ...
-Current understanding: ...
-Settled: ...
-Tentative: ...
-Open: ...
-Recommendation: ...
-Next: Forward | Backward | Branch | Stop — ...
-```
-
-## Good Checkpoints
-
-A good checkpoint:
-
-- Links or names live evidence instead of copying volatile inventory.
-- Separates settled facts from tentative assumptions.
-- Names open decisions that change the next route.
-- Recommends the next route without treating it as permission.
-- Avoids hiding user-owned decisions in polished prose.
-
-## Bad Checkpoints
-
-Bad:
-
-```text
-We discussed a lot. I'll implement the recommended path.
-```
-
-because it skips settled/tentative/open state and jumps to action.
-
-Bad:
-
-```text
-Decision: create docs/decisions/ and record everything.
-```
-
-when the repo has no decision-note convention and the user has not chosen that destination.
-
-Good:
-
-```text
-Settled: RiskReview is manual today; $500+ invoices enter review.
-Tentative: retry scheduling should assist support, not replace review.
-Open: should this be support-assistive or fully automated?
-Next: Backward — answer the automation-scope decision before spec.
-```

package/plugins/freeflow/skills/research/LANGUAGE.md

@@ -1,61 +0,0 @@
-# Research Language
-
-Use the same language as architecture review so early research shapes the codebase with the same concepts later used to review it.
-
-## Terms
-
-**Module**
-The thing being understood, built, or reshaped. It can be a feature, flow, artifact, repo area, package, class, function, or future slice of code.
-
-**Interface**
-Everything a user, caller, or future agent must know to use or continue the module correctly: names, inputs, invariants, ordering, error modes, ownership, and source truth.
-
-**Implementation**
-The details that can stay hidden behind the interface. Research should decide what callers must know before exposing implementation detail.
-
-**Depth**
-Leverage at the interface. Deep research makes the next spec, plan, or module simpler to use. Shallow research pushes coordination into the user, callers, or future agents.
-
-**Seam**
-Where behavior, ownership, or variation can change without rewriting surrounding work. A seam can be code, artifact, process, owner, or dependency shaped.
-
-**Adapter**
-A concrete thing satisfying an interface at a seam. Use this when something actually varies across the seam; do not invent adapters for ceremony.
-
-**Leverage**
-What one question, decision, or interface unlocks for future work.
-
-**Locality**
-Where evidence, decisions, tests, and changes should concentrate so future work can find them.
-
-## Deletion Tests
-
-Question deletion test:
-
-```text
-If I do not ask this, does downstream complexity spread?
-```
-
-Decision deletion test:
-
-```text
-If this is not captured, will future work rediscover or contradict it?
-```
-
-Module deletion test:
-
-```text
-If this module disappears, does complexity vanish or spread across callers?
-```
-
-## Research Use
-
-Use domain language from `CONTEXT.md`, existing docs, tests, and code. Do not invent polished names before evidence supports them.
-
-Name the outside first: what should users, callers, or future agents need to know? Then decide which implementation details can stay hidden.
-
-A good research pass should make later architecture review ask:
-
-```text
-Did we build the deep module we shaped here?
-```

package/plugins/freeflow/skills/research/SKILL.md

@@ -1,128 +0,0 @@
----
-name: research
-description: Use when shaping an idea, feature, architecture direction, vague task, or consequential question before spec, plan, build, or durable memory. Use when evidence, brainstorming, targeted questions, and decision checkpointing need to interleave.
----
-
-# Research
-
-Research is the discovery loop before action: evidence-guided back-and-forth that finds high-leverage decisions and ends in a checkpoint.
-
-For short-lived work, the checkpoint can stay in chat. When it must guide later work, save it in the narrowest owning artifact: spec, plan, handoff, decision note, ADR, or domain memory.
-
-Goal: enough evidence and shared understanding to checkpoint the current direction and route to spec, plan, more research, durable memory, build, or stop without inventing product, domain, scope, public API, security, privacy, billing, data-loss, compatibility, or architecture decisions.
-
-## Language
-
-Use the same architecture language when shaping work. Read `LANGUAGE.md` when the research needs deeper language mapping or the checkpoint will shape architecture:
-
-- **Module** — the thing being understood, built, or reshaped; it has an **interface** and an **implementation**.
-- **Interface** — what users, callers, or future agents must know to use or continue the work correctly.
-- **Implementation** — the details that can stay hidden behind the interface.
-- **Depth** — leverage at the interface. **Deep** means a small interface carries a lot of useful behavior. **Shallow** means the user, caller, or future agent must coordinate too many details.
-- **Seam** — where behavior, ownership, or variation can change without rewriting the surrounding work.
-- **Adapter** — a concrete thing satisfying an interface at a seam.
-- **Leverage** — how much future work one question, decision, or interface unlocks.
-- **Locality** — keeping evidence, decisions, tests, and changes where future work can find them.
-
-Use the **deletion test** on questions, decisions, and proposed modules: if skipping it makes complexity spread downstream, it matters. If skipping it makes complexity vanish, it was ceremony.
-
-## Loop
-
-1. Identify the target: repo area, artifact, URL, product, model, package, paper, issue, or idea. If multiple plausible targets would change research, ask for the source.
-2. Inspect the smallest evidence that can answer the current question: code, tests, docs, ADRs, specs, logs, issues, provided context, or current external sources.
-3. Explain the current understanding in plain language.
-4. Ask one path-changing question when the answer would change the next route.
-5. Let the user challenge, counter-question, or go deeper. Treat that as research input, not interruption.
-6. Refresh evidence when new claims, conflicts, or branches appear.
-7. Track decisions as settled, tentative, or open.
-8. Stop when remaining ambiguity would not change the next artifact or action.
-
-Research may move through evidence, brainstorming, targeted questioning, and checkpointing in any order. Do not force a fixed sequence when the evidence or conversation needs a loop.
-
-## Question Discipline
-
-Prefer deeper questions over more questions. Ask as many as the situation needs, but each question should earn its place: a good question collapses branches; a shallow question collects approvals.
-
-Before asking, run the question deletion test:
-
-```text
-If I do not ask this, does downstream complexity spread?
-```
-
-If no, skip it.
-
-Bad question:
-
-```text
-Should the button be blue or green?
-```
-
-when the feature purpose is still unclear.
-
-Good question:
-
-```text
-Is this for one workflow or many workflows?
-```
-
-because it changes the module interface, spec shape, and test surface.
-
-Long question chains are a failure mode, not diligence. Do not answer pressure for "every question" or "25-50 questions" by dumping a long questionnaire. That creates shallow approvals.
-
-Do not turn recommendations into an approval script. Recommendations should clarify tradeoffs, not make it easy to rubber-stamp many decisions. Give the recommendation when useful, then wait when the choice is user-owned.
-
-Instead of a long questionnaire: inspect evidence, name the decision tree, group lower-level unknowns, and ask the first high-leverage question that changes the next route. Continue in later turns as needed.
-
-After a few path-changing questions, or whenever the user introduces a new claim, inspect evidence, summarize, or checkpoint before asking more.
-
-## Decision Discipline
-
-Read `ARTIFACT-DESTINATIONS.md` when a checkpoint or decision must survive beyond chat and the owning destination is not obvious.
-
-Not every answer is durable. Keep a lightweight ledger:
-
-- **Settled** — explicit user decision or evidence-backed fact.
-- **Tentative** — useful working assumption, not authority.
-- **Open** — unresolved question that can change the next route.
-
-Persist a decision only when absence would make future work rediscover or contradict it.
-
-Put durable decisions where they belong:
-
-- Domain term or meaning -> existing glossary, `CONTEXT.md`, or domain doc.
-- Feature behavior, scope, or acceptance -> spec.
-- Future implementation path -> plan.
-- Immediate continuation state -> handoff.
-- Hard-to-reverse, surprising tradeoff chosen from alternatives -> ADR.
-- No durable value -> leave it in chat.
-
-If the destination is missing or ambiguous, ask before writing.
-
-## Stop Conditions
-
-Stop and ask the user when research reveals a user-owned decision, source-of-truth conflict, path conflict, material method substitution, or ambiguous artifact destination.
-
-Do not write implementation files from research.
-
-Write specs, plans, ADRs, handoffs, or decision notes only when the user asks or the checkpoint must guide later work.
-
-Do not leave research by silently jumping to spec, plan, or build. Close with a checkpoint when consequential direction changed.
-
-## Checkpoint Shape
-
-Read `CHECKPOINTS.md` when saving a checkpoint or choosing chat versus artifact.
-
-Use this shape when ending a research pass or routing forward. Save it in the owning artifact when it must survive beyond chat. Omit sections that do not apply.
-
-```text
-Question / goal: ...
-Evidence: ...
-Current understanding: ...
-Settled: ...
-Tentative: ...
-Open: ...
-Recommendation: ...
-Next: Forward | Backward | Branch | Stop — ...
-```
-
-`Next:` is routing, not permission to create the next artifact.