@hassangameryt/freeflow 0.5.0 → 0.7.0

package/skills/workflow/SKILL.md

@@ -1,91 +1,173 @@
 ---
-name: workflow
-description: Use when coordinating discussion, decisions, durable task memory, execution, verification, review, or a route change from feedback.
+name: "workflow"
+description: "Use when authority, current ownership, route changes, continuity, selected checkpoints, or Supported Exit must be coordinated across Freeflow activities."
 ---
 
 # Workflow
 
-Use feedback to choose the smallest useful next action. Treat work as an **Interaction Lifecycle** with an internal **Feedback Loop**, not a fixed sequence.
+Own the outer Interaction Lifecycle. Interpret and enforce authority, keep one current owner for each bounded activity, route only when evidence changes responsibility, select checkpoints deliberately, and determine when a Supported Exit is justified.
 
-The active agent owns understanding, routing, authorized work, verification, correction, and completion. It adjudicates selected review; independent judgment does not take over workflow control.
+Workflow does not create authority or supervise every action. It coordinates owners and methods without replacing their detailed jobs.
 
-Read the [expanded Workflow loop](references/workflow-loop.md) when the complete lifecycle, skill relationships, or exits are unclear. Read [domain skill composition](references/domain-skill-composition.md) when specialized engineering guidance must run inside the active route.
+Selecting a skill, method, lens, tool, artifact, review, checkpoint, domain guide, or compute profile never widens authority or changes the current owner automatically.
 
-## Route The Interaction
+## Enter Through Authority
 
-```text
-[Entry] -> [Feedback Loop when needed] -> [Supported Exit]
-   ^              ^        |                  |
-   |              |________|                  |
-   |__________________________________________|
-            later user turn or evidence
-```
+Interpret the whole user turn, current runtime state, and still-valid prior approval before consequential action.
 
-Entry begins with a user turn or new evidence interpreted through the Interaction Contract and effective mode. It may route directly to an answer, wait, deferment, or stop. When work is needed, choose the narrowest owner:
+Classify effects cumulatively when one activity contains more than one kind, using the Shared Terms definitions for passive observation, active evidence generation, and mutation or delivery.
 
-- **Understand and decide:** [Discuss](../discuss/SKILL.md), [Decision Gate](../decision-gate/SKILL.md), [Bypass](../bypass/SKILL.md), with [Design for Depth](../design-for-depth/SKILL.md) when the direction is design-bearing.
-- **Preserve memory or accepted artifacts:** [Track Work](../track-work/SKILL.md), [Write Spec](../write-spec/SKILL.md), [Write Plan](../write-plan/SKILL.md), and [Review Artifact](../review-artifact/SKILL.md).
-- **Execute and learn:** [Execute Work](../execute-work/SKILL.md), [Migration Work](../migration-work/SKILL.md), [Diagnose Failure](../diagnose-failure/SKILL.md), [Verify Work](../verify-work/SKILL.md), and [Review Work](../review-work/SKILL.md).
-- **Preserve or close out:** [Commit Work](../commit-work/SKILL.md), [Handoff](../handoff/SKILL.md), [Finish Branch](../finish-branch/SKILL.md), [Release Work](../release-work/SKILL.md), and [Launch Work](../launch-work/SKILL.md).
+A direct request authorizes its bounded outcome and entailed tools, checks, and reversible local choices. It does not authorize unrelated cleanup, another outcome, a separately controlled effect, or an action whose consequence could materially change the user’s choice.
 
-These are owners, not mandatory phases. Method and domain skills compose inside one active route without overriding accepted behavior, live evidence, or user authority.
+A Spec, Plan, Working Record, Handoff, review, recommendation, checkpoint, useful evidence, or silence may constrain or preserve work. None creates authority.
 
-## Authorize Or Wait
+Before active evidence generation, mutation, delivery, or another separately controlled action not covered by current authority, tell the user why it is needed, exactly what will happen, what evidence or result it should produce, and where it will stop. Ask one direct authorization question and wait. Do not perform the proposed action or dependent work while waiting.
 
-Before any state-changing or separately controlled action, identify the bounded action, confirm that the effective mode permits it, and establish its authority source. Authority may come from a clear direct request, explicit approval, or an action or checkpoint explicitly authorized through a user-approved Plan or discussion. An accepted Spec or Plan alone establishes direction, not execution authority. A Working Record may preserve authority but cannot create it.
+When authority, accepted intent, or the effect boundary is unclear, resolve that boundary before selecting an execution owner.
 
-If the action is not covered, recommend its exact purpose and scope, ask one direct authorization question, and wait for the user's response. Waiting means do not perform the proposed mutation, dispatch, or dependent next action. Mode, settled direction, a recommendation, review findings, silence, and task memory do not authorize work.
+## Choose And Keep One Current Owner
 
-Authorization covers the bounded outcome, not each tool call. Do not ask again for contained edits, tests, verification, or reversible local choices. Ask again when the result, scope, evidence boundary, stop condition, or separately controlled action changes.
+Choose the narrowest discoverable owner whose job matches the current bounded activity. The categories below are common owners, not an exhaustive list.
 
-Before authorized work begins, recommend Discuss only when user input could materially change the outcome, boundary, tradeoff, approach, or acceptance. Name the question and wait. Use Design for Depth while the direction remains design-bearing. Inspect facts and choose reversible local details without asking. If the user declines optional discussion, do not ask again without new evidence. A discussion recommendation creates no artifact or slice.
+### Understand or decide
 
-## Run One Feedback Loop
+- [Discuss](../discuss/SKILL.md) for materially open direction, alternatives, assumptions, or tradeoffs.
+- [Decision Gate](../decision-gate/SKILL.md) for one blocking user-owned choice or source conflict.
 
-For one bounded activity:
+Use [Design for Depth](../design-for-depth/SKILL.md) as a lens when direction is design-bearing. A lens does not become the current owner.
 
-1. Orient to accepted intent, relevant task memory, and live evidence.
-2. Use the owning skill to discuss, implement, test, observe, or otherwise act.
-3. Verify what the evidence proves at the required boundary.
-4. When supported, self-review once for alignment, suitability, and unnecessary complexity.
-5. Continue, correct, diagnose, revise, ask, defer, or stop from the result.
+### Produce, preserve, or judge durable state
 
-Self-review is silent and creates no formal judgment or cycle. Correct clear local issues within authority, re-verify, then freeze the supported state. Freezing does not itself close a current Track Work slice; selected review, checkpoints, discussion, and accepted in-scope correction may continue inside it. Further polish, advisory warnings, and unrelated issues require another selected slice.
+- [Track Work](../track-work/SKILL.md) for Working Record creation, recovery, reconciliation, and lifecycle.
+- [Write Spec](../write-spec/SKILL.md) for stable accepted content or contracts.
+- [Write Plan](../write-plan/SKILL.md) for stable ordered execution strategy.
+- [Review Artifact](../review-artifact/SKILL.md) for judgment of a durable guiding artifact.
 
-If verification fails, correct one clear local defect or diagnose an unsupported cause. Do not review unsupported work as ready. Handle only edge cases required by accepted behavior, observed evidence, or material safety. A stream of related patches routes to diagnosis of the shared requirement, cause, ownership, or interface.
+### Execute, investigate, verify, or judge work
 
-Continue only while authority remains clear, evidence supports the route, no checkpoint is due, and the work converges.
+- [Execute Work](../execute-work/SKILL.md) for concrete implementation, documentation, configuration, learning, or maintenance.
+- [Migration Work](../migration-work/SKILL.md) for moving consumers, state, or traffic between paths.
+- [Diagnose Failure](../diagnose-failure/SKILL.md) for unexplained or repeated failure.
+- [Verify Work](../verify-work/SKILL.md) for determining what direct evidence proves.
+- [Review Work](../review-work/SKILL.md) for implementation judgment, independent review, or adjudication.
 
-## Preserve Necessary State
+[TDD](../tdd/SKILL.md), [Simplify Code](../simplify-code/SKILL.md), domain guidance, references, and tools may supply the current owner’s method without becoming another owner.
 
-When authorized work is concrete and direction is settled, use Track Work to decide whether continuity needs a Working Record, then follow its result to Execute Work or wait. Create durable memory only when forgetting would risk misalignment: a Working Record for living task state, a Spec for stable accepted content, a Plan for ordered strategy, an ADR for a surprising hard-to-reverse decision, or a Handoff for point-in-time transfer.
+### Preserve, checkpoint, integrate, or deliver
 
-When an ongoing task resumes after compaction, summarization, clear, resume, or session navigation, read the complete owning Working Record before continuing and compare it with the conversation and live state. Another conversation branch may preserve memory, not authority.
+- [Commit Work](../commit-work/SKILL.md) for an authorized local commit or simple push.
+- [Handoff](../handoff/SKILL.md) for point-in-time continuation transfer.
+- [Finish Branch](../finish-branch/SKILL.md) for integration, preservation, discard, or branch closeout.
+- [Release Work](../release-work/SKILL.md) for versioned publication.
+- [Launch Work](../launch-work/SKILL.md) for production exposure, rollback, or recovery.
 
-Synchronize durable architecture, plugin, setup, or similar documentation when stabilized behavior or dependent work requires it—not after every slice. Never finish with a known required-doc inconsistency.
+### Apply modifiers and interaction control
 
-## Control Reviews And Checkpoints
+[Bypass](../bypass/SKILL.md) modifies explicitly selected optional Workflow pressure. It does not become the owner of the underlying activity.
 
-A local commit, independent review, correction, follow-up review, push, integration, release, or launch is separately controlled unless existing authority explicitly covers it. At a supported boundary, recommend a local commit only when it materially improves rollback, provenance, handoff, integration, or preservation; a slice ending alone is insufficient. When a useful boundary is unapproved, recommend its exact purpose and scope, then wait; do not stage, edit, dispatch, or cross the boundary from the recommendation.
+When the owner needs an environment interaction and the action or tool choice is not already obvious, use [Action Selection](../action-selection/SKILL.md). It returns the observation and state change to the same current owner.
 
-Specs and Plans receive separate independent Review Artifact after author self-review. Working Records do not by default. Select independent work review for sensitive, hard-to-reverse, architecture-bearing, strongly interacting, plan-selected, or explicitly requested boundaries—not merely because a slice ended. Reading a review skill does not create independence.
+When specialized engineering guidance must support the current owner, read [Domain Skill Composition](references/domain-skill-composition.md).
 
-Independent review ends with **Pass**, **Non-blocking**, **Inconclusive**, or **Blocking**. The active agent adjudicates the items and routes accordingly: proceed, proceed with explicit deferrals, gather missing evidence or a decision, or stop before the blocked boundary.
+Keep the current owner while its question, intended result, authority, and required observing boundary remain coherent. Methods, tools, feedback, profile transitions, and environment interactions do not create owner changes by themselves.
 
-Review findings are evidence, not commands, and do not authorize edits. Ask once for unapproved corrections plus any warranted focused follow-up, or corrections alone, then wait. A review budget caps dispatches; it does not authorize them. Return implementation corrections to Execute Work and artifact revisions to their owner, verify them, and run a focused follow-up only when needed and authorized. Never create an automatic review-fix-review loop or keep editing merely to obtain Pass.
+Recommend Discuss before authorized work only when user input could materially change the outcome, boundary, tradeoff, approach, or acceptance. Inspect available facts and choose reversible local details without unnecessary questions.
 
-## Route And Exit From Evidence
+## Route From The Result
 
-- **Continue:** evidence supports the current route.
-- **Correct:** one clear local defect preserves intent and scope.
-- **Broaden evidence:** the claim exceeds the check.
-- **Diagnose:** the cause is unclear or failure repeats.
-- **Discuss:** new options or invalid assumptions change direction.
-- **Track Work:** task memory or history must be reconciled.
-- **Revise Spec or Plan:** accepted content, contract, order, mechanism, dependencies, or checks changed.
-- **Decision Gate:** a user-owned choice or source conflict blocks progress.
-- **Stop or defer:** no safe worthwhile continuation remains.
+Run the guaranteed Feedback Loop through the current owner. Re-enter Workflow only when authority, ownership, required evidence, checkpoints, or the supported exit changes.
 
-Preserve valid work and revise only the affected layer. A supported exit may answer, wait, pause, hand off, defer, stop, preserve a controlled boundary, or complete the task.
+Route from what the result now supports:
 
-Claim completion only when fresh verification supports the outcome, self-review has no unresolved material issue, selected reviews are resolved, task memory is accurate, required artifacts are synchronized, and no user-owned decision or source conflict remains hidden. Report the outcome, evidence, gaps, and route. Use `Next:` only when one useful recommendation remains; it does not authorize action.
+- **Continue:** the current owner, intended result, authority, and required observing boundary remain coherent.
+- **Correct locally:** one clear defect preserves accepted intent and effects; return it to the producing owner, re-verify the affected boundary, and self-review the corrected state.
+- **Broaden evidence:** the claim exceeds the current observer; use Verify Work or return the missing evidence requirement to the current owner.
+- **Diagnose:** the cause is unclear, evidence conflicts, or correction repeats.
+- **Discuss:** assumptions, alternatives, strategy, or direction materially changed.
+- **Decision Gate:** one user-owned choice or source conflict blocks safe continuation.
+- **Track:** durable task state must be created, recovered, reconciled, or changed materially.
+- **Revise an artifact:** accepted content, strategy, decision, or transfer state changed; return to that artifact’s owner.
+- **Review:** selected judgment is needed after factual support.
+- **Checkpoint:** a selected boundary is due before dependent work.
+- **Stop or defer:** no safe, authorized, and worthwhile continuation remains.
+
+Preserve unaffected decisions, artifacts, work, and evidence. New evidence changes the route only where its consequence applies.
+
+Do not continue because implementation began, review unsupported work as ready, restart the task because one responsibility changed, or let a useful next action become implied authority.
+
+## Preserve Continuity Deliberately
+
+Decide whether losing current task state could cause later misalignment.
+
+Use Track Work when decisions, evidence, authority, current work, blockers, checkpoints, or the next useful action need durable recovery. Do not create a Working Record for a short disposable activity merely because work occurred.
+
+When a Working Record exists after compaction, summarization, session navigation, or ownership transfer:
+
+1. route record recovery and reconciliation through Track Work;
+2. compare recovered memory with the current user turn and relevant live state;
+3. return to the owner whose activity actually continues.
+
+After recovery, re-read the current owner’s skill when its exact method is absent, reopen only the sources or history needed for the next decision, and re-establish authority from valid current-session sources.
+
+Track Work owns record views, schemas, mutations, and lifecycle mechanics. Workflow does not reproduce them.
+
+A summary, historical skill body, Working Record, Plan, or Handoff preserves context. It does not create current authority, prove live state, or become profile-routing state.
+
+## Select And Route Checkpoints
+
+Select a checkpoint only when crossing it unresolved could materially endanger dependent work, rollback, provenance, transfer, integration, or delivery.
+
+A checkpoint may require:
+
+- a user decision;
+- selected independent review;
+- a local commit;
+- continuity transfer;
+- branch integration;
+- release;
+- launch.
+
+A pause, status update, bounded activity ending, completed implementation, passing check, or self-review does not create a checkpoint automatically.
+
+Workflow selects the checkpoint and the boundary it protects. Its owner performs it. Track Work preserves its selection and result when durable memory exists.
+
+Self-review remains part of the ordinary Feedback Loop and is never a checkpoint.
+
+Review Work owns review roles, findings, adjudication, judgments, and cycle limits. Workflow consumes the returned result and decides what responsibility follows. A review report, finding, judgment, or suggested remedy does not authorize correction or another review.
+
+When checkpoint evidence or conditions no longer hold, return the deviation rather than forcing the checkpoint. Cancel, replace, defer, or revise a selected checkpoint only through an explicit supported route, then reconcile durable state when present.
+
+Do not create an automatic review–fix–review loop. Do not keep editing merely to obtain Pass.
+
+A commit, handoff, integration, push, release, or launch remains separately controlled unless the authority envelope explicitly covers it.
+
+## Reach A Supported Exit
+
+A Supported Exit may answer, wait, pause, hand off, defer, preserve a controlled boundary, stop, or complete.
+
+Claim completion only when:
+
+- fresh evidence supports the accepted outcome at the required boundary;
+- every completed bounded activity received required self-review with no unresolved material issue;
+- selected reviews and checkpoints are resolved;
+- task memory and required artifacts accurately describe the supported state;
+- no material contradiction, source conflict, blocker, or user-owned decision remains hidden;
+- no separately controlled action is being implied as complete.
+
+Report proportionately:
+
+- the supported outcome;
+- strongest evidence and proof limits;
+- material unresolved or deferred state;
+- the current route when work continues or waits.
+
+A recommendation for a next action does not authorize it.
+
+## Stop
+
+Stop Workflow when:
+
+- a Supported Exit is reached; or
+- one current owner can continue without an unresolved authority, ownership, checkpoint, continuity, or route question.
+
+Resume Workflow only when feedback or evidence changes one of those boundaries.

package/skills/workflow/references/domain-skill-composition.md

@@ -1,57 +1,43 @@
 # Domain Skill Composition
 
-Read this when specialized engineering guidance must operate inside a Freeflow route.
+Read this when specialized engineering guidance must support the current owner.
 
-Freeflow chooses **what owns the current action**. Domain guidance supplies **how to perform the specialized engineering safely**. Do not turn a domain skill into a second workflow.
+Freeflow owns authority interpretation, current ownership, route changes, evidence honesty, checkpoints, continuity, and Supported Exit. Domain guidance supplies specialized engineering method. It does not become another Workflow, current owner, or authority source.
 
-## Keep Ownership Clear
+## Compose One Current Owner
 
-Freeflow owns:
+For the current bounded activity:
 
-- effective mode, authority, and route;
-- user decisions and source conflicts;
-- discussion, durable artifacts, slices, and route changes;
-- verification honesty, review calibration, checkpoints, and exits.
+1. keep one Freeflow current owner;
+2. add only the domain guidance required by the concrete technology, behavior, environment, or risk;
+3. use one primary implementation, diagnostic, verification, or review method at a time;
+4. retain [Design for Depth](../../design-for-depth/SKILL.md) only when direction is already design-bearing or evidence establishes structural pressure;
+5. select independent specialist review only when it materially protects a named boundary.
 
-Domain guidance may own techniques for frontend, accessibility, browser tools, security, performance, databases, APIs, CI/CD, observability, cloud platforms, migration, release, or deployment.
+Prefer repository policy, current primary sources, and technology-specific evidence over generic examples.
 
-Domain guidance never overrides accepted behavior, repository policy, owner decisions, failure contracts, or evidence requirements. When it conflicts with live source truth, inspect the conflict and use [Decision Gate](../../decision-gate/SKILL.md) if resolution changes behavior or material risk.
+Do not load a handbook because one keyword appears. Do not combine several overlapping methodologies merely because each contains useful advice.
 
-## Compose One Route
+## Preserve Workflow Boundaries
 
-For one current action:
+Domain guidance may provide techniques for frontend systems, accessibility, browsers, security, performance, databases, APIs, CI/CD, observability, cloud platforms, migrations, releases, deployments, or other specialized work.
 
-1. Keep one owning Freeflow skill.
-2. Use [Design for Depth](../../design-for-depth/SKILL.md) as a lens only when the direction is already design-bearing or evidence establishes structural pressure.
-3. Use one primary implementation or diagnostic method at a time, such as [TDD](../../tdd/SKILL.md), [Simplify Code](../../simplify-code/SKILL.md), or [Diagnose Failure](../../diagnose-failure/SKILL.md).
-4. Load only the domain guidance needed for the concrete technology or risk.
-5. Add specialist independent review only when its lens materially protects the selected boundary.
+It does not override:
 
-Changing method from evidence does not automatically change the current Track Work slice. Do not load a handbook because one keyword appears. Prefer repository policy and current primary sources over generic examples.
+- user-owned product, scope, or risk decisions;
+- repository instructions or accepted behavior;
+- the authority envelope;
+- source truth, failure contracts, or evidence requirements;
+- the current owner’s result and return conditions;
+- selected checkpoints or separately controlled effects;
+- mode, capability, host, or tool controls.
 
-## Common Shapes
+When domain guidance conflicts with accepted intent or live source truth, return the conflict to Workflow. Use [Decision Gate](../../decision-gate/SKILL.md) when resolving it requires one user-owned choice.
 
-```text
-UI change:
-Workflow -> frontend/accessibility guidance -> TDD when useful
--> browser verification
+## Return To The Current Owner
 
-Security- or integrity-sensitive work:
-Decision Gate when policy is unsettled -> Design for Depth -> security guidance
--> TDD at the real boundary -> failure-path verification
--> selected security review
+Return domain results, evidence, assumptions, and limits to the same current owner.
 
-Performance regression:
-Diagnose Failure -> profiler/query guidance -> bounded correction
--> representative performance verification
+A domain method, tool choice, or new observation does not automatically change the current owner, accepted scope, durable task state, or Workflow route.
 
-CI/CD change:
-Workflow or Plan -> provider/repository guidance -> pipeline verification
--> Launch Work only for separately authorized production rollout
-
-Migration:
-Migration Work -> storage/API guidance -> verify each unit
--> Launch Work for separately authorized production cutover
-```
-
-If no suitable domain skill exists, inspect current primary sources and repository conventions. State expertise or environment limits rather than inventing a universal checklist.
+When the domain method exposes material architecture, authority, safety, evidence, or scope pressure, return that changed boundary to Workflow rather than silently expanding the method.

package/skills/write-plan/SKILL.md

@@ -57,7 +57,7 @@ Each slice should produce a coherent result that can be checked. A validation st
 
 ## Select Useful Checkpoints
 
-Every meaningful slice is verified and silently self-reviewed during execution; do not restate that default unless its evidence boundary is unusual.
+During execution, every bounded activity is verified and silently self-reviewed before its result is accepted, reused, or claimed complete; do not restate that default unless its evidence boundary is unusual.
 
 At meaningful slice, phase, integration, risk, or continuity boundaries, consider independent review, a local commit, a user decision, or a continuity checkpoint. Record only selected checkpoints and their conditions. A slice ending or a fixed count alone does not justify a commit; prefer one when supported work forms a coherent rollback point or the next work may destabilize it.