@skill-map/spec 0.1.0

package/schemas/summaries/agent.schema.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/summaries/agent.schema.json",
+  "title": "SummaryAgent",
+  "description": "Report produced by `agent-summarizer` for a single `agent` node. Extends `report-base.schema.json`. Stability: experimental.",
+  "allOf": [
+    { "$ref": "../report-base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["whatItDoes"],
+  "additionalProperties": false,
+  "properties": {
+    "confidence": true,
+    "safety": true,
+    "whatItDoes": {
+      "type": "string",
+      "description": "One-sentence summary of the agent's role. REQUIRED."
+    },
+    "whenToUse": {
+      "type": "string",
+      "description": "Situations or triggers where this agent should be selected over alternatives."
+    },
+    "capabilities": {
+      "type": "array",
+      "description": "Distinct things the agent can do, as inferred from the body and declared tools.",
+      "items": { "type": "string" }
+    },
+    "toolsObserved": {
+      "type": "array",
+      "description": "Tool names the summarizer observed referenced in the body. MAY differ from `metadata.tools` / frontmatter.tools; rules can emit drift issues.",
+      "items": { "type": "string" }
+    },
+    "interactionStyle": {
+      "type": "string",
+      "description": "Free-form: autonomous vs interactive, synchronous vs queued, reporting style."
+    },
+    "relatedNodes": {
+      "type": "array",
+      "description": "`node.path` values inferred as related.",
+      "items": { "type": "string" }
+    },
+    "qualityNotes": {
+      "type": "string"
+    }
+  }
+}

package/schemas/summaries/command.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/summaries/command.schema.json",
+  "title": "SummaryCommand",
+  "description": "Report produced by `command-summarizer` for a single `command` node. Extends `report-base.schema.json`. Stability: experimental.",
+  "allOf": [
+    { "$ref": "../report-base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["whatItDoes"],
+  "additionalProperties": false,
+  "properties": {
+    "confidence": true,
+    "safety": true,
+    "whatItDoes": {
+      "type": "string",
+      "description": "One-sentence summary of the command's effect. REQUIRED."
+    },
+    "invocationExample": {
+      "type": "string",
+      "description": "Canonical example invocation, including arguments. Opaque platform-formatted string."
+    },
+    "argsObserved": {
+      "type": "array",
+      "description": "Argument structure as inferred from the body. MAY differ from declared `frontmatter.args`; rules can emit drift issues.",
+      "items": {
+        "type": "object",
+        "required": ["name"],
+        "additionalProperties": false,
+        "properties": {
+          "name": { "type": "string" },
+          "type": { "type": "string" },
+          "description": { "type": "string" },
+          "required": { "type": "boolean" }
+        }
+      }
+    },
+    "sideEffects": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "relatedNodes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "qualityNotes": {
+      "type": "string"
+    }
+  }
+}

package/schemas/summaries/hook.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/summaries/hook.schema.json",
+  "title": "SummaryHook",
+  "description": "Report produced by `hook-summarizer` for a single `hook` node. Extends `report-base.schema.json`. Stability: experimental.",
+  "allOf": [
+    { "$ref": "../report-base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["whatItDoes"],
+  "additionalProperties": false,
+  "properties": {
+    "confidence": true,
+    "safety": true,
+    "whatItDoes": {
+      "type": "string",
+      "description": "One-sentence summary of what the hook does when triggered. REQUIRED."
+    },
+    "triggerInferred": {
+      "type": "string",
+      "description": "Event or condition the summarizer inferred from the body. MAY differ from declared `frontmatter.event`/`condition`; rules can emit drift issues."
+    },
+    "sideEffects": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "blockingInferred": {
+      "type": "boolean",
+      "description": "Whether execution appears to block host flow. Compare against declared `frontmatter.blocking`."
+    },
+    "idempotentInferred": {
+      "type": "boolean",
+      "description": "Whether the hook appears safe to run multiple times. Compare against declared `frontmatter.idempotent`."
+    },
+    "relatedNodes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "qualityNotes": {
+      "type": "string"
+    }
+  }
+}

package/schemas/summaries/note.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/summaries/note.schema.json",
+  "title": "SummaryNote",
+  "description": "Report produced by `note-summarizer` for a single `note` node. Extends `report-base.schema.json`. Stability: experimental.",
+  "allOf": [
+    { "$ref": "../report-base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["whatItCovers"],
+  "additionalProperties": false,
+  "properties": {
+    "confidence": true,
+    "safety": true,
+    "whatItCovers": {
+      "type": "string",
+      "description": "One-sentence summary of the note's subject matter. REQUIRED. Named distinctly from `whatItDoes` since notes describe, not act."
+    },
+    "topics": {
+      "type": "array",
+      "description": "Topical tags inferred from the body. Feed into tag-based discovery and `related` link inference.",
+      "items": { "type": "string" }
+    },
+    "keyFacts": {
+      "type": "array",
+      "description": "Discrete claims or data points the note asserts. Useful for search and diffing over time.",
+      "items": { "type": "string" }
+    },
+    "relatedNodes": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "qualityNotes": {
+      "type": "string"
+    }
+  }
+}

package/schemas/summaries/skill.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/summaries/skill.schema.json",
+  "title": "SummarySkill",
+  "description": "Report produced by `skill-summarizer` for a single `skill` node. Extends `report-base.schema.json`. Stability: experimental — field set may tighten as real summarizer output stabilizes.",
+  "allOf": [
+    { "$ref": "../report-base.schema.json" }
+  ],
+  "type": "object",
+  "required": ["whatItDoes"],
+  "additionalProperties": false,
+  "properties": {
+    "confidence": true,
+    "safety": true,
+    "whatItDoes": {
+      "type": "string",
+      "description": "One-sentence summary of what the skill accomplishes. REQUIRED."
+    },
+    "recipe": {
+      "type": "array",
+      "description": "Ordered steps inferred from the skill body. Optional; empty array when the skill is declarative rather than procedural.",
+      "items": {
+        "type": "object",
+        "required": ["step", "description"],
+        "additionalProperties": false,
+        "properties": {
+          "step": { "type": "integer", "minimum": 1 },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "preconditions": {
+      "type": "array",
+      "description": "Conditions that must be true before the skill can run productively.",
+      "items": { "type": "string" }
+    },
+    "outputs": {
+      "type": "array",
+      "description": "Artifacts or observable effects the skill produces when it completes successfully.",
+      "items": { "type": "string" }
+    },
+    "sideEffects": {
+      "type": "array",
+      "description": "State changes outside the immediate output: files touched, processes spawned, network calls.",
+      "items": { "type": "string" }
+    },
+    "relatedNodes": {
+      "type": "array",
+      "description": "`node.path` values the summarizer inferred as related. Feeds `related` links at medium confidence.",
+      "items": { "type": "string" }
+    },
+    "qualityNotes": {
+      "type": "string",
+      "description": "Free-form notes: ambiguity in the source, potentially misleading wording, outdated references."
+    }
+  }
+}

package/versioning.md

@@ -0,0 +1,94 @@
+# Spec versioning
+
+The skill-map **spec** and the skill-map **reference CLI** evolve on independent semver tracks. A spec version and a CLI version are related through a `specCompat` range declared by each implementation and each plugin.
+
+## Two tracks
+
+| Track | Example tag | Semver meaning |
+|---|---|---|
+| Spec | `spec-v1.2.0` | Schemas + contracts in `spec/`. Consumed by any implementation. |
+| Reference CLI | `cli-v0.8.3` | The `sm` binary and its built-in extensions in `src/`. |
+
+A given CLI release declares the spec range it implements (e.g. `"specCompat": "^1.0.0"`). A plugin declares the spec range it targets. At load time the implementation runs `semver.satisfies(specVersion, plugin.specCompat)`; mismatch → plugin disabled with reason `incompatible-spec`.
+
+## Semver for the spec
+
+Patch, minor, major have precise meaning for a specification — different from code.
+
+| Bump | Allowed changes | Examples |
+|---|---|---|
+| **Patch** (`1.0.0 → 1.0.1`) | Editorial only. No normative change. | Typo fixes, clarified wording, examples added, non-binding notes. |
+| **Minor** (`1.0.0 → 1.1.0`) | Backward-compatible additions. Existing conforming implementations remain conforming. | New optional field, new optional schema, new optional CLI flag, new extension kind capability that is opt-in, new conformance case that tests a new optional feature. |
+| **Major** (`1.0.0 → 2.0.0`) | Any change that can break a conforming implementation. | Remove a field, rename a field, change a field's type, tighten an enum, make an optional field required, change an exit code's meaning, change an event's payload shape, change a verb's default behavior. |
+
+Rule of thumb: if a strict v1 implementation could fail a v1.X conformance run, the change is major.
+
+## What counts as normative
+
+All of the following are normative and governed by this policy:
+
+- Every JSON Schema in `schemas/` (fields, types, required, enums, defaults, `additionalProperties`).
+- Every MUST / SHOULD / MAY statement in prose documents (`architecture.md`, `cli-contract.md`, `job-events.md`, `prompt-preamble.md`, `db-schema.md`, `plugin-kv-api.md`, `dispatch-lifecycle.md`).
+- Exit codes, verb names, required flags, canonical error messages marked "normative".
+- Conformance fixtures and cases — removing or tightening a case is major.
+
+The following are **non-normative** and can change at any time without a version bump:
+
+- Editorial prose, examples, diagrams.
+- README layout, cross-link structure.
+- Filenames inside `../src/` (reference impl) — never referenced from spec normatively.
+- Internal commentary inside `../ROADMAP.md` and `../CLAUDE.md`.
+
+## Stability tags
+
+Fields and features inside the spec carry a stability tag. Tag drives what the version policy allows.
+
+| Tag | Meaning | Policy |
+|---|---|---|
+| `experimental` | Under design. May change without warning. | Minor and major bumps can change or remove. Plugins using an experimental field must tolerate breakage. |
+| `stable` | Default. Governed by the semver rules above. | Changes follow the table at the top of this doc. |
+| `deprecated` | Being removed in a future major. | Stays functional until the next major. `deprecated` notice must include the target removal version and a migration hint. |
+
+Tags live inline in schema `description` fields and in prose via a leading `**Stability: experimental**` line.
+
+## Deprecation window
+
+- `stable` → `deprecated` requires a minor bump.
+- `deprecated` → removed requires a major bump.
+- Between the two, at least three minor releases must ship with the field marked `deprecated`. This gives plugin authors a release window to migrate.
+- Rationale for the deprecation and the replacement field/flag must live in `CHANGELOG.md`.
+
+## Pre-1.0
+
+While the spec is `0.Y.Z`:
+
+- Minor bumps may contain breaking changes (documented as such in `CHANGELOG.md`).
+- Conformance is advisory — failing a conformance case is a bug report, not a spec violation.
+- `specCompat` in plugins should pin a minor range (`"^0.3.0"` means `>=0.3.0 <0.4.0`), not a major range.
+
+The first stable commitment is `spec-v1.0.0`. That tag ships with CUT 3 / `cli-v1.0.0`.
+
+## Independence in practice
+
+- **Spec `1.0.0` + CLI `0.1.0`** — spec is stabilized before the CLI ships its v1. Normal case during early life of the project.
+- **Spec `1.2.0` + CLI `0.8.0`** — spec gained an optional feature; CLI hasn't implemented it yet. Fine. Plugins needing that feature must declare `"specCompat": "^1.2.0"`.
+- **Spec `2.0.0` + CLI `1.4.0`** — CLI still targets spec v1. Operator must upgrade CLI before installing v2-targeting plugins.
+
+## Change process
+
+1. PR proposes a spec change. Include rationale and classification (patch/minor/major).
+2. If major, PR includes a migration note draft for `CHANGELOG.md`.
+3. If the change affects reference-impl behavior, a companion PR in `src/` lands the implementation behind the bumped `specCompat`.
+4. Merge order: spec change first, implementation second. An implementation MUST NOT ship a feature that is not yet in the spec (see `CLAUDE.md`: "Every feature: update spec/ first, then src/").
+5. Tag spec release (`spec-vX.Y.Z`) independent from any CLI tag.
+
+## Canonical URLs
+
+Once the domain is live, schemas resolve at stable URLs:
+
+```
+https://skill-map.dev/spec/v1/node.schema.json
+https://skill-map.dev/spec/v1.2/node.schema.json
+```
+
+Major version is always present in the path. Implementations MUST NOT rely on `latest`.