craftkit 0.3.0__py3-none-any.whl

craft_kit/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: craft
+description: Recreate or build any software — a website, CLI, desktop app, game, library or service — by studying an original (or a plain request), building a new project, checking it against the original with measurable checks, and refining until it passes. Use when asked to "recreate", "clone", "rebuild", "make my own version of", or "build something like" an existing site, program or tool, or to build a new tool from a description with verification. Works with or without the `craft` CLI.
+---
+
+# Craft: study → build → check → refine
+
+A method for rebuilding any piece of software from evidence, then proving the result is close.
+It works the same for a website, a command-line tool, a desktop app, a game or a library. Follow
+the five stages in order; never skip Check.
+
+If the `craft` command is installed (`craft --version`), it does the bookkeeping for you: use
+`craft new`, `craft study`, `craft check --self` and `craft status` at the matching stages. Without
+it, do each stage by hand as written below. The folder layout and contracts are the same either way.
+
+## 0. Intake (one minute, before anything else)
+
+Settle five things. Ask the person only for what you can't infer, in one message, with 2-4 choices
+per question.
+
+| Field   | Values | Default |
+|---------|--------|---------|
+| Request | what they want, in their words | (required) |
+| Target  | a URL, a file or folder, a command on PATH, or none | none: build from the request |
+| Kind    | `website`, `cli`, `app`, `game`, `tool` (library/API/service) | from the request's words |
+| Stack   | whatever the request names | the simplest stack that fits; for a website, whatever the original visibly uses |
+| Mode    | **Clean room** or **Deep** | Clean room |
+
+- **Clean room**: use only what a visitor or user sees: screenshots, visible text and measured
+  layout of a site; what a program prints when run (only with the person's OK to run it); pictures
+  the person provides. Never open, read, fetch or decompile the original's files, page source or
+  program.
+- **Deep** (the person must say so, for private use): you may look inside: a site's HTML and
+  scripts, a folder's files, a program's strings and code. Rebuild what you learn in your own code;
+  never paste the original's code or assets into the build.
+
+The request always wins over defaults: if it names a language, framework or engine, use exactly
+that, and never switch away from it to get past a failing build.
+
+## 1. Workspace
+
+Create one project folder (`craft new` does this):
+
+```text
+<project>/
+  craft.json       request, target, kind, stack, mode, round counters (versioned)
+  BRIEF.md         the task as given to the builder
+  capture/         evidence from Study — README.md first. Read-only.
+  reference/       pictures/files from the person. Read-only.
+  app/             THE ONLY FOLDER THE BUILD CHANGES
+  checks/round-N/  each check: result.json, screenshots, logs
+  checks/turn-N/   each builder turn: message sent, log, reply
+  unknowns.md      open questions about the original
+  questions.json   questions for the person, with their answers
+```
+
+Keeping evidence (`capture/`) apart from the build (`app/`) is what makes the checks honest.
+
+## 2. Study — gather evidence into `capture/`
+
+Overview first, details after. Write `capture/README.md` as the index of everything you found.
+
+| Target | Clean room | Deep adds |
+|--------|------------|-----------|
+| Website | full-page screenshots at **1440, 768, 390 px** (`screenshot-<w>.png`); visible facts: title, headings, navigation, buttons, computed fonts/colours/sizes, section count, visible text | the served HTML (`page.html`), scripts, network requests |
+| CLI program | with permission, run it with no args, `--help`, `--version`, `-h` (stdin closed, 10 s limit); record exit code + output in `runs.json` | its strings (`strings.txt`), file type |
+| App / game | the person's pictures in `reference/`; a screenshot of its window if allowed | its files, manifests, config values, strings |
+| Folder / repo | nothing inside is read | inventory by file type, manifests (package.json, Cargo.toml…), README |
+| None | the request alone | — |
+
+Record each question the evidence doesn't answer in `unknowns.md`:
+
+```text
+- [ ] Does the menu collapse on phones? — open it at 390 px — impact: high
+```
+
+Tick it later with the answer and the evidence that settled it. Missing evidence is never proof:
+mark what you estimate.
+
+## 3. Build — only inside `app/`
+
+1. **Plan**: 3-7 plain-language steps at the top of `app/PLAN.md`; tick them as you go.
+2. **Build** in the chosen stack until the build command succeeds.
+3. **Declare** how the build is built, tested and run in `app/craft-app.json` (commands are lists
+   run inside `app/`; leave out what doesn't apply):
+
+   ```json
+   {"version": 1, "install": ["npm", "install"], "build": ["npm", "run", "build"],
+    "test": ["npm", "test"], "run": ["node", "dist/main.js"], "site": "dist"}
+   ```
+
+4. **Meet the kind's contract** — this is what Check runs:
+
+| Kind | Contract |
+|------|----------|
+| website | static files with `index.html` at the top of `site`; each page at its own path; no sideways scroll on a phone |
+| cli | `run` prints the same as the original for each recorded input and exits with the same code |
+| app | `run --screenshot <file.png>`: start, draw ~2 s, save the window as PNG, exit |
+| game | `--screenshot` as above, plus `run --self-test <file.json>`: play the core loop with scripted input and write `{"version":1,"steps":[{"step":"move","passed":true,"detail":"…"},{"step":"act",…},{"step":"hud",…}]}` measured from the game's own state |
+| tool | tests that prove each feature the request names |
+
+Rules while building:
+- Rebuild layout, style and behaviour from the evidence. No logos, photos, brand names or long
+  copied text unless the person owns them or has permission; use neutral placeholders.
+- Ask the person only about choices that change the result (write `questions.json` with 2-4
+  choices, keep building what doesn't depend on it). Never ask about technical details.
+- Build everything asked. If part of it won't fit, ask before dropping it; never drop it silently.
+- Never start dev servers or watchers (`npm run dev`, `vite`, `cargo watch`): Check serves and runs
+  the build itself.
+
+## 4. Check — measure, don't guess
+
+Run the same checks every round (`craft check --self` while building; `craft check` records a
+round). Stop at the first failing build: nothing else can be judged.
+
+| Check | Applies to | Passes when |
+|-------|-----------|-------------|
+| build | all | install + build commands exit 0 |
+| web | website | serve `site` on 127.0.0.1, screenshot at the same three widths, compare with `capture/` per width; similarity ≥ the threshold (default 90%) |
+| runs | cli | every recorded input: same exit code, ≥ 80% of printed words in common |
+| screenshot | app, game | a readable, non-blank PNG; compared with `reference/` pictures when present |
+| selftest | game | every core-loop step (move, act, hud) passes |
+| tests | all | the project's tests pass ("no tests" is noted, not a failure) |
+
+A check that couldn't look (no browser, no recording) says so: it's "not judged", never "passed".
+Save each round's result as `checks/round-N/result.json`.
+
+## 5. Refine — then Ready
+
+- Feed the failing checks back as the next task: biggest visible or functional differences first,
+  with the measured numbers. Rebuild, re-check.
+- Stop when every check passes, **or** after **6 refinements per request** (the count survives
+  retries; only a new request resets it), **or** when two turns in a row change nothing in `app/`
+  (stuck: ask the person for detail instead of looping).
+- Before finishing, re-read `PLAN.md` and `unknowns.md`; settle what one more look can settle.
+
+**Ready** = a summary for the person in 3-5 plain sentences: what was built, what differs from
+the original or is still unknown, and one idea for what to ask next. No code, no file paths. Then
+how to open it (`craft open`) and how to ask for a change (`craft run "…"`).
+
+## Honesty rules (always)
+
+- Never claim something works that you didn't run. Report what you verified and what you didn't.
+- Every external program you start gets a time limit and no interactive stdin.
+- Keep secrets out of the project: no keys or tokens in `app/`, `capture/` or logs.

craft_kit/__init__.py

@@ -0,0 +1,3 @@
+"""craft-kit: study → build → check → refine any software, from the terminal."""
+
+__version__ = "0.3.0"

craft_kit/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

craft_kit/agent.py

@@ -0,0 +1,165 @@
+"""One builder turn: hand a message to a coding-agent CLI on stdin, show what it does on one live
+line, and return its final reply."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+from . import proc, tables
+from .ui import UI
+from .workspace import CraftError, Project, write_atomic
+
+TURN_TIMEOUT = float(os.environ.get("CRAFT_TURN_TIMEOUT", 3 * 3600))
+IDLE_TIMEOUT = float(os.environ.get("CRAFT_IDLE_TIMEOUT", 20 * 60))
+
+
+def pick(name: Optional[str]) -> tuple[str, dict]:
+    table = tables.agents()
+    name = name or os.environ.get("CRAFT_AGENT")
+    if name:
+        if name == "none":
+            raise CraftError("No agent: the brief is in BRIEF.md.", "Paste BRIEF.md into any coding agent opened in this folder, then run `craft check`.")
+        if name not in table:
+            raise CraftError(f"Unknown agent “{name}”.", f"Known: {', '.join(table)}. Add one in {tables.config_dir() / 'agents.json'}.")
+        return name, table[name]
+    for n in tables.AGENT_ORDER:
+        if n in table and proc.which(table[n]["argv"][0]):
+            return n, table[n]
+    raise CraftError("No coding agent found (claude, codex or gemini).", "Install one, or use `craft brief` and paste it into the agent you use, then `craft check`.")
+
+
+TOOL_KINDS = {
+    "Read": "read", "NotebookRead": "read", "LS": "read",
+    "Edit": "edit", "MultiEdit": "edit", "NotebookEdit": "edit",
+    "Write": "write",
+    "Bash": "run", "BashOutput": "run", "KillShell": "run",
+    "Grep": "search", "Glob": "search",
+    "WebFetch": "web", "WebSearch": "web",
+    "TodoWrite": "plan", "Task": "agent", "Agent": "agent",
+}
+
+
+class _Claude:
+    """Reads Claude Code's stream-json: every action for the live feed, the final reply and session id."""
+
+    def __init__(self, live, root: str = ""):
+        self.live = live
+        self.root = root.rstrip("/") + "/" if root else ""
+        self.reply = ""
+        self.session: Optional[str] = None
+        self.is_error = False
+        self._started = False
+
+    def __call__(self, line: str) -> None:
+        try:
+            ev = json.loads(line)
+        except ValueError:
+            return
+        if not isinstance(ev, dict):
+            return
+        if ev.get("session_id"):
+            self.session = ev["session_id"]
+        kind = ev.get("type")
+        if kind == "system" and ev.get("subtype") == "init" and not self._started:
+            self._started = True
+            model = ev.get("model")
+            self.live.event("agent", f"session started{f' · {model}' if isinstance(model, str) else ''}", count=False)
+        elif kind == "assistant":
+            for item in (ev.get("message") or {}).get("content") or []:
+                if not isinstance(item, dict):
+                    continue
+                if item.get("type") == "tool_use":
+                    name = str(item.get("name", ""))
+                    self.live.event(_tool_kind(name), _describe_tool(name, item.get("input") or {}, self.root))
+                elif item.get("type") == "text" and isinstance(item.get("text"), str):
+                    first = next((ln for ln in item["text"].strip().splitlines() if ln.strip()), "")
+                    self.live.event("say", first)
+        elif kind == "user":
+            for item in (ev.get("message") or {}).get("content") or []:
+                if isinstance(item, dict) and item.get("type") == "tool_result" and item.get("is_error"):
+                    self.live.event("fail", _first_line(item.get("content")) or "a tool call failed")
+        elif kind == "result":
+            self.reply = str(ev.get("result") or "")
+            self.is_error = bool(ev.get("is_error"))
+
+
+def _tool_kind(name: str) -> str:
+    return TOOL_KINDS.get(name, "tool")
+
+
+def _first_line(content) -> str:
+    if isinstance(content, list):
+        content = " ".join(c.get("text", "") for c in content if isinstance(c, dict) and isinstance(c.get("text"), str))
+    if not isinstance(content, str):
+        return ""
+    return next((ln.strip() for ln in content.splitlines() if ln.strip()), "")
+
+
+def _describe_tool(name: str, args: dict, root: str = "") -> str:
+    def rel(v: str) -> str:
+        return v[len(root):] if root and v.startswith(root) else v
+
+    if name == "TodoWrite" and isinstance(args.get("todos"), list):
+        todos = [t for t in args["todos"] if isinstance(t, dict)]
+        done = sum(1 for t in todos if t.get("status") == "completed")
+        active = [t.get("activeForm") or t.get("content") for t in todos if t.get("status") == "in_progress"]
+        now = active[0] if active and isinstance(active[0], str) else ("all done" if todos and done == len(todos) else "updating the plan")
+        return f"{done}/{len(todos)} · {now}" if todos else now
+    if name in ("Task", "Agent") and isinstance(args.get("description"), str):
+        return args["description"]
+    if name in ("Grep", "Glob") and isinstance(args.get("pattern"), str):
+        where = rel(args["path"]) if isinstance(args.get("path"), str) else ""
+        return args["pattern"] + (f"  in {where}" if where else "")
+    if name == "Bash" and isinstance(args.get("command"), str):
+        return args["command"].strip().splitlines()[0] if args["command"].strip() else "(empty command)"
+    for key in ("file_path", "notebook_path", "path", "pattern", "url", "query", "command"):
+        if isinstance(args.get(key), str):
+            text = rel(args[key])
+            return text if name in TOOL_KINDS else f"{name.split('__')[-1]} {text}"
+    return name.split("__")[-1] or name
+
+
+def turn(p: Project, message: str, ui: UI, agent: Optional[str], label: str) -> str:
+    name, spec = pick(agent or p.state.get("agent"))
+    p.state["agent"] = name
+    p.state["turns"] = p.state.get("turns", 0) + 1
+    rd = p.root / "checks" / f"turn-{p.state['turns']}"
+    rd.mkdir(parents=True, exist_ok=True)
+    write_atomic(rd / "message.md", message)
+    p.log(f"turn ({name}): {label}")
+    for attempt in (1, 2):
+        argv = list(spec["argv"])
+        session = p.state.get("session")
+        if session and spec.get("resume"):
+            argv += [a.replace("{session}", session) for a in spec["resume"]]
+        stage = "refine" if label.startswith("refin") else "build"
+        with ui.live(f"{label} · {name}", stage) as live:
+            reader = _Claude(live, str(p.root)) if spec.get("stream") == "claude-json" else None
+
+            def on_line(line: str) -> None:
+                if reader is not None:
+                    reader(line)
+                elif line.strip():
+                    live.event("out", line.strip())
+
+            r = proc.run(argv, cwd=str(p.root), timeout=TURN_TIMEOUT, idle=IDLE_TIMEOUT, input_text=message, on_line=on_line)
+        ui.say(f"   {ui.dim('└ ' + live.tally())}")
+        write_atomic(rd / "agent.log", r.output)
+        lost = spec.get("lost")
+        if attempt == 1 and session and lost and lost in r.output:
+            ui.note("The agent's saved conversation isn't on this computer; starting a fresh one.")
+            p.state["session"] = None
+            p.save()
+            continue  # the next message points it at BRIEF.md anyway
+        break
+    if reader is not None and reader.session:
+        p.state["session"] = reader.session
+    p.save()
+    if not r.ok or (reader is not None and reader.is_error):
+        why = r.error or (f"exit {r.code}" if r.code else "it reported an error")
+        raise CraftError(f"{name} stopped: {why}.\n{r.tail(12)}", f"Full output: {rd / 'agent.log'}. Fix the cause, then `craft run` carries on.")
+    reply = reader.reply if reader is not None else r.tail(40)
+    write_atomic(rd / "reply.md", reply)
+    return reply

craft_kit/banner.py

@@ -0,0 +1,86 @@
+"""The "CRAFT KIT" title: block letters leaning right (italic), in a gradient where blue dominates."""
+
+from __future__ import annotations
+
+import os
+
+GLYPHS = {
+    "C": [" █████", "██    ", "██    ", "██    ", " █████"],
+    "R": ["█████ ", "██  ██", "█████ ", "██ ██ ", "██  ██"],
+    "A": [" ████ ", "██  ██", "██████", "██  ██", "██  ██"],
+    "F": ["██████", "██    ", "█████ ", "██    ", "██    "],
+    "T": ["██████", "  ██  ", "  ██  ", "  ██  ", "  ██  "],
+    "K": ["██  ██", "██ ██ ", "████  ", "██ ██ ", "██  ██"],
+    "I": ["██", "██", "██", "██", "██"],
+    " ": ["   "] * 5,
+}
+
+# Colour stops (position 0..1, RGB): sky → azure → royal blue → indigo, a touch of violet and pink at the end.
+STOPS = [
+    (0.00, (70, 210, 255)),
+    (0.22, (40, 150, 255)),
+    (0.50, (45, 95, 245)),
+    (0.72, (80, 70, 235)),
+    (0.88, (150, 85, 250)),
+    (1.00, (240, 95, 200)),
+]
+SLANT = 1  # columns each row moves left from the top: the letters lean like italics
+
+
+def truecolor() -> bool:
+    return os.environ.get("COLORTERM", "").lower() in ("truecolor", "24bit") or os.environ.get("TERM_PROGRAM") in ("iTerm.app", "vscode", "WezTerm", "ghostty")
+
+
+def colour_at(t: float) -> tuple[int, int, int]:
+    t = min(1.0, max(0.0, t))
+    for (p0, c0), (p1, c1) in zip(STOPS, STOPS[1:]):
+        if t <= p1:
+            k = (t - p0) / (p1 - p0) if p1 > p0 else 0.0
+            return tuple(round(a + (b - a) * k) for a, b in zip(c0, c1))  # type: ignore[return-value]
+    return STOPS[-1][1]
+
+
+def fg(rgb: tuple[int, int, int]) -> str:
+    if truecolor():
+        return "\033[38;2;{};{};{}m".format(*rgb)
+    r, g, b = (round(v / 255 * 5) for v in rgb)  # nearest colour of the 256-colour cube
+    return f"\033[38;5;{16 + 36 * r + 6 * g + b}m"
+
+
+def gradient(text: str, italic: bool = True, bold: bool = False) -> str:
+    """Colour a line of text along the gradient."""
+    chars = list(text)
+    n = max(1, len(chars) - 1)
+    style = ("\033[3m" if italic else "") + ("\033[1m" if bold else "")
+    return "".join(f"{style}{fg(colour_at(i / n))}{ch}" if ch != " " else ch for i, ch in enumerate(chars)) + "\033[0m"
+
+
+def big_lines(word: str = "CRAFT KIT") -> list[str]:
+    rows = [""] * 5
+    for ch in word.upper():
+        glyph = GLYPHS.get(ch, GLYPHS[" "])
+        for r in range(5):
+            rows[r] += glyph[r] + " "
+    return [" " * (SLANT * (4 - r)) + row.rstrip() for r, row in enumerate(rows)]
+
+
+def render(width: int, fancy: bool, indent: int = 2) -> list[str]:
+    """The title as lines ready to print: big letters when there's room, one styled line otherwise."""
+    lines = big_lines()
+    longest = max(len(line) for line in lines)
+    if not fancy:
+        return [" " * indent + "C R A F T   K I T"]
+    if longest + indent > width:
+        return [" " * indent + gradient("C R A F T   K I T", bold=True)]
+    out = []
+    for line in lines:
+        cells = []
+        r = len(out)
+        for x, ch in enumerate(line):
+            if ch == " ":
+                cells.append(" ")
+            else:
+                # A slightly diagonal gradient: each letter shades from top-left to bottom-right.
+                cells.append(f"\033[3m\033[1m{fg(colour_at((x + 2 * r) / (longest + 8)))}{ch}")
+        out.append(" " * indent + "".join(cells) + "\033[0m")
+    return out

craft_kit/brief.py

@@ -0,0 +1,101 @@
+"""What the builder is told: the first brief, refinements, follow-ups, answers."""
+
+from __future__ import annotations
+
+from . import tables
+from .workspace import Project
+
+RULES = """Rules:
+- The request comes first. When it names a language, framework, engine or platform, use exactly that; the stack below is only the default for what it leaves open. Never switch away from what was asked to get past a failing build: fix the build.
+- Change files only inside app/. Everything else here is read-only evidence.
+- Rebuild layout, styling and behaviour yourself from the evidence. Don't copy logos, photos, brand names or long passages of text unless the person says they own them or have permission; use neutral placeholders instead.
+- Ask the person only about choices that really change the result, never about technical details you can decide (see "Asking" below).
+- Build everything that was asked for. If part of it won't fit this version, ask before leaving it out, with the smaller version as one choice; never drop it silently.
+- Never start dev servers, watchers or anything that doesn't exit (npm run dev, vite, cargo watch). The checks serve and run the build themselves.
+- Never claim something works that you didn't run. Missing evidence isn't proof: mark what you estimated.
+- Finish with 3-5 plain sentences for the person: what you built, what differs from the original or is still unknown, and one idea for what to ask next. No code and no file paths in that summary."""
+
+CONTRACTS = {
+    "website": 'The site must build to static files: index.html at the top of a folder, each other page at its own path, working when served as plain files. Name that folder in app/craft-app.json as "site" (for example "dist"; "." for plain HTML in app/). It is photographed at 1440, 768 and 390 px wide and compared with capture/screenshot-<width>.png; it must never scroll sideways on a phone.',
+    "cli": 'Declare "run" in app/craft-app.json (for example ["python3", "main.py"] or ["./target/debug/tool"], relative to app/). The check runs it with each input in capture/runs.json and compares the exit code and the printed words with the original\'s.',
+    "app": 'Declare "run" in app/craft-app.json. Give the program a `--screenshot <file.png>` option: start normally, draw about two seconds of frames, save the window as a PNG to that file and exit. The check runs it that way; a missing or one-colour picture fails.',
+    "game": 'Declare "run" in app/craft-app.json. Give the game `--screenshot <file.png>` (start, draw about two seconds, save the window as PNG, exit) and `--self-test <file.json>`: start a game as a player would, drive it with scripted input for a few seconds, measure from the game\'s own state whether each part of the core loop works, write {"version": 1, "steps": [{"step": "move", "passed": true, "detail": "walked 3 cells"}, {"step": "act", "passed": true, "detail": "…"}, {"step": "hud", "passed": true, "detail": "score and lives drawn"}]} and exit. The game isn\'t ready until every step passes.',
+    "tool": "Write tests that prove the features the request names, and declare how to run them in app/craft-app.json.",
+}
+
+ASKING = """Asking: when a decision is really the person's, write questions.json in the project folder (not in app/):
+{"version": 1, "questions": [{"id": "q1", "question": "Keep the dark theme?", "choices": ["Yes, dark", "Light", "Both, with a switch"]}]}
+with 2-4 short choices each, then end your turn with a one-line reason. Their answers arrive in the next message. Keep building whatever doesn't depend on the answer first."""
+
+
+def mode_text(p: Project) -> str:
+    if p.deep:
+        return ("Deep mode, for the person's private use: you may look inside the original (its files, its code, a site's HTML and scripts) "
+                "to learn how it works. Rebuild what you learn in your own code; never paste the original's code or assets into app/.")
+    return ("Clean room: work only from what a visitor or user can see: the screenshots, measurements and runs in capture/, the pictures in reference/ "
+            "and the person's words. Never open, read, fetch, run or decompile the original's files, folder, page source or program yourself.")
+
+
+def target_text(p: Project) -> str:
+    t = p.state["target"]
+    return {"website": f"the website {t['value']}", "local": f"the program or folder at {t['value']}"}.get(t["type"], "nothing specific (build from the request)")
+
+
+def first(p: Project) -> str:
+    kind = tables.KINDS.get(p.state["kind"], tables.KINDS["tool"])
+    stack = tables.stack_by_name(p.state["stack"])
+    self_check = "Run `craft check --self` in the project folder: it runs exactly the checks that judge your work and lists what differs. Fix, build and check again until it passes."
+    return f"""You are the builder in a craft project: rebuilding software from evidence for a person who may not code.
+
+Request: "{p.state['request']}"
+Target: {target_text(p)}
+What to build: {kind['goal']}.
+Project folder (your working directory): {p.root}
+
+{mode_text(p)}
+
+The folder:
+- capture/   evidence gathered by Study. Start with capture/README.md, then open every screenshot and file it lists.
+- reference/ pictures or files the person added. Look at each.
+- app/       the only folder you change. The whole build lives here.
+- checks/    results of earlier checks (round-N/result.json, screenshots, logs).
+- unknowns.md  questions the evidence doesn't answer yet; you keep it up to date.
+
+How to build it, unless the request says otherwise: {stack['steps']}
+
+Declare how your build is built, tested and run in app/craft-app.json, each command a list of program and arguments run in app/:
+{{"version": 1, "install": ["npm", "install"], "build": ["npm", "run", "build"], "test": ["npm", "test"], "run": ["node", "dist/main.js"], "site": "dist"}}
+(leave out what doesn't apply). {CONTRACTS.get(p.state['kind'], CONTRACTS['tool'])}
+
+How to work:
+1) Study the evidence, overview first. Where a gap matters to the result, look again (Deep) or ask (Clean room) instead of guessing. Add each open question to unknowns.md as `- [ ] question — what would settle it — impact: high|medium|low`; tick it with the answer and its evidence when settled, and until then say what you did instead (an estimate, a placeholder, a question).
+2) Plan: write 3-7 plain-language steps at the top of app/PLAN.md and tick them as you go.
+3) Build it in app/ and fix errors until the build succeeds.
+4) Test it against the original. {self_check} If `craft` isn't available, run the build, tests and the contract above yourself.
+5) Before you reply, go through PLAN.md and unknowns.md once more: settle what one more look can settle, and say what's left.
+
+{RULES}
+
+{ASKING}"""
+
+
+def refine(p: Project, check_text: str, answers: str = "") -> str:
+    return f"""{check_text}
+
+Fix this in app/ (biggest visible or functional differences first), build again until it succeeds, re-run the check, and reply with 1-2 plain sentences on what you changed. The full task is in BRIEF.md if you need it again.{answers}"""
+
+
+def follow_up(p: Project, message: str, answers: str = "") -> str:
+    return f"""The person asks for a change to the build: "{message}"
+
+Keep what works and change only what this needs, in app/. Build and check again until it passes, then reply with 2-3 plain sentences on what changed. The original task and rules are in BRIEF.md.{answers}"""
+
+
+def resume(p: Project, answers: str = "") -> str:
+    return f"""Carry on with the build where you left off. The task and rules are in BRIEF.md; app/PLAN.md, unknowns.md and checks/ show where things stand.{answers}"""
+
+
+def answers_text(answered: list[dict]) -> str:
+    if not answered:
+        return ""
+    return "\n\nThe person answered your questions:\n" + "\n".join(f"- {q['question']} → {q['answer']}" for q in answered)