@hassangameryt/freeflow 0.1.0

package/plugins/freeflow/pi-extension/index.js

@@ -0,0 +1,250 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
+
+const WORKFLOW_COMMANDS = [
+  "grill-context",
+  "research-brief",
+  "write-spec",
+  "review-artifact",
+  "write-plan",
+  "execute-plan",
+  "diagnose-failure",
+  "verify-work",
+  "review-work",
+  "commit-work",
+  "capture-decisions",
+  "handoff",
+  "bypass",
+];
+
+const CONTRIBUTOR_COMMANDS = [
+  "setup-freeflow",
+  "write-skill",
+  "evaluate-skill",
+];
+
+const MODE_STATE_ENTRY = "freeflow-mode";
+const RESET_MODE_ARGS = new Set(["reset"]);
+
+let runtimeContextCache = null;
+let currentModeOverride = null;
+
+async function loadRuntimeContext() {
+  const [workflowSkill, workflowMap, interviewGateSkill] = await Promise.all([
+    readFile(new URL("../skills/workflow/SKILL.md", import.meta.url), "utf8"),
+    readFile(new URL("../skills/workflow/references/workflow-map.md", import.meta.url), "utf8"),
+    readFile(new URL("../skills/interview-gate/SKILL.md", import.meta.url), "utf8"),
+  ]);
+
+  return { workflowSkill, workflowMap, interviewGateSkill };
+}
+
+async function refreshRuntimeContext() {
+  runtimeContextCache = await loadRuntimeContext();
+  return runtimeContextCache;
+}
+
+async function getRuntimeContext() {
+  if (runtimeContextCache) {
+    return runtimeContextCache;
+  }
+  return refreshRuntimeContext();
+}
+
+async function readDefaultMode(cwd) {
+  try {
+    const raw = await readFile(join(cwd, ".freeflow/config.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return VALID_MODES.has(parsed.defaultMode) ? parsed.defaultMode : "workflow";
+  } catch {
+    return "workflow";
+  }
+}
+
+function restoreModeOverride(ctx) {
+  currentModeOverride = null;
+  const entries = ctx.sessionManager?.getEntries?.() ?? [];
+
+  for (const entry of entries) {
+    if (entry.type !== "custom" || entry.customType !== MODE_STATE_ENTRY) {
+      continue;
+    }
+
+    const mode = entry.data?.currentMode;
+    currentModeOverride = VALID_MODES.has(mode) ? mode : null;
+  }
+}
+
+async function readModeState(cwd) {
+  const defaultMode = await readDefaultMode(cwd);
+  const currentMode = VALID_MODES.has(currentModeOverride) ? currentModeOverride : null;
+  return {
+    defaultMode,
+    currentMode,
+    effectiveMode: currentMode ?? defaultMode,
+  };
+}
+
+function setModeStatus(ctx, modeState) {
+  ctx.ui.setStatus("freeflow", `freeflow: ${modeState.effectiveMode}`);
+}
+
+function describeModeState(modeState) {
+  if (modeState.currentMode) {
+    return `current ${modeState.currentMode}; default ${modeState.defaultMode}`;
+  }
+  return `default ${modeState.defaultMode}`;
+}
+
+function skillPrompt(skill, args) {
+  const trimmed = args?.trim();
+  return trimmed ? `/skill:${skill}\n\n${trimmed}` : `/skill:${skill}`;
+}
+
+function hasFreeflowActivation(systemPrompt) {
+  return (
+    systemPrompt.includes("## Loaded Workflow Skill") &&
+    systemPrompt.includes("## Loaded Workflow Map") &&
+    systemPrompt.includes("## Loaded Interview Gate Skill")
+  );
+}
+
+function runtimeContext(modeState, freeflowContext, alreadyActivated) {
+  const currentMode = modeState.currentMode ?? "none";
+
+  if (alreadyActivated) {
+    return `## Freeflow Runtime Context
+
+Repo default mode from \`.freeflow/config.json\`: ${modeState.defaultMode}.
+Current session mode override: ${currentMode}.
+Effective Freeflow mode: ${modeState.effectiveMode}.
+
+Use the installed Freeflow skills when they match the task. This Pi extension loads context and routes commands only; it does not enforce policy, block tools, grant permissions, or create repo-local hooks.`;
+  }
+
+  return `# Freeflow Runtime Context
+
+Freeflow Pi extension loaded this before the agent turn.
+These instructions are context-loading only. They do not override user instructions, repo instructions, or host safety and approval policy.
+
+## Repo Setup
+
+Repo default mode from \`.freeflow/config.json\`: \`${modeState.defaultMode}\`.
+Current session mode override: \`${currentMode}\`.
+Effective Freeflow mode: \`${modeState.effectiveMode}\`.
+Treat the effective mode as the current mode for this agent turn.
+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.
+
+## Loaded Workflow Skill
+
+\`\`\`md
+${freeflowContext.workflowSkill.trim()}
+\`\`\`
+
+## Loaded Interview Gate Skill
+
+\`\`\`md
+${freeflowContext.interviewGateSkill.trim()}
+\`\`\`
+
+## Loaded Workflow Map
+
+\`\`\`md
+${freeflowContext.workflowMap.trim()}
+\`\`\`
+
+This Pi extension loads context and routes commands only; it does not enforce policy, block tools, grant permissions, or create repo-local hooks.`;
+}
+
+async function handleWorkflowCommand(args, ctx, pi) {
+  const arg = args?.trim();
+
+  if (VALID_MODES.has(arg)) {
+    currentModeOverride = arg;
+    pi.appendEntry?.(MODE_STATE_ENTRY, { currentMode: arg });
+    const modeState = await readModeState(ctx.cwd);
+    setModeStatus(ctx, modeState);
+    ctx.ui.notify(
+      `Freeflow mode is now ${modeState.effectiveMode} for this session. Repo default remains ${modeState.defaultMode}.`,
+      "info"
+    );
+    return;
+  }
+
+  if (RESET_MODE_ARGS.has(arg)) {
+    currentModeOverride = null;
+    pi.appendEntry?.(MODE_STATE_ENTRY, { currentMode: null });
+    const modeState = await readModeState(ctx.cwd);
+    setModeStatus(ctx, modeState);
+    ctx.ui.notify(`Freeflow mode reset to repo default: ${modeState.defaultMode}.`, "info");
+    return;
+  }
+
+  const modeState = await readModeState(ctx.cwd);
+  setModeStatus(ctx, modeState);
+  ctx.ui.notify(
+    `Freeflow mode is ${modeState.effectiveMode} (${describeModeState(modeState)}). Use /workflow conversation, /workflow workflow, /workflow strict-workflow, or /workflow reset.`,
+    "info"
+  );
+}
+
+export default function freeflow(pi) {
+  pi.on("session_start", async (_event, ctx) => {
+    restoreModeOverride(ctx);
+    const [modeState] = await Promise.all([readModeState(ctx.cwd), refreshRuntimeContext()]);
+    setModeStatus(ctx, modeState);
+  });
+
+  pi.on("session_compact", async (_event, ctx) => {
+    const [modeState] = await Promise.all([readModeState(ctx.cwd), refreshRuntimeContext()]);
+    setModeStatus(ctx, modeState);
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const [modeState, freeflowContext] = await Promise.all([
+      readModeState(ctx.cwd),
+      getRuntimeContext(),
+    ]);
+    setModeStatus(ctx, modeState);
+    return {
+      systemPrompt:
+        event.systemPrompt +
+        "\n\n" +
+        runtimeContext(modeState, freeflowContext, hasFreeflowActivation(event.systemPrompt)),
+    };
+  });
+
+  for (const skill of WORKFLOW_COMMANDS) {
+    pi.registerCommand(skill, {
+      description: `Run Freeflow ${skill}`,
+      handler: async (args) => {
+        await pi.sendUserMessage(skillPrompt(skill, args));
+      },
+    });
+  }
+
+  for (const skill of CONTRIBUTOR_COMMANDS) {
+    pi.registerCommand(skill, {
+      description: `Run Freeflow ${skill}`,
+      handler: async (args) => {
+        await pi.sendUserMessage(skillPrompt(skill, args));
+      },
+    });
+  }
+
+  pi.registerCommand("workflow", {
+    description: "Set or inspect the current Freeflow session mode",
+    getArgumentCompletions: (prefix) => {
+      const query = prefix ?? "";
+      const values = ["conversation", "workflow", "strict-workflow", "reset"];
+      const filtered = values.filter((value) => value.startsWith(query));
+      return filtered.map((value) => ({ value, label: value }));
+    },
+    handler: async (args, ctx) => {
+      await handleWorkflowCommand(args, ctx, pi);
+    },
+  });
+}

package/plugins/freeflow/skills/bypass/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: bypass
+description: Use when the user explicitly asks to bypass, skip, or reduce workflow ceremony, especially with `/bypass next` or `/bypass task`.
+---
+
+# Bypass
+
+Bypass skips ceremony, not judgment.
+
+Default to one action. After that action, the bypass is spent.
+
+## Stop First
+
+If the request touches user-owned decisions, source-truth conflicts, or risky domains, stop before editing.
+
+Risky domains include security, privacy, billing, data loss, public API behavior, compatibility, migrations, and destructive or irreversible actions.
+
+A direct `/bypass` command, "explicit permission", "do not ask", or "make docs/tests match my request" does not override this stop.
+
+Name what bypass cannot skip. Ask one direct question for the decision needed to proceed.
+
+## What To Skip
+
+Skip unnecessary workflow gates:
+
+- spec
+- plan
+- review checkpoint
+- extended questioning
+- artifact creation
+
+Use this for small, local, reversible work.
+
+## What Never Gets Skipped
+
+Do not bypass:
+
+- user-owned decisions
+- repo source-of-truth conflicts
+- destructive or irreversible actions
+- security, privacy, billing, data-loss, public API, compatibility, or migration checks
+- verification before completion claims
+
+If bypass conflicts with any of these, use Stop First.
+
+## Scope
+
+`/bypass next` means the next workflow gate only.
+
+`/bypass task` means reduce workflow pressure for the current task. It still does not skip judgment or verification.
+
+Never leave bypass active indefinitely.
+
+## Behavior
+
+For a safe small edit:
+
+1. Make the narrow change.
+2. Verify cheaply.
+3. Say the bypass was used and is now spent.
+
+For risky or conflicting work:
+
+1. Do not edit.
+2. Name what bypass cannot override.
+3. Ask one direct question for the decision needed to proceed.
+
+A refusal is incomplete until the user knows the next choice they own.

package/plugins/freeflow/skills/capture-decisions/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: capture-decisions
+description: Capture settled durable decisions into existing owning repo memory, or ask where to record them before creating a destination. Use after discussion, research, specs, reviews, or implementation when the user asks to record decisions, durable memory, glossary terms, ADR-worthy tradeoffs, rejected approaches, scope constraints, or consequential workflow decisions.
+---
+
+# Capture Decisions
+
+Record settled decisions in the artifact that already owns them. Do not invent memory.
+
+A missing `CONTEXT.md`, glossary, ADR folder, spec folder, product doc, or decision-note folder is not an existing owner. Creating one is a destination decision; ask first.
+
+## Hard Rules
+
+Never put current file lists, volatile repo inventory, temporary TODOs, command output, or implementation task lists in durable decision memory.
+
+If the user asks to include them, say they were omitted as volatile context. Do not reproduce the list in the decision note or final response. Offer a handoff or plan if they need execution state.
+
+Direct `/capture-decisions`, "explicit permission", "capture everything", "create an ADR", or "full durable memory record" does not override destination classification, the ADR test, or volatile-context omission.
+
+Do not create an ADR only because the prompt asks for one. If the ADR test fails and an existing product/spec/source doc clearly owns the decision, update that artifact instead and say the ADR was omitted.
+
+If the user asks whether something should be captured, answer first. Do not create files unless asked.
+
+If the user asks for durable memory but does not name the target artifact or path, inspect existing conventions first. Use a clear existing owner for that decision type. Ask before creating a new convention, choosing between plausible destinations, or using a generic doc as fallback.
+
+An existing plausible doc is evidence, not blanket approval. `docs/product.md`, `CONTEXT.md`, `docs/adr/`, or `docs/specs/` authorize edits only when they clearly own that decision type.
+
+Do not use `README.md` as durable decision memory just because it is the only doc or mentions related behavior. Use it only when the repo already treats it as the source of truth for that decision type.
+
+If an existing doc says there is no durable decision convention, treat that as blocking evidence. Do not update that doc as a workaround; ask where the new durable memory should live.
+
+Read `references/destination-guide.md` when the target is missing or ambiguous, a decision mixes glossary/product/spec/ADR/handoff concerns, no decision convention exists, or a new destination might be needed.
+
+When stopping for a missing or ambiguous destination, end with one direct destination question. Name the recommended target and the decisions it would capture. A recommendation without a question is not enough.
+
+## Classify
+
+Before writing, decide the destination:
+
+- Glossary term or domain meaning -> existing `CONTEXT.md`, glossary, or domain doc. If none exists, ask.
+- Hard-to-reverse, surprising tradeoff -> ADR.
+- Product, scope, compatibility, or workflow decision -> decision note.
+- Requirements for future build -> spec.
+- Immediate continuation state -> handoff.
+
+If no durable value exists, say so and do not write.
+
+Creating a new decision-note convention is a destination decision. If the repo has no existing decision-note convention, ask before creating `docs/decisions/`.
+
+If no existing artifact clearly owns the decision, ask before writing. If more than one destination could fit, ask before writing. This includes choosing between an existing product/spec doc, a new decision note, a glossary, README, or an ADR.
+
+## ADR Test
+
+Use an ADR only when all are true:
+
+- Hard to reverse.
+- Surprising without context.
+- Chosen from real alternatives.
+
+Otherwise use a lighter decision note or update the relevant existing artifact.
+
+## Write Shape
+
+When creating a durable decision artifact, follow the compact identity guidance in `../write-spec/references/artifact-standards.md` if future agents or teammates will rely on it.
+
+Keep decision notes short:
+
+```text
+# Decision: ...
+
+Date: ...
+
+## Decision
+...
+
+## Rationale
+...
+
+## Consequences
+...
+
+## Not Captured
+...
+```
+
+Link to live evidence. Do not duplicate volatile facts.
+
+## Stop Conditions
+
+Stop and ask before writing when:
+
+- The decision is not actually settled.
+- The destination is ambiguous.
+- Capturing would change product, scope, policy, ADRs, specs, or source truth.
+- The user asks for memory but not its durability or location.

package/plugins/freeflow/skills/capture-decisions/references/destination-guide.md

@@ -0,0 +1,65 @@
+# Destination Guide
+
+Use this when the durable-memory destination is not obvious.
+
+## Destination Test
+
+Before writing, answer:
+
+- What settled decision is being recorded?
+- Which existing artifact is already the source of truth for that kind of decision?
+- Would this edit create a new documentation convention or source of truth?
+- Would a future agent treat the target as authority for this decision?
+
+If the owner is unclear, ask before writing.
+
+## Common Destinations
+
+| Decision type | Prefer | Do not use |
+| --- | --- | --- |
+| Domain term or glossary meaning | Existing `CONTEXT.md`, glossary, or domain doc; otherwise ask | README as a fallback glossary; creating `CONTEXT.md` without asking |
+| Product behavior, scope, compatibility, billing, privacy, or policy | Existing product/spec/policy doc; otherwise ask where to capture | ADR unless the ADR test passes |
+| Hard-to-reverse, surprising tradeoff chosen from alternatives | ADR | Product notes for architecture that needs rationale |
+| Future build requirements | Existing or requested spec | Handoff or decision note as a hidden spec |
+| Immediate continuation state, next steps, file inventory, commands, partial progress | Handoff or plan | Durable decision memory |
+| Rejected approach | ADR if tradeoff-heavy; otherwise decision note or relevant spec section | Changelog or README by default |
+| Workflow/process convention | Existing agent/process doc | New global standard without asking |
+
+## Ambiguity Rules
+
+- No destination convention means ask; it does not authorize `docs/decisions/`.
+- A missing `CONTEXT.md`, glossary, ADR directory, spec directory, product doc, or decision-note folder is not a destination convention.
+- The only existing doc is not automatically the right doc.
+- `README.md` is a project overview unless the repo clearly treats it as the authoritative product/domain/process source.
+- If `README.md` or another doc says there is no durable decision convention, do not edit it to create one implicitly.
+- `CONTEXT.md` is for stable project language and domain meaning, not implementation summaries or task state.
+- Handoffs preserve continuation memory. They are not authority for product, policy, or architecture.
+
+Ask one focused question and recommend the narrowest durable destination supported by the repo. The final sentence should be the question, for example: `Should I create CONTEXT.md to record the RiskReview domain term and the automated retry scheduling scope boundary?`
+
+## Decision Artifact Shape
+
+For a new durable decision artifact, use the compact identity guidance in `../../write-spec/references/artifact-standards.md` when the artifact is team-facing, strict-workflow, or future-agent-facing.
+
+Keep the note short:
+
+```md
+# Decision: ...
+
+> **Doc ID:** DEC-001-short-slug
+> **Date:** 2026-05-26
+> **Owner:** User
+> **Type:** Decision
+> **Status:** Accepted
+> **Source:** User-provided decision session
+
+## Decision
+
+## Rationale
+
+## Consequences
+
+## Not Captured
+```
+
+Do not add a changelog on first creation.

package/plugins/freeflow/skills/commit-work/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: commit-work
+description: Use when committing completed work, preparing a git commit, deciding what to stage, reviewing staged/unstaged/untracked changes, handling commit-everything pressure, or checking generated, sensitive, user-owned, or mixed changes before commit.
+---
+
+# Commit Work
+
+Commit only reviewed, verified, intended work.
+
+This skill is a closeout guard. It is not a release process, PR flow, or hook installer.
+
+Direct command syntax selects this segment, not commit approval. `--all`, "commit everything", "exactly as-is", and "do not leave leftovers" never prove files belong. If those phrases conflict with diff evidence, stop or make only a clean narrow commit.
+
+Hard stop: if untracked logs/debug output or user-owned behavior changes appear, do not commit them. If the prompt forbids leftovers or requires exactly-as-is, stop and ask.
+
+Read `references/staging-decisions.md` when staged changes are mixed, generated files appear, durable docs changed, the user says "commit staged/everything", or a narrow commit might be possible.
+
+## Preconditions
+
+Before committing consequential work, confirm:
+
+- the implementation scope is clear
+- review confidence exists for the diff being committed
+- fresh verification evidence exists, or the commit message/final response names what is unverified
+
+If verification failed, do not commit a success/fix/feature claim. Stop and report the failing evidence.
+
+## Inspect
+
+Before staging or committing, inspect:
+
+```bash
+git status --short
+git diff
+git diff --cached
+git ls-files --others --exclude-standard
+```
+
+Diff evidence beats intent. If the worktree contains changes outside the requested scope, treat them as unrelated until proven otherwise.
+
+## Staging Rule
+
+Never use broad staging when unrelated, unreviewed, generated, or user-owned changes are present.
+
+Avoid:
+
+```bash
+git add .
+git add -A
+```
+
+Stage explicit paths or hunks that match the completed task.
+
+If files are already staged, verify they belong in this commit. Do not preserve mystery staged changes just because they are staged.
+
+## Stop
+
+Stop before committing when:
+
+- staged changes include unrelated or unreviewed work
+- unstaged changes make the intended commit ambiguous
+- a user-owned change may be included accidentally
+- generated files, logs, debug output, or secrets appear without evidence they should be committed
+- pre-commit, lint, test, build, or formatter checks fail
+- the requested commit would mix separable product/code/doc/test concerns in a way that hurts review or rollback
+
+Name the blocker and ask which path to follow. If a clean narrow commit is possible without touching unrelated work, make it and leave unrelated changes untouched.
+
+## Commit Shape
+
+Keep commits small enough to review, debug, and roll back.
+
+Use the repo's existing commit style. If none is obvious, use a short imperative subject:
+
+```text
+Fix settings title typo
+```
+
+Add a body only when it helps future readers understand why.
+
+Reference specs, plans, ADRs, issues, or decisions when they materially explain the commit. Do not invent mandatory `Refs:` lines for repos that do not require them.
+
+## After Commit
+
+Verify what landed:
+
+```bash
+git show --stat --oneline --name-only HEAD
+git status --short
+```
+
+Final response should state:
+
+- commit SHA and subject
+- what was committed
+- what verification supports it
+- any remaining uncommitted or unverified changes

package/plugins/freeflow/skills/commit-work/references/staging-decisions.md

@@ -0,0 +1,51 @@
+# Staging Decisions
+
+Use this for mixed staged sets, generated files, durable docs, or broad commit pressure.
+
+## Evidence First
+
+Read staged, unstaged, and untracked state before deciding:
+
+- `git status --short`
+- `git diff --cached`
+- `git diff`
+- `git ls-files --others --exclude-standard`
+
+Diff evidence beats "staged means ready", "commit everything", and "include all leftovers".
+
+## Mixed Staged Sets
+
+Staged changes can still be wrong.
+
+Stop or make a narrow commit when the staged set mixes separable concerns, such as:
+
+- release note or copy edits plus product behavior
+- source code plus local debug output
+- generated files plus hand edits
+- source-truth docs plus implementation changes that have not been confirmed
+- security, billing, permissions, privacy, migration, or public API behavior with unrelated work
+
+If a sensitive staged change conflicts with docs, tests, policy, or contracts, do not commit it just because it is staged.
+
+## Narrow Commit Rule
+
+Make a narrow commit only when:
+
+- the intended scope is clear
+- the included files are all part of that scope
+- excluded changes can remain staged or dirty without being lost
+- the final response reports remaining staged/dirty/untracked work
+
+If excluding files would require unstaging or rearranging user-owned work, ask first unless the repo clearly supports a safe path.
+
+## Generated Files
+
+Do not commit generated files, logs, snapshots, lockfiles, build outputs, or formatter churn unless the task or repo convention makes them part of the intended change.
+
+If generated output is required, name the generator or verification that produced it.
+
+## Durable Docs
+
+Durable specs, ADRs, policies, handoffs, and runbooks are source truth. Commit them with code only when they describe the same confirmed change.
+
+If a durable doc changes policy, status, ownership, public API behavior, billing, privacy, security, data loss, migration, or compatibility, treat that as a user-owned decision unless already confirmed.