orchestrix-skills 0.7.0 → 0.9.0

package/.claude-plugin/plugin.json

@@ -1,10 +1,15 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Capability-first AI development skill graph (Anthropic-native): plan → build with a warm-context orchestrator, contract-wired skills, and independent verification.",
   "author": "Orchestrix",
   "homepage": "https://orchestrix-mcp.youlidao.ai",
   "license": "MIT",
-  "keywords": ["orchestrix", "skills", "ai-development", "orchestration"],
+  "keywords": [
+    "orchestrix",
+    "skills",
+    "ai-development",
+    "orchestration"
+  ],
   "skills": "./skills"
 }

package/README.md

@@ -6,8 +6,8 @@ contract-bearing skills from intent to commit — with independent verification
 that never trusts the model's self-report.
 
 Open source (MIT). The skills run in any runtime that loads Anthropic skills
-(Claude Code, Claude apps, Agent SDK). The hosted orchestrator, knowledge
-hosting, and team features are the premium layer — see below.
+(Claude Code, Claude apps, Agent SDK). You run them in your own runtime with your
+own API key: no server, no license, no telemetry.
 
 ## The graph
 
@@ -29,42 +29,85 @@ intent
 Human gates are front-loaded (planning = direction) and at the end (acceptance);
 the build loop runs lights-out, gated only by objective `verify`.
 
-## Install (free, no license)
+## Install
 
 ```bash
-npx orchestrix-skills install            # default: Claude Code (.claude/skills/)
+npx orchestrix-skills install             # default: Claude Code (.claude/skills/)
 npx orchestrix-skills install --ide codex # Codex (.codex/skills/ + AGENTS.md)
 npx orchestrix-skills install --ide cursor
 npx orchestrix-skills doctor --ide codex  # validate an installation
 ```
 
 This copies the skills into your runtime's skills dir and scaffolds `knowledge/`
-+ `core-config.yaml` (it never overwrites an existing `knowledge/` — that's your
-brain). Then use the `orchestrate` skill. You run it in your own runtime with
-your own API key. No server, no license.
++ `core-config.yaml` (it never overwrites an existing `knowledge/` — that is your
+brain). Then use the `orchestrate` skill.
 
-For Claude Code you can also install via the plugin marketplace:
+For Claude Code you can also install from the plugin marketplace:
 `/plugin install orchestrix-skills`.
 
+### Upgrading, and how hosts automate it
+
+Re-running `install` refreshes the skills in place. It also writes a stamp at
+`<skills-dir>/.orchestrix-skills.json`:
+
+```json
+{ "version": "0.8.0", "ide": "claude", "skills": ["brainstorm", "commit", "…"] }
+```
+
+Two things read it. The installer prunes skills a previous version placed that
+the package no longer ships — and only those names, so a skill you or your
+platform installed alongside them is never touched. And a host that provisions
+projects can compare `version` against the npm dist-tag to decide whether to
+reinstall, instead of maintaining its own version constant that silently drifts.
+
+The stamp is written last: a run that dies mid-copy leaves the older stamp
+behind, so the next run still sees a mismatch and reinstalls rather than
+declaring itself current.
+
+## What `orchestrate` guarantees
+
+The root skill is where the interesting engineering lives. Beyond wiring:
+
+- **Verification is executable.** Each step's `verify` must be proven by a real
+  command the orchestrator runs itself, with the command, exit code, and output
+  tail captured to `.orchestrate/verify/step-<n>-attempt-<k>.log`. A subagent's
+  own success report is not evidence.
+- **State lives outside the context window.** Every run appends to
+  `.orchestrate/ledger.jsonl` (`run_start` / `plan` / `step` / `gate` /
+  `run_end`). The ledger is the run's durable memory, not the conversation.
+- **Cold re-entry is deterministic.** After compaction, an interruption, or a
+  wake-up, the orchestrator replays the ledger instead of trusting recall. A
+  step left dangling at `dispatched` is trusted in neither direction: its verify
+  command is re-run to decide whether it completed.
+- **Rework is bounded.** A failed verify re-dispatches the same skill with the
+  failure as input — capped at 3 attempts, and a failure whose cause is not
+  understood goes to `investigate` first, so the retry aims at a mechanism
+  rather than re-rolling the dice.
+- **Accept gates are enforced by authority, not by declaration.** A skill that
+  spends, sends, deploys, deletes, or signs is escalated to an inline human gate
+  even if it asked for a deferred one.
+- **Two rules are hard-wired** because output→input matching structurally cannot
+  reach them: `smoke-test` is the acceptance floor for a runnable app the run
+  changed, and `design-system` precedes `design-ui`.
+
 ## Runtime adapters
 
 `skills/` is the runtime-neutral source of truth. `adapters/` describes how a
 runtime maps generic capabilities to its tools. During a Codex install the CLI
-removes Claude-only `allowed-tools`, preserves the Orchestrix contract, and adds
-Codex runtime guidance. If the target has an unmanaged `AGENTS.md`, its content
-is left untouched and the guidance is placed at `.codex/orchestrix/AGENTS.md`
-for manual merging. Installer-created guidance uses a marked Orchestrix block,
-so later installs refresh that block while preserving surrounding user
-instructions.
-
-`doctor` validates every installed Skill's required frontmatter, Codex
+removes Claude-only `allowed-tools`, preserves the contract, and adds Codex
+runtime guidance. If the target has an unmanaged `AGENTS.md`, its content is left
+untouched and the guidance is placed at `.codex/orchestrix/AGENTS.md` for manual
+merging. Installer-created guidance uses a marked block, so later installs
+refresh that block while preserving surrounding user instructions.
+
+`doctor` validates every installed skill's required frontmatter, the Codex
 transformation, configuration shape, knowledge directory, and active root
 guidance. A reference file that has not been merged into an existing root
 `AGENTS.md` is reported as unhealthy rather than silently treated as active.
 
 Codex uses isolated agents when the active session exposes them and otherwise
-runs leaf skills sequentially. Cursor and Windsurf remain reference-rule
-installs until those runtimes provide native compatible skill execution.
+runs leaf skills sequentially. Cursor and Windsurf remain reference-rule installs
+until those runtimes provide native compatible skill execution.
 
 ## How it works
 
@@ -75,19 +118,15 @@ installs until those runtimes provide native compatible skill execution.
   verify. See `skills/README.md`.
 - **Two zones in your project:** `knowledge/` (the brain skills read — AI-primary,
   structured, with provenance) and `docs/` + `src/` (work products and the
-  deliverable). `core-config.yaml` maps logical namespaces to physical paths.
-
-## Premium (hosted)
-
-The skills are free and open. The hosted layer is where the work runs for you:
-the orchestrator-as-a-service, knowledge hosting + metabolism, team sync, and the
-transparent AI software company ("建造中心"). See
-[orchestrix-mcp.youlidao.ai](https://orchestrix-mcp.youlidao.ai).
+  deliverable). `core-config.yaml` maps logical namespaces to physical paths, so
+  a project keeps its brain wherever it already lives.
 
-## Design
+## Hosted
 
-Full design rationale: `Skill 编排器与最小契约设计` (the capability-first model,
-the 6-field contract, lights-out accept gates, the knowledge KB, distribution).
+A hosted layer — orchestrator-as-a-service, knowledge hosting, and team features
+— is available separately at
+[orchestrix-mcp.youlidao.ai](https://orchestrix-mcp.youlidao.ai). Nothing in this
+package requires it or talks to it.
 
 ## Attribution
 

package/bin/install.js

@@ -1,14 +1,19 @@
 #!/usr/bin/env node
 // orchestrix-skills installer — zero dependencies.
-// Free path: copy skills into the runtime's skills dir + scaffold knowledge/.
-// No MCP, no license. Premium (hosted orchestrator / KB / 建造中心) is a separate opt-in.
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+// Copies skills into the runtime's skills dir + scaffolds knowledge/.
+// No MCP, no license, no network calls. The hosted layer is a separate opt-in.
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
 const MANAGED_START = "<!-- orchestrix:start -->";
 const MANAGED_END = "<!-- orchestrix:end -->";
+// Written into the skills dir after every successful install. Two consumers:
+// this installer (prunes skills it placed that the package no longer ships) and
+// hosts that auto-upgrade projects (compare `version` against the npm dist-tag
+// to decide whether to reinstall — no second version constant to maintain).
+const STAMP = ".orchestrix-skills.json";
 
 // Where each runtime auto-loads skills from (relative to the target project).
 function adapter(name) {
@@ -36,11 +41,12 @@ Usage:
   npx orchestrix-skills install [--ide claude|codex|cursor|windsurf] [--dir <project>]
   npx orchestrix-skills doctor  [--ide claude|codex|cursor|windsurf] [--dir <project>]
 
-What it does (free, no license):
+What it does:
   1. Copies the skills into your runtime's skills dir (default: .claude/skills/)
   2. Scaffolds knowledge/ + core-config.yaml (never overwrites an existing brain)
+  3. Stamps <skills-dir>/.orchestrix-skills.json so upgrades and pruning are exact
 
-Premium (hosted orchestrator, KB hosting, teams, 建造中心):
+Hosted orchestration, knowledge hosting, and team features:
   see https://orchestrix-mcp.youlidao.ai`);
 }
 
@@ -54,9 +60,22 @@ function transformSkill(source, runtime) {
     );
 }
 
+function packageVersion() {
+  return JSON.parse(readFileSync(join(PKG, "package.json"), "utf8")).version;
+}
+
+function readStamp(target) {
+  try {
+    return JSON.parse(readFileSync(join(target, STAMP), "utf8"));
+  } catch {
+    return null; // absent, or written by a version that predates stamping
+  }
+}
+
 function installSkills(dir, runtimeName, runtime) {
   const target = join(dir, runtime.skillsDir);
   mkdirSync(target, { recursive: true });
+  const previous = readStamp(target);
   const entries = readdirSync(join(PKG, "skills"), { withFileTypes: true });
   for (const entry of entries) {
     const source = join(PKG, "skills", entry.name);
@@ -74,7 +93,26 @@ function installSkills(dir, runtimeName, runtime) {
       }
     }
   }
-  return entries.filter((entry) => entry.isDirectory()).length;
+
+  const names = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  // Retire skills a PREVIOUS install of this package placed that it no longer
+  // ships. Only names recorded in our own stamp are candidates, so a skill the
+  // project or its host installed alongside ours is never touched.
+  let pruned = 0;
+  for (const name of previous?.skills ?? []) {
+    if (names.includes(name)) continue;
+    const stale = join(target, name);
+    if (!isDirectory(stale)) continue;
+    rmSync(stale, { recursive: true, force: true });
+    pruned += 1;
+  }
+  // Stamp LAST: a crash mid-copy leaves the older stamp in place, so the next
+  // run still sees a mismatch and reinstalls rather than declaring itself current.
+  writeFileSync(
+    join(target, STAMP),
+    `${JSON.stringify({ version: packageVersion(), ide: runtimeName, skills: names }, null, 2)}\n`,
+  );
+  return { count: names.length, pruned };
 }
 
 function installRuntimeGuidance(dir, runtimeName) {
@@ -142,8 +180,9 @@ function install() {
   }
 
   // 1. Skills (capabilities) — always refreshed.
-  const count = installSkills(dir, ide, runtime);
-  console.log(`✓ ${count} skills → ${runtime.skillsDir}/`);
+  const { count, pruned } = installSkills(dir, ide, runtime);
+  console.log(`✓ ${count} skills → ${runtime.skillsDir}/ (v${packageVersion()})`);
+  if (pruned > 0) console.log(`✓ ${pruned} retired skill(s) removed`);
   installRuntimeGuidance(dir, ide);
 
   // 2. Knowledge (the brain) — scaffold only if absent; never clobber the user's brain.
@@ -167,7 +206,7 @@ function install() {
   if (ide === "cursor" || ide === "windsurf") {
     console.log(`\nNote: ${ide} does not auto-load Anthropic skills yet — copied as reference rules.`);
   }
-  console.log(`\nDone. Start with the "orchestrate" skill. Premium hosting: https://orchestrix-mcp.youlidao.ai`);
+  console.log(`\nDone. Start with the "orchestrate" skill.`);
 }
 
 function doctor() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "Capability-first AI development skill graph — Anthropic-native skills that run in any agent runtime.",
   "type": "module",
   "bin": {

package/project-scaffold/README.md

@@ -4,8 +4,6 @@ What the framework installs into a **target project** (the thing being built)
 not the framework's own content. Skills (capabilities) arrive separately via MCP
 or `.orchestrix/`; this scaffold is the project's durable knowledge + config.
 
-Maps to the design doc `cc-plans/Skill编排器与最小契约设计-v0.1.md` §10.
-
 ```
 <project>/
 ├── knowledge/     # the brain — what skills READ (reads:). AI-primary, human-audited.

package/skills/README.md

@@ -4,8 +4,6 @@ Capability-oriented skills, not role-oriented agents. Each skill is a single
 capability with a clear contract. The `orchestrate` skill wires them together by
 matching one skill's `outputs` to another's `inputs`.
 
-Design source of truth: `cc-plans/Skill编排器与最小契约设计-v0.1.md`.
-
 ## Format
 
 Every skill is a standard [Anthropic Agent Skill](https://agentskills.io/specification)

package/skills/commit/SKILL.md

@@ -37,22 +37,28 @@ Record verified work as one conventional commit.
    secrets, no `.env*`.
 4. Commit with the message format below.
 
-## Message format (required)
+## Message format
 
-A conventional-commit subject, then the mandatory footer, exactly:
+A conventional-commit subject, optional body, and whatever trailer this project
+requires:
 
 ```
 <type>(<scope>): <summary>
 
 <optional body>
 
-🤖 Generated with [Orchestrix](https://orchestrix-mcp.youlidao.ai)
+<project-required trailer, if any>
 ```
 
 - `<type>`: feat | fix | refactor | docs | test | chore | …
-- **The footer line is mandatory and exact.** A commit hook rejects commits
-  without it.
-- **Never** add `Co-Authored-By` or a "Claude Code" footer.
+- **The project decides the trailer, and it is binding.** Look for a required
+  commit trailer in `CLAUDE.md` / `AGENTS.md` / contributing docs / a commit
+  hook, and reproduce it EXACTLY — a hook that enforces one will reject the
+  commit otherwise, and a near-miss costs a rewrite. If the project defines
+  none, write no trailer.
+- **Never invent a trailer**, and never add `Co-Authored-By` or a tool-attribution
+  footer the project did not ask for. Whose name ends up in a project's history
+  is the project's call, not this skill's.
 
 ## Done
 

package/skills/orchestrate/SKILL.md

@@ -4,7 +4,7 @@ description: Use when a goal must be delivered end-to-end by composing skills, w
 license: MIT
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task]
 metadata:
-  version: 5
+  version: 6
   requires:
     capabilities: [filesystem.read, filesystem.write, shell.execute, "agent.spawn?"]
   contract:
@@ -36,9 +36,10 @@ no step above intent.
 1. **Bind intent.** Read the human's goal and constraints. This is the only
    place intent enters. Then run the first-run preflight (below) before any
    wiring.
-2. **Select.** Read the skill registry. Pick skills by their `description`
-   (when-to-use). Load a skill's full `contract` only when it is a candidate —
-   never load every contract at once.
+2. **Select.** Read the skill registry (the `description:` line of every
+   SKILL.md in the runtime's skills directory). Pick skills by that
+   when-to-use description. Load a skill's full `contract` only when it is a
+   candidate — never load every contract at once.
 3. **Wire (emergent, not hardcoded).** Build the path by matching one skill's
    `outputs` to the next skill's `inputs`. Skills do not know each other; only
    you do. Do not assume a fixed pipeline — wire what this intent needs.
@@ -68,8 +69,12 @@ no step above intent.
 6. **Accept (gate).** Apply the rule below. Then continue — do not pause to ask
    "should I keep going?" mid-run.
 7. **Repeat** 3–6 until the intent is fulfilled.
-8. **Final acceptance.** Present the batched deferred accepts and a final review
-   to the human, once. Apply corrections (see Metabolism), then deliver.
+8. **Final acceptance.** FIRST re-read the intent from the `run_start` ledger
+   line and check the assembled result against IT — every step passing its own
+   verify does not prove the composition serves the intent (steps can each be
+   right while the whole drifts). Then present the batched deferred accepts and
+   a final review to the human, once. Apply corrections (see Metabolism), then
+   deliver.
 
 ## Namespace resolution (`core-config.yaml`)
 
@@ -114,6 +119,27 @@ resolved paths):
 
 Both checks are per-run and idempotent: a populated brain makes them no-ops.
 
+## Hard wiring rules (what emergence cannot reach)
+
+Output→input matching wires most of the graph. Two skills it structurally
+CANNOT reach — wire these by rule, not by match:
+
+1. **`smoke-test` is the acceptance floor for runnable apps.** Nothing in the
+   graph outputs its `flows` or `run_instructions`, so no output→input match
+   will ever select it. If the deliverable is a runnable app or service and
+   this run changed it, wire `smoke-test` before final acceptance and derive
+   its inputs yourself: `flows` from the story's acceptance criteria (or from
+   the intent, when there is no story), `run_instructions` from `registry/app`
+   (or the project's own manifest). `run-tests` proves functions; `smoke-test`
+   proves the product — green unit tests are not this evidence. A `failed` or
+   `untested` verdict is a real result: carry it into final acceptance
+   verbatim, never round it up to passed.
+2. **`design-system` comes before `design-ui`.** `design-ui` READS
+   `taste/design-system` — it never produces it. If UI work is wired and the
+   resolved `taste/design-system` namespace is empty, wire `design-system`
+   first; otherwise `design-ui` dresses a project that has a brand in generic
+   defaults.
+
 ## Accept gate
 
 | Skill's `accept.timing` | Skill's `authority`                                               | Action                                                                                        |
@@ -141,8 +167,9 @@ aimed at a symptom re-rolls the dice.
 STOP the run — do not burn a 4th attempt. Write a `gate` event to the ledger
 (`{"e":"gate","kind":"rework_exhausted","question":"step <n> (<skill>) failed 3
 attempts: <one-line why>"}`), summarize the three failures for the human, and
-report AWAIT. A step that cannot pass its own verify after three tries needs a
-human decision (wrong approach, wrong spec, or wrong verify), not more tokens.
+stop for their decision. A step that cannot pass its own verify after three
+tries needs a human (wrong approach, wrong spec, or wrong verify), not more
+tokens.
 
 ## Metabolism — governed writeback
 
@@ -181,13 +208,18 @@ platform renders it as live progress). It is append-only JSONL: one JSON event
 per line, appended with `Bash` (`echo '<json>' >> .orchestrate/ledger.jsonl`).
 Never rewrite or delete lines. Timestamps: `date -u +%FT%TZ`.
 
+**Quoting hazard:** the single-quoted `echo` breaks on `'` inside the JSON —
+and a mangled line corrupts the run's only durable memory. Keep every free-text
+field (`intent`, `question`, `title`) to one line with no single quotes:
+rephrase (`don't` → `do not`) before writing, never fight the shell escaping.
+
 Events and when to write them:
 
 | Event | When | Shape |
 | ----- | ---- | ----- |
 | `run_start` | right after binding intent | `{"e":"run_start","run":"r-<yyyymmdd>-<slug>","intent":"...","ts":"..."}` |
 | `plan` | after wiring the graph, and EVERY time the graph changes | `{"e":"plan","run":"...","steps":[{"n":1,"skill":"research","title":"..."}, …]}` — full current plan; latest `plan` line wins; steps may be added, never removed |
-| `step` | immediately BEFORE each dispatch, and again after its verify | `{"e":"step","run":"...","n":3,"skill":"implement","status":"dispatched\|done\|failed","attempt":1,"evidence":"<file or one-line result>","ts":"..."}` — rework = same `n`, next `attempt` |
+| `step` | immediately BEFORE each dispatch, and again after its verify | `{"e":"step","run":"...","n":3,"skill":"implement","status":"dispatched\|done\|failed\|skipped","attempt":1,"evidence":"<file or one-line result>","ts":"..."}` — rework = same `n`, next `attempt`; a step a replan made obsolete gets `skipped` with the reason in `evidence` (plan lines are never removed, so this is how an obsolete step closes) |
 | `gate` | when stopping at a human gate | `{"e":"gate","run":"...","kind":"inline_accept","question":"...","ts":"..."}` |
 | `run_end` | at delivery or abandonment | `{"e":"run_end","run":"...","result":"delivered\|paused\|abandoned","ts":"..."}` |
 
@@ -196,6 +228,24 @@ step is required and should be the step's verify log path
 (`.orchestrate/verify/step-<n>-attempt-<k>.log`); a `done` with no evidence is
 a false claim.
 
+## Resume — cold re-entry (deterministic, not from memory)
+
+Whenever you enter with an existing ledger — after compaction, an interrupted
+session, or a wake-up — do NOT continue from what you remember. Replay:
+
+1. Read `.orchestrate/ledger.jsonl`. The active run is the last `run_start`
+   with no matching `run_end`. Its `intent` line — not your recollection — is
+   what you are delivering. No active run → this is a fresh start.
+2. Rebuild state from events alone: the latest `plan` wins; `done` and
+   `skipped` steps are closed; prior `attempt` values count toward each step's
+   cap of 3.
+3. **A dangling `dispatched`** (no `done`/`failed`/`skipped` after it) means
+   that attempt was cut off mid-flight. Trust it in NEITHER direction: run that
+   step's verify command now. Pass → append its `done` with the evidence.
+   Fail → re-dispatch as the next attempt.
+4. Continue the loop from the first open step. If the run was stopped at a
+   `gate`, re-ask that gate's question — never assume it was answered.
+
 ## Context discipline (stay lean)
 
 - **Files, not paste.** Move artifacts between steps as files. Never paste a
@@ -211,6 +261,8 @@ a false claim.
 - Hardcoding a fixed skill order instead of wiring outputs→inputs
 - Pasting a step's full output into your context instead of handing a file
 - Re-dispatching a step the ledger already marks done
+- Resuming from memory instead of replaying the ledger — or trusting a
+  dangling `dispatched` in either direction without running its verify
 - Dispatching a step without first writing its `dispatched` ledger line
 - Ending a run without a `run_end` ledger line
 - Marking a step done on the subagent's say-so, without your own verify command
@@ -219,4 +271,7 @@ a false claim.
 - Appending to `taste/*` without reading it first (duplicate/contradiction risk)
 - Dispatching a design/build skill in an existing codebase while `registry/*`
   is empty (first-run preflight skipped)
+- Delivering a runnable app this run changed with no `smoke-test` verdicts
+  (unit tests are not that evidence)
+- Dispatching `design-ui` while the resolved `taste/design-system` is empty
 - Marking the run complete without every step's `verify` evidence