@hassangameryt/freeflow 0.1.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "freeflow",
+  "interface": {
+    "displayName": "Freeflow"
+  },
+  "plugins": [
+    {
+      "name": "freeflow",
+      "source": {
+        "source": "local",
+        "path": "./plugins/freeflow"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
+    }
+  ]
+}

package/.claude-plugin/marketplace.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "freeflow",
+  "description": "Lightweight workflow for coding agents.",
+  "owner": {
+    "name": "Hassan Mohiddin",
+    "url": "https://github.com/hassan-mohiddin"
+  },
+  "plugins": [
+    {
+      "name": "freeflow",
+      "description": "Conversation, workflow, and strict-workflow skills for coding agents.",
+      "version": "0.1.0",
+      "category": "development",
+      "source": "./plugins/freeflow",
+      "author": {
+        "name": "Hassan Mohiddin"
+      },
+      "homepage": "https://github.com/hassan-mohiddin/freeflow"
+    }
+  ]
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hassan Mohiddin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,217 @@
+# Freeflow
+
+Lightweight workflow 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.
+
+## Workflow
+
+Freeflow is a workflow layer, not a new agent. It helps the agent choose the right amount of process for the task.
+
+### Modes
+
+- `conversation`: answer, explain, critique, or explore without workflow pressure.
+- `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.
+
+Use strict-workflow for security, privacy, billing, public APIs, migrations, data loss, compatibility, permissions, deployment, or irreversible architecture.
+
+### Map
+
+```mermaid
+flowchart LR
+  Request{request}
+  Talk[conversation<br/>answer directly]
+  Discover[discover<br/>research / grill]
+  Spec[spec]
+  Plan[plan]
+  Build[build<br/>execute / diagnose]
+  Check[review + verify]
+  Close[commit / handoff]
+
+  Request -->|question| Talk
+  Request -->|work| Discover
+  Discover --> Spec --> Plan --> Build --> Check --> Close
+  Check -. new evidence or failed check .-> Discover
+```
+
+The map is orienting, not mandatory. Small reversible work can skip unnecessary artifacts and gates.
+
+### Backward Edge
+
+Loop back when new evidence changes the path:
+
+```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]
+
+  Trigger --> Decide
+  Decide -->|no| Continue
+  Decide -->|yes| Reenter
+  Reenter -. resume .-> Decide
+```
+
+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.
+
+### Bypass
+
+Bypass skips ceremony, not judgment.
+
+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.
+
+## 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
+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`.
+
+### 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:
+
+```bash
+pi install npm:@hassangameryt/freeflow
+```
+
+Or install directly from GitHub:
+
+```bash
+pi install git:github.com/hassan-mohiddin/freeflow
+```
+
+For local development from this checkout:
+
+```bash
+pi install .
+```
+
+The Pi package exposes Freeflow skills and a small extension that registers direct Freeflow commands and loads workflow skill/map context before agent turns.
+
+### Required Step 1: Run Setup
+
+**Run this in every repo after installing Freeflow:**
+
+```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 workflow skill and workflow map before its final response so the current session can continue with Freeflow loaded.
+
+### Required Step 2: Enable Hooks
+
+**In Codex, open the hooks screen and trust the Freeflow `SessionStart` hook:**
+
+```text
+/hooks
+```
+
+Press `t` to trust/enable the hook when Codex marks it as needing review.
+
+Once enabled, the hook loads Freeflow workflow context at session start, resume, clear, and compact.
+
+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.
+
+These hooks do not run after every edit, block tools, grant permissions, or enforce workflow policy.
+
+### Other Agents
+
+Copy the `plugins/freeflow/skills/` directory into the agent's skills/plugin system and make sure the agent can read `SKILL.md` files with bundled `references/`.
+
+## Usage
+
+Use natural language first:
+
+```text
+Use Freeflow workflow mode for this task.
+Keep this in conversation mode.
+Use strict-workflow for this billing change.
+Verify before claiming completion.
+Capture the durable decision.
+```
+
+Slash-style prompts are model-routed in v0.1:
+
+```text
+/workflow conversation
+/workflow workflow
+/workflow strict-workflow
+/workflow reset
+/write-spec
+/write-plan
+/execute-plan
+/verify-work
+/commit-work
+/handoff
+```
+
+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.
+
+## Docs
+
+- [Docs index](plugins/freeflow/docs/README.md)
+- [Workflow](plugins/freeflow/docs/workflow.md)
+- [Skills](plugins/freeflow/docs/skills.md)
+- [Architecture](plugins/freeflow/docs/architecture.md)
+- [Release evidence](plugins/freeflow/docs/release-evidence.md)
+- [ADRs](plugins/freeflow/docs/adr/README.md)
+
+## Evidence
+
+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.
+
+| 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`. |
+| Command surface audit | - | Pass | 3 mode commands, 13 direct skill calls, and 2 developer skill calls are covered while native slash handlers remain disabled. |
+
+Eval sources and reports live with the plugin under `plugins/freeflow/evals/`; generated run output is ignored. Concise release evidence is summarized in [plugins/freeflow/docs/release-evidence.md](plugins/freeflow/docs/release-evidence.md).
+
+## What Freeflow Is Not
+
+- Not a new agent.
+- Not a CLI framework.
+- Not an enforcement hook system.
+- 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.
+
+## License
+
+MIT License. Copyright (c) 2026 Hassan Mohiddin.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@hassangameryt/freeflow",
+  "version": "0.1.0",
+  "description": "Lightweight workflow for coding agents.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": {
+    "name": "Hassan Mohiddin"
+  },
+  "homepage": "https://github.com/hassan-mohiddin/freeflow",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hassan-mohiddin/freeflow.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "agent-skills",
+    "workflow",
+    "skills",
+    "agents",
+    "planning",
+    "verification",
+    "codex",
+    "claude",
+    "pi"
+  ],
+  "pi": {
+    "skills": [
+      "plugins/freeflow/skills"
+    ],
+    "extensions": [
+      "plugins/freeflow/pi-extension/index.js"
+    ],
+    "image": "https://raw.githubusercontent.com/hassan-mohiddin/freeflow/main/plugins/freeflow/assets/freeflow-plugin-icon-transparent.png"
+  },
+  "files": [
+    ".agents/**",
+    ".claude-plugin/**",
+    "LICENSE",
+    "README.md",
+    "plugins/freeflow/.claude-plugin/**",
+    "plugins/freeflow/.codex-plugin/**",
+    "plugins/freeflow/assets/**",
+    "plugins/freeflow/command-surface.json",
+    "plugins/freeflow/docs/**",
+    "plugins/freeflow/hooks/**",
+    "plugins/freeflow/pi-extension/**",
+    "plugins/freeflow/skills/**"
+  ]
+}

package/plugins/freeflow/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "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.1.0",
+  "author": {
+    "name": "Hassan Mohiddin"
+  },
+  "homepage": "https://github.com/hassan-mohiddin/freeflow",
+  "repository": "https://github.com/hassan-mohiddin/freeflow",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "skills",
+    "agents",
+    "planning",
+    "verification",
+    "claude-code",
+    "codex"
+  ]
+}

package/plugins/freeflow/.codex-plugin/plugin.json

@@ -0,0 +1,44 @@
+{
+  "name": "freeflow",
+  "version": "0.1.0",
+  "description": "Lightweight workflow for coding agents.",
+  "author": {
+    "name": "Hassan Mohiddin"
+  },
+  "homepage": "https://github.com/hassan-mohiddin/freeflow",
+  "repository": "https://github.com/hassan-mohiddin/freeflow",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "skills",
+    "agents",
+    "planning",
+    "verification",
+    "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.",
+    "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."
+    ],
+    "websiteURL": "https://github.com/hassan-mohiddin/freeflow",
+    "privacyPolicyURL": "https://github.com/hassan-mohiddin/freeflow/blob/main/README.md",
+    "termsOfServiceURL": "https://github.com/hassan-mohiddin/freeflow/blob/main/LICENSE",
+    "brandColor": "#2563EB",
+    "composerIcon": "./assets/freeflow-plugin-icon-transparent.png",
+    "logo": "./assets/freeflow-plugin-icon-transparent.png"
+  }
+}

package/plugins/freeflow/command-surface.json

@@ -0,0 +1,85 @@
+{
+  "nativeSlashHandlers": false,
+  "modeCommands": [
+    {
+      "command": "/workflow conversation",
+      "routesTo": "mode-contract"
+    },
+    {
+      "command": "/workflow workflow",
+      "routesTo": "mode-contract"
+    },
+    {
+      "command": "/workflow strict-workflow",
+      "routesTo": "mode-contract"
+    },
+    {
+      "command": "/workflow reset",
+      "routesTo": "mode-contract"
+    }
+  ],
+  "directSkillCalls": [
+    {
+      "command": "/grill-context",
+      "skill": "grill-context"
+    },
+    {
+      "command": "/research-brief",
+      "skill": "research-brief"
+    },
+    {
+      "command": "/write-spec",
+      "skill": "write-spec"
+    },
+    {
+      "command": "/review-artifact",
+      "skill": "review-artifact"
+    },
+    {
+      "command": "/write-plan",
+      "skill": "write-plan"
+    },
+    {
+      "command": "/execute-plan",
+      "skill": "execute-plan"
+    },
+    {
+      "command": "/diagnose-failure",
+      "skill": "diagnose-failure"
+    },
+    {
+      "command": "/verify-work",
+      "skill": "verify-work"
+    },
+    {
+      "command": "/review-work",
+      "skill": "review-work"
+    },
+    {
+      "command": "/commit-work",
+      "skill": "commit-work"
+    },
+    {
+      "command": "/capture-decisions",
+      "skill": "capture-decisions"
+    },
+    {
+      "command": "/handoff",
+      "skill": "handoff"
+    },
+    {
+      "command": "/bypass",
+      "skill": "bypass"
+    }
+  ],
+  "developerSkillCalls": [
+    {
+      "command": "/write-skill",
+      "skill": "write-skill"
+    },
+    {
+      "command": "/evaluate-skill",
+      "skill": "evaluate-skill"
+    }
+  ]
+}

package/plugins/freeflow/docs/README.md

@@ -0,0 +1,39 @@
+# Freeflow Docs
+
+These docs describe the public plugin behavior. Historical research stays in root `docs/`; eval sources and reports live under `plugins/freeflow/evals/`.
+
+After installing Freeflow, run setup in each repo where you want it active:
+
+```text
+/setup-freeflow
+```
+
+Setup creates activation/config files only.
+
+In Codex, open the hooks screen after install:
+
+```text
+/hooks
+```
+
+Press `t` to trust/enable the Freeflow `SessionStart` hook when Codex marks it as needing review. Once enabled, plugin-bundled hooks load workflow and interview-gate context at session start, resume, clear, and compact.
+
+In Pi, install Freeflow as a Pi package from npm:
+
+```bash
+pi install npm:@hassangameryt/freeflow
+```
+
+Or install directly from GitHub:
+
+```bash
+pi install git:github.com/hassan-mohiddin/freeflow
+```
+
+The package exposes `plugins/freeflow/skills/` and `plugins/freeflow/pi-extension/index.js`. The Pi extension registers direct Freeflow commands, keeps `/workflow` mode changes scoped to the Pi session, refreshes workflow and interview-gate context on session start and compact, and injects that context before agent turns. It does not enforce policy, block tools, grant permissions, or create repo-local hooks.
+
+- [Workflow](workflow.md): modes, entry points, loops, and the compact workflow map.
+- [Skills](skills.md): shipped skills and what each one is for.
+- [Architecture](architecture.md): package layout, runtime boundary, context hooks, and progressive disclosure model.
+- [Release evidence](release-evidence.md): v0.1 acceptance evidence and deferred checks.
+- [ADRs](adr/README.md): durable release decisions.

package/plugins/freeflow/docs/adr/0001-three-modes.md

@@ -0,0 +1,27 @@
+# ADR 0001: Three Modes
+
+## Status
+
+Accepted.
+
+## Decision
+
+Freeflow has exactly three modes:
+
+- `conversation`
+- `workflow`
+- `strict-workflow`
+
+## Rationale
+
+Three modes give users explicit process control without creating a mode for every task shape.
+
+`conversation` removes workflow pressure for questions and discussion.
+
+`workflow` is the default for consequential work.
+
+`strict-workflow` exists for high-risk or hard-to-reverse work.
+
+## Consequences
+
+Freeflow must scale process inside these modes instead of adding new modes. Host permission modes remain separate from Freeflow workflow modes.

package/plugins/freeflow/docs/adr/0002-evals-before-hooks.md

@@ -0,0 +1,17 @@
+# ADR 0002: Evals Before Enforcement Hooks
+
+## Status
+
+Accepted.
+
+## Decision
+
+Freeflow v0.1 ships plugin-bundled context-loading runtime: Codex/Claude hooks and a Pi extension that load existing workflow and interview-gate context. It still ships without enforcement hooks or CLI enforcement. Behavior must first be proven with baseline-vs-with-skill evals before mechanical enforcement is added.
+
+## Rationale
+
+Context-loading runtime addresses a measured lifecycle gap: workflow and interview-gate context may not be present at session start. The setup skill handles the same-session setup case by reading runtime context after successful verification. Enforcement hooks can prevent expensive mistakes, but early enforcement machinery can hide weak skill wording and turn the package into brittle workflow infrastructure.
+
+## Consequences
+
+Native enforcement remains future work. Enforcement hooks should be added only when a repeated failure is concrete, deterministic, and not solved by concise skill wording.

package/plugins/freeflow/docs/adr/0003-release-boundary.md

@@ -0,0 +1,21 @@
+# ADR 0003: Release Boundary
+
+## Status
+
+Accepted.
+
+## Decision
+
+Freeflow v0.1 ships as a marketplace repo with one plugin runtime under `plugins/freeflow/`.
+
+The plugin runtime includes skills, bundled references, context-loading runtime, public docs, eval sources/reports, command-surface metadata, Codex/Claude metadata, and Pi package metadata/extension.
+
+The runtime excludes generated eval run output, historical research notes, handoffs, enforcement hooks, CLI tools, and old Orchestra compatibility.
+
+## Rationale
+
+The public repo should be installable without generated artifacts or duplicate package copies. Eval definitions and concise reports stay near the skills they protect; generated run output stays ignored.
+
+## Consequences
+
+Release evidence is summarized in `release-evidence.md`. Generated eval run output remains ignored unless a future release intentionally publishes it.

package/plugins/freeflow/docs/adr/README.md

@@ -0,0 +1,7 @@
+# Freeflow ADRs
+
+Durable decisions for the public Freeflow package:
+
+- [ADR 0001: Three Workflow Modes](0001-three-modes.md)
+- [ADR 0002: Evals Before Enforcement Hooks](0002-evals-before-hooks.md)
+- [ADR 0003: v0.1 Release Boundary](0003-release-boundary.md)