@hassangameryt/freeflow 0.7.3 → 0.9.0

package/skills/workflow/references/domain-skill-composition.md

@@ -1,43 +0,0 @@
-# Domain Skill Composition
-
-Read this when specialized engineering guidance must support the current owner.
-
-Freeflow owns authority interpretation, current ownership, route changes, evidence honesty, checkpoints, continuity, and Supported Exit. Domain guidance supplies specialized engineering method. It does not become another Workflow, current owner, or authority source.
-
-## Compose One Current Owner
-
-For the current bounded activity:
-
-1. keep one Freeflow current owner;
-2. add only the domain guidance required by the concrete technology, behavior, environment, or risk;
-3. use one primary implementation, diagnostic, verification, or review method at a time;
-4. retain [Design for Depth](../../design-for-depth/SKILL.md) only when direction is already design-bearing or evidence establishes structural pressure;
-5. select independent specialist review only when it materially protects a named boundary.
-
-Prefer repository policy, current primary sources, and technology-specific evidence over generic examples.
-
-Do not load a handbook because one keyword appears. Do not combine several overlapping methodologies merely because each contains useful advice.
-
-## Preserve Workflow Boundaries
-
-Domain guidance may provide techniques for frontend systems, accessibility, browsers, security, performance, databases, APIs, CI/CD, observability, cloud platforms, migrations, releases, deployments, or other specialized work.
-
-It does not override:
-
-- user-owned product, scope, or risk decisions;
-- repository instructions or accepted behavior;
-- the authority envelope;
-- source truth, failure contracts, or evidence requirements;
-- the current owner’s result and return conditions;
-- selected checkpoints or separately controlled effects;
-- mode, capability, host, or tool controls.
-
-When domain guidance conflicts with accepted intent or live source truth, return the conflict to Workflow. Use [Decision Gate](../../decision-gate/SKILL.md) when resolving it requires one user-owned choice.
-
-## Return To The Current Owner
-
-Return domain results, evidence, assumptions, and limits to the same current owner.
-
-A domain method, tool choice, or new observation does not automatically change the current owner, accepted scope, durable task state, or Workflow route.
-
-When the domain method exposes material architecture, authority, safety, evidence, or scope pressure, return that changed boundary to Workflow rather than silently expanding the method.

package/skills/write-plan/SKILL.md

@@ -1,92 +0,0 @@
----
-name: write-plan
-description: "Use when writing or revising an implementation plan, execution plan, remediation plan, migration plan, or similar ordered plan."
----
-
-# Write Plan
-
-Write a supported ordered strategy for an agreed outcome. Make its dependencies, actions, checks, and invalidation conditions clear without inventing requirements or pretending unknown later work is settled.
-
-A Plan describes intended execution. The Working Record preserves actual work, evolving state, and the next useful action. Neither creates authority by existing.
-
-## Plan Only What Is Understood Enough To Order
-
-Use a durable Plan when the intended outcome and material decisions are settled, the approach and dependencies can be ordered without guessing, and the strategy needs to survive independently.
-
-Not every task needs one. A small correction can proceed from its request and supported approach. An evolving route with substantial branching belongs in [Track Work](../track-work/SKILL.md) as provisional Slices, not a confident long-form Plan.
-
-Use [Discuss](../discuss/SKILL.md) for unresolved direction or material alternatives, [Decision Gate](../decision-gate/SKILL.md) for a blocking owner choice or source conflict, and [Diagnose Failure](../diagnose-failure/SKILL.md) for a fix whose cause is unsupported. Do not encode the hoped-for answer as a planning assumption.
-
-If the user asks about a Plan, answer rather than write one. If execution of the task is already authorized and a Plan is useful preparation, writing it need not create another approval stop. Preserve any review or user-return boundary actually selected.
-
-## Establish The Current Basis
-
-A separate Spec is not required when the request and accepted understanding are sufficiently clear. Otherwise consume the relevant Spec, issue, design, diagnosis, decision, or requirements, together with current code, tests, policies, ADRs, and external constraints where needed.
-
-Identify which accepted source version or amendment the Plan implements. A Working Record can locate those sources but cannot override them. Do not use an older experimental or design baseline merely because a prior Plan was reviewed.
-
-Separate:
-
-- the required outcome and non-goals;
-- accepted design choices and constraints;
-- the supported implementation approach;
-- assumptions whose failure would invalidate dependent work;
-- unresolved or intentionally deferred work outside this Plan's promise.
-
-An experiment produces evidence, not an automatic requirement. Include its consequences only where selected for this outcome; do not omit consequences the user subsequently accepted.
-
-## Write The Smallest Useful Strategy
-
-Read [Plan Shapes](references/plan-shapes.md) before choosing the artifact shape.
-
-Include relevant goal, sources, scope, decisions, assumptions, dependencies, ordered coherent outcomes, focused checks, integration, completion conditions, and what would invalidate the strategy. Use exact paths and commands when known and useful; do not invent them to make the Plan look executable.
-
-Size outcomes for manageable working context, dependencies, uncertainty, and checking. Do not divide mechanically by file, bug count, test, or method. The complete task may require several Slices, but each should have a coherent result and a clear dependency on earlier work where one exists.
-
-A validation step may stop the Plan if a bounded assumption fails. If its result is expected to select among materially different strategies, keep dependent work provisional in the Working Record rather than presenting the later sequence as decided.
-
-The Plan is not a context inventory. Specify only the sources and relationships needed to explain or execute its steps, leaving ordinary local choices to the executing agent.
-
-## Preserve Acceptance And Return Conditions
-
-Tie each material outcome and final check to the accepted behavior it serves. Do not let available tests redefine acceptance or claim whole-system completion from a narrow observer.
-
-Keep the agreed user-facing return condition visible: return a proposed strategy, implement one Slice, finish the described task, or stop at a specified boundary. Internal delegation handbacks and context cycles are not automatic user checkpoints.
-
-A Plan must not invent product behavior, compatibility, public interfaces, failure semantics, sensitive policy, migration, scale, retries, recovery, or extension machinery. Do not replace agreed scope with an unapproved MVP or later-version split.
-
-Before a new prerequisite becomes a planned obligation, determine whether it serves an accepted requirement or only preserves a particular approach. Resolve consequential alternatives instead of hiding them in confident steps.
-
-## Select Checkpoints Without Making A Schedule Of Ceremonies
-
-Ordinary verification and silent self-review belong to producing each supported result. Do not restate them as independent gates unless a particular evidence boundary needs explanation.
-
-Include independent review, a local commit, a user decision, or continuity transfer only when selected to protect a concrete dependency, risk, rollback, or delivery boundary. A Slice ending or a fixed count is insufficient.
-
-Accepting a Plan as a strategy is not permission to execute it. Explicit approval to execute the Plan may cover its listed work, checks, selected reviews, record maintenance, and local commits. It does not imply push, integration, migration, deprecation, release, or launch. Planned commits remain conditional on fresh evidence and [Commit Work](../commit-work/SKILL.md) inspection.
-
-When an existing agreement already covers the work, preserve that source instead of asking the user to approve the same scope again because it is now written down.
-
-## Revise Only The Affected Strategy
-
-Do not update a Plan for completed steps, ordinary local choices, test counts, or routine status. Record material actual state through Track Work when present.
-
-Revise or supersede the affected strategy when accepted intent or supported evidence changes its scope, design, ordering, dependencies, checks, or mechanism. Preserve valid earlier work and rationale. A clerical correction does not reopen the strategy, and reaching a review cap is not evidence that the Plan needs rewriting.
-
-Identify affected upstream and downstream artifacts. Revise only content whose owned meaning changed and whose mutation is authorized. If an upstream contract remains unresolved, mark dependent steps contingent before they are used. Do not repair consistency by silently changing the required outcome.
-
-## Self-Review Before Treating The Plan As Usable
-
-After factual source checks, use [Review Artifact](../review-artifact/SKILL.md) for one silent author self-review of the complete Plan, accepted sources, and intended execution boundary.
-
-Check whether the ordered work can achieve the accepted outcome, dependencies are supported, later uncertainty is honest, final checks match acceptance, and selected checkpoints are proportionate. Correct clear covered defects and recheck affected facts and lenses.
-
-Do not automatically dispatch an independent reviewer after writing or revising a Plan. Use Review Artifact's independent route only when separately selected and authorized to protect a concrete boundary. Supply complete sources, dependencies, and limits; adjudicate the returned report before acting on its findings.
-
-Neither self-review nor independent review grants user acceptance or execution authority. Conversely, an already-covered execution agreement does not need another approval turn solely because planning produced an artifact.
-
-## Report And Return
-
-Report the Plan path and intended use, source basis, material assumptions or contingent work, invalidation conditions, selected checkpoints, and actual review/acceptance/execution-authority status.
-
-Return the supported strategy to the requesting activity. If the agreement covers implementation, the agent can continue through the normal execution route; if it asks for a Plan first, stop there. Do not begin work outside that agreement or claim an unresolved strategy is ready.

package/skills/write-plan/references/plan-shapes.md

@@ -1,156 +0,0 @@
-# Plan Shapes
-
-Read this when choosing the structure, destination, identity, or revision shape of an ordered Plan. Use only the sections the Plan needs.
-
-## Destination And Durable Identity
-
-Follow repository convention when one exists.
-
-When [Track Work](../../track-work/SKILL.md) owns the task, store a task-local Plan in the `plans/` location it defines unless the Plan should become a canonical repository artifact.
-
-When no convention exists and future readers need durable identity, begin with a compact title and header:
-
-```md
-# Billing Webhook Implementation Plan
-
-> **Doc ID:** PLAN-001-billing-webhook
-> **Type:** Implementation Plan
-> **Status:** Draft
-> **Owner:** <plan owner>
-> **Source:** <spec, issue, Working Record, diagnosis, or accepted context>
-```
-
-Use one current status. Follow the repository or owner's vocabulary; useful states may include `Draft`, `Reviewed`, `Ready`, `Superseded`, and `Abandoned`. Writing or reviewing a Plan does not by itself make it `Ready`. State whether any recorded review was author self-review or selected independent review; neither implies user acceptance or execution authority.
-
-Add dates, supersession links, or approvers only when useful and reliable.
-
-## Start With Source And Boundaries
-
-Make the execution boundary and its dependencies clear:
-
-```text
-Goal:
-Source and linked artifacts:
-Scope:
-Non-goals:
-Accepted decisions:
-Assumptions:
-Dependencies:
-Required order:
-```
-
-Link accepted behavior, architecture, and decisions instead of copying their rationale. Identify the governing source version and relevant accepted amendments when they affect execution. Do not hide unsettled design or owner choices as assumptions. If an assumption could choose among materially different strategies, resolve it before treating the Plan as executable. Experimental findings become planned obligations only when selected for the accepted outcome; a previously reviewed baseline does not excuse omitting a later accepted change.
-
-## Choose The Execution Shape
-
-### Lightweight Ordered Plan
-
-Use when the work is clear and short enough that phases add no value:
-
-```text
-Ordered actions or slices:
-Checks:
-Selected checkpoints, if any:
-Completion condition:
-```
-
-A tiny reversible action may not need a saved Plan.
-
-### Phased Implementation Plan
-
-Use when execution has meaningful dependencies, integration points, or several coherent outcomes:
-
-```text
-## Phase 1 — <outcome>
-Purpose:
-Dependencies:
-Selected checkpoints, if any:
-Completion condition:
-
-### Slice 1.1 — <result>
-Scope or boundary:
-Work:
-Checks:
-Completion condition:
-
-### Slice 1.2 — <result>
-...
-
-## Phase 2 — <outcome>
-...
-```
-
-Describe the whole intended strategy with enough detail to inspect and execute it. If later phases cannot yet be planned honestly, use a Working Record instead.
-
-## Define Phases And Slices
-
-A phase groups slices that produce one meaningful integrated outcome. State its purpose, dependencies, and completion condition.
-
-For each slice, use only the fields needed to execute and check it:
-
-```text
-Intended result:
-Source requirement:
-Scope or write boundary:
-Work:
-Dependencies:
-Tests or observations:
-Verification claim and required boundary:
-Selected independent review, if any:
-Selected local commit, if any:
-Other user or continuity checkpoint, if any:
-Completion condition:
-```
-
-A slice is a coherent result, not a file list. Mention files, modules, or systems only when they clarify scope.
-
-Consider checkpoints at meaningful slice, phase, integration, risk, and continuity boundaries. Record only useful additions; normal verification and silent self-review need no repeated fields.
-
-A selected local commit names its coherent outcome and conditions, not merely “commit after this slice.” Approval to execute the Plan may authorize listed local commits subject to live evidence and Commit Work inspection; approval of its strategy alone does not. Neither implies push, integration, migration, deprecation, release, or launch. Record actual results and commit identities in the Working Record.
-
-## Adapt For The Work Type
-
-### Remediation
-
-After evidence or diagnosis establishes the cause, include the observed problem, source requirement, affected scope, ordered corrections, regression checks, recovery or cleanup, and completion condition. Do not plan from a requested patch or plausible cause alone.
-
-### Migration Or Operations
-
-For an accepted migration, release, rollout, or operational contract, include the source and target states, prerequisites, ordered execution or cohorts, checks before/during/after, stop or recovery conditions, observation, completion, and cleanup.
-
-The Plan implements accepted compatibility, safety, and recovery requirements; it does not invent them.
-
-## Finish With Integration And Invalidation
-
-End with the complete-result checks and conditions that would stop the Plan:
-
-```text
-Integration:
-Final tests or observations:
-Verification claims and required boundaries:
-Selected independent review, if any:
-Selected local commit, if any:
-Other user or continuity checkpoint, if any:
-Completion condition:
-
-Plan invalidation conditions:
-```
-
-Useful invalidation conditions include:
-
-- a source requirement or accepted decision changes;
-- a material dependency behaves differently;
-- the design or architecture cannot satisfy the contract;
-- checks cannot establish the required claims;
-- implementation requires materially different scope or order;
-- accepted review items expose a Plan-level defect.
-
-These conditions stop or revise the affected Plan. They are not alternate branches. Do not use a narrow final check to imply broader completion.
-
-## Revise Or Supersede
-
-A local implementation detail, expected result, or completed slice does not revise the Plan.
-
-For a founded material change, update only the affected strategy and dependencies, record why it changed, and preserve prior rationale. Update linked artifacts only when their owned content changed and revision is authorized; otherwise mark dependent work contingent and return the missing decision or revision.
-
-Use a superseding Plan when editing in place would obscure the earlier accepted strategy or reviewed state. Apply author self-review through Review Artifact to a materially revised or superseding Plan. Independent review is separately selected and authorized when it protects a concrete boundary, not required merely because the Plan changed.

package/skills/write-skill/references/activation-boundaries.md

@@ -1,104 +0,0 @@
-# Activation Boundaries
-
-Read this when activation is unclear or evidence shows missed, late, early, task-hijacking, or retained-interference behavior.
-
-A description should make the skill available at the earliest useful decision without requiring language introduced by the skill itself.
-
-## Diagnose The First Read
-
-Identify:
-
-- the earliest natural prompt or task state where the skill can change behavior;
-- cues visible before the body is read;
-- context guaranteed before activation;
-- the consequence of missing or delaying the read;
-- the consequence if a nearby prompt also loads the skill;
-- how retained guidance should behave after the immediate method ends.
-
-Do not optimize for repeated reads. A body may enter context once and continue influencing later messages and tool interactions until context projection or loss.
-
-## Compare Activation Costs
-
-False-positive and false-negative activation have different costs.
-
-A false-positive read may be acceptable when:
-
-- loading cost is proportionate;
-- the body identifies that its method does not apply;
-- it exits without changing ownership or route;
-- retained instructions do not hijack later work.
-
-A false negative is material when missing the first useful read causes:
-
-- an irreversible or expensive action;
-- a wrong owner or method;
-- repeated low-value environment interactions;
-- missing safety or evidence boundaries;
-- later work that the skill cannot reliably undo.
-
-Prefer recall when nearby reads are demonstrably safe and missed activation is materially worse. Tighten activation when early or retained guidance can distort ordinary work.
-
-## Check The Cues
-
-Useful cues include:
-
-- the skill’s core job;
-- natural user verbs;
-- visible task situations;
-- observable distinctions from neighboring jobs.
-
-Reject cues that depend on:
-
-- vocabulary defined only in the body or an optional sibling;
-- future-duration guesses;
-- unexplained internal classifications or named phases;
-- generic “help with” or “improve” language;
-- marketing claims;
-- exhaustive trigger catalogs.
-
-Guaranteed base context may define a term. Otherwise use plain observable language.
-
-## Test Nearby And Retained Behavior
-
-A nearby case can pass through:
-
-- **Non-trigger:** the skill is not read.
-- **Safe read:** the body loads, exits or defers correctly, and does not interfere later.
-
-Test both the immediate response and later declared turns when retained influence matters.
-
-Examples:
-
-Broad useful trigger:
-
-> Use when committing work.
-
-Over-specified trigger that hides the job:
-
-> Use after final verification when a planned checkpoint requires a locally reviewable commit.
-
-Broad safe-read trigger:
-
-> Use when working with software design—especially boundaries, interfaces, ownership, state, and failure behavior.
-
-The body must exit when the local interface remains sound and avoid turning later local choices into architecture work.
-
-## Preserve The Evidence Boundary
-
-Natural activation proves the host read the exact skill snapshot from a natural prompt.
-
-Explicit body delivery tests first-read instructions, not activation.
-
-Dependency composition tests exact declared skill and context order.
-
-Multi-turn evidence tests retained use.
-
-Artifact and transcript evidence show whether activation helped, exited safely, or hijacked behavior.
-
-Preserve:
-
-- the earliest useful positive prompt;
-- at least one close nearby case;
-- later-turn evidence when retained influence is part of the claim.
-
-Do not infer one evidence class from another.

package/skills/write-skill/references/agent-first-instructions.md

@@ -1,121 +0,0 @@
-# Agent-First Instructions
-
-Read this when a concrete first-read or retained-use failure involves wording, placement, undeclared context, author explanation, or competing instructions.
-
-## Reconstruct The Reader’s Context
-
-Assume the agent is seeing the skill for the first time.
-
-- State the job before local vocabulary.
-- Define terms before relying on them.
-- Assume only guaranteed runtime or declared base context.
-- Do not rely on an optional sibling, reference, common route, or accidental earlier read.
-- Make required reads explicit before their content is used.
-- Do not assume the skill will be reread before later use.
-
-Dependency direction remains:
-
-```text
-guaranteed base context
--> description
--> SKILL.md
--> required or conditional resources
-```
-
-A later layer may rely on language established by an earlier guaranteed layer, not the reverse.
-
-## Translate Author Context
-
-Keep a sentence only when it:
-
-- changes an action or judgment;
-- defines required language;
-- protects a likely or observed failure boundary;
-- states an evidence, return, or stop condition;
-- makes a dependency executable;
-- provides a compact example resolving likely misclassification.
-
-Translate rationale into a direct rule plus only the why needed to generalize.
-
-Translate debate into the selected boundary and stop condition.
-
-Translate a measured failure into the smallest transferable guard that prevents it.
-
-Omit rejected drafts, conversation history, fixture narration, evaluation status, and explanation whose only audience is the author.
-
-## Strengthen Rules
-
-A useful rule names:
-
-```text
-observable trigger or pressure
--> required or forbidden action
--> evidence, return, or stop condition
-```
-
-Prefer:
-
-> If saved evidence already answers the fixed question, inspect it before proposing a rerun.
-
-Over:
-
-> Keep evaluation efficient and aligned with best practices.
-
-Concrete rules reduce the judgment the agent must reconstruct.
-
-## Pair Negative Rules With The Route
-
-Bad:
-
-> Do not recreate the old worker/verifier architecture.
-
-Better:
-
-> The producing activity handles implementation and verification. The surrounding workflow may select independent review.
-
-Bad:
-
-> Do not implement the recommendation.
-
-Better:
-
-> Return the recommendation to the owning workflow. Implementation requires separate authorization.
-
-A negative rule may preserve an invariant directly when the positive route is already clear:
-
-> Preserve the accepted scope. Do not split it into MVP or roadmap phases without approval.
-
-## Fix Placement Before Adding Prose
-
-Put a rule where the agent first makes the affected choice.
-
-A late caveat rarely defeats an early command. Move or sharpen the controlling sentence before adding another section.
-
-When an early rule and later exception conflict, restructure the route rather than adding another disclaimer.
-
-## Repeat Local Guards Deliberately
-
-Repeat a shared rule only when local presence protects:
-
-- an independently activated path;
-- a distinct decision point;
-- retained behavior;
-- context-loss recovery;
-- a dangerous literal interpretation;
-- a measured failure.
-
-Keep one canonical owner for the full definition or method. Repeat only the compact local guard needed at the choice.
-
-> Repeat the behavioral invariant, not the owning method.
-
-Do not copy complete orchestration, authority, review, or task-memory sections into every consumer.
-
-## End The Skill’s Influence
-
-A skill body may remain in context after its immediate method ends.
-
-State stop, return, or exit conditions clearly enough that retained instructions do not continue claiming ownership or broadening later work.
-
-A first-turn exit is insufficient when later turns still show method hijacking.
-
-After editing, rerun the same first-read and retained-use pressure while keeping unrelated rules stable.

package/skills/write-skill/references/progressive-disclosure.md

@@ -1,127 +0,0 @@
-# Progressive Disclosure
-
-Read this before adding or reorganizing references, assets, or scripts.
-
-Progressive disclosure should change when content enters context, preserve one canonical owner, or isolate a real lifecycle boundary. Splitting files without one of those benefits adds dependency cost without reducing context.
-
-## Preserve Dependency Direction
-
-```text
-description
--> SKILL.md
--> required or conditional resource
-```
-
-`SKILL.md` establishes:
-
-- the job;
-- normal route;
-- necessary terms;
-- stop and return conditions;
-- observable resource read points.
-
-A reference cannot activate itself. Do not hide the rule needed to recognize a reference inside that reference.
-
-That is progressive reconstruction, not disclosure.
-
-## Classify The Read Point
-
-### Entry-required
-
-Read before the skill can follow or reject its normal route.
-
-Entry-required references are exceptional. Use one only when separation provides independent value, such as:
-
-- canonical reuse across packages;
-- separate ownership or lifecycle;
-- generated schemas or contracts;
-- compatibility or host constraints;
-- independently versioned external policy.
-
-If every useful activation reads the resource and it has no separate ownership or lifecycle value, inline it even when `SKILL.md` becomes substantially longer.
-
-### Activity-required
-
-Read before performing one named normal activity.
-
-The skill may first:
-
-- exit;
-- defer;
-- choose another route;
-- determine that the activity does not apply.
-
-Activity-required references provide real loading value even when the activity is common.
-
-### Conditional
-
-Read only when an observable branch occurs.
-
-The body must teach the agent enough to recognize the branch before loading the reference.
-
-Do not use “when unclear” if the reference contains the method for recognizing the underlying condition.
-
-## Keep The Normal Route Contiguous
-
-Start with one `SKILL.md`.
-
-Keep inline:
-
-- the first-read job;
-- normal route;
-- controlling definitions;
-- rules needed to select resources;
-- stop and return behavior.
-
-Move depth only when keeping it inline would obscure the normal route and the read point is executable.
-
-Do not split a file to satisfy a line count.
-
-## Add A Reference When
-
-- one named normal activity needs separately owned depth;
-- one observable conditional branch needs depth;
-- one canonical resource is shared without duplication;
-- one resource has a real independent lifecycle;
-- the body can name and require the read before use.
-
-The body instruction and reference introduction must state the same read condition.
-
-Required means necessary. Do not call a required reference recommended or optional.
-
-If skipping the reference preserves correct execution, either make its concrete optional value explicit or remove it.
-
-## Add A Script When
-
-- the skill owns a deterministic repeated operation;
-- model-generated execution would be error-prone, unsafe, or materially wasteful;
-- the interface and failure behavior can be tested;
-- the script’s output has a clear evidence boundary.
-
-Do not script ordinary commands merely to make the package appear complete.
-
-## Link At The Decision Point
-
-Link every agent-facing reference, asset, package dependency, and executable entrypoint from `SKILL.md` at the first useful choice.
-
-Avoid vague resource lists such as:
-
-> See references for more information.
-
-Prefer:
-
-> Read Test Design before designing or materially changing the behavior check.
-
-## Apply The Resource Test
-
-For every extra file, ask:
-
-1. What activity, conditional branch, shared ownership, or lifecycle requires it?
-2. When can the agent recognize the read or run condition?
-3. What prior language does it assume?
-4. Where is that language guaranteed?
-5. What context or ownership value does separation provide?
-6. Why is inline content worse?
-7. How will links, containment, and behavior be verified?
-
-If separation changes neither loading nor ownership, inline the content or remove it.