@gobing-ai/superskill 0.1.3 → 0.1.4

package/README.md

@@ -4,185 +4,158 @@ Multi-agent skill, command, subagent, hook, and MCP config distribution and auth
 
 ## Why
 
-Coding agents (Claude Code, Codex, Pi, OpenCode, Antigravity, Hermes, …) each use different config formats for skills, slash commands, subagents, hooks, and MCP servers. Maintaining hand-synced copies across agents is error-prone and doesn't scale.
+Coding agents (Claude Code, Codex, Pi, OpenCode, Antigravity, Hermes, omp) each use different config formats for skills, slash commands, subagents, hooks, and MCP servers. Maintaining hand-synced copies across agents is error-prone and doesn't scale.
 
 **superskill** solves this with two layers:
 
 1. **Distribution** — `superskill install` takes a Claude Code plugin as the single source of truth and distributes it to any target agent, using [rulesync](https://www.npmjs.com/package/rulesync) as the format-conversion engine.
-2. **Authoring + quality** — Five type commands (`agent`, `skill`, `command`, `hook`, `magent`) provide scaffold → validate → evaluate → refine → evolve workflows with persistent quality data.
+2. **Authoring + quality** — Five type commands (`agent`, `skill`, `command`, `hook`, `magent`) provide scaffold → validate → evaluate → refine → evolve workflows with persistent quality data in SQLite.
 
-## Supported targets
-
-| Target | Engine | Notes |
-|--------|--------|-------|
-| `claude` | Direct marketplace install | Source of truth |
-| `codex` | rulesync | `~/.agents/skills/` |
-| `pi` | rulesync | Subagents → Pi native agent format |
-| `omp` | superskill (copy) | Pi variant with custom root and binary (uses `pi` rulesync surrogate) |
-| `opencode` | rulesync | `~/.agents/skills/` |
-| `antigravity-cli` | rulesync | `~/.gemini/antigravity-cli/skills/` |
-| `antigravity-ide` | rulesync | `~/.gemini/config/skills/` |
-| `hermes` | superskill (copy) | `~/.hermes/skills/` (uses `opencode` rulesync surrogate) |
-
-**Deprecated:** Gemini CLI, old unified Antigravity.
+## Install
 
-## Quick start
-
-### Prerequisites
+```bash
+npm i -g @gobing-ai/superskill
+```
 
-- [Bun](https://bun.sh/) ≥ 1.3.14
-- [proto](https://moonrepo.dev/proto) (optional — pinned versions in `.prototools`)
+From source (contributors):
 
 ```bash
-# Install pinned tool versions (optional)
-proto use
-
-# Install dependencies
+proto use          # install pinned tool versions (Bun, etc.)
 bun install
+bun run build
+cd apps/cli && bun link
 ```
 
-### Run the CLI (development)
+Requires [Bun](https://bun.sh/) ≥ 1.3.14. See [`docs/help/installation.md`](docs/help/installation.md) for details and troubleshooting.
+
+## Quick start
 
 ```bash
-# Via workspace filter
-bun run dev
+# Distribute a plugin to every supported target
+superskill install my-plugin --targets all
 
-# Or directly
-bun run apps/cli/src/index.ts --help
-```
+# Author a skill: scaffold → validate → evaluate → refine
+superskill skill scaffold my-skill --description "Deploy a Cloudflare Worker"
+superskill skill validate my-skill
+superskill skill evaluate my-skill --save
+superskill skill refine my-skill --auto
 
-### Build a standalone binary
+# Package a skill for distribution, or merge skills
+superskill skill package my-skill
+superskill skill migrate ./source-skill-1 ./source-skill-2 ./dest-skill
 
-```bash
-bun run build
-# Output: dist/cli/superskill
+# Emit a hook to a single target agent
+superskill hook emit my-hook --target pi
 ```
 
+Full walkthrough: [`docs/help/quick_start.md`](docs/help/quick_start.md).
+
 ## Commands
 
-### `superskill install` — distribute a plugin to target agents
+| Command | What it does | Docs |
+|---------|--------------|------|
+| `install` | Distribute a plugin's skills, commands, subagents, hooks, MCP to target agents | [`cmd_install.md`](docs/help/cmd_install.md) |
+| `agent` | Manage subagent definitions (scaffold/validate/evaluate/refine/evolve) | [`cmd_agent.md`](docs/help/cmd_agent.md) |
+| `skill` | Manage skill definitions (+ `package`, `migrate`) | [`cmd_skill.md`](docs/help/cmd_skill.md) |
+| `command` | Manage slash command definitions | [`cmd_command.md`](docs/help/cmd_command.md) |
+| `hook` | Manage hook definitions (+ `emit`) | [`cmd_hook.md`](docs/help/cmd_hook.md) |
+| `magent` | Manage main-agent configurations | [`cmd_magent.md`](docs/help/cmd_magent.md) |
+
+The five type commands share a common five-operation lifecycle (scaffold → validate → evaluate → refine → evolve) with type-specific quality dimensions and rubrics. Each command doc includes usage, architecture diagrams, sequence diagrams, and source-file references.
 
-Install a Claude Code plugin's skills, commands, subagents, hooks, and MCP config to target coding agents.
+**Help docs index:** [`docs/help/index.md`](docs/help/index.md)
+
+### Operation lifecycle
 
 ```
-superskill install [options] <plugin>
+scaffold → validate → evaluate → refine → evolve
+                ↑                       │
+                └─── longitudinal ───────┘
 ```
 
-| Argument / Option | Description | Default |
-|-------------------|-------------|---------|
-| `<plugin>` | Plugin name to install (required) | — |
-| `--marketplace <path>` | Path to `.claude-plugin/marketplace.json` or its containing directory | CWD's `.claude-plugin/` |
-| `--targets <list>` | Comma-separated target agents, or `all` | all configured |
-| `--no-global` | Install to project-level instead of user-level global directories | `false` |
-| `--dry-run` | Preview without writing files | `false` |
-| `--verbose` | Print each step and file copy | `false` |
+| Operation | Purpose | Quality gate |
+|-----------|---------|-------------|
+| `scaffold` | Create new entity from template | Structure validation |
+| `validate` | Check structure and frontmatter | Pre-check spur rules |
+| `evaluate` | Score quality across dimensions | Rubric-weighted scoring (Scorer persona) |
+| `refine` | Apply low-risk fixes automatically | Fix classification (auto-apply / suggest / flag) |
+| `evolve` | Propose longitudinal improvements | Double-loop gate (Author → Skeptic → Judge) |
+
+Extra operations by type:
+
+| Type | Extra operation | What it does |
+|------|----------------|-------------|
+| `skill` | `package` | Bundle a skill + companion files into a distributable archive |
+| `skill` | `migrate` | Merge one or more source skills into a destination skill |
+| `hook` | `emit` | Emit a hook definition to a single target agent |
 
-**Examples:**
+## Quality system
+
+### Rubric-driven evaluation
+
+`evaluate` scores entities across type-specific quality dimensions using YAML rubrics. Ships with 5 package-default rubrics (`agent`, `skill`, `command`, `hook`, `magent`) — load custom ones with `--rubric <path>`.
 
 ```bash
-# Install a plugin to all supported targets
-superskill install rd3 --targets all
+# Heuristic evaluation (built-in checks)
+superskill skill evaluate my-skill --save
 
-# Install to specific targets only
-superskill install rd3 --targets codex,pi,antigravity-cli
+# Rubric evaluation — emit scoring brief for an external model
+superskill skill evaluate my-skill --rubric --json > scoring-brief.json
 
-# Preview what would be written without touching the filesystem
-superskill install rd3 --targets all --dry-run
+# Ingest scored result and persist
+superskill skill evaluate my-skill --ingest scored-result.json --save
 ```
 
----
+### Two-call seam (Scorer / Author / Skeptic / Judge)
 
-### Type Commands — `agent`, `skill`, `command`, `hook`, `magent`
+The CLI never scores or generates inline. Quality operations drive four personas via a two-call seam — the CLI emits envelopes, personas process offline, the CLI ingests results.
 
-Five type commands manage agent-facing resources:
+| Persona | Role | Input | Output |
+|---------|------|-------|--------|
+| **Scorer** | Rubric judge | Envelope from `evaluate --rubric --json` | `{ rubric_version, dimensions: { score, note } }` |
+| **Author** | Rewriter | Envelope from `evolve --propose-only --json` | `ProposedChange[]` with `anchor_hash` |
+| **Skeptic** | Refuter | Proposal + verbatim goal anchor | `{ ok, violations[] }` |
+| **Judge** | Tournament selector | Multiple candidate proposals | Winning proposal ID |
 
-| Command | Description |
-|---------|-------------|
-| `superskill agent` | Manage subagent definitions |
-| `superskill skill` | Manage skill definitions |
-| `superskill command` | Manage slash command definitions |
-| `superskill hook` | Manage hook definitions |
-| `superskill magent` | Manage main-agent configurations |
+### Double-loop gate for `evolve`
 
-Each type command supports the following five operations:
+`evolve --ingest <file>` applies authored proposals through a four-gate quality control:
 
-#### 1. `scaffold` — Create a new file from templates
-```bash
-superskill <type> scaffold <name> [options]
-```
-* **Options:**
-  * `--description <text>`: Set description frontmatter.
-  * `--target <agent>`: Target agent format.
-  * `--output <dir>`: Target directory for the output file.
-  * `--force`: Overwrite existing files.
+1. **Deterministic validate** — 0 errors required
+2. **Δ-margin** — score must improve by ≥ `--margin` (default 0.05)
+3. **Anchor hash** — goal anchor unchanged (hash-gated)
+4. **Skeptic review** — regressive merges rejected and restored
 
-#### 2. `validate` — Run schema and compliance check
-```bash
-superskill <type> validate <nameOrPath> [options]
-```
-* **Options:**
-  * `--target <agent>`: Target agent to validate format compliance.
-  * `--strict`: Enable optional/warning-level checks.
-  * `--json`: Output findings in JSON format.
+Version-aware trends partition by `rubric_version`, preventing false regression signals when rubrics are updated.
 
-#### 3. `evaluate` — Score content against 5 quality dimensions
-```bash
-superskill <type> evaluate <nameOrPath> [options]
-```
-* **Options:**
-  * `--target <agent>`: Target agent formatting rules.
-  * `--save`: Save report to SQLite database.
-  * `--json`: Output report in JSON format.
+## Supported targets
 
-#### 4. `refine` — Run automated fixes and suggestions
-```bash
-superskill <type> refine <nameOrPath> [options]
-```
-* **Options:**
-  * `--target <agent>`: Target agent formatting rules.
-  * `--auto`: Apply automatic fixes without confirmation.
-  * `--save`: Save post-remediation report to SQLite database.
+| Target | Engine | Output location |
+|--------|--------|-----------------|
+| `claude` | Direct `claude plugin install` | Claude Code marketplace |
+| `codex` | rulesync | `~/.agents/skills/` |
+| `pi` | rulesync + superskill hook shim | Pi native format |
+| `omp` | superskill copy (via `pi` surrogate) | `~/.omp/agent/skills/` |
+| `opencode` | rulesync | `~/.agents/skills/` |
+| `antigravity-cli` | rulesync | `~/.gemini/antigravity-cli/skills/` |
+| `antigravity-ide` | rulesync | `~/.gemini/config/skills/` |
+| `hermes` | superskill copy (via `opencode` surrogate) | `~/.hermes/skills/` |
 
-#### 5. `evolve` — Apply longitudinal improvements from evaluation history
-```bash
-superskill <type> evolve <name> [options]
-```
-* **Options:**
-  * `--target <agent>`: Target agent formatting rules.
-  * `--from <timestamp>`: Baseline evaluation window.
-  * `--proposeOnly`: Propose modifications and save as draft without applying.
-  * `--accept <proposal_id>`: Accept and apply a specific draft proposal.
-  * `--reject <proposal_id>`: Reject a specific draft proposal.
+Since ts-ai-runner 0.3.21, `omp`, `hermes`, and `antigravity-cli` are canonical `AgentName` values — slash-command dialect translation maps 1:1. Only `antigravity-ide` still bridges through `opencode`.
 
----
+## Bundled `cc` plugin
 
-## Project structure
+superskill ships with a Claude Code plugin at [`plugins/cc/`](plugins/cc/) (marketplace name: `cc`, version `0.1.1`) that demonstrates the full authoring lifecycle and provides the meta-agent skills the expert personas reference:
 
-```
-apps/
-  cli/                 # Commander-based CLI (the binary)
-    src/
-      commands/        # CLI command registration (install, type commands)
-      pipeline/        # Conversion stages (pure functions)
-      content/         # Frontmatter parse/edit, name resolution
-      operations/      # scaffold, validate, evaluate, refine, evolve logic
-      quality/         # Dimension definitions + per-type evaluators
-      store/           # SQLite via @gobing-ai/ts-db
-      templates/       # Default templates shipped with npm
-      targets.ts       # Target enum + mapping tables
-      config.ts        # superskill.jsonc schema + loader
-      marketplace.ts   # Marketplace manifest parser + resolver
-      mapper.ts        # Plugin → .rulesync/ canonical layout
-      rulesync.ts      # Thin wrapper around rulesync.generate()
-      cli.ts           # Commander program setup
-      index.ts         # Entry point
-    tests/             # bun:test suites
-packages/              # Shared workspace packages (Bun workspaces)
-tooling/
-  typescript/          # Shared tsconfig presets
-docs/                  # Authoritative project documentation (00–05, 99)
-vendors/               # Reference-only vendored source (do not modify)
-```
+| Entity | Count | Purpose |
+|--------|-------|---------|
+| **skills** | 6 | `anti-hallucination`, `cc-agents`, `cc-commands`, `cc-hooks`, `cc-magents`, `cc-skills` — domain knowledge for each entity type |
+| **commands** | 16 | 4 operations × 4 entity types — thin slash-command wrappers that delegate to skills |
+| **agents** | 5 | `expert-agent`, `expert-command`, `expert-hook`, `expert-magent`, `expert-skill` — specialist subagents that route to skills |
+| **hooks** | 1 | `Stop` hook running the anti-hallucination guard |
+| **scripts** | 3 | `ah_guard.ts`, `validate_response.ts`, `logger.ts` — deterministic enforcement for the anti-hallucination protocol |
+
+The plugin follows a three-tier delegation pattern: **Commands/Agents → Skills → `superskill` CLI**. See [`plugins/cc/README.md`](plugins/cc/README.md) for the full entity design and relationship diagram.
 
 ## Development
 
@@ -196,10 +169,21 @@ vendors/               # Reference-only vendored source (do not modify)
 | Lint + format | Biome 2.4.16 |
 | Test runner | `bun:test` |
 | Format conversion | rulesync (npm) |
+| Quality store | SQLite via `@gobing-ai/ts-db` |
+| Constraint rules | Spur (`spur rule run`) |
 | Git hooks | Lefthook |
 | Conventional commits | cocogitto (`cog`) |
 | Tool versions | proto (`.prototools`) |
 
+### Workspace layout
+
+```
+apps/cli/          # Commander-based CLI entry (the binary); imports @gobing-ai/superskill-core
+packages/core/     # reusable domain logic and no-app operation APIs
+tooling/typescript/ # shared tsconfig presets
+plugins/cc/        # bundled Claude Code plugin
+```
+
 ### Commands
 
 ```bash
@@ -210,6 +194,7 @@ bun run test       # bun test with coverage
 bun run build      # compile to standalone binary
 bun run dev        # watch mode
 bun run check      # lint + test (CI gate)
+bun run spur-check # lint + pre-check rules + test + post-check rules
 ```
 
 ### Verification gate
@@ -220,16 +205,11 @@ All must pass before a change is considered done:
 2. `bun run test` — all tests pass, no `.skip` or commented-out tests. Coverage ≥ 90% lines + functions.
 3. `bun run build` — standalone binary compiles.
 4. `git status` — only intentional changes.
+5. `bun run spur-check` — pre-check rules (22) + post-check rules (coverage-gate + tsdoc-export) all green.
 
 ### Code style
 
-Enforced by [biome.json](biome.json):
-
-- 4-space indent, 120-char line width
-- Single quotes, semicolons always, trailing commas everywhere
-- `interface` for object shapes, `type` for unions/intersections
-- `any` is an error — narrow the type or justify with `// biome-ignore`
-- Workspace imports use `@<scope>/*` aliases, never deep relative paths
+Enforced by [biome.json](biome.json): 4-space indent, 120-char width, single quotes, semicolons, trailing commas. `interface` for object shapes, `type` for unions. `any` is an error. Workspace imports use `@<scope>/*` aliases.
 
 ### Commits
 
@@ -237,6 +217,10 @@ Enforced by [biome.json](biome.json):
 
 ## Documentation
 
+**Help docs** (usage + implementation diagrams): [`docs/help/`](docs/help/index.md)
+
+**Authoritative project docs:**
+
 | Doc | Covers |
 |-----|--------|
 | [00_ADR](docs/00_ADR.md) | Architecture decisions (authoritative) |
@@ -250,4 +234,3 @@ Enforced by [biome.json](biome.json):
 ## License
 
 [Apache 2.0](LICENSE)
-