@hassangameryt/freeflow 0.6.0 → 0.7.0

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

@@ -1,77 +1,127 @@
 # Progressive Disclosure
 
-Read this before adding or reorganizing references and scripts.
+Read this before adding or reorganizing references, assets, or scripts.
 
-Make the first-read route understandable, then move only separately owned or conditional depth out of the active body.
+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.
 
-## Dependency Direction
+## Preserve Dependency Direction
 
 ```text
 description
 -> SKILL.md
--> required or conditional reference or script
+-> required or conditional resource
 ```
 
-The description routes the first useful skill read. `SKILL.md` establishes the job, normal method, necessary terms, and stop conditions, then explicitly directs any reference read. References do not activate independently, and an introduction inside an unread reference cannot activate itself.
+`SKILL.md` establishes:
 
-Do not hide a definition, rule, or step needed to recognize the normal route in an unannounced reference. That is progressive reconstruction, not disclosure.
+- the job;
+- normal route;
+- necessary terms;
+- stop and return conditions;
+- observable resource read points.
 
-## State The Read Point
+A reference cannot activate itself. Do not hide the rule needed to recognize a reference inside that reference.
 
-Use one of three explicit read points:
+That is progressive reconstruction, not disclosure.
 
-- **Entry-required:** read before following the skill's normal route.
-- **Activity-required:** read before performing a named activity on the normal route.
-- **Conditional:** read only when an observable branch occurs.
+## Classify The Read Point
 
-Entry-required and activity-required resources are required references. Conditional resources are conditional references. The word “when” does not determine the class: “When designing a test, read Test Design” is activity-required because test design is normal TDD work.
+### Entry-required
 
-Do not call a required read recommended or optional. If skipping it preserves correct normal execution, it is not required. Avoid “read when unclear” when the reference teaches how to recognize or make the underlying decision; either make the read activity-required or keep enough recognition guidance in `SKILL.md`.
+Read before the skill can follow or reject its normal route.
 
-The body instruction and reference introduction must describe the same read point. An introduction may explain purpose, but must not narrow or widen the condition established by `SKILL.md`.
+Entry-required references are exceptional. Use one only when separation provides independent value, such as:
 
-## Add A Required Reference When
+- canonical reuse across packages;
+- separate ownership or lifecycle;
+- generated schemas or contracts;
+- compatibility or host constraints;
+- independently versioned external policy.
 
-- normal execution genuinely needs separately owned depth;
-- the body can identify and require the read before using that depth;
-- keeping the material inline would obscure the skill’s controlling rules;
-- the dependency is delivered and validated with the skill package.
+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.
 
-Required does not mean implicit or merely recommended. The body must command the read at entry or before the named normal activity and must not act as if unread content were already known.
+### Activity-required
 
-## Add A Conditional Reference When
+Read before performing one named normal activity.
 
-- the material is needed only for a distinct branch of work;
-- loading it every time would obscure higher-priority behavior;
-- the active body can name an observable condition for reading it;
-- the reference has one clear job and does not restate the full skill or Workflow.
+The skill may first:
 
-The condition must be observable before the read. Keep compact examples that teach the normal boundary in `SKILL.md`. Move a larger example set only when it serves a conditional branch and would obscure the normal route.
+- 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 feature or repeated operation;
-- retyping it is error-prone, unsafe, or materially wasteful;
-- its interface and failure behavior can be tested.
+- 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.
 
-A script does not require an earlier failure. Do not script ordinary shell commands merely to look complete.
+Do not script ordinary commands merely to make the package appear complete.
 
 ## Link At The Decision Point
 
-A resource link should tell the agent when it becomes useful:
+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.
 
-> Read the integration-evidence reference when the claim depends on host dispatch or an installed artifact.
+Prefer:
 
-Avoid vague resource lists such as “See references for more information.”
+> Read Test Design before designing or materially changing the behavior check.
 
-## Resource Test
+## Apply The Resource Test
 
-For every extra file, answer:
+For every extra file, ask:
 
-1. What normal dependency or conditional branch requires it?
-2. When can the agent recognize that read or run condition?
-3. What prior language does the resource assume, and where is it established?
-4. Why cannot the active body or a direct command do the job clearly?
-5. How will the resource be validated and kept consistent?
+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 those answers are weak, remove the resource.
+If separation changes neither loading nor ownership, inline the content or remove it.

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

@@ -0,0 +1,190 @@
+# 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.
+
+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/runtime/prompts/skills.md

@@ -1,65 +0,0 @@
-## Shared Terms
-
-- **Authority envelope:** the requested outcome, permitted effects, evidence boundary, and stop condition established by valid current authority.
-- **Owner:** the one activity or skill responsible for the current bounded activity. Methods, tools, reviewers, and domain guidance do not take ownership automatically.
-- **Bounded activity:** one coherent unit of discussion, preservation, work, evidence, or judgment that can be assessed as one result.
-- **Slice:** one coherent outcome that can be executed and checked as a unit. It may span several bounded activities and methods. Track Work gives it durable identity when task memory is needed.
-- **Evidence boundary:** the strongest claim the current observer can directly support.
-- **Self-review:** after initial evidence supports a bounded result, the producing agent silently checks it once for alignment, suitability, and unnecessary complexity before accepting or reusing it. Self-review is not independent review.
-- **Independent review:** separately selected judgment from a context that did not produce the reviewed state. It reports without editing and does not authorize correction.
-- **Checkpoint:** a deliberately selected decision, review, preservation, or delivery boundary that must be resolved before dependent work continues. A pause or bounded activity ending is not automatically a checkpoint.
-- **Re-entry:** return only to the narrowest owner whose responsibility changed, preserving valid work, decisions, and evidence.
-- **Supported Exit:** an evidence-supported answer, wait, pause, handoff, deferment, stop, controlled boundary, or completion.
-
-## Three Nested Loops
-
-One user-facing **Interaction Lifecycle** runs from Entry to Supported Exit:
-
-```text
-[Entry]
--> [Feedback Loop when needed]
--> [Supported Exit]
-```
-
-A later user turn or route-changing evidence begins another lifecycle.
-
-For each bounded activity, the **Feedback Loop** is:
-
-```text
-Orient
--> choose one owner
--> use the owner
--> gather or produce evidence
--> determine what the result proves
--> self-review the supported result
--> continue, correct, re-enter, ask, defer, stop, or exit
-```
-
-When the owner must touch the environment, the **Environment Interaction Loop** is:
-
-```text
-Need evidence or a covered effect
--> select and bound one action
--> choose the tool
--> execute once
--> observe
--> identify what changed
--> reconcile observation residency when available
--> return to the owner
-```
-
-The Environment Interaction Loop may run zero or more times inside one Feedback Loop. It never changes the owner or authority by itself.
-
-## Workflow Cue
-
-Workflow owns authority, one active owner, evidence-driven re-entry, and Supported Exit. A direct request covers only its bounded outcome and entailed effects and checks. Before uncovered active evidence, mutation, delivery, or another separately controlled action, state the purpose, action, expected result, and stop condition; ask once and wait. Mode, skills, memory, reviews, and new evidence do not grant authority.
-
-After context loss, rebuild the decision surface from current user direction, bounded task memory, and live evidence. If a Working Record exists, read Track Work before any record operation; use its `resume` view and current schema before mutation, even when another skill owns the surrounding work. If Workflow is unread, read it before consequential work or owner selection. Summaries and records preserve context but do not prove live state or create authority.
-
-## Action Selection Cue
-
-Before an uncertain, broad, or repeated environment interaction, use Action Selection to choose and bound one useful action. Return its observation and state change to the current owner. An obvious mechanical and directly verifiable action takes the fast path without manufactured alternatives.
-
-## Supported Exit
-
-Reach a Supported Exit only when fresh evidence supports the accepted outcome, required self-review and selected checkpoints are resolved, task memory and required artifacts are accurate, and no material contradiction, source conflict, or user-owned decision remains hidden. Report the outcome, evidence, limits, and current route.

package/skills/mode-contract/SKILL.md

@@ -1,104 +0,0 @@
----
-name: mode-contract
-description: Use when choosing, changing, or explaining how Freeflow mode applies to current work.
----
-
-# Mode Contract
-
-Apply the effective Freeflow mode without inferring a different mode from the task. Freeflow has exactly three mode values: `conversation`, `workflow`, and `strict-workflow`.
-
-A mode changes how work proceeds; it does not authorize work, widen the current authority envelope, resolve a user-owned decision, or override live evidence.
-
-## Establish The Active Mode
-
-A mode is active only when the host reports that Freeflow Skills are effective. Keep the supplied layers distinct:
-
-- **Repository default:** the shared `defaultMode` from `.freeflow/config.json`.
-- **Personal default override:** an optional per-checkout `defaultMode` from `.freeflow/local.json`.
-- **Session override:** an optional temporary mode managed by the host.
-- **Resolved mode:** session override, otherwise personal default override, otherwise repository or built-in default.
-- **Effective mode:** the resolved mode only while Skills are active; otherwise no Freeflow mode is effective.
-
-If runtime reports that modes are inactive, preserve the resolved mode as dormant state without applying it. If effective-mode evidence is missing, do not guess or activate a fallback. Read [Setup Freeflow](../setup-freeflow/SKILL.md) when the user wants to configure, enable, or repair Freeflow.
-
-Task shape does not change mode. A question during Workflow stays in Workflow; an implementation request during Conversation stays in Conversation until the user changes mode.
-
-## Follow The Effective Mode
-
-### Conversation
-
-Answer, discuss, critique, explore, and inspect existing evidence or sources without exercising target behavior or intentionally changing task state.
-
-Conversation permits passive observation only for task work. Active evidence generation and mutation or delivery require `workflow` or `strict-workflow` plus authority. If the user requests one, explain the mode boundary and ask them to switch through the host's mode control before proceeding.
-
-Ask only what the answer needs. Conversation mode does not require workflow artifacts, checkpoints, plans, specs, or independent review.
-
-### Workflow
-
-Use the adaptive [Workflow](../workflow/SKILL.md) for active evidence generation and consequential or mutating work. Inspect or ask when ambiguity changes the next action, create durable artifacts only when they preserve needed state or decisions, and verify claims against fresh evidence.
-
-Workflow mode does not itself authorize a slice or require every lifecycle phase.
-
-### Strict Workflow
-
-Use the same adaptive Workflow with stronger decision, evidence, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
-
-Apply that pressure when work materially affects security, privacy, billing, data loss, migrations, public interfaces, compatibility, deployment, or architecture. Use [Decision Gate](../decision-gate/SKILL.md) for choices or source conflicts that belong to the user in every mutating mode. Gather evidence for the relevant risk surface before crossing the boundary or claiming success.
-
-Select artifacts, checkpoints, verification, and independent review when they reduce material risk. Do not add them automatically merely because Strict Workflow is active.
-
-Strict Workflow does not grant authority, bypass safety, or turn every implementation detail into a user decision.
-
-## Change Mode Deliberately
-
-The user owns mode changes. Recommend `strict-workflow` when risk warrants it, but continue under the effective mode unless the user changes it or another workflow boundary blocks progress.
-
-A task type, risk classification, direct skill call, or workflow route does not switch mode. Invoking an execution skill during Conversation still does not authorize mutation.
-
-Use host-managed session control so the change takes effect before the model acts. A clear natural-language instruction may use the same control. Questions, examples, hypotheses, and tentative language do not change mode.
-
-```text
-Switch to conversation mode.                 -> session override
-Use strict-workflow for this session.         -> session override
-Should we switch to strict-workflow?          -> answer or discuss; no override
-Suppose the mode were conversation.           -> discussion; no override
-```
-
-Host-native controls are:
-
-```text
-Pi:
-/freeflow mode conversation
-/freeflow mode workflow
-/freeflow mode strict-workflow
-/freeflow mode reset
-
-Claude:
-/freeflow:mode-contract <conversation|workflow|strict-workflow|reset>
-
-Codex:
-$mode-contract <conversation|workflow|strict-workflow|reset>
-```
-
-Claude and Codex persist their override in plugin-owned session state keyed by the host session identifier. Pi persists it in branch-aware Pi session state. The override survives ordinary turns and supported resume, clear, and compact boundaries for that session; `reset` clears it and returns to the configured default. A new session starts from configured state.
-
-Treat only runtime-reported effective state as proof that the control succeeded. If the host reports missing session identity, unavailable writable plugin state, disabled Skills, or another failure, say that mode did not change. Do not compensate by editing a configured default.
-
-Mention mode only when the user asks, configuration is being discussed, or it changes the next action.
-
-## Change Defaults Separately
-
-A persistent default change is not a session-mode change. Determine which configured layer the user means before editing:
-
-- explicit **personal** or **local** default targets `.freeflow/local.json`;
-- explicit **shared**, **repository**, or **team** default targets `.freeflow/config.json`;
-- an unqualified “change the default mode” request leaves that scope user-owned—ask one direct local-versus-repository question and wait;
-- “global” is not a defined Freeflow layer—ask whether the user means this checkout's personal default or the shared repository default.
-
-Do not infer the target from which file already exists or from the current mode. Preserve unrelated settings in the selected layer.
-
-In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared defaults. In another host, an agent may update only the explicitly selected valid configuration layer. Session controls never modify either file.
-
-For agent-performed config edits, obey the effective mode when one exists. Conversation remains read-only. When no mode is effective because Freeflow is unconfigured, inactive, blocked by invalid config, or Skills are dormant, an explicit configuration or [Setup Freeflow](../setup-freeflow/SKILL.md) request governs the selected change; any dormant resolved mode is neither authority nor prohibition. User-operated host controls change their own state before the model continues.
-
-A current session override remains effective until reset even when a configured default changes. If repository config is missing or invalid, route to Setup Freeflow; a personal override cannot activate Freeflow. If local config is invalid, report the blocking layer and repair or remove it only with authorization. Do not silently overwrite either source. Use Decision Gate when the requested default conflicts with established source truth or accepted direction.