@lernapps/tooling 0.0.1 → 0.1.0

package/guidance/increment-template.md

@@ -0,0 +1,194 @@
+---
+# Read by the hooks, the review, the evals. Schema: @lernapps/tooling/guidance/plan-front-matter.v1.schema.json
+# Keep all four keys.
+# Archetype as in the app's first plan; set it when you start. Never changes.
+archetype: null
+# Current phase. Allowed values: explore, plan, code, commit. Change the value line below, never this comment.
+phase: explore
+# prePushFailures: failed pre-push runs of this increment, written by the hook. Never change it.
+prePushFailures: 0
+# failedChecks: failed rules and runs, written by lernapps check and the hooks. Never change it.
+failedChecks: {}
+---
+
+# Increment: <what it adds>
+
+<!--
+For you, the assistant. One increment of a published app: new competencies, chapters, pages, rounds, questions, or
+a correction.
+1. Path: `.vibe/plans/<NN>-<short name>.md`, NN = highest + 1. Never change an earlier plan. App with only
+   `.vibe/plan.md`: that is plan 01; start this one as 02 (the update in Code moves it).
+2. The first version's decisions stand: archetype, content method, content guide
+   `.agents/skills/app-content/SKILL.md`. Change the guide only for a new pattern, figure type or source rule; say
+   so at the checkpoints.
+3. Read this plan before each step. One phase at a time, tasks in order.
+4. Task done → tick `[x]` at once and move it to "Completed" of its phase. New task found → add it.
+5. Each phase names its skills. Load a skill when its task comes, not before. Read it in full, from its file.
+6. Checkpoint: stop, ask, wait for the creator's answer.
+   Only a checkpoint waits. A phase's last box → set the next phase and go on in the same message.
+7. At most 2 questions per message, one topic each.
+8. Work on the branch `increment/<NN>-<short name>`. Until Commit everything is local: push nothing.
+9. Plan in the creator's language. Keep headings and front matter keys. Delete a comment once its part is filled.
+10. Begin each reply to the creator with the phase in `phase:`, and at a checkpoint the word checkpoint:
+    "**Plan · Checkpoint**", "**Code**". The creator always knows where you are.
+-->
+
+*Started <date>. Explore, Plan, Code, Commit.*
+
+## Goal
+
+<!-- 1–2 sentences: what learners can do after this increment. -->
+
+## Key decisions
+
+<!-- One line each: decision and reason. Your own choice without the creator: mark "(guess)". -->
+
+## Notes
+
+<!-- Curriculum orientation, new competencies by chapter, didactic approach, scope, sources and licences, open
+questions. -->
+
+## Explore
+
+<!--
+- All content questions belong here; Plan maps the answers onto the app. Ask; write no code.
+- Skip what earlier answers or the app already tell. Never tick a topic you assumed.
+- Skills: the content guide `app-content`, `lernapps-content-research`, `lernapps-<archetype>-design`.
+-->
+
+### Tasks
+
+- [ ] Set `archetype` as in the app's first plan in `.vibe/plans/`.
+- [ ] Skills are in `.agents/skills/`; if missing, install them as the first task of the plan template says.
+- [ ] Read the README of the archetype's template (link in skill `lernapps-app`): what the app can do now. Tell the
+      creator what is new, if it matters for this increment.
+- [ ] Load the content guide `.agents/skills/app-content/SKILL.md`. Read the plans in `.vibe/plans/`: what the app
+      teaches, how its content is made, what is open.
+- [ ] Interview: one topic per question, the creator's words under "Answers". No answer → ask once more, then
+      "(guess)". Topics: which competencies, chapters or rounds, for which school years; hurdles and examples;
+      amount; any change of look and feel or terms.
+- [ ] Load skill `lernapps-content-research`. Research what the guide's curriculum and sources do not cover. Under
+      "Notes": curriculum orientation, new competencies by chapter as "Ich kann …", verified sources.
+- [ ] Under "Notes": the didactic approach per competency and the scope (in, out, data range).
+- [ ] A kind of content the guide does not cover (a new page structure, screen, component or kind of exercise) →
+      load skills `lernapps-<archetype>-design` and `lernapps-exercise-patterns`. Else skip this task.
+- [ ] **Checkpoint:** research. Show in plain words: curriculum orientation, new competencies by chapter, didactic
+      approach, scope, every "(guess)", sources and how you checked them, what is unchecked. Stop and wait.
+      Changes → change, ask again.
+- [ ] Set `phase: plan`: change the value line (`grep '^phase:'` prints `phase: plan`).
+
+### Answers
+
+<!-- The creator's answers, in their words, one bullet each. -->
+
+### Completed
+
+## Plan
+
+<!--
+- Map the new content onto the app with the guide's patterns. Confirmable in one read.
+- After the yes, work on your own: at most 3 creator turns until the end.
+- Skills: `lernapps-content-growth`; for something the guide does not cover, the skills loaded in Explore.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: plan`; else set it.
+- [ ] Load skill `lernapps-content-growth`. Write the Code tasks as slices, one per competency, in the guide's
+      order. Mark the slices sub-agents can write in parallel.
+- [ ] Write "Content method": the guide's patterns, figures and components per slice. Anything new: map it as skill
+      `lernapps-<archetype>-design` says, choose its pattern with skill `lernapps-exercise-patterns` (both loaded
+      in Explore), and say why the guide's patterns do not fit.
+- [ ] Each new component or interactive exercise: a sketch (static SVG or image, or the steps). Words alone are not
+      enough.
+- [ ] Show the creator, short: goal, new competencies by chapter, slices; in plain words what learners see and do,
+      what is new. At most 2 questions.
+- [ ] **Checkpoint:** confirm the plan and the content method. Stop and wait for an explicit yes. Changes → change,
+      ask again.
+- [ ] Set `phase: code`: change the value line (`grep '^phase:'` prints `phase: code`).
+
+### Content method
+
+<!-- One line each: the guide's patterns, figures and components used, and where; anything new, what it does and
+cannot. Something new goes into the guide in the slice that adds it. -->
+
+### Completed
+
+## Code
+
+<!--
+- Build locally on the branch. Commit after each slice; the hooks check. A check fails → skill `lernapps-cli`. Fix from the message; never
+  bypass a hook.
+- Undecidable → choose, mark "(guess)", go on.
+- Creator asks for a change → first say your reading in one sentence; never narrow it silently.
+- Skills: `lernapps-cli`, `lernapps-<archetype>`, `lernapps-content-questions`, the content guide.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: code`; else set it.
+- [ ] `git switch -c increment/<NN>-<short name>` from `main`. Commit this plan on it.
+- [ ] Load skill `lernapps-cli`. Update the app as it says. Commit the update alone; fix its findings before
+      content. The update replaces the `lernapps-*` skills: reread those you use.
+- [ ] Load skill `lernapps-<archetype>` and the content guide. Questions with options and feedback: also skill
+      `lernapps-content-questions`.
+- [ ] <the slices written in Plan; each: competency, content, exercise, the entry's topic, check, commit>
+- [ ] After the first slice: show the creator a first look (`early-preview`) and go on.
+      Parallel slices: send each sub-agent `@lernapps/tooling/guidance/subagent-brief.md`, filled in.
+- [ ] The content guide describes the app as it is now (`app-content-matches`). `grep -c "FILL IN"
+      .agents/skills/app-content/SKILL.md` prints 0.
+- [ ] `npx lernapps check` passes.
+- [ ] Every box of Explore, Plan and Code ticked.
+- [ ] Set `phase: commit`: change the value line (`grep '^phase:'` prints `phase: commit`).
+      No checkpoint here: set it before you ask or report anything, then start Commit in the same message.
+
+### Completed
+
+## Commit
+
+<!--
+- Publish with the creator's yes. A push to `main` publishes.
+- Open the pull requests (to `main`, to the catalog) without asking: they publish nothing; their preview and result
+  are what the creator decides on.
+- Skills: `lernapps-explainer-self-assessment` (an explainer), `lernapps-github`, `lernapps-commit`,
+  `lernapps-listing`.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: commit`; else set it.
+- [ ] An explainer whose pages or exercises changed: load skill `lernapps-explainer-self-assessment`
+      (missing → `npx lernapps skills --archetype explainer`). Update the
+      self-assessment as it says (add one, if the app has none and the skill says so). Commit; the hooks check.
+- [ ] Load skill `lernapps-github`. Push the branch, open the preview pull request, see its checks to green as it
+      says.
+- [ ] **Checkpoint:** publish. Show what the increment adds and the preview link; ask whether it may go online. Wait
+      for the yes.
+- [ ] Load skill `lernapps-commit`. Publish as skill `lernapps-github` says: the pull request squash-merged into
+      `main` with the message from this plan, the run of `Pages` watched to the end.
+- [ ] Open the address the job `deploy` printed; confirm the new content. Never a derived address.
+- [ ] App listed and its entry changes (topics, school years, summary) → load skill `lernapps-listing` and write the
+      changed entry. Else skip the checkpoint "list".
+- [ ] Fill the retrospective.
+- [ ] Commit this plan on `main` and push it. A push of only `.vibe/` publishes nothing.
+- [ ] **Checkpoint:** list. Open the pull request to the catalog without asking first: the pull request is the
+      review. See it to "bestanden" as the skill says, then show the creator the pull request and its result.
+- [ ] Plan changed since its last push → commit it on `main`, push again.
+
+### Completed
+
+## Retrospective
+
+<!-- At the end of Commit. Facts, short, no names. Read by review and evals. -->
+
+### Phases reached
+
+<!-- Last phase completed, checkpoints passed. E.g. "commit; confirmed, published". -->
+
+### Creator turns after the plan
+
+<!-- Number of creator messages after the confirmation, topic of each. Target: at most 3. -->
+
+### Where I had to guess
+
+<!-- Each gap in plan, skills, content guide, messages or answers, and your choice. "None" if none. -->

package/guidance/plan-front-matter.v1.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Front matter of a lernapps plan file, version 1",
+  "description": "The YAML front matter of an app's plan files (.vibe/plans/<NN>-<short name>.md, one per piece of work). The assistant sets archetype and phase; the pre-push hook increments prePushFailures; every failed run of `lernapps check` in the repo (the hooks included) counts its failed rules in failedChecks. The review and the evals read them. One `key: value` per line; failedChecks is a flow map on its line. A breaking change gets a new version of this schema.",
+  "type": "object",
+  "properties": {
+    "archetype": {
+      "description": "The kind of app, chosen in Explore of its first plan from the creator's answers, and taken over by every later plan; null until then.",
+      "enum": ["explainer", "interactive", "quiz", null]
+    },
+    "phase": {
+      "description": "The phase the assistant works in now.",
+      "enum": ["explore", "plan", "code", "commit"]
+    },
+    "prePushFailures": {
+      "description": "Failed runs of the pre-push hook during this plan. Written by the hook, never by the assistant.",
+      "type": "integer",
+      "minimum": 0
+    },
+    "failedChecks": {
+      "description": "Each rule that had an error in a failed run of `lernapps check` in the repo during this plan (the git hooks included), with the number of such runs. Written by the check, never by the assistant. A plan made before this key has none.",
+      "type": "object",
+      "propertyNames": { "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$" },
+      "additionalProperties": { "type": "integer", "minimum": 1 }
+    }
+  },
+  "required": ["archetype", "phase", "prePushFailures"],
+  "additionalProperties": false,
+  "if": {
+    "properties": { "phase": { "enum": ["plan", "code", "commit"] } },
+    "required": ["phase"]
+  },
+  "then": {
+    "properties": { "archetype": { "type": "string" } }
+  }
+}

package/guidance/plan-template.md

@@ -0,0 +1,233 @@
+---
+# Read by the hooks, the review, the evals. Schema: @lernapps/tooling/guidance/plan-front-matter.v1.schema.json
+# Keep all four keys.
+# Archetype, null until chosen in Explore. Allowed values: explainer, interactive, quiz.
+archetype: null
+# Current phase. Allowed values: explore, plan, code, commit. Change the value line below, never this comment.
+phase: explore
+# prePushFailures: written by the pre-push hook. Never change it.
+prePushFailures: 0
+# failedChecks: failed rules and runs, written by lernapps check and the hooks. Never change it.
+failedChecks: {}
+---
+
+# Plan: <app name>, first version
+
+<!--
+For you, the assistant.
+1. Path: `.vibe/plans/01-<short name>.md`. Every later change gets its own plan from the increment template.
+2. Read this plan before each step. One phase at a time, tasks in order.
+3. Task done → tick `[x]` at once and move it to "Completed" of its phase. An unticked box counts as not done.
+4. New task found → add it.
+5. Each phase names its skills. Load a skill when its task comes, not before. Read it in full, from its file.
+6. Checkpoint: stop, ask, wait for the creator's answer. A message sent before the question is no yes.
+   Only a checkpoint waits. A phase's last box → set the next phase and go on in the same message.
+7. At most 2 questions per message, one topic each. No questions inside drafts or lists.
+8. Work on the branch `work`, locally: push nothing before Commit. Commit puts the app on GitHub and brings `work`
+   into `main`.
+9. Plan in the creator's language. Keep headings and front matter keys. Delete a comment once its part is filled.
+10. Begin each reply to the creator with the phase in `phase:`, and at a checkpoint the word checkpoint:
+    "**Plan · Checkpoint**", "**Code**". The creator always knows where you are.
+-->
+
+*Started <date>. Explore, Plan, Code, Commit.*
+
+## Goal
+
+<!-- 1–2 sentences: what learners do, what they learn. -->
+
+## Key decisions
+
+<!-- One line each: decision and reason. Archetype first. Your own choice without the creator: mark "(guess)". -->
+
+## Notes
+
+<!-- Curriculum orientation, competencies by chapter, didactic approach, scope, sources and licences, open
+questions. -->
+
+## Explore
+
+<!--
+- Find out what the app teaches, for whom, how much and how it looks. All content questions belong here; Plan only
+  maps the answers onto the archetype.
+- Ask. Write no code, run no `create`.
+- An answer counts only in the creator's words under "Answers". Never tick a topic you assumed.
+- Skills: `lernapps-app`, `lernapps-exercise-patterns`, `lernapps-<archetype>-design`, `lernapps-content-research`.
+-->
+
+### Tasks
+
+- [ ] The skills of the phases are in `.agents/skills/` (`npx --yes @lernapps/tooling init <short name>` put them there
+      and wrote this plan; the app commits them). `.agents/skills/lernapps-app` missing → stop and tell the creator
+      the folder was not started with `init`.
+- [ ] Load skill `lernapps-app`. Tell the creator in two sentences what a lernapps app is and where it will live: at
+      their own address, free, public, and once listed as a copy on lernapps.net. The technical part (GitHub) comes at the end, and you do it.
+- [ ] Interview: ask the topics "Goal" and "Learners" of "Answers".
+- [ ] Load skill `lernapps-exercise-patterns` and read the patterns of the subject: how will learners practise what
+      the goal names? The kind of practice points to the archetype, as the skill says.
+- [ ] Choose the archetype as skill `lernapps-app` says, from the kind of practice: read the README of each
+      archetype in question, tell the creator what the chosen one can and cannot do. Write it and its reason under
+      "Key decisions". Set `archetype`.
+- [ ] Install the archetype's skills: `npx lernapps skills --archetype <archetype>`. Load skill
+      `lernapps-<archetype>-design`.
+- [ ] Interview: ask the other topics of "Answers" in order. Skip a topic only when an earlier answer covers it; note
+      which. No answer → ask once more; still none → write your assumption with "(guess)". Done when every topic
+      has an answer or a guess.
+- [ ] Load skill `lernapps-content-research`. Research as it says. Under "Notes": curriculum orientation,
+      competencies by chapter as "Ich kann …", verified sources. No competencies → not done.
+- [ ] Under "Notes", one line per competency: how learners get there (derive, not only read off; e.g. a tree diagram
+      shows how a probability comes about), which misconception the feedback catches.
+- [ ] Under "Notes", the scope: what is in, what is out and why, the data range (e.g. "all main-group elements",
+      never a silent "1–20"), the languages.
+- [ ] Fetch https://lernapps.net/apps/schemas/entry.v1.schema.json and read each property's description. Ask what
+      helps teachers and parents find the app. Fill "Entry draft". Search words: one or two words each, as people
+      type them.
+- [ ] **Checkpoint:** research. Show in plain words: curriculum orientation, competencies by chapter, didactic
+      approach, scope, every "(guess)", sources and how you checked them, what is unchecked, archetype and reason.
+      Stop and wait. Changes → change, ask again.
+- [ ] Set `phase: plan`: change the value line (`grep '^phase:'` prints `phase: plan`).
+
+### Answers
+
+<!-- The interview: per topic the creator's answer, in their words. Keep the topics. -->
+
+- Goal: what learners do in the app, what they learn.
+- Learners: subject, school year, prior knowledge. Land and Schulform only if the creator names a school or class,
+  at most once; none → KMK-Bildungsstandards.
+- Model and focus: an app of the catalog (read https://lernapps.net/apps/llms.txt) as model; what matters most
+  (exercises, visualisations, game feel).
+- Hurdles: misconceptions and mistakes of the learners; the creator's examples and experiments.
+- Content: who writes it (creator, you, from sources); own material (worksheets, tests); how it is made (sources,
+  research, a data format).
+- Amount: how much content per level or chapter in the first version (e.g. "one text per school year"); what comes
+  later.
+- Languages: German only, or more (texts, code).
+- Look and feel: calm like a worksheet, or like a game (colours, praise, effects); dark mode.
+- Terms: the creator's words for the main things in the app, used everywhere.
+
+### Entry draft
+
+<!-- YAML valid against the entry schema, with its property names. Only known values, never invented. -->
+
+```yaml
+```
+
+### Completed
+
+## Plan
+
+<!--
+- Map the confirmed content onto the archetype: structure, screens or pages, exercise patterns, data files,
+  components.
+- No new content questions. A content gap → back to Explore; say so.
+- Confirmable in one read. After the yes, work on your own: at most 3 creator turns until the listing.
+- Skills: `lernapps-<archetype>-design` and `lernapps-exercise-patterns`, both loaded in Explore.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: plan`; else set it.
+- [ ] Map the content as skill `lernapps-<archetype>-design` says; reread it if it is no longer in view.
+- [ ] Choose a pattern per competency as skill `lernapps-exercise-patterns` says (loaded in Explore; reread it if it
+      is no longer in view). Write "Content method".
+- [ ] Write the Code tasks under "Code": pages or screens, their content, what each shows. Each ends in a commit.
+      After the first task that shows real content: the task "Show the creator a first look (`early-preview`)".
+- [ ] Each screen, component or interactive exercise: a sketch (static SVG or image, or the steps with what
+      learners see after each). Words alone are not enough.
+- [ ] Show the creator, short: goal, competencies by chapter, entry draft, tasks, sketches; the content method in
+      plain words (what learners see and do, what it cannot do). At most 2 questions.
+- [ ] **Checkpoint:** confirm the plan and the content method, with the sketches shown. Stop and wait for an
+      explicit yes. Changes → change, ask again. No `create` before the yes.
+- [ ] Set `phase: code`: change the value line (`grep '^phase:'` prints `phase: code`).
+
+### Content method
+
+<!-- One line each: exercise patterns and where; figures and how they are made; data files; each component, what it
+checks and cannot; how a later agent adds a chapter. Becomes the content guide in Code. -->
+
+### Completed
+
+## Code
+
+<!--
+- Build the app from the archetype and the confirmed plan, locally on `work`. Work on your own.
+- Commit after each task; the hooks check. A check fails → skill `lernapps-cli`. Fix from the message; never
+  bypass a hook.
+- Undecidable → choose, mark "(guess)" under "Key decisions", go on.
+- Creator asks for a change → first say your reading in one sentence ("Ich nehme alle 44 Hauptgruppenelemente
+  auf."); never narrow it silently. Content change → update "Notes" too.
+- Skills: `lernapps-cli`, `lernapps-<archetype>`, `lernapps-content-questions`, and the app's content guide
+  `app-content`.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: code`; else set it.
+- [ ] Load skill `lernapps-cli`. Create the app in this plan's folder as it says. `create` keeps this plan. Never
+      write the app by hand.
+- [ ] Fill the content guide `.agents/skills/app-content/SKILL.md` from "Notes" and "Content method"
+      (`app-content-guide`). `grep -c "FILL IN" .agents/skills/app-content/SKILL.md` prints 0. Commit it before
+      any content.
+- [ ] Load skill `lernapps-<archetype>` and the content guide. Questions with options and feedback: also skill
+      `lernapps-content-questions`.
+- [ ] <the tasks written in Plan; after each, commit on `work`; after the first with real content, show the
+      creator a first look (`early-preview`) and go on>
+- [ ] The content guide matches what was built (`app-content-matches`).
+- [ ] `npx lernapps check` passes.
+- [ ] Look at a screenshot of every screen and state (start, each mode, pause, end), desktop and 360 px. Compare
+      each with the confirmed sketches.
+- [ ] Every box of Explore, Plan and Code ticked.
+- [ ] Set `phase: commit`: change the value line (`grep '^phase:'` prints `phase: commit`).
+      No checkpoint here: set it before you ask or report anything, then start Commit in the same message.
+
+### Completed
+
+## Commit
+
+<!--
+- Put the app on GitHub, publish it with the creator's yes, then list it. A push to `main` publishes.
+- Open the pull requests (to `main`, to the catalog) without asking: they publish nothing; their preview and result
+  are what the creator decides on.
+- Skills: `lernapps-explainer-self-assessment` (an explainer), `lernapps-github`, `lernapps-commit`,
+  `lernapps-listing`.
+-->
+
+### Tasks
+
+- [ ] `grep '^phase:'` prints `phase: commit`; else set it.
+- [ ] An explainer: load skill `lernapps-explainer-self-assessment` (missing → `npx lernapps skills --archetype
+      explainer`). Add the self-assessment as it says, or
+      write under "Key decisions" why the app has none. Commit; the hooks check.
+- [ ] Load skill `lernapps-github`. Repo and Pages as it says: ask the repo name and every click only the creator can
+      make in one message.
+- [ ] Push `work`, open the preview pull request, see its checks to green as the skill says.
+- [ ] **Checkpoint:** publish. Show what the app does and the preview link from the comment "Vorschau der App"; ask
+      whether it may go online; put any open click into the same question. Wait for the yes.
+- [ ] Load skill `lernapps-commit`. Publish as skill `lernapps-github` says: `work` into `main` as one squash commit
+      with the message from this plan, the run of `Pages` watched to the end.
+- [ ] Open the address the job `deploy` printed; confirm the app shows. Use that address, never a derived one.
+- [ ] Load skill `lernapps-listing`. Complete the entry draft (e.g. the address).
+- [ ] Fill the retrospective.
+- [ ] Commit this plan on `main` and push it: the listing check and the review read it there.
+- [ ] **Checkpoint:** list. Open the listing pull request as the skill says, without asking first: the pull request
+      is the review. See it to "bestanden", then show the creator the pull request and its result; change nothing in
+      it without their word.
+- [ ] Plan changed since its last push → commit it on `main`, push again.
+
+### Completed
+
+## Retrospective
+
+<!-- At the end of Commit, before the listing pull request. Facts, short, no names. Read by review and evals. -->
+
+### Phases reached
+
+<!-- Last phase completed, checkpoints passed. E.g. "commit; confirmed, published". -->
+
+### Creator turns after the plan
+
+<!-- Number of creator messages after the confirmation, topic of each. Target: at most 3. -->
+
+### Where I had to guess
+
+<!-- Each gap in plan, skills, messages or answers, and your choice. "None" if none. -->

package/guidance/subagent-brief.md

@@ -0,0 +1,25 @@
+# Sub-agent brief
+
+Fill the brackets. Send the whole brief to each sub-agent.
+
+```text
+Add the chapter/round "<title>" to the lernapps app in <repo>, on the branch <branch>, in your own git worktree.
+
+Read first, in this order: .agents/skills/app-content/SKILL.md (it takes precedence), then the skills
+lernapps-<archetype> and lernapps-cli; for questions with options also lernapps-content-questions.
+
+Competencies, one slice each, in this order:
+1. "Ich kann …" (Lehrplan: <document, page, unit> | none)
+   - Content: <page or questions, with ids>
+   - Exercise: pattern "<name from the guide>", varied as <…>
+   - Second source: <address and exact title, verified> | none
+2. …
+
+Change only: <the files of this chapter or round>. Do not change: the content guide, the plan, <the shared files>.
+Write what the shared files need into your report instead.
+
+Per slice: content, exercise, `npx lernapps check` green, one commit. Never bypass a hook.
+
+Report: branch, commits, per competency the ids of its page or questions and exercises, the patterns used, what the
+shared files need, what you could not verify.
+```

package/guidance/workflow-rules.md

@@ -0,0 +1,109 @@
+# Workflow rules
+
+The plan holds the workflow. These rules say what each step must meet. They hold in every phase.
+
+## Plan
+
+### `plan-file`: Keep the plan file
+
+```rule
+id: plan-file
+scope: tooling
+severity: error
+```
+
+- Each plan in `.vibe/plans/`, with every section and front matter key of its template.
+- Never change the plan of an earlier piece of work.
+- Set `phase` when you enter a phase. Tick each task box when it is done.
+- Never edit `prePushFailures` or `failedChecks`: the hook and the check write them.
+
+### `explore-before-code`: No code before the plan is confirmed
+
+```rule
+id: explore-before-code
+scope: tooling
+severity: error
+```
+
+- No code and no `lernapps create` until the creator has confirmed the plan with a yes.
+
+### `stop-at-checkpoints`: Stop at the creator's checkpoints
+
+```rule
+id: stop-at-checkpoints
+scope: tooling
+severity: error
+```
+
+- Checkpoints: research, confirm the plan and the content method, publish. Stop at each and wait for the answer.
+- Checkpoint list: open the listing pull request first (it publishes nothing), then show it and its result and wait.
+- A message sent before the checkpoint's question is no yes.
+- Example: "Die App ist fertig und geprüft. Soll ich sie jetzt veröffentlichen?"
+
+### `few-turns-after-plan`: Work on your own after the plan
+
+```rule
+id: few-turns-after-plan
+scope: tooling
+severity: hint
+```
+
+- After the confirmation, ask only what you cannot decide.
+- Else choose, mark "(guess)" under "Key decisions" and list it in the retrospective.
+
+### `early-preview`: Show a first look early
+
+```rule
+id: early-preview
+scope: tooling
+severity: hint
+```
+
+- In Code, as soon as the first screen or page shows real content: send the creator a short "Zwischenstand".
+- Show screenshots, desktop and 360 px. On the creator's machine also the address of `npm run dev`, started in the
+  background.
+- No checkpoint, no question: go on in the same message. The creator may stop you or ask for a change.
+- Example: "Zwischenstand: So sieht die erste Seite aus. Ich baue weiter; sag Bescheid, wenn etwas nicht passt."
+
+### `retrospective-filled`: Fill the retrospective
+
+```rule
+id: retrospective-filled
+scope: tooling
+severity: error
+```
+
+- At the end of Commit, fill every part with facts: phases reached, creator turns after the plan, where you guessed.
+  No names.
+- Failed checks need no entry: the check counts them in `failedChecks`.
+
+## Content guide
+
+### `app-content-guide`: Keep the app's content guide
+
+```rule
+id: app-content-guide
+scope: tooling
+severity: error
+```
+
+- Keep `.agents/skills/app-content/SKILL.md` with its fixed headings.
+- After the plan is confirmed and before content: replace every placeholder ("FILL IN") with concrete instructions
+  for writing new content: files, ids, data files, an example of this app. Not how the app works, no general advice.
+- A content decision changes (pattern, figure type, source rule) → change the guide in the same commit.
+- `lernapps check` checks the file and its headings always, and that no placeholder is left once the plan is in
+  Commit.
+- App older than the guide: `lernapps update` adds the skeleton (skill `lernapps-cli`).
+
+### `app-content-matches`: The content guide says what was built
+
+```rule
+id: app-content-matches
+scope: tooling
+severity: error
+```
+
+- Every pattern it names is used; no pattern is used that it does not name.
+- Curriculum, competencies, chapters, pages or rounds match the content.
+- Its procedure for a new chapter or round names the current files.
+- An agent without your conversation can add the next chapter or round from it alone.