orchestrix-skills 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "orchestrix-skills",
+  "version": "0.1.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"],
+  "skills": "./skills"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orchestrix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# orchestrix-skills
+
+Capability-first AI development as an **Anthropic-native skill graph**. Organize
+by capability, not by role agents. A warm-context orchestrator wires small,
+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.
+
+## The graph
+
+```
+intent
+  └─ orchestrate (root: warm context, wires skills by output→input, enforces gates)
+       ├─ brainstorm ──(needs facts?)─→ research
+       ├─ (has UI?) ──→ design-system (once) → design-ui
+       ├─ (arch decision?) ──→ design-architecture
+       └─ draft-story → implement → run-tests → review-code → commit
+                                      ↑ verify         ↑ design-review (UI only)
+                                      (objective)      ↑ accept (batched)
+```
+
+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)
+
+```bash
+npx orchestrix-skills install            # default: Claude Code (.claude/skills/)
+npx orchestrix-skills install --ide cursor
+```
+
+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.
+
+For Claude Code you can also install via the plugin marketplace:
+`/plugin install orchestrix-skills`.
+
+## How it works
+
+- **Every skill is a standard [Anthropic Agent Skill](https://agentskills.io/specification)**
+  plus a `metadata.contract` extension. Vanilla runtimes read `name` +
+  `description` + `allowed-tools` and ignore the contract, so each skill runs
+  anywhere. The orchestrator additionally reads the contract to wire, gate, and
+  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).
+
+## Design
+
+Full design rationale: `Skill 编排器与最小契约设计` (the capability-first model,
+the 6-field contract, lights-out accept gates, the knowledge KB, distribution).
+
+## Attribution
+
+The TDD, verification, and code-review disciplines adapt patterns from
+[obra/superpowers](https://github.com/obra/superpowers) (MIT). The world-class
+design approach draws on gstack's design skills and the anti-slop consensus. The
+contract, orchestrator, knowledge layer, and graph model are original.
+
+MIT © 2026 Orchestrix

package/bin/install.js

@@ -0,0 +1,82 @@
+#!/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, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Where each runtime auto-loads skills from (relative to the target project).
+const IDE_SKILLS_DIR = {
+  claude: ".claude/skills",
+  codex: ".codex/skills",
+  // Cursor / Windsurf don't auto-load Anthropic skills; they read rule files.
+  // For those, skills are copied as reference rules (best-effort) until native support lands.
+  cursor: ".cursor/rules/orchestrix",
+  windsurf: ".windsurf/rules/orchestrix",
+};
+
+function arg(name, fallback) {
+  const i = process.argv.indexOf(`--${name}`);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : fallback;
+}
+
+function help() {
+  console.log(`orchestrix-skills — capability-first AI dev skill graph
+
+Usage:
+  npx orchestrix-skills install [--ide claude|codex|cursor|windsurf] [--dir <project>]
+
+What it does (free, no license):
+  1. Copies the skills into your runtime's skills dir (default: .claude/skills/)
+  2. Scaffolds knowledge/ + core-config.yaml (never overwrites an existing brain)
+
+Premium (hosted orchestrator, KB hosting, teams, 建造中心):
+  see https://orchestrix-mcp.youlidao.ai`);
+}
+
+function install() {
+  const ide = arg("ide", "claude");
+  const dir = arg("dir", process.cwd());
+  const rel = IDE_SKILLS_DIR[ide];
+  if (!rel) {
+    console.error(`Unknown --ide "${ide}". Options: ${Object.keys(IDE_SKILLS_DIR).join(", ")}`);
+    process.exit(1);
+  }
+
+  // 1. Skills (capabilities) — always refreshed.
+  const skillsTarget = join(dir, rel);
+  mkdirSync(skillsTarget, { recursive: true });
+  cpSync(join(PKG, "skills"), skillsTarget, { recursive: true });
+  const count = readdirSync(join(PKG, "skills"), { withFileTypes: true }).filter((d) => d.isDirectory()).length;
+  console.log(`✓ ${count} skills → ${rel}/`);
+
+  // 2. Knowledge (the brain) — scaffold only if absent; never clobber the user's brain.
+  const knowledgeTarget = join(dir, "knowledge");
+  if (existsSync(knowledgeTarget)) {
+    console.log("• knowledge/ exists — left untouched (your brain is yours)");
+  } else {
+    cpSync(join(PKG, "project-scaffold", "knowledge"), knowledgeTarget, { recursive: true });
+    console.log("✓ knowledge/ scaffolded (taste / architecture / registry)");
+  }
+
+  // 3. core-config — namespace → path mapping; scaffold only if absent.
+  const cfgTarget = join(dir, "core-config.yaml");
+  if (existsSync(cfgTarget)) {
+    console.log("• core-config.yaml exists — left untouched");
+  } else {
+    cpSync(join(PKG, "project-scaffold", "core-config.yaml"), cfgTarget);
+    console.log("✓ core-config.yaml scaffolded");
+  }
+
+  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`);
+}
+
+const cmd = process.argv[2];
+if (cmd === "install") install();
+else help();

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "orchestrix-skills",
+  "version": "0.1.0",
+  "description": "Capability-first AI development skill graph — Anthropic-native skills that run in any agent runtime.",
+  "type": "module",
+  "bin": {
+    "orchestrix-skills": "bin/install.js"
+  },
+  "files": [
+    "skills",
+    "project-scaffold",
+    "bin",
+    ".claude-plugin"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "agent-skills",
+    "skills",
+    "orchestrix",
+    "ai-development"
+  ],
+  "homepage": "https://orchestrix-mcp.youlidao.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dorayo/orchestrix-skills.git"
+  },
+  "bugs": "https://github.com/dorayo/orchestrix-skills/issues",
+  "license": "MIT"
+}

package/project-scaffold/README.md

@@ -0,0 +1,33 @@
+# Project Scaffold
+
+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.
+│   ├── taste/         coding-standards, brand, design-system
+│   ├── architecture/  structure, decisions, conventions
+│   └── registry/      api, db, models
+├── docs/          # work products — what skills WRITE (outputs:). Human-reviewed.
+│   ├── specs/    stories/    research/   (created by skills at runtime)
+├── src/  tests/   # the deliverable
+└── core-config.yaml   # logical namespace → physical path mapping
+```
+
+## Two audiences, two formats
+
+- **`knowledge/` is for the AI to read** (as context slices), and for humans to
+  **audit and curate** — not to browse. Write it as **structured, chunked, terse
+  data with provenance**, never as prose. See `knowledge/README.md`.
+- **`docs/` is for humans to review** (they approve specs/stories at the accept
+  gates) — and is also consumed by skills as handoff input. Write it **clear and
+  unambiguous** so a human can judge it.
+
+## Brownfield
+
+Don't move existing files. Point `core-config.yaml`'s namespaces at wherever the
+project already keeps that knowledge. Skills never change — only the mapping does.

package/project-scaffold/core-config.yaml

@@ -0,0 +1,19 @@
+# Maps the logical namespaces used in skill contracts (reads: / updates: / outputs:)
+# to physical paths in THIS project. Skills address knowledge logically and never
+# hardcode paths — for brownfield projects, change the paths here, not the skills.
+
+knowledge: # the brain — skills READ slices of this (reads:), metabolism writes back (updates:)
+  taste: knowledge/taste # coding-standards, brand, design-system
+  architecture: knowledge/architecture # structure, decisions, conventions
+  registry: knowledge/registry # api, db, models
+
+work: # work products — skills WRITE these (outputs:), humans review at gates
+  specs: docs/specs # <slug>.md / -ui.md / -arch.md
+  stories: docs/stories # <slug>.md (flat, origin tag)
+  research: docs/research # research briefs
+
+runtime: .orchestrix/runtime # ledger + step handoff files (ephemeral, gitignored)
+
+# Org-level cascade (shared taste/standards across many products) is intentionally
+# NOT enabled yet (YAGNI). When needed: add an `extends:` base that project paths
+# override. The logical namespaces above do not change when cascade is added.

package/project-scaffold/knowledge/README.md

@@ -0,0 +1,34 @@
+# knowledge/ — the project brain
+
+**Audience: AI-primary, human-audited.** Skills read slices of this as context
+(the `reads:` field). Humans do not browse it — they **seed, audit, and correct**
+it. The metabolism loop (design-\* skills, human accept corrections) writes back
+here via `updates:`.
+
+## Format rules (these files are data, not docs)
+
+1. **Structured, not prose.** Lists / entries / records — parseable by AI,
+   diffable by a human auditor. No essays.
+2. **Chunked for slice retrieval.** A skill reads only the slice it needs. Keep
+   files small and single-topic so nobody loads the whole brain (that would
+   re-introduce the context tax we removed).
+3. **Provenance on every entry.** `source` (human | which skill), `added`
+   (date), `approved_by`. The brain poisons every run if wrong — entries must be
+   auditable: "why does the org believe this?"
+4. **Append / supersede, don't silently rewrite.** Corrections add or supersede
+   entries so the history of what the org learned stays visible.
+
+## Governance
+
+Writing here is a **high-authority, audited** action. AI writes back only through
+the metabolism loop, and the human is the value anchor for the brain — exactly as
+the accept gate is the value anchor for work products.
+
+## Slices
+
+- `taste/` — declarative taste: how things should be made (read by implement,
+  review-code, design-ui).
+- `architecture/` — system structure, conventions, and decisions (read by
+  draft-story, design-architecture, implement).
+- `registry/` — structured facts: the actual api / db / models (read by
+  draft-story, implement; updated by implement as they are built).

package/project-scaffold/knowledge/architecture/decisions.md

@@ -0,0 +1,32 @@
+# architecture/decisions
+
+ADR-style entries that `draft-story`, `design-architecture`, and `implement`
+read. One entry per decision, terse, with provenance. Append-only; supersede,
+do not rewrite.
+
+## AD-001: Capability-first orchestration
+
+- decision: Organize by capability (skills) wired by an orchestrator, not by role agents with handoffs.
+- context: Role-handoff pipelines cost 30–50x in cold-start re-reads; strong models make them unnecessary.
+- alternatives: BMAD-style role agents (rejected — handoff tax); single monolithic agent (rejected — no isolation/verification).
+- status: accepted
+- source: human
+- added: 2026-06-27
+- approved_by: dorayo
+- ref: cc-plans/Skill编排器与最小契约设计-v0.1.md
+
+<!--
+Entry shape (copy for new decisions):
+
+## AD-NNN: <title>
+- decision: <one line>
+- context: <why it came up, one line>
+- alternatives: <what was rejected, one line>
+- status: accepted | superseded by AD-MMM
+- source: design-architecture | human
+- added: <date>
+- approved_by: <who>
+
+Metabolism: design-architecture appends new ADRs here; a superseding decision
+sets the old one's status to "superseded by AD-MMM" rather than deleting it.
+-->

package/project-scaffold/knowledge/registry/api.yaml

@@ -0,0 +1,15 @@
+# registry/api — structured record of this project's API surface.
+# Read by draft-story (to wire Interfaces) and implement. Updated by implement
+# (metabolism) as endpoints are built. Seed is empty — this is honest: no
+# endpoints exist yet. Add records in the shape shown below.
+
+endpoints: [] # implement appends here as endpoints are built
+
+# Record shape (copy for each new endpoint):
+#   - path: "POST /auth/login"
+#     request:  { email: string, password: string }
+#     response: { token: string }
+#     errors:   [ "400 Email required", "401 Invalid credentials" ]
+#     story:    user-login        # the story that produced it (origin trace)
+#     added_by: implement
+#     added:    2026-06-27

package/project-scaffold/knowledge/taste/brand.md

@@ -0,0 +1,20 @@
+# taste/brand
+
+Brand voice and identity `design-ui` and copy decisions read. **Authored by the
+`design-system` skill** (and refined by the metabolism loop). Empty until then.
+Structured, with provenance.
+
+```yaml
+voice: "" # how the product sounds: e.g. "plain, confident, no hype"
+tone_rules: [] # do / don't, e.g. ["no exclamation marks", "verbs over nouns"]
+naming: "" # product/feature naming conventions
+logo_usage: "" # clear space, min size, what not to do
+do_not: [] # brand red lines
+
+provenance: { source: design-system, added: "", approved_by: "" }
+```
+
+<!--
+Metabolism: when a human corrects brand/voice at an accept gate, append or
+supersede an entry here (with date + approver). Supersede, don't delete.
+-->

package/project-scaffold/knowledge/taste/coding-standards.md

@@ -0,0 +1,17 @@
+# taste/coding-standards
+
+Rules `implement` and `review-code` read as their taste slice. Terse rules, each
+with provenance. Not prose. Seed examples below — replace with this project's.
+
+| id            | rule                                                                | rationale                                  | source | added      | approved_by |
+| ------------- | ------------------------------------------------------------------- | ------------------------------------------ | ------ | ---------- | ----------- |
+| ts-strict     | TypeScript strict mode on; no `any` without an inline justification | Catches runtime errors at compile time     | human  | 2026-06-27 | dorayo      |
+| named-exports | Named exports only; no default exports                              | Refactor-safe imports, better autocomplete | human  | 2026-06-27 | dorayo      |
+| no-swallow    | Never swallow errors; handle or rethrow with context                | Silent failures are undebuggable           | human  | 2026-06-27 | dorayo      |
+| pure-io-split | Keep I/O at the edges; core logic pure and testable                 | Testability, fewer mocks                   | human  | 2026-06-27 | dorayo      |
+
+<!--
+Metabolism: when a human corrects taste at the accept gate, append or supersede a
+row here (source: <skill or human>, with date + approver). Supersede, don't
+delete — keep what the org learned visible.
+-->

package/project-scaffold/knowledge/taste/design-system.md

@@ -0,0 +1,32 @@
+# taste/design-system
+
+The durable visual system `design-ui` applies. **Authored by the `design-system`
+skill** — empty until then (honest). Structured, with provenance. Specifics, not
+adjectives.
+
+```yaml
+memorable_thing: "" # the one thing to remember on first sight (design-system fills)
+references: [] # 2-3 named products this steals direction from
+distinctive_rule: "" # the one rule that makes this product's UI unmistakable
+
+typography:
+  typeface: "" # named (not Inter/Roboto unless deliberate + justified)
+  scale: [] # real sizes/weights, e.g. [12/400, 14/400, 16/500, 24/600, 40/700]
+  line_height: ""
+color: # roles, not framework swatches
+  bg: ""
+  surface: ""
+  text: ""
+  accent: ""
+  states: { success: "", warning: "", error: "" }
+  contrast_floor: "" # e.g. WCAG AA 4.5:1 body text
+space:
+  scale: [] # e.g. [4, 8, 12, 16, 24, 32, 48, 64]
+  density: "" # tight | airy, tied to the product
+motion:
+  timing: "" # e.g. 150ms enter / 100ms exit
+  easing: ""
+  use_where: "" # and where motion is deliberately absent
+
+provenance: { source: design-system, added: "", approved_by: "" }
+```

package/skills/README.md

@@ -0,0 +1,74 @@
+# Skills (v0.1)
+
+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)
+plus a `metadata.contract` extension. A vanilla Claude Code / Claude App / Agent
+SDK runtime reads `name` + `description` + `allowed-tools` and ignores
+`metadata.contract`, so each skill runs anywhere. Our orchestrator additionally
+reads `metadata.contract` to wire, gate, and verify.
+
+### The contract (6 fields)
+
+| Field         | Meaning                                            |
+| ------------- | -------------------------------------------------- |
+| `description` | When to use / when NOT to use. The selection key.  |
+| `inputs`      | What the skill needs to run.                       |
+| `outputs`     | What it produces (enables output→input wiring).    |
+| `authority`   | What it may touch / spend. Its blast radius.       |
+| `verify`      | Objective, automated success check. Never skipped. |
+| `accept`      | Subjective human sign-off: `{ when, timing }`.     |
+
+`accept.timing`:
+
+- `deferred` (default) — batch the human check at the end (lights-out middle).
+- `inline` — block now. Forced by the orchestrator when `authority` is
+  irreversible / high blast radius (spend, send, deploy, delete, sign).
+
+`verify` is objective and runs autonomously. `accept` is human judgment. They
+are different gates; never merge them.
+
+## The graph (this directory)
+
+```
+intent
+  └─ orchestrate (root: warm context, wires skills by output→input, enforces gates)
+       ├─ brainstorm ──(needs facts?)─→ research
+       ├─ (has UI?) ──→ design-system (once) → design-ui
+       ├─ (arch decision?) ──→ design-architecture
+       └─ draft-story → implement → run-tests → review-code → commit
+                                      ↑ verify         ↑ design-review (UI only)
+                                      (objective)      ↑ accept (batched)
+```
+
+Human gates are front-loaded (planning = direction) and at the very end
+(acceptance); the build loop runs lights-out, gated only by objective `verify`.
+
+### Skills
+
+| Skill                 | Phase                    | accept             |
+| --------------------- | ------------------------ | ------------------ |
+| `orchestrate`         | root                     | inline (delivery)  |
+| `brainstorm`          | planning                 | inline (hard gate) |
+| `research`            | planning (optional)      | never              |
+| `design-system`       | planning (UI, once)      | inline             |
+| `design-ui`           | planning (UI only)       | inline             |
+| `design-architecture` | planning (when needed)   | inline             |
+| `draft-story`         | planning                 | inline (direction) |
+| `implement`           | build                    | deferred           |
+| `run-tests`           | build (verify primitive) | never              |
+| `review-code`         | build                    | deferred           |
+| `design-review`       | build (UI only)          | deferred           |
+| `commit`              | build                    | deferred           |
+
+## Attribution
+
+The TDD, verification, and code-review disciplines adapt patterns from
+[obra/superpowers](https://github.com/obra/superpowers) (MIT). The contract,
+orchestration, and taste layers are original.

package/skills/brainstorm/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: brainstorm
+description: Use before any build, when an idea or intent must become an agreed, sharp requirement and design — explores intent, weighs approaches, and decomposes if too big.
+license: MIT
+allowed-tools: [Read, Write, Grep, Glob]
+metadata:
+  contract:
+    inputs: [intent, project_context]
+    reads: [taste/*, architecture/*, registry/*]
+    outputs: [specs/<slug>.md]
+    authority: "Write to the specs namespace (default docs/specs/) only. No code, no production, no spend."
+    verify: "No placeholders; no internal contradiction; single-plan scope (or explicitly decomposed); no requirement open to two readings."
+    accept:
+      when: "Always — HARD GATE: nothing is built before the design is approved."
+      timing: inline
+---
+
+# Brainstorm
+
+Turn a rough intent into an agreed, sharp requirement and design through
+dialogue. This is the front of the funnel and the project's main direction gate.
+
+**Core principle:** "Too simple to need a design" is where unexamined
+assumptions waste the most work. Every intent gets a design — short if simple,
+but always presented and approved.
+
+> HARD GATE: do not invoke any build skill, write code, or scaffold anything
+> until the design is approved. (`accept: inline`.)
+
+## Process
+
+1. **Explore context.** Read the relevant `knowledge/*` slices and existing
+   code before asking anything.
+2. **Scope check first.** If the intent spans independent subsystems, say so and
+   help decompose into sub-projects — each gets its own spec → stories → build.
+   Don't refine details of something that should be split.
+3. **Clarify, one question at a time.** Purpose, constraints, success criteria.
+   Prefer multiple-choice. Never batch questions.
+4. **Propose 2–3 approaches** with trade-offs; lead with your recommendation and
+   why.
+5. **Present the design in sections**, scaled to complexity; confirm each
+   section before moving on. Cover: behavior, data flow, error handling, testing.
+6. **Apply YAGNI ruthlessly.** Cut every feature the intent does not require.
+
+## Output: the spec
+
+Write one file in the specs namespace (default `docs/specs/<slug>.md`):
+
+```markdown
+---
+origin: <stable short handle of this intent>
+---
+
+# <Title>
+
+## Goal — one sentence: what this delivers and for whom.
+
+## Requirement — the agreed scope, in prose a human approved.
+
+## Approach — the chosen approach and why (1–2 lines on rejected ones).
+
+## Constraints — hard rules, verbatim (see draft-story).
+
+## Downstream — flags for the orchestrator:
+
+- needs UI design? yes/no (→ design-ui)
+- needs an architecture decision? yes/no (→ design-architecture)
+- open question needing facts? yes/no (→ research)
+
+## Out of Scope — what this deliberately excludes.
+```
+
+The `Downstream` flags tell the orchestrator which planning skills to wire next.
+
+## Spec self-review (fix inline)
+
+1. Placeholders (TBD/TODO/vague)? Replace with the real thing.
+2. Any section contradict another?
+3. Single-plan scope, or does it still need decomposition?
+4. Any requirement open to two readings? Pick one, make it explicit.
+
+## Done
+
+Write the spec, then stop for approval (`accept: inline`). On approval the
+orchestrator wires the flagged planning skills, then `draft-story`. Brainstorm
+never builds.

package/skills/commit/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: commit
+description: Use when verified work is ready to be recorded in version control.
+license: MIT
+allowed-tools: [Read, Bash]
+metadata:
+  contract:
+    inputs: [verified_changes, message_intent]
+    reads: []
+    outputs: [git_commit]
+    authority: "git add and commit on the current branch. No push, no force, no commit to the default branch."
+    verify: "run-tests is green AND the staged diff matches message_intent."
+    accept:
+      when: "never — a local commit is low-risk and reversible."
+      timing: deferred
+---
+
+# Commit
+
+Record verified work as one conventional commit.
+
+**Core principle:** Commit only what is verified. Never commit to claim progress.
+
+## Preconditions
+
+- `run-tests` is green (run it now if unsure; do not trust a remembered run).
+- You are NOT on the default branch (`main`/`master`). If you are, stop and ask.
+- The staged change matches `message_intent` — review `git diff --staged` first.
+
+## Steps
+
+1. Stage only the intended files: `git add <paths>`. Never `git add .` blindly.
+2. Confirm the staged diff: `git diff --staged`.
+3. Confirm nothing forbidden is staged: no `dist/`, no build artifacts, no
+   secrets, no `.env*`.
+4. Commit with the message format below.
+
+## Message format (required)
+
+A conventional-commit subject, then the mandatory footer, exactly:
+
+```
+<type>(<scope>): <summary>
+
+<optional body>
+
+🤖 Generated with [Orchestrix](https://orchestrix-mcp.youlidao.ai)
+```
+
+- `<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.
+
+## Done
+
+Output the commit SHA and subject. Do not push.