@hassangameryt/freeflow 0.4.0 → 0.6.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.6.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.6.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.6.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

@@ -2,138 +2,96 @@
 
 **A feedback-based control system for coding agents.**
 
-Freeflow helps coding agents move through consequential work without a rigid pipeline, silent decisions, or context-heavy ceremony.
+Freeflow helps coding agents do consequential work without turning every task into a rigid ceremony. It gives the agent a clear interaction contract, evidence-driven Workflow, focused methods, durable task memory, and controlled delivery boundaries.
 
-> 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.
+The host agent still owns tools, permissions, and execution. Freeflow helps it choose the right next action—and know when to stop, ask, verify, or hand work back.
 
 ## Why Freeflow
 
-Coding agents are strong at mutation and weak at control boundaries:
+Coding agents commonly fail at control boundaries:
 
-| Common failure | Freeflow response |
+| Pressure | Freeflow response |
 | --- | --- |
 | A question or tentative idea becomes an edit. | The Interaction Contract answers first and waits for clear action authority. |
-| A prompt conflicts with tests, policy, or accepted behavior. | Decision Gate names the conflict and stops before mutation. |
-| Work follows a plan after evidence invalidates it. | Workflow routes from evidence and preserves unaffected work. |
-| Every task gets a spec, plan, review, and status ceremony. | Workflow enters at the narrowest useful owner and creates artifacts only when they help. |
-| 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. |
-
-Freeflow is not a new agent or workflow engine. It is a portable control layer for Codex, Claude Code, Pi, and similar coding environments.
-
-## The Control System
-
-One user interaction is an **Interaction Lifecycle**:
-
-![Freeflow Workflow: Entry, Feedback Loop, and Supported Exit](assets/workflow.png)
+| A prompt conflicts with tests, policy, or accepted behavior. | Decision Gate names the conflict before mutation. |
+| New evidence invalidates the plan. | Workflow routes from evidence and preserves unaffected work. |
+| Every task receives unnecessary ceremony. | Workflow enters at the narrowest useful owner. |
+| A passing command becomes an unsupported completion claim. | Verify Work matches evidence to the exact claim and boundary. |
+| Compaction loses task state. | Track Work restores a Working Record and reconciles it with live state. |
+| Tool output consumes future context. | Context Virtualization can archive consumed evidence while preserving session history. |
+
+## Contents
+
+- [How it works](#how-it-works)
+- [Host support](#host-support)
+- [Capabilities](#capabilities)
+- [Quick start](#quick-start)
+- [Modes and workflow](#modes-and-workflow)
+- [System prompt architecture](#system-prompt-architecture)
+- [Evidence and limits](#evidence-and-limits)
+- [Commands](#commands)
+- [Documentation and development](#documentation-and-development)
+- [What Freeflow is not](#what-freeflow-is-not)
+
+## How it works
+
+Freeflow uses one active agent, one shared context, and nested feedback loops:
 
 ```text
-[Entry] -> [Feedback Loop when needed] -> [Supported Exit]
-   ^              ^        |                  |
-   |              |________|                  |
-   |__________________________________________|
-            later user turn or evidence
-```
-
-When work is needed, the inner **Feedback Loop** is:
-
-![Freeflow Core Feedback Loop: orient, use the owning skill, verify, self-review once, and route from evidence](assets/feedback-loop.png)
-
-```text
-orient to accepted intent, task memory, and live evidence
--> use the narrowest owning skill
--> implement, discuss, test, or observe
--> verify what the evidence proves
--> when supported, self-review once
--> continue, correct, diagnose, revise, ask, defer, or stop
+Interaction Lifecycle
+└─ Workflow Feedback Loop
+   ├─ establishes authority, owner, and slice
+   └─ Cognitive Execution Loop — automatic control only
+      ├─ Reasoning establishes the governing execution contract
+      ├─ DELEGATE to Standard
+      │  └─ Environment Interaction Loop
+      │     ├─ select and bound the next action
+      │     ├─ use Action Selection when uncertain or broad
+      │     ├─ take the obvious fast path when mechanical
+      │     ├─ execute and observe
+      │     └─ repeat within the delegation contract
+      ├─ RETURN evidence to Reasoning
+      ├─ Reasoning self-reviews
+      └─ close, delegate correction, or return to Workflow
 ```
 
-A Supported Exit may answer, wait, pause, hand off, defer, stop, preserve a controlled boundary, or complete. Freeflow does not invent another phase merely because one exists in the full skill pack.
+Under manual profile control, the Cognitive Execution Loop is not used; the held profile runs the ordinary unsplit Workflow. Cognitive Routing changes compute placement only. It never changes authority, ownership, mode, task scope, evidence requirements, or review independence.
 
-## Core Principles
+The Workflow owner may be Discuss, Track Work, Execute Work, Verify Work, Review Work, Review Artifact, Diagnose Failure, or another focused method. These methods compose when their conditions apply; they are not a mandatory phase pipeline.
 
-- **The active agent owns the current route.** Independent review may add judgment; it does not take over routing or verification.
-- **Verification is factual. Review is judgment.** The active agent verifies; self-review is silent; selected independent review uses a separate context.
-- **Pass is not the only review exit.** Pass, Non-blocking, Inconclusive, and Blocking all end review and return evidence to Workflow.
-- **Review findings do not authorize edits.** Ask for unapproved corrections and any warranted focused follow-up together.
-- **Specs and Plans have separate jobs and separate reviews.** Working Records carry evolving state; Plans remain stable ordered strategy.
-- **A slice may span several feedback iterations.** Extend its boundary write-ahead only while the intended result remains coherent.
-- **Diagnose before redesigning.** Ordinary mistakes do not prove structural failure.
-- **Bypass skips optional pressure, not authority, safety, evidence, or selected review.**
+## Host support
 
-## Modes
+Freeflow is one package with different host boundaries:
 
-Freeflow has exactly three modes:
-
-| Mode | Use for | Guardrail |
+| Host | Freeflow support | Cognitive Routing |
 | --- | --- | --- |
-| `conversation` | Discussion, critique, explanation, and read-only exploration | Agent-performed mutation requires switching mode. |
-| `workflow` | Normal consequential or mutating work | Use the adaptive lifecycle and proportionate evidence. |
-| `strict-workflow` | High-risk or hard-to-reverse work | Stronger decision, evidence, and checkpoint pressure without review after every slice. |
-
-Task type and direct skill calls do not silently switch mode.
-
-## Skills And Routing
+| Codex | Shared skills and lifecycle hook | Not available; Pi-only capabilities are not delivered |
+| Claude Code | Shared skills and lifecycle hook | Not available; Pi-only capabilities are not delivered |
+| Pi | Shared skills, Pi extension, and optional context capabilities | Configuration is inspectable but execution is disabled |
+| PiFlow | Freeflow package hosted by the separate PiFlow distribution | Available when host controls, Skills, and profiles are configured |
 
-Freeflow ships 26 skill packages:
+Freeflow owns workflow policy, prompt fragments, skills, capabilities, and the Pi extension. PiFlow owns host launch, package installation, session state, updates, and the model-state control required by Cognitive Routing.
 
-- 25 active model/contributor skills;
-- Output Router as an optional capability loaded only when effective.
+## Capabilities
 
-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.
+### Workflow and task memory
 
-## Task Memory Without A Second Task System
+- **Workflow** coordinates authority, owner selection, evidence-driven re-entry, and Supported Exit.
+- **Action Selection** bounds uncertain or broad Environment Interactions while preserving the current owner.
+- **Track Work** maintains one Working Record when decisions, evidence, blockers, or the next action must survive context loss.
+- **Verify Work, Review Work, Review Artifact, and Diagnose Failure** separate factual support, judgment, artifact fitness, and unsupported causes.
 
-Track Work maintains one Working Record for an ongoing task:
+### Optional host capabilities
 
-- current context;
-- one current slice;
-- ordered proposed slices;
-- task-local decisions and hypotheses;
-- evidence pointers and completed history;
-- one next useful action;
-- optional inert Notes.
+- **[Cognitive Routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/cognitive-routing.md)** places compute between Reasoning and Standard under automatic control. It is PiFlow-only and experimental.
+- **[Context Virtualization](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/context-virtualization.md)** classifies consumed tool evidence as Full, Retained, or Reference-only for future context while leaving canonical history unchanged.
+- **[Conversation History](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/conversation-history.md)** performs bounded retrieval of exact missing prior-conversation evidence from the current active branch.
 
-It records state transitions, not every edit or comment. Routine in-slice feedback is not checkpoint history. After compaction, summarization, clear, resume, or session navigation, Workflow reads the complete record before continuing and treats it as memory rather than authority.
-
-## Context Is For Decisions, Not Dumps
-
-Output Router keeps noisy evidence recoverable without forcing all of it into model context.
-
-| Need | Use |
-| --- | --- |
-| Search repo, explicit local sources, or routed evidence | `freeflow_search` |
-| Run noisy tests, builds, typechecks, logs, or diagnostics | `freeflow_run` |
-| Run independent searches/checks and aggregate facts | `freeflow_batch` |
-| Compute bounded subsets or statistics | `freeflow_search action=transform` |
-| Inspect configuration, vault, routing, or adapters | `freeflow_status` |
-| Read a known file or run a tiny exact command | Native host tools |
+All three capabilities are Skills-gated and default-off or unavailable unless their configuration and host conditions are effective. None of them grants authority or replaces Workflow.
 
-Output Router is disabled by default. Setup enables it only after an explicit request.
+## Quick start
 
-## Evidence, Not Marketing Certainty
-
-Historical v0.1 workflow fixtures and current router benchmarks remain reproducible evidence, not universal guarantees. The current adaptive skill candidate is **Unverified** pending baseline-vs-with-skill behavioral evaluation.
-
-| Evidence | Result |
-| --- | --- |
-| Historical v0.1 acceptance suite | 15/15 fixtures passed after measured fixes. |
-| Historical source-truth conflict pressure | Baseline 2/10; with-skill 10/10. |
-| Retrieval benchmark | 7/7 gated fixtures; 98.54% weighted context reduction. |
-| Command-output benchmark | 8/8 fixtures with exact recovery; 85.03% weighted reduction. |
-| Pi observed-routing eval | 28/28 objective gates; 82.2% overall byte reduction. |
-
-See [release evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release-evidence.md) for boundaries, reports, and deferred checks.
-
-## Install
+For the complete host-specific setup, see [Getting Started](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/getting-started.md).
 
 ### Codex
 
@@ -141,16 +99,16 @@ See [release evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plu
 codex plugin marketplace add https://github.com/hassan-mohiddin/freeflow.git
 codex plugin marketplace upgrade freeflow
 codex plugin add freeflow@freeflow
-codex plugin list | rg freeflow
 ```
 
-Trust the Freeflow `SessionStart` hook from `/hooks` when Codex requests review.
+Trust the Freeflow hook from `/hooks`, then start a new session.
 
 ### Claude Code
 
-```bash
+```text
 /plugin marketplace add hassan-mohiddin/freeflow
 /plugin install freeflow
+/reload-plugins
 ```
 
 ### Pi
@@ -165,45 +123,77 @@ Or:
 pi install git:github.com/hassan-mohiddin/freeflow
 ```
 
-## Activate In A Repository
+### PiFlow
 
-Run:
+Install PiFlow separately, then install Freeflow into it:
+
+```bash
+npm install -g --ignore-scripts @hassangameryt/piflow
+piflow install npm:@hassangameryt/freeflow
+```
+
+For a Git source:
+
+```bash
+piflow install git:github.com/hassan-mohiddin/freeflow
+```
+
+In the target repository, run:
 
 ```text
 /setup-freeflow
 ```
 
-Minimal setup creates shared activation:
+Setup creates `.freeflow/config.json`, the required shared activation boundary. `.freeflow/local.json` is an optional personal override and cannot activate Freeflow by itself.
 
-```json
-{
-  "defaultMode": "workflow"
-}
-```
+## Modes and workflow
+
+Freeflow has exactly three modes:
 
-Configuration layers are:
+| Mode | Use for |
+| --- | --- |
+| `conversation` | Discussion, critique, explanation, and passive inspection |
+| `workflow` | Active evidence generation and normal consequential work |
+| `strict-workflow` | High-risk or hard-to-reverse work |
+
+Mode changes do not authorize work. A direct request, still-valid approval, or accepted task contract establishes the authority envelope; mode, skill selection, usefulness, and new evidence do not widen it.
+
+Every bounded activity follows the same Feedback Loop:
 
 ```text
-Pi session capability or mode override
--> .freeflow/local.json personal core override
--> .freeflow/config.json shared repository value
--> built-in default
+orient to accepted intent, task memory, and live evidence
+-> use the narrowest owner
+-> act, discuss, test, or observe
+-> verify what the evidence proves
+-> self-review the supported result
+-> continue, correct, diagnose, revise, ask, defer, or stop
 ```
 
-`.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.
+## System prompt architecture
+
+Freeflow’s model-facing surface has three layers:
+
+1. **Stable prompt fragments** under `runtime/prompts/` provide compact guidance and conditional capability cues.
+2. **Runtime State** reports current mode, capability availability, and Cognitive Routing `Control`/`Profile` before every provider request.
+3. **Discoverable skills and tools** provide complete methods and operations when effective gates apply.
 
-## Runtime Delivery
+One effective-state snapshot determines all three surfaces. The Interaction Contract is prompt-only. Skills gates Cognitive Routing, Context Virtualization, and Conversation History. Missing optional capability content is omitted and reported unavailable rather than fabricated.
 
-When effective, host adapters deliver:
+Read the full [System Prompt Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/prompt-architecture.md) and [Workflow](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md) docs for the complete contract.
 
-- `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.
+## Evidence and limits
 
-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.
+Freeflow is explicit about what its checks prove:
 
-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.
+- deterministic checks prove structure, assembly, package boundaries, and selected delivery behavior;
+- release evidence is versioned and records source, checks, artifacts, deferred evidence, and limits;
+- local installation does not prove remote host installation or registry propagation;
+- deterministic skill/runtime checks do not prove model behavior or universal skill readiness;
+- Cognitive Routing remains experimental pending behavioral acceptance.
+
+The deprecated Output Router is removed and no longer available. Its implementation and evidence remain archived under `.deprecated/output-router/`.
+
+See [Release Process](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release.md) and [Release Evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release-evidence/README.md).
 
 ## Commands
 
@@ -211,6 +201,7 @@ Natural language is preferred. Pi registers these canonical direct calls:
 
 ```text
 /discuss
+/action-selection
 /track-work
 /write-spec
 /review-artifact
@@ -229,13 +220,6 @@ Natural language is preferred. Pi registers these canonical direct calls:
 /bypass
 ```
 
-Pi-only compatibility aliases:
-
-```text
-/discover
-/execute-plan
-```
-
 Contributor calls:
 
 ```text
@@ -253,34 +237,45 @@ Mode controls:
 /freeflow mode reset
 ```
 
-Pi-native settings controls:
+Pi settings and PiFlow-only Cognitive Routing controls:
 
 ```text
 /freeflow
-/output-router
+/freeflow profile standard
+/freeflow profile reasoning
+/freeflow profile auto
 ```
 
-`/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 overrides, `/freeflow settings session` manages temporary session overrides, and `/freeflow settings repo` edits shared repository settings. Profile changes require PiFlow and an idle host.
 
-Direct skill calls select a method. They do not change mode, authorize mutation, or create independent review context.
+In PiFlow, while the host is idle:
 
-## Public Docs
+- `Ctrl+Shift+R` cycles the manual standard/reasoning hold.
+- `Ctrl+Shift+A` cycles the automatic standard/reasoning profile; from a manual hold, its first press returns to automatic control without forcing a profile transition.
 
-- [Docs index](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/README.md)
-- [Workflow](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/workflow.md)
-- [Skill routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/skill-routing.md)
+Normal Pi does not register these Cognitive Routing shortcuts.
+
+## Documentation and development
+
+- [Documentation hub](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/README.md)
+- [Getting Started](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/getting-started.md)
 - [Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/architecture.md)
-- [Output Router](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/output-router.md)
-- [Release evidence](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release-evidence.md)
-- [Release ADRs](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/adr/README.md)
+- [System Prompt Architecture](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/prompt-architecture.md)
+- [Capabilities](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/capabilities/README.md)
+- [PiFlow integration](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/integrations/piflow.md)
+- [Skill routing](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/skill-routing.md)
+- [Release Process](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/release.md)
+- [Changelog](CHANGELOG.md)
+- [Contributing](CONTRIBUTING.md)
+
+For local development, use committed Freeflow snapshots with `npm run snapshot:refresh`. Do not treat an uncommitted working tree as a production package source. PiFlow owns the host development launcher and state synchronization.
 
-## What Freeflow Is Not
+## What Freeflow is not
 
-- Not a new agent.
-- Not a mandatory phase pipeline.
-- Not a CLI enforcement framework.
+- Not a new agent or workflow engine.
+- Not a rigid phase pipeline.
+- Not a permission or CLI enforcement framework.
 - Not a replacement for repository instructions, tests, policies, or review culture.
-- Not old Orchestra with a smaller README.
 - Not proof that the current candidate is behaviorally ready.
 
 ## License