@hassangameryt/freeflow 0.1.0 → 0.3.0

package/{plugins/freeflow/skills → skills}/commit-work/references/staging-decisions.md

@@ -1,17 +1,17 @@
 # Staging Decisions
 
-Use this for mixed staged sets, generated files, durable docs, or broad commit pressure.
+Use this for mixed staged sets, generated files, durable docs, or broad commit/push pressure.
 
 ## Evidence First
 
-Read staged, unstaged, and untracked state before deciding:
+Read staged, unstaged, and untracked state before deciding what to commit or push:
 
 - `git status --short`
 - `git diff --cached`
 - `git diff`
 - `git ls-files --others --exclude-standard`
 
-Diff evidence beats "staged means ready", "commit everything", and "include all leftovers".
+Diff evidence beats "staged means ready", "commit everything", "push all changes", and "include all leftovers".
 
 ## Mixed Staged Sets
 

package/skills/design-for-depth/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: design-for-depth
+description: Use when shaping, reviewing, implementing, or diagnosing work where module/interface/seam choices affect complexity, locality, testability, future change, or repeated edge-case churn. Use for architecture direction, growing scope, shallow modules, bad seams, broad refactors, and review loops that keep finding new edge cases.
+---
+
+# Design For Depth
+
+Use this as a lens, not a phase.
+
+Core rule: if complexity is spreading across callers, tests, docs, artifacts, or review comments, stop and classify the design pressure before patching forward.
+
+Goal: hide useful complexity behind stable interfaces so future callers, tests, reviewers, and agents coordinate less.
+
+Do not add architecture ceremony when the next action is small, local, and reversible. Do not use architecture language to hide product or policy decisions.
+
+## Load When Needed
+
+Read `references/software-design-philosophy.md` when shaping architecture direction, reviewing a design-heavy artifact, or diagnosing repeated design failure.
+
+Read `references/design-pressure-signals.md` when reviewing code/work for shallow modules, scattered policy, edge-case churn, or refactor candidates.
+
+Do not load references for every small design question. The active skill should be enough for routine routing.
+
+## Language
+
+Use these terms consistently:
+
+- **Module** — anything with an interface and implementation: function, class, package, subsystem, workflow slice.
+- **Interface** — everything a caller, user, test, or future agent must know: types, invariants, ordering, errors, configuration, performance, side effects, and policy context.
+- **Implementation** — details hidden behind the interface.
+- **Depth** — leverage at the interface. Deep modules hide useful behavior behind a smaller interface.
+- **Shallow module** — interface is nearly as complex as implementation, or callers coordinate details the module should own.
+- **Seam** — where behavior, ownership, or variation can change without editing surrounding work.
+- **Adapter** — a concrete thing satisfying an interface at a seam.
+- **Locality** — changes, bugs, decisions, and verification stay near one module.
+- **Leverage** — future work gets more behavior from less interface knowledge.
+
+Avoid using “architecture” as a vague quality claim. Name the module, interface, hidden decision, seam, adapter, locality, or leverage.
+
+## Signals
+
+Use this lens when evidence shows:
+
+- one concept requires many unrelated file, test, doc, or reviewer-comment changes;
+- callers know ordering, flags, retries, cleanup, cache, auth, billing, migration, privacy, permissions, or compatibility policy;
+- tests reach past the interface to assert normal behavior;
+- review findings become a stream of edge-case patches;
+- the same conditional or policy appears in multiple callers;
+- a module is mostly pass-through naming around another module;
+- a seam exists only for theoretical future variation;
+- a spec or plan encodes detailed implementation guesses before evidence exists;
+- the agent can only explain correctness by listing coordinated steps across modules.
+
+Do not use this lens just because work is “important.” Use it when interface shape changes the next action.
+
+## Tests
+
+Use the smallest test that changes the route:
+
+- **Deletion test:** if deleting the module makes complexity vanish, it may be pass-through ceremony. If complexity reappears across callers, tests, docs, or review comments, it was earning its keep.
+- **Interface test surface:** callers and tests should exercise normal behavior through the same interface. If tests bypass it, mock internals, or duplicate setup, the module shape may be wrong.
+- **Variation test:** one adapter is a hypothetical seam. Two adapters, a real test double, or a known upcoming variation justify a seam better.
+- **Locality test:** one behavior change should not scatter policy, error handling, retries, logging, auth, billing, compatibility, docs, and tests across unrelated places.
+- **Decision-hiding test:** design decisions likely to change should live behind modules, not in every caller or artifact.
+- **Obscurity test:** if a fresh agent must read many files to learn a simple rule, the design may be obscure even if each file is small.
+
+## Route
+
+If the current direction spreads complexity, do not patch forward silently.
+
+Classify the pressure:
+
+- **Local fix:** same interface, complexity stays hidden; continue in the current phase.
+- **Plan defect:** slice boundary, check, or implementation path is wrong; revise the plan.
+- **Spec gap:** behavior, scope, or acceptance is unclear; revise the spec or return to discovery.
+- **Owner decision:** public API, compatibility, security, privacy, billing, data-loss, permissions, migration, or hard-to-reverse architecture changes; use the interview gate.
+- **Refactor candidate:** current behavior is valid but the module is shallow; propose a bounded deepening path before editing.
+- **Stop/defer:** design pressure is real but not worth solving in this scope; record or defer it explicitly.
+
+## Non-Goals
+
+Do not:
+
+- introduce abstractions for imagined future variation;
+- hide product or policy decisions inside architecture wording;
+- rewrite source truth to make a design cleaner;
+- turn every feature into upfront architecture design;
+- broaden a narrow fix into a refactor without user approval;
+- treat line count, file count, indirection, or pattern names as proof of quality;
+- claim a design is better without evidence from code, tests, review, usage, or an explicit owner decision.

package/skills/design-for-depth/references/design-pressure-signals.md

@@ -0,0 +1,265 @@
+# Design Pressure Signals
+
+Use this reference when reviewing code, artifacts, or work for shallow modules and complexity spread.
+
+The goal is not to find every smell. The goal is to notice pressure that changes the next route.
+
+## Quick Classifier
+
+Ask:
+
+1. What is the module?
+2. What is the interface?
+3. What details are callers forced to know?
+4. What decision is likely to change?
+5. Where would that decision be localized?
+6. Would solving this now fit the approved scope?
+
+Then classify:
+
+- **Continue:** no design pressure that changes the next action.
+- **Local fix:** improve within current module/interface.
+- **Plan revision:** slice boundary or verification path is wrong.
+- **Spec/discovery:** behavior, scope, or acceptance is unclear.
+- **Owner decision:** public API, compatibility, security, privacy, billing, data loss, permissions, migration, or hard-to-reverse architecture.
+- **Deferred deepening:** real design pressure, but not worth solving in this scope.
+
+## Signals And What They Usually Mean
+
+### Shotgun Surgery
+
+Signal: one concept requires many unrelated edits.
+
+Examples:
+
+- retry policy added to every route;
+- permission check copied into API, UI, and job worker;
+- billing grace-period logic repeated in webhook, email, and dashboard;
+- cache freshness flags threaded through callers.
+
+Likely issue: a likely-changing decision is not hidden behind a module.
+
+Route:
+
+- If behavior/scope is unsettled: discovery or spec.
+- If behavior is settled but slice spreads edits: plan revision or refactor candidate.
+
+### Caller Choreography
+
+Signal: callers must perform steps in the right order.
+
+Examples:
+
+```text
+open connection -> set retry -> register cleanup -> call provider -> translate error -> log metric
+```
+
+Likely issue: interface exposes implementation sequence.
+
+Better interface asks for outcome:
+
+```text
+deliverNotification(invitation)
+```
+
+while the module owns retry, fallback, logging, cleanup, and provider errors.
+
+### Scattered Policy
+
+Signal: product or operational rules appear in many places.
+
+Examples:
+
+- billing downgrade timing in UI, webhook, worker, and tests;
+- notification fallback rules in every route;
+- authorization rules in frontend and backend separately;
+- migration compatibility gates inside individual callers.
+
+Likely issue: policy is not localized.
+
+Stop if changing it would alter product, security, privacy, billing, permissions, public API, compatibility, or data-loss behavior.
+
+### Test Knows Too Much
+
+Signal: tests assert implementation sequencing instead of behavior.
+
+Examples:
+
+- tests assert `sendEmail` then `logFailure` then `sendSms` in every route;
+- tests mock five helpers to verify one user-visible behavior;
+- tests duplicate retry counts and provider error types;
+- tests need private methods or internal state.
+
+Likely issue: the production interface is not the right test seam.
+
+Do not automatically add mocks. Ask whether the module interface should own the behavior.
+
+### Edge-Case Patch Stream
+
+Signal: each review pass finds another special case.
+
+Examples:
+
+- “also handle null phone”; then “also handle email bounce”; then “also handle duplicate invite”; then “also handle retry telemetry.”
+
+Likely issue: review is exposing missing behavior ownership, not isolated bugs.
+
+Route:
+
+- classify findings;
+- stop at review cap;
+- diagnose whether discovery, spec, plan, source truth, module shape, or reviewer context is wrong.
+
+### Pass-Through Wrapper
+
+Signal: a module mostly renames another call.
+
+Example:
+
+```ts
+function sendTeamInviteEmail(email, subject, options) {
+  return sendEmail(email, subject, options);
+}
+```
+
+Likely issue: shallow wrapper.
+
+Options:
+
+- delete it if it hides nothing;
+- deepen it by moving real policy behind it;
+- keep it only if it expresses a stable domain interface that will soon hide behavior.
+
+### Leaky Interface
+
+Signal: callers know provider/database/cache internals.
+
+Examples:
+
+- callers catch Stripe-specific errors;
+- UI code knows database enum transitions;
+- API callers pass cache invalidation flags;
+- tests assert internal queue names.
+
+Likely issue: implementation detail leaked through interface.
+
+Route to design if leakage blocks safe change or verification.
+
+### God Module
+
+Signal: one file owns unrelated responsibilities.
+
+Examples:
+
+- route file validates input, applies policy, calls providers, logs metrics, and formats UI copy;
+- workflow module owns routing, vaulting, parsing, rendering, and config mutation.
+
+Likely issue: missing internal modules or seams.
+
+Do not split by file type alone. Split around hidden decisions and interfaces.
+
+### Speculative Seam
+
+Signal: interface/adapters/factory exist for only imagined future variation.
+
+Examples:
+
+- `PaymentProviderAdapterFactoryRegistry` when only Stripe exists and no migration is planned;
+- strategies for every small formatting function;
+- generic repository around a single simple query.
+
+Likely issue: indirection without leverage.
+
+Use the variation test: one adapter is hypothetical; two adapters or known upcoming variation justify a seam better.
+
+### Premature Artifact Detail
+
+Signal: spec or plan chooses exact classes, factories, tables, or algorithms before evidence exists.
+
+Likely issue: artifact is hiding uncertainty as implementation detail.
+
+Better:
+
+```text
+Tentative: likely need a policy-owning module if retry/fallback rules spread.
+Open: whether provider variation is real in this scope.
+Stop: revisit plan if slice requires touching every caller.
+```
+
+## Before / After Examples
+
+### Notification Retry
+
+Bad direction:
+
+```text
+Add retryCount to each route that sends notifications.
+```
+
+Pressure:
+
+- callers know retry policy;
+- fallback and telemetry are duplicated;
+- tests assert provider sequencing;
+- adding another provider touches every caller.
+
+Better direction:
+
+```text
+Introduce a notification delivery module whose interface accepts the notification intent and owns retry, fallback, provider errors, and telemetry.
+```
+
+Still ask owner decisions before changing user-visible delivery semantics.
+
+### Billing Grace Period
+
+Bad direction:
+
+```text
+Patch webhook to downgrade immediately, update email text, adjust dashboard copy.
+```
+
+Pressure:
+
+- billing policy spread across systems;
+- likely source-truth conflict with docs/tests;
+- user-owned billing behavior.
+
+Better direction:
+
+```text
+Stop at interview gate. Decide billing policy first. Then localize policy behind a billing-state transition module if implementation spreads.
+```
+
+### Cache Freshness
+
+Bad direction:
+
+```text
+Thread forceRefresh through every caller.
+```
+
+Pressure:
+
+- callers know cache invalidation policy;
+- tests must set timing flags;
+- source truth may allow caching.
+
+Better direction:
+
+```text
+Discover expected freshness boundary. If source truth supports it, hide invalidation/freshness rules behind a cache-aware read interface.
+```
+
+## False Positives
+
+Do not overreact when:
+
+- a small repeated pattern is stable and local;
+- a one-off script does not need long-term depth;
+- a wrapper exists for public compatibility;
+- broad edits are mechanical and source-backed;
+- tests inspect internals only for an internal module whose interface is intentionally internal;
+- deeper design would expand scope beyond the user's goal.
+
+When in doubt, classify as deferred design pressure rather than silently refactoring.

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/skills/discover/ARTIFACT-DESTINATIONS.md

@@ -0,0 +1,58 @@
+# Artifact Destinations
+
+Use this when a discovery 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
+
+| 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 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 |
+| 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.