@newt-kit/plan 0.0.0-stage → 0.10.0

package/skills/newt-plan/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: newt-plan
+description: Use to plan a feature (a user story) of a newt application before writing it - split into steps, each a commit that leaves the application working - as a plan checked against the code and newt's rules and drawn as a page. Also when asked to "plan", "draw" or "map" what a story does to the application's modules, use cases and events.
+---
+
+# Planning a story with @newt-kit/plan
+
+What you write is the plan, a JSON file, and only what the story changes. The map (the
+application as its code is) is read by `newt map`, never written. The page is always the
+same: `newt map --plan` fills it. You never write or edit its HTML.
+
+## 1. The story and where the plan goes
+
+- The story comes as a file's path or as text. Read it whole.
+- The plan's path is the person's: if they did not say it (`--out` or in words), ask
+  where to save it before writing anything. Never pick it yourself.
+- Write the plan's words (title, whys, steps, rules) in the person's language, and set
+  `"language"` to it (`en` or `es`; any other, `en`).
+
+## 2. Read what is there
+
+```sh
+bunx newt map --json > /tmp/map.json      # in the application's folder (--tsconfig if not ./tsconfig.json)
+```
+
+Read the modules the story touches (`*.module.ts`, `*.workers.ts`, `*.deps.ts`) and newt's
+rules (`node_modules/@newt-kit/newt/AGENTS.md`): a plan that breaks them is wrong. Say the
+map's warnings to the person if they matter to the story.
+
+## 3. Write the plan, in steps
+
+Split the story into steps the person could merge one by one: each a commit that compiles,
+passes its tests and leaves the application working; the whole story is one branch and
+one pull request. Few steps (2 to 6), each small, the first the smallest that works.
+
+```jsonc
+{
+  "version": 1,
+  "language": "es",
+  "title": "Abonar la factura de un pedido cancelado",
+  "subtitle": "Historia 12",                       // optional
+  "contexts": [],                                  // { "name", "status": "new" | "removed" }
+  "modules": [                                     // new or removed ("status"); without status, only a why
+    { "id": "sales/order", "why": "Su evento cancelled dispara el abono. No cambia." }
+  ],
+  "pieces": [                                      // use cases, events, schedules: new, modified, removed
+    { "id": "billing/invoice.creditFor", "kind": "useCase", "status": "new", "why": "…" },
+    { "id": "billing/invoice.credited", "kind": "event", "status": "new" },
+    { "id": "billing/invoice.nightly", "kind": "schedule", "status": "new", "cron": "0 3 * * *" }
+  ],
+  "relations": [                                   // new or removed
+    { "kind": "emits", "from": "billing/invoice.creditFor", "to": "billing/invoice.credited", "status": "new" },
+    { "kind": "triggers", "from": "sales/order.cancelled", "to": "billing/invoice.creditFor", "status": "new" },
+    { "kind": "calls", "from": "billing/invoice.creditFor", "to": "ports/mailer.send", "status": "new" }
+  ],
+  "steps": [                                       // each a commit; a piece in braces is drawn as itself
+    { "title": "La factura se abona", "text": "{billing/invoice.creditFor} la abona y emite {billing/invoice.credited}." },
+    { "title": "Al cancelar un pedido, se abona", "text": "{sales/order.cancelled} dispara {billing/invoice.creditFor}." }
+  ],
+  "rules": [ { "ok": true, "text": "creditFor dos veces no abona dos veces." } ]   // checked by hand
+}
+```
+
+- Ids are the map's: a module `<context>/<module>`, a piece `<context>/<module>.<name>`; an
+  event is its class's `eventName` (`invoice.credited`); a port is `ports/<field>.<method>`.
+- `emits`: a use case to an event of its own module. `triggers`: an event or a schedule to
+  a use case (a worker). `calls`: a use case to another module's use case, or a port's.
+- A step's pieces are those it names in braces (or its `focus`); a review finds the step
+  done when they, and the relations between them, are in the code.
+- What touches a change but stays (an event it listens to, a use case it calls) is found,
+  not written. An existing use case that starts to emit or call is modified on its own.
+
+## 4. Check it, until it fits
+
+```sh
+bunx newt map --plan <plan.json> --out <page.html>
+```
+
+It exits with 1 for what the plan contradicts (a piece the code has not, a new one it
+has, an event another module's use case emits…). Then it prints the rules: `!` is
+something to change in the plan, or to tell the person why it stays.
+
+## 5. The page, and its comments
+
+Publish the page the command wrote exactly as it is, as an artifact with the `downloads`
+capability (`capabilities: { downloads: true }`): its "Guardar plan" button saves the plan. Watch its comments: for each, change the plan (never
+the page), check it again (step 4) and publish the new page to the same URL. Say in a
+line what changed.

package/skills/newt-review/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: newt-review
+description: Use to review a branch of a newt application - what it adds, changes and takes away of modules, use cases, events and schedules, drawn as a page - and, with the story's plan, whether each step is done. Also when asked to check a pull request against its plan.
+---
+
+# Reviewing a branch with @newt-kit/plan
+
+`newt review` reads the code on disk and the code of a base (a branch, a tag), draws what
+changed, checks newt's rules on it and, with a plan, holds the branch against it: each
+thing done (✓), missing (✗), different (≠) or not planned (+), and each step done, half
+done or not started, by what is in the code, not by the commits.
+
+```sh
+bunx newt review --base main --out review.html                       # what the branch changes
+bunx newt review --base main --plan <plan.json> --out review.html    # held against its plan
+bunx newt review --base origin/main --plan <plan.json> --format markdown   # for the pull request
+```
+
+- It exits with 1 when something is missing, different or not planned; `--warn-only` says it
+  and exits with 0. In CI, fetch the base (`fetch-depth: 0`).
+- The plan's path is the person's: ask for it if they did not say it, never guess it.
+- Publish the page as it is, as an artifact. It has a "Cargar plan" button: whoever opens it
+  can load a plan and see the branch held against it, with no command line.
+- Read what it says to the person in a few lines: the steps' state, what is missing, what
+  was not planned and the rules marked `!`. Do not change code unless they ask.