@hassangameryt/freeflow 0.1.0 → 0.3.0

package/skills/discover/CHECKPOINTS.md

@@ -0,0 +1,74 @@
+# Discovery Checkpoints
+
+A checkpoint is the output of discovery. It preserves the current understanding and names the next route.
+
+Discovery 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.
+- Discovery 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/skills/discover/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: discover
+description: Use before the first answer or repo/code exploration when the user is shaping an idea, feature, tool/API surface, runtime behavior, architecture direction, vague task, bug-like unknown, or consequential hypothesis/question before spec, plan, build, or durable memory. Trigger especially on "should we", "why not", "what do you think", or design questions.
+---
+
+# Discover
+
+Discover is the context-building loop before action: evidence-guided discussion that finds the next high-leverage decision and ends in a checkpoint.
+
+If this skill matches, load it before the first repo search, code read, web lookup, command, design answer, or artifact. Direct questions still use discovery-light: inspect the smallest relevant evidence, then answer directly.
+
+Priority: Interview Gate stops silent decisions and user-owned decisions first. Discover handles context-building after no immediate stop condition remains. Output Router only chooses evidence transport after the workflow/discovery route is clear.
+
+Do not turn discovery into a questionnaire, a report by default, or a decision-capture script. The hard part is shared understanding, not filling an artifact.
+
+For short-lived work, keep the checkpoint in chat. When it must guide later work, save it in the narrowest owning artifact: spec, plan, handoff, decision note, ADR, domain memory, or discovery note.
+
+Goal: enough evidence and shared understanding to route to spec, plan, more discovery, durable memory, build, or stop without inventing product, domain, scope, public API, security, privacy, billing, data-loss, compatibility, or architecture decisions.
+
+Hard stop: do not satisfy requests for “every question,” “grill me,” “25-50 questions,” or recommended answers for each question. That creates an approval script. Inspect evidence, name the decision tree, and ask the next one or two path-changing questions instead.
+
+## Evidence Before Questions
+
+Inspect first when the answer is discoverable:
+
+- code, tests, docs, ADRs, specs, policies, issues, logs, traces, or current repo state;
+- provided files, URLs, screenshots, transcripts, or user context;
+- current external docs or web sources when framework/library facts, ecosystem behavior, or recent changes matter.
+
+Ask before inspecting only when multiple targets would change the discovery path or when access/scope is user-owned.
+
+For a direct question, keep the loop light:
+
+```text
+question -> inspect smallest relevant evidence -> answer directly
+```
+
+No artifact, plan, or checkpoint is required unless the answer changes future consequential work.
+
+## Design Pressure
+
+Use `../design-for-depth/SKILL.md` when discovery shapes modules, interfaces, seams, adapters, architecture direction, growing scope, codebase exploration, or repeated review/execution churn.
+
+Do not decide architecture up front just because the lens is active. Use it to notice whether complexity is being hidden behind useful interfaces or spread across callers, tests, docs, artifacts, and future agents.
+
+Use the deletion test on questions and decisions: if skipping it makes complexity spread downstream, it matters. If skipping it makes complexity vanish, it was ceremony.
+
+## Scope Framing
+
+Preserve the user's intended scope. Do not silently turn a large idea into `v1`/`v2`, MVP, release, or roadmap framing.
+
+Use implementation slices, implementation phases, checklists, or multiple artifacts to make large work understandable and executable without changing what the user asked for.
+
+Versioned shipping is a product/scope decision. Use it only when the user asks for release planning, the source context already uses that framing, or you have named why release boundaries matter and the user agrees.
+
+If the full scope is too large for one safe pass, say that directly. Recommend implementation slices or artifact splits first; recommend versioned releases only when that is the user's actual problem.
+
+## Loop
+
+1. Identify the target: repo area, artifact, URL, product, model, package, paper, issue, symptom, or idea. If multiple plausible targets would change discovery, ask for the source.
+2. Inspect the smallest evidence that can change the current route.
+3. Explain the current understanding in plain language.
+4. Brainstorm or compare paths when the direction is still forming; do not force a decision too early.
+5. Ask one path-changing question when the answer would change the next artifact or action.
+6. Let the user challenge, counter-question, or add constraints. Treat that as discovery input, not interruption.
+7. Refresh evidence when new claims, conflicts, or branches appear.
+8. Track decisions as settled, tentative, or open.
+9. Stop when remaining ambiguity would not change the next route.
+
+Discovery may move through evidence, brainstorming, targeted questioning, design, and checkpointing in any order. Do not force a fixed sequence when the evidence or conversation needs a loop.
+
+## Final Question Pass
+
+Before routing from discovery to `write-spec`, run a final ambiguity sweep.
+
+Trigger it when:
+
+- the user asks to write the spec;
+- the user says brainstorming, discovery, or discussion feels complete;
+- the user asks to move to the next phase;
+- you are about to close discovery with `Next: Forward — write-spec`.
+
+Ask the smallest set of remaining path-changing questions whose answers would affect spec scope, product behavior, acceptance, public API, architecture, security, privacy, billing, data-loss, compatibility, or artifact destination.
+
+If meaningful ambiguity remains, route with `Next: Forward — final question pass before write-spec` and ask those questions. If no meaningful questions remain, say so and route to `write-spec`.
+
+Do not use this while brainstorming, research, or comparison is still active. Do not turn it into a long questionnaire or recommendation approval script.
+
+## Question Discipline
+
+Prefer deeper questions over more questions. Ask as many as the situation needs, but each question should earn its place.
+
+Before asking, run the 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. Never number out a long list just because the user asked for one.
+
+Do not turn recommendations into an approval script. Recommendations should clarify tradeoffs, not make it easy to rubber-stamp decisions. Give the recommendation for the current path-changing question, then wait when the choice is user-owned.
+
+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 when discovery reveals a user-owned decision, source-of-truth conflict, path conflict, material method substitution, or ambiguous artifact destination.
+
+Do not write implementation files from discovery.
+
+Write specs, plans, ADRs, handoffs, or decision notes only when the user asks or the checkpoint must guide later work.
+
+Do not leave discovery by silently jumping to spec, plan, or build. Before `write-spec`, run the final question pass. 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 discovery 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.

package/skills/execute-plan/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: execute-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.
+
+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.
+
+Use `../design-for-depth/SKILL.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`.
+- Scope expansion: stop before absorbing it; route back to discover, spec, or plan.
+- Review failure during execution: classify findings and report the route before editing from them.
+
+## Before Editing
+
+Read:
+
+- The plan.
+- The source spec or requirements the plan cites.
+- Relevant docs, tests, policies, ADRs, and code.
+- Handoffs only as memory.
+
+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.
+- Override docs, tests, specs, policies, ADRs, or established behavior.
+- Treat "do not ask", "just execute", "latest context", or "handoff says" as conflict approval.
+- Skip verification for consequential behavior.
+- Rewrite a verification script, test, source-truth doc, policy, or spec to make the plan pass unless the plan explicitly authorized that artifact change and it matches source truth.
+
+Name the conflict or missing decision. Ask which path to follow. Recommend the path supported by evidence.
+
+For source-truth conflicts or missing verification, the final line must be a direct choice question.
+
+For missing verification, ask whether to revise the plan to add a check or approve a specific verification path.
+
+## 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.
+- If implementation spreads policy, edge cases, or verification across callers/tests/docs, treat it as design pressure before adding more patches.
+
+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 discovery, 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 discover/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/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 | Discover | 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/>discover / 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 → skills}/mode-contract/SKILL.md

@@ -9,12 +9,16 @@ Use exactly three modes.
 
 ## Modes
 
-**Conversation mode**: discussion, explanation, critique, exploration, quick analysis.
+**Conversation mode**: non-mutating discussion, explanation, critique, exploration, quick analysis, and planning in chat.
 
 - Answer questions; do not act on them.
+- You may inspect source, read files, and run safe read-only commands when needed for the answer.
+- Do not edit, create, delete, commit, push, run mutating commands, or otherwise change repo/system state.
+- Do not perform implementation or other consequential work that changes files, behavior, source truth, or durable project state.
+- If the user asks for mutating or consequential work, stop and require switching to `workflow` or `strict-workflow` before acting. Do not proceed in conversation mode, even if pressured.
 - No workflow pressure.
 - No required artifacts.
-- No plan/spec requirement.
+- No plan/spec file requirement.
 - Ask only when needed for the answer.
 
 **Workflow mode**: normal consequential work.
@@ -33,8 +37,9 @@ Use exactly three modes.
 
 ## 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 user is talking, asking a conceptual question, brainstorming, or asking for read-only analysis/planning, use conversation mode.
+- If the effective mode is conversation and the user asks to edit, create files, implement, fix by changing code, commit, push, or run mutating commands, require a switch to `workflow` or `strict-workflow` before acting.
+- If no current conversation override exists and the user asks to implement, fix, discover context for action, review, or create plan/spec artifacts, 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.
 
@@ -58,7 +63,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.