orchestrix-skills 0.8.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,7 +1,7 @@
 #!/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.
+// 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";
@@ -41,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`);
 }
 
@@ -205,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.8.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