@hassangameryt/freeflow 0.1.0

package/plugins/freeflow/docs/architecture.md

@@ -0,0 +1,86 @@
+# Architecture
+
+Freeflow is a portable skill pack for coding agents.
+
+## Runtime Boundary
+
+Freeflow ships Markdown skills, bundled references, lightweight context-loading hooks, and a Pi extension. It does not ship a CLI, Codex/Claude native slash handlers, enforcement hooks, or a new agent runtime in v0.1.
+
+Host runtimes still control tools, sandboxing, approvals, and permissions. Freeflow controls workflow pressure:
+
+- how much clarification is needed
+- when artifacts are useful
+- when source-truth conflicts stop edits
+- when review and verification are required
+- when a handoff or durable decision is useful
+
+## Package Layout
+
+```text
+freeflow/
+  package.json
+  .agents/plugins/marketplace.json
+  .claude-plugin/marketplace.json
+  README.md
+  LICENSE
+  CHANGELOG.md
+  docs/
+  plugins/freeflow/
+    .codex-plugin/plugin.json
+    .claude-plugin/plugin.json
+    command-surface.json
+    hooks/
+    pi-extension/
+    skills/
+    docs/
+    evals/
+```
+
+The repository root is the marketplace and package-facing shell. Codex uses `.agents/plugins/marketplace.json`; Claude uses `.claude-plugin/marketplace.json`. Both point at `plugins/freeflow/`. Pi uses the root `package.json` `pi` manifest to load `plugins/freeflow/skills/` and `plugins/freeflow/pi-extension/index.js`.
+
+`plugins/freeflow/` is the single runtime source of truth. Skill edits, bundled references, eval metadata, and command-surface metadata live there to avoid generated package drift.
+
+## Progressive Disclosure
+
+Each skill keeps its active `SKILL.md` short. Stable details move into `references/` files only when they prevent bloat, reduce repeated work, or address measured failures.
+
+This keeps the model's first-loaded instructions focused on behavior:
+
+- trigger
+- loop
+- stop condition
+- failure prevention
+
+## Host Setup
+
+`setup-freeflow` installs a compact always-on contract into the host repo.
+
+The canonical setup contract lives in `skills/setup-freeflow/references/activation-contract.md`; setup docs, fixtures, and eval assertions should reference it or be checked against it.
+
+Codex setup targets `AGENTS.md` and `.freeflow/config.json`.
+
+Claude setup targets `CLAUDE.md`, `.claude/rules/freeflow-core.md`, and `.freeflow/config.json` when Claude is the selected host.
+
+Setup should not silently update both hosts or overwrite stronger repo-specific rules. Existing repo instructions are source truth.
+
+## Runtime Context Hooks
+
+The installed plugin owns `hooks/hooks.json`. Setup does not copy hook files into target repos.
+
+The hooks load the existing `workflow` skill, workflow map, and `interview-gate` skill:
+
+- at session start, including startup, resume, clear, and compact
+
+They also report whether the current repo appears set up, partially set up, or missing setup. They do not run after edit/write tools, block tools, grant permissions, enforce mode policy, or replace repo instructions.
+
+Setup handles the same-session case directly: after successful setup verification, it reads the workflow skill, workflow map, and interview-gate skill before its final response and only then says workflow and interview-gate context is loaded.
+
+Host runtimes may require plugin hooks to be reviewed and trusted after install. If the host skips untrusted hooks, setup still writes activation/config files, but future session-start runtime context will not load until hooks are trusted and the session is restarted, resumed, cleared, or compacted.
+
+Pi uses an extension instead of `hooks/hooks.json`. The Pi extension registers direct commands, reads `workflow/SKILL.md`, `workflow/references/workflow-map.md`, and `interview-gate/SKILL.md`, refreshes that context on `session_start` and `session_compact`, and injects it during Pi's `before_agent_start` lifecycle event. Pi `/workflow` commands set a session-scoped current-mode override, while `.freeflow/config.json` remains the default-mode source. It follows the same boundary as the Codex/Claude hooks: context loading only, no enforcement.
+
+## Deferred Enforcement
+
+Enforcement hooks and CLI checks are intentionally deferred. They are useful only after skill wording and evals prove a repeated behavior needs mechanical enforcement.
+
+For v0.1, commands are model-routed language such as `/write-spec` or `/verify-work`; they are not native registered slash handlers.

package/plugins/freeflow/docs/release-evidence.md

@@ -0,0 +1,49 @@
+# Release Evidence
+
+Freeflow v0.1 is based on local fixture evals and release acceptance runs from the development repository.
+
+## Acceptance Summary
+
+The local v0.1 acceptance suite passed after measured fixes and was rerun during prepublish verification on 2026-05-26.
+
+High-signal behaviors covered:
+
+- Source-truth conflicts stop before edits.
+- Strict public API specs ask for owner decisions.
+- Execution stops when verification reveals a bad plan.
+- Commit flow refuses mixed staged sensitive changes.
+- Decision capture asks before inventing memory conventions.
+- Bypass skips ceremony, not judgment.
+
+## Command Surface
+
+The development registry covers:
+
+- 4 mode commands.
+- 13 direct workflow skill calls.
+- 2 contributor skill calls.
+
+Codex/Claude native slash handlers are not shipped in v0.1. In those hosts, commands are model-routed through natural language and skill activation. Pi registers direct Freeflow commands through its extension.
+
+## Runtime Context
+
+Freeflow ships plugin-bundled context hooks that load the existing `workflow` skill, workflow map, and `interview-gate` skill at session start. These hooks do not run after edit/write tools, enforce behavior, block tools, or create repo-local hook files.
+
+For the same session that runs setup, `setup-freeflow` reads the workflow skill, workflow map, and interview-gate skill after successful setup verification before saying workflow and interview-gate context is loaded.
+
+Host trust prompts for plugin hooks are expected host behavior. Local metadata validation checks hook packaging and deterministic output, not end-to-end host trust UI.
+
+## Release Metadata
+
+Run `plugins/freeflow/evals/scripts/validate-release-metadata.sh` for local prepublish checks across marketplace metadata, host manifests, command-surface routing, release-boundary docs, package cleanliness, and deferred install-smoke status.
+
+Run `plugins/freeflow/evals/scripts/check-runtime-context-hook.sh` after changing lifecycle context hooks.
+
+## Known Deferred Work
+
+- Live Claude smoke evals after Hassan confirms Claude testing is available again.
+- GitHub-install smoke tests in separate Codex, Claude, and fresh Pi environments.
+- Enforcement hooks or CLI checks only after repeated behavior failures justify them.
+- Public marketplace submission only after GitHub install works for required hosts.
+
+Full eval reports are development evidence and are not included in the runtime package.

package/plugins/freeflow/docs/skills.md

@@ -0,0 +1,44 @@
+# Skills
+
+Freeflow ships a small workflow skill pack. Natural language is the preferred interface. In Codex/Claude, slash-style phrases work as model-routed skill hints in v0.1; in Pi, the extension registers direct Freeflow commands.
+
+## Core
+
+| Skill | Use When |
+| --- | --- |
+| `workflow` | Choosing the next workflow entry point or explaining the full flow. |
+| `mode-contract` | Inferring or switching `conversation`, `workflow`, or `strict-workflow`. |
+| `interview-gate` | Ambiguity or a user-owned decision would change the next action. |
+| `bypass` | Skipping unnecessary ceremony without skipping judgment. |
+
+## Discovery And Artifacts
+
+| Skill | Use When |
+| --- | --- |
+| `research-brief` | Repo, domain, evidence, or current facts are unknown. |
+| `grill-context` | Direction is vague and a decision tree needs clarification. |
+| `write-spec` | Agreed requirements or decisions need a durable spec. |
+| `review-artifact` | A spec, plan, handoff, research brief, or decision note must guide future work. |
+| `write-plan` | An approved spec or explicit task context needs executable slices. |
+
+## Execution And Closeout
+
+| Skill | Use When |
+| --- | --- |
+| `execute-plan` | An approved plan exists and should be implemented in checked slices. |
+| `diagnose-failure` | Behavior is broken, failing, flaky, slow, or unclear. |
+| `review-work` | A completed diff or review feedback needs bug/risk-focused review. |
+| `verify-work` | Fresh evidence is needed before claiming completion. |
+| `commit-work` | Reviewed, verified, intended work is ready to commit. |
+| `handoff` | Pausing, compacting, transferring context, or preserving continuation memory. |
+| `capture-decisions` | Stable decisions, glossary terms, rejected approaches, or ADR-worthy tradeoffs should be recorded. |
+
+## Contributor Skills
+
+| Skill | Use When |
+| --- | --- |
+| `setup-freeflow` | Installing the compact always-on Freeflow contract into a repo. |
+| `write-skill` | Creating or revising concise behavior-shaping skills. |
+| `evaluate-skill` | Turning failures into baseline-vs-with-skill evals and revising from evidence. |
+
+These contributor skills are shipped because teams may use Freeflow to install or adapt workflow behavior, but they are not normal workflow states for ordinary feature work.

package/plugins/freeflow/docs/workflow.md

@@ -0,0 +1,57 @@
+# 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.

package/plugins/freeflow/hooks/freeflow-runtime-context.mjs

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const PLUGIN_ROOT = path.resolve(SCRIPT_DIR, "..");
+const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
+
+function readStdinJson() {
+  const raw = fs.readFileSync(0, "utf8").trim();
+  if (!raw) {
+    return { input: {}, raw: "" };
+  }
+
+  try {
+    return { input: JSON.parse(raw), raw };
+  } catch {
+    return { input: {}, raw };
+  }
+}
+
+function readText(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+function findWorkspaceRoot(cwd) {
+  let current = path.resolve(cwd || process.cwd());
+
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) {
+      return current;
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return path.resolve(cwd || process.cwd());
+    }
+    current = parent;
+  }
+}
+
+function loadRuntimeContext() {
+  const workflowSkill = readText(path.join(PLUGIN_ROOT, "skills", "workflow", "SKILL.md"));
+  const workflowMap = readText(
+    path.join(PLUGIN_ROOT, "skills", "workflow", "references", "workflow-map.md")
+  );
+  const interviewGateSkill = readText(
+    path.join(PLUGIN_ROOT, "skills", "interview-gate", "SKILL.md")
+  );
+
+  if (!workflowSkill || !workflowMap || !interviewGateSkill) {
+    throw new Error("Freeflow runtime context files are missing.");
+  }
+
+  return { workflowSkill, workflowMap, interviewGateSkill };
+}
+
+function readConfig(root) {
+  const configPath = path.join(root, ".freeflow", "config.json");
+  const body = readText(configPath);
+  if (!body) {
+    return { exists: false, valid: false, defaultMode: null };
+  }
+
+  try {
+    const parsed = JSON.parse(body);
+    const keys = Object.keys(parsed);
+    const valid =
+      keys.length === 1 &&
+      Object.prototype.hasOwnProperty.call(parsed, "defaultMode") &&
+      VALID_MODES.has(parsed.defaultMode);
+    return { exists: true, valid, defaultMode: parsed.defaultMode ?? null };
+  } catch {
+    return { exists: true, valid: false, defaultMode: null };
+  }
+}
+
+function inspectSetup(root) {
+  const config = readConfig(root);
+  const agents = readText(path.join(root, "AGENTS.md")) || "";
+  const claude = readText(path.join(root, "CLAUDE.md")) || "";
+  const claudeRule = readText(path.join(root, ".claude", "rules", "freeflow-core.md")) || "";
+
+  const codexActive =
+    agents.includes("## Freeflow") && agents.includes("Use Freeflow for consequential work");
+  const claudeActive =
+    claude.includes("@.claude/rules/freeflow-core.md") &&
+    claudeRule.includes("Use Freeflow for consequential work");
+  const activeHosts = [
+    codexActive ? "Codex AGENTS.md" : null,
+    claudeActive ? "Claude CLAUDE.md import" : null
+  ].filter(Boolean);
+
+  return { config, activeHosts };
+}
+
+function configStatus(config) {
+  if (config.valid) {
+    return `defaultMode \`${config.defaultMode}\``;
+  }
+  if (config.exists) {
+    return "invalid `.freeflow/config.json`; effective default mode falls back to `workflow`";
+  }
+  return "missing `.freeflow/config.json`; effective default mode falls back to `workflow`";
+}
+
+function modeGuidance(mode) {
+  return [
+    `Current Freeflow default mode: \`${mode}\`.`,
+    "Treat this as the repo default at session start, resume, clear, and compact.",
+    "For mode changes or mode interpretation, use `mode-contract`.",
+    "Do not announce the current mode on every reply. Mention it when the user asks, setup/config is discussed, or the mode changes the next action."
+  ];
+}
+
+function buildSetupStatus(root) {
+  const setup = inspectSetup(root);
+  const parts = [];
+  const modeStatus = configStatus(setup.config);
+
+  if (setup.config.valid && setup.activeHosts.length > 0) {
+    parts.push(
+      `Setup status: configured for ${setup.activeHosts.join(" and ")} with ${modeStatus}.`
+    );
+    parts.push(...modeGuidance(setup.config.defaultMode));
+  } else if (setup.config.exists || setup.activeHosts.length > 0) {
+    const issues = [];
+    if (!setup.config.valid) {
+      issues.push("valid `.freeflow/config.json` is missing");
+    }
+    if (setup.activeHosts.length === 0) {
+      issues.push("no Freeflow activation block/import was found");
+    }
+    parts.push(`Setup status: partial setup; ${issues.join(" and ")}.`);
+    parts.push(`Repo default mode: ${modeStatus}.`);
+    parts.push(
+      "Required user-facing notice: in the next assistant reply, tell the user Freeflow setup is incomplete and recommend `/setup-freeflow` or completing the missing host/config setup. Do this even if the user's prompt is casual, such as a greeting."
+    );
+    parts.push(
+      "Before consequential work in this repo, complete setup or ask which host setup to complete unless the user explicitly bypasses setup."
+    );
+  } else {
+    parts.push("Setup status: this repo does not appear to be set up for Freeflow yet.");
+    parts.push(`Repo default mode: ${modeStatus}.`);
+    parts.push(
+      "Required user-facing notice: in the next assistant reply, tell the user Freeflow is installed but this repo is not set up yet, and recommend `/setup-freeflow`. Do this even if the user's prompt is casual, such as a greeting."
+    );
+    parts.push(
+      "Before consequential work in this repo, use `/setup-freeflow` or ask whether to set up Freeflow for Codex, Claude, or both. Do not start implementation solely because the plugin is installed."
+    );
+  }
+
+  return parts.join("\n");
+}
+
+function shouldInject(eventName) {
+  if (process.env.FREEFLOW_DISABLE_RUNTIME_CONTEXT === "1") {
+    return false;
+  }
+
+  return eventName === "SessionStart";
+}
+
+function buildContext(input) {
+  const root = findWorkspaceRoot(input.cwd || process.cwd());
+  const { workflowSkill, workflowMap, interviewGateSkill } = loadRuntimeContext();
+
+  return [
+    "# Freeflow Runtime Context",
+    "",
+    "Freeflow plugin lifecycle hook loaded this at session start.",
+    "These instructions are context-loading only. They do not override user instructions, repo instructions, or host safety and approval policy.",
+    "",
+    "## Repo Setup",
+    buildSetupStatus(root),
+    "",
+    "## Loaded Workflow Skill",
+    "```md",
+    workflowSkill.trim(),
+    "```",
+    "",
+    "## Loaded Interview Gate Skill",
+    "```md",
+    interviewGateSkill.trim(),
+    "```",
+    "",
+    "## Loaded Workflow Map",
+    "```md",
+    workflowMap.trim(),
+    "```"
+  ].join("\n");
+}
+
+function isCodexHookInput(input) {
+  return typeof input.model === "string" && input.model.length > 0;
+}
+
+function emitAdditionalContext(eventName, input, additionalContext) {
+  if (isCodexHookInput(input)) {
+    process.stdout.write(`${additionalContext}\n`);
+    return;
+  }
+
+  process.stdout.write(
+    `${JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: eventName,
+        additionalContext
+      }
+    })}\n`
+  );
+}
+
+function main() {
+  const { input, raw } = readStdinJson();
+  const eventName = process.argv[2] || input.hook_event_name || "";
+
+  if (!raw && !eventName) {
+    return;
+  }
+
+  if (!shouldInject(eventName)) {
+    return;
+  }
+
+  emitAdditionalContext(eventName, input, buildContext(input));
+}
+
+try {
+  main();
+} catch (error) {
+  process.stderr.write(`Freeflow runtime context hook skipped: ${error.message}\n`);
+}

package/plugins/freeflow/hooks/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Load Freeflow runtime context at session start.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT}}/hooks/freeflow-runtime-context.mjs\" SessionStart",
+            "timeout": 5,
+            "statusMessage": "Loading Freeflow context"
+          }
+        ]
+      }
+    ]
+  }
+}