@hassangameryt/freeflow 0.2.0 → 0.4.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

@@ -0,0 +1,104 @@
+---
+name: write-spec
+description: Use when writing or revising a spec, PRD, issue, API contract, technical design, migration contract, decision artifact, or similar durable document.
+---
+
+# Write Spec
+
+Turn clear intent and source evidence into a durable artifact that later work can rely on.
+
+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.
+
+## Identify The Artifact
+
+Before writing, establish:
+
+- 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 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).
+
+Do not repeat discussion that already settled the artifact's intent.
+
+## Write From Source
+
+Inspect the sources that define the artifact:
+
+- 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.
+
+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.
+
+Do not infer goals or requirements from adjacent repository details merely because they are available.
+
+## Shape The Artifact By Its Job
+
+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.
+
+Include, when relevant:
+
+- 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.
+
+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.
+
+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.
+
+## Stop Before Inventing Intent
+
+Stop when writing would:
+
+- 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.
+
+Ask only for the decision that prevents the artifact from serving its intended use. Otherwise represent uncertainty honestly and continue.
+
+## Revise Deliberately
+
+When revising an artifact:
+
+- 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.
+
+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.
+
+## Self-Check
+
+Silently review the artifact before routing it onward:
+
+- 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?
+
+Correct clear local issues directly. Surface only unresolved material issues that prevent the artifact from being fit for use.
+
+## Review The Artifact
+
+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.
+
+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.
+
+## 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

@@ -0,0 +1,86 @@
+# Artifact Standards
+
+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.
+
+## 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.
+
+## 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. It 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

@@ -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.

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

@@ -0,0 +1,128 @@
+# Spec Shapes
+
+Read this when choosing the structure of a spec-like artifact. 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.
+
+## 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.

package/plugins/freeflow/command-surface.json

@@ -1,77 +0,0 @@
-{
-  "nativeSlashHandlers": false,
-  "modeCommands": [
-    {
-      "command": "/workflow conversation",
-      "routesTo": "mode-contract"
-    },
-    {
-      "command": "/workflow workflow",
-      "routesTo": "mode-contract"
-    },
-    {
-      "command": "/workflow strict-workflow",
-      "routesTo": "mode-contract"
-    },
-    {
-      "command": "/workflow reset",
-      "routesTo": "mode-contract"
-    }
-  ],
-  "directSkillCalls": [
-    {
-      "command": "/research",
-      "skill": "research"
-    },
-    {
-      "command": "/write-spec",
-      "skill": "write-spec"
-    },
-    {
-      "command": "/review-artifact",
-      "skill": "review-artifact"
-    },
-    {
-      "command": "/write-plan",
-      "skill": "write-plan"
-    },
-    {
-      "command": "/execute-plan",
-      "skill": "execute-plan"
-    },
-    {
-      "command": "/diagnose-failure",
-      "skill": "diagnose-failure"
-    },
-    {
-      "command": "/verify-work",
-      "skill": "verify-work"
-    },
-    {
-      "command": "/review-work",
-      "skill": "review-work"
-    },
-    {
-      "command": "/commit-work",
-      "skill": "commit-work"
-    },
-    {
-      "command": "/handoff",
-      "skill": "handoff"
-    },
-    {
-      "command": "/bypass",
-      "skill": "bypass"
-    }
-  ],
-  "developerSkillCalls": [
-    {
-      "command": "/write-skill",
-      "skill": "write-skill"
-    },
-    {
-      "command": "/evaluate-skill",
-      "skill": "evaluate-skill"
-    }
-  ]
-}

package/plugins/freeflow/docs/README.md

@@ -1,40 +0,0 @@
-# Freeflow Docs
-
-These docs describe the public plugin behavior. Historical research stays in root `docs/`; eval sources and reports live under `plugins/freeflow/evals/`.
-
-After installing Freeflow, run setup in each repo where you want it active:
-
-```text
-/setup-freeflow
-```
-
-Setup creates activation/config files only.
-
-In Codex, open the hooks screen after install:
-
-```text
-/hooks
-```
-
-Press `t` to trust/enable the Freeflow `SessionStart` hook when Codex marks it as needing review. Once enabled, plugin-bundled hooks load workflow and interview-gate context at session start, resume, clear, and compact.
-
-In Pi, install Freeflow as a Pi package from npm:
-
-```bash
-pi install npm:@hassangameryt/freeflow
-```
-
-Or install directly from GitHub:
-
-```bash
-pi install git:github.com/hassan-mohiddin/freeflow
-```
-
-The package exposes `plugins/freeflow/skills/` and `plugins/freeflow/pi-extension/index.js`. The Pi extension registers direct Freeflow commands, keeps `/workflow` mode changes scoped to the Pi session, refreshes workflow, interview-gate, and output-router context on session start and compact, and injects that context before agent turns. Output-router context includes its safety-policy reference. The extension does not enforce policy, block tools, grant permissions, or create repo-local hooks.
-
-- [Workflow](workflow.md): modes, entry points, loops, and the compact workflow map.
-- [Skills](skills.md): shipped skills and what each one is for.
-- [Architecture](architecture.md): package layout, runtime boundary, context hooks, and progressive disclosure model.
-- [Output Router](output-router.md): compact guide to routed retrieval, command output routing, vault recovery, and config.
-- [Release evidence](release-evidence.md): current release evidence and deferred checks.
-- [ADRs](adr/README.md): durable release decisions.

package/plugins/freeflow/docs/adr/0001-three-modes.md

@@ -1,27 +0,0 @@
-# ADR 0001: Three Modes
-
-## Status
-
-Accepted.
-
-## Decision
-
-Freeflow has exactly three modes:
-
-- `conversation`
-- `workflow`
-- `strict-workflow`
-
-## Rationale
-
-Three modes give users explicit process control without creating a mode for every task shape.
-
-`conversation` removes workflow pressure for questions and discussion.
-
-`workflow` is the default for consequential work.
-
-`strict-workflow` exists for high-risk or hard-to-reverse work.
-
-## Consequences
-
-Freeflow must scale process inside these modes instead of adding new modes. Host permission modes remain separate from Freeflow workflow modes.

package/plugins/freeflow/docs/adr/0002-evals-before-hooks.md

@@ -1,17 +0,0 @@
-# ADR 0002: Evals Before Enforcement Hooks
-
-## Status
-
-Accepted.
-
-## Decision
-
-Freeflow ships plugin-bundled context-loading runtime: Codex/Claude hooks and a Pi extension that load existing workflow and interview-gate context. It still ships without enforcement hooks or CLI enforcement. Behavior must first be proven with baseline-vs-with-skill evals before mechanical enforcement is added.
-
-## Rationale
-
-Context-loading runtime addresses a measured lifecycle gap: workflow and interview-gate context may not be present at session start. The setup skill handles the same-session setup case by reading runtime context after successful verification. Enforcement hooks can prevent expensive mistakes, but early enforcement machinery can hide weak skill wording and turn the package into brittle workflow infrastructure.
-
-## Consequences
-
-Native enforcement remains future work. Enforcement hooks should be added only when a repeated failure is concrete, deterministic, and not solved by concise skill wording.