@hassangameryt/freeflow 0.8.0 → 0.9.0

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

@@ -1,106 +0,0 @@
-# Activation Boundaries
-
-Read this when activation is unclear or evidence shows missed, late, early, task-hijacking, or retained-interference behavior.
-
-This reference is judgment: adapt it to the skill's goal. Its binding statements restate [Write Skill](../SKILL.md) Rules.
-
-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,133 +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.
-
-This reference is judgment: adapt it to the skill's goal. Its binding statements restate [Write Skill](../SKILL.md) Rules.
-
-## 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 instruction 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.
-
-## Make Instructions Concrete
-
-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.
-
-This applies to Rules. Judgment gets concrete differently: a sharper goal, clearer signals for deviating, and a realistic example on each side of the line. Turning judgment into an absolute makes it easier to follow and worse to follow.
-
-Prefer:
-
-> Start a Slice for work that would leave partial state to reconcile if interrupted. An investigation across many sources can qualify; a discussion whose results land directly in the record usually does not.
-
-Over:
-
-> Start a Slice for every activity.
-
-## Pair Negative Instructions 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 instruction 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 an instruction 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 instruction and a later exception conflict, restructure the route rather than adding another disclaimer.
-
-## Repeat Local Guards Deliberately
-
-Repeat a shared instruction 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 instructions stable.

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

@@ -1,129 +0,0 @@
-# Progressive Disclosure
-
-Read this before adding or reorganizing references, assets, or scripts.
-
-This reference is judgment: adapt it to the skill's goal. Its binding statements restate [Write Skill](../SKILL.md) Rules.
-
-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 instruction 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;
-- instructions 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.

package/skills/write-skill/references/skill-dependency-graphs.md

@@ -1,192 +0,0 @@
-# Skill Dependency Graphs
-
-Read this when creating or revising multiple related skills, shared terminology, cross-skill links, capability activation, direct or routed entry paths, or context-loss recovery.
-
-This reference is judgment: adapt it to the skill's goal. Its binding statements restate [Write Skill](../SKILL.md) Rules.
-
-A multi-skill system is a stateful, partially loaded prompt graph. It is not a mandatory sequence.
-
-## Identify The Edge Types
-
-Do not treat every link as execution.
-
-### Activation edge
-
-Causes a skill to be read or made effective:
-
-```text
-natural prompt -> description -> skill
-always-loaded system cue -> recovery skill
-capability cue -> capability skill
-```
-
-### Owner route
-
-Changes which activity controls the current bounded result.
-
-A plain-text return may express control flow without creating a Markdown package dependency.
-
-### Composition edge
-
-Adds a method, lens, reviewer contract, or domain guide without changing the current owner.
-
-### Reference edge
-
-Loads activity-required or conditional depth inside a package.
-
-### Environment-interaction edge
-
-Temporarily selects one observation or effect and returns to the same current owner.
-
-### Persistence edge
-
-Earlier skill guidance remains in context and may affect later behavior without another read.
-
-### Recovery edge
-
-Reintroduces required guidance after context loss through an always-loaded upstream cue.
-
-## Enumerate Every Valid Entry Path
-
-For each skill, identify:
-
-- natural description activation;
-- orchestrator or lifecycle routes;
-- sibling routes;
-- direct user commands;
-- capability cues;
-- context-loss recovery;
-- host-specific activation;
-- artifact or checkpoint routes.
-
-Do not optimize only for the most common path.
-
-A skill may rely only on context guaranteed across every valid activation path.
-
-If a skill can activate directly, it cannot depend on vocabulary introduced only by a commonly preceding skill.
-
-If a skill can activate through an independent recovery cue, it cannot assume that an earlier discussion or planning skill was read first.
-
-## Place Terminology Upstream
-
-For every shared term:
-
-1. list all consumers;
-2. list every valid path to those consumers;
-3. find the nearest upstream context guaranteed on all paths;
-4. define the term there;
-5. keep specialized detail with its owning skill.
-
-Place shared vocabulary in the nearest always-available context only when independently activated consumers require it.
-
-Keep local terms local when other skills should route to the owner rather than implement its method.
-
-Do not duplicate full definitions merely to compensate for a broken activation graph.
-
-## Prevent Self-Activation
-
-An unread skill cannot require its own first read.
-
-Critical activation must come from:
-
-- guaranteed base or system guidance;
-- a skill description;
-- an already-loaded owner;
-- an effective capability cue;
-- another declared upstream path.
-
-References follow the same rule: the body must name the read condition before using reference content.
-
-## Check Direct And Routed Paths
-
-For every related skill, test:
-
-```text
-direct natural activation
-routed activation from expected parent
-nearby safe-read activation
-retained use after another skill loads
-recovery after context loss
-```
-
-A path that works only because another skill happened to be read is not valid dependency composition.
-
-## Check Redundancy And Inconsistency
-
-Across all changed skills, inspect:
-
-- duplicate canonical definitions;
-- divergent wording for the same invariant;
-- early commands contradicted by later caveats;
-- two skills claiming the same current ownership;
-- methods or lenses accidentally becoming owners;
-- links with no activation, route, composition, or reference job;
-- terms used before guaranteed definition;
-- body and reference read-condition mismatch;
-- stale recovery cues;
-- direct routes bypassing required context;
-- retained instructions hijacking later owners.
-
-Distinguish semantic duplication from intentional local guards.
-
-## Repeat Across Skills Deliberately
-
-Repeat a compact invariant when a distinct activation path or decision point requires local protection.
-
-Keep:
-
-```text
-canonical owner
--> complete definition or method
-
-consumer
--> compact local guard
--> route to canonical owner when needed
-```
-
-Do not copy complete sections across skills. Repetition should preserve meaning without creating competing ownership.
-
-## Keep Routing And Terminology Graphs Distinct
-
-Terminology and dependency order should normally flow from guaranteed upstream context toward consumers.
-
-Runtime routing may be cyclic:
-
-```text
-For example:
-clarification -> task memory -> clarification
-execution -> verification -> review -> execution
-```
-
-A cyclic routing graph does not justify cyclic terminology dependencies.
-
-## Validate Facts And Evaluate Behavior
-
-Deterministic checks can establish:
-
-- links;
-- containment;
-- dependency cycles;
-- resource inventory;
-- routing-map parity;
-- exact duplicate text.
-
-They cannot establish:
-
-- correct activation;
-- safe retained influence;
-- semantic consistency;
-- useful repetition;
-- behavior preservation;
-- readiness.
-
-Evaluate the exact graph claim:
-
-- activation;
-- first-read body behavior;
-- dependency composition;
-- retained use;
-- recovery;
-- artifact outcome.
-
-Do not require a graph artifact for every small skill edit. Use this method when several nodes, paths, terms, or owners change together.

package/skills/write-spec/SKILL.md

@@ -1,85 +0,0 @@
----
-name: write-spec
-description: "Use when writing or revising a spec, PRD, issue, API contract, technical design, migration contract, decision artifact, or similar durable document."
----
-
-# Write Spec
-
-Turn accepted intent and source evidence into a durable artifact that later work can use without inheriting invented requirements or losing accepted changes.
-
-A Spec describes content, behavior, constraints, and uncertainty for its intended use. It is not an implementation sequence, Working Record, transcript, or permission grant. Useful technical depth is welcome; hypothetical completeness is not required.
-
-The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
-
-## Rules
-
-- A Spec grants no permission and does not begin implementation. Review establishes fitness, not user acceptance or execution authority; never label author self-review as independent review, or use an approval status without its source.
-- A drafted proposal is not accepted behavior; label proposed design as proposed. Authorization to investigate or draft an option is not acceptance of undisclosed production consequences.
-- Never add an obligation without an accepted source or a reason it is necessary for the stated outcome. Do not infer requirements from nearby code, existing tests, or available machinery, and do not reduce agreed scope into an unapproved MVP, roadmap, or later-version split.
-- Stop the affected writing when it would silently change behavior, scope, public interfaces, compatibility, sensitive policy, failure semantics, or hard-to-reverse design; never settle such a choice through normative prose, an unexplained assumption, or a polished placeholder; return the concrete effect and supported alternatives to its owner through [Decision Gate](../decision-gate/SKILL.md) or [Discuss](../discuss/SKILL.md).
-- Never rewrite source truth to suit implementation, and never rewrite historical decisions as though they always contained the new choice.
-- Writing or revising a Spec does not trigger independent review.
-
-## Establish The Artifact's Job
-
-Goal: know who will use the artifact and for what, before writing it.
-
-Identify the artifact type, intended reader or future action, accepted scope, destination, and the unresolved questions it must preserve.
-
-Answer questions about a Spec without editing it unless revision is requested. Use Discuss when direction or alternatives remain materially open and Decision Gate for one blocking owner choice or source conflict; do not repeat discussion that already settled the artifact's purpose. An agreement to implement accepted work may include documenting its supported contract; do not manufacture another user approval because a document was produced.
-
-## Establish The Current Source Basis
-
-Goal: the artifact rests on what was actually accepted, including later amendments.
-
-Use the sources that actually determine the artifact:
-
-- current user direction and accepted discussion, including later amendments;
-- existing Specs, issues, decisions, and contracts being revised or consumed;
-- relevant live code, tests, policy, ADRs, and established behavior;
-- current primary sources when an external version or interface constrains the result;
-- [Track Work](../track-work/SKILL.md) for task memory when a record exists.
-
-A record or implementation summary cannot override contradictory current intent or accepted source truth. Distinguish what was requested, proposed, accepted, and actually observed. Preserve enough source identity to recover the basis of a consequential statement; for an approval such as "proceed", keep the proposal and response together when their scope matters. A test can faithfully protect an unnecessary mechanism.
-
-## Write Only What The Intended Use Needs
-
-Goal: enough depth for the use, with requirements, facts, proposals, and open questions never confused.
-
-Read [Spec Shapes](references/spec-shapes.md) before choosing the structure. Read [Artifact Standards](references/artifact-standards.md) when choosing destination, identity, status, source trail, or revision shape. Read [Decision Records](references/decision-records.md) when the artifact primarily preserves a decision and rationale.
-
-Include relevant purpose, scope, non-goals, accepted behavior, constraints, interfaces, consequential failure semantics, acceptance, and evidence. Explain architecture and ownership deeply where the use requires it; do not remove necessary detail just to shorten the document.
-
-When writing an implementation-guiding design whose unresolved representation, identity, ownership, algorithm, or failure choices could invalidate significant dependent work, read [Design for Depth](../design-for-depth/SKILL.md) and use its Implementation Decisions method. Preserve the selected choices and rationale, distinguishing fixed constraints from illustrative sketches and local freedom. Existing supported decisions need no fresh design exercise; open choices stay visible rather than being filled with invented mechanics.
-
-Keep distinguishable: required behavior and accepted decisions; supported facts and their evidence limits; proposed mechanisms; tentative assumptions and open questions; intentional deferrals and superseded direction. Use the repository's vocabulary rather than inventing a status schema, and place a consequential uncertainty where the reader makes the affected decision, not in a distant caveat.
-
-A limitation of one implementation technique does not establish a need for stronger guarantees, host changes, new persistence, retries, or a subsystem. Open questions need not stop unrelated content; a proposal can be fit for discussion while unfit to guide production, so state that boundary.
-
-Keep ordered execution in a Plan and live progress in the Working Record. Link shared rationale rather than copying it into several independently maintained sources.
-
-## Reconcile Material Changes
-
-Goal: the artifact reflects the current accepted contract without losing why it changed.
-
-Preserve accepted content that still holds. Change only what new intent or evidence affects, and keep consequential prior rationale recoverable through the owning decision record, change history, or version control.
-
-When an accepted amendment or learning result changes the contract, identify the affected downstream Plan, acceptance check, or implementation assumption. Reconcile them when authorized; otherwise mark them contingent and return the needed revision before dependent use. Do not synchronize unrelated artifacts.
-
-Experimental learning does not automatically enter the production contract: distinguish findings deliberately selected for implementation from observations kept as evidence or deferred possibilities. Conversely, do not keep an older baseline after the user accepted a relevant change. Follow repository policy for historical records and supersession.
-
-## Self-Review Once Before Use
-
-Goal: the artifact is fit for its use before anyone relies on it.
-
-After checking source-backed factual claims, use [Review Artifact](../review-artifact/SKILL.md) for silent author self-review of the complete artifact and its intended use. Check that it preserves accepted intent and amendments, separates requirements from proposals, has sufficient evidence and acceptance conditions, and keeps affected dependencies coherent. Correct clear covered defects and recheck affected facts and lenses; return unresolved owner decisions instead of inventing an answer to make the document consistent.
-
-Independent review applies only when selected and authorized to protect a concrete boundary: supply the complete artifact, source basis, dependencies, and evidence limits through Review Artifact's independent route, and adjudicate its report before revision or use. Respect an explicitly selected approval checkpoint, but do not create one for every artifact.
-
-## Report And Stop
-
-Report the artifact path, type, intended use, source basis, material unresolved or contingent content, and actual review and acceptance status.
-
-When a Working Record exists and the Spec is accepted for its task, list it under the record's `What defines this task` through Track Work so every recovery reads it.
-
-Stop when the authorized artifact is fit for its stated use or its blocking decision or evidence limit is explicit, and return to the requesting activity.