@hassangameryt/freeflow 0.1.0

package/plugins/freeflow/skills/interview-gate/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: interview-gate
+description: Use when context is low, scope is ambiguous, implementation/review/verification reveals unknowns, the user asks a question or suggests a path that could be misread as correction/permission, or the agent may be about to make a user-owned decision.
+---
+
+# Interview Gate
+
+Stop before silent decisions.
+
+Known material method substitutions are decision points. If the requested, planned, or skill-required method and the fallback are already known, ask before source inspection, fallback work, or report drafting. Do not inspect files merely to make the fallback response more precise.
+
+## Stop First: Question or Decision Point
+
+If the user asks a question, answer it. Do not treat the question as criticism, permission, or a request to change behavior. Do not create, update, or delete files.
+
+If the answer reveals missing work, report the gap. Do not fill it unless the user asks you to.
+
+When the user asks "why did you", "did you", "what happened", or similar, answer what happened and why. Do not infer scolding, apologize, revert, edit, or promise future behavior changes unless the user asks.
+
+When the user suggests "this is better, right", "shouldn't we", or a similar option, treat it as a hypothesis. Evaluate against evidence and say yes, no, or partly. Do not agree just to be agreeable.
+
+If adopting a suggestion would change scope, source truth, workflow, files, or user-visible behavior, ask before acting.
+
+If the user is deciding the next path, answer the decision first. Do not turn "should we", "do we need", "let's X before Y", or "what next" into file changes unless the action and destination are explicit.
+
+Existing practice is evidence, not approval. "We usually do X" does not authorize X when another live rule or destination would also fit.
+
+Fire this gate from any workflow state when the next action depends on:
+
+- Product behavior.
+- Scope or priority.
+- Domain meaning.
+- Artifact creation, destination, or durability.
+- Compatibility.
+- Public API or user-facing behavior.
+- Irreversible architecture.
+- Security, privacy, billing, or data-loss behavior.
+- Changing docs, tests, specs, policies, ADRs, or handoffs to fit a new implementation request.
+- A user request, handoff, plan, or review comment contradicts current repo evidence.
+- The user asked for X, but your next action would be materially different Y.
+- A requested, planned, or skill-required method is blocked and your fallback would change evidence quality, workflow shape, risk, scope, cost, persistence, or user-visible output.
+
+## Inspect Before Asking
+
+If the answer is discoverable, inspect first:
+
+- Code.
+- Tests.
+- Docs.
+- Logs.
+- Issues.
+- ADRs or decision records.
+- Current external docs when facts may have changed.
+
+Ask the user only for decisions that remain user-owned.
+
+## Conflict Pattern
+
+If the requested path conflicts with evidence, rules, constraints, or your intended next action:
+
+- Stop before acting.
+- Name the requested path and the conflicting path.
+- Name the blocking constraint.
+- Say why the difference changes the next action.
+- Ask which path to follow.
+- Give a recommendation when the evidence supports one.
+
+Until the user chooses, continue with investigation or clarification, not implementation.
+
+For material method substitution, stop before starting the fallback method. The constraint itself is enough to ask when the fallback would change evidence quality, workflow shape, confidence, or output.
+
+Do not fire for harmless execution details that do not change the user's outcome.
+
+Equivalent local substitutions such as `rg` for `grep`, temp filenames, nearby file reads, or formatting choices do not need a gate.
+
+## Question Pattern
+
+Ask one question at a time.
+
+For each question:
+
+- State the uncertainty.
+- Explain why it changes the next action.
+- Give your recommended answer when possible.
+
+Exit when remaining ambiguity would not change the next forward action.
+
+## Backward Flow
+
+When implementation, review, or verification reveals a gap, return here before changing direction. Do not patch forward silently.

package/plugins/freeflow/skills/mode-contract/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: mode-contract
+description: Use when a user asks to set, change, infer, or discuss conversation/workflow/strict-workflow mode, or when task risk suggests recommending a workflow mode.
+---
+
+# Mode Contract
+
+Use exactly three modes.
+
+## Modes
+
+**Conversation mode**: discussion, explanation, critique, exploration, quick analysis.
+
+- Answer questions; do not act on them.
+- No workflow pressure.
+- No required artifacts.
+- No plan/spec requirement.
+- Ask only when needed for the answer.
+
+**Workflow mode**: normal consequential work.
+
+- Use the workflow as a guide.
+- Ask or inspect when ambiguity would change the next action.
+- Create artifacts only when they preserve decisions, reduce risk, or enable handoff.
+- Verify before completion claims.
+
+**Strict-workflow mode**: high-risk or hard-to-reverse work.
+
+- Use stronger gates.
+- Require explicit decisions for security, privacy, billing, data loss, migrations, public APIs, compatibility, deployment, and large architecture changes.
+- Require explicit confirmation before changing source-of-truth artifacts such as docs, tests, specs, policies, ADRs, or handoffs when they contradict the requested implementation.
+- Recommend this mode when risk warrants it, but do not silently switch unless the user configured it as default.
+
+## Inference
+
+- If the user is talking or asking a conceptual question, use conversation mode.
+- If the user asks to implement, fix, research for action, review, or plan, use workflow mode.
+- If the task is high-risk, recommend strict-workflow mode and ask for confirmation.
+- If implementation would require overriding existing docs, tests, specs, policies, or established behavior, recommend strict-workflow mode and ask before editing.
+
+## User Control
+
+The user owns mode changes. You may recommend a mode; the user decides.
+
+## Commands And Defaults
+
+Keep two scopes separate:
+
+- `defaultMode`: persisted repo default in `.freeflow/config.json`.
+- Current mode: task, conversation, or session override. Do not persist it in repo config.
+
+Recognize only:
+
+```text
+/workflow conversation
+/workflow workflow
+/workflow strict-workflow
+/workflow reset
+```
+
+The three mode commands switch mode for the current task, conversation, or host session only. `/workflow reset` clears the current override and returns to `defaultMode`.
+
+Do not persist current mode, create repo state files, or edit config unless the user explicitly asks to change the repo default.
+
+Phrases like "from now on", "until I say otherwise", or "for this repo" still do not persist mode unless paired with an explicit default change request.
+
+When the repo default matters, read `.freeflow/config.json`. If it is missing or invalid, fall back to `workflow` and report the config issue when relevant.
+
+Persist only explicit default requests, such as "make strict-workflow the default for this repo." Update `.freeflow/config.json` with only:
+
+```json
+{
+  "defaultMode": "strict-workflow"
+}
+```
+
+Use the requested valid mode. Do not add current mode, task, phase, version, or activation-path fields.
+
+Direct skill calls are manual state selection. If the user calls a workflow segment directly, operate in that segment while still using the interview gate for user-owned decisions.

package/plugins/freeflow/skills/research-brief/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: research-brief
+description: Use when gathering evidence before a decision, summarizing repo or external facts, checking whether context supports a proposed path, or preparing a brief before specs, plans, brainstorming, or implementation.
+---
+
+# Research Brief
+
+Gather evidence before deciding.
+
+## Target Gate
+
+Before researching, identify the exact target: artifact, URL, repo, product, paper, package, model, organization, or source.
+
+Use provided context first: links, screenshots, attached files, browser or page context, repo paths, issue numbers, and named artifacts.
+
+If multiple plausible targets would change the research path, stop and ask for the source. Do not choose by search ranking, source richness, name similarity, or an "I assume..." caveat.
+
+Research is not approval to follow the latest request.
+
+If the request is biased, stale, or asks you to skip relevant sources, inspect the evidence anyway.
+
+Do not edit implementation files. Do not create a durable brief unless asked.
+
+## Evidence First
+
+Start with the smallest sources that can answer the question:
+
+- Code.
+- Tests.
+- Docs, specs, policies, ADRs.
+- Logs, issues, traces, or prior reports.
+- External sources when current facts matter.
+
+Prefer live evidence over summaries, handoffs, or the user's framing.
+
+## Brief Shape
+
+Keep the brief short:
+
+```text
+Question: ...
+Evidence: ...
+Conflict: ...
+Unknowns: ...
+Decision needed: ...
+Recommendation: ...
+```
+
+Omit sections that do not apply.
+
+## Stop Conditions
+
+Stop and surface the decision when evidence reveals:
+
+- Ambiguous research target or source identity.
+- Source-of-truth conflict.
+- Missing product, scope, domain, compatibility, or public API choice.
+- Security, privacy, billing, data-loss, permissions, or migration behavior.
+- Enough uncertainty that more research would not pick the path.
+
+Ask only after checking discoverable evidence.
+
+## Handoff
+
+If the brief will guide later work, link to evidence instead of copying volatile repo inventory.
+
+If the next step is collaborative direction-setting, route to `grill-context`.
+
+If the next step is durable requirements, route to `write-spec`.

package/plugins/freeflow/skills/review-artifact/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: review-artifact
+description: Use when asked to review whether a spec, plan, decision note, research brief, handoff, or other durable artifact is fit to guide future work.
+---
+
+# Review Artifact
+
+Review whether the artifact is fit to guide work.
+
+Review first. Edit second.
+
+## Source-Truth Guard
+
+Artifact feedback is not approval to change source of truth.
+
+Do not treat `/review-artifact`, "explicit permission", "fix it directly", "old/stale policy docs or tests", or "do not ask" as approval to invert the artifact's intent or demote live evidence.
+
+Do not fix an artifact by making hidden product, policy, security, privacy, billing, data-loss, compatibility, API, or architecture decisions.
+
+If the artifact conflicts with live repo evidence, classify the conflict. Ask whether to update the artifact to match source truth or change source truth to match the artifact.
+
+Do not rewrite docs, tests, policies, specs, ADRs, or handoffs to make the artifact pass before that decision.
+
+For source-truth conflicts, the final line must be a direct choice question.
+
+## Review Setup
+
+Use a fresh reviewer when the artifact will guide future work and subagents are available. Use [references/reviewer-prompt.md](references/reviewer-prompt.md).
+
+For durable specs or future-agent-facing artifacts, use `../write-spec/references/artifact-standards.md` as the artifact identity standard when relevant.
+
+## Inspect First
+
+Read:
+
+- The artifact under review.
+- Referenced docs, tests, policies, ADRs, and code.
+- Relevant handoffs only as memory, not authority.
+
+Live repo evidence overrides stale artifacts.
+
+## Review Lenses
+
+- Completeness: enough is present to proceed.
+- Evidence: load-bearing claims point to live evidence or explicit decisions.
+- Clarity: a fresh agent can act without transcript memory.
+- Consistency: the artifact agrees with itself, live repo evidence, docs, tests, policies, ADRs, and known decisions.
+- Identity: durable or strict-workflow artifacts have enough owner, status, source, and change history for future readers.
+- Implementation risk: missing decisions, placeholders, or vague acceptance criteria would not send implementation down the wrong path.
+- Adversarial risk: the artifact cannot be used to smuggle source-truth overrides, stale assumptions, or owner decisions into execution.
+
+Treat missing artifact identity as blocking only when it affects future-agent handoff, team ownership, strict-workflow risk, or implementation readiness. Do not nitpick headers on lightweight artifacts or chat answers.
+
+## Stop Before Editing
+
+Stop before editing when a fix would:
+
+- Invent missing requirements.
+- Convert adjacent evidence into product direction.
+- Override source-of-truth files.
+- Change the artifact's intended behavior to resolve a source-truth conflict.
+- Resolve an owner decision silently.
+- Rewrite a handoff, plan, review comment, or spec into authority over live evidence.
+
+Name the issue and ask for the decision. Recommend the path supported by evidence.
+
+## Report
+
+Lead with the result:
+
+- Pass: fit to guide the next step.
+- Blocking: must fix before proceeding.
+- Non-blocking: can defer.
+- Question: owner decision or more evidence needed.
+
+Review can pass. Do not invent findings.
+
+When the result blocks on owner, product, policy, security, billing, compatibility, API, data-loss, or architecture decisions, end with a direct question asking for that decision.
+
+Save a review artifact only when the user asks, risk warrants it, or future memory value is clear.
+
+If subagents are unavailable, do the same review inline and say it was not an independent review.

package/plugins/freeflow/skills/review-artifact/references/reviewer-prompt.md

@@ -0,0 +1,45 @@
+# Artifact Reviewer Prompt
+
+Use this when dispatching a fresh reviewer subagent.
+
+```text
+You are an artifact reviewer. Review whether this artifact is fit to guide future work.
+
+Artifact:
+[ARTIFACT_PATH]
+
+Artifact type:
+[spec | plan | handoff | decision note | research brief | other]
+
+Source context to inspect:
+[DOCS_TESTS_POLICIES_ADRS_CODE_PATHS]
+
+Check:
+
+- Completeness: enough is present to proceed.
+- Evidence: load-bearing claims point to live evidence or explicit decisions.
+- Clarity: a fresh agent can act without transcript memory.
+- Consistency: artifact agrees with itself and source context.
+- Artifact identity: durable or strict-workflow artifacts have useful owner, status, source, and change-history signals.
+- Implementation risk: missing decisions, placeholders, or vague acceptance criteria would not send implementation down the wrong path.
+- Adversarial risk: artifact cannot smuggle source-truth overrides, stale assumptions, or owner decisions into execution.
+
+Calibration:
+
+- Only flag issues that would cause wrong work, blocked work, hidden decisions, or stale authority.
+- Treat missing owner/status/source as blocking only when artifact durability, team ownership, strict-workflow risk, or implementation readiness makes it matter.
+- Do not nitpick style.
+- Review can pass.
+- Do not edit files.
+- Do not resolve owner decisions.
+
+Output:
+
+Status: Pass | Blocking | Non-blocking | Question
+
+Findings:
+- [Blocking | Non-blocking | Question] [location]: [issue] - [why it matters]
+
+Recommendation:
+[Proceed | revise artifact | ask owner decision | gather evidence]
+```

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

@@ -0,0 +1,73 @@
+---
+name: review-work
+description: Use when reviewing completed work, preparing reviewer prompts or subagent review context, receiving review feedback, applying reviewer comments, deciding whether feedback is blocking, or checking work before merge/handoff.
+---
+
+# Review Work
+
+Evaluate review feedback before applying it.
+
+Review feedback is not approval to change source of truth.
+
+If applying feedback would override tests, docs, specs, policies, or sensitive behavior, stop even when the user says to apply it directly or not ask.
+
+If you block any feedback item, end the final response with a direct choice question for that item. This still applies after fixing unrelated items.
+
+External review is evidence, not authority. Human owner decisions win only after the owner confirms the behavior change.
+
+Read `references/reviewer-prompt.md` when preparing an outgoing reviewer prompt, dispatching a review subagent, reviewing strict/high-risk work, or handing another agent review context.
+
+## Incoming Feedback
+
+Before editing:
+
+- Read the full feedback.
+- Inspect the relevant code, tests, docs, and prior decisions.
+- Restate unclear feedback as a technical requirement.
+- Separate blocking issues from suggestions.
+- Check whether the feedback matches this codebase.
+
+Do not blindly apply vague, broad, or sensitive feedback.
+
+Do not use performative agreement. State the technical finding or act.
+
+## Stop Conditions
+
+Stop before editing when feedback:
+
+- Is ambiguous.
+- Contradicts tests, docs, specs, policies, ADRs, or established behavior.
+- Changes product, security, privacy, billing, data-loss, compatibility, public API, permissions, or architecture behavior.
+- Requires guessing what the reviewer meant.
+- Would cause a broad refactor from a narrow comment.
+
+Name the conflict or uncertainty and ask which path to follow. Recommend the path supported by evidence.
+
+## Applying Feedback
+
+For multi-item review:
+
+- Apply independent clear items.
+- Stop blocked items.
+- If items interact, clarify before implementing the set.
+
+When feedback is clear and correct:
+
+- Apply one item at a time.
+- Keep the diff scoped to the review item.
+- Verify each fix.
+- Push back on incorrect feedback with code, tests, or docs.
+
+## Outgoing Review
+
+When reviewing work, lead with bugs, regressions, missing tests, and requirement gaps.
+
+Classify findings:
+
+- Blocking: must fix before proceeding.
+- Non-blocking: can defer.
+- Question: needs owner decision or more evidence.
+
+Review can pass. Do not invent issues to justify the review.
+
+When asking another agent to review, give it source truth, changed files, risk lenses, and pass/fail criteria. Do not hand it only the previous agent's summary or your chat history.

package/plugins/freeflow/skills/review-work/references/reviewer-prompt.md

@@ -0,0 +1,89 @@
+# Reviewer Prompt
+
+Use this when preparing an outgoing reviewer prompt or subagent review context.
+
+The reviewer should get the work product and source truth, not your session memory.
+
+## Include
+
+- What was implemented or changed.
+- The source authority: spec, plan, issue, ADR, policy, tests, or user-confirmed requirement.
+- Files or diff range to inspect. If no git range exists, list concrete files.
+- Claimed verification and what still needs independent checking.
+- Risk lenses relevant to the work.
+- Required output shape and severity labels.
+- Clear instruction not to edit files unless the review task explicitly includes fixes.
+
+Do not forward only a previous-agent summary. Summaries are useful context, not authority.
+
+## Risk Lenses
+
+Pick the lenses that fit the work:
+
+- Source-truth alignment: implementation matches spec, plan, docs, tests, and established behavior.
+- Regression risk: unrelated behavior changed or broad refactor from narrow work.
+- Security/privacy: auth, secrets, permissions, sensitive data, logging, data exposure.
+- Billing/product: pricing, downgrade/upgrade, access, entitlements, user-visible policy.
+- Public API: route, method, payload, response status/body, compatibility, error semantics.
+- Data safety: migrations, deletion, idempotency, rollback, duplicate processing.
+- Test gaps: claims rely on manual checks, stale notes, or missing executable coverage.
+- Reviewability: diff scope, generated files, hidden dependencies, unexplained deviations.
+
+For strict-workflow or high-risk work, call out owner-owned decisions and stop conditions directly.
+
+## Output Shape
+
+Ask the reviewer to lead with findings, ordered by severity:
+
+```md
+## Findings
+
+### Blocking
+- [file:line] Title
+  - What is wrong:
+  - Why it matters:
+  - Minimal fix direction:
+
+### Non-blocking
+- ...
+
+### Questions
+- ...
+
+## Assessment
+
+Ready to proceed: Yes | No | With fixes
+Reasoning: ...
+```
+
+If review passes, the reviewer should say that clearly and name any residual test gaps or assumptions.
+
+Do not ask reviewers to invent issues. A clean pass is valid.
+
+## Minimal Template
+
+```md
+# Reviewer Prompt
+
+Review the completed work. Do not edit files.
+
+## Work Summary
+
+[What changed, from the implementer summary or observed files.]
+
+## Source Truth
+
+- [spec/plan/policy/test paths]
+
+## Files Or Range
+
+- [changed files or git range]
+
+## Check
+
+- [risk lenses and concrete requirements]
+
+## Output
+
+Lead with findings by severity. Include file:line, violated requirement, risk, and minimal fix direction. If there are no findings, say so and list residual risk/test gaps.
+```

package/plugins/freeflow/skills/setup-freeflow/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: setup-freeflow
+description: Use when setting up, installing, enabling, initializing, or configuring Freeflow in a repo, choosing Codex/Claude/multi-agent activation, creating `.freeflow/config.json`, or changing the repo default mode during setup.
+---
+
+# Setup Freeflow
+
+Use `references/activation-contract.md` before rendering activation text, config, or host setup.
+
+Use `references/host-setup.md` when the request mentions Codex, Claude, both hosts, team setup, solo setup, strict defaults, hooks, CLI, or setup profiles.
+
+## Stop Before Editing
+
+Do not create config, add activation blocks, imports, or rule files until setup has a clear host target and no unresolved repo-rule conflict.
+
+Hard stops:
+- both `AGENTS.md` and `CLAUDE.md` exist, and the user did not explicitly choose a host or ask for multi-agent setup
+- existing repo instructions conflict with asking before user-owned decisions
+- existing repo instructions conflict with verification before completion claims
+- Claude setup would add `.claude/rules/freeflow-core.md` but the user has not clearly chosen Claude or multi-agent setup
+
+For a hard stop, make no file changes. Name the blocker and ask one direct question.
+
+## Inspect
+
+Inspect `.freeflow/config.json`, `AGENTS.md`, `CLAUDE.md`, `.claude/rules/freeflow-core.md`, `.codex/rules/`, existing `## Freeflow` blocks, and conflicting repo instructions.
+
+Existing repo instructions are source truth. If a rule conflicts with Freeflow's core behavior, name the conflict and ask whether to install Freeflow as advisory, revise the rule, or skip setup. Advisory install is a user decision, not the default.
+
+## Target
+
+- Codex target: update `AGENTS.md`.
+- Claude target: update `CLAUDE.md` and `.claude/rules/freeflow-core.md`.
+- If only `AGENTS.md` exists, choose Codex.
+- If only `CLAUDE.md` exists, choose Claude.
+- If both exist and the user explicitly named the host target, update that host's files.
+- If both exist and the target is ambiguous, ask before editing.
+- If neither exists, ask which one to create.
+- Update both only when the user asks for multi-agent setup. Mention duplicated host activation drift risk.
+
+Do not treat the current agent runtime alone as target approval. A Codex run in a repo that also has `CLAUDE.md` still needs the user to choose unless the request or repo instructions make the target explicit.
+
+Update an existing `## Freeflow` block in place. Otherwise place the block near existing agent skill/workflow sections, or append near the end. Never duplicate it. Do not use `.codex/rules/*.rules` for Freeflow behavior; Codex rules are shell approval/security policy, not model memory.
+
+## Config
+
+Create or update `.freeflow/config.json` using the config adapter in `references/activation-contract.md`.
+
+Use `workflow` unless the user explicitly asks to persist a valid repo default: `conversation`, `workflow`, or `strict-workflow`.
+
+Do not infer `strict-workflow` from "team", "strict gates", "careful", or high-risk examples. Recommend or ask unless the user explicitly says to make a mode the repo default.
+
+Do not add current mode, task, phase, file inventory, active plans, version metadata, or activation file path.
+Mode switches are task/conversation scoped unless the user explicitly asks to persist a different default mode.
+
+## Activation
+
+Render the canonical blocks from `references/activation-contract.md`.
+
+For Codex, put the Codex core block in `AGENTS.md`.
+
+For Claude, put only the Claude import block in `CLAUDE.md`, then put the Codex core block text in `.claude/rules/freeflow-core.md`. Do not create a separate Claude rule file for `interview-gate`; plugin runtime loads it.
+
+Do not list the whole workflow, every mode, or full `interview-gate` skill in always-loaded text. Do not split into multiple always-loaded Freeflow rule files unless the user explicitly confirms that split after the one-file recommendation.
+
+## Do Not Create
+
+Setup must not create empty `CONTEXT.md`, docs pages, repo-local hooks, state files, handoffs, skill inventories, or `.codex/rules` behavior files.
+`CONTEXT.md` is domain language memory, not plugin state.
+Plugin-bundled context hooks are installed with Freeflow, not created by repo setup.
+
+## Verify
+
+Before claiming setup is complete, check:
+- config JSON parses
+- config contains only `defaultMode` with the requested explicit default, or `workflow` when no explicit default was requested
+- Codex setup has exactly one `## Freeflow` block in `AGENTS.md`
+- Claude setup has exactly one `CLAUDE.md` import and one `.claude/rules/freeflow-core.md` core file
+- `.codex/rules` was not created or changed for Freeflow behavior
+- no unrelated files changed
+
+After successful setup verification, read `../workflow/SKILL.md`, `../workflow/references/workflow-map.md`, and `../interview-gate/SKILL.md` before the final response. Only say workflow and interview-gate context is loaded for this session if all three files were read successfully.
+
+If verification cannot run, say what remains unverified.