@hassangameryt/freeflow 0.2.0 → 0.4.0

package/skills/bypass/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: bypass
+description: Use when the user explicitly asks to skip or reduce workflow steps for the next action or current task.
+---
+
+# Bypass
+
+Skip optional ceremony, not authority, judgment, safety, or evidence.
+
+Bypass changes the workflow method within an already accepted action. It does not authorize work, expand scope, switch mode, resolve a user-owned decision, override source truth, or create host permissions.
+
+## Establish The Boundary
+
+Before using bypass, identify:
+
+- the accepted action it applies to;
+- the named optional step, or whether the user selected `next` or `task` scope;
+- the effective mode;
+- the evidence and checkpoints that still govern the action.
+
+A bare `/bypass` means `/bypass next`. If no accepted action exists, return to [Workflow](../workflow/SKILL.md); do not treat bypass itself as implementation authorization.
+
+Bypass never changes mode. In `conversation`, remain read-only and use [Mode Contract](../mode-contract/SKILL.md) before mutation. In `workflow` or `strict-workflow`, keep the active mode's decision and evidence pressure.
+
+## Skip Only Optional Pressure
+
+A bypass may remove a step that does not protect accepted intent, material risk, required evidence, or a selected checkpoint, such as:
+
+- an unnecessary Spec or Plan;
+- extended questioning whose answer would not change the action;
+- an artifact created only for ceremony;
+- an optional checkpoint or extra review with no remaining risk purpose.
+
+Do not infer that a named artifact or review is optional. Inspect why it exists first.
+
+## Preserve Non-Bypassable Boundaries
+
+A generic or scoped bypass does not remove:
+
+- the user's authority over product behavior, scope, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migrations, deployment, or another hard-to-reverse outcome;
+- a conflict with code, tests, docs, policies, requirements, accepted behavior, or another source of truth;
+- host safety, sandbox, permission, or approval controls;
+- proportionate verification and supported self-review before a factual or completion claim;
+- an accepted Spec, Plan, selected checkpoint, required artifact review, selected independent review, or other accepted completion boundary;
+- a stop condition or evidence that invalidates the current route.
+
+Material risk still needs the decisions and evidence that address that risk. A domain label alone does not require ceremony, but bypass cannot erase an observed risk.
+
+If the user wants to change an accepted requirement, evidence boundary, or selected review, treat that as a route change rather than bypass. Use [Decision Gate](../decision-gate/SKILL.md) when one user-owned choice or source conflict blocks progress; use Workflow when the route itself must change.
+
+## Apply The Selected Scope
+
+### Next
+
+`/bypass next` skips one identified optional step for the current accepted action. Re-check the route immediately after skipping it.
+
+If that step was the only remaining optional pressure, complete the bounded action and verify it. The bypass is then spent. It also expires if the action changes, another gate appears, or the route stops.
+
+### Task
+
+`/bypass task` reduces optional workflow pressure for the current accepted task. The task is the accepted request or active Working Record scope—not the repository, session, or future related work. If that boundary is unclear, ask before applying task scope.
+
+The task scope ends at completion, abandonment, material scope change, or explicit withdrawal. Reassess each new risk, conflict, checkpoint, and completion claim inside that scope.
+
+When an existing Working Record is already authorized for maintenance and task-scoped bypass must survive context loss, record its exact source, scope, and expiry through [Track Work](../track-work/SKILL.md). The record preserves the instruction; it does not broaden it. Without durable task memory, do not claim bypass survives context loss.
+
+Never convert either scope into a permanent, repository-wide, or cross-task bypass.
+
+## Act Or Stop
+
+When the bypass is valid:
+
+1. skip only the selected optional pressure;
+2. perform only the separately authorized bounded action;
+3. gather the same proportionate evidence the outcome requires;
+4. report what was skipped, the result, and whether the bypass is spent or still task-scoped.
+
+When a boundary remains:
+
+1. do not perform the blocked action;
+2. name the boundary bypass cannot remove;
+3. route to the owning mode, decision, discussion, or workflow step.

package/skills/commit-work/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: commit-work
+description: Use when committing work, including selecting and staging the intended changes, creating and verifying the commit, or explicitly pushing committed work.
+---
+
+# Commit Work
+
+Commit an intended, coherent checkpoint. A commit preserves rollback and provenance; it does not prove correctness or approve the next route.
+
+This skill covers commits and simple pushes, not branch integration, release, or deployment orchestration. Use [Finish Branch](../finish-branch/SKILL.md), [Release Work](../release-work/SKILL.md), or [Launch Work](../launch-work/SKILL.md) for those later jobs.
+
+A local commit is authorized by an explicit user request, a checkpoint whose local-commit authority was explicitly granted through a user-approved Plan, or a checkpoint explicitly approved during discussion. A Working Record may preserve that authorization but cannot create it. Plan acceptance does not authorize push, integration, migration, deprecation, release, or launch.
+
+A planned checkpoint remains conditional on live state. Do not force it when its intended outcome, evidence, review status, or change boundary no longer holds; return the deviation to [Workflow](../workflow/SKILL.md).
+
+A commit does not select or trigger independent review. Complete only review selected by Workflow, an approved Plan, or repository policy. Commit Work does not adjudicate findings or authorize corrections or follow-up review. Fresh verification is required for the claim the commit represents.
+
+Read [staging decisions](references/staging-decisions.md) when changes are mixed, generated files or durable docs appear, existing staged state is unclear, or broad commit/push language conflicts with diff evidence.
+
+## Route Check
+
+Before staging, confirm:
+
+- the slice or work package has one coherent outcome;
+- source truth and owner decisions still support it;
+- fresh evidence supports the claim represented by the commit, or an explicitly requested preservation checkpoint names its incomplete claim honestly;
+- any selected review has ended, its adjudicated status is known, and Workflow supports the checkpoint route;
+- no unresolved blocker, required evidence gap, or route-changing assumption is hidden by the checkpoint claim;
+- the checkpoint remains authorized and useful for rollback, integration, handoff, or repository workflow.
+
+When review or evidence leaves unresolved work, return it to Workflow rather than deciding readiness here. If the user explicitly requests a preservation checkpoint of incomplete, unverified, blocked, or inconclusive work, label that state honestly and include only what is safe and useful to preserve. The commit does not authorize crossing the unresolved boundary.
+
+## Inspect
+
+Inspect before staging or committing:
+
+```bash
+git status --short
+git diff
+git diff --cached
+git ls-files --others --exclude-standard
+```
+
+Diff evidence beats “staged,” “commit everything,” “push all,” “exactly as-is,” or “do not leave leftovers.” Treat unrelated changes as user-owned until proven otherwise.
+
+## Stage Narrowly
+
+Stage explicit paths or hunks that implement the coherent checkpoint.
+
+Avoid `git add .` and `git add -A` when unrelated, unreviewed, generated, sensitive, or user-owned changes are present.
+
+Verify existing staged changes rather than inheriting them blindly. Do not unstage, rearrange, discard, or overwrite user-owned changes merely to manufacture a clean commit without permission.
+
+## Stop
+
+Stop before commit or push when:
+
+- included changes are unrelated, unreviewed when review is required, or outside the accepted outcome;
+- staged and unstaged edits make commit ownership ambiguous;
+- logs, debug output, secrets, generated artifacts, lockfiles, or formatter churn lack evidence they belong;
+- durable docs and implementation describe different behavior or authority;
+- verification failed or proves less than the commit message would claim;
+- the commit mixes separable concerns in a way that harms review, diagnosis, or rollback;
+- product, security, privacy, billing, permissions, data-loss, compatibility, public API, migration, or architecture behavior changed without an explicit decision.
+
+Use [Decision Gate](../decision-gate/SKILL.md) when the safe commit path depends on an owner or source-truth decision. If a clean narrow commit is possible without touching unrelated work, prefer it and report what remains.
+
+## Commit Shape
+
+Keep the checkpoint independently understandable and revertible.
+
+Use the repo's established message style. Otherwise use a short imperative subject. Add a body only when source context, tradeoffs, residual risk, or the reason for the checkpoint would not be clear from the diff.
+
+Reference specs, plans, ADRs, issues, or decisions only when they materially explain the change. Do not invent metadata conventions.
+
+A learning-slice commit must distinguish diagnostic or exploratory output from production behavior. A deepening commit should not silently change behavior. A delivery commit should name the behavior it adds or changes.
+
+## Push
+
+Push only inspected commits when the user request and branch state make the route clear.
+
+Before pushing, inspect branch, upstream, remote, and ahead/behind state. Stop before protected/shared branches, upstream changes, force pushes, remote-history rewrites, divergence, or release/PR decisions that were not explicitly requested.
+
+Use `--force-with-lease` only for an intended rewrite of the user's own branch with explicit approval and supporting branch evidence.
+
+## Verify The Checkpoint
+
+After commit or push, inspect:
+
+```bash
+git show --stat --oneline --name-only HEAD
+git status --branch --short
+```
+
+Report:
+
+- commit SHA and subject;
+- what the checkpoint contains;
+- verification and review evidence;
+- push result when applicable;
+- remaining staged, unstaged, untracked, unpushed, or unverified work;
+- recommended next route.
+
+When a Working Record exists, use [Track Work](../track-work/SKILL.md) to record the commit SHA, checkpoint result, remaining state, and next useful action.
+
+Do not continue to the next slice, push, or integrate merely because the commit succeeded. Return the result to [Workflow](../workflow/SKILL.md), or use [Finish Branch](../finish-branch/SKILL.md) when branch closeout is selected.

package/skills/commit-work/references/staging-decisions.md

@@ -0,0 +1,73 @@
+# Staging Decisions
+
+Use this when staged state is mixed, generated files or durable docs appear, broad commit/push language conflicts with the diff, or producing a narrow checkpoint may touch user-owned work.
+
+## Evidence First
+
+Inspect:
+
+- `git status --short`
+- `git diff --cached`
+- `git diff`
+- `git ls-files --others --exclude-standard`
+
+Diff evidence beats “staged means ready,” “commit everything,” “push all changes,” and “include every leftover.”
+
+## Classify Paths
+
+For each changed path, classify:
+
+- **Checkpoint:** directly implements or proves the intended slice.
+- **Required generated output:** repo convention or task requires it and its generator is known.
+- **Durable artifact:** Spec, policy, ADR, or Plan that belongs to the same accepted checkpoint while retaining its own authority and lifecycle.
+- **Durable continuation memory:** Working Record or Handoff describing the same checkpoint without becoming authority over live evidence.
+- **Related but separable:** useful work that should remain outside this checkpoint.
+- **Unrelated or user-owned:** not part of the current outcome.
+- **Sensitive or unsafe:** secrets, private data, debug output, destructive state, or unclear generated content.
+
+Do not infer ownership from staging state.
+
+## Narrow Checkpoint
+
+A narrow commit is safe when:
+
+- an explicit request, user-approved Plan, or explicitly approved discussion authorizes the local checkpoint;
+- its outcome and source requirement are clear;
+- every included path belongs to that outcome;
+- verification supports the claim represented by the commit;
+- selected review status is known and [Workflow](../../workflow/SKILL.md) supports the checkpoint route;
+- excluded changes can remain untouched without loss;
+- the final report names remaining dirty state.
+
+Plan approval does not prove that every current path belongs. Stage explicit paths or hunks. If narrowing requires unstaging, rearranging, regenerating, or modifying user-owned work, stop unless the user or repo workflow already authorized that operation.
+
+## Mixed Concerns
+
+Separate changes when combining them harms review, diagnosis, or rollback, especially:
+
+- behavior plus unrelated refactoring;
+- source code plus local debug output;
+- generated artifacts plus unexplained hand edits;
+- durable source-truth changes plus implementation that has not been confirmed;
+- security, privacy, billing, permissions, migration, data-loss, compatibility, or public API behavior plus unrelated work;
+- learning-slice evidence plus production changes that have not passed promotion criteria.
+
+A single coherent behavior with its tests and matching docs may belong together.
+
+## Generated Files
+
+Commit generated files, snapshots, lockfiles, build outputs, or formatter changes only when the task or repo convention makes them part of the checkpoint.
+
+Name the generator or command that produced required output. Do not hand-edit generated files unless the repo explicitly expects it.
+
+## Durable Artifacts
+
+Specs, policies, and ADRs may govern behavior. Plans preserve approved strategy; Working Records and Handoffs preserve memory. Include any of them with code only when they belong to the same coherent checkpoint and their own maintenance rules support the change.
+
+Do not revise a durable artifact merely to make the commit appear coherent. Return a material inconsistency to [Workflow](../../workflow/SKILL.md); use [Decision Gate](../../decision-gate/SKILL.md) when one user-owned choice or source conflict blocks the checkpoint.
+
+## Existing Staged State
+
+Existing staged changes may belong to another workflow. Inspect them, but do not silently unstage, amend, discard, or absorb them.
+
+When ownership remains ambiguous, present the smallest safe staging options and ask which checkpoint the user wants.

package/skills/decision-gate/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: decision-gate
+description: Use when proceeding would silently choose for the user, conflict with existing code, tests, docs, or requirements, or take a materially different path from what was requested or agreed.
+---
+
+# Decision Gate
+
+Stop before making a decision that belongs to the user or quietly changing the agreed path.
+
+The [Interaction Contract](../../runtime/interaction-contract.md) governs whether the user is asking, proposing, reasoning, or authorizing action. Decision Gate begins only after one blocking choice or conflict is clear. When the problem or alternatives still need broader exploration, read [Discuss](../discuss/SKILL.md) instead.
+
+## Stop Here
+
+Use the gate when:
+
+- the user must choose product behavior, scope, priorities, public interfaces, compatibility, permissions, security, privacy, billing, data-loss behavior, migration direction, or another hard-to-reverse outcome;
+- the request conflicts with existing code, tests, docs, policies, requirements, or established behavior;
+- the proposed action would materially change what was requested or agreed, including its evidence quality, risk, cost, persistence, or user-visible result;
+- new evidence exposes one known user choice or source conflict that must be resolved before proceeding.
+
+Do not use the gate for facts that can be inspected, harmless local choices, or reversible implementation details that preserve the accepted outcome.
+
+## Inspect Before Asking
+
+Inspect code, tests, docs, policies, logs, repository state, or current external sources when they can answer the factual part of the problem.
+
+Ask the user only for a choice that remains theirs. If you cannot state the decision and meaningful alternatives clearly, the option space is not ready for a gate; use Discuss.
+
+## Ask One Direct Question
+
+State:
+
+1. what was requested or previously agreed;
+2. the conflicting evidence, missing choice, or materially different path;
+3. why it changes the next action;
+4. the meaningful options and tradeoffs;
+5. a recommendation when evidence supports one;
+6. one direct question that resolves the block.
+
+Then stop. Do not perform the blocked action in the same response.
+
+Urgency, approval to continue, reviewer confidence, or existing practice does not resolve an unnamed decision or conflict.
+
+## Exit
+
+Exit when the choice is explicit, the conflict is resolved, and remaining uncertainty would not change the next safe action.
+
+Preserve the decision accurately for the work that depends on it. Do not broaden the decision or treat it as approval for a different path.

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

@@ -0,0 +1,106 @@
+---
+name: design-for-depth
+description: Use when working with software design—especially boundaries, interfaces, ownership, state, and failure behavior.
+---
+
+# Design For Depth
+
+Reduce coordination by hiding internal decisions behind small, stable, outcome-level interfaces.
+
+A **module** is anything with an interface and implementation. A **caller** is anything that uses or coordinates the module through its interface, such as application code, another service, a script, a test, a tool, or an agent. Its **interface** is every fact callers must know to use it correctly: inputs, decisions, states, ordering, errors, side effects, configuration, timing, and failure behavior. **Depth** is useful behavior and hidden complexity per unit of interface knowledge.
+
+A **seam** is a boundary where behavior, dependencies, or observation can change without forcing surrounding edits. An **adapter** is a concrete implementation supplied at that seam. Add a seam for real variation or a required testing or observation boundary—not imagined flexibility.
+
+Use this as a compositional lens, not a mandatory phase or permission to refactor.
+
+## Compose The Lens Early
+
+Read this during design-bearing discussion before core boundaries settle. Use it while writing a Spec or Plan when ownership, interfaces, state, or failure behavior shapes the contract. Keep it available during execution, TDD, and review when the work must preserve those decisions or exposes new coordination.
+
+Feedback may also route here after [Diagnose Failure](../diagnose-failure/SKILL.md) establishes structural ownership, interface, state, or failure-unit pressure. Ordinary bugs, failed tests, or finding count do not prove bad design.
+
+Do not force this lens onto a local change whose interface remains sound. Do not use architecture language to hide product decisions or turn reversible implementation detail into ceremony.
+
+## Start With Outcome And Failure
+
+Before choosing classes, services, states, or adapters, ask:
+
+- What complete outcome should the caller request?
+- Which decisions genuinely belong to the caller?
+- Which ordering, policy, storage, retry, cleanup, or provider details can the module own?
+- What counts as complete and visible success?
+- If it fails, who observes it, what state or evidence is written, and what must never happen?
+- Does failure stop, fail closed, fail open, degrade, retry, escalate, or require recovery?
+- What is safe to restart, and what evidence establishes recovery?
+- Which likely-changing decision should remain local?
+
+The answers form the **failure contract**: failure modes, observers, written state, forbidden outcomes, retry or degradation behavior, recovery, and proof. The **failure unit** is the smallest outcome treated as one success, failure, and recovery boundary. Failure behavior is part of the interface even when its mechanism remains private.
+
+When these answers change product behavior, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migration direction, or another user-owned outcome, use [Decision Gate](../decision-gate/SKILL.md). This lens surfaces the decision; it does not make it silently.
+
+## Hide Coordination
+
+Prefer interfaces where callers ask for an outcome and the module owns internal protocol.
+
+Before exposing a flag, state, path, filename, ordering rule, retry, timing behavior, or error, ask:
+
+- Does the caller own this choice?
+- Does exposing it make correct use easier?
+- Is it stable enough to become a contract?
+- Could one outcome-level operation hide it?
+
+Keep caller-owned outcomes and decisions public. Keep internal sequencing, storage, cleanup, provider mechanics, integrity publication, and optimization private unless correct use requires caller control.
+
+Read [software design philosophy](references/software-design-philosophy.md) when the reason a design is shallow or coordination-heavy is unclear.
+
+## Recognize Structural Pressure
+
+Structural pressure exists when evidence shows that:
+
+- each correction adds caller knowledge, public states, flags, retries, or recovery rules;
+- one policy or behavior requires unrelated edits across callers;
+- callers or tests duplicate lifecycle choreography;
+- tests need many owned internals or production hooks created only for testing;
+- a bounded outcome requires an unplanned subsystem because no current seam can own it;
+- correctness depends on coordinated steps that no module owns.
+
+These signals justify design attention, not automatic refactoring. Read [design pressure signals](references/design-pressure-signals.md) when code, artifacts, tests, or reviews show complexity spreading.
+
+Diagnose repeated or unexplained failure before redesigning. Direct design work is appropriate when structural pressure is already observable or an important boundary must be chosen before implementation.
+
+## Shape The Interface
+
+When pressure changes the next action:
+
+1. Name the complete outcome and settled behavior.
+2. Choose the success and failure unit.
+3. Inventory what callers, tests, reviewers, and future agents must know.
+4. Keep caller-owned decisions public and move internal protocol behind the module.
+5. Separate required trust and safety from speculative efficiency, scale, or portability.
+6. For a structural or hard-to-reverse choice, compare materially different ownership or seam placements—not cosmetic variants.
+7. Prefer the design with less caller knowledge, better locality, safer failure behavior, easier correct use, and proportionate evidence cost.
+
+Read [the interface design loop](references/interface-design-loop.md) when materially different interfaces must be compared, evidence cannot yet choose one, or authority, canonical state, atomic visibility, replay, cancellation, or post-commit recovery affects correctness.
+
+Do not force multiple designs for an obvious local choice. If source inspection cannot distinguish viable designs, propose one bounded learning slice with a question, competing designs, evidence, cost boundary, and discard-or-promote condition.
+
+## Tests And Evidence
+
+The intended interface is the normal test surface. If tests must bypass it, reproduce caller choreography, or mock many owned internals, question the module shape before adding test machinery.
+
+Architecture-bearing tests should protect accepted behavior, observed failure, or a settled failure contract. Tests that exist only to protect unnecessary machinery do not justify that machinery.
+
+Exploratory code may produce design evidence. It does not become production architecture without deliberate selection through [Workflow](../workflow/SKILL.md), implementation as an authorized slice, and verification at the required boundary.
+
+## Boundary Examples
+
+- A core operation is being discussed, but partial failure is unspecified → define the failure unit and surface any owner decision before settling the interface.
+- Every caller coordinates retry, storage, cleanup, and error translation → consider an outcome-level module that owns the protocol.
+- One isolated condition is wrong while callers and the interface remain valid → make a local correction; do not redesign.
+- Related failures repeatedly add shared states and caller rules → diagnose the common cause, then use this lens only when structural pressure is supported.
+
+## Return The Route
+
+Return the structural evidence, affected boundary, materially different options when needed, recommendation, and unresolved owner decisions to Workflow. Recommend the narrowest route: continue, run a learning slice, revise a Spec or Plan, use Decision Gate, propose a bounded deepening slice, defer, or stop.
+
+A design recommendation does not authorize implementation. Do not expose speculative variation, broaden accepted scope, or refactor merely because a deeper design is possible. Freeze a supported design boundary instead of pursuing architectural completeness.