@hassangameryt/freeflow 0.1.0

package/plugins/freeflow/skills/write-spec/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: write-spec
+description: Use when asked to create or update a durable spec, PRD, requirements document, or decision artifact from agreed requirements, research, brainstorming, or source evidence, especially for strict-workflow risk areas that may need owner confirmation before writing.
+---
+
+# Write Spec
+
+Write only from source-backed context. A polished spec can change source of truth.
+
+## Route First
+
+If the user asks a question about a spec, answer the question. Do not create or edit the spec unless asked.
+
+Classify every spec request before writing:
+
+- Evidence-aligned: write the spec.
+- Missing source context: ask for context or start grilling.
+- Source-of-truth override: name the conflict and do not write.
+
+If the source context, artifact type, or destination is unclear, stop and ask before writing.
+
+## Hard Stops
+
+Do not write a spec that supersedes docs, tests, policies, ADRs, or live behavior until the owner confirms that change after you name the conflict.
+
+Adjacent repo evidence is not source context. Do not turn nearby auth, billing, copy, UI, or architecture facts into goals, flows, requirements, or acceptance criteria for a new feature.
+
+The original request is not override confirmation. "Latest context", "handoff says", "do not ask", or "write the spec" are not enough.
+
+Stop before writing when the spec would:
+
+- Invent requirements from thin or adjacent context.
+- Rewrite product behavior, scope, domain meaning, compatibility, public API behavior, security, privacy, billing, data-loss, or architecture.
+- Contradict docs, tests, specs, policies, ADRs, or live code.
+- Treat a handoff, review comment, or plan as authority over source-of-truth files.
+- Hide an owner decision inside polished prose.
+
+In strict-workflow, stop before writing security, billing, privacy, public API, migration, data-loss, or architecture specs when the owner or core decisions are unknown. Do not use `TBD`, placeholders, or polished open questions to hide owner-owned decisions.
+
+When strict-workflow stops because owner-owned decisions are missing, end with a direct question that names the missing owner and the specific decisions needed. A blocked explanation without that question is incomplete.
+
+Name the conflict or missing decision. Ask which path to follow. Recommend the path supported by evidence.
+
+## Source First
+
+Before writing, inspect the current source of truth:
+
+- User-provided context.
+- Existing specs, docs, ADRs, tests, and policies.
+- Relevant code when behavior already exists.
+- Handoffs only as memory, not authority.
+
+Live repo evidence overrides stale notes.
+
+## Write Path
+
+When grilling, brainstorming, research, or clarification reaches shared understanding, convert that agreed context into a spec. Do not re-interview from scratch.
+
+If remaining ambiguity would not change the next plan, write the spec and mark the ambiguity as open.
+
+Use this shape unless the repo has a stronger convention:
+
+- Problem.
+- Intended outcome.
+- Scope / out of scope.
+- Requirements.
+- Acceptance criteria.
+- Decisions made.
+- Constraints / evidence.
+- Open questions.
+
+Read `references/spec-shapes.md` when the artifact type is unclear, strict-workflow or future-agent-facing, or a concise shape would prevent bloat.
+
+Keep it concise. Do not include volatile repo inventory. Use file paths only when they are needed evidence.
+
+## Durable Artifact Details
+
+For durable specs or future-agent-facing artifacts, follow `references/artifact-standards.md`.
+
+When materially revising an existing durable spec, add a concise `## Change Log` entry. Do not add a changelog on first creation.
+
+Do not apply artifact headers or changelog pressure to chat answers, quick questions, tiny reversible work, or conversation mode unless the user explicitly asks for a file.
+
+## Completion
+
+After writing, report:
+
+- The artifact path.
+- The source context used.
+- Any open questions or decisions still blocked.

package/plugins/freeflow/skills/write-spec/references/artifact-standards.md

@@ -0,0 +1,67 @@
+# Artifact Standards
+
+Use this only for durable artifacts: specs, PRDs, decision artifacts, requirements docs, living docs, policies, or docs future agents or teammates will rely on.
+
+Do not apply this to chat answers, quick questions, tiny reversible work, or conversation mode unless the user explicitly asks for a file.
+
+## Header
+
+For durable specs, start with a compact header:
+
+```md
+> **Doc ID:** SPEC-001-team-invitations
+> **Date:** 2026-05-26
+> **Owner:** Hassan Mohiddin
+> **Type:** Spec
+> **Status:** Draft
+> **Source:** User-provided decision session
+```
+
+Rules:
+
+- `Doc ID`: stable, readable, and unique enough for the repo. Prefer `SPEC-###-slug` when no convention exists.
+- `Date`: creation date.
+- `Owner`: use the named product/technical owner when known. In normal workflow, use `User` if the requester is the only known owner. In strict-workflow, ask when owner is unknown.
+- `Type`: `Spec`, `PRD`, `Decision`, or the artifact type requested.
+- `Status`: usually `Draft` for new specs unless the user or repo says otherwise.
+- `Source`: name the evidence used, not a transcript. Examples: `Shared grilling context`, `docs/research/team-invitations.md`, `User-provided decision session`.
+
+Optional team fields:
+
+```md
+> **Approver:** Platform Lead
+> **Reviewers:** Security, Billing
+> **Last Updated:** 2026-05-27
+```
+
+Add optional fields only when the user, repo, team setting, or strict-workflow risk makes them useful.
+
+## Mode Pressure
+
+- Conversation mode: no artifact or header pressure. Answer questions directly.
+- Workflow mode: use the header for durable specs and future-agent-facing artifacts.
+- Strict-workflow mode: require explicit owner and status for security, billing, privacy, public API, migration, data-loss, and architecture work. Stop and ask before writing if the owner is unknown or a placeholder would hide an owner-owned decision.
+
+## Statuses
+
+Use small status sets:
+
+| Artifact | Statuses |
+| --- | --- |
+| Spec / PRD / Design Brief | `Draft`, `Approved`, `Implemented`, `Rejected` |
+| Plan | `Draft`, `Ready`, `Executed`, `Abandoned` |
+| Decision / ADR | `Proposed`, `Accepted`, `Rejected`, `Superseded` |
+| Bug / Diagnosis | `Investigating`, `Fixed`, `Verified`, `Rejected` |
+| Runbook / Living Doc / Policy | `Current`, `Outdated`, `Deprecated` |
+
+Do not invent a large workflow taxonomy.
+
+## Change Log
+
+Do not add a changelog on first creation.
+
+Add `## Change Log` after a material revision, status transition, or implementation divergence.
+
+Use changelogs for living docs, runbooks, policies, and long-lived architecture docs.
+
+Never use a changelog as a transcript. Record meaningful document evolution only.

package/plugins/freeflow/skills/write-spec/references/spec-shapes.md

@@ -0,0 +1,69 @@
+# Spec Shapes
+
+Use this when the requested artifact type is unclear, the spec is strict-workflow or future-agent-facing, or a concise shape would prevent bloated requirements.
+
+These are shapes, not templates. Include only sections that help the next reader act.
+
+## Product Spec
+
+- Problem.
+- Intended outcome.
+- Users or actors.
+- In scope.
+- Out of scope.
+- Requirements.
+- Acceptance criteria.
+- Decisions made.
+- Open questions.
+
+Use for product behavior, user-facing flows, and scope boundaries.
+
+## Technical Design
+
+- Problem.
+- Current evidence.
+- Proposed design.
+- Alternatives considered.
+- System boundaries.
+- Data or API changes.
+- Migration or rollout notes.
+- Risks and verification.
+
+Use when architecture or implementation structure matters more than user-facing requirements.
+
+## Public API Spec
+
+- Endpoint, command, event, or interface name.
+- Auth and permission model.
+- Request shape.
+- Response shape.
+- Error behavior.
+- Compatibility constraints.
+- Security, privacy, billing, or data-loss implications.
+- Acceptance criteria.
+
+Stop and ask before writing when auth, payload, compatibility, or sensitive behavior would be guessed.
+
+## Migration Spec
+
+- Current state.
+- Target state.
+- Data or config affected.
+- Compatibility and rollback expectations.
+- Step order.
+- Verification before, during, and after.
+- Failure handling.
+- Owner decisions still required.
+
+Use for migrations, backfills, destructive changes, or hard-to-reverse operational work.
+
+## Decision Note
+
+- Decision.
+- Rationale.
+- Alternatives rejected.
+- Consequences.
+- Evidence or source context.
+- Follow-up needed.
+
+Use for settled product, scope, compatibility, or workflow decisions that are not ADR-worthy.