@hassangameryt/freeflow 0.1.0 → 0.2.0

package/plugins/freeflow/skills/execute-plan/SKILL.md

@@ -1,21 +1,29 @@
 ---
 name: execute-plan
-description: Use when implementing an approved plan or executing planned work against a repo, especially when a planned verification command fails or reveals a plan/source conflict. Use when the user says to execute, implement, follow, or carry out a plan.
+description: Use when implementing an approved plan, executing planned slices, resuming planned work, handling planned verification failures, adjudicating review findings during execution, or encountering scope/source conflicts while carrying out a plan.
 ---
 
 # Execute Plan
 
 Execute the plan. Do not improve it silently.
 
-Classify first:
+The plan is instructions, not authority. Live repo evidence and source truth win.
+
+Move one verified slice at a time. Preserve rollback, reviewability, and user control.
+
+Read `references/execution-map.md` when the plan has multiple slices, TDD/benchmark work, review checkpoints, per-slice commits, context-window pressure, or any failed check/review/source-scope conflict.
+
+Keep research language alive. Read `../research/LANGUAGE.md` when a slice changes modules, interfaces, seams, adapters, architecture, or when review findings become a stream of edge-case patches. Ask whether the slice is deepening the module or spreading complexity across callers, tests, docs, or review comments.
+
+## Classify First
 
 - Valid plan: inspect source context, execute the next slice, verify it.
 - Plan/source conflict: stop and ask which source should change.
 - Hidden owner decision: stop and ask.
 - Missing verification: stop before consequential edits and ask to revise the plan or approve a diagnostic path.
 - Missing plan: ask for a plan or route to `write-plan`.
-
-The plan is instructions, not authority.
+- Scope expansion: stop before absorbing it; route back to research, spec, or plan.
+- Review failure during execution: classify findings and report the route before editing from them.
 
 ## Before Editing
 
@@ -28,6 +36,21 @@ Read:
 
 Live repo evidence overrides stale plans and handoffs.
 
+Before each non-trivial slice, name the slice contract:
+
+```text
+Slice:
+Source truth:
+Module/interface changed:
+Behavior/test/benchmark:
+Verification:
+Review checkpoint:
+Commit or handoff checkpoint:
+Stop conditions:
+```
+
+Do not start a slice if the remaining context is not enough to orient, edit, verify, and checkpoint it. Stop with a handoff route instead.
+
 Do not execute a plan that would:
 
 - Invent or change product behavior, scope, domain meaning, compatibility, public API behavior, security, privacy, billing, data-loss, or architecture.
@@ -42,26 +65,68 @@ For source-truth conflicts or missing verification, the final line must be a dir
 
 For missing verification, ask whether to revise the plan to add a check or approve a specific verification path.
 
-## Execute
+## Slice Execution
 
 Work in vertical slices.
 
 For each slice:
 
 - Make only the edits needed for that slice.
+- Keep the slice boundary intact; do not blend future slices into the current one for convenience.
 - Run the planned check or the smallest equivalent check.
 - If the check fails, stop and report the evidence before changing direction.
 - If new evidence invalidates the plan, stop before patching forward.
 
+When TDD is requested by the user, plan, or repo practice, use TDD inside the slice:
+
+```text
+one behavior test or benchmark
+-> minimal implementation
+-> refactor while green
+-> verify the slice
+```
+
+Do not write all tests first and all implementation later. Do not anticipate future slices.
+
 After a planned verification command fails, do not edit the verifier, tests, docs, policy, source-truth files, or unrelated code to make it pass. This is true even when the verifier appears wrong and even when the user said to "fix whatever is needed". A bad verifier is a plan defect; stop, report the failing command and conflicting evidence, and ask whether to revise the plan or change the source truth.
 
 Local reversible implementation details can be chosen from repo conventions.
 
+If per-slice commits are requested, do not continue to the next slice with a verified slice still uncommitted. Route to `commit-work` after review/verification evidence exists.
+
+## Review Checkpoints
+
+Use review where the plan, risk, or slice boundary calls for it. Do not review every slice by habit.
+
+A non-passing review is a phase exit, not an autonomous patch loop.
+
+When a review returns findings during execution:
+
+1. Inspect the relevant code, tests, docs, plan, and source truth.
+2. Classify each material finding: accepted, rejected, question, or needs evidence.
+3. Report the route before editing from that review batch.
+
+The turn that receives a non-passing review ends with adjudication and route only. Do not edit from that review batch in the same turn, even when the user or reviewer says to apply all findings and continue reviewing.
+
+Do not immediately apply findings and request another review in the same loop. Do not treat non-blocking findings or reviewer questions as automatic failure.
+
+If all accepted findings are small, in-scope, and supported by source truth, recommend a bounded fix pass as the next route. Do not perform that fix pass until the user or parent explicitly chooses it after seeing the adjudication. If findings change scope, behavior, source truth, public API, security, privacy, billing, data loss, compatibility, or architecture, route backward before editing.
+
+Three review passes is the hard cap for the same slice/work scope. At pass 3, stop, classify, and diagnose. Do not request a fourth broad review. Use a `diagnose-failure`-style loop to decide whether the issue is shallow research, weak spec, wrong plan slice, ambiguous policy, source-truth conflict, shallow module/interface, implementation bug, or stale reviewer context.
+
+## Backward Edge
+
+If implementation reveals that the plan is wrong, incomplete, or too narrow, re-enter research/spec/plan before continuing.
+
+Do not absorb material scope expansion into execution. New behavior, API shape, security/privacy/billing/data-loss decisions, compatibility changes, or irreversible architecture usually need a revised spec or plan.
+
 ## Completion
 
 Report:
 
 - What changed.
 - What was verified.
+- Review status and any adjudicated findings.
+- Commit or handoff status when relevant.
 - What remains unverified.
 - Any blocked decisions or plan changes needed.

package/plugins/freeflow/skills/execute-plan/references/execution-map.md

@@ -0,0 +1,122 @@
+# Execute Plan Map
+
+Use this when carrying out a multi-slice plan, resuming from handoff, combining TDD with execution, deciding whether to review/commit, or handling failed checks/reviews/scope changes.
+
+The map is a control surface, not ceremony. Small reversible slices can use the compact map only.
+
+## Compact Map
+
+```text
+Orient
+-> Slice contract
+-> Red / Green / Refactor when TDD applies
+-> Verify
+-> Review checkpoint when needed
+-> Commit or handoff checkpoint when needed
+-> Next slice
+
+Any failed check, non-pass review, source conflict, or scope expansion
+-> Classify evidence
+-> Report route
+-> Fix | Diagnose | Research | Spec | Plan | Stop
+```
+
+## Contract Map
+
+Before a non-trivial slice, name:
+
+```text
+Slice: what part of the plan is active
+Source truth: spec/docs/tests/policies/code that own behavior
+Module/interface changed: outside contract affected by this slice
+Behavior/test/benchmark: observable behavior to prove
+Verification: command or check that proves this slice
+Review checkpoint: none | after this slice | after stack | final
+Commit or handoff checkpoint: when rollback/resume needs a snapshot
+Stop conditions: decisions/conflicts/failures that end the slice
+```
+
+A slice contract prevents hidden broadening. If the contract changes materially, stop and route backward.
+
+## Reference Map
+
+```mermaid
+flowchart TD
+  Start([Plan or handoff]) --> Orient[Orient<br/>read plan, source truth, live code]
+  Orient --> Contract[Slice contract<br/>boundary + interface + checks]
+  Contract --> Decision{Can execute safely?}
+
+  Decision -->|yes| Build[Build slice<br/>TDD vertical loop if applicable]
+  Decision -->|missing plan/check/decision| Back[Backward route<br/>research / spec / plan / owner]
+
+  Build --> Verify[Verify planned check]
+  Verify -->|pass| ReviewGate{Review needed now?}
+  Verify -->|fail| Fail[Classify failure evidence]
+
+  ReviewGate -->|no| Checkpoint[Commit/handoff checkpoint if needed]
+  ReviewGate -->|yes| Review[Review checkpoint]
+  Review -->|pass| Checkpoint
+  Review -->|non-pass| ReviewFail[Classify findings<br/>accepted / rejected / question / needs evidence]
+
+  Checkpoint --> Next{Next slice?}
+  Next -->|yes| Orient
+  Next -->|no| Done([Complete / final verify / handoff])
+
+  Fail --> Route{Route}
+  ReviewFail --> Route
+  Route -->|next bounded fix| Build
+  Route -->|unclear or repeated| Diagnose[Diagnose]
+  Route -->|source/scope decision| Back
+  Diagnose --> Back
+```
+
+## Entry Points
+
+Use this map when the current task is:
+
+- start or continue an approved plan;
+- execute the next planned slice;
+- resume from a handoff;
+- run a TDD or benchmark-backed implementation slice;
+- handle a planned verification failure;
+- handle review findings during execution;
+- decide whether to commit after a slice;
+- context is getting low before the next slice;
+- implementation reveals scope or source truth changed.
+
+## Exits
+
+- **Forward** — slice verified; next slice boundary is clear.
+- **Bounded fix** — accepted finding/check failure is small, in-scope, and source-truth-supported.
+- **Commit checkpoint** — verified slice should be committed before continuing.
+- **Handoff checkpoint** — context is too low or continuation state must survive.
+- **Backward** — scope/source truth/review evidence invalidates the plan.
+- **Diagnose** — repeated failure or edge-case patching suggests a deeper problem.
+- **Stop** — blocked on owner decision or plan/spec/source change.
+
+## Review Failure Routing
+
+A non-pass review is not an edit script.
+
+Classify before action:
+
+- **Accepted** — valid, source-truth-supported, and in scope.
+- **Rejected** — stale, unsupported, already resolved, equivalent, or not important.
+- **Question** — needs owner/product/domain/security/API/etc. decision.
+- **Needs evidence** — inspect before deciding.
+
+Route:
+
+- Accepted + bounded + in scope -> recommend one fix pass next; do not perform it in the same turn that received the non-pass review.
+- Non-blocking -> defer or bundle only when safe.
+- Question -> ask; do not implement the answer silently.
+- Needs evidence -> inspect or diagnose before editing.
+- Third review pass -> diagnose; no fourth broad review.
+
+Repeated edge-case findings are a design signal. Ask whether the module/interface is too shallow, the plan slice is wrong, the spec is under-specified, or reviewer context is stale.
+
+## Context And Snapshot Discipline
+
+Do not start a slice if you cannot finish the edit, verification, and checkpoint in the current context window.
+
+When per-slice commits are requested, a verified slice should route to `commit-work` before the next slice. When a commit is not appropriate, make a handoff if future execution depends on the slice state.

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

@@ -58,7 +58,7 @@ Recognize only:
 /workflow reset
 ```
 
-The three mode commands switch mode for the current task, conversation, or host session only. `/workflow reset` clears the current override and returns to `defaultMode`.
+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.
 

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

@@ -0,0 +1,69 @@
+---
+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

@@ -0,0 +1,33 @@
+# 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

@@ -0,0 +1,58 @@
+# 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

@@ -0,0 +1,74 @@
+# 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

@@ -0,0 +1,61 @@
+# 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?
+```