@hassangameryt/freeflow 0.6.0 → 0.7.1

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "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.6.0",
+  "description": "Freeflow gives coding agents an Interaction Contract, adaptive Workflow, focused methods, and durable task memory.",
+  "version": "0.7.1",
   "author": {
     "name": "Hassan Mohiddin"
   },
@@ -9,6 +9,7 @@
   "repository": "https://github.com/hassan-mohiddin/freeflow",
   "license": "MIT",
   "skills": "./skills/",
+  "hooks": "./hooks/claude/hooks.json",
   "keywords": [
     "workflow",
     "skills",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "freeflow",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"
@@ -21,18 +21,17 @@
     "claude"
   ],
   "skills": "./skills/",
-  "hooks": "./hooks/hooks.json",
+  "hooks": "./hooks/codex/hooks.json",
   "interface": {
     "displayName": "Freeflow",
     "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.",
+    "longDescription": "Freeflow gives coding agents an Interaction Contract, adaptive Workflow, focused methods, and durable task memory.",
     "developerName": "Hassan Mohiddin",
     "category": "Coding",
     "capabilities": ["Interactive", "Read", "Write"],
     "defaultPrompt": [
-      "Use Freeflow workflow mode for this task.",
-      "Keep this in conversation mode.",
-      "Use strict-workflow for this risky change."
+      "Use Freeflow's adaptive Workflow for this task.",
+      "Respect the Interaction Contract and ask before going beyond the requested scope."
     ],
     "websiteURL": "https://github.com/hassan-mohiddin/freeflow",
     "privacyPolicyURL": "https://github.com/hassan-mohiddin/freeflow/blob/main/README.md",

package/.cursor-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "freeflow",
+  "description": "Feedback-based control system for coding agents.",
+  "version": "0.7.1",
+  "author": {
+    "name": "Hassan Mohiddin"
+  },
+  "homepage": "https://github.com/hassan-mohiddin/freeflow",
+  "repository": "https://github.com/hassan-mohiddin/freeflow",
+  "license": "MIT",
+  "skills": "./skills/",
+  "hooks": "./hooks/cursor/hooks.json",
+  "logo": "assets/freeflow-plugin-icon-transparent.png",
+  "keywords": [
+    "workflow",
+    "skills",
+    "agents",
+    "feedback-loop",
+    "task-memory",
+    "planning",
+    "verification",
+    "review",
+    "cursor"
+  ]
+}

package/README.md

@@ -2,7 +2,7 @@
 
 **A feedback-based control system for coding agents.**
 
-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.
+Freeflow helps coding agents do consequential work without turning every task into a rigid ceremony. It gives the agent a clear Interaction Contract, adaptive Workflow, focused methods, durable task memory, and controlled delivery boundaries.
 
 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.
 
@@ -15,7 +15,7 @@ Coding agents commonly fail at control boundaries:
 | 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 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. |
+| Every task receives unnecessary ceremony. | Workflow enters at the narrowest useful owner and scales pressure to risk. |
 | 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. |
@@ -26,7 +26,7 @@ Coding agents commonly fail at control boundaries:
 - [Host support](#host-support)
 - [Capabilities](#capabilities)
 - [Quick start](#quick-start)
-- [Modes and workflow](#modes-and-workflow)
+- [Workflow](#workflow)
 - [System prompt architecture](#system-prompt-architecture)
 - [Evidence and limits](#evidence-and-limits)
 - [Commands](#commands)
@@ -41,21 +41,16 @@ Freeflow uses one active agent, one shared context, and nested feedback loops:
 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
+   └─ Cognitive Execution Routes — automatic control only
+      ├─ Reasoning chooses one route
+      │  ├─ YIELD → Standard leads ordinary work → YIELD HANDOFF → Reasoning
+      │  ├─ DELEGATE → open model-written boundary → Standard executes
+      │  │  └─ RETURN → Reasoning assesses; boundary remains open until CLOSE
+      │  └─ TASK ACT → Reasoning performs narrow direct OBSERVE or ACT_BOUNDED
+      └─ Action Selection guides uncertain environment interactions
 ```
 
-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.
+Under automatic Cognitive Routing control, each new user interaction begins in Reasoning. Under manual control, the selected compute profile runs the ordinary unsplit Workflow. Cognitive Routing changes compute placement only. It never changes authority, ownership, task scope, evidence requirements, or review independence.
 
 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.
 
@@ -65,12 +60,18 @@ Freeflow is one package with different host boundaries:
 
 | Host | Freeflow support | Cognitive 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 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.
+| Codex | Shared skills and Codex `SessionStart` hook | Not available; Pi/PiFlow capabilities are not delivered |
+| Claude Code | Shared skills and Claude Code `SessionStart` hook | Not available; Pi/PiFlow capabilities are not delivered |
+| Gemini CLI | Gemini extension manifest, shared skills, and Gemini `SessionStart` hook | Not available; Pi/PiFlow capabilities are not delivered |
+| Cursor | Agent Plugins 1.0 skills plus Cursor-specific hook delivery | Not available; Pi/PiFlow capabilities are not delivered |
+| GitHub Copilot / VS Code | Agent Plugins 1.0 skills plus Copilot-specific hook delivery | Not available; Pi/PiFlow capabilities are not delivered |
+| Kiro | Agent Plugins 1.0 Power and shared skills | Not available; no Kiro-specific runtime adapter is claimed |
+| OpenCode v2 | Canonical `skills/` through OpenCode’s 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, Pi extension, optional context capabilities, and native host controls | Available when configured and the official model-state APIs are present |
+| PiFlow | Freeflow package hosted by the separate PiFlow distribution | Available when configured |
+
+Freeflow owns workflow policy, portable prompt fragments, the 25-skill distribution kernel, host adapters, Pi/PiFlow capabilities, and the Pi extension. Each host owns its launch, package installation, session state, updates, and native model-state control; PiFlow remains a supported host integration.
 
 ## Capabilities
 
@@ -78,20 +79,20 @@ Freeflow owns workflow policy, prompt fragments, skills, capabilities, and the P
 
 - **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.
+- **Track Work** maintains a 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.
 
 ### Optional host capabilities
 
-- **[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.
+- **[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 in Pi and PiFlow. It remains 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.
 
-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.
+The three capabilities are individually gated and default-off or unavailable unless their configuration and host conditions are effective. None grants authority or replaces Workflow.
 
 ## Quick start
 
-For the complete host-specific setup, see [Getting Started](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/getting-started.md).
+For complete host-specific setup, see [Getting Started](https://github.com/hassan-mohiddin/freeflow/blob/main/plugin-docs/getting-started.md).
 
 ### Codex
 
@@ -111,6 +112,24 @@ Trust the Freeflow hook from `/hooks`, then start a new session.
 /reload-plugins
 ```
 
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/hassan-mohiddin/freeflow
+```
+
+Restart Gemini CLI after installation or updates. The extension uses the root `gemini-extension.json`, shared `skills/`, and its Gemini-specific `SessionStart` hook adapter.
+
+### Cursor, GitHub Copilot, VS Code, Kiro, OpenCode, and Hermes Agent
+
+These hosts consume the root Agent Plugins 1.0 manifest and the same `skills/` directory. Cursor also reads `.cursor-plugin/plugin.json` for its host-specific hook surface; GitHub Copilot and VS Code read the `com.github.copilot/` extension namespace. Install from each host’s documented plugin source or marketplace UI. For Copilot CLI, the direct repository form is:
+
+```bash
+copilot plugin install hassan-mohiddin/freeflow
+```
+
+VS Code provides **Chat: Install Plugin From Source**. Kiro exposes compatible Agent Plugins as Powers and can import a GitHub source through its Powers UI. OpenCode v2 can add the checkout or package’s `skills/` directory to the documented `skills` array in `opencode.json`; it does not receive a native Freeflow plugin runtime. Hermes can install the root portable package with `hermes plugins install hassan-mohiddin/freeflow --no-enable`, then enable it with `hermes plugins enable freeflow`, or use its documented skills source workflow. A host’s install/trust UI and marketplace availability are external to this repository’s deterministic checks.
+
 ### Pi
 
 ```bash
@@ -123,6 +142,8 @@ Or:
 pi install git:github.com/hassan-mohiddin/freeflow
 ```
 
+The full normal-Pi integration targets Pi 0.84.3 or newer; Pi 0.84.4 is the current Cognitive Routing test target.
+
 ### PiFlow
 
 Install PiFlow separately, then install Freeflow into it:
@@ -144,19 +165,13 @@ In the target repository, run:
 /setup-freeflow
 ```
 
-Setup creates `.freeflow/config.json`, the required shared activation boundary. `.freeflow/local.json` is an optional personal override and cannot activate Freeflow by itself.
+Setup creates `.freeflow/config.json`, the required shared activation boundary. Minimal activation is `{}`. `.freeflow/local.json` is an optional personal override and cannot activate Freeflow by itself.
 
-## Modes and workflow
+## Workflow
 
-Freeflow has exactly three modes:
-
-| 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 |
+Freeflow always uses one adaptive Workflow. The Interaction Contract interprets the whole user turn; Workflow then chooses the narrowest owner and scales coordination to consequence, uncertainty, interaction, and reversibility.
 
-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.
+A question or tentative idea remains discussion until clear action authority exists. A direct request covers only its bounded outcome and entailed effects. Risk-sensitive work receives stronger decisions, evidence, verification, and checkpoints through the same Workflow rather than through a separate selectable process.
 
 Every bounded activity follows the same Feedback Loop:
 
@@ -171,13 +186,14 @@ orient to accepted intent, task memory, and live evidence
 
 ## System prompt architecture
 
-Freeflow’s model-facing surface has three layers:
+Freeflow’s model-facing surface has four coordinated parts:
 
-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.
+1. **Core guidance** in `runtime/prompts/core.md` contains identity, shared terms, loops, Workflow, Action Selection, and Supported Exit cues.
+2. **Interaction Contract** in `runtime/prompts/interaction-contract.md` remains a separate mandatory fragment so its behavior can be revised independently.
+3. **Runtime State** reports current capability availability and Cognitive Routing `Control`/`Profile` at session start, after context reconstruction or loss, and when displayed state changes; unchanged state remains in the current provider context.
+4. **Discoverable skills and tools** provide the 25 base methods and individually gated optional capability operations.
 
-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.
+The core guidance and Interaction Contract are always delivered together when Freeflow is enabled. Optional capability content is omitted and reported unavailable rather than fabricated. One effective-state snapshot determines prompt assembly, discovery, tools, and projection.
 
 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.
 
@@ -186,6 +202,8 @@ Read the full [System Prompt Architecture](https://github.com/hassan-mohiddin/fr
 Freeflow is explicit about what its checks prove:
 
 - deterministic checks prove structure, assembly, package boundaries, and selected delivery behavior;
+- host-manifest and adapter checks prove the Agent Plugins 1.0, Gemini, Cursor, and Copilot/VS Code package shapes, not native host dispatch;
+- OpenCode and Hermes compatibility checks cover the canonical Agent Skills/Agent Plugins package shape, not native host plugin APIs or runtime prompt delivery;
 - 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;
@@ -228,32 +246,24 @@ Contributor calls:
 /evaluate-skill
 ```
 
-Mode controls:
-
-```text
-/freeflow mode conversation
-/freeflow mode workflow
-/freeflow mode strict-workflow
-/freeflow mode reset
-```
-
-Pi settings and PiFlow-only Cognitive Routing controls:
+Pi and PiFlow Cognitive Routing controls:
 
 ```text
 /freeflow
+/freeflow settings
+/freeflow settings session
+/freeflow settings repo
 /freeflow profile standard
 /freeflow profile reasoning
 /freeflow profile auto
 ```
 
-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.
+`/freeflow settings` edits personal overrides, `/freeflow settings session` manages temporary enablement and optional-context overrides, and `/freeflow settings repo` edits shared repository settings. Profile changes require an idle host with the required model-state APIs.
 
-In PiFlow, while the host is idle:
+In Pi or PiFlow, while the host is idle:
 
 - `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.
-
-Normal Pi does not register these Cognitive Routing shortcuts.
+- `Ctrl+Shift+A` sets automatic control; from a manual hold, it releases the hold and moves to Reasoning when necessary. Repeating it while already automatic is idempotent.
 
 ## Documentation and development