@hassangameryt/freeflow 0.7.3 → 0.9.0

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

@@ -1,190 +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.
-
-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,92 +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.
-
-## Establish The Artifact's Job
-
-Identify the artifact type, intended reader or future action, accepted scope, destination, and unresolved questions it must preserve.
-
-Answer questions about a Spec without editing it unless revision is requested. Use [Discuss](../discuss/SKILL.md) when direction or alternatives remain materially open, and [Decision Gate](../decision-gate/SKILL.md) for one blocking owner choice or source conflict. Do not repeat discussion that already settled the artifact's purpose.
-
-An agreement to draft a proposal permits proposed design, clearly labelled. It does not make that design accepted behavior. An agreement to implement accepted work may include documenting its supported contract; do not manufacture another user approval merely because a document was produced.
-
-## Establish The Current Source Basis
-
-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, what was proposed, what was accepted, and what an observation actually established.
-
-Preserve enough source identity to recover the basis of a consequential statement. For an approval such as "proceed," retain the proposal and response together when their scope matters. Authorization to investigate or draft an option is not acceptance of undisclosed production consequences.
-
-Do not infer requirements from nearby code, existing tests, or available machinery merely because those sources exist. A test can faithfully protect an unnecessary mechanism.
-
-## Write Only What The Intended Use Needs
-
-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 intended 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 must remain visible rather than being filled with invented mechanics.
-
-Keep distinguishable:
-
-- required behavior and accepted decisions;
-- supported facts and their evidence limits;
-- proposed implementation mechanisms;
-- tentative assumptions and open questions;
-- intentional deferrals and superseded direction.
-
-Use the repository's vocabulary rather than inventing a new status schema. Place a consequential uncertainty where the reader makes the affected decision, not in a distant caveat after confident requirements.
-
-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.
-
-## Do Not Promote An Approach Into A Requirement
-
-Before adding an obligation, identify its accepted source or why it is necessary for the stated outcome. A limitation of one implementation technique does not establish a need for stronger guarantees, host changes, new persistence, retries, or a subsystem.
-
-When a consequential choice remains, present its concrete effect and supported alternatives through its owner. Do not settle it through normative prose, an unexplained assumption, or a polished placeholder.
-
-Stop the affected writing when it would silently change behavior, scope, public interfaces, compatibility, sensitive policy, failure semantics, or hard-to-reverse design. Do not rewrite source truth to suit implementation, or reduce agreed scope into an unapproved MVP, roadmap, or later-version split.
-
-Open questions need not stop unrelated content. A proposal can be fit for discussion while remaining unfit to authorize or guide production implementation; state that boundary clearly.
-
-## Reconcile Material Changes
-
-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 those dependencies 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 retained as evidence or deferred possibilities. Conversely, do not keep using an older baseline after the user accepted a relevant change.
-
-Do not rewrite historical decisions as though they always contained the new choice. Follow repository policy for historical records and supersession.
-
-## Self-Review Once Before Use
-
-After checking source-backed factual claims, use [Review Artifact](../review-artifact/SKILL.md) for silent author self-review of the complete resulting 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, then recheck affected facts and review lenses. Return unresolved owner decisions instead of making the document internally consistent by inventing an answer.
-
-This is the author's ordinary self-review, not another mandatory review cycle. Do not dispatch an independent reviewer merely because a Spec was written or materially revised.
-
-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. Its report ends the review; findings require adjudication before revision or use.
-
-Review establishes fitness, not user acceptance or execution authority. Respect an explicitly selected approval checkpoint, but do not create one for every artifact by default.
-
-## Report And Stop
-
-Report the artifact path, type, intended use, source basis, material unresolved or contingent content, and actual review/acceptance status. Do not label author self-review as independent review or use an approval status without its source.
-
-Stop when the authorized artifact is fit for its stated use or its blocking decision/evidence limit is explicit. Return to the requesting activity; writing a Spec does not begin implementation or authorize another outcome.

package/skills/write-spec/references/artifact-standards.md

@@ -1,86 +0,0 @@
-# Artifact Standards
-
-Read this when a durable spec-like artifact needs a destination, identity, status, source trail, or revision history. Follow established repository conventions before introducing these defaults.
-
-## Choose The Destination
-
-Place the artifact where its intended readers and authority belong.
-
-- Use an established product, design, API, issue, migration, policy, or architecture location when one exists.
-- For a task-local artifact, read [Track Work](../../track-work/SKILL.md) and use the `specs/` location it owns unless the artifact should become canonical repo documentation.
-- Use the repository's issue tracker when the requested artifact is an issue and that system is available and intended.
-- Ask before choosing between task-local memory and canonical repository documentation when the distinction changes authority, review, or longevity.
-
-Do not create a new top-level docs convention for one artifact without a real need.
-
-## Give Durable Artifacts Identity
-
-Use the repository's required frontmatter or metadata format. When no convention exists and identity will help future readers, use a compact title and header:
-
-```md
-# Team Invitations API
-
-> **Doc ID:** SPEC-001-team-invitations-api
-> **Type:** API Contract
-> **Status:** Draft
-> **Owner:** User
-> **Source:** Working Record task-004 and accepted product decisions
-```
-
-Add only useful fields:
-
-- **Doc ID:** stable identifier when links, review history, or supersession need one.
-- **Type:** the artifact's actual job, such as PRD, Issue, Technical Design, API Contract, Migration Contract, or Decision.
-- **Status:** current artifact state under the repository or owner's vocabulary.
-- **Owner:** person or role with authority over the artifact's intent.
-- **Source:** compact pointers to accepted context and evidence.
-- **Date / Last Updated:** only when a reliable date matters.
-- **Supersedes / Superseded by:** when readers must follow artifact lineage.
-
-Do not invent an owner, approval, date, or authority merely to complete a header. Writing or reviewing an artifact does not make it `Approved`.
-
-## Represent Status Honestly
-
-Use the repository's statuses when available. Otherwise keep the vocabulary small, for example:
-
-```text
-Draft | Reviewed | Approved | Rejected | Superseded
-```
-
-The appropriate statuses depend on the artifact type. An issue, policy, ADR, and API contract need not share one lifecycle.
-
-Status communicates artifact state; it does not replace review evidence or user authority. Distinguish author self-review from selected independent review when reporting review status. Writing a Spec or Plan does not automatically select an independent reviewer.
-
-## Preserve Sources Without Copying Them
-
-Link to stable sources such as:
-
-```text
-file:<path>#<section>
-working-record:<task>/record.md#<section>
-commit:<sha>
-issue:<id>
-output:<output-id>
-session:<session-id>/turn:<turn-id>
-```
-
-Use identifiers that actually exist. Prefer links and concise quotations over copied inventories, logs, diffs, or transcripts.
-
-A source trail should let a future reader recover why the artifact says what it says. For consequential choices, preserve the relevant proposal, disclosed consequences, and acceptance source rather than an isolated “proceed” or an agent's approval summary. Distinguish accepted amendments from unselected experimental findings. This does not require preserving every conversation turn.
-
-## Revise Without Rewriting History
-
-Do not add a changelog on first creation unless repository policy requires one.
-
-For material revisions:
-
-- update the artifact's current content and status honestly;
-- preserve consequential rationale through a change note, decision record, supersession link, or version control;
-- record only changes that help readers understand current intent or avoid repeating rejected work;
-- do not turn the changelog into execution status or transcript history.
-
-Use the Working Record for task progress, slice history, and current execution state.
-
-## Keep The Artifact Usable
-
-A durable artifact should be identifiable, source-backed, and understandable without the original conversation. It should contain enough depth for its intended use while avoiding information owned by a Plan, Working Record, Handoff, or another canonical document.

package/skills/write-spec/references/decision-records.md

@@ -1,78 +0,0 @@
-# Decision Records
-
-Read this when writing or revising an artifact whose primary job is to preserve a decision and its rationale.
-
-## Choose The Right Record
-
-Use the smallest record that preserves the decision where future work will look for it.
-
-- **Working Record decision:** task-local choice that affects later slices or current task direction. [Track Work](../../track-work/SKILL.md) owns its `D-` ID, state, rationale, and supersession.
-- **Decision note:** durable product, policy, scope, compatibility, or technical choice that needs a separate document but does not require the repository's ADR process.
-- **ADR:** surprising, cross-cutting, or hard-to-reverse architecture or operational decision whose alternatives and consequences must remain durable.
-- **Owning spec:** keep a decision inside a PRD, API contract, technical design, or other spec when that artifact clearly owns the decision and a separate record would only duplicate it.
-
-Do not create a separate decision artifact merely because a decision occurred.
-
-## When A Separate Decision Artifact Helps
-
-A separate record is useful when the decision is:
-
-- hard or expensive to reverse;
-- surprising relative to repository or domain practice;
-- a real tradeoff among materially different paths;
-- cross-cutting across systems, teams, or operational boundaries;
-- likely to be challenged again without its original rationale;
-- intentionally rejected or superseded in a way future work must understand;
-- explicitly requested as a durable decision artifact.
-
-Ordinary reversible implementation choices, task progress, temporary constraints, assumptions, and unanswered questions do not belong in a durable decision record.
-
-## Write The Decision Clearly
-
-Use the repository's ADR or decision format when one exists. Otherwise adapt this shape:
-
-```md
-# Decision: <title>
-
-> **Doc ID:** DECISION-<stable-id>
-> **Type:** Decision | ADR
-> **Status:** Proposed | Accepted | Rejected | Superseded
-> **Owner:** <decision owner>
-> **Source:** <accepted context and evidence>
-
-## Context
-<Decision question, constraints, and evidence.>
-
-## Decision
-<Chosen path and exact scope.>
-
-## Alternatives
-<Only materially different alternatives and why they were not chosen.>
-
-## Consequences
-<Benefits, costs, risks, compatibility, operations, and follow-up obligations.>
-
-## Revisit Or Supersession
-<Evidence, conditions, or later decision that would reopen or replace it.>
-```
-
-State proposals as proposals. Do not write an assumption, reviewer suggestion, or agent preference as an accepted decision. For a consequential choice, identify the presented option, disclosed consequences, and acceptance source. Approval to investigate or draft an option does not establish acceptance of its eventual production requirements.
-
-## Preserve Authority And History
-
-Name who made or owns the decision when that matters. A reviewer can challenge a decision but cannot silently replace it. A Working Record, Plan, or Handoff cannot supersede a durable decision merely by describing a different path.
-
-When a decision changes:
-
-- preserve the old record as `Superseded` rather than rewriting it to match the present;
-- create or identify the replacement decision;
-- link both directions;
-- identify owning specs, plans, or policies whose current content depends on it and revise them when authorized;
-- mark dependent work contingent when a required decision or source revision remains unresolved;
-- preserve the evidence that justified the change.
-
-Live evidence may show that implementation violates a decision or that the decision is no longer viable. Use Decision Gate when resolving that conflict requires user authority.
-
-## Avoid Duplication
-
-Reference the decision from dependent artifacts instead of copying its full rationale. Keep task-local decisions in the Working Record unless they become durable beyond the task.

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

@@ -1,143 +0,0 @@
-# Spec Shapes
-
-Read this when choosing the structure of a spec-like artifact. These are composable shapes, not mandatory templates. Use only the sections the artifact needs for its intended use.
-
-## Product Spec Or PRD
-
-Use for a product, capability, workflow, or user-facing outcome.
-
-Possible sections:
-
-- problem and motivation;
-- intended outcome;
-- users or actors;
-- scope and non-goals;
-- user journeys or observable behavior;
-- requirements and constraints;
-- product, policy, or domain decisions;
-- edge and failure behavior;
-- acceptance criteria;
-- unresolved questions and source evidence.
-
-Do not turn a PRD into an implementation task list.
-
-## Issue Or Problem Specification
-
-Use when a durable issue must define a problem clearly enough to investigate, fix, or accept.
-
-Possible sections:
-
-- observed problem or requested change;
-- affected behavior and users;
-- current evidence, reproduction, or examples;
-- expected behavior;
-- scope and non-goals;
-- severity, constraints, and known impact;
-- acceptance criteria;
-- unresolved facts or owner decisions.
-
-Do not present a guessed cause or requested patch as established fact. A fix sequence belongs in a Plan after the cause and path are sufficiently understood.
-
-## Requirements Or Behavioral Specification
-
-Use when observable behavior and constraints matter more than implementation structure.
-
-Possible sections:
-
-- actors and preconditions;
-- required behavior and invariants;
-- inputs, outputs, states, and transitions;
-- errors, rejection, degradation, and recovery;
-- forbidden outcomes;
-- compatibility and data guarantees;
-- acceptance examples and evidence.
-
-Express behavior precisely without copying implementation logic into the contract.
-
-## Technical Design
-
-Use when the artifact must define an accepted technical direction in depth.
-
-Possible sections:
-
-- problem and current evidence;
-- goals and non-goals;
-- proposed architecture or design;
-- module, interface, state, and ownership boundaries;
-- data flow and persistence;
-- failure contract and recovery;
-- security, privacy, performance, and operational constraints;
-- alternatives and rationale;
-- compatibility or migration impact;
-- risks, validation, and unresolved design questions.
-
-A technical design may contain implementation detail when that detail defines the accepted design. Ordered phases and execution slices still belong in a Plan.
-
-### Implementation Decisions
-
-Include this subsection when consequential engineering choices must survive implementation handoffs or context loss. For selecting those choices, use [Design for Depth](../../design-for-depth/SKILL.md); this shape preserves their result rather than duplicating the design method.
-
-Capture only what the intended implementation needs:
-
-- selected representation, identity, state owners, and module responsibilities;
-- essential algorithm, effect ordering, update/invalidation, and failure behavior;
-- source basis, rationale, and invariants;
-- a plausible wrong implementation and the observer that distinguishes it;
-- required constraints, suggested mechanics, and implementer freedom;
-- unresolved assumptions and conditions requiring reconsideration.
-
-A compact type or control-flow sketch is useful when it removes consequential ambiguity. Mark illustrative code as such; it is not the behavioral oracle. Keep the applicable revision recoverable and update only decisions affected by new evidence. Do not require this subsection for a product-only artifact or an already clear local change.
-
-## API, Protocol, Or Interface Contract
-
-Use for a public or internal interface that callers will depend on.
-
-Possible sections:
-
-- interface, endpoint, command, event, or protocol name;
-- callers, roles, authentication, and permissions;
-- requests, inputs, responses, outputs, and schemas;
-- invariants and ordering;
-- errors and failure semantics;
-- idempotency, retries, versioning, and compatibility;
-- privacy, billing, data-safety, and operational constraints;
-- examples and acceptance evidence.
-
-Stop rather than inventing caller-visible behavior or compatibility promises.
-
-## Migration Contract
-
-Use when current and target states, compatibility, and safety obligations must be durable before execution is planned.
-
-Possible sections:
-
-- current and target contracts;
-- affected consumers, data, traffic, or configuration;
-- compatibility and support commitments;
-- data and state invariants;
-- cutover, rollback, or forward-recovery requirements;
-- observation and removal conditions;
-- consequential failure behavior;
-- acceptance and completion evidence;
-- decisions still required.
-
-Include ordering only when it is part of the accepted migration contract. Detailed execution phases belong in a migration or implementation Plan.
-
-## Decision Artifact
-
-Use when a durable choice and its rationale are the artifact's primary job. Read [decision records](decision-records.md) before choosing a task-local decision note, durable decision record, or ADR.
-
-Possible sections:
-
-- context and decision question;
-- decision and owner;
-- materially different alternatives;
-- rationale and evidence;
-- consequences and constraints;
-- revisit or supersession conditions.
-
-## Combine Carefully
-
-An artifact may combine shapes when it genuinely owns both jobs, such as a technical design containing an API contract. Keep each responsibility legible.
-
-Do not create an omnibus artifact merely to avoid links. Separate artifacts when they have different owners, statuses, audiences, lifecycles, or review boundaries.