@the-open-engine-company/zeroshot 10.17.0 → 10.19.0

package/README.md

@@ -1,6 +1,11 @@
 # `@the-open-engine-company/zeroshot`
 
-Installer for the canonical `zeroshot` executable and agent skills. The package selects the release
+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.
+
+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
 `SHA256SUMS`, and installs the executable.
 
@@ -9,7 +14,8 @@ runtime configuration, targets, and CLI reference.
 
 The product site is [zeroshot.sh](https://zeroshot.sh/?utm_source=npm&utm_medium=readme&utm_campaign=zeroshot).
 
-The `zeroshot` and `zeroshot-memory-init` managed skills share one source each across hosts.
+The `zeroshot`, `zeroshot-memory-init`, and `zeroshot-graph-design` managed skills share one source
+each across hosts.
 They install for Codex, GitHub Copilot, and Pi at `$HOME/.agents/skills/<name>/SKILL.md`, and for
 Claude Code at `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/skills/<name>/SKILL.md`. Reinstalling updates an unchanged
 managed copy. A conflicting or edited skill is preserved; installation fails with the exact path so

package/lib/skills.js

@@ -5,7 +5,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
-const SKILL_NAMES = Object.freeze(['zeroshot', 'zeroshot-memory-init']);
+const SKILL_NAMES = Object.freeze(['zeroshot', 'zeroshot-memory-init', 'zeroshot-graph-design']);
 const MANAGED_MARKER = 'managed by @the-open-engine-company/zeroshot';
 const MANAGED_PATTERN =
   /^<!-- managed by @the-open-engine-company\/zeroshot; sha256=([a-f0-9]{64}) -->\n/;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@the-open-engine-company/zeroshot",
-  "version": "10.17.0",
-  "description": "Runs coding agents as a graph: one agent implements, independent agents review, failures go to repair, and nothing ships until the checks pass. Works with Codex, Claude Code, GitHub Copilot and Pi.",
+  "version": "10.19.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.",
   "keywords": [
     "claude-code",
     "codex",

package/skills/zeroshot/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: zeroshot
-description: Use Zeroshot to prepare, run, observe, or troubleshoot explicit multi-agent software work locally or on Zeroshot Cloud. Apply when the user names Zeroshot, including 'zeroshot this' or 'zeroshot it' (this orchestrator, not one-shot prompting), or asks about its CLI; do not route ordinary local work into Zeroshot without that intent.
+description: Use Zeroshot to prepare, run, observe, or troubleshoot explicit multi-agent software work locally or on Zeroshot Platform. Apply when the user names Zeroshot, including 'zeroshot this' or 'zeroshot it' (this orchestrator, not one-shot prompting), or asks about its CLI; do not route ordinary local work into Zeroshot without that intent.
 ---
 
 # Zeroshot
@@ -26,7 +26,7 @@ Suggest separate tasks only for independently useful outcomes or real prerequisi
 
 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
-another run. A failed Cloud run does not authorize silently implementing the task locally.
+another run. A failed Platform run does not authorize silently implementing the task locally.
 
 ## Choose the target
 
@@ -34,14 +34,16 @@ another run. A failed Cloud run does not authorize silently implementing the tas
   Git worktrees use their root. File arguments stay relative to the invoking folder. Runs without
   Git delivery need no repository. Keep workspace and active Zeroshot state disjoint; use an external
   `ZEROSHOT_STATE_DIR` when necessary.
-- Zeroshot Cloud is built in. Sign in once with `zeroshot target login cloud`, then use
-  `--target cloud` explicitly on Cloud commands. Cloud setup (organizations, GitHub App,
-  connections) is documented at https://cloud.zeroshot.sh/docs.
-- Do not add or set up the built-in Cloud target. Named targets store endpoints and login identity,
+- Zeroshot Platform is built in. Sign in once with `zeroshot target login platform`, then use
+  `--target platform` explicitly on Platform commands. Platform setup (organizations, GitHub App,
+  connections) is documented at https://app.zeroshot.sh/docs.
+- Do not add or set up the built-in Platform target. Named targets store endpoints and login identity,
   not repository configuration.
 
 ## Reuse profiles and connections
 
+For a guided interview to design or revise a graph, use the `zeroshot-graph-design` skill.
+
 Prefer a saved profile over inventing a graph or runtime. Inspect its input, runtime, and delivery
 behavior before constructing a run. Local profiles need no login; a local default profile applies
 when a run names no profile, graph, or runtime:
@@ -49,11 +51,11 @@ when a run names no profile, graph, or runtime:
 ```console
 zeroshot profile list
 zeroshot profile show NAME
-zeroshot profile list --target cloud --scope user
-zeroshot profile list --target cloud --scope org
-zeroshot profile show NAME --target cloud --scope org
-zeroshot connection list --target cloud --scope user
-zeroshot connection list --target cloud --scope org
+zeroshot profile list --target platform --scope user
+zeroshot profile list --target platform --scope org
+zeroshot profile show NAME --target platform --scope org
+zeroshot connection list --target platform --scope user
+zeroshot connection list --target platform --scope org
 ```
 
 Inspect saved profiles to see their delivery behavior. New `software-change` templates default to
@@ -62,7 +64,7 @@ or `--ship` when merge delivery is intended. Custom graphs and saved profiles ow
 
 ## Run locally without a profile
 
-When no saved profile fits and the user has not asked for Cloud, run the built-in
+When no saved profile fits and the user has not asked for Platform, run the built-in
 `software-change` graph locally. Its default publishes a PR. For local-only work, use
 `--delivery none` as shown below; that mode needs only the harness's native login.
 
@@ -116,7 +118,7 @@ zeroshot run --title "Review PR 123" --template pr-review \
 
 Use `issue-review` for an issue URL; its basic issue workflow is separate. PR intake captures linked
 issue text before execution. Local reviews require clean tracked files and, for a PR, a checkout already at its head. Comment
-publication uses the declared `github.GH_TOKEN` connection. Use `--target cloud` for hosted source
+publication uses the declared `github.GH_TOKEN` connection. Use `--target platform` for hosted source
 preparation and credential resolution. With a saved review profile, use `--profile` instead of the
 template/runtime/delivery flags. Validate first with `--validate-only`; retry uncertain submission
 using the same key and configuration. A successful review may report defects; success confirms
@@ -150,7 +152,7 @@ one from scratch:
 ## Prepare the execution environment
 
 Environments belong to a run, independently of its profile. A `local:NAME` profile can run on a
-Docker target with its own environment. For Docker or Cloud, pass
+Docker target with its own environment. For Docker or Platform, pass
 `--environment environment.json` with a flat definition such as:
 
 ```json
@@ -161,8 +163,8 @@ Docker target with its own environment. For Docker or Cloud, pass
 }
 ```
 
-Cloud resolves an omitted environment from the repository's User default, then Org default, then
-Base. `--no-environment` bypasses defaults. Choose saved environments through Cloud's UI or API;
+Platform resolves an omitted environment from the repository's User default, then Org default, then
+Base. `--no-environment` bypasses defaults. Choose saved environments through Platform's UI or API;
 the CLI accepts a concrete JSON file. Local runs use the invoking machine and reject setup/startup
 and hook connections.
 
@@ -213,23 +215,23 @@ submission key for safe retries:
 
 ```console
 zeroshot run --title "TASK" --profile org:NAME --input input.json \
-  --target cloud --submission-key KEY --validate-only
+  --target platform --submission-key KEY --validate-only
 
 zeroshot run --title "TASK" --profile org:NAME --input input.json \
-  --target cloud --submission-key KEY
+  --target platform --submission-key KEY
 ```
 
-`--validate-only` materializes and validates without starting a run. A named Cloud profile must
-still be fetched from the target first, so this command requires Cloud access. It does not prove
+`--validate-only` materializes and validates without starting a run. A named Platform profile must
+still be fetched from the target first, so this command requires Platform access. It does not prove
 connection availability.
 
 For named targets, `--cwd` selects the client Git checkout. Zeroshot prefers its attached upstream,
-then a unique eligible HTTPS/SSH remote. Docker and Cloud still require an exact committed Git
+then a unique eligible HTTPS/SSH remote. Docker and Platform still require an exact committed Git
 source. Detached worktrees require repository and branch overrides. `--repository` accepts GitHub
 `owner/name` or a credential-free HTTPS/SSH clone URL. Override source only when needed:
 
 ```console
---target cloud --repository OWNER/REPOSITORY --branch BRANCH --revision SHA
+--target platform --repository OWNER/REPOSITORY --branch BRANCH --revision SHA
 ```
 
 Git push uses shared transport and needs no GitHub API. PR and merge require a registered forge;
@@ -246,13 +248,13 @@ profile, and delivery intent reported for the run.
 Keep the run ID and target:
 
 ```console
-zeroshot status RUN_ID --target cloud
-zeroshot watch RUN_ID --target cloud
-zeroshot logs RUN_ID --target cloud
+zeroshot status RUN_ID --target platform
+zeroshot watch RUN_ID --target platform
+zeroshot logs RUN_ID --target platform
 ```
 
 A foreground run streams events. Ctrl-C detaches observation without stopping the run. Use
-`zeroshot force-stop RUN_ID --target cloud` only when the user explicitly intends to stop it.
+`zeroshot force-stop RUN_ID --target platform` only when the user explicitly intends to stop it.
 
 For command errors, check `zeroshot --version` and the relevant `--help`; do not revive removed
 commands such as `target setup`. If login cannot retain credentials, fix the credential store before

package/skills/zeroshot-graph-design/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: zeroshot-graph-design
+description: Design or revise a Zeroshot graph through a guided interview grounded in the invoking repository. Review an ASCII diagram and exact node instructions, select runtimes, then confirm the profile name and local or platform storage scope before saving.
+---
+
+# Zeroshot graph design
+
+Help the user design a lean graph they understand and can reuse. Keep the conversation short and opinionated: inspect what you can, propose sensible defaults, and ask about choices that materially change the design. Graph design does not authorize starting a run.
+
+## Confirm the starting point
+
+Begin by asking:
+
+> I'll assume you want a reusable code-change graph for the repository this skill was called from: `<invoking directory>`. Is that right, or do you have a different purpose or repository in mind?
+
+Use the actual invoking directory. Wait for the answer before inspecting the repository or proposing a graph. If the user already confirmed this in the conversation, continue without repeating the question. Honor any specific task or different purpose they provide; otherwise keep the task as a per-run input.
+
+Do not ask for harnesses, models, or effort yet.
+
+## Inspect and propose
+
+Read applicable repository guidance, manifests, scripts, CI workflows, test configuration, and enough representative code to identify the stack and normal development workflow. Use read-only inspection; designing a graph does not require running the test suite or changing application code.
+
+Infer what the user would almost always check after a code change. Ground the proposal in concrete commands and file paths, and label uncertain assumptions. Distinguish routine checks from checks that depend on the affected code:
+
+- Use the repository's own build, formatting, lint, type, and test commands where applicable. Scope expensive suites according to its established workflow.
+- For a UI, consider browser interaction, visual inspection, accessibility, and existing end-to-end tests. Identify the main flows worth checking; do not add a browser node merely because a dependency mentions a UI framework.
+- For services, CLIs, libraries, or infrastructure, choose the corresponding integration, smoke, compatibility, or deployment validation supported by the repository.
+- Translate common manual verification into concrete agent actions when tools permit. If a required check needs unavailable services, credentials, or human judgment, surface that dependency and ask how to handle it. Missing evidence cannot count as a pass.
+
+For code-change graphs, ask: "How should runs deliver changes: leave them local, push a branch, open a PR, or merge?" Reuse any earlier choice and include delivery in the proposal.
+
+Propose a complete first draft using the evidence. Ask focused follow-ups only where the answer would change the graph; avoid making the user describe facts you can inspect.
+
+## Keep the graph lean
+
+Start with an implement/repair worker followed by independent review, looping on actionable feedback until the required reviewers accept. Combine responsibilities when one reviewer can cover them well; add nodes only for distinct work or verification that earns a separate pass.
+
+Parallelize independent work and reviews. Keep overlapping edits and checks that compete for mutable resources sequential unless they have suitable isolation. Avoid routing trees, coordinator layers, and separate planning or reporting agents without a concrete need.
+
+The worker must receive every relevant rejection. Repairs trigger fresh review of the resulting workspace; success requires all required reviewers to accept that version. Keep environment failures distinct from code defects.
+
+Write concise node prompts with the task, responsibility, applicable checks, and expected result. Reviewers inspect and verify without repairing the change; remind them that other nodes may execute concurrently. Keep Git commands out of reviewer prompts; use files and observable outputs. Pass task and feedback through graph inputs rather than repeating them in long prompts. Resolve material ambiguities during the interview because runtime agents are non-interactive.
+
+Leave optional deadlines, budgets, and retry restrictions unset unless requested. Do not copy small loop caps from examples. When the graph format requires finite bounds, derive permissive valid values from the current structural ceilings and the proposed graph's execution counts. Explain those required bounds briefly; preserve mandatory protocol limits and never claim the runtime is unbounded.
+
+## Show the proposal
+
+Briefly explain the repository evidence behind the verification choices. Then draw the graph in an inline ASCII code block, using only node titles or purposes, forks/joins, and high-level conditions. Omit schemas, field bindings, runtime details, and plumbing from the diagram.
+
+For example, when two independent reviews are useful:
+
+```text
+[Implement / repair]
+        |
+        +----> [Review code] -----+
+        |                        |
+        +----> [Verify behavior] -+
+                                 |
+                       all accept? -- yes --> [Done]
+                            |
+                            no
+                            +----> [Implement / repair]
+```
+
+Immediately below the diagram, show the complete authored instructions for every agent node, each in a labeled fenced text block. Quote them verbatim, including any shared authored instruction text. Do not summarize, elide, or hide instructions behind references. Explain variable inputs outside the quoted text. Structural nodes need no invented prompts.
+
+Invite feedback on the graph and wording. After revisions, show the updated diagram and all current node instructions together so the user can review a complete version. Keep simplifying as you iterate. Wait for the user's acceptance; silence is not acceptance.
+
+## Choose runtimes after acceptance
+
+Only after the user is happy with both graph and instructions, ask:
+
+> Which harness, model, provider, and effort would you like? You can use one configuration for all agent nodes or specify them per node. Effort can also stay at the harness default.
+
+Reuse choices already supplied. Confirm the provider when needed to form a valid harness/provider lane. Keep model identifiers exactly as authored; do not infer providers from model names or invent a model catalog. Resolve incomplete choices before producing a runnable runtime plan.
+
+Accept ordinary model names and resolve their technical IDs from existing configuration or official provider documentation. If the provider is unclear, ask only for the provider; do not ask the user for a model ID.
+
+Prefer a continuing worker session and fresh independent reviewer sessions when supported, unless the user chooses otherwise. If runtime constraints require changing the graph or instructions, show the revision and get agreement on it before finalizing.
+
+## Prepare the profile
+
+Use installed Zeroshot help and version-matched documentation as the contract. The official [review-loop guide](https://the-open-engine.github.io/zeroshot/current/guides/review-loop/) and [runtime-plan reference](https://the-open-engine.github.io/zeroshot/current/reference/runtime-plan/) describe the separate graph and runtime documents; check compatibility with the installed version.
+
+Produce `graph.json` and `runtime.json` in the user's chosen location, or a dedicated local artifact directory if none was specified. Preserve the reviewed node instructions verbatim. Bind every executable node and connect reviewer verdicts and diagnostics to the loop's acceptance condition and repair feedback. Give bound exhaustion and execution failures explicit unsuccessful outcomes.
+
+Use supported validation that does not start a run, subject to repository guidance. Report what was actually validated; JSON parsing alone does not prove graph admission. If Zeroshot or full validation is unavailable, still provide the design and files and state the remaining validation clearly.
+
+## Final step: save, configure, and explain how to run
+
+Suggest a name and offer local, platform user, or platform organization storage. Use `cloud` unless another target is specified.
+
+Before asking for login or an organization, check existing access with `zeroshot profile list --target TARGET --scope SCOPE`. Reuse the session and selected organization; ask only if unresolved. Follow host credential-store guidance if login is needed.
+
+Check name conflicts, then confirm the name, destination, and any replacement once. An explicit save instruction counts as confirmation. Save with `zeroshot profile set NAME --graph graph.json --runtime-config runtime.json`, adding `--target TARGET --scope SCOPE` for platform storage. Read back and verify the saved profile; retain the draft and report any failure.
+
+Ask whether the saved profile should become the default, naming the affected scope. If yes, use `zeroshot profile default NAME` with the matching target/scope flags. Reuse an earlier default decision.
+
+Inspect the effective runtime's required environment/connection fields and existing configuration. If values are missing, ask how the user wants to provide them:
+
+- Printed CLI setup commands: use `zeroshot connection set KEY --field FIELD` with repeated hidden prompts and the correct target/scope. Include every connection field because `set` replaces the connection.
+- Platform UI: link to `https://app.zeroshot.sh/orgs/ORG_ID/connections?scope=SCOPE` using verified values, or link to [Platform](https://app.zeroshot.sh) and direct the user to Connections.
+- At run startup: print a command that prompts without echo and supplies the required variables only to that run.
+
+Never request secret values in chat or embed them in printed commands. Skip this question when no values are missing.
+
+Finish with a copyable `zeroshot run` command containing the saved profile selector, title, input file, and target where applicable, plus minimal input JSON matching the graph. Include startup prompts if chosen. Do not start the run unless explicitly requested.

package/skills/zeroshot-memory-init/SKILL.md

@@ -84,7 +84,7 @@ For an invalid response, correct only the named task using its existing contract
 failure persists, stop and report the error and session directory rather than retry indefinitely.
 Report exclusions and incomplete work alongside the command's publication/defer counts.
 
-This workflow reads local native Rust run history, not Cloud or Docker target history. Never read
+This workflow reads local native Rust run history, not Platform or Docker target history. Never read
 controller bootstrap files, provider homes or credentials to recover evidence. Do not fetch code or
 switch branches to interpret “newest”; use the recorded checkouts. Current maintenance citations must
 refer to tracked or nonignored source, which the CLI fingerprints before publication.