@hassangameryt/freeflow 0.3.0 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
   "name": "freeflow",
-  "description": "Lightweight workflow for coding agents.",
+  "description": "Feedback-based control system for coding agents.",
   "owner": {
     "name": "Hassan Mohiddin",
     "url": "https://github.com/hassan-mohiddin"
@@ -9,10 +9,10 @@
   "plugins": [
     {
       "name": "freeflow",
-      "description": "Conversation, workflow, and strict-workflow skills for coding agents.",
-      "version": "0.3.0",
+      "description": "Feedback-based control for coding agents.",
+      "version": "0.4.0",
       "category": "development",
-      "source": ".",
+      "source": "./",
       "author": {
         "name": "Hassan Mohiddin"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "freeflow",
-  "description": "Lightweight workflow for coding agents. Conversation, workflow, and strict-workflow skills for planning, execution, review, verification, handoff, and decision capture.",
-  "version": "0.3.0",
+  "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",
   "author": {
     "name": "Hassan Mohiddin"
   },
@@ -12,8 +12,11 @@
     "workflow",
     "skills",
     "agents",
+    "feedback-loop",
+    "task-memory",
     "planning",
     "verification",
+    "review",
     "claude-code",
     "codex"
   ]

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "freeflow",
-  "version": "0.3.0",
-  "description": "Lightweight workflow for coding agents.",
+  "version": "0.4.0",
+  "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"
   },
@@ -12,23 +12,22 @@
     "workflow",
     "skills",
     "agents",
+    "feedback-loop",
+    "task-memory",
     "planning",
     "verification",
+    "review",
     "codex",
     "claude"
   ],
   "skills": "./skills/",
   "interface": {
     "displayName": "Freeflow",
-    "shortDescription": "Lightweight workflow for coding agents.",
-    "longDescription": "Freeflow guides coding agents through conversation, workflow, and strict-workflow modes with interview gates, source-truth checks, planning, execution, review, verification, commit discipline, handoffs, and durable decision capture.",
+    "shortDescription": "Feedback-based control for coding agents.",
+    "longDescription": "Freeflow gives coding agents an Interaction Contract, evidence-driven Workflow, focused methods, and durable task memory across conversation, workflow, and strict-workflow modes.",
     "developerName": "Hassan Mohiddin",
     "category": "Coding",
-    "capabilities": [
-      "Interactive",
-      "Read",
-      "Write"
-    ],
+    "capabilities": ["Interactive", "Read", "Write"],
     "defaultPrompt": [
       "Use Freeflow workflow mode for this task.",
       "Keep this in conversation mode.",

package/README.md

@@ -1,73 +1,142 @@
 # Freeflow
 
-Lightweight workflow for coding agents.
+**A feedback-based control system for coding agents.**
 
-Agent workflow tools tend to choose one side of the problem: sharp point skills, full lifecycle methodology, or enforcement-heavy runtimes. The missing layer is a small workflow spine that prevents silent product decisions, source-truth rewrites, fake verification, and messy handoffs without turning every change into a process operating system.
+Freeflow helps coding agents move through consequential work without a rigid pipeline, silent decisions, or context-heavy ceremony.
 
-## Workflow
+> Use feedback to choose the smallest useful next action.
 
-Freeflow is a workflow layer, not a new agent. It helps the agent choose the right amount of process for the task.
+> Re-enter the narrowest owning activity when evidence changes the path.
 
-### Modes
+> Memory preserves context. It does not create authority.
 
-- `conversation`: non-mutating discussion, read-only exploration, and planning in chat; edits or other state-changing work require switching to `workflow` or `strict-workflow` first.
-- `workflow`: default for consequential work; use the workflow spine and scale detail to risk.
-- `strict-workflow`: high-risk or hard-to-reverse work with stronger gates.
+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.
 
-Use strict-workflow for security, privacy, billing, public APIs, migrations, data loss, compatibility, permissions, deployment, or irreversible architecture.
+## Why Freeflow
 
-### Map
+Coding agents are strong at mutation and weak at control boundaries:
 
-```mermaid
-flowchart LR
-  Request{request}
-  Talk[conversation<br/>answer directly]
-  Discover[discover<br/>research checkpoint]
-  Spec[spec]
-  Plan[plan]
-  Build[build<br/>execute / diagnose]
-  Check[review + verify]
-  Close[commit / handoff]
+| Common failure | 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. |
 
-  Request -->|question| Talk
-  Request -->|work| Discover
-  Discover --> Spec --> Plan --> Build --> Check --> Close
-  Check -. new evidence or failed check .-> Discover
-```
+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
 
-The map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates.
+One user interaction is an **Interaction Lifecycle**:
 
-### Backward Edge
+![Freeflow Workflow: Entry, Feedback Loop, and Supported Exit](assets/workflow.png)
+
+```text
+[Entry] -> [Feedback Loop when needed] -> [Supported Exit]
+   ^              ^        |                  |
+   |              |________|                  |
+   |__________________________________________|
+            later user turn or evidence
+```
 
-Loop back when new evidence changes the path:
+When work is needed, the inner **Feedback Loop** is:
 
-```mermaid
-flowchart LR
-  Trigger{new evidence<br/>conflict<br/>failed check<br/>owner decision}
-  Decide{changes<br/>next action?}
-  Continue[continue]
-  Reenter[clarify / research<br/>revise spec or plan<br/>diagnose / split / stop]
+![Freeflow Core Feedback Loop: orient, use the owning skill, verify, self-review once, and route from evidence](assets/feedback-loop.png)
 
-  Trigger --> Decide
-  Decide -->|no| Continue
-  Decide -->|yes| Reenter
-  Reenter -. resume .-> Decide
+```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
 ```
 
-The agent should not silently choose the backward destination when the choice changes product behavior, scope, compatibility, public APIs, security, privacy, billing, data loss, permissions, or irreversible architecture.
+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.
+
+## Core Principles
+
+- **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.**
+
+## Modes
+
+Freeflow has exactly three modes:
+
+| Mode | Use for | Guardrail |
+| --- | --- | --- |
+| `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
+
+Freeflow ships 26 skill packages:
+
+- 25 active model/contributor skills;
+- Output Router as an optional capability loaded only when effective.
+
+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.
 
-### Bypass
+## Task Memory Without A Second Task System
 
-Bypass skips ceremony, not judgment.
+Track Work maintains one Working Record for an ongoing task:
 
-Use `bypass` only to skip an unnecessary gate. It does not skip user-owned decisions, source-truth conflicts, risky checks, or fresh verification before completion claims.
+- 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.
+
+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 |
+
+Output Router is disabled by default. Setup enables it only after an explicit request.
+
+## 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
 
 ### Codex
 
-Register the GitHub repo as a Codex marketplace, refresh it, then install Freeflow:
-
 ```bash
 codex plugin marketplace add https://github.com/hassan-mohiddin/freeflow.git
 codex plugin marketplace upgrade freeflow
@@ -75,151 +144,144 @@ codex plugin add freeflow@freeflow
 codex plugin list | rg freeflow
 ```
 
-In the Codex app, add the same GitHub marketplace URL from `/plugins`, then search for `freeflow`.
+Trust the Freeflow `SessionStart` hook from `/hooks` when Codex requests review.
 
 ### Claude Code
 
-Register the marketplace:
-
 ```bash
 /plugin marketplace add hassan-mohiddin/freeflow
 /plugin install freeflow
 ```
 
-Or install directly from GitHub:
-
-```bash
-/plugin install hassan-mohiddin/freeflow
-```
-
-### Pi Coding Agent
-
-Install Freeflow as a native Pi package from npm:
+### Pi
 
 ```bash
 pi install npm:@hassangameryt/freeflow
 ```
 
-Or install directly from GitHub:
+Or:
 
 ```bash
 pi install git:github.com/hassan-mohiddin/freeflow
 ```
 
-For local development from this checkout:
+## Activate In A Repository
 
-```bash
-pi install .
-```
-
-The Pi package exposes Freeflow skills and a small extension that registers direct Freeflow commands and loads mode-contract, workflow, interview-gate, discover, and output-router context before agent turns.
-
-### Required Step 1: Run Setup
-
-**Run this in every repo after installing Freeflow:**
+Run:
 
 ```text
 /setup-freeflow
 ```
 
-Setup creates the repo activation file and `.freeflow/config.json`. It does not create repo-local hooks, docs inventories, state files, handoffs, or `.codex/rules` behavior files.
-
-After successful setup, the setup skill reads the mode-contract, workflow, interview-gate, discover, and output-router skills before its final response so the current session can continue with Freeflow loaded.
+Minimal setup creates shared activation:
 
-### Required Step 2: Enable Hooks
+```json
+{
+  "defaultMode": "workflow"
+}
+```
 
-**In Codex, open the hooks screen and trust the Freeflow `SessionStart` hook:**
+Configuration layers are:
 
 ```text
-/hooks
+Pi session capability or mode override
+-> .freeflow/local.json personal core override
+-> .freeflow/config.json shared repository value
+-> built-in default
 ```
 
-Press `t` to trust/enable the hook when Codex marks it as needing review.
-
-Once enabled, the hook loads Freeflow mode-contract, workflow, interview-gate, discover, and output-router context at session start, resume, clear, and compact.
+`.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.
 
-In Pi, Freeflow's package extension provides the context-loading hook through Pi lifecycle events. It refreshes workflow context on session start and compact, then injects it before agent turns. If you install it project-locally, trust the project when Pi prompts for project-local package resources.
+## Runtime Delivery
 
-These hooks do not run after every edit, block tools, grant permissions, or enforce workflow policy.
+When effective, host adapters deliver:
 
-### Other Agents
+- `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.
 
-Copy the `skills/` directory into the agent's skills/plugin system and make sure the agent can read `SKILL.md` files with bundled `references/`.
+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.
 
-## Usage
+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.
 
-Use natural language first:
+## Commands
 
-```text
-Use Freeflow workflow mode for this task.
-Keep this in conversation mode.
-Use strict-workflow for this billing change.
-Verify before claiming completion.
-Create a research checkpoint.
-```
-
-Slash-style prompts are model-routed in Codex and Claude:
+Natural language is preferred. Pi registers these canonical direct calls:
 
 ```text
-/workflow conversation
-/workflow workflow
-/workflow strict-workflow
-/workflow reset
-/research
+/discuss
+/track-work
 /write-spec
 /review-artifact
 /write-plan
-/execute-plan
+/execute-work
+/simplify-code
+/migration-work
 /diagnose-failure
 /verify-work
 /review-work
 /commit-work
 /handoff
+/finish-branch
+/release-work
+/launch-work
 /bypass
-/output-router
 ```
 
-For Codex and Claude, these commands work as skill-routing language. In Pi, the package extension registers native command handlers for Freeflow commands. Pi `/workflow` mode changes are session-scoped and update the footer; `.freeflow/config.json` remains the repo default only.
+Pi-only compatibility aliases:
 
-## Docs
+```text
+/discover
+/execute-plan
+```
 
-- [Docs index](plugin-docs/README.md)
-- [Workflow](plugin-docs/workflow.md)
-- [Skills](plugin-docs/skills.md)
-- [Architecture](plugin-docs/architecture.md)
-- [Release evidence](plugin-docs/release-evidence.md)
-- [ADRs](plugin-docs/adr/README.md)
+Contributor calls:
 
-## Evidence
+```text
+/setup-freeflow
+/write-skill
+/evaluate-skill
+```
 
-Freeflow does not claim to beat Matt Pocock's skills or Obra's Superpowers. Those are references for skill sharpness and lifecycle discipline. Current evals compare baseline agent behavior against Freeflow instructions/skills, then verify command coverage.
+Mode controls:
 
-| Report | Baseline | With Freeflow | What It Shows |
-| --- | ---: | ---: | --- |
-| v0.1 acceptance suite | - | 15/15 pass | Required release behaviors passed after measured fixes. |
-| Always-on source-truth conflict | 2/10 | 10/10 | Freeflow stopped a pressured billing rewrite, made no edits, named the conflict, and asked for the policy decision. |
-| Write spec from stale handoff | 4/10 | 10/10 | Freeflow refused to supersede billing policy from stale handoff text. |
-| Write plan with hidden billing decision | 4/10 | 10/10 | Freeflow created no plan, named the policy conflict, and asked which path to follow. |
-| Cold spec call without context | 2/10 | 10/10 | Freeflow did not invent onboarding behavior from adjacent files. |
-| Workflow context lifecycle | fail | pass | Setup loads workflow context for the same session; session-start hooks load workflow context without `PostToolUse`. |
-| Output router retrieval | - | 7/7 pass | Deterministic router evidence fixes generated-artifact false positives while keeping scanner retrieval default. |
-| Output router run recovery | - | 8/8 pass + script-producer unit coverage | `freeflow_run` preserves exact facts and verifies raw vault recovery for routed command output; sandboxed script producers capture stdout/stderr through the same run pipeline. |
-| Codex Structured Q&A | native proxy 0/1 | improved router 1/1 | Sandbox Permissions Q&A resolves to the source markdown instead of a generated `graphify-out` decoy. |
-| Command surface audit | - | Pass | 4 mode commands, 12 direct skill calls, and 3 developer skill calls are covered while native slash handlers remain disabled for Codex/Claude. |
+```text
+/freeflow mode conversation
+/freeflow mode workflow
+/freeflow mode strict-workflow
+/freeflow mode reset
+```
 
-Eval sources and reports live with the plugin under `evals/`; generated run output is ignored. Concise release evidence is summarized in [plugin-docs/release-evidence.md](plugin-docs/release-evidence.md).
+Pi-native settings controls:
+
+```text
+/freeflow
+/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.
+
+Direct skill calls select a method. They do not change mode, authorize mutation, or create independent review context.
+
+## Public Docs
+
+- [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)
+- [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)
 
 ## What Freeflow Is Not
 
 - Not a new agent.
-- Not a CLI framework.
-- Not an enforcement hook system.
+- Not a mandatory phase pipeline.
+- Not a CLI enforcement framework.
+- Not a replacement for repository instructions, tests, policies, or review culture.
 - Not old Orchestra with a smaller README.
-- Not a replacement for Matt's skills or Superpowers.
-
-The shipped hooks are context-loading only. They do not enforce policy, block tools, or replace repo instructions.
-
-Freeflow is the lightweight workflow layer between point skills and full process systems.
+- Not proof that the current candidate is behaviorally ready.
 
 ## License
 

package/command-surface.json

@@ -2,26 +2,36 @@
   "nativeSlashHandlers": false,
   "modeCommands": [
     {
-      "command": "/workflow conversation",
+      "command": "/freeflow mode conversation",
       "routesTo": "mode-contract"
     },
     {
-      "command": "/workflow workflow",
+      "command": "/freeflow mode workflow",
       "routesTo": "mode-contract"
     },
     {
-      "command": "/workflow strict-workflow",
+      "command": "/freeflow mode strict-workflow",
       "routesTo": "mode-contract"
     },
     {
-      "command": "/workflow reset",
+      "command": "/freeflow mode reset",
       "routesTo": "mode-contract"
     }
   ],
   "directSkillCalls": [
+    {
+      "command": "/discuss",
+      "skill": "discuss"
+    },
     {
       "command": "/discover",
-      "skill": "discover"
+      "skill": "discuss",
+      "aliasFor": "/discuss",
+      "piOnly": true
+    },
+    {
+      "command": "/track-work",
+      "skill": "track-work"
     },
     {
       "command": "/write-spec",
@@ -35,9 +45,23 @@
       "command": "/write-plan",
       "skill": "write-plan"
     },
+    {
+      "command": "/execute-work",
+      "skill": "execute-work"
+    },
     {
       "command": "/execute-plan",
-      "skill": "execute-plan"
+      "skill": "execute-work",
+      "aliasFor": "/execute-work",
+      "piOnly": true
+    },
+    {
+      "command": "/simplify-code",
+      "skill": "simplify-code"
+    },
+    {
+      "command": "/migration-work",
+      "skill": "migration-work"
     },
     {
       "command": "/diagnose-failure",
@@ -59,13 +83,33 @@
       "command": "/handoff",
       "skill": "handoff"
     },
+    {
+      "command": "/finish-branch",
+      "skill": "finish-branch"
+    },
+    {
+      "command": "/release-work",
+      "skill": "release-work"
+    },
+    {
+      "command": "/launch-work",
+      "skill": "launch-work"
+    },
     {
       "command": "/bypass",
       "skill": "bypass"
+    }
+  ],
+  "piNativeCommands": [
+    {
+      "command": "/freeflow",
+      "handler": "freeflow",
+      "kind": "settings"
     },
     {
       "command": "/output-router",
-      "skill": "output-router"
+      "handler": "output-router",
+      "kind": "settings"
     }
   ],
   "developerSkillCalls": [