@hassangameryt/freeflow 0.8.0 → 0.9.0

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

@@ -1,86 +0,0 @@
-# Artifact Standards
-
-Read this when a durable spec-like artifact needs a destination, identity, status, source trail, or revision history. This reference is judgment: follow established repository conventions before introducing these defaults. One Rule applies: never invent an owner, approval, date, or authority to complete a header.
-
-## Choose The Destination
-
-Place the artifact where its intended readers and authority belong.
-
-- Use an established product, design, API, issue, migration, policy, or architecture location when one exists.
-- For a task-local artifact, read [Track Work](../../track-work/SKILL.md) and use the `specs/` location it owns unless the artifact should become canonical repo documentation.
-- Use the repository's issue tracker when the requested artifact is an issue and that system is available and intended.
-- Ask before choosing between task-local memory and canonical repository documentation when the distinction changes authority, review, or longevity.
-
-Do not create a new top-level docs convention for one artifact without a real need.
-
-## Give Durable Artifacts Identity
-
-Use the repository's required frontmatter or metadata format. When no convention exists and identity will help future readers, use a compact title and header:
-
-```md
-# Team Invitations API
-
-> **Doc ID:** SPEC-001-team-invitations-api
-> **Type:** API Contract
-> **Status:** Draft
-> **Owner:** User
-> **Source:** Working Record task-004 and accepted product decisions
-```
-
-Add only useful fields:
-
-- **Doc ID:** stable identifier when links, review history, or supersession need one.
-- **Type:** the artifact's actual job, such as PRD, Issue, Technical Design, API Contract, Migration Contract, or Decision.
-- **Status:** current artifact state under the repository or owner's vocabulary.
-- **Owner:** person or role with authority over the artifact's intent.
-- **Source:** compact pointers to accepted context and evidence.
-- **Date / Last Updated:** only when a reliable date matters.
-- **Supersedes / Superseded by:** when readers must follow artifact lineage.
-
-Do not invent an owner, approval, date, or authority merely to complete a header. Writing or reviewing an artifact does not make it `Approved`.
-
-## Represent Status Honestly
-
-Use the repository's statuses when available. Otherwise keep the vocabulary small, for example:
-
-```text
-Draft | Reviewed | Approved | Rejected | Superseded
-```
-
-The appropriate statuses depend on the artifact type. An issue, policy, ADR, and API contract need not share one lifecycle.
-
-Status communicates artifact state; it does not replace review evidence or user authority. Distinguish author self-review from selected independent review when reporting review status. Writing a Spec or Plan does not automatically select an independent reviewer.
-
-## Preserve Sources Without Copying Them
-
-Link to stable sources such as:
-
-```text
-file:<path>#<section>
-working-record:<task>/record.md#<section>
-commit:<sha>
-issue:<id>
-output:<output-id>
-session:<session-id>/turn:<turn-id>
-```
-
-Use identifiers that actually exist. Prefer links and concise quotations over copied inventories, logs, diffs, or transcripts.
-
-A source trail should let a future reader recover why the artifact says what it says. For consequential choices, preserve the relevant proposal, disclosed consequences, and acceptance source rather than an isolated “proceed” or an agent's approval summary. Distinguish accepted amendments from unselected experimental findings. This does not require preserving every conversation turn.
-
-## Revise Without Rewriting History
-
-Do not add a changelog on first creation unless repository policy requires one.
-
-For material revisions:
-
-- update the artifact's current content and status honestly;
-- preserve consequential rationale through a change note, decision record, supersession link, or version control;
-- record only changes that help readers understand current intent or avoid repeating rejected work;
-- do not turn the changelog into execution status or transcript history.
-
-Use the Working Record for task progress, slice history, and current execution state.
-
-## Keep The Artifact Usable
-
-A durable artifact should be identifiable, source-backed, and understandable without the original conversation. It should contain enough depth for its intended use while avoiding information owned by a Plan, Working Record, Handoff, or another canonical document.

package/skills/write-spec/references/decision-records.md

@@ -1,80 +0,0 @@
-# Decision Records
-
-Read this when writing or revising an artifact whose primary job is to preserve a decision and its rationale.
-
-This reference is judgment, with one Rule: never write an assumption, reviewer suggestion, or agent preference as an accepted decision, and never rewrite a superseded decision to match the present.
-
-## Choose The Right Record
-
-Use the smallest record that preserves the decision where future work will look for it.
-
-- **Working Record decision:** task-local choice that affects later slices or current task direction. [Track Work](../../track-work/SKILL.md) owns its `D-` ID, state, rationale, and supersession.
-- **Decision note:** durable product, policy, scope, compatibility, or technical choice that needs a separate document but does not require the repository's ADR process.
-- **ADR:** surprising, cross-cutting, or hard-to-reverse architecture or operational decision whose alternatives and consequences must remain durable.
-- **Owning spec:** keep a decision inside a PRD, API contract, technical design, or other spec when that artifact clearly owns the decision and a separate record would only duplicate it.
-
-Do not create a separate decision artifact merely because a decision occurred.
-
-## When A Separate Decision Artifact Helps
-
-A separate record is useful when the decision is:
-
-- hard or expensive to reverse;
-- surprising relative to repository or domain practice;
-- a real tradeoff among materially different paths;
-- cross-cutting across systems, teams, or operational boundaries;
-- likely to be challenged again without its original rationale;
-- intentionally rejected or superseded in a way future work must understand;
-- explicitly requested as a durable decision artifact.
-
-Ordinary reversible implementation choices, task progress, temporary constraints, assumptions, and unanswered questions do not belong in a durable decision record.
-
-## Write The Decision Clearly
-
-Use the repository's ADR or decision format when one exists. Otherwise adapt this shape:
-
-```md
-# Decision: <title>
-
-> **Doc ID:** DECISION-<stable-id>
-> **Type:** Decision | ADR
-> **Status:** Proposed | Accepted | Rejected | Superseded
-> **Owner:** <decision owner>
-> **Source:** <accepted context and evidence>
-
-## Context
-<Decision question, constraints, and evidence.>
-
-## Decision
-<Chosen path and exact scope.>
-
-## Alternatives
-<Only materially different alternatives and why they were not chosen.>
-
-## Consequences
-<Benefits, costs, risks, compatibility, operations, and follow-up obligations.>
-
-## Revisit Or Supersession
-<Evidence, conditions, or later decision that would reopen or replace it.>
-```
-
-State proposals as proposals. Do not write an assumption, reviewer suggestion, or agent preference as an accepted decision. For a consequential choice, identify the presented option, disclosed consequences, and acceptance source. Approval to investigate or draft an option does not establish acceptance of its eventual production requirements.
-
-## Preserve Authority And History
-
-Name who made or owns the decision when that matters. A reviewer can challenge a decision but cannot silently replace it. A Working Record, Plan, or Handoff cannot supersede a durable decision merely by describing a different path.
-
-When a decision changes:
-
-- preserve the old record as `Superseded` rather than rewriting it to match the present;
-- create or identify the replacement decision;
-- link both directions;
-- identify owning specs, plans, or policies whose current content depends on it and revise them when authorized;
-- mark dependent work contingent when a required decision or source revision remains unresolved;
-- preserve the evidence that justified the change.
-
-Live evidence may show that implementation violates a decision or that the decision is no longer viable. Use Decision Gate when resolving that conflict requires user authority.
-
-## Avoid Duplication
-
-Reference the decision from dependent artifacts instead of copying its full rationale. Keep task-local decisions in the Working Record unless they become durable beyond the task.

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

@@ -1,143 +0,0 @@
-# Spec Shapes
-
-Read this when choosing the structure of a spec-like artifact. This reference is judgment: these are composable shapes, not mandatory templates. Use only the sections the artifact needs for its intended use.
-
-## Product Spec Or PRD
-
-Use for a product, capability, workflow, or user-facing outcome.
-
-Possible sections:
-
-- problem and motivation;
-- intended outcome;
-- users or actors;
-- scope and non-goals;
-- user journeys or observable behavior;
-- requirements and constraints;
-- product, policy, or domain decisions;
-- edge and failure behavior;
-- acceptance criteria;
-- unresolved questions and source evidence.
-
-Do not turn a PRD into an implementation task list.
-
-## Issue Or Problem Specification
-
-Use when a durable issue must define a problem clearly enough to investigate, fix, or accept.
-
-Possible sections:
-
-- observed problem or requested change;
-- affected behavior and users;
-- current evidence, reproduction, or examples;
-- expected behavior;
-- scope and non-goals;
-- severity, constraints, and known impact;
-- acceptance criteria;
-- unresolved facts or owner decisions.
-
-Do not present a guessed cause or requested patch as established fact. A fix sequence belongs in a Plan after the cause and path are sufficiently understood.
-
-## Requirements Or Behavioral Specification
-
-Use when observable behavior and constraints matter more than implementation structure.
-
-Possible sections:
-
-- actors and preconditions;
-- required behavior and invariants;
-- inputs, outputs, states, and transitions;
-- errors, rejection, degradation, and recovery;
-- forbidden outcomes;
-- compatibility and data guarantees;
-- acceptance examples and evidence.
-
-Express behavior precisely without copying implementation logic into the contract.
-
-## Technical Design
-
-Use when the artifact must define an accepted technical direction in depth.
-
-Possible sections:
-
-- problem and current evidence;
-- goals and non-goals;
-- proposed architecture or design;
-- module, interface, state, and ownership boundaries;
-- data flow and persistence;
-- failure contract and recovery;
-- security, privacy, performance, and operational constraints;
-- alternatives and rationale;
-- compatibility or migration impact;
-- risks, validation, and unresolved design questions.
-
-A technical design may contain implementation detail when that detail defines the accepted design. Ordered phases and execution slices still belong in a Plan.
-
-### Implementation Decisions
-
-Include this subsection when consequential engineering choices must survive implementation handoffs or context loss. For selecting those choices, use [Design for Depth](../../design-for-depth/SKILL.md); this shape preserves their result rather than duplicating the design method.
-
-Capture only what the intended implementation needs:
-
-- selected representation, identity, state owners, and module responsibilities;
-- essential algorithm, effect ordering, update/invalidation, and failure behavior;
-- source basis, rationale, and invariants;
-- a plausible wrong implementation and the observer that distinguishes it;
-- required constraints, suggested mechanics, and implementer freedom;
-- unresolved assumptions and conditions requiring reconsideration.
-
-A compact type or control-flow sketch is useful when it removes consequential ambiguity. Mark illustrative code as such; it is not the behavioral oracle. Keep the applicable revision recoverable and update only decisions affected by new evidence. Do not require this subsection for a product-only artifact or an already clear local change.
-
-## API, Protocol, Or Interface Contract
-
-Use for a public or internal interface that callers will depend on.
-
-Possible sections:
-
-- interface, endpoint, command, event, or protocol name;
-- callers, roles, authentication, and permissions;
-- requests, inputs, responses, outputs, and schemas;
-- invariants and ordering;
-- errors and failure semantics;
-- idempotency, retries, versioning, and compatibility;
-- privacy, billing, data-safety, and operational constraints;
-- examples and acceptance evidence.
-
-Stop rather than inventing caller-visible behavior or compatibility promises.
-
-## Migration Contract
-
-Use when current and target states, compatibility, and safety obligations must be durable before execution is planned.
-
-Possible sections:
-
-- current and target contracts;
-- affected consumers, data, traffic, or configuration;
-- compatibility and support commitments;
-- data and state invariants;
-- cutover, rollback, or forward-recovery requirements;
-- observation and removal conditions;
-- consequential failure behavior;
-- acceptance and completion evidence;
-- decisions still required.
-
-Include ordering only when it is part of the accepted migration contract. Detailed execution phases belong in a migration or implementation Plan.
-
-## Decision Artifact
-
-Use when a durable choice and its rationale are the artifact's primary job. Read [decision records](decision-records.md) before choosing a task-local decision note, durable decision record, or ADR.
-
-Possible sections:
-
-- context and decision question;
-- decision and owner;
-- materially different alternatives;
-- rationale and evidence;
-- consequences and constraints;
-- revisit or supersession conditions.
-
-## Combine Carefully
-
-An artifact may combine shapes when it genuinely owns both jobs, such as a technical design containing an API contract. Keep each responsibility legible.
-
-Do not create an omnibus artifact merely to avoid links. Separate artifacts when they have different owners, statuses, audiences, lifecycles, or review boundaries.