@hassangameryt/freeflow 0.8.0 → 0.9.0

package/.agents/plugins/marketplace.json

@@ -7,8 +7,8 @@
     {
       "name": "freeflow",
       "source": {
-        "source": "local",
-        "path": "."
+        "source": "npm",
+        "package": "@hassangameryt/freeflow"
       },
       "policy": {
         "installation": "AVAILABLE",

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "freeflow",
       "description": "Feedback-based control for coding agents.",
-      "version": "0.8.0",
+      "version": "0.9.0",
       "category": "development",
       "source": "./",
       "author": {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "freeflow",
-  "description": "Freeflow gives coding agents an Interaction Contract, adaptive Workflow, focused methods, and durable task memory.",
-  "version": "0.8.0",
+  "description": "Freeflow gives coding agents an Interaction Contract, one cycle (agree, build and verify, review and hand over), ten skills with scripts, and durable task memory.",
+  "version": "0.9.0",
   "author": {
     "name": "Hassan Mohiddin"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "freeflow",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"
@@ -25,12 +25,12 @@
   "interface": {
     "displayName": "Freeflow",
     "shortDescription": "Feedback-based control for coding agents.",
-    "longDescription": "Freeflow gives coding agents an Interaction Contract, adaptive Workflow, focused methods, and durable task memory.",
+    "longDescription": "Freeflow gives coding agents an Interaction Contract, one cycle (agree, build and verify, review and hand over), ten skills with scripts, and durable task memory.",
     "developerName": "Hassan Mohiddin",
     "category": "Coding",
     "capabilities": ["Interactive", "Read", "Write"],
     "defaultPrompt": [
-      "Use Freeflow's adaptive Workflow for this task.",
+      "Use Freeflow for this task: agree before building, verify, then review and hand over.",
       "Respect the Interaction Contract and ask before going beyond the requested scope."
     ],
     "websiteURL": "https://github.com/hassan-mohiddin/freeflow",

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "freeflow",
   "description": "Feedback-based control system for coding agents.",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "author": {
     "name": "Hassan Mohiddin"
   },

package/README.md

@@ -2,115 +2,110 @@
 
 **A feedback-based control system for coding agents.**
 
-**Memory. Context. Compute.**
+Freeflow gives the coding agent you already use (Codex, Claude Code, Pi and others) what it needs at the moment it decides. On every host its prompts and skills work as a portable layer; on Pi a native extension adds the runtime parts.
 
-Freeflow helps coding agents do consequential work without turning every task into a rigid ceremony. It gives the active agent a clear Interaction Contract, one adaptive Workflow, durable task memory, focused engineering methods, and controlled delivery boundaries.
+- **A short method, always loaded.** One cycle: agree before building, build and verify, review and hand over. Each step checks what actually happened (a script's output, a test, your answer) before the next one, rather than trusting the plan.
+- **Ten capability skills** that bring scripts and structured artifacts, not just advice: a script that maps what a change touches, a self-review report, a decision list for your choices, a Working Record that survives context loss.
+- **On Pi, a runtime** that pushes the right lines of a skill at the tool call that needs them, and adds compaction, tool handling, task memory and multi-model routing.
 
-The host agent still owns tools, permissions, and execution. Freeflow helps it understand the request, choose the right next action, preserve continuity, use evidence honestly, place compute deliberately, and know when to continue, ask, defer, or stop.
+The agent keeps its own tools, permissions and execution. Freeflow does not grant permission, enforce a pipeline, or replace your repository's instructions, tests or review.
 
-- **New to Freeflow?** Read [Using Freeflow Effectively](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/using-freeflow.md).
+- **New to Freeflow?** Read [Using Freeflow Effectively](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/using-freeflow.md) and [How Freeflow Works](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md).
 - **Installing it?** Start with [Getting Started](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/getting-started.md).
-- **Using Cognitive Routing?** Read the detailed [Cognitive Routing reference](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/cognitive-routing.md).
-- **Using Freeflow on Pi?** Read [Tool Execution](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/tool-execution.md) and [Compaction](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/compaction.md).
 
-## Memory · Context · Compute
+## Why
 
-| Pillar | What it provides | Status |
-| --- | --- | --- |
-| **Memory — Track Work** | Working Records that preserve current context, one Current Slice, decisions, evidence limits, future work, and the next useful action. | Available through the shared skill surface. |
-| **Context — Context Control** | Planned source-aware residency, representation, and bounded recovery for admitted context. | Planned/in development; unavailable in this release. |
-| **Compute — Cognitive Routing** | Coordinator, Helper, and Executor profiles in one agent/session, with mode-aware work placement and optional worker-evidence projection. | Experimental native-Pi capability; installed-host and model-behavior evidence remain separate. |
-
-The former Freeflow Context (`freeflow_context`, `/freeflow context`), Context Virtualization, and Conversation History surfaces are removed as a breaking change. Context Control v2 is planned but unavailable in this release; it does not replace those operations yet. See the Unreleased changelog for the required config-key cleanup.
-
-## Selected OpenAI model cache-aware reuse
+Agents often act without opening the skill that describes the step they are taking. In Freeflow's own runs, the old Workflow and Action Selection skills were rarely opened, so their guidance rarely reached the work. Version 0.9.0 is built around that finding. The few rules that must always hold live in a short always-loaded prompt; each skill's description says when it applies; and the skills hand the agent facts and checks (script output, a list of choices, a review brief) instead of more prose to remember.
 
-Freeflow's Pi extension includes cache-aware request history and a qualified effort-history adapter for selected GPT-6 models: `gpt-6-astra`, `gpt-6-luna`, and `gpt-6-sol`.
+| What goes wrong | What Freeflow does |
+| --- | --- |
+| A question or tentative idea becomes an edit. | The Interaction Contract tells discussion apart from a request to act. |
+| A request leaves choices open that the agent settles silently. | Before building, the agent sends what it will do, where it stops, and your decisions with its defaults, then waits; the hand-over shows any choice you have not seen. |
+| A change misses a caller, a test or a doc. | Execute Work's `touch-map.mjs` lists what a change touches, and `self-review.mjs` reports every changed test and whether each requirement's check ran after the last edit. |
+| A passing command becomes an unsupported completion claim. | Verify Work ties the claim to what the check actually observed. |
+| Context loss erases decisions and partial work. | Track Work recovers the Working Record in one call and reconciles it with live state. |
+| Risky changes ship without a second look. | Review Work's gate calls for an independent review when the change touches security, data, release files or a public interface. |
+| Commits, pushes and releases happen without a clear yes. | Deliver Work handles each one within its own approval, and its scripts check state before acting. |
 
-- compatible Freeflow-generated state stays at stable historical positions where possible;
-- changed runtime state is appended instead of rewriting earlier generated context;
-- supported OpenAI Responses and OpenAI-Codex Responses routes can retain a request-level effort baseline and insert trusted effort changes at validated historical positions;
-- unsupported or uncertain requests fall back to the untouched native request.
+## How it works
 
-The adapter uses `freeflow-openai-effort-v1`. Older `freeflow-astra-effort-v1` entries remain in native session history but are not replayed; no migration is provided. This is request-construction and compatibility behavior—not proof of a provider cache hit, billing reduction, model quality improvement, or universal provider support. See the [Pi cache reuse boundaries](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/integrations/pi.md#cache-reuse-boundaries).
+```text
+1. Agree             before the first edit on a task that builds or changes behavior:
+                     what I'll do, where I stop, your decisions with defaults; wait
+2. Build and verify  within the agreement; check on the path you will use
+3. Review, hand over self-review; independent review when the gate calls for it;
+                     report what done looks like against what was done
+When evidence changes the picture, go back only to the step it affects.
+```
 
-## Why Freeflow
+A question gets an answer, an exact one-line edit gets made, and a large change gets the whole cycle. Only your request or a still-valid approval authorizes work; commit, push and release each need their own yes.
 
-Coding agents commonly fail at control boundaries:
+## Skills
 
-| Pressure | Freeflow response |
+| Skill | Use it when |
 | --- | --- |
-| A question or tentative idea becomes an edit. | The Interaction Contract distinguishes discussion from authorization. |
-| A prompt conflicts with policy, tests, or accepted behavior. | Decision Gate exposes the material conflict before mutation. |
-| New evidence invalidates the chosen approach. | Workflow re-enters only the affected owner and preserves valid work. |
-| Every task receives the same heavy process. | Workflow scales pressure to consequence, uncertainty, interaction, and reversibility. |
-| A passing command becomes an unsupported completion claim. | Verify Work ties the claim to the actual observer and evidence boundary. |
-| Context loss erases decisions and partial work. | Track Work restores a complete Working Record and reconciles it with live state. |
-| Expensive models perform routine supporting work. | Cognitive Routing can place bounded support and substantive execution on configured profiles. |
-| Models flood their context with whole files and long command output, or lose edits to files that changed behind them. | Tool Execution teaches narrow reads and capped output, tracks what the model has read, and adds `apply_patch` and background commands. |
-| Pi's automatic compaction summarizes work the agent was in the middle of, and the next step drifts. | Compaction warns the agent first, so it compacts at a safe point from its own summary, Working Record and carried context. |
-| Request history changes destroy reusable prefixes unnecessarily. | RequestHistory and qualified selected-model effort adaptation preserve compatible request structure. |
+| Discuss Work | What to do or how is still open; agreeing before building; a choice mid-work; skipping an optional step |
+| Execute Work | Implementing, fixing, refactoring, designing, finding why something fails, migrating |
+| Verify Work | Checking whether work or a claim holds; setting up or rechecking saved live checks of your software |
+| Review Work | Judging whether work or a document is fit to use, yours or another's |
+| Deliver Work | Commit, push, merge or pull request, branch cleanup, release, deploy |
+| Track Work | Task memory beyond the conversation: the Working Record, recovery, handoffs |
+| Write Docs | Specs, plans, decision records, user and developer docs |
+| Setup Freeflow | Activating Freeflow in a repository and checking delivery |
+| Write Skill | Writing or revising a skill or other text an agent acts on |
+| Evaluate Behavior | Testing or comparing how an agent behaves with a setup change |
+
+Version 0.9.0 replaced twenty-five skills with these ten; removed names have no aliases. [What changed in 0.9.0](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md#what-changed-in-090) says where each one went.
 
-## How it works
+## Commands
 
-Freeflow uses one active agent and one adaptive Workflow:
+Natural language works: the agent opens the skill whose description matches. A direct call helps when it makes the intended method clear. A skill is a method, not a permission.
+
+Skill commands on Pi (Claude Code uses `/freeflow:<skill>`, Codex a skill mention):
 
 ```text
-Interaction Lifecycle
-└─ Workflow Feedback Loop
-   ├─ interpret authority and establish the work agreement
-   ├─ choose the narrowest current owner
-   ├─ discuss, act, test, or observe
-   ├─ determine what the evidence supports
-   ├─ self-review the supported result
-   └─ continue, correct, diagnose, ask, defer, or stop
+/discuss-work
+/execute-work
+/verify-work
+/review-work
+/deliver-work
+/track-work
+/write-docs
 ```
 
-Focused methods own different results: Discuss, Track Work, Execute Work, Diagnose Failure, Verify Work, Review Work, Review Artifact, Write Spec, Write Plan, Release Work, and others. They compose when their conditions apply; they are not mandatory phases.
-
-On a qualified native Pi host, automatic Cognitive Routing sits inside the current Workflow owner:
+Contributor calls:
 
 ```text
-Coordinator receives user direction
--> Helper handles normal supporting assignments when enabled
--> Executor handles substantive or consequential assignments
--> assigned worker returns actual work and evidence
--> Coordinator assesses, continues, corrects, or closes
+/setup-freeflow
+/write-skill
+/evaluate-behavior
 ```
 
-Only one worker assignment runs at a time. A profile switch is not another agent or independent review. A worker report does not complete a Track Work Slice, task, commit, integration, release, or launch.
-
-## Cognitive Routing modes
-
-The labels describe intended optimization direction and potential, not guarantees.
-
-| Mode | Positioning | Behavior |
-| --- | --- | --- |
-| **Helper only** | Quality-first — maximum performance and output-quality potential | Coordinator implements; Helper gathers context, prepares, checks, maintains task memory, and performs settled support. |
-| **Executor only** | Savings-first — maximum savings potential | Coordinator directs and assesses; Executor owns delegated environment work. |
-| **Both** | Balanced | Helper handles frequent routine support; Executor is commissioned for substantive or consequential work. |
-
-A comparatively economical but capable Helper can contribute much of Both mode's potential savings because many routine assignments go through it. The detailed guide includes [recommended OpenAI subscription starting presets](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/using-freeflow.md#recommended-openai-subscription-starting-presets) and the limits on those recommendations.
-
-## Availability
+Native Pi controls:
 
-| Surface | Availability |
-| --- | --- |
-| Interaction Contract, Workflow, and 25 base skills | Shared supported package surface when Freeflow is effectively activated |
-| Track Work / Working Records | Shared skill surface |
-| Context Control v2 | Planned/in development; not available in this release |
-| Cognitive Routing | Experimental native Pi source candidate |
-| Selected GPT-6 effort history | Narrow source/fixture-qualified native Pi route for Astra, Luna, and Sol; provider savings unverified |
-| Tool Execution | Experimental native Pi; off by default; native fixtures and live sessions exercise it, its effect on task results is unmeasured |
-| Compaction | Experimental native Pi; on by default; native fixtures and live sessions exercise it, summary quality against Pi's summarizer is unmeasured |
+```text
+/freeflow
+/freeflow status
+/freeflow settings
+/freeflow settings session
+/freeflow settings local
+/freeflow settings repo
+/freeflow profile coordinator
+/freeflow profile helper
+/freeflow profile executor
+/freeflow profile auto
+/freeflow profile history
+/freeflow resume
+/freeflow compact
+/freeflow task
+/freeflow project
+```
 
-Configuration or installation alone does not establish runtime delivery.
+Profile changes and resume require an idle host. These commands do not prove installed-host delivery or authorize task work.
 
 ## Host support
 
-Freeflow is one package with different host boundaries:
-
-| Host | Freeflow support | Cognitive Routing |
+| Host | Freeflow support | Pi capabilities |
 | --- | --- | --- |
 | Codex | Shared skills and Codex `SessionStart` hook | Not available |
 | Claude Code | Shared skills and Claude Code `SessionStart` hook | Not available |
@@ -120,9 +115,21 @@ Freeflow is one package with different host boundaries:
 | Kiro | Agent Plugins 1.0 Power and shared skills | Not available; skills-only claim |
 | OpenCode v2 | Canonical `skills/` through a documented project skill source | Not available; skills-only support |
 | Hermes Agent | Agent Plugins 1.0 package and canonical skills | Not available; skills-only support |
-| Pi | Shared skills and the native extension (core prompt, Compaction, Tool Execution) | Experimental; native fixtures and live Pi 1.0 sessions on GPT-6 Luna and Sol 6.1 |
+| Pi | Shared skills and the native extension | Tool Execution and Compaction on by default; Task Memory, Messaging and Cognitive Routing opt-in |
+
+Freeflow owns its prompts, skills, capability source, host adapters and the Pi extension. Each host owns launch, package installation, session state, trust and updates.
 
-Freeflow owns workflow policy, portable prompts, skills, capability source, host adapters, and the Pi extension. Each host owns launch, package installation, session state, trust, and updates. Freeflow's PiFlow integration was removed as a breaking change; use native Pi for the Freeflow extension. Freeflow does not change or uninstall a separate PiFlow installation. See the [Unreleased changelog](CHANGELOG.md#unreleased).
+### Pi capabilities
+
+| Capability | Status | What it does |
+| --- | --- | --- |
+| [Tool Execution](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/tool-execution.md) | Experimental; on by default | Working guidance, file tracking, clearer edit errors, `apply_patch`, background commands and monitors, and a skill's key lines at the tool call that needs them (`toolExecution.guidanceNotices`) |
+| [Compaction](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/compaction.md) | Experimental; on by default | The agent compacts at a safe point from its own summary and Working Record; Pi's compaction stays the fallback |
+| [Task Memory](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/task-memory.md) | Preview; off by default | Working Records attached to the session and delivered after context loss; projects and child tasks |
+| [Messaging](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/messaging.md) | Preview; off by default | Messages between the agents in your Pi sessions on this machine |
+| [Cognitive Routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/cognitive-routing.md) | Experimental; off by default | Coordinator, Helper and Executor profiles on different models in one session |
+
+Native fixtures and live sessions exercise these capabilities; their effect on task results, cost and long real use is not yet measured. Freeflow's Pi extension also keeps request history cache-friendly and has a qualified effort-history route for `gpt-6-astra`, `gpt-6-luna` and `gpt-6-sol`; that is request-construction behavior, not proof of a provider cache hit or a billing reduction ([Pi cache reuse boundaries](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/integrations/pi.md#cache-reuse-boundaries)).
 
 ## Quick start
 
@@ -193,11 +200,11 @@ Run:
 /setup-freeflow
 ```
 
-This creates the required shared `.freeflow/config.json` activation boundary. Minimal activation is `{}`. Optional `.freeflow/local.json` personal overrides cannot activate Freeflow alone.
+This creates the required shared `.freeflow/config.json` activation boundary. Minimal activation is `{}`. Optional `.freeflow/local.json` personal overrides cannot activate Freeflow alone. Configuration or installation alone does not establish runtime delivery; setup reports delivery as confirmed, unavailable or unconfirmed.
 
 ## Use Freeflow effectively
 
-A clear prompt normally needs:
+A clear prompt for consequential work names:
 
 ```text
 Outcome: what should be true?
@@ -209,63 +216,7 @@ User-owned choices: what must come back to me?
 Stop and return: where should the agent stop?
 ```
 
-Natural language is preferred. Direct calls such as `/discuss`, `/execute-work`, `/diagnose-failure`, `/verify-work`, `/review-work`, `/track-work`, and `/release-work` are useful when they make the intended method clear. A skill is a method, not an authority grant or required phase.
-
-Read [Using Freeflow Effectively](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/using-freeflow.md) for prompt examples, Workflow management, Track Work, settings, mode selection, preset recommendations, cache/cost boundaries, and troubleshooting.
-
-## Commands
-
-Canonical Pi direct calls include:
-
-```text
-/discuss
-/action-selection
-/track-work
-/write-spec
-/review-artifact
-/write-plan
-/write-docs
-/execute-work
-/simplify-code
-/migration-work
-/diagnose-failure
-/verify-work
-/review-work
-/commit-work
-/handoff
-/finish-branch
-/release-work
-/launch-work
-/bypass
-```
-
-Contributor calls:
-
-```text
-/setup-freeflow
-/write-skill
-/evaluate-skill
-```
-
-Native Pi controls:
-
-```text
-/freeflow
-/freeflow status
-/freeflow settings
-/freeflow settings session
-/freeflow settings local
-/freeflow settings repo
-/freeflow profile coordinator
-/freeflow profile helper
-/freeflow profile executor
-/freeflow profile auto
-/freeflow profile history
-/freeflow resume
-/freeflow compact
-```
-
-Profile changes and resume require an idle host. These commands do not prove installed-host delivery or authorize task work.
+Natural language is preferred. Answer the agent's agreement with "go" to accept its defaults, or correct the line you disagree with. Read [Using Freeflow Effectively](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/using-freeflow.md) for prompt examples, steering the agreement, Track Work, settings, Cognitive Routing modes and presets, cache and cost boundaries, and troubleshooting.
 
 ## Evidence and limits
 
@@ -278,21 +229,17 @@ Freeflow is explicit about what observations prove:
 - local release preparation is not publication;
 - publication is not production deployment.
 
-Cognitive Routing remains experimental pending broader behavioral acceptance. Context Control v2 remains planned. The deprecated Output Router is removed and archived outside the active runtime.
-
 ## Documentation
 
 - [Using Freeflow Effectively](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/using-freeflow.md)
+- [How Freeflow Works](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md)
 - [Getting Started](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/getting-started.md)
-- [Workflow](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md)
-- [Cognitive Routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/cognitive-routing.md)
-- [Tool Execution](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/tool-execution.md)
-- [Compaction](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/compaction.md)
+- [Settings](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/settings.md)
+- [Capabilities](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/README.md)
 - [Pi integration](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/integrations/pi.md)
 - [Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/dev-docs/README.md)
 - [System prompt architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/dev-docs/subsystems/prompt-assembly.md)
 - [Skill routing](https://github.com/hassan-mohiddin/freeflow/blob/main/dev-docs/subsystems/skill-routing.md)
-- [Capabilities](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/README.md)
 - [Release process](https://github.com/hassan-mohiddin/freeflow/blob/main/dev-docs/guides/release.md)
 - [Release evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release-evidence/README.md)
 - [Changelog](CHANGELOG.md)

package/capabilities/cognitive-routing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "cognitive-routing"
-description: "Use when Cognitive Routing is active to place work across configured profiles, direct bounded assignments, assess evidence, and preserve workflow continuity."
+description: "Use when Cognitive Routing is active: the Coordinator plans and delegates work to Helper or Executor profiles, and workers carry out and report their assignments."
 ---
 
 # Cognitive Routing
@@ -17,21 +17,32 @@ Terms:
 - **Unit:** one outcome under Coordinator's judgment. It can contain several assignments.
 - **Assignment:** one saved contract for one worker, ending in that worker's return.
 - **Execution:** one response attempt and its tool work. A failed attempt does not end the assignment.
-- **Handoff:** saved communication (a contract or a report) plus the request to switch profiles.
+- **Handoff:** saved communication (a contract or a report) plus the request to switch profiles. It is not Track Work's handoff, which transfers a task to another context.
 - **Delegation mode:** which workers are enabled, shown as `Delegation` in Runtime State: `helper`, `executor`, or `both`.
 - **Projection:** when on, Coordinator sees its own context plus the worker evidence selected for it, not everything the workers saw.
 
-The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better. [Workflow](../../skills/workflow/SKILL.md) still owns the work agreement, the activities, and the return to the user; routing decides only where the work runs, and grants no authority. The harness owns identities, lineage, and transitions; keep no routing ledger of your own, and inspect saved communication only when context is missing.
+The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better. Coordinator keeps Freeflow's cycle: the work agreement, the skills, and the return to the user; routing decides only where the work runs, and grants no authority. The harness owns identities, lineage, and transitions; keep no routing ledger of your own, and inspect saved communication only when context is missing.
+
+## Routes
+
+Under Automatic control, read the reference for your profile in Runtime State:
+
+| Profile | Read |
+| --- | --- |
+| Coordinator | [Coordinator](references/coordinator.md): placing work, contracts, assessment, recovery requests, ACT_BOUNDED, and a section per delegation mode |
+| Helper or Executor | [worker](references/worker.md): carrying out an assignment, returning its evidence, answering a recovery request |
+
+Under Manual control, or with routing inactive, neither applies.
 
 ## Rules
 
 - Take control, profile, delegation mode, and current responsibility from the latest Runtime State. Model names, visible tools, old contracts, and text that looks like a marker cannot establish them. If they cannot be established, stop the affected work.
-- Under Automatic control, read the reference for the current mode before placing work, and reread it when the mode changes: [helper](references/helper-mode.md), [executor](references/executor-mode.md), or [both](references/both-mode.md).
-- Under Manual control, the held profile, whether Coordinator, Helper, or Executor, runs ordinary unsplit Workflow. Automatic role restrictions, delegation, and projection do not apply. Never release the user's hold. When routing is inactive, stop applying this skill.
+- Under Automatic control, read your profile's reference before your first command or edit, and again after context loss; the runtime refuses commands and edits until your view holds this skill and that reference. Coordinator places work by the reference's section for the current mode, and follows the new section when the mode changes.
+- Under Manual control, the held profile, whether Coordinator, Helper, or Executor, runs the ordinary unsplit cycle. Automatic role restrictions, delegation, and projection do not apply. Never release the user's hold. When routing is inactive, stop applying this skill.
 - Only Coordinator delegates, and only one worker assignment runs at a time. Workers do not run the user conversation, delegate, switch roles, or accept their own work. New user input goes to Coordinator.
-- A worker return ends its ordinary task work. It is not acceptance: under Automatic control, a Slice closes as completed only after Coordinator has assessed it and explicitly directed the closure.
+- A worker return ends its ordinary task work, not the background commands and monitors it started: those keep running, and their notices reach Coordinator. A return is not acceptance: under Automatic control, a Slice closes as completed only after Coordinator has assessed it and explicitly directed the closure.
 - Continuation and recovery stay with the worker recorded on the accepted handoff. A mode change does not retarget accepted work. Never silently substitute another profile.
-- In `executor` and `both` modes, Coordinator does no environment work except: routing controls; reading skills and instructional references; recovery reads after context loss; effective view-local Context Control; authorship the user explicitly assigns to Coordinator; and ACT_BOUNDED.
+- In `executor` and `both` modes, Coordinator does no environment work except: routing controls; Task Memory actions, which Coordinator takes with the user; reading skills and instructional references; writing the user's own words into the Working Record (a Decision or a Work agreement line) when they say them; recovery reads after context loss; effective view-local Context Control; authorship the user explicitly assigns to Coordinator; and ACT_BOUNDED.
 - Never change compute configuration yourself.
 - Never fabricate evidence, and never drop adverse evidence to make a return look complete or ready.
 
@@ -50,135 +61,16 @@ Total cost is the number of model turns times their average cost. Moving work to
 
 Lower cost never lowers the required quality or evidence. Several cheap corrections can still be economical; repeated misunderstanding, needless handoffs, and unsupported acceptance are not savings.
 
-## Decide Where Work Runs
-
-Goal: each result is produced where the total cost is lowest without losing quality.
-
-Delegate when the expected saving in cost or quality exceeds the handoff, the ramp-up, the assessment, and the likely corrections. The kind of difficulty usually suggests the owner:
-
-- missing facts about the environment: a worker observes;
-- an unresolved design or governing choice: Coordinator;
-- settled mechanics: a worker, or a script when the work is deterministic and repeated;
-- a decision the user owns: Coordinator asks, using [Decision Gate](../../skills/decision-gate/SKILL.md); never a worker.
-
-Default: follow your mode reference. Keep a tightly coupled edit, check, and interpret loop with one producer; hand off results that can be separated from it. A separate multi-entry record update qualifies; a one-line update in the middle of your own work does not. A read-only check of the candidate against the Slice's acceptance requirements qualifies even mid-implementation, because it gives Coordinator a different result, not a repeat.
-
-Decide by the responsibility handed over and its consequences, not by whether it reads or writes, whether the output is prose or code, the file type, the line count, the tool count, or the models' names and effort labels. Choosing a worker never substitutes for the user's authorization. Do not require a worker to fail before choosing a stronger owner. If a return shows the responsibility is different from what you assumed, reassess the placement rather than repeat the assignment more forcefully.
-
-Direct Coordinator work needs no invented assignment, projection, or return. Authorship the user assigns to Coordinator means the user asked Coordinator itself to write a particular artifact; a general request such as "write the plan" does not select it, and it authorizes nothing beyond that artifact. Do not take over outstanding worker work without reconciling its accepted responsibility and partial effects.
-
-## Prepare The Route Before Delegating Production
-
-Goal: the implementer starts with what it needs, and nobody gathers in the premium profile what the route could have predicted.
-
-Workflow's route preparation applies. Routing adds:
-
-- Coordinator plans the route and may read skills directly to know which methods the assignments will need.
-- Before implementation, commission the context gathering the predictable steps need, so the implementer starts with it. Who gathers, and how the evidence reaches Coordinator, depends on the mode; see your mode reference.
-- The implementing producer forms the execution forecast described in [Execute Work](../../skills/execute-work/SKILL.md) under Gather Enough Context For This Unit. When a worker implements, Coordinator supplies the governing decisions and the worker forms the forecast; do not write the patch for it.
-
-## Coordinator: Write A Contract That Carries The Decision
-
-Goal: the worker can act correctly on the first attempt without re-deriving what Coordinator already knows.
-
-Put the actual contract in `freeflow_delegate(operation: "assign")`. In `both` mode, set `worker` to `helper` or `executor`; with one enabled worker the tool infers it. Write for what the worker can see, not what you remember:
-
-- the required result, why it matters, and the method to use;
-- established facts, accepted decisions, and open questions;
-- scope, order, constraints, permitted effects, and remaining local freedom;
-- behavior for the cases the request does not mention but the change touches: other entry points, sibling operations, data already written, and work that runs at the same time or on a schedule;
-- the contracts the worker must not choose: names, messages, interfaces, file locations, and dependencies, exactly as they must appear;
-- the evidence you need to assess the result;
-- when to return, including when a premise or governing choice changes.
-
-State each requirement as the outcome for a named thing, without an escape clause such as "unless needed" or "as today". When behavior elsewhere must be preserved, say where the change belongs and what each named caller must still get: "keep what callers rely on today" alone can steer a worker away from a correct fix in shared code.
-
-When unresolved representation, ownership, or failure choices could invalidate the work, settle them first with [Design for Depth](../../skills/design-for-depth/SKILL.md). Your most valuable contribution is framing the problem so the worker finds it straightforward. For a consequential or repeatedly misunderstood property, name the mechanism and why it fits, the plausible wrong approach, and the observation that tells them apart. Give more structure where the worker has shown difficulty and more freedom where the mechanics are settled. A contract that contains the finished patch has moved the work back to Coordinator's price.
-
-A gathering assignment names what must be learned, not a guessed implementation. Request evidence by purpose, since its refs do not exist yet; what you request is a minimum, and workers also return material discoveries and counterevidence. Shared history and provider caching do not convey unspoken direction, and a filename does not mean its content is available to the worker.
-
-Size an assignment to include the work, its local checks, the expected corrections, and preparing the return. Shorten it when an unfamiliar boundary could invalidate much dependent work. Do not supervise every command, and do not delegate the whole objective to avoid later judgment. A negative result can complete a gathering or experimental assignment.
-
-Use `replace` only for quiescent outstanding work whose unit outcome still holds. State why the direction changed, preserve partial effects and uncertainty, and choose the worker again in `both` mode. Do not replace returned work, or close and reopen a unit to escape unfinished responsibility.
-
-## Worker: Execute Within The Contract
-
-Goal: produce the assigned result resourcefully, within scope, and stop at the useful boundary.
-
-Establish the contract, your assigned role, the constraints, and the return condition. Load the producing method and [Action Selection](../../skills/action-selection/SKILL.md) when absent. Follow required direction; choose ordinary mechanics yourself. A useful discovery or an available tool grants no new authority.
-
-Challenge unsupported premises and report better-supported approaches. A governing change, one that alters the accepted outcome, architecture, policy, scope, authority, failure behavior, or required evidence, stops dependent effects until Coordinator decides. An unprescribed filename or helper does not require a return. For an unexplained or repeatedly stalling failure, use [Diagnose Failure](../../skills/diagnose-failure/SKILL.md) within scope or return.
-
-Run routine tools without announcing them; put findings in the report. Questions for the user go to Coordinator in the return.
-
-Verify the actual candidate and self-review through the producing method, using [Verify Work](../../skills/verify-work/SKILL.md) to say what the observations support. Keep failed, stale, incomplete, and inconclusive evidence. If a test changes, say what the old and new versions each establish.
-
-Return when the result is ready, the stop condition is reached, no useful covered work remains, or new user input needs Coordinator. Do not stop after each command, and do not continue into a different responsibility to avoid a handoff. State what remains before the Slice's exit.
-
-## Worker: Prepare Evidence, Then Return
-
-Goal: Coordinator receives what it needs to judge the result and nothing it does not.
-
-Helper and Executor share ordinary history. Reuse each other's sources and observations while keeping who produced them; do not create worker-to-worker projections. With projection on, Coordinator sees only what you select, so select enough original material for judgment, not the execution trail. Prepare evidence once, at the return boundary, not after each tool call.
-
-1. **Reconcile the result.** Compare the contract with the actual work, changed assumptions, partial effects, missing checks, and contrary findings. Make sure captures describe the candidate you are reporting, after any later edits.
-2. **Choose the evidence.** Start with what Coordinator requested and what it already has. Add governing background, material discoveries, and counterevidence it needs. Being eligible is not a reason to select a source, and a nearby result, filename, or shared report is not automatically the evidence for a claim. Unknown authorship stays unknown. When Coordinator already has adequate evidence or the result is self-contained, select nothing new.
-3. **Add the bodies and submit together.** With projection on, add the skill and reference reads that carry the methods Coordinator needs, and the original task-evidence bodies needed for assessment, in one `freeflow_project` add using visible refs directly. Only tool results are evidence; write findings, drafts, and interpretation into the report instead. In the same response, put `freeflow_return(operation: "submit")` last, with the result, evidence and limits, changed assumptions, partial effects, what remains, and why you are returning. Do not wait for the selection receipt: the report is saved even when evidence has problems. Never batch the return with new task work whose outcome the report assumes. Then stop ordinary task work.
-4. **Check the return receipt.** If it reports problems, resolve identity or representation problems with `freeflow_project`, then use payload-free `freeflow_return(operation: "retry")`. Withdraw a request only with a reason; withdrawing does not close a required evidence gap. Do not rerun work to manufacture a selectable receipt.
-
-Use `freeflow_project` inspect only when a ref's identity, eligibility, representation, or selection state is unclear; assignment size alone is not a reason. Once you find the refs you need, add them; the remaining candidates are not a work queue. With projection off, skip the projection tools, not verification or honest reporting.
-
-A required stop takes precedence over another read or test: return an honest `partial` or `blocked` report instead of forcing `completed`. `reportSaved` does not mean delivered or assessed. If the transfer is blocked, ordinary work stays ended; fix only the handoff problem and use payload-free `freeflow_return(operation: "retry")`. Use `submit` again only to deliberately revise the report.
-
-## Coordinator: Assess The Return
-
-Goal: accept only what the evidence supports, and choose the next work from the actual gap.
-
-Assess the report and evidence you received. Ordinary assessment needs neither routine inspection nor an `assess` call; `assess` restores a suspended evidence view after new user input paused it.
-
-For a material claim, compare the accepted property, the observation actually made, the decisive assertions, the candidate's identity, and the result. A confident report or a green suite cannot fill a missing link. Keep unsupported required claims open and stop dependent work. Check the actual state before calling something a defect or crediting a fix.
-
-Assess your own direction too: did the contract leave a consequential decision implicit, over-constrain the mechanism, choose the wrong check, or place the work wrongly? A worker that asked no questions has not shown the contract was sufficient; missing specification shows in the result, as a plausible but different name, location, or behavior. Improve the next contract from the answer.
-
-Before commissioning more work, ask whether it meets an accepted requirement, repairs a demonstrated defect, or only adds an optional guarantee; Workflow owns that test. Then choose from the gap:
-
-- **Supported result:** continue with the next covered work, or accept the outcome.
-- **Evidence omitted but it exists:** recover it (below) before investigating again; absence from your view does not mean the action never happened.
-- **Missing or inadequate observation:** request the observation that decides it, without changing the required property.
-- **Supported defect:** assign the correction and affected checks to the owner its responsibility needs.
-- **Invalidated approach or unclear cause:** revise the direction or commission diagnosis rather than repeat the demand.
-- **User-owned choice:** take it to the user before dependent work.
-
-Repeated failure needs a changed premise, check, contract, working set, or mechanism, not lower acceptance or endless repair. Reuse adequate producer verification; a worker's audit in the same session is not independent review, which remains a separate Workflow choice.
-
-Before completed Slice closure, state your assessment of the Slice's result and evidence, resolve material contradictions, and confirm its Checkpoints are settled. Then direct the [Track Work](../../skills/track-work/SKILL.md) closure through whichever route your mode allows, preferably folded into work already going to that profile rather than a handoff of its own. A prior "close it if green" instruction cannot stand in for assessing results you have not seen. Workers may record factual progress while the Slice is open; a worker writing the closure returns instead if new evidence contradicts the accepted basis.
-
-Use `freeflow_unit(operation: "close")` when the unit's outcome is supported, or to record an authorized `cancelled` or `deferred` outcome. Closing a unit does not complete a Slice or task, clear history, or authorize a commit or delivery. Continue covered work to the agreed return point.
-
 ## Keep Control And Continuity
 
-New natural-language input, including "continue", goes to Coordinator. If it reaches a worker mid-assignment, honor any restriction at once, stop task work, and return the partial state. When the user asks what a worker did, answer from `freeflow_unit` inspection or by asking that worker; absence from your view does not mean the action never happened. Runtime State refreshes are observations, not new direction. Technical retries stay within the accepted assignment; `/freeflow resume` continues unchanged saved work after reconciliation and does not release a Manual hold.
+New natural-language input, including "continue", goes to Coordinator. If it reaches a worker mid-assignment, honor any restriction at once, stop task work, and return the partial state. When the user asks what a worker did, answer from `routing_unit` inspection or by asking that worker; absence from your view does not mean the action never happened. Runtime State refreshes are observations, not new direction. Technical retries stay within the accepted assignment; `/freeflow resume` continues unchanged saved work after reconciliation and does not release a Manual hold.
 
 During a Manual hold, preserve any interrupted assignment, partial effects, and pending assessment; keep no shadow delegation. If the held preset cannot do the work, report it and leave the choice to the user. When the user releases the hold, Coordinator reconciles current direction, the mode, outstanding responsibility, and anything done during the hold before routing again.
 
-After context loss, follow the bootstrap in the capability cue, reload the methods and the mode reference, and recover control, mode, contract or report, user direction, partial effects, and stop conditions. When a Working Record exists, Coordinator reads it in full through Track Work, and the artifacts under `What defines this task`, directly, in every mode. Large Recovery sources that only serve execution stay with the worker that needs them. An outstanding worker reconstructs and continues its recorded assignment, and its recovery reads stay within the contract's limits; do not wrap existing responsibility in a new assignment. A summary mentioning a superseded contract does not revive it.
-
-### Recover Missing Evidence For An Assessment
-
-Outstanding assignments use ordinary continuation, not this. For the current returned assessment, Coordinator uses `freeflow_unit(operation: "recover")` with the missing-evidence question, any exact task-file `paths`, and any captured result ids in `results` (a context ref such as `ctx:1a2b3c4d` goes in the request instead; the worker selects it). Recovery belongs to the assignment's recorded worker. Preserve the unit, assignment, original report, outcome, revision, selections, and assessment.
-
-During recovery, the worker may select previously exposed evidence and read only exact admitted task paths, granted captured results, or packaged Freeflow skill and reference files. It must not edit, run commands or tests, broaden discovery, or resume task work. Report stale or unavailable evidence without rerunning anything. Return with `freeflow_return(operation: "supplement")` and stop reading. A `partial` or `blocked` supplement can deliver its communication while the full evidence obligation stays suspended; payload-free `retry` resends an unchanged saved supplement.
-
-A separate recovery assignment fits only when no existing assignment or assessment needs preserving. Coordinator uses `cancel-recovery` when the lookup is no longer needed; the original report and assessment remain. Deliver the supplement or cancel recovery before `assess`; new user input does not settle recovery. Do not simulate recovery by replacing an assignment/report or opening a new unit.
+After context loss, follow the bootstrap in the capability cue, reload the methods, this skill and your profile's reference, and recover control, mode, contract or report, user direction, partial effects, and stop conditions. When a Working Record exists, Coordinator recovers it through Track Work's order, including the artifacts under `What defines this task`, directly, in every mode. Large Recovery sources that only serve execution stay with the worker that needs them. An outstanding worker reconstructs and continues its recorded assignment, and its recovery reads stay within the contract's limits; do not wrap existing responsibility in a new assignment. A summary mentioning a superseded contract does not revive it.
 
 ### Keep Useful History
 
 Closing, replacing, returning, and pausing change responsibility, not the value of history already admitted. Keep past work distinguishable from the current obligation without removing it. Navigation does not roll back files, processes, or the record; compaction does not justify inventing source bodies or repeating uncertain effects. When Context Control is effective, read its method before managing a view, and keep current direction, contrary findings, and promised originals. Optional cleanup comes after the promised evidence is prepared; if cleanup fails, keep the extra context and continue the handoff.
 
-## ACT_BOUNDED: Inseparable Judgment And Action
-
-In `executor` and `both` modes, Coordinator may do other environment work only when judgment and action cannot be separated and delegating would lose something concrete. Examples: synthesizing a governing artifact when a complete contract would already be the artifact; intervening result by result in sensitive work. Task size, convenience, fewer switches, a failed recovery, or a preference for premium compute do not qualify, and separable production does not become judgment by being relabelled.
-
-Before acting, state ACT_BOUNDED with its scope, expected result, existing authority, stop condition, the inseparable judgment, and what delegation would lose. Stay inside that scope; end on completion, interruption, context loss, changed applicability, or before delegating again. It grants no permission, assignment, or acceptance. Helper-mode Coordinator production needs no ACT_BOUNDED.
-
-Stop applying the Automatic split when control becomes Manual or routing becomes inactive; preserve unfinished responsibility honestly and follow ordinary Workflow.
+Stop applying the Automatic split when control becomes Manual or routing becomes inactive; preserve unfinished responsibility honestly and follow the ordinary cycle.