@hassangameryt/freeflow 0.4.0 → 0.5.0

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,13 +1,14 @@
 {
   "name": "freeflow",
   "description": "Freeflow gives coding agents an Interaction Contract, evidence-driven Workflow, focused methods, and durable task memory across conversation, workflow, and strict-workflow modes.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": {
     "name": "Hassan Mohiddin"
   },
   "homepage": "https://github.com/hassan-mohiddin/freeflow",
   "repository": "https://github.com/hassan-mohiddin/freeflow",
   "license": "MIT",
+  "skills": "./skills/",
   "keywords": [
     "workflow",
     "skills",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "freeflow",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"
@@ -21,6 +21,7 @@
     "claude"
   ],
   "skills": "./skills/",
+  "hooks": "./hooks/hooks.json",
   "interface": {
     "displayName": "Freeflow",
     "shortDescription": "Feedback-based control for coding agents.",

package/README.md

@@ -5,9 +5,9 @@
 Freeflow helps coding agents move through consequential work without a rigid pipeline, silent decisions, or context-heavy ceremony.
 
 > Use feedback to choose the smallest useful next action.
-
+>
 > Re-enter the narrowest owning activity when evidence changes the path.
-
+>
 > Memory preserves context. It does not create authority.
 
 The active agent still does the work. Freeflow supplies the interaction contract, workflow routing, focused methods, task memory, and evidence discipline that help it decide what to do next—and when not to edit.
@@ -25,7 +25,7 @@ Coding agents are strong at mutation and weak at control boundaries:
 | A passing command becomes an unsupported completion claim. | Verify Work matches direct evidence to the exact claim and boundary. |
 | Review findings are treated as commands. | The active agent adjudicates; corrections require existing or explicit authority. |
 | Compaction loses task state or imports stale branch authority. | Track Work restores the complete Working Record and reconciles it with the current conversation and live repo. |
-| Large search, logs, and test output consume the context window. | Output Router returns focused evidence with exact recovery where configured. |
+| Large search, logs, and test output consume the context window. | Pi's optional Output Router returns focused evidence with exact recovery where configured. |
 
 Freeflow is not a new agent or workflow engine. It is a portable control layer for Codex, Claude Code, Pi, and similar coding environments.
 
@@ -83,10 +83,7 @@ Task type and direct skill calls do not silently switch mode.
 
 ## Skills And Routing
 
-Freeflow ships 26 skill packages:
-
-- 25 active model/contributor skills;
-- Output Router as an optional capability loaded only when effective.
+Freeflow ships 25 model/contributor skills to Codex, Claude Code, and Pi. The Pi package also includes Output Router as a separately packaged optional capability; it is not part of Codex or Claude skill discovery or lifecycle context.
 
 See the [typed skill routing map](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/skill-routing.md) for every owner, sibling route, and reference dependency. See [Workflow](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md) for the lifecycle and [Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/architecture.md) for delivery and configuration.
 
@@ -106,7 +103,7 @@ It records state transitions, not every edit or comment. Routine in-slice feedba
 
 ## Context Is For Decisions, Not Dumps
 
-Output Router keeps noisy evidence recoverable without forcing all of it into model context.
+In Pi, the optional Output Router keeps noisy evidence recoverable without forcing all of it into model context.
 
 | Need | Use |
 | --- | --- |
@@ -117,7 +114,7 @@ Output Router keeps noisy evidence recoverable without forcing all of it into mo
 | Inspect configuration, vault, routing, or adapters | `freeflow_status` |
 | Read a known file or run a tiny exact command | Native host tools |
 
-Output Router is disabled by default. Setup enables it only after an explicit request.
+Output Router is disabled by default and available only through the Pi extension. Enable it explicitly through Pi's `/output-router` surface.
 
 ## Evidence, Not Marketing Certainty
 
@@ -144,15 +141,18 @@ codex plugin add freeflow@freeflow
 codex plugin list | rg freeflow
 ```
 
-Trust the Freeflow `SessionStart` hook from `/hooks` when Codex requests review.
+Trust the Freeflow `SessionStart` hook from `/hooks` when Codex requests review, then start a new session so skills and lifecycle context load from the installed plugin.
 
 ### Claude Code
 
 ```bash
 /plugin marketplace add hassan-mohiddin/freeflow
 /plugin install freeflow
+/reload-plugins
 ```
 
+Start a new session after first install when the current session predates the plugin.
+
 ### Pi
 
 ```bash
@@ -184,26 +184,25 @@ Minimal setup creates shared activation:
 Configuration layers are:
 
 ```text
-Pi session capability or mode override
+host session mode override
 -> .freeflow/local.json personal core override
 -> .freeflow/config.json shared repository value
 -> built-in default
 ```
 
-`.freeflow/config.json` is required. `.freeflow/local.json` is optional and cannot activate Freeflow by itself. Session overrides live in branch-aware Pi session JSONL, do not mutate config files, and cannot bypass missing or invalid repository activation. Setup does not write Freeflow instructions into `AGENTS.md`, `CLAUDE.md`, or host rule files.
+`.freeflow/config.json` is required. `.freeflow/local.json` is optional and cannot activate Freeflow by itself. Pi stores session overrides in branch-aware session JSONL; Claude and Codex store mode overrides in plugin-owned data keyed by host session ID. Session controls do not mutate config files and cannot bypass missing or invalid repository activation. Setup does not write Freeflow instructions into `AGENTS.md`, `CLAUDE.md`, or host rule files.
 
 ## Runtime Delivery
 
 When effective, host adapters deliver:
 
-- `runtime/interaction-contract.md` for compact turn interpretation;
-- one `skills/workflow/SKILL.md` bootstrap while Skills are effective;
-- compact mode and capability state;
-- effective optional capability context.
+- `runtime/interaction-contract.md` as developer context for compact turn interpretation;
+- one `skills/workflow/SKILL.md` bootstrap per context epoch while Skills are effective;
+- compact active or dormant mode state.
 
 Mode Contract and other skills remain on demand. Hooks load context only; they do not enforce policy, block tools, grant permissions, or replace repo instructions.
 
-Pi appends effective compact context before agent turns and stores Workflow as one hidden persistent session message. Codex and Claude use packaged lifecycle hooks at supported start, resume, clear, and compact boundaries. Setup reports automatic delivery as confirmed, unavailable, or unconfirmed.
+Pi appends effective compact context before agent turns and stores Workflow as one hidden persistent session message. Codex and Claude use one packaged runtime hook: `SessionStart` restores the complete enabled context after startup, resume, clear, and compact; `UserPromptSubmit` emits only for an explicit session-mode control and stays silent on ordinary prompts. Claude uses a bounded host-process-scoped, one-shot lifecycle handoff to retain an override when `/clear` changes the host session identifier. Their hook never exposes Output Router. Setup reports automatic delivery as confirmed, unavailable, or unconfirmed.
 
 ## Commands
 
@@ -260,9 +259,11 @@ Pi-native settings controls:
 /output-router
 ```
 
-`/freeflow settings` edits personal core overrides. `/freeflow settings session` manages temporary, branch-aware Freeflow, Interaction Contract, Skills, and mode overrides without changing config files. `/freeflow settings repo` edits shared settings. `/freeflow mode` remains the direct temporary mode control. Codex and Claude have no native Freeflow slash handlers; canonical names and natural language remain model-routed cues.
+Pi `/freeflow settings` edits personal core overrides, `/freeflow settings session` manages temporary core and mode overrides, and `/freeflow settings repo` edits shared settings. For session mode, Pi uses `/freeflow mode <mode|reset>`, Claude uses `/freeflow:mode-contract <mode|reset>`, and Codex uses `$mode-contract <mode|reset>`. Clear natural-language instructions such as “Switch to conversation mode” use the same host-managed session control; questions and hypotheticals do not.
+
+Claude exposes plugin skills as namespaced commands such as `/freeflow:discuss`; Codex exposes them through `/skills` and `$discuss`. Freeflow uses these host-native skill surfaces instead of duplicate manifest command handlers. Direct skill calls select a method. They do not change mode unless they invoke the mode control, authorize mutation, or create independent review context.
 
-Direct skill calls select a method. They do not change mode, authorize mutation, or create independent review context.
+A request to change the **default** is separate. Explicit local/personal wording targets `.freeflow/local.json`; explicit repository/shared/team wording targets `.freeflow/config.json`. An unqualified “change the default mode” request requires one local-versus-repository clarification before editing.
 
 ## Public Docs
 

package/{skills → capabilities}/output-router/SKILL.md

@@ -193,7 +193,7 @@ When line numbers are unknown, use `query` or `get` first. Use `expand` when a r
 
 Use `freeflow_status` to inspect effective config, vault writability/index state, script adapters, observed routing, and migration recommendations.
 
-Use `../setup-freeflow/SKILL.md` for installation, invalid-config repair, or the initial optional-capabilities branch. After valid setup, Output Router owns explicit operational tuning requested through its capability surface.
+Use Pi's `/output-router enable` or repository settings surface for initial enablement. Read [setup guidance](references/setup.md) before repairing capability config or changing optional routing features. After valid setup, Output Router owns explicit operational tuning requested through its capability surface.
 
 Persist operational config only after an explicit tuning request or a previously accepted setup branch:
 

package/{skills/setup-freeflow/references/output-router-setup.md → capabilities/output-router/references/setup.md}

@@ -86,7 +86,7 @@ Rules:
 - Do not offer or write `redacted`; it is reserved for future work and currently falls back to `metadata-only` with a warning if hand-edited.
 - Pi public `freeflow_capture` and the separate `providers` setup surface have been removed. Do not write removed `capture` or `providers` config.
 - `scriptTransform.enabled` defaults to `false`; write `true` only after an explicit script-execution opt-in.
-- If the user opts into script transform setup and adapters are missing or unavailable, recommend installing global adapters. On consent, resolve `../../router/dist/setup/script-transform-adapters.js` relative to `skills/setup-freeflow/SKILL.md` and run `node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json`.
+- If the user opts into script transform setup and adapters are missing or unavailable, recommend installing global adapters. On consent, run `node <plugin-root>/router/dist/setup/script-transform-adapters.js install --config .freeflow/config.json`.
 - The installer uses `~/.cache/freeflow-script-adapters` by default, or `FREEFLOW_SCRIPT_TRANSFORM_ADAPTERS_HOME` when set. It installs `quickjs-wasi@3.0.1`, `jq-wasm@1.2.0-jq-1.8.2`, `@bsull/eryx@0.5.0`, and `node@24` for the Python JSPI child runner, writes `freeflow-adapter-env.sh`, probes sandbox proofs, and updates `outputRouter.scriptTransform.languages` with only proof-passing languages.
 - Freeflow auto-discovers adapters from that global cache. The explicit roots `FREEFLOW_QUICKJS_WASI_ROOT`, `FREEFLOW_JQ_WASM_ROOT`, and `FREEFLOW_ERYX_ROOT` remain overrides for custom installs.
 - Python/Eryx is installed by setup and uses the setup-installed child Node process launched with `--experimental-wasm-jspi` when the host process lacks JSPI. It must not be marked available unless that child runner passes the required sandbox probes.

package/command-surface.json

@@ -1,5 +1,16 @@
 {
   "nativeSlashHandlers": false,
+  "hostNativeSkillInvocation": {
+    "claude": "namespaced-slash-skill",
+    "codex": "skill-mention",
+    "pi": "registered-command"
+  },
+  "sessionModeControls": {
+    "claude": "/freeflow:mode-contract <mode|reset>",
+    "codex": "$mode-contract <mode|reset>",
+    "pi": "/freeflow mode <mode|reset>",
+    "naturalLanguage": true
+  },
   "modeCommands": [
     {
       "command": "/freeflow mode conversation",