@turri-dev/cli 0.0.0-stage → 0.1.1

package/genome/skills/implement-unit-testing-script/assets/run_unittests_python.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# The unit tests of a Python build, with its static checks: ruff's formatter in check mode, ruff's linter and mypy,
+# each from the project's own `dev` dependency group, then pytest - as stdlib/lang/python asks for them.
+#
+#   run_unittests_python.sh <build folder>
+#
+# The build folder is read only: the build is staged in a working folder in /tmp and everything runs there.
+# Every check runs, and the tests run whatever the checks said, so one run reports both.
+# Exit codes: 0 all pass; 1 bad usage; 2 a filesystem problem; 69 a toolchain missing on this machine;
+# 80 the tests passed and only the static checks did not; any other, the failing install or test tool's own.
+
+set -u
+STATIC_CHECKS_FAILED=80
+
+echo "===== [1/8] Toolchain check ====="
+if ! command -v uv >/dev/null 2>&1; then
+  echo "Error: uv is not installed on this machine (https://docs.astral.sh/uv/)."
+  exit 69
+fi
+echo "uv: $(command -v uv) - $(uv --version)"
+PYTHON="$(uv python find --system --no-python-downloads 3.12 2>/dev/null)" || {
+  echo "Error: Python 3.12 is not installed on this machine; no runtime is downloaded."
+  exit 69
+}
+echo "Python: $PYTHON - $("$PYTHON" --version 2>&1)"
+
+echo "===== [2/8] Argument validation ====="
+if [ -z "${1:-}" ]; then
+  echo "Usage: $0 <build folder>"
+  exit 1
+fi
+SOURCE="$(cd "$1" 2>/dev/null && pwd)" || { echo "Error: the build folder '$1' does not exist."; exit 2; }
+echo "Build folder (read only): $SOURCE"
+
+echo "===== [3/8] Working folder ====="
+# A folder of its own each run: runs side by side never share one.
+WORKING_FOLDER="$(mktemp -d "/tmp/python_$(basename "$SOURCE").XXXXXX")" || { echo "Error: could not create a working folder in /tmp."; exit 2; }
+trap 'rm -rf "$WORKING_FOLDER"' EXIT
+echo "Working folder: $WORKING_FOLDER"
+
+echo "===== [4/8] Copy the build ====="
+EXCLUDES=(--exclude=.venv --exclude=venv --exclude=__pycache__ --exclude=.mypy_cache --exclude=.ruff_cache --exclude=.pytest_cache --exclude=.git)
+echo "+ tar -C $SOURCE ${EXCLUDES[*]} -cf - . | tar -C $WORKING_FOLDER -xf -"
+tar -C "$SOURCE" "${EXCLUDES[@]}" -cf - . | tar -C "$WORKING_FOLDER" -xf - || { echo "Error: could not copy the build folder."; exit 2; }
+
+echo "===== [5/8] Enter the working folder ====="
+cd "$WORKING_FOLDER" 2>/dev/null || { echo "Error: cannot enter $WORKING_FOLDER."; exit 2; }
+echo "Now in: $(pwd)"
+
+echo "===== [6/8] Dependencies ====="
+if [ ! -f pyproject.toml ]; then
+  echo "Error: there is no pyproject.toml - the project's dependencies, pytest, ruff and mypy among them, go in it."
+  exit 1
+fi
+export UV_PROJECT_ENVIRONMENT="$WORKING_FOLDER/.venv" UV_PYTHON="$PYTHON" UV_PYTHON_DOWNLOADS=never
+export UV_CACHE_DIR="${UV_CACHE_DIR:-$WORKING_FOLDER/.uv-cache}" PYTHONDONTWRITEBYTECODE=1
+unset PYTHONPATH PYTHONHOME
+echo "+ uv sync (the project and its dev dependency group into $UV_PROJECT_ENVIRONMENT)"
+uv sync || exit $?
+
+echo "===== [7/8] Static checks ====="
+CHECKS=0
+for tool in ruff mypy; do
+  if [ ! -x ".venv/bin/$tool" ]; then
+    echo "pyproject.toml:1:1: $tool is not in the dev dependency group - add it with \`uv add --dev $tool\`"
+    CHECKS=1
+  fi
+done
+if [ -x .venv/bin/ruff ]; then
+  echo "+ ruff format --check --output-format concise ."
+  .venv/bin/ruff format --check --output-format concise . || CHECKS=1
+  echo "+ ruff check --output-format concise --no-fix ."
+  .venv/bin/ruff check --output-format concise --no-fix . || CHECKS=1
+fi
+if [ -x .venv/bin/mypy ]; then
+  # `files` in [tool.mypy] says what to check; without it, the whole build.
+  if grep -Eq '^\s*files\s*=' pyproject.toml; then TARGETS=(); else TARGETS=(.); fi
+  echo "+ mypy --no-color-output --show-column-numbers ${TARGETS[*]:-}"
+  .venv/bin/mypy --no-color-output --show-column-numbers ${TARGETS[@]+"${TARGETS[@]}"} || CHECKS=1
+fi
+[ "$CHECKS" -eq 0 ] && echo "Static checks: passed" || echo "Static checks: FAILED - the findings are above"
+
+echo "===== [8/8] Unit tests ====="
+echo "+ uv run --no-sync pytest"
+uv run --no-sync pytest
+TESTS=$?
+
+echo "===== Summary ====="
+if [ "$TESTS" -ne 0 ]; then
+  STATUS=$TESTS
+elif [ "$CHECKS" -ne 0 ]; then
+  STATUS=$STATIC_CHECKS_FAILED
+else
+  STATUS=0
+fi
+echo "static checks: $([ "$CHECKS" -eq 0 ] && echo passed || echo failed); unit tests: exit $TESTS"
+echo "Exit: $STATUS; build: $SOURCE; working folder: $WORKING_FOLDER"
+exit "$STATUS"

package/genome/skills/implement-unit-testing-script/assets/run_unittests_react.ps1

@@ -0,0 +1,87 @@
+#!/usr/bin/env pwsh
+
+$ErrorActionPreference = 'Stop'
+
+$UNRECOVERABLE_ERROR_EXIT_CODE = 69
+
+# ANSI escape code pattern to remove color codes and formatting from output
+$ANSI_ESCAPE_PATTERN = '\x1b\[[0-9;]*[mK]'
+
+# Check if subfolder name is provided
+if (-not $args[0]) {
+    Write-Host "Error: No subfolder name provided."
+    Write-Host "Usage: $($MyInvocation.MyCommand.Name) <subfolder_name>"
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+$BuildFolder = $args[0]
+
+# Define the path to the subfolder. It lives in the system temp directory;
+# $BuildFolder may be an absolute path, so only its leaf name is used.
+$NODE_SUBFOLDER = Join-Path ([System.IO.Path]::GetTempPath()) "node_$(Split-Path $BuildFolder -Leaf)"
+
+if ($env:VERBOSE -eq "1") {
+    Write-Host "Preparing Node subfolder: $NODE_SUBFOLDER"
+}
+
+# Check if the node subfolder exists
+if (Test-Path $NODE_SUBFOLDER) {
+    # Delete all files and folders except "node_modules", "build", and "package-lock.json"
+    Get-ChildItem -Path $NODE_SUBFOLDER -Force |
+        Where-Object {
+            $_.Name -ne "node_modules" -and
+            $_.Name -ne "build" -and
+            $_.Name -ne "package-lock.json"
+        } | Remove-Item -Recurse -Force
+
+    if ($env:VERBOSE -eq "1") {
+        Write-Host "Cleanup completed, keeping 'node_modules' and 'package-lock.json'."
+    }
+} else {
+    if ($env:VERBOSE -eq "1") {
+        Write-Host "Subfolder does not exist. Creating it..."
+    }
+
+    New-Item -ItemType Directory -Path $NODE_SUBFOLDER -Force | Out-Null
+}
+
+Copy-Item -Path "$BuildFolder/*" -Destination $NODE_SUBFOLDER -Recurse -Force
+
+# Move to the subfolder
+if (-not (Test-Path $NODE_SUBFOLDER)) {
+    Write-Host "Error: Subfolder '$BuildFolder' does not exist."
+    exit $UNRECOVERABLE_ERROR_EXIT_CODE
+}
+
+Push-Location $NODE_SUBFOLDER
+
+try {
+    # Install libraries
+    npm install
+
+    # Execute all React unittests in the subfolder
+    Write-Host "Running React unittests in $BuildFolder..."
+    # Temporarily allow stderr output without throwing (npm/jest may write to stderr)
+    # ForEach-Object converts ErrorRecord objects (from stderr) to plain strings to avoid verbose error formatting
+    $ErrorActionPreference = 'Continue'
+    $output = npm test -- --runInBand --silent --detectOpenHandles 2>&1 | ForEach-Object { if ($_ -is [System.Management.Automation.ErrorRecord]) { $_.Exception.Message } else { $_ } } | Out-String
+    $TEST_EXIT_CODE = $LASTEXITCODE
+    $ErrorActionPreference = 'Stop'
+
+    # Strip ANSI escape codes
+    $output = $output -replace $ANSI_ESCAPE_PATTERN, ''
+    Write-Host $output
+
+    # Check if tests failed
+    if ($TEST_EXIT_CODE -ne 0) {
+        Write-Host "Error: Tests failed with exit code $TEST_EXIT_CODE"
+        exit $TEST_EXIT_CODE
+    }
+
+    exit $TEST_EXIT_CODE
+} finally {
+    Pop-Location
+    if (Test-Path $NODE_SUBFOLDER) {
+        Remove-Item -Path $NODE_SUBFOLDER -Recurse -Force -ErrorAction SilentlyContinue
+    }
+}

package/genome/skills/init-plain-project/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: init-plain-project
+description: >-
+  Lightweight initializer for a new ***plain project. Asks about the base
+  technology and project kind, asks whether conformance testing is enabled,
+  then scaffolds a template import module (with base implementation reqs and
+  test reqs), a stub top-level module, the unit testing script, and
+  (optionally) the conformance testing script under `test_scripts/`. Does NOT run `validate`. Use when the user wants a
+  quick project skeleton to start writing functional specs against, without
+  the full `brood` interview.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Init Plain Project
+
+## Scope
+
+This skill is intentionally **minimal**. It produces a runnable project skeleton — not a complete spec. **No `***definitions***` sections are written by this skill — not in the template module, not in the top module.** No functional specs, no concepts, no acceptance tests, no validation. The user will fill those in afterwards with `bud`, `add-concept`, `add-functional-spec`, etc.
+
+What this skill writes:
+
+- `template/base.plain` — an import module with the project's base `***implementation reqs***` and `***test reqs***`.
+- `<project>.plain` — a top-level module that imports `base`. Frontmatter only — no body sections. The user adds `***functional specs***` later.
+- `test_scripts/run_unittests_<lang>.sh` — always.
+- `test_scripts/run_conformance_tests_<lang>.sh` — only if conformance testing is enabled.
+
+turri requires these scripts: a build with no unit testing script (or, with conformance on, no conformance testing script) stops before it starts. The harness runs them with Bash on the person's machine, so they are `.sh` scripts.
+
+What this skill does **not** do:
+
+- Run `validate`.
+- Author concepts, functional specs, or acceptance tests.
+- Probe the host environment (`check-plain-env` is a separate step the user can run later).
+
+## Workflow
+
+### 1. Ask the project basics
+
+Ask each with `ask_user`, one question per call, in this order:
+
+- **Project name** — used as the top module filename and as `:AppName:` later. Free-form (`free_form: true`).
+- **Base technology** — programming language and primary framework (e.g. Python + FastAPI, Node.js + Express, Go + net/http, Java + Spring Boot). Offer the most common stacks as options.
+- **Project kind** — CLI tool, web app, REST API / backend service, library, desktop app, mobile app, other. Offer the common kinds as options.
+
+Follow up with one free-form question for anything the options didn't cover (e.g. specific Python version, monorepo layout).
+
+### 2. Ask about testing
+
+Ask each with `ask_user`, one question per call:
+
+- **Unit testing framework** — propose the canonical one for the chosen language (pytest, Jest, Go `testing`, JUnit, ...) and let the user override.
+- **Conformance testing** — enabled or not. If the user is unsure, briefly explain it adds a `run_conformance_tests` script and per-spec acceptance tests later.
+
+### 3. Author `template/base.plain`
+
+Create the import module with `create-import-module`. It must contain:
+
+- `***implementation reqs***` — the base stack as requirements **and everything about `:UnitTests:`**:
+  - Programming language and version.
+  - Primary framework (if any).
+  - Dependency / package manager.
+  - Project kind as a constraint (e.g. ":Implementation: should be a REST API service.").
+  - `:UnitTests:` framework (pytest / Jest / JUnit / Go's `testing` / …) and the command used to run them — phrased in terms of `:UnitTests:` so the partition is explicit.
+  - Anything else the user added in the free-form catch-all.
+- `***test reqs***` — the base **conformance**-testing rules (only added if conformance testing is enabled):
+  - ":ConformanceTests: must be implemented and executed - do not skip tests."
+  - The `:ConformanceTests:` framework and the command used to run them.
+  - **Do NOT** put unit-test framework / command here — that lives in `***implementation reqs***` above.
+
+Do **not** add a `***definitions***` section to `template/base.plain`. This skill does not author any concepts. Use only the predefined concepts (`:Implementation:`, `:ConformanceTests:`) in the reqs — no project-specific concepts like `:AppName:` or `:App:`. Do not declare `required_concepts` either.
+
+Do **not** add `***functional specs***` to `template/base.plain` — it is an import module.
+
+### 4. Author the top module `<project>.plain`
+
+Create it at the repo root with frontmatter:
+
+```yaml
+---
+import:
+  - base
+description: <one-line project description>
+---
+```
+
+Body: **none**. The file ends after the closing `---` of the frontmatter. Do **not** add `***definitions***`, do **not** add `***functional specs***`, do **not** add any other section. The user will add `***functional specs***` later via `add-functional-spec` / `add-functional-specs`, and any concepts via `add-concept`.
+
+The file must still be created on disk — an empty body is fine, but the file itself is required.
+
+### 5. Generate the testing scripts
+
+Call the corresponding implementation skills in order. Each skill writes a Bash script, which is what the harness runs.
+
+- `implement-unit-testing-script` — always. It runs the stack's static checks - formatter, linter, type checker - with the unit tests, and they count as the tests do.
+- `implement-conformance-testing-script` — only if conformance testing was enabled. The script is self-contained: it stages the build, installs dependencies, and runs the module's whole conformance suite.
+
+### 6. Check turri finds the scripts
+
+turri finds the testing scripts in the project root, not through the specs: first in `config.turri.yaml` (`unittests-script:`, `conformance-tests-script:`, paths relative to the root), then the one `run_unittests*.sh` / `run_conformance_tests*.sh` in the root, then the one of each kind in `test_scripts/`. It puts them into the prompts of the agents that write and run the tests itself, so do not link them from `template/base.plain` (a link to one is ignored). Confirm every generated script is in `test_scripts/` and is the only one of its kind there - or, if the project wants it, that a `config.turri.yaml` at the root names the one to use and the path resolves. A project with parts on different stacks (e.g. a Python backend and a React frontend sharing an imported `base`) keeps one `config.turri.yaml` for what they share and gives each stack its own `config.turri.<stack>.yaml` beside it - `config.turri.backend.yaml`, `config.turri.frontend.yaml` - naming that stack's `unittests-script:` and `conformance-tests-script:`. A stack is chosen, never worked out: tell the user to choose it with `/stack <stack>` (`--stack <stack>` on the command line) before building that part. When the project has only a `config.yaml`, copy it to `config.turri.yaml` first - and each `config.<name>.yaml` to `config.turri.<name>.yaml` - and write the copies; never write `config.yaml`.
+
+Do **not** run `validate` here — keeping this skill light is the whole point. The user can run it when they want validation.
+
+### 7. Recap
+
+Tell the user what was created and what's next:
+
+- Files written: `template/base.plain`, `<project>.plain`, the test scripts.
+- Suggested next steps: add concepts with `add-concept`, add functional specs with `add-functional-spec` or `add-functional-specs`, or jump straight into `bud`.
+- Mention that `validate` has not been run on `<project>.plain` yet.
+
+## Validation checklist
+
+Before the recap, walk `references/checklist.md` and confirm every box is met. It is a self-audit of this workflow — never a substitute for it. A box only counts as met when the file is on disk as described; complete any unmet step before recapping.
+
+## Question style
+
+Use simple grammatical structures: short direct sentences, one idea per sentence, plain words over jargon. Keep every constraint and edge case the user needs to answer accurately.

package/genome/skills/init-plain-project/references/checklist.md

@@ -0,0 +1,30 @@
+# Init Plain Project Workflow Checklist
+
+Use this to verify the scaffold was produced correctly — never as a substitute for the workflow. Run it once before the recap. This skill is intentionally minimal: it writes a runnable skeleton, not a complete spec. If a box is unmet, go back and complete the step.
+
+## Setup
+
+
+## Ask the basics
+
+- [ ] Asked the project basics with `ask_user`, one question per call (project name, base technology, project kind), plus a free-form catch-all.
+- [ ] Asked testing with `ask_user`, one question per call (unit-test framework, conformance on/off).
+
+## Author the modules
+
+- [ ] Created `template/base.plain` via `create-import-module` with `***implementation reqs***` (language/version, framework, package manager, project kind, and everything about `:UnitTests:` — framework + run command).
+- [ ] Added `***test reqs***` to `template/base.plain` with the `:ConformanceTests:` rules **only** when conformance testing is enabled — and kept unit-test facts out of it.
+- [ ] No `***definitions***`, no `***functional specs***`, and no project-specific concepts in `template/base.plain`; only predefined concepts (`:Implementation:`, `:ConformanceTests:`) used; no `required_concepts` declared.
+- [ ] Created `<project>.plain` at the repo root with frontmatter only (`import: [base]`, `description`) and **no body sections** — the file exists on disk.
+
+## Generate scripts
+
+- [ ] Generated `implement-unit-testing-script` (always).
+- [ ] The unit testing script runs the stack's static checks with the tests, exiting `80` when only the checks fail.
+- [ ] Generated `implement-conformance-testing-script` only if conformance was enabled.
+- [ ] Every generated script is in `test_scripts/`, the only one of its kind there - or named in a `config.turri.yaml` at the root (`unittests-script:`, `conformance-tests-script:`) - or, for a part on a stack of its own, in that stack's `config.turri.<stack>.yaml` - whose paths resolve. No script is linked from the specs.
+- [ ] Did **not** run `validate` or `check-plain-env` (out of scope for this skill).
+
+## Recap
+
+- [ ] Told the user what was written, suggested next steps (`add-concept`, `add-functional-spec(s)`, `bud`), and noted that `validate` has not been run.

package/genome/skills/mature/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: mature
+description: >-
+  Mature a rough `***plain` spec until it is fully rendered, on its own: the goal is the spec built
+  - every functionality from the spec as it stands, its tests passing - and the loop is render,
+  watch the agents building it, and when one struggles on something the spec leaves open or
+  unclear, settle it in the spec, stop that build and render again. It reads what the builds had to
+  decide themselves - assumptions, pitfalls, a failed build's diagnosis, a spec that contradicts
+  itself - and writes what the spec should have said, as spec diffs. It decides open choices itself
+  and records every decision; it does not ask. It stops when the spec is fully rendered, or when it
+  is stuck on something the spec cannot settle. Use when the user has a rough or hand-written spec
+  and wants it made to build without steering it. Not for starting from nothing (`brood`,
+  `spawn`) or adding a feature (`bud`).
+allowed-tools: [read, write, edit, bash, ls, grep, find, write_spec_diff, regenerate, drift, halt, watch_jobs, spec_findings]
+metadata:
+  # What each phase does, in a line - shown under the skill's progress while it runs.
+  phases:
+    intake: "reads the spec, checks it parses, and makes sure a build can start"
+    regenerate: "builds what is left, watches the builds, and settles what the spec leaves open"
+    report: "what was built, what struggled, and what was decided in the spec"
+  # It writes its fixes one after another, from what the builds show: no answer between them.
+  paced: false
+---
+
+# Mature
+
+Load the `***plain` syntax rules before writing anything - they are in the system prompt under
+`<plain-rules>`; read `genome/rules/<name>.md` for the full text of any rule you need to follow
+closely.
+
+## Role
+
+Act as a `***plain` spec writer who hardens a spec by building it, on your own, until it builds.
+
+**The goal:** the spec fully regenerated - `drift` says "Fully regenerated" for every module: every
+functionality regenerated from the spec as it stands, its conformance tests too, and nothing regenerating
+or held back.
+
+**The loop:** render what is not built; watch the agents building it; when one struggles on something
+the spec leaves open or unclear, settle it in the spec, stop that build, and render again.
+
+Where a spec is silent, the agent that renders it has to decide - a format, a default, an error, a
+rule - and when the decision is hard, or the spec reads two ways, it struggles: its tests keep
+failing, the judge keeps finding the tests or the code wrong, it runs far too long. Much of that is
+the spec's to settle, and once the spec says it, the next build does not struggle. Some of it is not
+- a bug the agent will fix, an environment problem, turri itself - and the spec stays out of
+that.
+
+You never ask the user: this runs on its own. Where the spec leaves a real choice, take the reading
+that best fits the rest of the spec, the intent it states and what the builds already did, write it,
+and record the decision for the report. You never change what the spec plainly means, never write the
+spec to match code that does something else, never add features, never touch generated code, and
+never edit a `.plain` file with the file tools once rendering has started - every change is a spec
+diff, with `write_spec_diff`.
+
+## Steps
+
+### intake
+
+1. Find the spec: the `.plain` file(s) the user named, or the project's modules. Read them whole,
+   with their `import` and `requires` chains, and the project's `config.turri.yaml` (or the old
+   `config.yaml`, when there is no `config.turri.yaml`) and each stack's `config.turri.<stack>.yaml`.
+2. Run `validate` on each, and fix only what stops it parsing - with the file tools, while nothing
+   is built from it yet, otherwise with `write_spec_diff`.
+3. Make sure a build can start: the unit testing script (and, with conformance tests on, the
+   conformance testing script) turri finds. When one is missing, write it by following the
+   `implement-unit-testing-script` (or `implement-conformance-testing-script`) skill, for the stack the
+   spec's implementation reqs name. The static checks - formatter, linter, type checker - are part of
+   the unit testing script, as that skill writes it.
+
+Say in two lines what will be rendered, and go on.
+
+### regenerate
+
+Run cycles until the goal is met - or you are stuck - and at most twenty. Each cycle:
+
+1. **Check the goal**: `drift` for every module. All fully regenerated: the goal is met - go to the report.
+2. **Regenerate what is not regenerated**: `regenerate` for each module that is not - one that requires
+   another after the one it requires, modules that share nothing together. A module with builds still
+   running or queued is left to them.
+3. **Watch**: `watch_jobs`. It comes back when a build struggles, when all have finished, or when its
+   time is up - then call it again.
+4. **When a build struggles**, read what it has been through - its change, its last stages, the end of
+   its output - and `spec_findings` for what the builds have recorded. Then judge:
+   - **The spec's to settle** - the spec is silent where the build needs a decision (a format, a
+     default, an error and its message, a limit, an order, an edge case); it reads two ways; two of
+     its specs conflict; a test and the code disagree over something the spec never said. Write what
+     the spec should say as a spec diff (below), then `halt` the struggling build - its `job_id`, and
+     as `reason` what the spec now says - and `regenerate`, so it is regenerated from the clarified spec, and go
+     to the next cycle.
+   - **Not the spec's** - a bug the agent is working through, a missing tool or package, a flaky
+     service, turri itself. Leave the build to it, note it for the report, and keep watching.
+     Stopping it would throw its work away for nothing.
+5. **When the builds finish**, read `spec_findings`, and write into the spec every assumption about
+   what the software does that a user, a caller or a test can see - as the build assumed it, unless
+   that is not what the spec meant - so the next build does not have to guess. An assumption about how
+   it is built inside - a library, a file layout, a name - stays out. A diagnosis that says the fix is
+   in the spec is written; one that says code, environment or turri is noted. Then the next
+   cycle: what failed, and what the new diffs changed, is rendered again.
+
+**Writing a fix.** A git diff of the `.plain` file(s), paths from the project root, a few lines of
+context, with `write_spec_diff`. One diff per concern - a functionality's missing rules together, a
+concept and what it means together - never one diff for everything. Put each where it belongs: a rule
+of one functionality into its functional spec, a policy for many into `***implementation reqs***`, a
+term into `***definitions***`, following `add-concept`, `add-functional-spec` and
+`add-implementation-requirement` for how it is written. Each diff is built as it is written: what is left
+to build is worked out again from the spec - only what it changes is rendered again.
+
+**When you are stuck, stop.** The same functionality struggling three times after you clarified the
+spec for it is not something the spec can settle: stop maturing it, and report it. Two cycles in a
+row with nothing newly built and nothing newly settled: stop, and report what is open. Twenty cycles:
+stop, and report.
+
+### report
+
+A short account:
+
+- whether the goal was met - `drift` for every module, as it is now;
+- every cycle in a line: what was rendered, what struggled, what you did about it;
+- every decision you wrote into the spec - what it settles, what the spec now says, and the spec diff
+  job that renders it - with the ones where you chose between readings marked, for the user to check;
+- what was not the spec's - code, environment, turri - with what the builds and diagnoses said;
+- what is still open, when you stopped before the goal.
+
+Then say that any further change is asked for in the conversation, as a spec diff: what is left to build
+is worked out again from the spec.

package/genome/skills/refactor-module/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: refactor-module
+description: >-
+  Split a large ***plain module into smaller modules grouped by logical domain.
+  The resulting modules are connected via a requires chain so that functionality
+  is 100% preserved. Use when a module has become too large and its functional
+  specs span multiple distinct concerns that would be clearer as separate modules.
+allowed-tools: [read, write, edit, bash, ls, grep, find]
+---
+
+# Refactor Module
+
+## When to Use
+
+- A module has many functional specs spanning multiple distinct domains or feature areas.
+- The module is hard to reason about because unrelated concerns are interleaved.
+- New features are difficult to add because the module's scope is too broad.
+- The user explicitly asks to split or reorganize a module.
+
+## Guiding Principle
+
+The refactoring is purely structural. The **combined behavior** of the resulting modules must be **identical** to the original module. No functional spec is added, removed, or weakened. The split is semantic — grouping related specs together — not behavioral.
+
+## Input
+
+The `.plain` file to refactor, plus guidance from the user on the desired grouping (or ask the user to confirm your proposed grouping).
+
+## Phase 1 — Analyze the Current Module
+
+1. **Read the entire `.plain` file** — frontmatter, definitions, implementation reqs, test reqs, and all functional specs. Also read any `import` and `requires` chains to understand the full context.
+2. **Inventory the functional specs.** Number each spec and note which `:Concepts:` it references. Build a dependency map: which specs depend on earlier specs (by referencing behavior or state they introduced)?
+3. **Inventory the definitions.** For each concept, note which functional specs reference it. Identify concepts that are used across multiple logical groups vs. concepts used only within one group.
+4. **Identify logical groups.** Look for natural seams — clusters of functional specs that share concepts, represent a cohesive domain, or describe a single feature area. Common groupings:
+   - Data model setup and CRUD operations
+   - Business logic and processing rules
+   - UI screens and navigation
+   - Integrations and external interfaces
+   - Statistics, reporting, and analytics
+5. **Verify group independence.** Each group's specs should form a contiguous or near-contiguous block in chronological order. If a group's specs are scattered and interleaved with other groups, the split boundary may need adjustment.
+
+## Phase 2 — Plan the Split
+
+Present the proposed split to the user and get explicit confirmation before making any changes.
+
+### 2a. Define the module chain
+
+The modules form a `requires` chain that preserves the original chronological ordering of functional specs. The first module in the chain contains the earliest specs; each subsequent module `requires` the previous one and adds the next logical group.
+
+```
+original-module
+  ↓ splits into
+module-group-a  (no requires — this is the new base)
+module-group-b  (requires: module-group-a)
+module-group-c  (requires: module-group-b)
+```
+
+If the original module already had `requires` or `import` dependencies, the first new module inherits them.
+
+### 2b. Assign functional specs to modules
+
+Place each functional spec in exactly one module. The placement must respect chronological ordering:
+- Within each module, the specs appear in the same relative order as in the original.
+- Across the chain, the ordering is preserved: all specs in module A come before all specs in module B, which come before all specs in module C.
+- A spec **cannot** move to an earlier module than a spec it depends on.
+
+### 2c. Assign definitions to modules
+
+For each concept, determine where it belongs:
+
+| Concept usage | Placement |
+|---------------|-----------|
+| Used only within one module's specs | Define in that module |
+| Used across multiple modules in the chain | Define in the first module that uses it, and add to that module's `exported_concepts` |
+| Already defined in an import template | Leave in the import — no change needed |
+
+If many concepts are shared across all modules, consider creating a new import module (template) to hold them. This avoids long `exported_concepts` lists and keeps definitions centralized. Use the `create-import-module` skill for this.
+
+### 2d. Assign implementation reqs and test reqs
+
+- Reqs that apply to all modules should live in a shared import template. If one already exists, keep them there.
+- Reqs specific to a single module's domain move to that module.
+- When in doubt, keep reqs in the shared template — duplication across modules is worse than a slightly broad template.
+
+### 2e. Present the plan
+
+Summarize for the user:
+- Number of resulting modules and their names
+- Which functional specs go in each module (listed by number or short description)
+- The `requires` chain order
+- Any new import module being created
+- Which concepts are exported from each module
+- Confirmation that all original specs are accounted for (none lost)
+
+Get explicit user confirmation before proceeding.
+
+## Phase 3 — Execute the Split
+
+Create the new modules in order, from the base of the chain upward.
+
+### 3a. Create or update the import template (if needed)
+
+If shared definitions or reqs are being moved to a new import template, create it first using the `create-import-module` skill.
+
+### 3b. Create the base module
+
+Create the first module in the chain:
+1. Set the YAML frontmatter — inherit the original module's `import` references. Add `exported_concepts` for any concepts that downstream modules need.
+2. Add the `***definitions***` section with concepts used by this module's specs and concepts that need to be exported.
+3. Add `***implementation reqs***` and `***test reqs***` specific to this module (if not fully covered by the import template).
+4. Add the `***functional specs***` assigned to this module, preserving their original order and exact wording.
+5. Carry over any `***acceptance tests***` nested under the moved functional specs.
+
+### 3c. Create subsequent modules
+
+For each subsequent module in the chain:
+1. Set `requires` to point to the previous module in the chain. Set `import` if it uses shared templates.
+2. Add `exported_concepts` for any concepts that later modules in the chain need.
+3. Add `***definitions***` for concepts local to this module. Do **not** redefine concepts already available via `requires` (exported) or `import`.
+4. Add `***implementation reqs***` and `***test reqs***` specific to this module.
+5. Add the `***functional specs***` assigned to this module, preserving their original order and exact wording.
+6. Carry over any `***acceptance tests***`.
+
+### 3d. Handle the original module file
+
+After all new modules are created:
+- If the original module is being fully replaced (all specs moved out), delete it or rename it to avoid confusion.
+- If the original module was required by other modules, update those modules to `require` the last module in the new chain instead — its accumulated code and previous functional specs cover the whole chain. Exported concepts are **not** transitive, though: if a downstream module references a concept now exported by an earlier module in the new chain, it must list that earlier module in its `requires` as well.
+
+## Phase 4 — Verify
+
+### 4a. Completeness check
+
+This is the most critical verification. Walk through every functional spec from the original module and confirm it appears in exactly one of the new modules. Nothing may be lost, weakened, modified, or left implicit.
+
+Checklist:
+- [ ] Total spec count across all new modules equals the original spec count
+- [ ] Each spec's text is identical to the original (no rewording)
+- [ ] Each spec's acceptance tests (if any) are carried over intact
+
+### 4b. Chronological ordering check
+
+Verify that the chronological order of all functional specs — when read across the requires chain from base to leaf — matches the original ordering exactly. A spec must not appear before a spec it depends on.
+
+### 4c. Concept availability check
+
+For each module, verify:
+- [ ] Every `:Concept:` referenced in its specs is either defined locally, available via `import`, or available via `exported_concepts` from a module listed in `requires`
+- [ ] `exported_concepts` includes every concept that downstream modules need
+- [ ] No concept name collisions between modules
+
+### 4d. Structural validation per module
+
+For each new module:
+- [ ] Has at least one functional spec and one implementation req
+- [ ] YAML frontmatter is correctly formatted
+- [ ] `requires` and `import` paths are correct
+- [ ] Module file is at the repository root (not in `template/`)
+- [ ] Specs are language-agnostic
+- [ ] All external interfaces remain explicit
+
+### 4e. Read all new modules
+
+Read each new `.plain` file in full and present the final structure to the user for approval. If the user requests changes, apply them and re-verify.
+
+## Common Pitfalls
+
+### Splitting too aggressively
+Creating many tiny modules with 1–2 specs each adds overhead without clarity. Aim for modules with 3–10 functional specs each, grouped around a cohesive theme.
+
+### Breaking chronological order
+Specs that set up foundational behavior (entry point, database init, core CRUD) must stay in the base module even if they touch concepts from multiple domains. Only split when specs are cleanly separable.
+
+### Forgetting exported_concepts
+If a concept defined in module A is referenced by a spec in module B (which requires A), the concept must be in A's `exported_concepts`. Missing exports cause rendering failures.
+
+### Modifying spec text during the split
+This is a refactoring, not a rewrite. Spec text must be copied verbatim. If a spec needs rewording to work in its new module context, that is a sign the split boundary is wrong — adjust the grouping instead.
+
+### Losing acceptance tests
+Acceptance tests are nested under their parent functional spec. When moving a spec to a new module, its acceptance tests must move with it.
+
+## Validation Checklist
+
+- [ ] User confirmed the split plan before execution
+- [ ] All original functional specs are present in exactly one new module — none lost
+- [ ] Spec text is identical to the original — no rewording
+- [ ] Acceptance tests moved with their parent specs
+- [ ] Chronological order preserved across the requires chain
+- [ ] Every referenced `:Concept:` is available in each module (local, import, or exported)
+- [ ] `exported_concepts` are correctly set on each module
+- [ ] No concept name collisions
+- [ ] Each module has at least one functional spec and one implementation req
+- [ ] `requires` chain is correctly ordered (base → leaf)
+- [ ] Original module removed or updated
+- [ ] Downstream modules (if any) updated to require the chain tip, plus any earlier chain modules whose exported concepts they reference
+- [ ] User approved the final result