k0-board 0.3.0 → 0.5.0

package/.claude/skills/k0-plan/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: k0-plan
+description: Plans one k0 story in plan mode, with the decisions already taken written into the plan as constraints the plan has to satisfy out loud, then stores the approved plan on the story and moves it to Planned. Use this skill when the user types "/k0-plan" or "/k0-plan K42", or says "plan this story", "let's plan K42", "make the plan before we start", "pianifica questa storia", "facciamo il piano di K42", "prepara il piano". Do not use it to discuss a story that has never been discussed (that is /k0-discuss), to break a story into tasks (/k0-split), or to write any code: this skill plans and never edits a file.
+---
+
+# /k0-plan [key]
+
+A plan that quietly contradicts what was already decided is the failure this whole feature
+exists to prevent. So the plan carries the decisions in it, in writing, and every step says
+which one it serves.
+
+`[key]` is a story key such as `K42`. With no argument, the story is the one this session is
+attached to.
+
+## 1. Find the story, and read it
+
+```bash
+PORT="${K0_PORT:-4319}"
+REPO="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"; REPO="${REPO%/.git}"
+[ -d "$REPO" ] || REPO="$(git rev-parse --show-toplevel 2>/dev/null)"
+curl -sS --max-time 30 --get --data-urlencode "repo=$REPO" \
+  "http://127.0.0.1:$PORT/api/backlog" -o "$SCRATCH/k0-backlog.json"
+```
+
+`127.0.0.1`, not `k0.localhost`: browsers resolve that name by themselves, `curl` does not.
+`--get --data-urlencode`, not `?repo=$REPO`: a repository path with a space in it makes `curl`
+refuse the address outright, and one with a `#` in it quietly sends half.
+`$SCRATCH` is the session's scratch directory; nothing is written outside it. `REPO` is the
+repository the stories are filed under — the main one, even when this session sits in a
+subdirectory of it or inside a worktree, which is why it is not `$PWD`.
+
+- `curl` cannot connect → the k0 server is not running. Say so (`k0-board start`, or the tray
+  icon → *Restart*) and **stop**.
+- `{"enabled": false}` → say in one line that the k0 backlog is switched off and **stop**.
+- `REPO` empty → this is not a git repository. Ask once which repository this belongs to and
+  take the path he gives.
+- **A listing with no stories in it** → say that plainly. It means this repository has nothing
+  on the board, not that you failed to find the story; do not fall back to asking the user for a
+  key, a state or a plan the board would have given you.
+
+With a key, take that story. With no key, take the story whose `session` is alive in this
+repository; if more than one is, that is the only thing worth asking about — ask which.
+
+```bash
+curl -sS --max-time 30 "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" -o "$SCRATCH/k0-story.json"
+```
+
+`$STORY_ID` is the `id` of the story you just matched, not its key. That file holds the body, the
+rounds, the decisions, the checks, any plan already stored and the log. Everything else — the
+epic, the dependencies, what is blocked — is in the first call. Do not ask the user
+for any of it, and do not work it out yourself.
+
+- **No decisions at all** → the story was never discussed. Say so, offer `/k0-discuss`, and go on
+  only if the user tells you to plan it as it stands.
+- **A plan already stored** → say it exists, in one line say what it plans, and ask whether to
+  replace it. A new plan overwrites the old one.
+- **A dependency that is not Done** → say which, before planning. The user decides whether to
+  carry on.
+
+## 2. Plan mode
+
+Enter plan mode and stay in it. Read the code, follow the story, ask what you must — nothing on
+disk changes until the plan is approved, and this skill never changes anything on disk at all.
+
+For questions, `AskUserQuestion`, and the rules that govern them are the ones in
+`../k0-discuss/references/rounds.md` — how many rounds and how to say the count, when to stop,
+how to ask, and what never to ask. The path is relative to the folder this skill was loaded from;
+the two skills are siblings wherever k0 is installed. Read that file; it is not restated here,
+and if you cannot find it, say so and **stop**. Planning is usually two or three rounds, not
+eight: most of the unknowns were closed by the discussion.
+
+**Keep the planning on tasks.** The task tools work in plan mode, so before the first question
+create one task per phase — reading the story, the rounds of questions, writing the constraints
+and the plan, storing it once approved (§4) — and move each one to `in_progress` when it starts
+and `completed` when it is over. They are how somebody glancing at this terminal sees where the
+planning has got to. If `TaskCreate` is not among your tools, say so in one line and carry on;
+never call it again to see whether it has come back.
+
+## 3. The constraints go in the plan, in writing
+
+The plan opens with two blocks, above anything technical:
+
+```markdown
+## What you get
+<one or two sentences, in the user's language: what is different once this is done>
+
+## Constraints — already decided
+- **D1** <the decision, word for word as it is recorded>
+- **K7·D3** <one inherited from the epic, under the label the story shows it with>
+```
+
+Then the plan itself. Rules that make it worth reading:
+
+- **Every decision that is still standing appears.** Copy the sentence as recorded, in the
+  language it was written in; do not summarise it, do not translate it, do not tidy it up.
+- **Use each decision's `label`, exactly as the story gives it.** The list is the effective set:
+  the story's own, labelled `D1`, `D2`, and its epic's, labelled `K7·D3` — decided before this
+  story existed and binding on every story under that epic. The epic's key in front is what says
+  so, and it matters because the story usually has a `D3` of its own that says something else. A
+  plan with two lines both called `D3` is a plan whose constraints cannot be checked, and
+  `/k0-verify` will name them the other way round.
+- **Leave out the superseded ones.** A decision with `superseded_by` set lost; the one that beat
+  it is already in the list.
+- **Every step of the plan names the decisions it serves** — by label, `(D2, K7·D3)` at the end of
+  the line. A step that serves none is either scaffolding or something nobody asked for; say which.
+- **A decision the plan cannot satisfy stops the plan.** Do not plan around it and do not
+  reinterpret it. Put it in front of the user, say what it collides with, say which you think
+  should win and why, and wait — the collision rules are §4 of `rounds.md`.
+- The rest of the plan is a plan: what gets touched, in what order, what could go wrong. Keep it
+  short enough to be read in one sitting.
+- **Write the steps so each one can be a task.** `/k0-work` opens with one task per step of the
+  stored plan, so a step is one thing somebody could say is finished — not a paragraph holding
+  three.
+
+Anything settled while planning is a **new decision**, written the moment it is settled, in the
+user's language, one sentence about behaviour and not implementation (§5 of `rounds.md`):
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/decision" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-decision.json"   # {"text": "…", "source": "plan"}
+```
+
+## 4. When the user approves it
+
+Two calls, in this order:
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/plan" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-plan.json"        # {"text": "<the whole plan>"}
+
+curl -sS --max-time 30 -X PATCH "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" \
+  -H 'content-type: application/json' -d '{"state": "Planned"}'
+```
+
+Store the plan **as it was approved**, in the user's language, the constraints block included —
+it is what `/k0-work` reads and what `/k0-verify` holds the finished work up against. Write the
+JSON to a file under `$SCRATCH` and send it with `-d @file`: a plan pasted inline dies on its
+first quote or newline.
+
+Then one more call, **only if the story has no checklist yet**. Write one from the plan — a
+handful of lines, each something the user could look at and tell whether it is true:
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/check" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-checks.json"      # {"items": [{"text": "…"}]}
+```
+
+**Leave a checklist that already exists alone.** This call replaces the whole list, so on a story
+that already has one it does not add lines, it destroys the ones somebody wrote by hand. When
+there is already a checklist, this third call does not happen at all.
+
+## 5. Close
+
+Two lines: the story is `Planned`, and `/k0-work` is what does it. Do not start the work, do not
+open a worktree, do not touch a file. That is the next skill's job, and the separation is the
+point: a plan that begins implementing itself was never a plan.

package/.claude/skills/k0-split/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: k0-split
+description: Breaks a k0 story that will not close — too big, or open for weeks — into tasks that inherit the parent's decisions and context, so nothing has to be explained a second time. Reads what the story already holds, says plainly what it based the split on, proposes the tasks and creates them under the parent once the user agrees. Use this skill when the user types "/k0-split", or says "split K42", "this story is too big", "it has been open for weeks", "break it into pieces", "spezza K42", "questa storia è troppo grande", "dividila in task", "non si chiude mai". Do not use it to create unrelated stories (that is /k0-story), to discuss a story that is merely vague (/k0-discuss), or to decide what to work on next (/k0-next).
+---
+
+# /k0-split [key]
+
+A story that has been in `Working` for three weeks is not a story any more. This cuts it into
+tasks that live under it, each one small enough to finish, and each one carrying the decisions
+that already apply to it — so the first thing a task does is not re-explain the story.
+
+`[key]` is `K42`, or nothing — with nothing, work out which story from what the user just said.
+
+## Procedure
+
+1. **Find the story, and check the feature is on.**
+
+   ```bash
+   PORT="${K0_PORT:-4319}"
+   REPO="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"; REPO="${REPO%/.git}"
+   [ -d "$REPO" ] || REPO="$(git rev-parse --show-toplevel 2>/dev/null)"
+   curl -sS --max-time 30 --get --data-urlencode "repo=$REPO" \
+     "http://127.0.0.1:$PORT/api/backlog" -o "$SCRATCH/k0-backlog.json"
+   ```
+
+   `127.0.0.1`, not `k0.localhost`: `curl` does not resolve that name. `--get --data-urlencode`,
+   not `?repo=$REPO`: a repository path with a space in it makes `curl` refuse the address
+   outright, and one with a `#` in it quietly sends half. `$SCRATCH` is the session's
+   scratch directory; nothing is written outside it. `REPO` is the repository the stories are
+   filed under — the main one, even when this session sits in a subdirectory of it or inside a
+   worktree, which is why it is not `$PWD`.
+
+   - `curl` cannot connect → the server is not running. Say so (`k0-board start`, or the tray
+     icon → *Restart*) and **stop**.
+   - `{"enabled": false}` → say in one line that the backlog is switched off in k0's settings and
+     **stop**.
+   - `REPO` empty → this is not a git repository. Ask once which repository this belongs to.
+   - A listing with no stories in it → say so and stop; there is nothing here to split.
+
+   Match the key the user gave, or the title he described. If two stories match, ask which one.
+   A story that already has tasks can still be split further; a task itself cannot be split
+   again. If the user points at one, say so and offer its parent instead.
+
+2. **Read everything the story holds.**
+
+   ```bash
+   curl -sS --max-time 30 "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" -o "$SCRATCH/k0-story.json"
+   ```
+
+   `$STORY_ID` is the `id` of the story you matched in step 1, not its key — which is why this
+   call comes after that one and not beside it. Rounds, decisions, plan, checks, log.
+
+3. **Say what you are splitting on, before you propose anything.** Four lines at most, and every
+   one of them a fact from the two files you just read — not an impression:
+
+   > K42 · Fix the invoicing API — `Working` since 12 August, 9 decisions, 2 of them superseded,
+   > a plan from 20 August, and a log whose last entry says the export is done and the retries
+   > are not.
+
+   If there are no decisions and no plan, say that too: *the split is based on the story's Why
+   and its log, nothing else has been recorded.* The user needs to know how thin the ground is
+   before he agrees to stand on it.
+
+4. **Propose the tasks.** Two to five. More than five and you are not splitting the story, you
+   are rewriting the epic — say that instead and stop. For each one:
+
+   - a title of a handful of words, in his language;
+   - one line saying what it finishes — a piece that can reach `Done` on its own;
+   - **the decisions it inherits, by label**: `D1, D4, D7`. A superseded decision is never
+     inherited; the one that superseded it is.
+
+   Only the story's **own** decisions are shared out this way — the ones whose `owner` is
+   `story`. The epic's, labelled `K7·D3`, go to every task automatically because every task
+   carries the parent's `epic_key`: do not list them here and do not divide them up. Say in one
+   line that they carry over, and leave them alone.
+
+   Every decision of the story's own that is still standing must land on at least one task. If one
+   lands on none, either you missed a task or the decision was about something already finished:
+   say which, out loud, rather than letting it fall on the floor.
+
+5. **Ask once.** `AskUserQuestion`, under the rules in §3 of
+   `../k0-discuss/references/rounds.md` — the path is relative to the folder this skill was
+   loaded from, and the two skills are siblings wherever k0 is installed. Read that file rather
+   than working from memory, and if you cannot find it, say so and **stop**. Ask whether the cut
+   is right, with the alternative cuts you considered as the other options. If the answer opens
+   genuine unknowns, run rounds on them the way that file describes — do not invent your own
+   rules. Usually one question is enough.
+
+6. **Create the tasks.** One `POST` each, `parent_key` set to the parent's key, `epic_key` and
+   `lang` copied from the parent:
+
+   ```bash
+   curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story" \
+     -H 'content-type: application/json' -d @"$SCRATCH/k0-task-1.json"
+   ```
+
+   `body` is the context the task inherits, in the user's language: why the parent exists,
+   condensed to what this task needs, and the sentence that says which slice it owns. It is
+   written so that somebody opening the task alone, six weeks from now, does not have to open
+   the parent to understand it.
+
+   Then copy each of the **parent's own** decisions that this task inherits onto it, **verbatim**,
+   one call each. Never an epic decision: the task already has those, through `epic_key`, as the
+   same rows the parent has. Copying one makes a second row saying the same sentence, and the day
+   the user reverses it on the epic only the epic's changes — `/k0-verify` goes on checking the
+   task against a rule he took back. A decision copied is a decision that forks.
+
+   ```bash
+   curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$TASK_ID/decision" \
+     -H 'content-type: application/json' -d @"$SCRATCH/k0-decision.json" \
+     -o "$SCRATCH/k0-new-decision.json"
+   ```
+
+   Copied verbatim means copied: same sentence, same language, same wording. Rewording an
+   inherited decision to fit the task is how a decision quietly changes meaning, and `/k0-verify`
+   would then be checking the work against something the user never said.
+
+   **Numbering starts again at 1 on the task, so write down where each one came from.** The
+   parent's `D4` may well be the task's `D2`, and the user approved a list that said `D1, D4, D7`.
+   Each `POST` answers with the new decision's `n`: put the correspondence at the end of the
+   task's `body`, one line, in his language —
+
+   > Decisions inherited from K42: D1 here is K42's D1, D2 is K42's D4, D3 is K42's D7.
+
+   — and repeat it in the parent's log in step 8. Without it, `/k0-verify` reports on `D1, D2, D3`
+   and the man reviewing his own decisions has nothing to tie them back to.
+
+7. **Order them if the order matters.** When one task genuinely cannot start before another
+   finishes, record it and say so in the same breath:
+
+   ```bash
+   curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/dependency" \
+     -H 'content-type: application/json' -d '{"story_id": 91, "depends_on": 90}'
+   ```
+
+   A dependency is a note, not a lock: it marks the task and never stops anybody starting it.
+   Do not invent an order to look tidy — two tasks that could be done in either order get no
+   dependency.
+
+8. **Write the split into the parent's log**, one line, in his language, then say what you did.
+
+   ```bash
+   curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/log" \
+     -H 'content-type: application/json' -d @"$SCRATCH/k0-log.json"
+   ```
+
+   The account is short: the keys and titles of the tasks that were born, and which of the
+   parent's decisions each one carries, by the parent's numbers. Then stop. Do not start working
+   on the first one.
+
+## Rules
+
+- **The parent survives.** It is not deleted, its decisions are not moved, its state is not
+  changed, and its rounds stay where they are. It becomes the place the tasks came from, and it
+  closes when they are done — by the user pressing `Done`, as always.
+- **A copied decision lives in two places, and both have to move together.** That is the cost of
+  the copy, and it is why only the parent's own decisions are ever copied: when one is later
+  reversed, the copy on the task is superseded too — §4 of `rounds.md` says how. An epic's
+  decision is never copied and so never has this problem: it is one row, reversed once.
+- **Nothing is decided that was not decided.** A split redistributes what is already recorded.
+  If a task needs an answer nobody has given, it is an open question you name in step 4, not a
+  decision you write on the user's behalf.
+- **Say what you based it on, always.** Step 3 is not a courtesy. A split proposed without
+  showing its ground is a guess wearing a plan's clothes, and the user has no way to tell.
+- **Talk in the language the user speaks, and store what he says in that language.**
+- **Never ask what the API can tell you** — the state, the age, the decisions, the plan, the log,
+  the epic, the dependencies are all in the two calls in steps 1 and 2. See §7 of `rounds.md`.
+- **No files outside the scratch directory**, and never write into `.k0/` by hand: the server
+  mirrors the tasks there on its own.

package/.claude/skills/k0-story/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: k0-story
+description: Puts one story on the k0 board in a single move — the user says what he wants, it lands as a post-it with a key of its own, and a Claude Code session can start on it straight away. No questions, no rounds, no ceremony: this is the fast door. Use this skill when the user says "/k0-story", "add a story", "put this on the board", "new post-it", "note this down for later", "one more thing for the backlog", "and start it now", or in Italian "aggiungi una storia", "mettila sul board", "segnati questa cosa", "nuova storia e partiamo". Do not use it for something big enough to need breaking up — that is /k0-epic — and do not use it on a story that already exists: discussing it is /k0-discuss, planning it is /k0-plan, working it is /k0-work.
+---
+
+# /k0-story [what it is]
+
+One story, straight onto the board. The user has already said what he wants; your job is to
+write it down well and get out of the way. **No rounds, no questions, no confirmation** unless
+he asks for one or something is genuinely missing.
+
+If he also says *and start it* — or anything like it — start the session in the same breath.
+
+## Before anything
+
+```bash
+PORT="${K0_PORT:-4319}"
+REPO="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"; REPO="${REPO%/.git}"
+[ -d "$REPO" ] || REPO="$(git rev-parse --show-toplevel 2>/dev/null)"
+curl -sS --max-time 30 --get --data-urlencode "repo=$REPO" \
+  "http://127.0.0.1:$PORT/api/backlog" -o "$SCRATCH/k0-backlog.json"
+node -e 'const b=JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"));
+  console.log(JSON.stringify({enabled: b.enabled, epics: (b.epics||[]).map(e => ({key: e.key, title: e.title}))}))' \
+  "$SCRATCH/k0-backlog.json"
+```
+
+`127.0.0.1`, not `k0.localhost`: browsers resolve that name by themselves, `curl` does not.
+`--get --data-urlencode`, not `?repo=$REPO`: a repository path with a space in it makes `curl`
+refuse the address outright, and one with a `#` in it quietly sends half.
+`$SCRATCH` is the session's scratch directory; nothing is written outside it. `REPO` is the
+repository the stories are filed under — the main one, even when this session sits in a
+subdirectory of it or inside a worktree, which is why it is not `$PWD`.
+
+- `curl` cannot connect → the k0 server is not running. Say so (`k0-board start`, or the tray
+  icon → *Restart*) and **stop**.
+- `enabled` is `false` → say in one line that the backlog is switched off in k0's settings and
+  **stop**. Do not create anything and do not argue for turning it on.
+- `REPO` empty → this is not a git repository. Ask once which repository the story belongs to
+  and take the path he gives. That is the only question this skill asks on its own.
+
+**Read the two lines `node` prints, not the file.** The board's answer carries every story in the
+repository with everything known about each one, and this skill needs exactly two things out of
+it: whether the feature is on, and what the epics are called. On a board of a hundred stories,
+reading all of that to write one post-it costs more than the post-it does. If the user named no
+epic, even the list of epics is surplus — check `enabled` and move on.
+
+If he did name one in passing — *"this one goes under invoicing"* — match it in that list and use
+its `key`. Do not ask which epic: a story with no epic is perfectly normal and stands on its own all
+the same.
+
+## Write it
+
+- **`title`** — 2 to 6 words, 60 characters at most, the thing itself. Readable, not a slug.
+- **`body`** — the *why*, in one or two sentences: what he wants and what it is for. **His
+  words, his language**, tidied but not translated and not padded. If he said one sentence, the
+  body is one sentence.
+- **`lang`** — the language he spoke: `it`, `en`, and so on.
+- **`prompt`** — only when the story is starting now: the instruction the session opens with.
+
+Do not invent scope. If he described half a thing, the story is half a thing — a story is
+allowed to be thin, and `/k0-discuss` exists for the rest.
+
+## Create it
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-story.json"
+```
+
+with `{ "project_path": "…", "title": "…", "body": "…", "lang": "it", "epic_key": "K7" }` —
+`project_path` is `REPO`, and `epic_key` only when there is one. Write the JSON to a file and
+send it with `-d @file`: a body dictated by voice will have quotes and newlines in it and will
+not survive being pasted inline.
+
+The answer carries the `key` and the `id`. **Read them from there** — never work
+them out yourself, and never ask.
+
+## Start it, if that is what he said
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$ID/start" \
+  -H 'content-type: application/json' -d '{"auto_send": true}'
+```
+
+`prompt` is optional here: leave it out and the story's own prompt is used. Only start when he
+asked. A story created and left on the board is the normal case.
+
+## Say one line
+
+In his language, and one line is the whole report:
+
+> **K42 · 1.12** — Fix the invoice export. On the board, in Backlog.
+
+Add *and the session is running* when you started one. Nothing else: no summary of what you
+understood, no list of what he might want next, no offer to discuss it.
+
+## Rules
+
+- **Speed is the feature.** Two calls, one line back. If you find yourself asking a second
+  question, you are in the wrong skill.
+- **Never ask for what the API just told you** — the key, the epic, the state.
+- **Store what he said in the language he said it in.** The interface is English; his words are
+  his.
+- **This skill only creates.** No `PATCH`, no `DELETE`, no touching stories that already exist.
+- **Several stories in one breath** — *"add these three"* — is still this skill: one `POST` each,
+  then one line each. Do not turn it into a discussion.
+- If he starts discussing instead of dictating, hand over to `/k0-discuss` on the story you have
+  just created rather than running rounds here.