@the-open-engine-company/zeroshot 11.0.0 → 12.0.0

package/README.md

@@ -1,9 +1,10 @@
 # `@the-open-engine-company/zeroshot`
 
-Zeroshot enforces your team's QA process on coding agents. You define the process as a graph:
-which agents implement, which reviewers and tests a change must pass, where failures go for repair,
-and where a run stops. Every task runs through it, and no agent can skip a step. It works with
-Codex, Claude Code, GitHub Copilot and Pi.
+zeroshot is the open-source engine for autonomous software production. Its workflow engine
+orchestrates coding agents through implementation, independent code review, testing, repair
+and delivery. Define your team's development and QA process as a reusable multi-agent graph;
+the engine enforces its transitions and retry limits. It works with Codex, Claude Code,
+GitHub Copilot and Pi.
 
 This package is the installer for the canonical `zeroshot` executable and agent skills. The package selects the release
 archive for the current Node platform and architecture, verifies it against that release's
@@ -21,7 +22,20 @@ Claude Code at `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/<name>/SKILL.md`. Rei
 managed copy. A conflicting or edited skill is preserved; installation fails with the exact path so
 the conflict cannot pass unnoticed.
 
-When set, `CLAUDE_CONFIG_DIR` must be absolute so the managed skills have stable locations.
+Set `ZEROSHOT_SKIP_SKILLS=1` to install or update only the executables:
+
+```sh
+ZEROSHOT_SKIP_SKILLS=1 npm install --global @the-open-engine-company/zeroshot
+ZEROSHOT_SKIP_SKILLS=1 zeroshot update
+```
+
+Only the exact value `1` enables this opt-out. Export it in your shell configuration to keep later
+installs and updates from recreating removed skills. Existing skills are left untouched, and skill
+conflicts or unwritable destinations do not block executable installation. Unset it to restore
+automatic skill installation.
+
+With automatic skill installation enabled, `CLAUDE_CONFIG_DIR` must be absolute when set so the
+managed skills have stable locations.
 
 npm 7 and newer do not run uninstall lifecycle scripts. After uninstalling the package, remove the
 managed skill directories above manually if their `SKILL.md` files are still unmodified managed copies.

package/bin/zeroshot.js

@@ -2,6 +2,7 @@
 'use strict';
 
 const fs = require('fs');
+const os = require('os');
 const path = require('path');
 const { spawnSync } = require('child_process');
 const { selectTarget } = require('../lib/install');
@@ -16,8 +17,15 @@ try {
   }
   const result = spawnSync(binary, process.argv.slice(2), { stdio: 'inherit' });
   if (result.error) throw result.error;
-  if (result.signal) process.kill(process.pid, result.signal);
-  else process.exitCode = result.status === null ? 1 : result.status;
+  if (result.signal) {
+    // Node ignores some signals, such as SIGPIPE and SIGXFSZ, so the re-raise can return.
+    // Then exit with the status a shell reports for that signal death.
+    const number = os.constants.signals[result.signal];
+    process.exitCode = number === undefined ? 1 : 128 + number;
+    process.kill(process.pid, result.signal);
+  } else {
+    process.exitCode = result.status === null ? 1 : result.status;
+  }
 } catch (error) {
   process.stderr.write(`zeroshot: ${error.message}\n`);
   process.exitCode = 1;

package/lib/skills.js

@@ -137,9 +137,11 @@ function installAt(location, canonical, managed) {
 }
 
 function installSkills(options = {}) {
+  const environment = options.environment ?? process.env;
+  if (environment.ZEROSHOT_SKIP_SKILLS === '1') return [];
+
   const packageRoot = options.packageRoot || path.resolve(__dirname, '..');
   const homeDirectory = options.homeDirectory ?? os.homedir();
-  const environment = options.environment ?? process.env;
   const uid = options.uid ?? (typeof process.getuid === 'function' ? process.getuid() : undefined);
   const sources = SKILL_NAMES.map((skill) => {
     const canonical = fs.readFileSync(path.join(packageRoot, 'skills', skill, 'SKILL.md'), 'utf8');

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@the-open-engine-company/zeroshot",
-  "version": "11.0.0",
-  "description": "Enforces your team's QA process on coding agents. Define the workflow as a graph of implementers, reviewers, tests and repair loops; every task runs through it and no agent can skip a step. Works with Codex, Claude Code, GitHub Copilot and Pi.",
+  "version": "12.0.0",
+  "description": "The open-source engine for autonomous software production. Orchestrate coding agents through implementation, code review, testing and repair.",
   "keywords": [
     "claude-code",
     "codex",
@@ -12,7 +12,10 @@
     "agent-orchestration",
     "code-review",
     "verification",
-    "cli"
+    "cli",
+    "autonomous-software-production",
+    "workflow-engine",
+    "qa-automation"
   ],
   "homepage": "https://zeroshot.sh",
   "license": "MIT",

package/skills/zeroshot/SKILL.md

@@ -30,7 +30,8 @@ a plan file exists (`.zeroshot/plans/<id>.md`), use its Goal, Context, Acceptanc
 Constraints, Decided approach and Decisions as the task. Criteria marked `Check (manual):` need a
 person or another environment: tell the run to list them rather than verify them. If the plan lists
 `depends_on`, confirm with the user that those plans are built and merged before starting it, and
-include any constraints they share that the plan does not repeat.
+include any constraints they share that the plan does not repeat, or submit the dependent plans
+together as a stack on Platform (see Submit a stack).
 
 Never start a Zeroshot run merely because the skill is available. The user must ask to use Zeroshot.
 A worker already executing inside a Zeroshot run should perform its assigned work directly, not start
@@ -112,9 +113,9 @@ When no saved profile fits and the user has not asked for Platform, run the buil
 
 ## Review an issue or pull request
 
-The `pr-review` and `issue-review` templates post reports as comments by default.
+The `pr-review`, `code-review` and `issue-review` templates post reports as comments by default.
 PR review classifies whether reproduction is necessary, runs required full-stack checks (including
-a browser for UI changes), then checks the diff and linked issue coverage. Its final report is concise. PR review uses comment delivery; issue review also supports `--delivery none` for a report without publication. Supply an issue or PR URL through `--task-from`, which resolves
+a browser for UI changes), then checks the diff and linked issue coverage. Its final report is concise. `code-review` takes the same PR input and runs parallel specialist reviewers whose verified findings become one comment. Both PR templates use comment delivery; issue review also supports `--delivery none` for a report without publication. Supply an issue or PR URL through `--task-from`, which resolves
 title/body and pins source before execution:
 
 ```console
@@ -251,6 +252,37 @@ Named targets receive the remote revision, not uncommitted files. Check dirty or
 never push or omit it without authorization. Confirm the exact repository, branch, revision, target,
 profile, and delivery intent reported for the run.
 
+## Submit a stack
+
+A stack submits several dependent tasks to Platform at once, for example the stack manifest the
+`zeroshot-plan` skill writes as `.zeroshot/plans/<id>.stack.json`. It is atomic and immutable: every
+run uses one repository, base branch and profile, and `needs` decides which runs must succeed before
+another starts without passing output between them. Submit one only when the user asks. The
+manifest's `delivery` is required; when it is still a placeholder, ask the user to choose:
+
+- `merge`: each run merges into the base branch before the runs that need it start. The profile
+  needs exactly one Git merge delivery node, `merge@2` or `merge@3` (`--ship` templates use
+  `merge@3`).
+- `stacked_pull_requests`: Zeroshot puts the runs in one line, in dependency order with ties broken
+  by run name, and each run opens a pull request against the branch of the run before it. Nothing
+  merges; the stack is done when every pull request is open. The profile needs exactly one `pr@2`
+  delivery node, the `software-change` default.
+
+Agent bindings in the profile must not declare `GH_TOKEN`. Validate, show the user the printed order
+for stacked pull requests, then submit with a stable key and follow it:
+
+```console
+zeroshot stack validate STACK.json
+zeroshot stack submit STACK.json --target platform --submission-key KEY
+zeroshot stack status STACK_ID --target platform
+```
+
+`zeroshot stack --help` documents the manifest. Stacked pull requests are reviewed and merged from
+the bottom up. GitHub moves a child pull request onto the base branch when its merged parent's
+branch is deleted; a squash-merged parent, or a parent changed during review, leaves the pull
+requests above it to rebase by hand. `zeroshot stack force-stop` stops every unfinished run; use it
+only when the user intends to stop the stack.
+
 ## Observe and troubleshoot
 
 Keep the run ID and target:

package/skills/zeroshot-plan/SKILL.md

@@ -212,3 +212,37 @@ prepares the edit you are about to make; this skill writes a plan file that outl
   `zeroshot` skill with the plan's Goal, Context, Acceptance criteria, Constraints, Decided approach
   and Decisions as the task, and start it only when the user asks. After the run, remind the user of
   the manual checks it could not perform.
+- **Stack:** when the plans you wrote are linked by `depends_on`, offer to also write a stack
+  manifest so Zeroshot Platform can build them in order from one submission. Write it only when the
+  user agrees, as `.zeroshot/plans/<id>.stack.json` beside the plans, where `<id>` is the plan the
+  others build on:
+
+  ```json
+  {
+    "schema": "zeroshot.stack/v1",
+    "title": "<title of that plan>",
+    "delivery": "<merge or stacked_pull_requests>",
+    "source": { "repository": "<owner/name>", "branch": "<base branch>" },
+    "profile": "<org:NAME or user:NAME>",
+    "expiresAt": "<RFC 3339 time, at most seven days ahead>",
+    "runs": {
+      "<plan id>": {
+        "needs": ["<ids from the plan's depends_on>"],
+        "input": { "task": "<the plan's Goal through Decisions>" }
+      }
+    }
+  }
+  ```
+
+  Add one run per plan, named by its id. Its task is one string holding the plan's Goal, Context,
+  Acceptance criteria, Constraints, Decided approach and Decisions sections as written, the task a
+  single run would get; use the profile's own input field if it has no `task`. `needs` lists the
+  `depends_on` ids that are in this stack and is omitted when there are none; a dependency outside
+  the stack must be built and merged before the stack is submitted. Take the repository and base
+  branch from the checkout and ask for the Platform profile and deadline. Leave `delivery` to the
+  user and keep the placeholder until they choose: `merge` merges each plan into the base branch
+  before the plans that need it start; `stacked_pull_requests` builds the plans in one line, in
+  dependency order with ties broken by id, and opens one pull request per plan against the branch of
+  the plan before it, merging nothing. Check the file with `zeroshot stack validate` when the CLI is
+  installed (the placeholder fails until `delivery` is chosen) and leave submission to the
+  `zeroshot` skill.