@hassangameryt/freeflow 0.1.0 → 0.3.0

package/plugins/freeflow/skills/grill-context/SKILL.md

@@ -1,79 +0,0 @@
----
-name: grill-context
-description: Use when brainstorming, shaping a feature or task, stress-testing a plan, clarifying product or domain direction, or reaching shared understanding before specs, plans, implementation, or normal non-code decisions.
----
-
-# Grill Context
-
-Shape the direction before action.
-
-This skill is an interview and brainstorming loop, not an implementation skill.
-
-Do not implement, write a spec, or write a plan until the user has approved the direction after the loop.
-
-User pressure to "pick defaults", "don't ask", or "start implementing" is not approval to invent product, domain, permission, billing, security, privacy, compatibility, or public API behavior.
-
-If the answer is discoverable, inspect first. Ask only for choices that remain user-owned.
-
-Ask one question at a time.
-
-## Loop
-
-Interview relentlessly until shared understanding:
-
-1. Inspect relevant context.
-2. Name the decision tree.
-3. Ask the next question that changes the path.
-4. Give your recommended answer without treating it as approval.
-5. Wait for the user.
-6. Continue down the next unresolved branch.
-
-Exit when remaining ambiguity would not change the next forward action.
-
-Do not compress many unresolved branches into one mega-question. Do not stop early because the first question was answered.
-
-## Brainstorming
-
-When the user wants brainstorming, help shape the idea:
-
-- Clarify purpose, constraints, success criteria, and risk.
-- Challenge vague terms and hidden assumptions.
-- Use concrete scenarios to test boundaries.
-- Offer 2-3 approaches when enough context exists.
-- Recommend one approach and explain why.
-
-Brainstorming may be short. Grilling may take many turns. Let the uncertainty decide the length.
-
-Keep it conversational. Do not turn every brainstorm into an artifact.
-
-Read `references/approach-framing.md` when there are multiple plausible approaches or the decision tree is too fuzzy to ask the next useful question.
-
-## Repo-Aware Work
-
-In a codebase, inspect relevant code, docs, tests, ADRs, or existing behavior before asking.
-
-Do not ask the user to restate facts the repo can answer.
-
-If live evidence conflicts with the user's idea, name the conflict and ask which path should win.
-
-## Non-Code Work
-
-Use the same loop for normal decisions:
-
-- Clarify the goal.
-- Surface tradeoffs.
-- Offer options.
-- Ask the next useful question.
-
-Do not pretend repo workflow is required when there is no repo-shaped task.
-
-## Output
-
-Prefer one focused question:
-
-```text
-I found ...
-The key decision is ...
-Question: ...
-Recommendation: ...
-```

package/plugins/freeflow/skills/grill-context/references/approach-framing.md

@@ -1,52 +0,0 @@
-# Approach Framing
-
-Use this when brainstorming or grilling needs options before the next question can be useful.
-
-Do not use this to avoid asking. Use it to make the next decision sharper.
-
-## Frame The Decision
-
-Start with:
-
-- Goal: what outcome the user is trying to reach.
-- Constraint: what limits the solution space.
-- Risk: what would be expensive to get wrong.
-- Unknown: what must be inspected or decided before action.
-- Owner: who owns the next user-owned decision.
-
-If the answer is discoverable in repo evidence, inspect before asking.
-
-## Offer Approaches
-
-Offer 2-3 approaches only when they are meaningfully different.
-
-For each approach, keep it short:
-
-```text
-Approach: ...
-Best when: ...
-Tradeoff: ...
-```
-
-Then ask the next decision-changing question and give the recommended approach without treating it as approval.
-
-## Useful Approach Types
-
-- Lightweight patch: best for small reversible work with clear source truth.
-- Spec-first: best when requirements, scope, or acceptance criteria need durable agreement.
-- Research-first: best when repo behavior, external facts, or evidence are unknown.
-- Diagnostic-first: best when the request is a bug, regression, failed check, flaky behavior, or performance issue.
-- Strict-workflow: best for security, privacy, billing, data loss, public API, compatibility, migrations, permissions, or hard-to-reverse architecture.
-
-## Question Shape
-
-Prefer:
-
-```text
-I found ...
-The decision tree is ...
-Question: ...
-Recommendation: ...
-```
-
-Ask one question. Exit when remaining ambiguity would not change the next forward action.

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

@@ -1,69 +0,0 @@
----
-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-work/SKILL.md

@@ -1,73 +0,0 @@
----
-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/setup-freeflow/SKILL.md

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