@hassangameryt/freeflow 0.3.0 → 0.5.0

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

@@ -1,70 +1,156 @@
 # Plan Shapes
 
-Use this for strict-workflow, high-risk, durable, or delegated plans.
+Read this when choosing the structure, destination, identity, or revision shape of an ordered Plan. Use only the sections the Plan needs.
 
-## Durable Plan Identity
+## Destination And Durable Identity
 
-When saving a plan that future agents or teammates will rely on, start with a compact header:
+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
-> **Doc ID:** PLAN-001-billing-webhook-api
-> **Date:** 2026-05-26
-> **Owner:** Hassan Mohiddin
-> **Type:** Plan
-> **Status:** Ready
-> **Source:** docs/specs/billing-webhook-api.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>
 ```
 
-Rules:
+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`.
 
-- `Doc ID`: stable and readable. Prefer `PLAN-###-slug` when no repo convention exists.
-- `Owner`: use the spec/product owner when known. In normal workflow, use `User` only when the requester is the only known owner.
-- `Status`: use `Draft` when decisions/checks are still incomplete; use `Ready` when the plan is executable.
-- `Source`: cite the approved spec, clarified context, issue, ADR, or docs used as authority.
+Add dates, supersession links, or approvers only when useful and reliable.
 
-In strict-workflow for security, billing, privacy, public API, migration, data-loss, or architecture work, stop and ask if owner/status/source would be guessed.
+## Start With Source And Boundaries
 
-Do not add a changelog on first creation.
+Make the execution boundary and its dependencies clear:
+
+```text
+Goal:
+Source and linked artifacts:
+Scope:
+Non-goals:
+Accepted decisions:
+Assumptions:
+Dependencies:
+Required order:
+```
 
-## Lightweight Plans
+Link accepted behavior, architecture, and decisions instead of copying their rationale. 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.
 
-Use for low-risk context-backed work:
+## 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>
+...
+```
 
-- goal
-- source context
-- files likely touched
-- short slices
-- checks
+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.
 
-Mention that a spec is preferred when no approved spec exists, but do not add artifact pressure for tiny reversible work.
+## Define Phases And Slices
 
-## Normal Plans
+A phase groups slices that produce one meaningful integrated outcome. State its purpose, dependencies, and completion condition.
 
-Use for spec-backed feature work:
+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.” Plan approval authorizes listed local commits subject to live evidence and Commit Work inspection, but not 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:
+```
 
-- goal
-- source context
-- non-goals if the spec has them
-- files likely touched
-- vertical slices, each with tests/checks
-- stop conditions
-- final verification
+Useful invalidation conditions include:
 
-Each slice should produce a reviewable state, not just a list of files to edit.
+- 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.
 
-## Strict Or Delegated Plans
+These conditions stop or revise the affected Plan. They are not alternate branches. Do not use a narrow final check to imply broader completion.
 
-Use for high-risk work or work another agent will execute:
+## Revise Or Supersede
 
-- durable plan identity
-- goal and source authority
-- explicit assumptions from source truth
-- likely files/modules, with "find existing pattern first" when unknown
-- vertical slices with expected red/green checks
-- review checkpoints before risky behavior lands
-- stop conditions for source-truth conflicts or owner-owned decisions
-- final verification and handoff criteria
+A local implementation detail, expected result, or completed slice does not revise the Plan.
 
-Call out sensitive boundaries directly: auth, public API shape, billing behavior, privacy/security, data loss, migrations, compatibility, and rollback.
+For a founded material change, update only the affected strategy and dependencies, record why it changed, preserve prior rationale, and update linked artifacts only when their content changed.
 
-Do not hide ambiguity as implementation detail. If endpoint shape, auth semantics, payload fields, billing behavior, or rollback expectations are missing, stop and ask before writing an executable plan.
+Use a superseding Plan when editing in place would obscure what was originally reviewed. Route a materially revised or superseding Plan through artifact review again.

package/skills/write-skill/SKILL.md

@@ -1,88 +1,119 @@
 ---
 name: write-skill
-description: Use when creating, rewriting, tightening, or reviewing an agent skill's instructions, trigger description, structure, examples, or bundled resources.
+description: Use when creating or revising an agent skill.
 ---
 
 # Write Skill
 
-Use Anthropic/Claude `skill-creator` guidance as the structure and progressive-disclosure authority when available. Do not copy it into this skill.
+Write the smallest agent-first skill that changes one named behavior.
 
-Use concise, behavior-shaping wording. Prefer sharp rules, concrete triggers, and stop conditions over explanation or filler.
+## Establish The First Read
 
-## Job
+Before writing, identify:
 
-Write the smallest skill that changes behavior.
+- the behavior and failure the skill must change;
+- the earliest natural prompt or situation where its guidance becomes useful;
+- the cues an agent can observe before reading the body;
+- the context guaranteed to be loaded before this skill;
+- a nearby case that should not be hijacked.
 
-Start with one `SKILL.md`. Add other files only when the skill would fail without them.
+A description cannot rely on terminology or classifications taught only inside the skill. The body must work for an agent reading it for the first time with only declared guaranteed context.
 
-Direct `/write-skill`, "production-ready", "complete", or "add examples/references/scripts if useful" does not override the smallest-skill default or the repo's skill-file rules.
+If public behavior, dependencies, safety, or compatibility remain unsettled, stop and resolve that boundary before encoding it.
 
-Do not add references, examples, README files, changelogs, or metadata when a compact `SKILL.md` can hold the behavior.
+## Preserve Before Substantial Revision
 
-Do not add helper scripts for commands the agent can run directly, such as `git log`, `git diff`, search, formatting, or line counts. Scripts are for repeated deterministic work that would be risky or wasteful to retype.
+Before rewriting or substantially editing an existing skill, snapshot the complete current package—`SKILL.md`, references, scripts, and other owned resources—and record an exact identity. Use a recoverable Git ref or task evidence outside the active package so the rewrite cannot replace its own baseline.
 
-Treat the repo's line budget as a best practice, not a hard cap. If none exists, aim to keep `SKILL.md` under 100 lines for normal skills. Let deep skills exceed it when the active rules, examples, or structure clearly earn their place.
+A small local wording correction does not need an extra snapshot when the exact prior state is already recoverable and the change does not alter behavior, dependencies, or package structure.
 
-## Description First
+## Write The Description
 
-The description controls activation. Make it specific enough to route the skill without making it broad enough to hijack unrelated work.
+Optimize for the first useful read, not repeated reads.
 
-Use:
+- State the broad core job in plain language.
+- Use cues observable in the user request or immediate task state.
+- Prefer broad recall when loading the skill is safe and the body can exit cleanly.
+- Do not require the agent to predict an internal classification taught only after activation.
+- Do not turn the description into an exhaustive trigger taxonomy or compressed summary of the body.
+- Treat “Use when…” as useful advice, not required grammar.
 
-- What the skill does.
-- When to use it.
-- Concrete trigger situations.
+A nearby case may pass by not loading the skill or by loading it and exiting without changing the task incorrectly. Do not narrow a description solely to prevent harmless reads, and do not broaden it until the skill routinely overrides the actual owning job.
 
-Avoid:
+Read [activation boundaries](references/activation-boundaries.md) when the boundary is unclear or evidence shows missed, late, early, or task-hijacking activation.
 
-- Generic helper language.
-- Marketing copy.
-- Long taxonomies.
-- Claims about quality.
+## Write For The Executing Agent
 
-## Wording Discipline
+1. Establish the skill’s job immediately.
+2. Define necessary terms before relying on them.
+3. Put rules where the agent first makes the affected choice.
+4. Keep the normal route understandable from `SKILL.md`; when it requires another resource, name that dependency and its read condition before relying on it.
+5. Say what to do, what not to do, and when to stop, exit, or route.
+6. Lead with required behavior. Use a negative instruction only to block a plausible or observed failure, and pair it with the positive action, exit, or route.
+7. Use direct instructions that change action or judgment.
+8. Include why only when it helps the agent generalize, choose correctly in an unseen case, or avoid a harmful literal reading.
+9. Repeat a shared rule only when a local reminder prevents a real failure; do not copy the owning workflow.
+10. Keep authoring status, evaluation summaries, evidence gaps, changelog notes, and readiness prose out of the executing skill.
 
-Every sentence should either route, constrain, stop, or guide behavior.
+Use discussion, research, and author reasoning to understand the target behavior. Do not copy conversation history, author debate, iteration notes, rejected drafts, or explanation written for collaborators into the skill. Translate that context into only the instructions, definitions, boundaries, and examples a first-time executing agent needs.
 
-Prefer sharp rules over explanations. Prefer one good example over a paragraph.
+A skill may rely on guaranteed base context. Do not assume an optional sibling skill, reference, or accidental earlier read. Link dependencies and state when to read them.
 
-Small wording changes can alter agent behavior. Change one pressure point at a time when possible.
+Read [agent-first instructions](references/agent-first-instructions.md) when wording, placement, undeclared context, or author explanation is obscuring execution.
 
-Use direct verbs:
+## Use Examples Deliberately
 
-- Inspect.
-- Stop.
-- Ask.
-- Do not edit.
-- Verify.
-- Report.
+Add a compact behavioral example when prose alone leaves a likely misclassification. Show the observable situation and the required action, stop, exit, or route.
 
-Avoid vague verbs:
+Keep examples general enough to transfer beyond one fixture. Do not turn the body into a transcript, test suite, or scenario catalog. Inline examples teach; behavioral evals test whether the skill changes behavior under pressure.
 
-- Consider.
-- Ensure.
-- Leverage.
-- Try to.
-- Be mindful.
+## Add Resources Only When Needed
 
-## Placement Discipline
+Read [progressive disclosure](references/progressive-disclosure.md) before adding or reorganizing references and scripts.
 
-Order rules by behavioral priority, not topic neatness.
+Start with one `SKILL.md`. Remove repeated prose and low-value checklists before expanding the file set.
 
-Put hard stop conditions before normal workflow details.
+- Add a required reference when normal execution genuinely needs separately owned depth; link it before the dependency is used.
+- Add a conditional reference when a distinct branch needs depth that would obscure the normal route; state the observable condition for reading it.
+- Add a script for repeated deterministic work or a feature the skill owns when automation is safer, clearer, or materially less wasteful than retyping it.
+- Link every agent-facing reference, asset, declared dependency, and executable entrypoint from `SKILL.md`; internal implementation modules need not be linked.
+- Keep owned resources inside the skill package unless a declared package dependency is required.
+- Treat unlinked-file inspection as factual inventory, not an automatic defect.
+- Do not add resources merely to make the package look complete.
 
-Put source-of-truth, user-owned decision, safety, and verification rules above convenience rules.
+There is no universal body template, section inventory, wording rule, file-count target, or requirement that a script follow an earlier failure.
 
-Do not hide the real constraint in a later caveat.
+## Evaluate The Behavioral Claim
 
-## Revision Rule
+Static validation proves structure, not activation or behavior. Name the exact claim being tested: description activation, first-read body behavior, nearby behavior, dependency composition, retained use, or artifact outcome.
 
-Do not add prose because the skill "could be clearer." Add or move wording because an eval, user failure, or concrete pressure case showed a behavior gap.
+Use [Evaluate Skill](../evaluate-skill/SKILL.md) to compare exact baseline and candidate environments under fixed declared inputs. Preserve adequate existing evidence, revise one measured pressure point at a time, and rerun the complete fixed group after a behavioral change.
 
-When improving a skill after a failure:
+Do not claim activation from body injection, retained use from one turn, or dependency behavior from ambient context. Keep behavior conclusions and missing evidence in the owning evaluation, Working Record, or delivery response rather than annotating the executing skill.
 
-1. Name the failed behavior.
-2. Find the sentence that should have prevented it.
-3. Tighten wording or placement.
-4. Keep unrelated sections still.
-5. Re-run the smallest relevant eval.
+## Check The Package
+
+Use the bundled [skill author](scripts/skill-author.mjs) for deterministic structure work:
+
+```text
+node <write-skill-directory>/scripts/skill-author.mjs init <directory> --name <name> --description <text>
+node <write-skill-directory>/scripts/skill-author.mjs validate <directory> [--package-root <directory>]
+node <write-skill-directory>/scripts/skill-author.mjs inspect <directory> [--package-root <directory>]
+```
+
+Choose the command by job:
+
+- `init`: use only for a new package. It creates the directory and minimal `SKILL.md` and refuses to overwrite an existing one.
+- `validate`: use after structural or resource changes and before claiming structural validity. It checks frontmatter, the top-level heading, recursive links, package dependencies, cycles, and containment.
+- `inspect`: use when body sizes, resource classes, scripts, unlinked files, and validation findings are needed. It reports facts rather than quality.
+
+Commands emit JSON. Invalid structure still emits its report and exits nonzero; command errors emit structured error JSON.
+
+- Package root defaults to the nearest `package.json` ancestor, falling back to the skill directory’s parent. Use `--package-root` to set it explicitly.
+- Frontmatter accepts flat plain strings or JSON-compatible double-quoted strings. Double-quote values when there is any ambiguity, especially punctuation, numbers, booleans, or null-like text.
+
+Never import or invoke deprecated tooling.
+
+## Stop
+
+Stop when the requested skill is minimal, executable on first read, honest about its dependencies, and free of author-facing status. Stop and ask when public behavior, activation boundaries, dependencies, safety, or compatibility cannot be settled from evidence. Do not add resources or procedure merely to make the package look complete.

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

@@ -0,0 +1,62 @@
+# Activation Boundaries
+
+Read this when an activation boundary is unclear or evidence shows missed, late, early, or task-hijacking activation.
+
+A description should make the skill available at the earliest useful moment without requiring language introduced by the skill itself.
+
+## Diagnose The First Read
+
+Identify:
+
+- the earliest natural prompt or state where the method can change behavior;
+- cues visible before the body is read;
+- context guaranteed before activation;
+- the consequence of missing that read;
+- the consequence if a nearby prompt also loads the skill.
+
+Do not optimize for repeated reads. Diagnose the first decision the skill should influence.
+
+## Check The Cues
+
+Useful cues include the skill’s job, natural user verbs, visible task situations, and distinctions from neighboring jobs.
+
+Reject cues that depend on:
+
+- vocabulary defined only in the body or an optional sibling;
+- future-duration guesses;
+- unexplained classifications or named phases;
+- generic “help with” or “improve” language;
+- marketing claims or exhaustive trigger catalogs.
+
+Guaranteed base context may define a term. Otherwise use plain observable language.
+
+## Test Nearby Behavior
+
+A nearby case can pass in two ways:
+
+- **Non-trigger:** the skill should not load.
+- **Safe read:** loading is acceptable, but the body exits or defers without applying the wrong method.
+
+Do not narrow a description solely to prevent harmless reads. Do not broaden it until the skill routinely overrides the actual owning job.
+
+## Examples
+
+Broad core trigger:
+
+> Use when committing work.
+
+Over-specified trigger that hides the job behind later workflow details:
+
+> 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 can exit when the local interface remains sound; the description need not encode every structural-pressure case.
+
+## 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. Composition tests declared dependencies. Multi-turn evidence tests later use. Artifact or transcript evidence shows whether the loaded skill helped or hijacked behavior.
+
+Preserve the earliest useful positive prompt and at least one close nearby case before making a broad activation claim.

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.