@hassangameryt/freeflow 0.3.0 → 0.4.0

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

@@ -0,0 +1,87 @@
+# Agent-First Instructions
+
+Read this when a concrete first-read failure involves wording, placement, undeclared context, or author explanation.
+
+## 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, or accidental earlier read.
+- Make required reads explicit before their content is used.
+
+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 failure boundary;
+- states an evidence, exit, or stop condition;
+- provides a compact example that resolves a likely misclassification.
+
+Translate rationale into a direct rule plus only the why needed to generalize. Translate debate into the selected boundary and stop condition. Omit rejected drafts, conversation history, and explanation whose only audience is the author.
+
+## Strengthen Rules
+
+A useful rule names:
+
+- the observable trigger or pressure;
+- the required or forbidden action;
+- the evidence, exit, 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.
+
+## Pair Negative Rules With The Route
+
+```text
+Bad:
+Do not recreate the old worker/verifier architecture.
+
+Better:
+The active agent owns implementation and verification.
+Workflow selects optional independent review.
+```
+
+```text
+Bad:
+Do not implement the recommendation.
+
+Better:
+Return the recommendation to Workflow.
+Implementation requires authorized execution.
+```
+
+A negative rule may preserve an invariant directly:
+
+```text
+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.
+
+Repeat shared policy only where a short local reminder prevents a real failure. Do not copy an owning workflow into a method skill.
+
+After editing, rerun the same first-read pressure while keeping unrelated rules stable.

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

@@ -0,0 +1,63 @@
+# Progressive Disclosure
+
+Read this before adding or reorganizing references and scripts.
+
+Make the first-read route understandable, then move only separately owned or conditional depth out of the active body.
+
+## Dependency Direction
+
+```text
+description
+-> SKILL.md
+-> required or conditional reference or script
+```
+
+The description routes the first useful read. `SKILL.md` establishes the job, normal method, necessary terms, and stop conditions. A required resource must be linked before the body relies on it. A conditional resource may rely on language already established by the body.
+
+Do not hide a definition, rule, or step needed to recognize the normal route in an unannounced reference. That is progressive reconstruction, not disclosure.
+
+## Add A Required Reference When
+
+- 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.
+
+Required does not mean implicit. The body must say when to read the resource and must not act as if unread content were already known.
+
+## Add A Conditional Reference When
+
+- 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.
+
+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.
+
+## 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.
+
+A script does not require an earlier failure. Do not script ordinary shell commands merely to look complete.
+
+## Link At The Decision Point
+
+A resource link should tell the agent when it becomes useful:
+
+> Read the integration-evidence reference when the claim depends on host dispatch or an installed artifact.
+
+Avoid vague resource lists such as “See references for more information.”
+
+## Resource Test
+
+For every extra file, answer:
+
+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?
+
+If those answers are weak, remove the resource.