@hassangameryt/freeflow 0.3.0 → 0.5.0

package/skills/simplify-code/references/simplification-patterns.md

@@ -0,0 +1,70 @@
+# Simplification Patterns
+
+Use these as candidate transformations, not automatic rules. Preserve behavior and project conventions.
+
+## Control Flow
+
+- Replace deep nesting with guard clauses when exits are truly equivalent.
+- Collapse duplicate branches into one named path.
+- Replace repeated conditionals on one shape with an explicit model or dispatcher when that removes branching across callers.
+- Name intermediate concepts when a dense expression hides intent.
+- Keep straightforward branching when a lookup, callback table, or polymorphic hierarchy would add more concepts.
+
+## Locality
+
+- Move behavior toward the state or policy it owns.
+- Gather scattered validation, normalization, or failure handling behind one stable seam.
+- Separate orchestration from business rules when each can then be read and tested independently.
+- Reuse a canonical helper instead of maintaining a near-duplicate.
+- Do not centralize unrelated behavior merely because its syntax looks similar.
+
+## Indirection
+
+Question:
+
+- pass-through wrappers;
+- one-use factories and strategy layers;
+- aliases that no longer protect compatibility;
+- helpers whose interface is as complex as their implementation;
+- extension points with no accepted variation;
+- adapters that outlived a migration.
+
+Keep indirection when it hides volatile dependencies, enforces policy, preserves a real compatibility contract, or creates meaningful test and change locality.
+
+## Names And Types
+
+- Rename generic or misleading terms to match domain language.
+- Make invariants explicit at a type or interface boundary when doing so removes downstream checks.
+- Remove casts, optionality, and silent fallbacks only after proving the stronger invariant.
+- Keep comments that explain why, constraints, or non-obvious tradeoffs; remove comments that merely narrate clear code.
+
+## Duplication
+
+Duplication is harmful when one behavior must change in several places and can drift.
+
+Do not extract merely because two snippets look alike. First confirm they represent the same concept and should evolve together.
+
+A small amount of explicit repetition can be simpler than a generalized abstraction with configuration, callbacks, flags, or hidden coupling.
+
+## Dead And Legacy Paths
+
+Before removal, inspect static references, runtime use, generated callers, config, tests, history, and compatibility obligations.
+
+- Truly dead local code may be removed within the agreed simplification boundary.
+- Supported legacy behavior requires deprecation/migration evidence.
+- Historical docs and audit evidence are not dead code.
+- Commented-out code normally belongs in version history, but confirm it is not an intentional operational instruction.
+
+## Before And After Test
+
+Ask:
+
+- Are there fewer concepts and branches?
+- Is ownership clearer?
+- Can behavior be understood through fewer files or transitions?
+- Did error and failure semantics remain visible?
+- Is the public interface smaller or unchanged?
+- Did tests become more behavior-focused rather than more coupled?
+- Would the next likely change touch fewer coordinated locations?
+
+If the answer is mostly no, complexity was relocated rather than reduced.

package/skills/tdd/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: tdd
+description: Use when implementing or changing behavior test-first, fixing a bug with regression evidence, protecting behavior during refactoring, or when a test is difficult to write or starts shaping production design.
+---
+
+# Test-Driven Development
+
+Use one observed failing behavior check to guide the smallest complete implementation for one accepted behavior.
+
+TDD is an execution method inside [Execute Work](../execute-work/SKILL.md). One vertical RED/GREEN/REFACTOR loop is a bounded action, not automatically a Track Work slice. Several accepted behavior loops may remain inside one coherent current slice.
+
+TDD does not define intended behavior. The accepted request, source truth, and user decisions establish what should happen.
+
+## Follow The Behavior Loop
+
+```text
+[Accepted behavior with settled expectation]
+-> [Choose stable seam and independent oracle]
+-> [RED: write and run the smallest behavior check]
+   -> fails for expected missing behavior -> GREEN
+   -> passes immediately -> inspect test, boundary, or existing behavior
+   -> errors for unrelated reason -> correct harness or diagnose
+-> [GREEN: smallest complete implementation]
+-> [Verify focused behavior]
+-> [REFACTOR when useful, without behavior change]
+-> [Verify original path and affected boundary]
+-> [Route]
+   -> another accepted behavior in this slice -> next TDD loop
+   -> coherent extension -> approve and record when needed
+   -> unclear cause or structural pressure -> Workflow
+   -> supported bounded action -> return to Execute Work
+```
+
+Do not write all tests first and all implementation later. Finish, verify, and route one accepted behavior before starting another.
+
+## Use Or Exit Deliberately
+
+Use TDD for accepted behavior changes, bug fixes with a supported cause, consequential logic, and refactors whose behavior needs protection.
+
+Do not force test-first work onto documentation, static content, mechanical formatting, generated output, or a disposable learning prototype whose result is not selected production behavior.
+
+Stop before RED when expected behavior, failure semantics, or a public contract is unsettled. Return the missing direction to [Workflow](../workflow/SKILL.md) rather than encoding a guess as a test.
+
+## Choose The Seam And Oracle
+
+Test observable behavior through the highest stable interface that exercises the real requirement.
+
+A useful seam:
+
+- is used by callers rather than created only for tests;
+- survives internal refactoring;
+- reaches the real behavior or failure path;
+- keeps setup proportionate;
+- can disagree with the implementation.
+
+Derive expected results from source truth, a worked example, protocol contract, or independent calculation—not the implementation algorithm.
+
+Read [Test Design](references/test-design.md) when the test level, oracle, double, rejected state, composed failure, time or concurrency boundary, or legacy seam is unclear.
+
+If testing requires owned internals, duplicated caller choreography, or production hooks used only by tests, return the evidence to Workflow. Use [Design for Depth](../design-for-depth/SKILL.md) only when it establishes design-bearing interface or ownership pressure; do not redesign merely because one test is inconvenient.
+
+## Enforce The Test-First Evidence
+
+- Observe RED failing for the intended missing behavior before changing production code.
+- If RED passes immediately, inspect the test, observing boundary, and existing behavior; do not proceed to GREEN automatically.
+- If RED fails because of syntax, setup, environment, or unrelated behavior, correct the harness or diagnose before implementation.
+- Implement the smallest complete GREEN behavior. Read [Code Practices](../execute-work/references/code-practices.md) while changing code.
+- Refactor only when it improves the result while the focused behavior check remains green.
+- Re-run the original path and smallest affected boundary before returning the supported action and evidence to Execute Work.
+- Do not claim TDD when the check was written after implementation or RED was never observed for the intended reason.
+
+## Keep Tests About Accepted Behavior
+
+Prefer observable outcomes over internal call sequences, real implementations before doubles, independent expected values, descriptive domain names, and one behavior concept per test.
+
+Use fakes, stubs, mocks, or spies only at a boundary where replacement is necessary and the double preserves the fields, effects, invariants, and failure behavior the test needs.
+
+Do not copy the implementation into the expected value, add production methods used only by tests, change a valid test merely to make implementation pass, or treat coverage and test count as proof.
+
+Add an edge-case check only when accepted behavior, observed failure, material safety, or a settled failure contract requires it. If behavior is undefined, return it to Workflow. When related cases keep adding states, flags, setup, or patches, stop the behavior-loop stream and diagnose the shared contract, cause, ownership, or interface.
+
+## Fix Bugs Through The Reported Boundary
+
+First reproduce the reported symptom through the correct seam. A nearby failing path is not the bug.
+
+If no reliable diagnostic loop or supported cause exists, use [Diagnose Failure](../diagnose-failure/SKILL.md) before selecting a production correction. After RED and GREEN, rerun both the minimized regression check and the original unminimized symptom or strongest available observer.
+
+## Stop When Tests Start Designing The System
+
+Return evidence to Workflow when test setup grows faster than behavior coverage, each case requires another public state or fallback, tests protect machinery introduced by earlier patches, the next check requires an unplanned subsystem, or making it pass expands accepted scope.
+
+A green local loop does not prove the global design is right. Diagnose repeated or unexplained failure before redesigning.
+
+## Report
+
+Report the accepted behavior and seam, observed RED result, GREEN implementation, refactor if any, original-path and broader verification, current slice effect, and remaining unverified behavior. Return route-changing evidence rather than silently beginning another behavior or slice.

package/skills/tdd/references/test-design.md

@@ -0,0 +1,96 @@
+# Test Design
+
+Read this when the right test level is unclear, a dependency needs a double, legacy behavior lacks a seam, or test setup starts driving production design.
+
+The goal is confidence in accepted behavior, not maximal isolation or a fixed unit/integration/end-to-end ratio. One TDD behavior loop is a bounded action and may remain inside a larger coherent Track Work slice.
+
+## Choose The Confidence Boundary
+
+Start from the highest stable interface used by callers, then choose the smallest test environment that still exercises its real behavior and failure path:
+
+- **Focused behavior test:** deterministic logic or one stable public operation can prove the requirement.
+- **Integration test:** correctness depends on collaborating components, persistence, serialization, process boundaries, or a real adapter contract.
+- **End-to-end or user-path check:** the requirement is a critical flow whose value depends on the assembled system.
+- **Characterization test:** existing behavior must be observed and protected before a behavior-preserving refactor.
+
+A characterization test records current behavior; it does not make that behavior desired or authoritative. Stop when intended behavior conflicts with source truth or remains user-owned.
+
+A smaller environment is not better when it mocks away the behavior being claimed. A larger environment is not better when its extra machinery adds noise without proving more.
+
+## Build An Independent Oracle
+
+Expected results should come from source truth, a worked example, a protocol contract, or an independently calculated value.
+
+Do not compute the expected value with the same algorithm as the implementation. That produces agreement by construction.
+
+Prefer observable state, outputs, errors, persisted effects, and caller-visible behavior. Assert an interaction only when that interaction is itself part of the accepted contract or the real effect cannot be observed safely at this test boundary.
+
+Keep one behavior concept per test. Multiple assertions are fine when they jointly describe one outcome.
+
+## Rejection And Composed Failures
+
+For authority, persistence, canonical evidence, retry, cancellation, or recovery behavior, identify the dimensions that materially change the outcome:
+
+```text
+entry point
+× valid or invalid input
+× empty or existing accepted state
+× pre-commit or post-commit failure
+× first call or retry/replay
+```
+
+Do not expand this into an exhaustive matrix by habit. Select the smallest rows that can disprove the accepted failure contract. For each selected row, assert:
+
+- returned result;
+- allowed writes or effects;
+- forbidden writes or effects;
+- preservation of prior accepted state;
+- required diagnostic or recovery evidence.
+
+When two accepted conditions can coincide, test the composition rather than assuming isolated cases commute. Examples include cancellation plus integrity failure, successful commit plus failed reconciliation, invalid replacement plus existing valid state, or bounded recovery plus continuation redemption.
+
+## Choose A Test Double
+
+Preference order:
+
+1. **Real implementation:** use when deterministic, fast enough, safe, and controllable.
+2. **Fake:** a lightweight working implementation that preserves the relevant contract.
+3. **Stub:** returns fixed data needed to reach the behavior under test.
+4. **Mock or spy:** records interactions; use sparingly when the interaction itself matters.
+
+Before replacing a dependency, identify:
+
+- the behavior and side effects it owns;
+- which of those effects the test depends on;
+- the boundary being isolated;
+- how the double stays faithful to the real contract and failure modes.
+
+Mock the slow, external, destructive, privileged, or nondeterministic boundary—not a higher-level operation whose behavior the test needs.
+
+Useful double boundaries often include external APIs, email or payment delivery, uncontrollable clocks or randomness, destructive infrastructure, and unavailable remote services. Databases and filesystems may be cheaper and more trustworthy to use for real than to imitate.
+
+A fake or stub must preserve the fields, invariants, errors, and side effects relevant downstream. Validate it against a schema, recorded contract, or shared contract tests when drift would create false confidence.
+
+Do not add public production methods, flags, branches, or lifecycle operations used only by tests. Keep cleanup and fixture construction in test utilities unless production genuinely owns that behavior.
+
+## Time, Randomness, And Concurrency
+
+Prefer an existing controllable boundary for clocks, randomness, scheduling, and external events. Do not expose new public test hooks merely to make assertions convenient.
+
+Avoid arbitrary sleeps as proof. Use observable synchronization, deterministic inputs, bounded eventual assertions, or the real diagnostic loop.
+
+When a race or flaky path cannot be made deterministic, use [Diagnose Failure](../../diagnose-failure/SKILL.md) to raise the reproduction rate and gather evidence before changing production behavior.
+
+## Pressure Signals
+
+Question the seam before adding more test machinery when:
+
+- mock setup is longer or more conditional than the behavior;
+- removing a mock changes what the test is actually proving;
+- many owned internals must be exposed or replaced;
+- doubles duplicate production orchestration;
+- test-only production APIs appear;
+- integration repeatedly fails despite isolated tests passing;
+- fixtures must know internal states, ordering, or cleanup protocols callers should not coordinate.
+
+A real integration test may be simpler than a network of mocks. If the difficulty reflects caller choreography or a shallow interface, use [Design for Depth](../../design-for-depth/SKILL.md) rather than designing production around the test framework.

package/skills/track-work/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: track-work
+description: Use when deciding whether proposed or ongoing work needs a durable Working Record, or when creating, resuming, or updating one to preserve task state across execution, pauses, or context loss.
+---
+
+# Track Work
+
+Decide whether proposed or ongoing work needs a durable Working Record, then maintain selected records without turning them into a transcript, fixed Plan, or authority over live evidence and user decisions. Deciding or reading an existing record is read-only; create or update one only when the effective mode permits mutation.
+
+Use this route to decide whether to wait, return to Workflow, or continue through [Execute Work](../execute-work/SKILL.md):
+
+```text
+[Proposed or ongoing work]
+-> existing Working Record owns it
+   -> read the required reference
+   -> maintain it
+   -> select an authorized slice and route to Execute Work, or wait
+-> no existing Working Record
+   -> would losing context, decisions, evidence, or the next action risk misalignment?
+      -> no
+         -> authorized work in a mutation-permitting mode -> Execute Work
+         -> otherwise -> Workflow or wait
+      -> yes, but a record is unapproved
+         -> recommend a Working Record
+         -> wait
+      -> yes, and a record is approved
+         -> mode permits durable mutation
+            -> read the required reference
+            -> create the record
+            -> first slice already requested or approved
+               -> select the slice
+               -> Execute Work
+            -> only record creation was approved
+               -> Current Slice: None
+               -> wait
+         -> mode does not permit durable mutation
+            -> recommend the required mode change
+            -> wait
+```
+
+## Read The Required Reference
+
+Before creating, resuming, or updating a Working Record, read the complete [Working Record method and schema](references/working-record-schema.md). This skill and its reference form one method. Do not invent fields, states, or transitions from memory; if the reference is unavailable, do not mutate the record.
+
+## Core Contract
+
+- A record preserves current context, one current slice, revisable proposals, durable history, inert Notes, and one next useful action. It is memory; live evidence and user decisions win.
+- `Current understanding` is a present-state summary, not a running task summary or compressed transcript. Replace superseded prose instead of appending completed events.
+- Give detailed facts one schema-owned home. Other sections summarize or point to that owner rather than repeating findings, hashes, commands, or test inventories.
+- Only the user changes task state. Do not infer `Paused`, `Completed`, `Abandoned`, or renewed `Active` state from inactivity, apparent completion, or failure.
+- A **slice** is one bounded piece of learning, delivery, or structural improvement. One slice may span multiple iterations of [Workflow's](../workflow/SKILL.md) Feedback Loop and calls to other owning skills.
+- Record state changes, not every edit or conversation. Apply authorized in-scope steering and reconcile its meaningful final effect when the slice closes.
+- Before work changes the recorded result, scope, authority, evidence boundary, or stop conditions, decide and record whether it extends the current slice or requires a new one.
+- Questions, criticism, and review findings do not authorize changes. Ordinary in-slice feedback is not a checkpoint or history event merely because work pauses for the user.
+- Workflow establishes slice outcomes. Implementation, verification, self-review, or a review report does not end a slice by itself, and review need not Pass.
+- The record may preserve authority sources, decisions, checkpoints, and evidence; it never creates authority or proof.
+
+## Follow The Lifecycle
+
+After reading the required reference:
+
+1. **Create or resume:** use the established task directory, restore task state after context loss, and orient from live evidence.
+2. **Select or wait:** select a slice only when its concrete work is requested or approved. If only record creation is approved, keep `Current Slice` as `None` and wait. When selected, move one proposal into `Current Slice`, assign its chronological `S-` ID, save the write-ahead state, then route to Execute Work.
+3. **Maintain the slice:** keep small steering out of the event history; record accepted extensions before execution; preserve blockers, review routes, and evidence without replacing a coherent slice.
+4. **Close the slice:** move the Workflow-established outcome to History, preserve the original boundary and accepted extensions, rewrite Current Context from the resulting present state, remove completed-event detail already owned by History, and set `Current Slice` to `None`.
+5. **Preserve what matters:** keep task-local decisions, selected checkpoints, evidence pointers, and Notes in their schema-owned sections.
+
+## Context Boundaries
+
+Before an expected compaction, summarization, pause, clear, or transfer, reconcile the record only when task state changed. The boundary itself is not a record event.
+
+After compaction, summarization, resume, clear, or session navigation, read the complete record before the next task action and compare it with the current conversation and live state. Identify the task from current context or inspect and ask rather than guessing. A record written on another conversation branch is memory, not authority.
+
+## Route Or Stop
+
+Use [Discuss](../discuss/SKILL.md) before selecting a slice when a collaborative question could materially change its result, scope, or route.
+
+Use `Blocked` only when a required decision, dependency, capability, evidence source, stop condition, or other unavailable condition prevents safe continuation. Keep the blocked slice current, record what is needed, then stop. General execution authority does not override a stop condition.
+
+When the user requests a separate point-in-time transfer artifact, read [Handoff](../handoff/SKILL.md). Creating a handoff does not replace living Working Record state.
+
+## Check The Record
+
+After every update, silently compare the record with live evidence and the required reference. Correct clear local issues. Remove historical narration from Current Context once its active consequence is captured, and replace duplicated detail with a compact pointer to its owner. Do not create review history or request review merely because the record changed.