@hassangameryt/freeflow 0.2.0 → 0.3.0

package/skills/design-for-depth/references/software-design-philosophy.md

@@ -0,0 +1,219 @@
+# Software Design Philosophy
+
+Use this reference when `design-for-depth` needs deeper reasoning than the active skill can carry.
+
+This is not a checklist to run every time. Pull the idea that changes the next route.
+
+## Core Claim
+
+Good design reduces coordination.
+
+A deep module lets callers, tests, reviewers, and future agents use a small interface to get a lot of behavior. A shallow module makes them learn almost as much as the implementation.
+
+Design work is worthwhile when it hides a decision that would otherwise spread.
+
+## Ousterhout: Complexity, Deep Modules, Strategic Programming
+
+### Complexity
+
+Complexity shows up as:
+
+- too many dependencies;
+- obscurity, where important facts are hard to find;
+- change amplification, where a small behavior change touches many places;
+- cognitive load, where the user of a module must remember too much;
+- unknown unknowns, where a future agent cannot tell what it must inspect.
+
+For Freeflow, complexity is not “many lines.” A single compact helper can be complex if callers must know its quirks. A large implementation can be simple to use if the interface hides the hard parts.
+
+### Deep modules
+
+A deep module has a simple interface and useful behavior behind it.
+
+Deep means:
+
+- callers say what outcome they need;
+- implementation owns sequencing and policy details;
+- tests can verify behavior through the public interface;
+- future changes stay localized;
+- docs and review comments do not need to explain the hidden machinery every time.
+
+Shallow means:
+
+- the interface mirrors the implementation;
+- callers pass many flags and know ordering rules;
+- tests assert internal call sequences;
+- wrappers rename work without hiding decisions;
+- future agents still need to inspect everything to use it safely.
+
+### Strategic vs tactical programming
+
+Tactical programming makes the current patch fit, even if it spreads complexity.
+
+Strategic programming spends a little extra attention to preserve future locality.
+
+Freeflow translation:
+
+- Do not redesign everything up front.
+- Do stop when the local patch clearly makes the next slice, review, or bug fix harder.
+- Route backward when the plan is tactical but the work is becoming structural.
+
+## Parnas: Information Hiding
+
+Parnas's key design move: modules should hide design decisions likely to change.
+
+Do not decompose only by processing steps:
+
+```text
+parse -> validate -> send -> log
+```
+
+when the real likely-changing decision is:
+
+```text
+notification delivery policy: provider choice, retry, fallback, telemetry, failure semantics
+```
+
+A good module hides the unstable decision.
+
+Ask:
+
+- What decision would cause the most edits if it changed?
+- Which callers currently know that decision?
+- Can one module own it?
+- What interface would let callers stop knowing it?
+
+Examples:
+
+- Billing grace period policy should not be spread across webhook handlers, email copy, UI guards, and tests.
+- Notification retry/fallback policy should not be duplicated in each route.
+- Permission semantics should not be separately encoded in frontend, backend, and test setup.
+- Cache invalidation rules should not require every caller to remember freshness knobs.
+
+## Feathers: Seams And Enabling Points
+
+A seam is where behavior can change without editing the surrounding work.
+
+A seam needs an enabling point: the place where a different adapter, test double, probe, or behavior can be supplied.
+
+Freeflow use:
+
+- Use seams to make hard-to-test or hard-to-change behavior tractable.
+- Do not create seams merely because a pattern sounds clean.
+- Prefer seams that match real variation or observability needs.
+
+Questions:
+
+- What behavior needs to vary?
+- Where can that variation enter without editing callers?
+- What enabling point supplies the adapter or behavior?
+- Does the seam protect production code and tests, or only add indirection?
+
+Good seam candidates:
+
+- provider variation: email/SMS/payment/search/storage;
+- environment variation: prod/test/offline/fake implementations;
+- observability variation: probes, clocks, log sinks, metrics;
+- migration variation: old and new implementations behind one interface.
+
+Weak seam candidates:
+
+- one implementation with no likely variation;
+- a seam created only to mock internals while the real interface stays awkward;
+- a factory/registry around every function;
+- an adapter whose interface still exposes provider-specific quirks.
+
+## Ports And Adapters
+
+Ports/adapters protects core behavior from infrastructure details.
+
+Freeflow wording:
+
+- The core owns policy.
+- The adapter owns provider mechanics.
+- The interface between them says what the core needs or provides.
+
+Use this idea when infrastructure details are leaking into product logic.
+
+Examples:
+
+- Stripe event parsing is adapter work; billing policy is core work.
+- Email provider retries are adapter work; user notification policy may be core work.
+- Database query syntax is adapter work; permission semantics are core work.
+- Browser event plumbing is adapter work; user-flow state is core work.
+
+Do not over-apply ports/adapters:
+
+- simple scripts may not need ports;
+- a single stable library call may not need an adapter;
+- wrapping an SDK without hiding policy or provider quirks is often shallow.
+
+## Refactoring Pressure
+
+Design pressure often appears as ordinary implementation pain:
+
+- shotgun surgery;
+- repeated review findings;
+- flaky tests around ordering;
+- many mocks for one behavior;
+- hard-to-explain correctness;
+- one bug fix causing another;
+- “just add this flag everywhere.”
+
+Do not treat all pressure as a command to refactor.
+
+Classify it:
+
+- **Real design pressure:** complexity spread blocks safe progress.
+- **Local mess:** cleanup can happen within current scope.
+- **Deferred deepening:** record the candidate, finish current work.
+- **Owner decision:** deeper change affects product/API/security/compatibility.
+
+## Applying The Philosophy In Freeflow
+
+### In discovery
+
+Use design ideas to ask better questions, not to freeze architecture.
+
+Good questions:
+
+- Which decision is most likely to change?
+- Who should know this rule?
+- What should callers stop coordinating?
+- What future variation is real, not imagined?
+- Which tests should survive a provider or implementation change?
+
+### In specs
+
+Specs name behavior and boundaries. They should not lock in unproven module shapes.
+
+Use:
+
+```text
+Tentative: notification delivery may need one policy-owning module if retries/fallbacks continue spreading.
+Open: whether provider variation is real now or deferred.
+```
+
+not:
+
+```text
+Requirement: implement NotificationDeliveryPortFactoryStrategy.
+```
+
+### In plans
+
+Plan around vertical behavior and interfaces.
+
+A good slice can be verified through the intended interface. If the slice requires broad caller choreography, revise the slice.
+
+### In review
+
+Review design depth by asking whether the diff reduces or increases caller knowledge.
+
+A diff can pass tests and still fail design review if it scatters policy or creates a shallow interface.
+
+### In diagnosis
+
+Repeated failures may indicate that the system is missing a module, seam, or source-truth decision.
+
+Do not keep fixing symptoms when every fix reveals another coordination problem.

package/{plugins/freeflow/skills → skills}/diagnose-failure/SKILL.md

@@ -13,7 +13,9 @@ No production fix without root-cause evidence. A plausible cause is not enough.
 
 Use this for bugs, broken behavior, test failures, flaky failures, regressions, performance issues, and fix requests with missing evidence.
 
-Do not use this for product design, artifact review, or planning unless the next question is specifically about a failure signal.
+Also use it when a workflow loop fails repeatedly: artifact review hits the cap, work review hits the cap, verification keeps failing for different reasons, implementation keeps spawning edge cases, or accepted fixes reveal shared-state or module-shape problems.
+
+Do not use this for product design, artifact review, or planning unless the next question is specifically about a failure signal or failed workflow loop.
 
 ## Hard Stops
 
@@ -32,6 +34,7 @@ Direct `/diagnose-failure`, "explicit permission", "skip the diagnostic loop", "
 
 - For possible loop shapes, read `references/feedback-loop-catalog.md`.
 - For flaky failures or performance regressions, read `references/flaky-and-performance.md`.
+- For repeated workflow failures, edge-case churn, shared-state fixes, or shallow module/interface signals, read `../design-for-depth/SKILL.md`.
 
 ## Feedback Loop
 
@@ -71,6 +74,8 @@ Before changing behavior:
 
 If the failure exposes a product, data-loss, security, privacy, billing, compatibility, or architecture decision, re-enter the interview gate before fixing.
 
+For repeated workflow failures, classify the likely cause before fixing again: thin discovery, wrong scope, premature decisions, source-truth conflict, missing owner decision, bad plan slice, shallow module/interface, implementation bug, stale reviewer context, or inadequate verification loop. Recommend the next route: rediscover, revise spec, revise plan, use `../design-for-depth/SKILL.md`, fix implementation, adjust reviewer context, or stop.
+
 ## Fix
 
 Turn the repro into a regression check when there is a correct seam.

package/{plugins/freeflow/skills/research → skills/discover}/ARTIFACT-DESTINATIONS.md

@@ -1,6 +1,6 @@
 # Artifact Destinations
 
-Use this when a research checkpoint or decision must survive beyond chat.
+Use this when a discovery checkpoint or decision must survive beyond chat.
 
 ## Destination Test
 
@@ -16,12 +16,12 @@ If the owner is unclear, ask before writing.
 
 ## Common Destinations
 
-| Research output | Prefer | Avoid |
+| Discovery 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 |
+| Future implementation path | Plan | Hidden plan inside a discovery note |
+| Evidence summary before requirements settle | Existing discovery, research, or design notes; otherwise 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 |

package/{plugins/freeflow/skills/research → skills/discover}/CHECKPOINTS.md

@@ -1,8 +1,8 @@
-# Research Checkpoints
+# Discovery Checkpoints
 
-A checkpoint is the output of research. It preserves the current understanding and names the next route.
+A checkpoint is the output of discovery. It preserves the current understanding and names the next route.
 
-Research does not end by silently writing a spec, plan, or implementation.
+Discovery does not end by silently writing a spec, plan, or implementation.
 
 ## Chat Or Artifact
 
@@ -17,7 +17,7 @@ Use the narrowest owning artifact:
 - 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.
+- Discovery note: evidence summary that must be reused before requirements are settled.
 
 If no clear destination exists, ask before writing.
 

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/{plugins/freeflow/skills → skills}/execute-plan/SKILL.md

@@ -13,7 +13,7 @@ Move one verified slice at a time. Preserve rollback, reviewability, and user co
 
 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.
+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
 
@@ -22,7 +22,7 @@ Keep research language alive. Read `../research/LANGUAGE.md` when a slice 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 research, spec, or 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
@@ -76,6 +76,7 @@ For each slice:
 - 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:
 
@@ -112,11 +113,11 @@ Do not immediately apply findings and request another review in the same loop. D
 
 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.
+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 research/spec/plan before continuing.
+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.
 

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

@@ -18,7 +18,7 @@ Orient
 Any failed check, non-pass review, source conflict, or scope expansion
 -> Classify evidence
 -> Report route
--> Fix | Diagnose | Research | Spec | Plan | Stop
+-> Fix | Diagnose | Discover | Spec | Plan | Stop
 ```
 
 ## Contract Map
@@ -47,7 +47,7 @@ flowchart TD
   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]
+  Decision -->|missing plan/check/decision| Back[Backward route<br/>discover / spec / plan / owner]
 
   Build --> Verify[Verify planned check]
   Verify -->|pass| ReviewGate{Review needed now?}

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.