@hassangameryt/freeflow 0.1.0 → 0.2.0

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

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

@@ -1,65 +0,0 @@
-# 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/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`.