@rayul/kordis 0.11.1 → 0.12.1

package/assets/kordis-using/SKILL.md

@@ -1,28 +1,30 @@
 ---
 name: kordis-using
-description: Use whenever the user wants to consult or install a Kordis package — including any `<username>/<slug>` reference, "install this skill", "use the X skill", "fetch the Y rule", "set this repo up with…", "pin to version", "specific version", "버전 고정", "전이 의존성", "transitive dependency", "yanked", "version withdrawn", "철회", "unrecommended version". Covers JIT read vs pull, the five Kordis package types, dependencies, version pinning, range syntax, yank semantics, and attribution. Load eagerly when in doubt.
+description: Use whenever the user wants to consult or install a Kordis package — including any `<username>/<slug>` reference, "install this skill", "use the X skill", "fetch the Y rule", "adapt this judgment", "apply a decision pattern", "set this repo up with…", "pin to version", "specific version", "버전 고정", "전이 의존성", "transitive dependency", "yanked", "version withdrawn", "철회", "unrecommended version". Covers JIT read vs pull, `kordis adapt`, the six Kordis package types (incl. judgment-pattern), trust tier, dependencies, version pinning, range syntax, yank semantics, and attribution. Load eagerly when in doubt.
 type: skill
-allowed-tools: ["Bash(kordis:*)"]
+allowed-tools: ['Bash(kordis:*)']
 ---
 
 # Kordis: Reading & Installing
 
 ## Goal
+
 Pick the right mode (`read` vs `pull`), respect type-specific restrictions,
 surface dependencies, and credit the author.
 
 ## read vs pull
 
-| Mode  | Use when                                   | Effect                                   |
-| ----- | ------------------------------------------ | ---------------------------------------- |
-| read  | One-shot consultation, you'll use it once. | Body returned to context. No disk write. |
-| pull  | Long-term: user said "install" / "set up". | Files written into the current project.  |
+| Mode | Use when                                   | Effect                                   |
+| ---- | ------------------------------------------ | ---------------------------------------- |
+| read | One-shot consultation, you'll use it once. | Body returned to context. No disk write. |
+| pull | Long-term: user said "install" / "set up". | Files written into the current project.  |
 
 DEFAULT to `read` when you spontaneously want to consult a skill. DEFAULT to
 `pull` when the user explicitly asks to adopt a package.
 
 `read` restrictions:
-- Eligible: `skill`, `project-rules`, `custom-agent`.
+
+- Eligible: `skill`, `project-rules`, `custom-agent`, `judgment-pattern`.
 - INELIGIBLE: `mcp-server`, `hook` → must `pull`. CLI exits 33 (`jit_blocked`).
 - Trust gate: only `review_status=passed` returned by default. To get a
   `pending_review` body, pass `--allow-pending` AFTER warning the user the
@@ -38,19 +40,37 @@ immediately (e.g. to verify a package you just pushed), use `pull` with
 
 ## Commands
 
-### `kordis read <full_slug>[@<version>] [--allow-pending] [--pin <semver>] [--json]`
+### `kordis read <full_slug>[@<version>] [--allow-pending] [--pin <semver>] [--outline | --section <name>] [--json]`
+
 Returns the full body (Markdown) of a text-bearing package, plus an
 `attribution` string. `--pin <semver>` overrides any `@suffix` on the slug.
+**Context economy**: `--outline` returns just the section map (heading names);
+then `--section <name>` returns one section's body. Read the outline first
+when a body is large and you only need part of it.
+
+### `kordis adapt <full_slug>[@<version>] [--json]`
+
+For `judgment-pattern` packages. **Run it from the user's PROJECT ROOT** — it
+reads the harness in the CURRENT working directory, so `cd` there first (don't
+run it from an unrelated repo, or you'll adapt against the wrong harness).
+Reads the judgment AND this project's local harness (root `CLAUDE.md` /
+`AGENTS.md` / `GEMINI.md` / `.cursorrules`, `~/.claude/CLAUDE.md`,
+`.claude/CLAUDE.md` — read LOCALLY, never uploaded) and
+prints a transplant brief: which parts apply verbatim, which need refitting to
+your context, conflicts to reconcile, and a plain-language rationale. The brief
+is a PROPOSAL — present the changes to the user and apply only what they
+approve. NEVER auto-inject. Credit the source (`following <slug>@<version>`).
 
 ### `kordis pull <full_slug>[@<version|range>] [options]`
+
 Writes files into the current project.
 
-| flag                       | meaning                                                       |
-| -------------------------- | ------------------------------------------------------------- |
-| `--tool <name>`            | force a target tool format (default: auto-detect)             |
-| `--target <path>`          | install into a sub-directory (default: cwd)                   |
-| `--with-recommends`        | also install depth-0 recommended dependencies (0.9.0+)        |
-| `--no-with-required`       | skip transitive required deps (advanced; default installs)    |
+| flag                 | meaning                                                    |
+| -------------------- | ---------------------------------------------------------- |
+| `--tool <name>`      | force a target tool format (default: auto-detect)          |
+| `--target <path>`    | install into a sub-directory (default: cwd)                |
+| `--with-recommends`  | also install depth-0 recommended dependencies (0.9.0+)     |
+| `--no-with-required` | skip transitive required deps (advanced; default installs) |
 
 IMPORTANT: `pull` **fails fast** when the target tool can't be inferred from
 the cwd (no `.claude/`, `.codex/`, `.cursor/`, `AGENTS.md`, `CLAUDE.md`,
@@ -62,6 +82,7 @@ Valid `--tool` values: `claude-code`, `codex`, `cursor`, `continue`,
 `windsurf`, `antigravity`, `copilot`.
 
 ### `kordis info <full_slug> --json`
+
 Inspect metadata (description, tier, deps, license, review status, …) before
 reading or pulling. ALWAYS run this for `mcp-server` / `hook` types, where the
 user is about to execute foreign code or runtime config.
@@ -69,31 +90,59 @@ user is about to execute foreign code or runtime config.
 ## Behaviour per package type
 
 ### `skill`
+
 LLM-facing recipe (Markdown body following the open Agent Skills spec).
+
 - DEFAULT: `read`.
 - `pull` writes to the auto-detected tool's skill path
   (e.g. `~/.claude/skills/<slug>/SKILL.md` for Claude Code).
 
 ### `project-rules`
+
 Repo-scoped agent instructions (Cursor `.cursorrules`, Claude Code project
 `CLAUDE.md` snippets, etc.). Only meaningful inside a project.
+
 - DEFAULT: `pull`. `read` allowed for inspection.
 - Pull writes inside the **current repo**, never `$HOME`.
 
 ### `custom-agent`
+
 Sub-agent definitions (e.g. Claude Code `.claude/agents/`).
+
 - `read` allowed (preview the agent's system prompt).
 - `pull` to make the agent invokable; tell the user how to call it after.
 
+### `judgment-pattern`
+
+A unit of agentic _judgment_ — decision logic, when-to-apply / when-NOT-to-apply,
+failure modes — meant to be READ and adapted, never installed as a file.
+
+- DEFAULT: `kordis adapt` (fits it to THIS harness) or `read` (raw). `pull`
+  writes a Markdown copy, but the value is in reading + adapting, not the file.
+- A judgment's substance is in structured fields, which ARE its sections. To
+  pull just one (instead of the whole body), name the field:
+  `kordis read <slug> --section when_not_to_apply` (or `decision_logic`,
+  `failure_modes`, …). `kordis read <slug> --outline` lists the field names.
+- `trust_tier` (in `read --json` / `info --json`), strongest to weakest:
+  `re-verified` (Kordis-vetted), then `community-adapted` (distinct other
+  authors adapted it), then `author-reported` (the author's own `evidence`
+  claim — UNVERIFIED), then `unsubstantiated`. Weight the judgment accordingly;
+  for any load-bearing decision, tell the user the tier and never present
+  `author-reported` as proven.
+
 ### `mcp-server`
+
 Model Context Protocol server packages.
+
 - `read` is INELIGIBLE → CLI returns `jit_blocked`. ALWAYS `pull`.
 - After pull, instruct the user to restart the agent and supply any required
   env vars.
 
 ### `hook`
+
 Event-driven scripts (pre-commit, pre-tool-call, etc.) that run on the user's
 machine.
+
 - `read` is INELIGIBLE → ALWAYS `pull`.
 - IMPORTANT: hooks execute arbitrary code. EXPLAIN in plain words what the
   hook does, and confirm with the user BEFORE pulling.
@@ -104,15 +153,15 @@ Append `@<version|range>` to a slug on `kordis pull`, `kordis read`,
 `kordis info` (and check what's available with `kordis versions`).
 Supported forms:
 
-| input                              | meaning                                                          |
-| ---------------------------------- | ---------------------------------------------------------------- |
-| `user/foo` (no @)                  | latest `current_version` (server's bumped default)               |
-| `user/foo@1.2.3`                   | exact version                                                    |
-| `user/foo@1.0.0-beta.1`            | exact prerelease (only matches if the literal exists)            |
-| `user/foo@^1.2`                    | caret — highest 1.x.y (x≥2). For 0.x.y, caret pins the minor   |
-| `user/foo@~1.2`                    | tilde — highest 1.2.y                                            |
-| `user/foo@0.1.x`                   | x-range — alias for `~0.1` (0.9.3+; semver-native)               |
-| `user/foo@*`                       | alias for `current_version`                                      |
+| input                   | meaning                                                      |
+| ----------------------- | ------------------------------------------------------------ |
+| `user/foo` (no @)       | latest `current_version` (server's bumped default)           |
+| `user/foo@1.2.3`        | exact version                                                |
+| `user/foo@1.0.0-beta.1` | exact prerelease (only matches if the literal exists)        |
+| `user/foo@^1.2`         | caret — highest 1.x.y (x≥2). For 0.x.y, caret pins the minor |
+| `user/foo@~1.2`         | tilde — highest 1.2.y                                        |
+| `user/foo@0.1.x`        | x-range — alias for `~0.1` (0.9.3+; semver-native)           |
+| `user/foo@*`            | alias for `current_version`                                  |
 
 Comparator strings (`>=1 <2`, `||`) are NOT supported in 0.9.x —
 server returns `usage_error` with the accepted-forms list. Deferred to
@@ -149,10 +198,10 @@ installs.
 
 Three install behaviours:
 
-| Input                              | Behaviour                                                        |
-| ---------------------------------- | ---------------------------------------------------------------- |
-| `kordis pull <slug>`               | Always picks the highest **non-yanked** version. Yanked versions are silently skipped — user sees the next-best release. |
-| `kordis pull <slug>@^X.Y`          | Range resolution skips yanked. If every match is yanked, server returns `not_found` with hint "every version satisfying X has been yanked". |
+| Input                                                     | Behaviour                                                                                                                                                                                      |
+| --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kordis pull <slug>`                                      | Always picks the highest **non-yanked** version. Yanked versions are silently skipped — user sees the next-best release.                                                                       |
+| `kordis pull <slug>@^X.Y`                                 | Range resolution skips yanked. If every match is yanked, server returns `not_found` with hint "every version satisfying X has been yanked".                                                    |
 | `kordis pull <slug>@<exact>` (pinned to a yanked version) | Succeeds (exit 0) with a stderr warning: `⚠ pulled yanked version X of slug (reason: …) — author marked this as unrecommended on YYYY-MM-DD`. Stays installable so old lockfiles keep working. |
 
 `kordis info <slug>` shows a red `⚠ Yanked YYYY-MM-DD` banner with the
@@ -165,17 +214,20 @@ parent. Surface that chain to the user — fixing usually means pinning
 A's requirement to a non-yanked range, or contacting B's author.
 
 ## Dependencies
+
 `kordis pull` reports `depends` and `recommends` from the package metadata.
 Surface the dependency tree to the user FIRST. If they accept,
 `--with-recommends` also pulls the recommended set in one go. Never
 auto-resolve silently.
 
 ## Attribution
+
 `kordis read` returns an `attribution` string (e.g.
 `"following <full_slug>@<version>"`). RECOMMENDED: end your reply with that
 exact line. Skip only when it would clutter a casual non-technical reply.
 
 ## Bundled assets
+
 Skills published as a `.skill` bundle or directory include `assets/`,
 `references/`, `scripts/`, and `agents/` subdirectories alongside
 `SKILL.md`. After `kordis pull`, these files land next to `SKILL.md` in
@@ -215,6 +267,14 @@ User: "use the v0.2.0 of <full_slug> specifically"
   (or:  kordis read <full_slug>@0.2.0 --json)
 </example>
 
+<example>
+User: "how should the agent decide when to ask before acting? pull that judgment from Kordis"
+- (delegate search to kordis-search → picks a judgment-pattern <full_slug>)
+- kordis adapt <full_slug> --json   # judgment + THIS repo's harness → transplant brief
+- note the trust_tier; present the proposed fit, apply only what the user approves
+- end reply with "following <full_slug>@<version>"
+</example>
+
 <example>
 User: "add a pre-commit hook that blocks committing API keys"
 - kordis info <full_slug> --json
@@ -245,13 +305,13 @@ kordis setup --personalization off
 
 **What error telemetry carries** (sent to `POST /api/telemetry/error`):
 
-| field | value |
-|---|---|
-| `kind` | one of `auto_finalize_stage1_fail`, `auto_finalize_stage2_fail`, `network_unreachable`, `unhandled_error` |
-| `cli_version`, `node_version`, `platform` | version + OS strings |
-| `message_excerpt` | first 200 chars of `err.message` after sanitization (homedir → `~`; paths / JWTs / UUIDs / long hex runs stripped) |
-| `error_code`, `elapsed_ms` | optional |
-| `timestamp` | ISO 8601 |
+| field                                     | value                                                                                                              |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `kind`                                    | one of `auto_finalize_stage1_fail`, `auto_finalize_stage2_fail`, `network_unreachable`, `unhandled_error`          |
+| `cli_version`, `node_version`, `platform` | version + OS strings                                                                                               |
+| `message_excerpt`                         | first 200 chars of `err.message` after sanitization (homedir → `~`; paths / JWTs / UUIDs / long hex runs stripped) |
+| `error_code`, `elapsed_ms`                | optional                                                                                                           |
+| `timestamp`                               | ISO 8601                                                                                                           |
 
 **Never carries**: `argv`, env-var values, file paths (after sanitization), identity (`user_id` / `username` / `session_id` / refresh tokens), `X-Kordis-Context` content, full stack traces. The server's POST route ignores `Authorization` headers entirely.