@hassangameryt/freeflow 0.7.3 → 0.9.0

package/skills/verify-work/scripts/test-changes.mjs

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+// Lists every existing test file, fixture, snapshot and shared test setup file that changed, moved or was deleted
+// between a base and a head, with the changed hunks. It only lists; whether a change is justified is a judgment for
+// the agent and the user (references/test-design.md). A file that does not exist at the base is a new test, not a
+// changed one, and is not listed; --new lists those instead (added, copied, or untracked in the working tree).
+// Usage: test-changes.mjs --base <ref> [--head <ref>] [--root <repository>] [--pattern <glob>]... [--only]
+//                         [--exclude <glob>]... [--new] [--json]
+// Without --head, the head is the working tree, staged and unstaged. Exit code 0 when it lists (even nothing),
+// 2 on a usage or Git error.
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+const USAGE =
+  "Usage: test-changes.mjs --base <ref> [--head <ref>] [--root <repository>] [--pattern <glob>]... [--only] [--exclude <glob>]... [--new] [--json]";
+
+// Common layouts for JavaScript, TypeScript, Python, Go, Ruby, Java, Kotlin, C#, Swift, C and C++, PHP, Elixir and
+// Dart. Matching is case-sensitive, so capitalised folders such as Swift's Tests/ are listed separately. --pattern adds
+// to these; --only replaces them.
+const DEFAULT_PATTERNS = [
+  "**/*.{test,spec}.{js,jsx,mjs,cjs,ts,tsx,mts,cts}",
+  "**/{test,tests,__tests__,spec,e2e,Tests}/**",
+  "**/*.{Tests,UnitTests,IntegrationTests}/**",
+  "**/src/*Test/**",
+  "**/*_test.{go,dart,exs}",
+  "**/*_{test,unittest}.{c,cc,cpp,cxx}",
+  "**/*_spec.rb",
+  "**/*{Test,Tests}.{java,kt,cs,swift,php}",
+  "**/test_*.py",
+  "**/*_test.py",
+  "**/conftest.py",
+  "**/{fixtures,__fixtures__,testdata,__mocks__}/**",
+  "**/__snapshots__/**",
+  "**/*.snap",
+  "**/{jest,vitest,playwright,cypress,karma}.config.*",
+  "**/vitest.workspace.*",
+  "**/{jest.setup,setupTests,setup-tests,test-setup,vitest.setup}.*",
+  "**/*.setup.{js,mjs,cjs,ts,mts,cts}",
+  "**/.mocharc*",
+  "**/{pytest.ini,tox.ini,noxfile.py}",
+  "**/{spec_helper,rails_helper}.rb",
+  "**/.rspec",
+  "**/phpunit.xml*",
+  "**/test_helper.exs",
+];
+
+// The first matching kind wins, so a snapshot under tests/ is a snapshot and a fixture under tests/ is a fixture.
+const KINDS = [
+  ["snapshot", ["**/__snapshots__/**", "**/*.snap"]],
+  [
+    "setup",
+    [
+      "**/conftest.py",
+      "**/{jest,vitest,playwright,cypress,karma}.config.*",
+      "**/vitest.workspace.*",
+      "**/{jest.setup,setupTests,setup-tests,test-setup,vitest.setup}.*",
+      "**/.mocharc*",
+      "**/{pytest.ini,tox.ini,noxfile.py}",
+      "**/*.setup.{js,mjs,cjs,ts,mts,cts}",
+      "**/{spec_helper,rails_helper}.rb",
+      "**/.rspec",
+      "**/phpunit.xml*",
+      "**/test_helper.exs",
+    ],
+  ],
+  ["fixture", ["**/{fixtures,__fixtures__,testdata,__mocks__}/**"]],
+];
+
+const STATUS = { M: "modified", D: "deleted", R: "renamed", T: "type-changed" };
+
+function fail(message) {
+  console.error(message);
+  process.exit(2);
+}
+
+let parsed;
+try {
+  parsed = parseArgs({
+    options: {
+      base: { type: "string" },
+      head: { type: "string" },
+      root: { type: "string" },
+      pattern: { type: "string", multiple: true, default: [] },
+      only: { type: "boolean", default: false },
+      exclude: { type: "string", multiple: true, default: [] },
+      new: { type: "boolean", default: false },
+      json: { type: "boolean", default: false },
+    },
+  });
+} catch (error) {
+  fail(`${error.message}\n${USAGE}`);
+}
+const { values } = parsed;
+if (!values.base) fail(USAGE);
+if (values.only && !values.pattern.length) fail(`--only needs at least one --pattern\n${USAGE}`);
+
+// Glob to RegExp over repository-relative paths with "/" separators: "**/" is zero or more directories, "**" anything,
+// "*" anything within one segment, "?" one character, and "{a,b}" either alternative.
+function globToRegExp(glob) {
+  let source = "";
+  for (let index = 0; index < glob.length; index += 1) {
+    const char = glob[index];
+    if (char === "*" && glob[index + 1] === "*") {
+      const slash = glob[index + 2] === "/";
+      source += slash ? "(?:.*/)?" : ".*";
+      index += slash ? 2 : 1;
+    } else if (char === "*") source += "[^/]*";
+    else if (char === "?") source += "[^/]";
+    else if (char === "{") {
+      const end = glob.indexOf("}", index);
+      if (end === -1) source += "\\{";
+      else {
+        source += `(?:${glob
+          .slice(index + 1, end)
+          .split(",")
+          .map((part) => globToRegExp(part).source.slice(1, -1))
+          .join("|")})`;
+        index = end;
+      }
+    } else source += /[.+^$()|[\]\\]/.test(char) ? `\\${char}` : char;
+  }
+  return new RegExp(`^${source}$`);
+}
+const matcher = (globs) => {
+  const expressions = globs.map(globToRegExp);
+  return (path) => expressions.some((expression) => expression.test(path));
+};
+
+const patterns = values.only ? values.pattern : [...DEFAULT_PATTERNS, ...values.pattern];
+const included = matcher(patterns);
+const excluded = matcher(values.exclude);
+const kindMatchers = KINDS.map(([kind, globs]) => [kind, matcher(globs)]);
+const kindOf = (path) => kindMatchers.find(([, matches]) => matches(path))?.[0] ?? "test";
+
+const git = (cwd, args) =>
+  execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 256 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+const gitOrFail = (cwd, args, what) => {
+  try {
+    return git(cwd, args);
+  } catch (error) {
+    fail(`${what}: ${String(error.stderr || error.message).trim()}`);
+  }
+};
+
+const root = resolve(
+  gitOrFail(resolve(values.root ?? "."), ["rev-parse", "--show-toplevel"], "not inside a Git repository").trim(),
+);
+const commitOf = (ref) => {
+  try {
+    return git(root, ["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]).trim();
+  } catch {
+    fail(`no such commit: ${ref}`);
+  }
+};
+const base = { ref: values.base, commit: commitOf(values.base) };
+const head = values.head ? { ref: values.head, commit: commitOf(values.head) } : { ref: "working tree", commit: null };
+
+// Fixed flags so the user's Git configuration (colour, external diff tools, prefixes, rename limits) cannot change
+// what is listed or how hunks read.
+const DIFF = [
+  "-c",
+  "core.quotePath=false",
+  "diff",
+  "--no-color",
+  "--no-ext-diff",
+  "--no-textconv",
+  "--no-relative",
+  "-M",
+];
+const range = head.commit ? [base.commit, head.commit] : [base.commit];
+
+const fields = gitOrFail(root, [...DIFF, "--name-status", "-z", ...range], "git diff failed").split("\0");
+const changes = [];
+const added = [];
+for (let index = 0; index < fields.length - 1;) {
+  const code = fields[index][0];
+  const paths = code === "R" || code === "C" ? [fields[index + 1], fields[index + 2]] : [fields[index + 1]];
+  index += 1 + paths.length;
+  const status = STATUS[code];
+  const [path] = paths;
+  if ((code === "A" || code === "C") && included(paths.at(-1)) && !excluded(paths.at(-1))) added.push(paths.at(-1));
+  // Only files that existed at the base: added and copied files are new.
+  if (!status || !included(path) || excluded(path)) continue;
+  const diff = gitOrFail(
+    root,
+    [...DIFF, "--unified=3", "--src-prefix=a/", "--dst-prefix=b/", ...range, "--", ...paths],
+    `git diff failed for ${path}`,
+  );
+  const lines = diff.split("\n");
+  const start = lines.findIndex((line) => line.startsWith("@@") || line.startsWith("Binary files"));
+  const body = start === -1 ? [] : lines.slice(start);
+  changes.push({
+    status,
+    path,
+    ...(status === "renamed" ? { to: paths[1] } : {}),
+    kind: kindOf(path),
+    added: body.filter((line) => line.startsWith("+")).length,
+    removed: body.filter((line) => line.startsWith("-")).length,
+    binary: body[0]?.startsWith("Binary files") ?? false,
+    // A deleted file's hunks are its whole content; the path and line count say what went.
+    hunks: status === "deleted" ? null : body.join("\n").trimEnd(),
+  });
+}
+
+// New test files, for a check that each one fails on the base: committed additions, plus untracked files when the head
+// is the working tree.
+if (values.new) {
+  if (!head.commit)
+    for (const path of gitOrFail(root, ["ls-files", "-z", "--others", "--exclude-standard"], "git ls-files failed")
+      .split("\0")
+      .filter(Boolean))
+      if (included(path) && !excluded(path)) added.push(path);
+  const tests = [...new Set(added)].sort().map((path) => ({ status: "added", path, kind: kindOf(path) }));
+  if (values.json)
+    console.log(
+      JSON.stringify(
+        { command: "test-changes", mode: "new", root, base, head, patterns, exclude: values.exclude, tests },
+        null,
+        2,
+      ),
+    );
+  else if (!tests.length) console.log(`No new test, fixture, snapshot or test setup file since ${base.ref}.`);
+  else {
+    console.log(`${tests.length} new test, fixture, snapshot or test setup file(s) since ${base.ref}:`);
+    for (const each of tests) console.log(`added ${each.kind} ${each.path}`);
+  }
+} else if (values.json) {
+  console.log(
+    JSON.stringify({ command: "test-changes", root, base, head, patterns, exclude: values.exclude, changes }, null, 2),
+  );
+} else {
+  const against = `${base.ref} (${base.commit.slice(0, 12)})`;
+  const to = head.commit ? `${head.ref} (${head.commit.slice(0, 12)})` : head.ref;
+  if (!changes.length)
+    console.log(`No existing test, fixture, snapshot or test setup file changed between ${against} and ${to}.`);
+  else {
+    console.log(
+      `${changes.length} existing test, fixture, snapshot or test setup file${changes.length === 1 ? "" : "s"} changed between ${against} and ${to}:\n`,
+    );
+    for (const change of changes) {
+      const name = change.to ? `${change.path} -> ${change.to}` : change.path;
+      console.log(`${change.status} ${change.kind} ${name} (+${change.added} -${change.removed})`);
+      if (change.hunks) console.log(`${change.hunks}\n`);
+    }
+  }
+}

package/skills/write-docs/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: write-docs
+description: "Use when writing, updating or reviewing a document someone will act on: a spec, PRD, issue, requirements, API or interface contract, technical design, decision record or ADR; an implementation, remediation, migration or operations plan; a README, user guide, developer docs, subsystem doc, overview, folder README or feature file; or when a code change makes existing docs wrong, or a project has no developer docs yet. It covers where a document goes, its header and status, and the checks to run after writing it."
+---
+
+# Write Docs
+
+Write a document a reader will act on: true to its sources, no more certain than they are, and holding only what its use needs.
+
+Documents come in two kinds, with different lives:
+
+- **Specs and Plans decide work before it happens.** A Spec defines what to build or decide: a PRD, issue, requirements, technical design, API or migration contract. A Plan orders how to carry out agreed work. They are task artifacts, kept beside the task's Working Record (`specs/`, `plans/`) unless the repository keeps them elsewhere; they are drafted, accepted by the user, and left behind once the work is done. A decision record is written the same way and can outlive the task.
+- **Documentation describes software that exists:** how it works and why, for the people and agents who use or change it. It lives in the repository and stays true only if it changes with the code; its header names the code it `Covers` and the commit it was `Verified at`. A document that decides work not yet done is a Spec or a Plan, not documentation.
+
+Readers include agents. An agent that reads code sees what it does but not why; without the why, it may treat a deliberate choice as a bug, rebuild a design that was rejected for a reason, or break a rule nobody wrote down.
+
+The **Rules** below are binding; if one cannot be met, stop and say why. Everything else is **judgment**: follow its stated goal, and adapt when a different choice serves that goal better.
+
+## Routes
+
+| Situation | Read |
+| --- | --- |
+| A spec, PRD, issue, requirements, technical design, API or interface contract, or migration contract; an ordered plan for implementation, remediation, migration or operations | [spec and plan shapes](references/spec-and-plan-shapes.md) |
+| Preserving a decision and its rationale: a decision note or ADR | [spec and plan shapes: Decision Records](references/spec-and-plan-shapes.md#decision-records) |
+| Where a Spec, Plan or decision record goes, its header, status and source trail | Header, Status And Sources, below |
+| Finding a project's developer docs or proposing them; the structure of an overview, subsystem doc, folder README, feature file or live-verification guide; a new or rewritten subsystem doc or overview | [documentation shapes](references/documentation-shapes.md) |
+| After writing or revising a Spec, Plan or decision record | Run [artifact-check](scripts/artifact-check.mjs), and [plan-lint](scripts/plan-lint.mjs) for a Plan, as Specs And Plans says |
+| After writing or changing documentation, or to find the docs and feature files covering a changed file | Run the [docs check](scripts/docs-check.mjs), as Check It says |
+| A design whose open representation, identity, ownership, algorithm or failure choices could invalidate dependent work | Execute Work's [design](../execute-work/references/design.md) |
+| Direction or alternatives still open, a user-owned choice, or conflicting sources | [Discuss Work](../discuss-work/SKILL.md) |
+| Planning a fix whose cause is not supported | Execute Work's [diagnose](../execute-work/references/diagnose.md) |
+
+## Rules
+
+- A document grants no permission. Accepting a Spec or Plan is not permission to execute it, and review establishes fitness, not acceptance or authority. Writing or revising one does not trigger independent review; never label author self-review as independent review, or give a document an accepted status without its source.
+- Never add an obligation without an accepted source or a reason the stated outcome needs it. Never infer requirements from nearby code, existing tests or available machinery, invent a user-owned choice or scale, retry, recovery or extension machinery, or reduce agreed scope into an unapproved MVP, roadmap or later-version split.
+- Label proposed design as proposed. Never write an assumption, a reviewer's suggestion or your own preference as an accepted decision, or a hoped-for answer or unsettled owner choice as a planning assumption. Authorization to investigate or draft an option does not accept its undisclosed production consequences.
+- Stop the affected writing when it would silently settle a user-owned choice, as [Discuss Work](../discuss-work/SKILL.md) defines it, or a hard-to-reverse design; never settle such a choice through normative prose, an unexplained assumption or a polished placeholder. Return the concrete effect and supported alternatives to the owner through Discuss Work.
+- Never rewrite source truth to suit implementation, let available tests redefine acceptance, or rewrite a historical decision as though it always contained the new choice.
+- Check each factual claim against its source (the code, its tests, an observed run, or the accepted source) before writing it as fact; state what you could not check as unverified, or leave it out. Never claim whole-system completion from a narrow observer.
+- Documentation says what is true now. Plans, task progress and open work belong in the task's record, Spec or Plan; history appears only as a short list of major changes.
+- When your change makes a document wrong, correct it in the same change. Writing new documentation, or rewriting more than your change made wrong, needs a request or the repository's documentation rules.
+- Follow the repository's documentation rules (`AGENTS.md` or its equivalent): where documents live, which parts need the user's approval to change, and what is public.
+- Keep secrets, credentials, private task notes and personal data out of documents others can read.
+
+## Write The Document
+
+Goal: a reader with only the document and its sources can act correctly, and can tell what is required, what is fact, and what is still open.
+
+**Know the reader and the use.** Identify the document type, who reads it and for what later action, the accepted scope, the destination, and the open questions it must keep. Answer a question about a document without editing it unless revision is requested. Use Discuss Work when direction or alternatives are still materially open; do not repeat discussion that already settled the document's purpose. An agreement to implement accepted work may include documenting its supported contract; do not manufacture another approval because a document was produced.
+
+**Ground it in current sources:** current user direction and accepted discussion, including later amendments; the Specs, issues, decisions and contracts it revises or consumes; live code, tests, policy and ADRs; current primary sources when an external version or interface constrains it; and the Working Record through [Track Work](../track-work/SKILL.md) when one exists. For documentation, start from the code and its tests, then read what explains them: specs, task records, decision records, commit messages, review threads. A reason that exists only in a task record or a conversation is the one most worth writing down, because it disappears with them.
+
+A record or summary cannot override contradictory current intent or accepted source truth. Distinguish what was requested, proposed, accepted and observed, and know which accepted version or amendment the document follows; an earlier reviewed baseline does not excuse ignoring a later accepted change. An experiment produces evidence, not a requirement: carry its consequences only where they were selected for this outcome. A test can faithfully protect an unnecessary mechanism.
+
+**Write only what the use needs**, in the shape the routes above name. Give the depth the reader needs, including architecture and ownership where the use requires it; do not cut necessary detail just to shorten the document, and leave out a section with nothing true to say. Keep distinguishable: required behavior and accepted decisions; supported facts and their limits; proposed mechanisms; assumptions and open questions; deferrals and superseded direction. Use the repository's vocabulary, and put a consequential uncertainty where the reader makes the affected decision, not in a distant caveat. A limitation of one technique does not establish a need for stronger guarantees, host changes, new persistence, retries or a subsystem. Open questions need not stop unrelated content; a document can be fit for discussion while unfit to guide production, so say which. Give each fact one home and link shared rationale instead of copying it.
+
+**Self-review once before anyone relies on it.** After checking factual claims, use [Review Work](../review-work/SKILL.md) for one silent author self-review of the complete document against its use: it keeps accepted intent and amendments, separates requirements from proposals, has the evidence and acceptance conditions it needs, and keeps dependent documents coherent; for a Plan, also that the ordered work can achieve the outcome, its dependencies hold, later uncertainty is honest, final checks match acceptance, and selected checkpoints are proportionate. Correct clear defects and recheck what they affect; return an unresolved owner decision instead of inventing an answer to make the document consistent. Independent review applies only when selected and authorized to protect a concrete boundary: give the reviewer the complete document, its sources, dependencies and limits through Review Work, and adjudicate the report before revision or use. Respect a selected approval checkpoint, but do not create one for every document.
+
+## Specs And Plans
+
+A Spec describes content, behavior, constraints and uncertainty for its use; it is not an implementation sequence, a Working Record, a transcript or a permission grant. Useful technical depth is welcome; hypothetical completeness is not required. A Plan describes intended execution; the Working Record keeps actual work, evolving state and the next useful action. Keep ordered execution in a Plan and live progress in the record. After writing or revising a Plan, run [plan-lint](scripts/plan-lint.mjs) (`node <write-docs-directory>/scripts/plan-lint.mjs <plan.md>`): it lists each step that names no check.
+
+When a Working Record exists and the Spec or Plan is accepted for its task, list it under the record's `What defines this task` through Track Work, so every recovery reads it.
+
+Revise for a change in the contract or strategy, not for progress. Preserve accepted content that still holds, change only what new intent or evidence affects, update the status honestly, and keep consequential prior rationale recoverable through a change note, decision record, supersession link or version control; a change note explains current intent or keeps rejected work from being repeated, never execution status or a transcript, and a first version needs none unless repository policy requires it. When an accepted amendment or learning result changes the contract, find the affected Plan, acceptance check or implementation assumption: reconcile it when authorized, otherwise mark it contingent and return the needed revision before dependent use. Learning does not enter the contract by itself: keep findings selected for implementation apart from observations kept as evidence. Do not keep an older baseline after the user accepted a change, synchronize unrelated documents, or repair consistency by silently changing the required outcome.
+
+### Header, Status And Sources
+
+These apply to Specs, Plans and decision records; documentation uses the header in [documentation shapes](references/documentation-shapes.md#header) instead.
+
+**Destination.** A task-local Spec or Plan goes in the task folder Track Work owns (`specs/`, `plans/`). Use an established product, design, API, issue, migration, policy or architecture location instead when the document should be canonical there, and the repository's issue tracker for an issue when it is available and intended. Ask before choosing between task-local memory and canonical repository documentation when the choice changes authority, review or longevity. Do not start a new top-level docs convention for one document.
+
+**Header.** Use the repository's required metadata. Otherwise, when identity helps future readers, give a title and a compact header with only useful fields:
+
+```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
+```
+
+**Doc ID** when links, review history or supersession need one; **Type** the document's actual job, such as PRD, Issue, Technical Design, API Contract, Migration Contract, Implementation Plan or Decision; **Owner** the person or role with authority over its intent; **Source** compact pointers to accepted context and evidence; a date, or **Supersedes** / **Superseded by**, only when reliable and needed. Never invent an owner, approval, date or authority to complete a header.
+
+**Status.** Use the repository's statuses when it has them. Otherwise give one current status from this vocabulary, the same for every Spec, Plan and decision record, using only the states its life reaches:
+
+| Status | Means |
+| --- | --- |
+| `Draft` | Being written, or proposed and not yet accepted. |
+| `Reviewed` | Reviewed and not yet accepted; say whether by author self-review or selected independent review. |
+| `Accepted` | The owner accepted it; `Source` names where. |
+| `Rejected` | The owner declined it. |
+| `Superseded` | Replaced; link the replacement both ways. |
+| `Retired` | Dropped with nothing replacing it, with the date and the reason. |
+
+Writing or reviewing a document never makes it `Accepted`, and `Accepted` is not permission to execute it. Status reports the document's state; it does not replace review evidence or user authority.
+
+**Source trail.** Link stable sources that actually exist, such as `file:<path>#<section>`, `working-record:<task>/record.md#<section>`, `commit:<sha>`, `issue:<id>`, `output:<output-id>` or `session:<session-id>/turn:<turn-id>`, with concise quotations rather than copied inventories, logs, diffs or transcripts. The trail lets a later reader recover why the document says what it says, without preserving every turn: for a consequential choice, keep the proposal, its disclosed consequences and the acceptance source together rather than an isolated "proceed" or an agent's summary of approval, and keep accepted amendments apart from unselected experimental findings.
+
+Then run [artifact-check](scripts/artifact-check.mjs) (`node <write-docs-directory>/scripts/artifact-check.mjs <document.md> [--statuses <the repository's own>]`): it refuses a missing title or status, a status outside this vocabulary, an `Accepted` document with no Source, a `Superseded` one with no replacement, and a `file:` or `commit:` pointer that does not resolve.
+
+A Spec or Plan stays identifiable, source-backed and understandable without the original conversation, holding no information a Working Record, handoff or another canonical document owns.
+
+## Documentation
+
+### Choose The Document
+
+Goal: each fact lives in one place, written for the reader who needs it.
+
+| Reader | Document | Holds |
+| --- | --- | --- |
+| Someone using the software | User guide | What it does and how to use it: tasks, settings, commands, from the user's side. |
+| Someone finding their way around the code | Overview (an `ARCHITECTURE.md`, or the index of the developer docs) | The problem the software solves, its parts and how they relate, a map of where things are, and the rules that hold across parts. Short and slow to change. |
+| Someone changing one subsystem | Subsystem doc | How the subsystem works and why: its surface, state, invariants, decisions, failure behavior, code map, and tests. |
+| Someone editing files in one folder | Folder `README.md` | What each file owns, local rules, and a pointer to its subsystem doc. |
+| Someone checking a feature in the running software | Feature file, plus a shared live-verification guide | What the user sees and the exact steps that show it works. |
+| Anyone revisiting a hard-to-reverse choice | Decision record | The decision and why, in the [Decision Records](references/spec-and-plan-shapes.md#decision-records) shape. |
+
+Prefer extending an existing document to creating a new one: a small set of current documents serves readers better than many partly current ones. A subsystem earns its own doc when the reasons behind it cannot be read from the code and readers keep needing them: agents re-derive the same design, or mistake a deliberate behavior for a bug. A user guide and a subsystem doc about the same feature are different documents for different readers; link them rather than merging them.
+
+Each kind of knowledge has one home. How the code works and why, its decisions, and behavior that looks wrong but is intended: developer docs, with hard-to-reverse choices in decision records and what the user sees in feature files. Rules for agents working in the repository: its instruction files. Task progress and decisions in flight: the task's record, until settled decisions move to the docs. The user's own preferences: the host's memory.
+
+Write documentation where the repository keeps it; [documentation shapes](references/documentation-shapes.md#starting-developer-docs) says where to look, and what to propose when there is none. If the repository keeps none and you are asked to start, propose a location and confirm with the user before creating it. When a project has code and no developer docs, propose creating them and wait for the user's yes; keep that knowledge out of `AGENTS.md`, `CLAUDE.md` and other always-loaded instruction files, which every request pays for.
+
+### Write It For The Next Change
+
+Goal: a reader with only the document and the code can make a correct change, and can tell what is deliberate.
+
+- **Name, do not link to lines.** Write paths, functions, types, configuration keys, and messages exactly, in backticks, so readers and search tools find them. Line numbers go stale with the next edit.
+- **Write invariants, including absences.** "Nothing outside `config.ts` reads the config file" or "the request path never reads session files" cannot be seen by reading any one file, so state it.
+- **Say what looks wrong but is intended.** For behavior a careful reader would take for a bug, state the behavior, the reason, and what would break if it changed.
+- **Keep explanation apart from reference.** Explanation (purpose, how it works, why) is read once to understand; reference (surface, state, invariants, code map, tests) is consulted while working. Put them in separate sections so a reader looking up a fact does not wade through reasoning.
+- **Prefer present-tense facts to narrative.** "Compaction runs at the end of a turn" rather than "We changed compaction so that it now runs at the end of a turn". History gets one short section of major changes, with commits.
+
+Depth follows the reader's risk. A subsystem with many hidden reasons needs most of the shape; a small one may need only purpose, surface, and code map.
+
+### Keep It Current
+
+Goal: documentation stays true as the code changes, without anyone remembering to check.
+
+- When you finish a change, ask whether any document now says something false: a user guide, a subsystem doc, a folder README, an overview. Correct it in the same change.
+- When work settles a decision about a documented subsystem (a design choice, a rejected alternative, a limit accepted on purpose), record the decision and its reason in the subsystem doc once the work it decided is done. The task record is deleted or forgotten with the task; the doc stays.
+- Before you treat behavior in a documented subsystem as a bug, read its decisions and its list of intended behavior that looks wrong. If the behavior is listed there, changing it is a design change for the user to decide, not a fix.
+- Delete or correct documentation that is no longer true. A wrong document misleads more than a missing one.
+- After checking a document against the code, update the commit it records as verified.
+
+### Check It
+
+Run the bundled [docs check](scripts/docs-check.mjs) after writing or changing documentation:
+
+```text
+node <write-docs-directory>/scripts/docs-check.mjs <docs-file-or-directory>... [--root <repository>] [--strict] [--driven] [--json]
+node <write-docs-directory>/scripts/docs-check.mjs [<docs-file-or-directory>...] --covering <path>... [--root <repository>] [--json]
+```
+
+It reports paths a document names that do not exist and, for documents with the header, those whose covered code changed since the commit they record as verified. A change made together with the document, in the same commit or both uncommitted, counts as reviewed with it. Missing paths are errors (exit code 1). Changed code is a warning, since many changes leave a document true; `--strict` makes it an error. Read the changes it lists and update the document or its verified commit. `--driven` counts a change made together with the document too: use it for feature files, whose verified commit is the last live drive, so editing the text does not count as driving it.
+
+`--covering` instead lists the documents that cover each path and whether each is current: the ones a change should reread or update.
+
+A passing check shows that the named paths exist; it does not prove every claim is current. A new or substantially rewritten subsystem doc or overview also gets the reader test in [documentation shapes](references/documentation-shapes.md#test-it-on-a-new-reader). Report what was checked.
+
+## Stop
+
+Report the document's path, type and intended use, its source basis, what is unresolved, contingent or unverified, and what was checked. For a Spec or Plan, also report a Plan's invalidation conditions and selected checkpoints, and the actual review, acceptance and execution-authority status.
+
+Stop when the document is fit for its use, or its blocking decision or evidence limit is explicit; for documentation, when it says only what is true now, each claim is checked or marked unverified, and the docs check passes. Then return to the activity that asked for it: if the agreement covers implementation, continue through the normal route; if it asks for a Plan first, stop there. Do not begin work outside that agreement or call an unresolved strategy ready.
+
+Stop and ask when where a document lives, who may change it, or whether a disputed behavior is intended cannot be settled from the code, its tests and its sources.

package/skills/write-docs/references/documentation-shapes.md

@@ -0,0 +1,184 @@
+# Documentation Shapes
+
+This reference is judgment except for the header: these are shapes to adapt, not mandatory templates. Where the repository already has documentation conventions, follow them and borrow from these shapes only what they lack. Use the sections a document's readers need, in the order that serves them, and leave out a section with nothing true to say.
+
+The header is binding when you use it, because the [docs check](../scripts/docs-check.mjs) reads it. Use it on a document whose code the check should watch for staleness.
+
+## Starting Developer Docs
+
+First look for the project's own docs index, in this order: `dev-docs/README.md`, `ARCHITECTURE.md`, a `README.md` in `docs/`, then a docs folder the root `README.md` names. The first one found is the index. A project that has one keeps its home and its conventions: map these shapes onto what is there, never start a second tree, and never move existing docs without the user's yes.
+
+Only when the project has no developer docs, propose this layout:
+
+```text
+dev-docs/
+  README.md      overview: purpose, parts, code map, rules across the code, review rules, index of docs
+  subsystems/    how each part works and why
+  features/      what the user sees, and how to drive it live
+  guides/        recurring maintainer jobs, such as a release or live verification
+  adr/           hard-to-reverse decisions
+```
+
+Grow it on demand: start with `README.md` alone, and add a folder when its first document is needed. A small project may never need more than the overview and `features/`. The proposal names what the first change writes (the overview only, from the code), roughly what it costs, and what it gains.
+
+## Header
+
+An overview, a subsystem doc, a feature file, and a live-verification guide start with a title and a header block:
+
+```markdown
+# Compaction
+
+> **Covers:** `pi-extension/src/compaction/`, `pi-extension/src/index.ts`
+> **Tests:** `pi-extension/tests/compaction/`
+> **Verified at:** `9078dd0` (2026-10-03)
+> **User docs:** `plugin-docs/capabilities/compaction.md`
+```
+
+- **Covers:** the files and directories the document describes, as repository-relative paths in backticks, separated by commas. The check reports a document as possibly stale when any of them changes after the verified commit, unless the document changed in the same commit.
+- **Tests:** the tests that prove the document's claims, in the same form. Optional.
+- **Verified at:** the commit the document was last checked against, in backticks, with the date. Update it only after checking the document against the code at that commit.
+- **User docs:** the user guide for the same feature, when one exists. Optional.
+
+Under the header, one or two sentences say who the document is for and what it lets them do.
+
+## Subsystem Doc
+
+The first part explains; the second is reference to consult while working. The sections below are the full set for a subsystem with many hidden reasons; most need fewer.
+
+```markdown
+## Purpose
+## Vocabulary
+## How It Works
+## Decisions
+## Intended Behavior That Looks Wrong
+## Surface
+## State
+## Invariants
+## Failure Behavior
+## Cost
+## Code Map
+## Tests
+## Limits
+## Changes
+```
+
+- **Purpose:** the problem it solves, what it does, and what it deliberately does not do.
+- **Vocabulary:** the terms a reader needs, each mapped to its name in the code.
+- **How It Works:** the model in prose, then its lifecycle: which events or calls drive it, in order, and what each step does. A sequence or diagram helps when several parts take turns.
+- **Decisions:** one entry per choice a reader could reasonably question: the decision, the reason, the alternative rejected and why, and the source (decision record, commit, issue).
+- **Intended Behavior That Looks Wrong:** behavior a careful reader would take for a bug. For each: the behavior, why it is intended, and what would break if it changed.
+- **Surface:** everything outside the subsystem touches: configuration keys with defaults, commands, tools or APIs, events, messages shown to users or models.
+- **State:** what is stored and where (file, entry type, schema), what lives only in memory, and how state is rebuilt after a restart, reload, or other loss.
+- **Invariants:** what must always hold, including absences. Name the test that guards each one, or say that none does.
+- **Failure Behavior:** what happens when each dependency or step fails, and what the user or caller sees.
+- **Cost:** the performance, caching, or resource rules the subsystem follows, and any measured numbers with their date.
+- **Code Map:** one line per directory or important file: what it owns, and its key types or functions by name. Point to folder READMEs for per-file detail rather than repeating it.
+- **Tests:** each test file or group and what it proves.
+- **Limits:** known limits and open questions, as facts about the present, not plans.
+- **Changes:** major changes in a few lines each, newest first, with commits. Not a changelog of every edit.
+
+## Overview
+
+One short document for the whole codebase, revised when its structure changes rather than with every edit.
+
+```markdown
+## Purpose
+## The Parts
+## Code Map
+## Rules Across The Code
+## Cross-Cutting Concerns
+## Subsystem Docs
+```
+
+- **Purpose:** the problem the software solves, in a paragraph.
+- **The Parts:** the major parts, how data and control flow between them, and the boundaries between layers.
+- **Code Map:** one entry per top-level area: a sentence or three on what it does, its key types by name, and any boundary or invariant it keeps. A map of the country, not an atlas of its states.
+- **Rules Across The Code:** invariants that span parts, especially absences, such as which layer never depends on which.
+- **Cross-Cutting Concerns:** how errors, configuration, testing, performance, and security work across parts.
+- **Subsystem Docs:** a list linking each subsystem doc with one line on what it covers.
+
+## Folder README
+
+A folder README orients someone about to edit files in that folder.
+
+```markdown
+# <Folder name>
+
+<One sentence: what this folder is.> How it works and why: `<path to subsystem doc>`.
+
+| File | Owns |
+|---|---|
+| `file.ts` | <what it is responsible for, in one or two sentences> |
+
+## Rules
+
+- <A rule that holds for code in this folder.>
+
+Tests: `<path to the folder's tests>`.
+```
+
+Keep it to what someone editing the folder needs first. Explanation belongs in the subsystem doc it points to.
+
+## Feature File
+
+Subsystem docs describe the software the way the code is built; a feature map describes it the way a user meets it, with the exact steps that show each feature working in the running software. Features cut across subsystems, so the map is its own folder beside them (`features/` in the developer docs): a `README.md` index and one file per user-facing feature. Software with nothing to run, such as a pure library, has no feature map; its tests are the live check.
+
+A feature file uses the header. **Covers** names the code behind what the user sees, so the docs check flags the steps when that code changes. **Verified at** is the commit at which every step not marked unverified was last driven, not only read. Then:
+
+```markdown
+# <Feature name>
+
+<One paragraph: what the user sees and does.>
+
+## Sub-features
+## How to get to it (user POV)
+## Driving it
+## Gotchas
+```
+
+- **Sub-features:** one line each, led by a short ID (`settings-open`) that evidence names reuse.
+- **How to get to it (user POV):** every entry point a user has: a command, a key, a menu, a URL.
+- **Driving it:** `Preconditions:` first, then one labeled bullet per user action, with the exact command and the observable result, including side effects such as files written. Mark a step that calls a paid service, such as a model, and say what it needs before it runs.
+- **Gotchas:** traps that waste or invalidate a run, entry points not driven yet, and steps left unverified, with the reason.
+
+Name only user paths, stable handles, required state, commands, and observable results; a source path appears only when it is the only stable handle. Link the subsystem docs the feature touches. A step that could not be driven stays marked unverified. A product bug the steps expose is reported to the user, never written into the steps as expected behavior.
+
+The index `README.md` holds what every file shares: baseline preconditions, driving conventions, how proof and skipped steps are reported, and one line per feature file.
+
+## Live-Verification Guide
+
+One guide shared by every feature file (for example `guides/verify-live.md` in the developer docs), with the helper script it documents kept in the repository. It uses the header, covering the helper.
+
+```markdown
+## Launch
+## Health Check
+## Drive
+## Evidence
+## Clean Up
+## Paid Calls
+```
+
+- **Launch:** the exact command that starts an isolated instance from empty state, and the signal that it is usable, not merely running.
+- **Health Check:** one read-only command that says whether this instance is worth driving: it is the one the run started, on the right build, with isolated state. Run it before the first step and after anything surprising.
+- **Drive:** the helper's commands and the stable handles they rely on (prompts, labels, on-screen text), not coordinates or tab order.
+- **Evidence:** what each step saves and where (an ignored folder), and the proof standards: drive the real user path, capture the action and the resulting state, and check side effects from a second view.
+- **Clean Up:** stop only what the run started, never by process name; remove scratch state; keep the evidence.
+- **Paid Calls:** which inputs call a model or another paid service, the guard that refuses them by default, and what a step needs before it may run one, such as a pinned cheap model and the user's yes.
+
+## Adapting To The Software
+
+Shape the sections around what readers of this software need to know before changing it. For example:
+
+- **A library:** the surface is its public API, so Surface becomes the API reference or points to the generated one; add compatibility promises and how versions change.
+- **A service:** add how it is deployed, configured per environment, observed, and recovered; operational steps are how-to content, so keep them in a separate runbook the doc links.
+- **A command-line tool:** the surface is its commands, flags, exit codes, and output formats.
+- **A data pipeline:** add data shapes at each stage, ordering and idempotency guarantees, and what reprocessing does.
+- **A small module:** purpose, surface, and a few invariants may be the whole document, or a folder README may be enough.
+
+## Test It On A New Reader
+
+For a new subsystem doc or overview, or one you substantially rewrote, test it on a reader without your context. Write five to ten questions a newcomer would ask: where is the code that does X, why does it do Y, is Z a bug, what breaks if W changes, which test proves V. Give a fresh agent only the document and the questions (a subagent where the host has one; otherwise ask the user to run it in a new session). Compare each answer with the code. Where an answer is wrong or unsure, fix the document and ask again. The test passes when the answers are right without new gaps; it shows the reader understood the document, not that every claim is current.
+
+## User Guide
+
+A user guide is task-oriented: what the user can do, the settings and commands involved, and what they will see. Keep internals out unless the user must understand them to use the feature correctly, and link the subsystem doc for readers who want more.