@hassangameryt/freeflow 0.7.3 → 0.9.0

package/skills/discuss/SKILL.md

@@ -1,116 +0,0 @@
----
-name: discuss
-description: "Use when exploring, clarifying, or revisiting what to accomplish or how to approach it, especially when user collaboration, alternatives, assumptions, or new evidence could change the next action."
----
-
-# Discuss
-
-Build enough shared understanding to choose the next sound action. Discussion can establish both what to accomplish and how to approach it; it need not end at requirements or continue until every implementation detail is known.
-
-Discuss owns exploration, alternatives, assumptions, and direction. It does not turn conversation, a recommendation, or a recorded proposal into execution authority.
-
-## Start From The User's Intent
-
-Respond to the substance before steering the process.
-
-A request to discuss keeps the user involved as understanding develops. Gather relevant existing facts when needed, explain what they imply, and return at the next meaningful question or supported conclusion. Do not treat convergence as permission to implement.
-
-A direct action request may already settle the outcome and delegate approach selection. Do not force a discussion phase when existing evidence can resolve the remaining facts and reversible local choices. Return clear covered work to [Workflow](../workflow/SKILL.md).
-
-Use [Decision Gate](../decision-gate/SKILL.md) for one known blocking user-owned choice or source conflict. Use [Diagnose Failure](../diagnose-failure/SKILL.md) when a reported or recurring failure needs a supported cause rather than broader option discussion.
-
-## Separate Outcome From Approach
-
-Identify which understanding is missing:
-
-- **What:** the problem or opportunity, desired result, accepted behavior, constraints, non-goals, and what would count as success.
-- **How:** the mechanism, dependencies, affected boundaries, tradeoffs, and evidence needed to produce that result in the actual environment.
-
-Use [Design for Depth](../design-for-depth/SKILL.md) when representation, identity, ownership, interfaces, algorithms, state, dependencies, or failure behavior materially shape the choice. If unresolved choices could materially change a technical recommendation or invalidate significant dependent work, read its Implementation Decisions method before recommending a mechanism. Use it to explain the differences that matter between viable approaches, not to turn ordinary discussion or a supported local change into an architecture exercise.
-
-These questions can be answered together. Reuse what remains supported instead of running two compulsory discovery passes. A detailed request may settle what while leaving how open; an investigation may reveal that the initial problem description was wrong.
-
-Keep supported facts and explicit decisions distinct from hypotheses, proposed mechanisms, and unresolved choices. Do not turn an assistant recommendation into a requirement because it is repeated or recorded.
-
-When reopening discussion, name what changed and preserve unaffected understanding. A new local obstacle does not reopen the whole task.
-
-## Gather Context To Answer A Question
-
-Before inspecting the environment, identify the missing fact and how its answer could change the discussion. Check whether current evidence already supplies it.
-
-Use [Action Selection](../action-selection/SKILL.md) for uncertain or broad inspection. Prefer a focused source, caller, contract, or observation over a repository survey. Read more only when the result leaves a material question unresolved.
-
-Existing code, tests, documentation, policies, artifacts, repository state, supplied material, and current primary sources may settle factual questions. Inspect them rather than asking the user to supply facts available to the agent. Source inspection cannot establish unobserved runtime behavior.
-
-Stop gathering when sufficient evidence supports the next decision. Do not collect every later dependency, reconstruct exhausted history, or prepare an exact implementation plan while the outcome is still open.
-
-## Collaborate And Recommend Proportionately
-
-Carry your share of the thinking:
-
-- explain what the evidence and intent imply;
-- challenge unsupported claims and consequential assumptions;
-- compare only materially different paths that could realistically be chosen;
-- state what each sacrifices and the assumptions it needs;
-- recommend the best-supported direction and what would change it;
-- revise your position when evidence changes.
-
-Ask about priorities, behavior, constraints, and tradeoffs the user owns. Keep one consequential uncertainty in focus; do not conduct a questionnaire or manufacture alternatives for ordinary choices.
-
-Before recommending a new obligation, distinguish a requirement from a limitation of the current approach. Explain consequences in user terms: "requires changing and distributing a patched host," not merely "needs a provenance interface." Include a simpler in-scope alternative when one is supported. Do not weaken required behavior to make an approach look simpler.
-
-## Frame And Assess A Learning Action
-
-Use an experiment or prototype when existing evidence cannot settle a material question and exercising behavior can distinguish the remaining answers. A separate prototype should isolate the uncertainty more safely or economically than changing production; unfamiliarity alone does not require one.
-
-If the work is an accepted useful outcome regardless of what it teaches, treat it as Delivery or Deepening rather than disguise implementation as Learning. Incidental learning does not change its authority or acceptance boundary.
-
-Frame the action before proposing execution:
-
-- the question and its consequence for the accepted outcome or approach;
-- plausible answers and the observation that would distinguish them;
-- the smallest adequate prototype or observer;
-- permitted effects, environment, and production exclusion;
-- expected evidence and return conditions: question answered, observing limit reached, or further work requiring a different question or expanded scope;
-- what would justify discarding, revising, or proposing promotion.
-
-Add a time or cost boundary when repetition or setup could grow; do not demand an exact token prediction. If no adequate observer is available within scope, state the limitation rather than inventing a proof.
-
-Return the framed action to Workflow for authority and, when needed, [Track Work](../track-work/SKILL.md) preservation, then [Execute Work](../execute-work/SKILL.md) for execution. Existing authority may already cover the experiment; its name does not create another approval gate.
-
-Assess returned evidence against the original question. Negative or inconclusive evidence is a valid result; one failed technique does not prove every alternative impossible. If a new prerequisite is reported, distinguish a limitation of the observer or chosen approach from a requirement of the intended outcome before recommending more work.
-
-Revise only the affected understanding. Preserve the consequence for the task, remaining uncertainty, and exploratory-artifact disposition when continuity matters. A successful demonstration is not production acceptance; promotion must be deliberately selected and its effects authorized. Stop assessment when the supported next direction or unresolved decision is clear.
-
-## Preserve A Useful Route When Needed
-
-When the likely work becomes clear enough, propose coherent outcomes and their dependencies. Keep near-term work concrete and later work directional. A rough route need not wait for a formal Plan; its order may change as evidence arrives.
-
-Ask whether losing the current understanding, decisions, evidence, proposals, or next action would risk misalignment. If not, keep it in conversation.
-
-If continuity matters, read [Discussion Continuity](references/discussion-continuity.md), then Track Work before record operations. Preserve the state that made memory necessary, not an empty shell or transcript. Keep the outcome separate from the current approach and retain material uncertainty instead of describing proposals as settled work.
-
-```text
-Discuss establishes supported meaning
--> Track Work preserves material state
--> Discuss continues or returns the direction to Workflow
-```
-
-The record does not select work or grant authority. Propose independent review, a local commit, a user decision, or a continuity checkpoint only when it protects a material boundary; Workflow selects it.
-
-## Converge And Return
-
-End the current discussion when the next sound action no longer depends on unresolved direction, or when a bounded learning action, missing user decision, wait, or stop is clear. Do not continue merely because more detail could be explored.
-
-When the user requests execution, return to Workflow to establish its outcome, scope, and user-facing return condition. If the user delegates the remaining investigation and implementation, do not require them to finish planning it.
-
-Return only what the next route needs: supported understanding, tentative approach, material open questions, relevant evidence, recommended or accepted next action, continuity, and authority state.
-
-- Stable accepted content needing a durable source -> [Write Spec](../write-spec/SKILL.md).
-- A supported ordered strategy needing a durable artifact -> [Write Plan](../write-plan/SKILL.md).
-- Covered concrete work -> Workflow and Execute Work.
-- One blocking owner choice -> Decision Gate.
-- Unsupported failure cause -> Diagnose Failure.
-- No action needed -> answer or stop.
-
-Neither an artifact nor a planning milestone is mandatory. Stop recommending or preserving once the agreed discussion result is supported; do not begin implementation without the execution agreement.

package/skills/evaluate-skill/SKILL.md

@@ -1,219 +0,0 @@
----
-name: evaluate-skill
-description: Use when evaluating or comparing agent-skill behavior.
----
-
-# Evaluate Skill
-
-Determine whether an exact skill package changes agent behavior as intended under declared pressure. Evidence outranks confident prose.
-
-A **group** asks one behavioral question through exactly two variants:
-
-- `baseline`: no target skill for a new skill, or one exact immutable previous package for a revision;
-- `candidate`: one exact new or updated package.
-
-The **subject** performs the declared task under one variant. The **evaluator** isolates subjects and preserves canonical evidence. The **deterministic grader** derives fixed mechanical facts after run persistence. A **suite** runs an ordered set of independent groups.
-
-Evaluate Skill does not author or revise skills, decide semantic quality, claim readiness, or choose publication. [Write Skill](../write-skill/SKILL.md) owns package preservation and revision. The active agent or user judges unresolved meaning. The user decides whether to revise, use, publish, or reject the skill.
-
-Inline examples teach the subject and are part of the candidate intervention. They are not independent evaluation evidence. Keep deterministic criteria and review questions outside natural subject prompts.
-
-## Route From Existing Evidence First
-
-Before proposing a run or revision:
-
-- inspect adequate saved evidence;
-- reuse an existing group unchanged when it still preserves the question, pressure, variants, and fixed criteria;
-- use saved views and raw artifact reads when a complete result already answers the question;
-- preserve partial infrastructure evidence without converting unavailable behavior into pass or fail;
-- do not mutate canonical evidence or erase an unfavorable result.
-
-For a draft-only request, use Write Skill. Do not fabricate behavioral evidence.
-
-A revision comparison requires an exact immutable baseline identity. If none exists, return to Write Skill to preserve the complete current package before revision. Evaluate Skill consumes baseline and candidate identities; it does not create a baseline by editing the package it is evaluating.
-
-## Name One Behavioral Question
-
-Name the exact claim and observing mechanism before choosing the group shape.
-
-Evidence classes include:
-
-- **Description activation:** did a natural prompt cause the exact target to be read, and when?
-- **First-read body behavior:** did explicit body delivery guide the subject using only guaranteed context?
-- **Nearby behavior:** did a close case avoid activation or load without hijacking the task?
-- **Dependency composition:** did exact ordered skills, resources, and context work together?
-- **Retained use:** did guidance remain useful on later declared turns without redelivery?
-- **Artifact outcome:** did files, structured state, events, and responses match fixed criteria?
-- **Cross-host behavior:** did the same behavioral question hold on every named host?
-
-One evidence class does not prove another.
-
-```text
-successful read
-≠ behavioral compliance
-
-explicit body delivery
-≠ natural activation
-
-one turn
-≠ retained use
-
-ambient installation
-≠ declared composition
-
-correct behavior
-≠ proof that the target caused it
-```
-
-Read [Evaluation Design](references/evaluation-design.md) before choosing or materially changing the question, evidence class, group shape, pressure, or baseline/candidate boundary.
-
-## Design The Smallest Valid Comparison
-
-Before subject output exists:
-
-1. fix one behavioral question;
-2. fix deterministic expectations and review questions;
-3. preserve the earliest natural prompt or strongest pressure capable of distinguishing behavior;
-4. declare exact baseline and candidate identities;
-5. keep prompt or turns, fixture, tools, model, thinking, other skills, context, runtime, and criteria fixed except for the target difference;
-6. run one group or an ordered suite serially;
-7. inspect canonical evidence and deterministic facts before judging meaning;
-8. classify the failed boundary before proposing revision;
-9. return one measured revision target to Write Skill;
-10. rerun the complete fixed group with both variants after a behavioral change.
-
-For a new skill:
-
-```text
-baseline: no target skill
-candidate: exact candidate package
-```
-
-For a revision:
-
-```text
-baseline: exact previous package
-candidate: exact revised package
-```
-
-For a description-only revision, keep body, references, scripts, and other resources byte-identical.
-
-If both variants pass, the pressure may be weak or the baseline already sufficient. If both fail, distinguish skill, fixture, dependency, environment, host, isolation, and criterion failures before revising instructions.
-
-## Declare The Complete Environment
-
-Use the exact [Evaluation Definition Schema](references/evaluation-definition-schema.md) when authoring or checking group and suite JSON.
-
-Declare:
-
-- prompt or ordered turns;
-- fixture;
-- exact ordered skill packages and target index;
-- working-tree or Git source identity;
-- context resources;
-- tools;
-- model and thinking;
-- runtime host and extension bundles when needed;
-- literal and inherited environment sources;
-- deterministic expectations and comparison IDs;
-- review questions.
-
-Snapshot every declared subject resource. Ambient installation is not declared composition.
-
-Criteria and review questions remain outside the subject prompt.
-
-## Run And Preserve Canonical Evidence
-
-Before operating the evaluator, resolving paths, interpreting states, or reasoning about host execution, read [Execution and Evidence](references/execution-and-evidence.md).
-
-Use the canonical [skill evaluator](scripts/skill-eval.mjs):
-
-```text
-node <evaluate-skill-directory>/scripts/skill-eval.mjs run <suite-or-group-path> [--group <id-or-position>] [--variant baseline|candidate]
-node <evaluate-skill-directory>/scripts/skill-eval.mjs view <result-id-or-directory> [--group <id-or-position>] [--variant baseline|candidate]
-```
-
-Run from the definition root.
-
-With no selectors, run or view every suite group and both variants. Selectors narrow execution or viewing scope; they do not modify definitions.
-
-Canonical results live under:
-
-```text
-<definition-root>/.skill-eval/runs/<result-id>
-```
-
-A view is a projection of saved evidence, not its canonical source. Use ordinary file tools when exact run, event, transcript, response, stderr, workspace, definition, grade, context-observation, or group artifacts matter.
-
-Do not invoke archived evaluators.
-
-## Derive Facts Without Inventing Meaning
-
-Append deterministic grades only after canonical run evidence exists.
-
-Deterministic checks may establish exact facts such as:
-
-- skill or resource reads;
-- file and path state;
-- changed paths;
-- file or response text;
-- JSON validity or values;
-- tool-call outcomes and argument predicates;
-- context text at a selected surface, request, and turn;
-- factual baseline-to-candidate transitions.
-
-A failed check remains ordinary behavioral evidence. It does not turn a valid subject run into infrastructure failure.
-
-Missing evidence remains unavailable.
-
-Malformed expectations or grading failures produce separate `grade-error` evidence and do not rewrite canonical run evidence.
-
-A transition such as `fail-to-pass` is a factual comparison. It does not mean bad-to-good, not-ready-to-ready, or rejected-to-promotable.
-
-## Review Meaning After Evidence Exists
-
-After canonical evidence and deterministic grades exist, read [Review and Revision](references/review-and-revision.md) when:
-
-- evidence conflicts;
-- semantic meaning remains unresolved;
-- the failed boundary must be classified;
-- a revision target must be selected;
-- rerun scope is uncertain.
-
-The evaluator does not launch an automatic semantic grader.
-
-The active agent or user may judge reasoning quality, authority preservation, architectural fitness, recommendation quality, or semantic completeness. Keep that judgment, cited evidence, uncertainty, and limits outside canonical run and grade state.
-
-## Return Revision To The Author
-
-When evidence supports a candidate change:
-
-1. identify the exact failed boundary;
-2. preserve the canonical result path and relevant evidence;
-3. state one measured revision target;
-4. keep unrelated instructions and criteria stable;
-5. return revision to Write Skill;
-6. rerun the complete fixed group with both variants after the change.
-
-Do not edit the skill from Evaluate Skill.
-
-If the evaluation definition or criterion is wrong, preserve the old result and state that it no longer answers the revised question. Do not reinterpret it as evidence for the new question.
-
-## Report And Stop
-
-Report:
-
-- what ran;
-- exact baseline and candidate identities;
-- selected groups and variants;
-- deterministic results;
-- infrastructure failures, cancellation, or unavailable evidence;
-- viewed scope;
-- canonical result paths;
-- what the evidence proves;
-- what it does not prove;
-- any supported failed boundary or revision target.
-
-Stop rather than overclaim when required activation, first-read, composition, retained-use, isolation, artifact, or host evidence is unavailable.
-
-The active agent or user judges unresolved behavior. The user decides whether to revise, use, publish, or reject the skill.