@hassangameryt/freeflow 0.3.0 → 0.5.0

package/skills/write-skill/scripts/skill-author.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import { initSkill, inspectSkill, SkillAuthorError, validateSkill } from "./lib/skill-author.mjs";
+
+const commands = new Set(["init", "validate", "inspect"]);
+
+function printUsage() {
+  process.stdout.write(
+    `Usage: skill-author <init|validate|inspect> [options]\n\nCommands:\n  init <directory> --name <name> --description <text>\n      init creates a minimal SKILL.md and refuses to overwrite one\n  validate <directory> [--package-root <directory>]\n      validate checks structure and recursive resource containment\n  inspect <directory> [--package-root <directory>]\n      inspect reports factual inventory plus validation findings\n\nOutput:\n  Commands emit JSON. Invalid structure still emits JSON and exits nonzero.\n  Command errors emit structured error JSON.\n  Package root defaults to the nearest package.json ancestor, then the skill parent.\n\nFrontmatter:\n  Validation supports flat plain-string or JSON-compatible double-quoted scalars.\n  Double-quote values when punctuation, numbers, booleans, or null-like text could be ambiguous.\n`,
+  );
+}
+
+function fail(code, message, exitCode = 2) {
+  throw new SkillAuthorError(code, message, exitCode);
+}
+
+function parseOptions(args, allowedOptions) {
+  const positionals = [];
+  const options = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (!argument.startsWith("--")) {
+      positionals.push(argument);
+      continue;
+    }
+
+    if (!allowedOptions.has(argument)) {
+      fail("unknown-option", `Unknown option: ${argument}`);
+    }
+    if (Object.hasOwn(options, argument)) {
+      fail("duplicate-option", `Option may be supplied once: ${argument}`);
+    }
+
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+      fail("missing-option-value", `Option requires a value: ${argument}`);
+    }
+    options[argument] = value;
+    index += 1;
+  }
+
+  return { positionals, options };
+}
+
+async function run(command, args) {
+  if (command === "init") {
+    const { positionals, options } = parseOptions(args, new Set(["--name", "--description"]));
+    if (positionals.length !== 1) {
+      fail("invalid-arguments", "init requires exactly one skill directory");
+    }
+    if (!Object.hasOwn(options, "--name") || !Object.hasOwn(options, "--description")) {
+      fail("invalid-arguments", "init requires --name and --description");
+    }
+    return initSkill({
+      directory: positionals[0],
+      name: options["--name"],
+      description: options["--description"],
+    });
+  }
+
+  if (command === "validate" || command === "inspect") {
+    const { positionals, options } = parseOptions(args, new Set(["--package-root"]));
+    if (positionals.length !== 1) {
+      fail("invalid-arguments", `${command} requires exactly one skill directory`);
+    }
+    const input = { directory: positionals[0], packageRoot: options["--package-root"] };
+    return command === "validate" ? validateSkill(input) : inspectSkill(input);
+  }
+
+  fail("unknown-command", `Unknown command: ${command}`);
+}
+
+async function main() {
+  const [command, ...args] = process.argv.slice(2);
+
+  if (!command || command === "--help" || command === "-h") {
+    printUsage();
+    return;
+  }
+  if (!commands.has(command)) {
+    fail("unknown-command", `Unknown command: ${command}`);
+  }
+
+  const result = await run(command, args);
+  process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  if (result.status === "invalid") process.exitCode = 1;
+}
+
+try {
+  await main();
+} catch (error) {
+  const knownError = error instanceof SkillAuthorError;
+  const result = {
+    command: process.argv[2] ?? null,
+    status: "error",
+    error: {
+      code: knownError ? error.code : "unexpected-error",
+      message: knownError ? error.message : "Skill Author failed unexpectedly",
+    },
+  };
+  process.stderr.write(`${JSON.stringify(result, null, 2)}\n`);
+  process.exitCode = knownError ? error.exitCode : 1;
+}

package/skills/write-spec/SKILL.md

@@ -1,93 +1,104 @@
 ---
 name: write-spec
-description: Use when asked to create or update a durable spec, PRD, requirements document, or decision artifact from agreed requirements, discovery, brainstorming, or source evidence, especially for strict-workflow risk areas that may need owner confirmation before writing.
+description: Use when writing or revising a spec, PRD, issue, API contract, technical design, migration contract, decision artifact, or similar durable document.
 ---
 
 # Write Spec
 
-Write only from source-backed context. A polished spec can change source of truth.
+Turn clear intent and source evidence into a durable artifact that later work can rely on.
 
-## Route First
+A spec may be broad, deep, or both. Its shape follows its intended use. It is not a transcript, implementation plan, Working Record, or polished substitute for an unresolved decision.
 
-If the user asks a question about a spec, answer the question. Do not create or edit the spec unless asked.
+## Identify The Artifact
 
-Classify every spec request before writing:
+Before writing, establish:
 
-- Evidence-aligned: write the spec.
-- Missing source context: ask for context or route to `discover`.
-- Source-of-truth override: name the conflict and do not write.
+- artifact type and intended use;
+- audience or future action it must support;
+- accepted intent, scope, and source context;
+- destination and repository convention;
+- unresolved questions that belong in the artifact.
 
-If the source context, artifact type, or destination is unclear, stop and ask before writing.
+If the user is asking about an artifact, answer instead of writing one. If direction or alternatives still need shared understanding, read [Discuss](../discuss/SKILL.md). If one user-owned choice or source conflict blocks writing, read [Decision Gate](../decision-gate/SKILL.md).
 
-## Hard Stops
+Do not repeat discussion that already settled the artifact's intent.
 
-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.
+## Write From Source
 
-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.
+Inspect the sources that define the artifact:
 
-The original request is not override confirmation. "Latest context", "handoff says", "do not ask", or "write the spec" are not enough.
+- explicit user decisions and current shared understanding;
+- [Track Work](../track-work/SKILL.md), which owns the living Working Record for current state, slices, task-local decisions, and evidence, when one exists;
+- relevant code, tests, requirements, policies, ADRs, and established behavior;
+- existing artifacts that this one revises or depends on;
+- current primary sources when an external contract or version matters.
 
-Stop before writing when the spec would:
+Use a Working Record as task memory, not authority over contradictory user decisions or live evidence. Distinguish accepted facts and decisions from hypotheses, proposals, and unresolved questions.
 
-- 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.
-- Reduce or reframe agreed scope as `v1`, MVP, roadmap, or later-version work without source-backed owner approval.
+Do not infer goals or requirements from adjacent repository details merely because they are available.
 
-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.
+## Shape The Artifact By Its Job
 
-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.
+Read [spec shapes](references/spec-shapes.md) and use only the sections that help the artifact perform its intended job. Read [artifact standards](references/artifact-standards.md) when choosing a durable destination, identity, status, or revision shape. Read [decision records](references/decision-records.md) when the artifact records a durable decision.
 
-Name the conflict or missing decision. Ask which path to follow. Recommend the path supported by evidence.
+Include, when relevant:
 
-## Source First
+- purpose, context, scope, and accepted content;
+- behavior, design, interfaces, constraints, and consequential failure semantics required by the artifact;
+- acceptance and suitable evidence;
+- accepted decisions, clearly marked uncertainty, and source references.
 
-Before writing, inspect the current source of truth:
+A technical design may go deeply into architecture, interfaces, ownership, state, and failure behavior. Do not remove useful depth merely to keep the artifact short.
 
-- User-provided context.
-- Existing specs, docs, ADRs, tests, and policies.
-- Relevant code when behavior already exists.
-- Handoffs only as memory, not authority.
+Do not turn the artifact into ordered execution phases, task status, slice history, or a volatile file inventory. Ordered execution belongs in a Plan; living task state belongs in the Working Record.
 
-Live repo evidence overrides stale notes.
+## Stop Before Inventing Intent
 
-## Write Path
+Stop when writing would:
 
-When discovery, brainstorming, or clarification reaches shared understanding, convert that agreed context into a spec. Do not re-interview from scratch.
+- invent or silently change product behavior, scope, requirements, public interfaces, compatibility, sensitive policy, failure semantics, or hard-to-reverse design;
+- override code, tests, docs, policies, ADRs, or established behavior without resolving the conflict;
+- present a tentative proposal or assumption as accepted;
+- hide an owner decision behind `TBD`, polished prose, or an unmarked open question;
+- reduce agreed scope into MVP, v1/v2, roadmap, or later-version framing without approval;
+- create a destination or artifact convention whose authority or durability matters without resolving it.
 
-Preserve the agreed scope. Use scope boundaries, open questions, or follow-up artifacts to manage size; use `v1`/`v2`, MVP, release, or roadmap framing only when it was agreed or source-backed.
+Ask only for the decision that prevents the artifact from serving its intended use. Otherwise represent uncertainty honestly and continue.
 
-If remaining ambiguity would not change the next plan, write the spec and mark the ambiguity as open. Preserve tentative architecture assumptions as tentative unless evidence or the owner settles them.
+## Revise Deliberately
 
-Use this shape unless the repo has a stronger convention:
+When revising an artifact:
 
-- Problem.
-- Intended outcome.
-- Scope / out of scope / ask first / never boundaries when useful.
-- Requirements.
-- Acceptance criteria.
-- Decisions made and open decisions.
-- Constraints / evidence.
-- Open questions.
+- preserve accepted content that still holds;
+- update only what new intent or evidence changed;
+- keep superseded decisions and material rationale recoverable through the owning decision record, change history, or version control.
 
-Read `references/spec-shapes.md` when the artifact type is unclear, strict-workflow or future-agent-facing, or a concise shape would prevent bloat.
+Do not rewrite history or synchronize unaffected artifacts. A clerical correction does not reopen settled intent; a material revision changes the artifact's review boundary and may affect its dependencies.
 
-Keep it concise. Do not include volatile repo inventory. Use file paths only when they are needed evidence.
+## Self-Check
 
-## Durable Artifact Details
+Silently review the artifact before routing it onward:
 
-For durable specs or future-agent-facing artifacts, follow `references/artifact-standards.md`.
+- Does it perform its stated job?
+- Does it agree with accepted intent and source evidence?
+- Can a future reader distinguish required, tentative, open, deferred, and superseded information?
+- Is it broad and deep enough for its intended use without taking over another artifact's job?
+- Are consequential claims, failure behavior, and acceptance supported or explicitly unresolved?
+- Did writing introduce any decision the user did not make?
 
-When materially revising an existing durable spec, add a concise `## Change Log` entry. Do not add a changelog on first creation.
+Correct clear local issues directly. Surface only unresolved material issues that prevent the artifact from being fit for use.
 
-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.
+## Review The Artifact
 
-## Completion
+After writing or materially revising the artifact, route it to [Review Artifact](../review-artifact/SKILL.md) before treating it as fit for its intended use.
 
-After writing, report:
+Provide the reviewer with the complete artifact, its intended use, source truth, dependencies, and known evidence gaps. Review Artifact owns review items, judgment, adjudication, and the review cycle.
 
-- The artifact path.
-- The source context used.
-- Any open questions or decisions still blocked.
+## Report
+
+State:
+
+- artifact path, type, and intended use;
+- source context used;
+- material unresolved questions or blocked decisions;
+- artifact-review status.

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

@@ -1,67 +1,86 @@
 # 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.
+Read this when a durable spec-like artifact needs a destination, identity, status, source trail, or revision history. Follow established repository conventions before introducing these defaults.
 
-Do not apply this to chat answers, quick questions, tiny reversible work, or conversation mode unless the user explicitly asks for a file.
+## Choose The Destination
 
-## Header
+Place the artifact where its intended readers and authority belong.
 
-For durable specs, start with a compact header:
+- 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
-> **Doc ID:** SPEC-001-team-invitations
-> **Date:** 2026-05-26
-> **Owner:** Hassan Mohiddin
-> **Type:** Spec
+# Team Invitations API
+
+> **Doc ID:** SPEC-001-team-invitations-api
+> **Type:** API Contract
 > **Status:** Draft
-> **Source:** User-provided decision session
+> **Owner:** User
+> **Source:** Working Record task-004 and accepted product decisions
 ```
 
-Rules:
+Add only useful fields:
 
-- `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`.
+- **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.
 
-Optional team fields:
+Do not invent an owner, approval, date, or authority merely to complete a header. Writing or reviewing an artifact does not make it `Approved`.
 
-```md
-> **Approver:** Platform Lead
-> **Reviewers:** Security, Billing
-> **Last Updated:** 2026-05-27
+## Represent Status Honestly
+
+Use the repository's statuses when available. Otherwise keep the vocabulary small, for example:
+
+```text
+Draft | Reviewed | Approved | Rejected | Superseded
 ```
 
-Add optional fields only when the user, repo, team setting, or strict-workflow risk makes them useful.
+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.
 
-## Mode Pressure
+## Preserve Sources Without Copying Them
 
-- 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.
+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>
+```
 
-## Statuses
+Use identifiers that actually exist. Prefer links and concise quotations over copied inventories, logs, diffs, or transcripts.
 
-Use small status sets:
+A source trail should let a future reader recover why the artifact says what it says. It does not require preserving every conversation turn.
 
-| 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` |
+## Revise Without Rewriting History
 
-Do not invent a large workflow taxonomy.
+Do not add a changelog on first creation unless repository policy requires one.
 
-## Change Log
+For material revisions:
 
-Do not add a changelog on first creation.
+- 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.
 
-Add `## Change Log` after a material revision, status transition, or implementation divergence.
+Use the Working Record for task progress, slice history, and current execution state.
 
-Use changelogs for living docs, runbooks, policies, and long-lived architecture docs.
+## Keep The Artifact Usable
 
-Never use a changelog as a transcript. Record meaningful document evolution only.
+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

@@ -0,0 +1,77 @@
+# Decision Records
+
+Read this when writing or revising an artifact whose primary job is to preserve a decision and its rationale.
+
+## 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.
+
+## 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;
+- update owning specs, plans, or policies whose current content depends on it;
+- 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.