kimal3 0.5.0 → 0.6.0

package/skill/en/commands/k3course.md

@@ -1,41 +1,41 @@
----
-description: Back into the Mini course — pick up where you left off
----
-
-<!-- kimal3:erzeugt — this file is maintained by `kimal3 skill install` and
-     overwritten on every update. Your own changes will be lost; if you want
-     to keep them, copy the file under a different name. -->
-# Course
-
-> Back into the Mini course: “Where was I again?” — picks up where you left off.
-> `kimal3 course` fetches the status fresh from kimal3 — the same ticks the person sees in the browser at
-> https://app.kimal3.de/kurs.
-
-Carry out the steps in order. Stay in the coaching tone: English, friendly, one step at a
-time, the why before the how, no prior knowledge assumed.
-
-## 1. Fetch the status
-- Run `kimal3 course` (on Windows the way `SKILL.md` describes).
-- Exit code **2**: the person is not signed in. Show them `kimal3 login`, let them confirm in the browser themselves
-  and name **no** course status.
-- Exit code **3**: the status can't be fetched right now. Say so in one sentence and **do not retell the course from
-  memory**.
-- If the program doesn't know the command, it is too old: name `npm install -g kimal3@latest`, then `kimal3 skill install`.
-
-## 2. Say where you stand in one sentence
-- Say in **one** sentence where you are in the course — from the output (the `Course:` line), invent nothing. No lecture.
-
-## 3. Lead on with what comes next
-- The line `Next:` names the next step. Lead on **one** step at a time: show, let them do it, make sure they understand.
-  Never the whole list at once.
-- If it says **“(you tick it off)”** after it and the person has obviously already done the step (for example “closed
-  Claude completely and reopened it” — they are sitting in Claude right now), don't lead it again: ask briefly and
-  ask them to tick it off at https://app.kimal3.de/kurs.
-- If it says **“(Claude sets it)”** and it is open, run the setup once more — through the guide
-  `https://app.kimal3.de/setup` (load it the way the course sentence does and follow it), **not** with a freely called
-  `kimal3 setup`. If the step is still open afterwards, name the reason from the output of `setup` and don't suggest
-  a third run.
-
-## 4. Finished
-- If the output says `Course: complete`, congratulate them briefly and ask, with a suggestion, what they would like to
-  work on here. No more course talk.
+---
+description: Back into the Mini course — pick up where you left off
+---
+
+<!-- kimal3:erzeugt — this file is maintained by `kimal3 skill install` and
+     overwritten on every update. Your own changes will be lost; if you want
+     to keep them, copy the file under a different name. -->
+# Course
+
+> Back into the Mini course: “Where was I again?” — picks up where you left off.
+> `kimal3 course` fetches the status fresh from kimal3 — the same ticks the person sees in the browser at
+> https://app.kimal3.de/kurs.
+
+Carry out the steps in order. Stay in the coaching tone: English, friendly, one step at a
+time, the why before the how, no prior knowledge assumed.
+
+## 1. Fetch the status
+- Run `kimal3 course` (on Windows the way `SKILL.md` describes).
+- Exit code **2**: the person is not signed in. Show them `kimal3 login`, let them confirm in the browser themselves
+  and name **no** course status.
+- Exit code **3**: the status can't be fetched right now. Say so in one sentence and **do not retell the course from
+  memory**.
+- If the program doesn't know the command, it is too old: name `npm install -g kimal3@latest`, then `kimal3 skill install`.
+
+## 2. Say where you stand in one sentence
+- Say in **one** sentence where you are in the course — from the output (the `Course:` line), invent nothing. No lecture.
+
+## 3. Lead on with what comes next
+- The line `Next:` names the next step. Lead on **one** step at a time: show, let them do it, make sure they understand.
+  Never the whole list at once.
+- If it says **“(you tick it off)”** after it and the person has obviously already done the step (for example “closed
+  Claude completely and reopened it” — they are sitting in Claude right now), don't lead it again: ask briefly and
+  ask them to tick it off at https://app.kimal3.de/kurs.
+- If it says **“(Claude sets it)”** and it is open, run the setup once more — through the guide
+  `https://app.kimal3.de/setup` (load it the way the course sentence does and follow it), **not** with a freely called
+  `kimal3 setup`. If the step is still open afterwards, name the reason from the output of `setup` and don't suggest
+  a third run.
+
+## 4. Finished
+- If the output says `Course: complete`, congratulate them briefly and ask, with a suggestion, what they would like to
+  work on here. No more course talk.

package/skill/en/commands/k3plan.md

@@ -0,0 +1,342 @@
+---
+description: Check the specs against the code and upload the planning to the app
+---
+
+<!-- kimal3:erzeugt — this file is maintained by `kimal3 skill install` and
+     overwritten on every update. Your own changes will be lost; if you want
+     to keep them, copy the file under a different name. -->
+# Checking and uploading the planning
+
+## 1. What for
+
+You check the user stories in this project's specs against the code and upload **only the
+result** to the app — never the code. There, on the project page (tab "Planning"), the person
+sees what is open, what is waiting for their test and what is done, and gives a verdict with
+"Works" or "Doesn't work".
+
+Work through the sections in order. You need the rules (section 5) and the file format
+(section 6) from section 2 onwards — read them first. What an exit code of `kimal3` means is in
+**`~/.claude/skills/kimal3/SKILL.md`, section "Exit codes"**; this file does not repeat it.
+
+🔑 **`/k3plan` checks, sorts and uploads — it builds nothing.** Whatever needs fixing is
+attached to the story as a finding afterwards; building happens when the person says so.
+
+## 2. Fetch the responses
+
+Work in the **project folder** (where the specs and the code are). The file is always called
+`plan/stand.json`, relative to that folder.
+
+```
+kimal3 plan
+```
+
+**If you get `There's no plan/stand.json in this folder.`**, it is the first time (or you are in
+the wrong folder — check that first):
+
+1. `kimal3 project list` — look for the project this is about. If there is **no** matching one,
+   ask the person which one is meant and suggest `/k3project <what you built>`
+   (German: `/k3projekt`): without an entry in the success profile there is no project page.
+   Stop there, don't invent anything.
+2. Create `plan/stand.json` with the name **exactly as the list writes it**:
+
+   ```json
+   {
+     "format": 1,
+     "projekt": "LinkedIn Content App",
+     "projekt_id": null,
+     "basis": null,
+     "geprueft_am": "2026-10-21T22:10:00+02:00",
+     "specs": [],
+     "themen": [],
+     "uebernommen": []
+   }
+   ```
+
+   (Name and time are an example.) The field names are German and stay German. `kimal3 plan
+   upload` enters `projekt_id` and `basis` itself after the first upload — **leave them at
+   `null`**.
+3. Run `kimal3 plan` again.
+
+**What the output means** (example, made-up values):
+
+```
+#12 · doesn't work · 2026-09-23-content-planner / US-2 (round 1): When dragging, it jumps to Tuesday
+#13 · Topic: The calendar should show public holidays
+Confirmed: 2026-09-23-content-planner / US-1 (round 1)
+View: https://app.kimal3.de/projekt/…
+```
+
+- `#12 · doesn't work · <spec> / <story> (round n): <sentence>` — the person tested the story and
+  it doesn't hold. → Rule 1 in section 5. You need the number later for `uebernommen`.
+- `#13 · Topic: <sentence>` — something new they noted in the app. → Rule 3.
+- `Confirmed: …` — for these stories they said "Works" in **this** round; they are done. You
+  never need to hand on a "Works".
+- `View: …` — the link to the planning. Keep it for the report.
+- `No open responses.` — nothing to hand on; carry on with section 3.
+
+**Refusals:**
+- `No project is called "…". Your projects: … Enter the name in plan/stand.json exactly like
+  that.` — copy the matching name **word for word** from the list into `"projekt"`. If two could
+  fit, ask.
+- `Several of your projects are called "…" (ids: …).` — ask the person which one is meant and
+  enter its id as `"projekt_id"`.
+- `The project number in plan/stand.json belongs to none of your projects.` — the number comes from
+  a copied folder or a deleted project. Set `"projekt_id"` to `null` (the line stays, the field is
+  required); then kimal3 searches by name. This is the **only** case in which you change
+  `projekt_id` yourself.
+- `The plan can't be read: plan/stand.json doesn't contain a valid JSON object.` — repair the
+  brackets or commas in the file.
+
+## 3. Find the specs
+
+In the project folder, look in **`docs/superpowers/specs/`**, **`plan/`** and **`docs/specs/`**
+for Markdown files with user stories ("As … I want … so that …", often `US-1`, `US-2`, with
+acceptance criteria and a counter-check). `plan/stand.json` itself, status notes and task lists
+are not specs.
+
+One entry in `specs` per spec, one entry in `stories` per user story, one entry in `kriterien`
+per acceptance criterion (in short, at most 500 characters: starting point → action → result).
+
+🔴 **The keys are binding.** The app ties every "Works" and "Doesn't work" to spec key + story
+key + round. If a spec or story is already in `plan/stand.json`, **keep its key unchanged** — a
+renamed key makes the person's verdict disappear. New: spec key = file name without `.md`; story
+key = the number from the spec (`US-3`); if the spec doesn't number them, count `US-1`, `US-2` …
+yourself in their order.
+
+- `titel`: the heading of the spec or the story. `datei`: the path of the spec in the project
+  folder (relative, ends in `.md`; otherwise `null`). `kimal3 plan upload` reads the **text** of the spec from
+  this file and sends it along — it does not read paths outside the project folder.
+- The story key is **the same as in the heading of the spec**, where the spec numbers its stories
+  (`### US-3 · …` → `US-3`): the app finds the story in the spec text through this key.
+- A spec without stories goes in with `"stories": []`; mention it in the report.
+- Limits: at most 50 specs, 60 stories per spec, 400 altogether. If there are more, ask the
+  person which specs belong in.
+
+**The state of each story (`stand`):**
+- `offen` — nothing built yet.
+- `in_arbeit` — partly built, or a finding is open. `gebaut_am` is then `null`.
+- `gebaut` — built. `gebaut_am`: the date on which **this round** was finished (`YYYY-MM-DD`);
+  plus a `testen` sentence (section 4).
+- `weggelassen` — deliberately not built, `grund` is required (rule 8). Only if the spec or the
+  person decided so — never on your own to tidy up. If in doubt: leave it `offen` and ask in the
+  report.
+
+## 4. Check against the code
+
+Run the counter-check of each criterion **wherever you can**: the project's guards or tests
+(`npm test`, `npm run …`), a command, starting the app and calling the address, reading a file.
+
+- `bestanden` (passed) — **only** if the counter-check ran in this session and showed the
+  expected result. Never from memory, never from last time, never because the code "looks right".
+- `gescheitert` (failed) — it ran and showed something else. That is a finding (rule 1); the app
+  then puts the story and its spec under "In progress".
+- `offen` (not run) — everything that did not run: needs a browser, a sign-in, real data or a
+  person. Reading only counts if the criterion says something about the file itself (a file
+  exists, a text is there as written) — reading does not prove a behaviour.
+
+⚠️ A story with an `offen` criterion is shown under "Claude test pending", and the person can't
+test it yet. Say in the report what is missing so the counter-check can run.
+
+**The `testen` sentence** (on every `gebaut` story, at most 1000 characters) names **the address
+or the command** and **what must be visible there**, for example: "Start `npm run dev`, open
+http://localhost:3000/calendar and drag the post from Monday to Wednesday — it is then on
+Wednesday." Without it the app shows: "Claude didn't write down how to test this".
+
+**Findings** (`befunde`): only **open** ones. `quelle: "claude"` for something the story promises
+and doesn't do, and that no criterion covers. `seit`: the date the finding came up — if it is
+already in the file, it keeps its old date.
+
+**The round** (`runde`) ties a verdict to a build — like a stamp on one version of a document:
+- It starts at `1` and **never** goes down.
+- **Raise it by exactly 1** when a story with a finding from the person (`quelle: "mensch"`) has
+  been fixed since (Git history, and the counter-checks pass now): then `befunde: []`,
+  `stand: "gebaut"`, a new `gebaut_am`, a new `testen` sentence. The person tests again. If it is
+  unclear whether it was fixed: leave the finding and ask in the report.
+- **Also raise it** if you changed a **confirmed** story in a way the person would notice — their
+  old "Works" no longer applies (rule 7).
+- Otherwise **leave it alone**: a confirmed story stays done as long as its round stays the same.
+
+## 5. The eight rules
+
+The app shows them to the person in exactly this wording ("How planning stays short"):
+
+1. **A finding is not a new card.** If a story doesn't hold what it promises — Claude's check fails or you say "Doesn't work" — the finding is attached to that story and its spec goes back to "In progress".
+2. **Only what nobody promised is new. It goes into the inbox, which has five places.**
+3. **Claude sorts every topic at the next `/k3plan`:** as a new story in a spec, as a finding on a story, or dropped with a reason. There is no "later". What happened to it is shown under "Recently sorted".
+4. **Nothing stays in the inbox longer than 14 days.**
+5. **At most one spec in progress at once** ("In progress" and "Claude test pending" together). Finish it before starting the next.
+6. **At most five stories wait for your test.** If there are more, Claude starts nothing new until you have tested.
+7. **Done means checked twice:** Claude's checks passed, and you said "Works" — for exactly this version.
+8. **A spec is only closed when every story is done or deliberately left out** — with a reason. There is no silent remainder.
+
+**What you do with them:**
+
+- **Rule 1 — every `doesn't work` from `kimal3 plan`:** if the story still exists, attach the
+  person's sentence to it as a finding (`{ "text": "<their sentence>", "quelle": "mensch",
+  "seit": "<today>" }`), `stand: "in_arbeit"`, `gebaut_am: null`. If it has already been fixed
+  since, raise the round by 1 and set `befunde: []` instead (section 4). Plus in `uebernommen`:
+  `{ "rueckmeldung": 12, "antwort": "Finding on US-2" }`. If the story no longer exists, the
+  `antwort` says why. ⚠️ Without a finding from `mensch` and without a higher round, the server
+  refuses the upload.
+- **Rule 2 — something new:** what you notice while checking, or what the person says in the
+  conversation, and what **no** spec promises goes into `themen`:
+  `{ "schluessel": "T-1", "text": "…", "quelle": "claude" | "mensch", "seit": "<today>" }`.
+  The five places are shared by `themen` and the open notes from the app.
+- **Rule 3 — sort:** every `Topic` from `kimal3 plan` **and** every topic already in `themen` from
+  earlier is sorted **now** — one of three:
+  - **new story:** write it into the spec it belongs to (user story, acceptance criterion with
+    counter-check) and into `plan/stand.json` with `stand: "offen"`. If no spec fits, ask where it
+    goes. Answer: `new story US-7 in "Content planner"`.
+  - **finding on a story:** as in rule 1. Answer: `finding on US-2 in "Content planner"`.
+  - **dropped:** answer `dropped: <reason in one sentence>`, for example
+    `dropped: public holidays are already in the calendar tool.`
+
+  For a note from the app, the answer goes into `uebernommen` as **one sentence** (the app shows
+  it under "Recently sorted" as `<note> → <answer>`); so write it **without** an arrow at the
+  start. A topic from the file you take out of `themen` and name how it was sorted in the
+  report.
+- **Rule 4:** because you sort everything at every `/k3plan`, nothing stays long. A topic with
+  `seit` more than 14 days ago is sorted now **in any case**.
+- **Rules 5 and 6 — don't start a new spec** while another spec is in progress (one of its
+  stories is `in_arbeit`, has a finding or a failed counter-check, or is `gebaut` with an `offen`
+  criterion or with no criteria at all), or while more than five stories are waiting for the person's test (`gebaut`, all
+  passed, no finding, not yet confirmed). **Tell the person what to test instead** — with the
+  `testen` sentences. If you sort a topic in as a new story in a spec, you do not start that spec
+  with it: it stays `offen`, and the spec does not count as in progress.
+- **Rule 7:** only the person sets "Done", with "Works" in the app; the file has no field for it.
+  You only keep the round stable (section 4).
+- **Rule 8:** `weggelassen` only with a `grund` (section 3).
+
+## 6. The file
+
+`plan/stand.json` is under Git. Example, shortened:
+
+```json
+{
+  "format": 1,
+  "projekt": "LinkedIn Content App",
+  "projekt_id": null,
+  "basis": null,
+  "geprueft_am": "2026-10-21T22:10:00+02:00",
+  "specs": [
+    {
+      "schluessel": "2026-09-23-content-planner",
+      "titel": "Content planner as a page",
+      "datei": "plan/2026-09-23-content-planner-page-spec.md",
+      "stories": [
+        {
+          "schluessel": "US-2",
+          "titel": "Move posts in the calendar",
+          "stand": "gebaut",
+          "runde": 1,
+          "gebaut_am": "2026-10-21",
+          "kriterien": [
+            { "text": "Drag the post from Monday to Wednesday -> it is on Wednesday", "gegenprobe": "bestanden" }
+          ],
+          "befunde": [],
+          "testen": "Open /calendar and drag the post from Monday to Wednesday.",
+          "grund": null
+        }
+      ]
+    }
+  ],
+  "themen": [
+    { "schluessel": "T-1", "text": "The calendar should show public holidays", "quelle": "mensch", "seit": "2026-10-21" }
+  ],
+  "uebernommen": [
+    { "rueckmeldung": 12, "antwort": "Finding on US-2" }
+  ]
+}
+```
+
+**The fields** — every one must be there, even if it is `null` or empty; the server refuses an
+unknown field (a typo like `"befund"`):
+
+- `format`: exactly `1`.
+- `projekt`: the name as in the app, 1–200 characters.
+- `projekt_id`, `basis`: `null` at first; after that `kimal3 plan upload` writes them — **never
+  change them by hand**. Only exception: the refusal "The project number in plan/stand.json
+  belongs to none of your projects." — then set `projekt_id` to `null` (section 2).
+- `geprueft_am`: now, with time zone (`date +%Y-%m-%dT%H:%M:%S%:z` in Bash, `Get-Date -Format
+  "yyyy-MM-ddTHH:mm:sszzz"` in PowerShell).
+- `specs[]`: `schluessel` (unique, 1–80 characters), `titel` (1–200), `datei` (path or `null`),
+  `stories[]`.
+- `stories[]`: `schluessel` (unique within its spec), `titel`, `stand` (`offen` · `in_arbeit` ·
+  `gebaut` · `weggelassen`), `runde` (1–999), `gebaut_am` (`YYYY-MM-DD` for `gebaut`, otherwise
+  `null`), `kriterien[]`, `befunde[]`, `testen` (sentence or `null`), `grund` (required for
+  `weggelassen`, otherwise `null`).
+- `kriterien[]`: `{ "text", "gegenprobe": "bestanden" | "gescheitert" | "offen" }`, at most 30
+  per story.
+- `befunde[]`: `{ "text", "quelle": "claude" | "mensch", "seit": "YYYY-MM-DD" }` — open ones only,
+  at most 20.
+- `themen[]`: `{ "schluessel", "text", "quelle", "seit" }`, at most 50 (the inbox has five places,
+  rule 2).
+- `uebernommen[]`: `{ "rueckmeldung": <number from kimal3 plan>, "antwort": "<one sentence>" }`.
+  `kimal3 plan upload` empties it itself after uploading.
+- The whole file: at most 300 KB.
+
+## 7. Upload
+
+First the dry run — it checks everything and saves nothing:
+
+```
+kimal3 plan upload --dry-run
+```
+
+`Dry run: would upload 9 stories and mark 2 responses as handled. Nothing was saved.` (numbers as
+an example). **Compare the second number** with the open responses from `kimal3 plan`: if it is
+smaller, you forgot one — it would stay in the app under "Waiting for Claude".
+
+Then:
+
+```
+kimal3 plan upload
+```
+
+It worked if you see `✓ Planning for "…" uploaded: … stories, … waiting for your test.` and
+`View: …`; the first time also `projekt_id and basis are now in plan/stand.json.` The CLI has
+entered `projekt_id` and `basis` and emptied `uebernommen` — leave the file like that. Tell the
+person that `plan/stand.json` has changed and belongs in the next commit.
+
+After that comes a line `Spec texts uploaded: 1 of 3. Without text: …` — the text of the specs goes up too.
+A spec without text is a **hint, not a failure** (exit code `0`): tell the person which specs are in
+the brackets and what to do (correct the path in `datei`; over 300 KB cannot be uploaded).
+
+**Refusals — read the message, fix it, dry run, again:**
+
+| The message starts with | What you do |
+|---|---|
+| `The plan can't be read: <place> …` | Repair that place (`specs[0].stories[2].stand`) in the file. |
+| `No project is called …` · `Several of your projects are called …` · `The project number in plan/stand.json belongs to none of your projects.` | As in section 2. For the project number you may set `projekt_id` to `null` — only here. |
+| `<spec> / <story> has round 1, round 2 is already saved.` | The file is older than the saved state. Set the round to the saved value — never lower. |
+| `Response 12 doesn't exist in this project or is listed twice …` | Only numbers from `kimal3 plan`, each one once. |
+| `Response 12 ("…") is marked as handled, but US-2 has no finding from you …` | Attach the finding with `quelle: "mensch"` to the story (rule 1) — or raise the round by 1 if it has been fixed. |
+| `The app has a newer plan (uploaded …).` | Another working copy has uploaded. **Do not overwrite.** Tell the person and ask whether you should first fetch that state (Git) and check again. `kimal3 plan upload --overwrite` **only after their explicit yes.** |
+| `The planning saved in the app is damaged …` | Here too, `--overwrite` **only after their yes.** |
+| `The planning is saved, but the responses aren't marked as handled yet.` | Run `kimal3 plan upload` **unchanged** once more — that is harmless, the CLI has already entered `basis` and left `uebernommen` in place. |
+| ``The plan is saved, but the spec texts are not. Run `kimal3 plan upload` again.`` | Run `kimal3 plan upload` **unchanged** once more — the plan is already in the app, the CLI has entered `basis`. |
+| `⚠ The planning is saved, but plan/stand.json couldn't be updated. Enter it yourself: …` | Write exactly these values into the file. |
+| `… couldn't be loaded just now` / `… couldn't be saved just now` | Try once more; if it still fails, tell the person. |
+
+🔴 **`--overwrite` replaces what someone else uploaded.** Never on your own decision, not even
+when the message suggests it.
+
+## 8. Report to the person
+
+**At most five lines**, without jargon:
+
+- what was **done** (confirmed since last time),
+- what is **waiting for their test** — with the `testen` sentence, so they can start right away,
+- what was decided in the **inbox** (each topic with its answer),
+- a **warning** if rule 5 or 6 is broken: "Test … first" instead of a new story,
+- the **link** from `View: …`.
+
+Example (made-up values):
+
+```
+Done: US-1 "Create posts".
+Your test: US-2 - open /calendar and drag the post from Monday to Wednesday.
+Inbox: "The calendar should show public holidays" -> new story US-7 in "Content planner".
+Claude test pending: US-4 needs a browser I don't have here.
+Planning: https://app.kimal3.de/projekt/…
+```