zames_pro 2.77.1 → 2.78.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.78.0] - 2026-10-18
+
+### Added
+
+- **skills:** ship the methodology skills inside the package
+
+### Fixed
+
+- **fsutil:** remove the temp file when an atomic write fails
+
 ## [2.77.1] - 2026-10-17
 
 ### Fixed

package/dist/context.js

@@ -2,6 +2,7 @@ import fs from 'fs/promises';
 import { statSync } from 'fs';
 import path from 'path';
 import os from 'os';
+import { fileURLToPath } from 'url';
 // Built-in skills, always available unless a project/global skill with the
 // same name overrides them (real files win). They give the agent proven,
 // reusable workflows in the spirit of Claude Code / Codex. English only (the
@@ -362,6 +363,20 @@ export async function loadSkills(workdir) {
         dir: path.join(os.homedir(), '.claude', 'skills'),
         source: 'global',
     });
+    // The skills SHIPPED with the package. In the installed layout they sit next
+    // to `dist/`; in a development checkout that path resolves INSIDE the repo
+    // (`src/../skills`), where the same skills also exist as files. The built-in
+    // copies (BUILTIN_SKILLS, appended below with an inline body) are the
+    // canonical ones — adding the files here would override them and break
+    // `/skill-name` expansion and the offline docs. So only add the directory when
+    // the module runs from the built `dist/` layout.
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    if (!moduleDir.endsWith(path.sep + 'src')) {
+        roots.push({
+            dir: path.join(moduleDir, '..', 'skills'),
+            source: 'global',
+        });
+    }
     for (const root of roots) {
         const files = await findSkillFiles(root.dir);
         for (const f of files) {

package/dist/fsutil.js

@@ -20,15 +20,27 @@ export function writeFileAtomic(file, data) {
     // fsync the file BEFORE rename: without it a power loss can leave the
     // renamed name pointing at an empty/partial inode (rename itself is atomic,
     // but the data blocks may not have reached the disk yet).
-    const fd = fs.openSync(tmp, 'w', 0o600);
     try {
-        fs.writeFileSync(fd, data);
-        fs.fsyncSync(fd);
+        const fd = fs.openSync(tmp, 'w', 0o600);
+        try {
+            fs.writeFileSync(fd, data);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, file);
     }
-    finally {
-        fs.closeSync(fd);
+    catch (e) {
+        // A failed write/fsync/rename (full disk, EIO, a directory in the way)
+        // must not leave the temp file behind: every failure used to accumulate a
+        // stray `<file>.tmp-<pid>` next to the real file.
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { }
+        throw e;
     }
-    fs.renameSync(tmp, file);
     // fsync the DIRECTORY so the rename entry itself is durable.
     try {
         const dirFd = fs.openSync(path.dirname(file), 'r');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zames_pro",
-  "version": "2.77.1",
+  "version": "2.78.0",
   "description": "Terminal coding agent that drives a real browser to chat with DeepSeek, Qwen and other web LLMs — no API key required. Reads and edits files, runs commands, commits to git, like Claude Code / Codex CLI.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "scripts/postinstall.mjs",
     "README.md",
     "CHANGELOG.md",

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: brainstorming
+description: Use when the operator's request is a GOAL, not a spec — "add X", "make it better", "integrate Y" — and it is unclear what "done" means. Draws out the intent and plays it back before building.
+---
+
+# Brainstorming
+
+When a request is a goal ("add superpowers", "make scrolling feel right"),
+building immediately produces the wrong thing fast. First make the intent
+concrete.
+
+## What to pin down
+
+- **The real outcome.** What should be TRUE after this that is not true now?
+  Not the feature name — the result the operator wants to see.
+- **The acceptance check.** How will the operator know it works? "I open X
+  and Y happens." If neither of you can state this, the task is not ready.
+- **Scope edges.** What is explicitly NOT part of this (the operator often
+  has an opinion, e.g. "no button", "don't touch the existing code").
+- **The alternatives you considered** and why you chose one — a decision is
+  cheaper to correct before it is built.
+
+## The zames constraint (IMPORTANT)
+
+zames has NO conversational turn: the operator sees only your final `respond`
+and your tool calls, and a task is expected to make PROGRESS, not to ask
+questions and wait. So do the brainstorming yourself and return it as a
+SHORT, concrete proposal in ONE `respond`, instead of an interview:
+
+- state the goal as you understood it;
+- state your assumptions and the choices you made by default;
+- state what you will NOT do;
+- then either (a) proceed if the request was clearly actionable, or (b) stop
+  and ask the ONE decision you genuinely cannot make alone.
+
+For a request that is already precise ("read file X", "rename Y"), skip this
+entirely — brainstorming a one-line task wastes the operator's time.

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: systematic-debugging
+description: Use when something is broken and the cause is not obvious — a failing test, a wrong result, a hang, a crash. Four phases: reproduce, isolate, hypothesize, fix. Prevents guessing.
+---
+
+# Systematic debugging
+
+Do NOT start by editing code. Work through the four phases in order; each
+phase must produce an artifact you can point at.
+
+## Phase 1 — Reproduce (no fix yet)
+
+Get a command that FAILS the same way the operator describes it.
+
+- Run it. Copy the exact error/output into your reasoning.
+- If it passes, you do not have the bug yet: narrow the input until it fails,
+  or ask which steps differ.
+- A bug you cannot reproduce is a bug you cannot verify you fixed.
+
+## Phase 2 — Isolate (bisect, do not read blindly)
+
+Shrink the failure to the smallest unit that still fails.
+
+- Comment out / stub / binary-search the input space; each step doubles the
+  information you have.
+- Read the code that the failing path ACTUALLY executes — not the code you
+  remember writing.
+- Check the obvious causes FIRST: wrong file, stale build, cached state,
+  different config, an earlier error swallowed by a catch.
+
+## Phase 3 — Hypothesize (one at a time)
+
+State the hypothesis in one sentence and predict what you should see if it is
+right. Then test exactly that.
+
+- One change at a time; two changes at once prove nothing.
+- Prefer an observation (a log, a probe, a test assertion) over an edit.
+- If the prediction is wrong, the hypothesis is wrong — discard it, do not
+  "adjust" it to fit.
+
+## Phase 4 — Fix and verify
+
+- Fix the CAUSE, not the symptom. A guard added to hide a wrong value leaves
+  the wrong value in place.
+- Add a regression test that fails WITHOUT the fix and passes WITH it.
+- Re-run the Phase 1 reproduction verbatim.
+- Look for the same bug elsewhere (the same wrong assumption is usually not
+  in one place only).
+
+## Anti-patterns
+
+- Editing before reproducing.
+- "It works now" without knowing what changed.
+- Adding a try/catch or a null-check to silence an error you do not understand.
+- Trusting a green test you wrote against the FIXED code without ever seeing
+  it red.

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: test-driven-development
+description: Use when writing or changing behaviour that can be tested — a bug fix, a new function, a parser, a formatter. Write the failing test first, watch it fail, then make it pass. Prevents tests that only pass because they were written against the finished code.
+---
+
+# Test-driven development
+
+RED → GREEN → REFACTOR. The order is the point, not a formality.
+
+## The cycle
+
+1. **RED** — write the smallest test that expresses the new behaviour and
+   RUN it. It must FAIL, and fail for the RIGHT reason ("not implemented",
+   not a typo or a missing import). A test you never saw fail proves nothing.
+2. **GREEN** — write the MINIMUM code that makes it pass. Do not add the
+   next feature "while you are there"; that code is untested.
+3. **REFACTOR** — clean up with the test green, and re-run it.
+
+## What makes a test good
+
+- It asserts BEHAVIOUR (input → output), not implementation detail.
+- It fails when the behaviour is wrong — verify this by breaking the code
+  on purpose once, if you are unsure.
+- It is deterministic: no sleeps, no network, no dependence on wall-clock
+  time or on the order other tests ran in.
+- One reason to fail, with a message that says what broke.
+
+## Rules in this project
+
+- A bug fix ALWAYS gets a regression test that reproduces the original bug.
+- When you fix a test to make it pass, ask whether the TEST was wrong or the
+  CODE was wrong; do not just move the assertion.
+- If the code was written before its test, delete and rewrite it driven by
+  the test — otherwise the test is shaped around the implementation.

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: verification-before-completion
+description: Use BEFORE declaring a task done or reporting success — a feature, a bug fix, a file you generated. Forces you to run the verification you promised instead of trusting that the code looks right.
+---
+
+# Verification before completion
+
+"It should work" is not done. Before you report success, produce EVIDENCE
+from the real artifact — not from your intent.
+
+## The checklist
+
+1. **Re-read the original request.** Every requirement, including the small
+   ones in a parenthetical. List them; tick each one against something you
+   can show.
+2. **Run the thing.** For code: build/typecheck/tests. For a script: run it.
+   For a generated file: open/parse it and confirm it is complete, not
+   truncated. For a UI: the real screen, not the diff.
+3. **Check the WHOLE file.** A generated file (HTML/JSON/config) is a common
+   silent failure: the head is there, the body/tail is missing or a
+   placeholder. Confirm the closing structure exists and the file runs.
+4. **Re-read your own diff** as a reviewer: leftover debug output, dead code,
+   a commented-out block, a wrong path, a test that asserts nothing.
+5. **State the evidence** in the final report — the exact command and its
+   result — so the operator can reproduce it. "Tests pass" without the
+   command is not evidence.
+
+## The two failure modes this prevents
+
+- **Partial delivery**: a game file with a scene but no game loop; a handler
+  that handles one case; a migration that covers one table. The operator runs
+  it, it is broken, and trust drops.
+- **Phantom fix**: the code changed, but the original reproduction was never
+  re-run, so nothing proves the bug is gone.
+
+## Rule
+
+If you cannot run the verification (no test, no runnable entry point), SAY SO
+explicitly and describe exactly what you did instead. Never report "done"
+while implying a verification you did not perform.

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: writing-plans
+description: Use when a task is large enough to need more than one or two tool calls — a multi-file change, a new feature, a refactor. Breaks the work into small ordered steps with exact paths and a verification for each.
+---
+
+# Writing plans
+
+A plan is a sequence of steps a careful engineer with NO project context
+could follow. If a step needs knowledge you have but did not write down, the
+plan is incomplete.
+
+## Shape of a good plan
+
+Each step is 2–5 minutes of work and names:
+
+- the EXACT file path(s) it touches;
+- what changes (the concrete edit, not "update the parser");
+- how to verify it (the command, the test name, the expected output).
+
+Order matters: put the step that DE-RISKS the task first (a spike, a failing
+test, a proof that the API works). Do not build three layers on an unverified
+assumption.
+
+## Rules
+
+- One concern per step. "Add the flag AND refactor the caller" is two steps.
+- Prefer a step that FAILS LOUDLY over a step that silently half-works.
+- Every behavioural change gets a test step (see test-driven-development);
+  write the failing test BEFORE the implementation step that satisfies it.
+- If you discover mid-plan that a step was wrong, STOP and revise the plan —
+  do not improvise the rest of it.
+- Keep the plan short enough to hold in your head; a 30-step plan is a sign
+  the task should be split.
+
+## In zames
+
+Because there is no separate plan file unless the operator asks for one, the
+plan lives in your reasoning and, for a long task, in a TodoWrite list — one
+entry per step, status updated as you go. Do not narrate the plan to the
+operator between tool calls; the todo list IS the visible plan.