@skaile/workspaces 0.24.0 → 0.26.0

package/dist/factory-assets/skills/authoring-skaile-manifests/references/dependency-standard.md

@@ -0,0 +1,197 @@
+# The skaile dependency standard (canonical-identity)
+
+Deep reference for the dependency grammar used by `@skaile/workspaces`. The
+authoritative source is `docs/concepts/manifest-schema.md` and the spec
+`_devlog/specs/2026-05-31-manifest-canonical-identity.md` (scoped-grammar follow-up:
+`_devlog/specs/2026-06-02-scoped-asset-ref-grammar.md`). This file restates it for
+asset authors and flags where the current code is **stricter than the older docs**.
+
+## 1. Identity
+
+Every asset has a global identity tuple:
+
+```
+(publisher, kind, name, version)
+```
+
+- **Asset-intrinsic.** Declared in the *source's* `skaile.yaml`, never by the
+  consuming project. There is no project-local renaming.
+- **publisher** — canonical, GitHub-shaped: 1–39 chars, alphanumeric + single
+  hyphens, no leading/trailing hyphen, no double hyphen. Auto-derived from a
+  GitHub source URL's org/user; **must be declared** for any non-GitHub URL.
+- **kind** — one of: `skill`, `agent`, `prompt`, `bundle`, `flow`, `contract`,
+  `mcp-server`, `persona`, `ruleset`, `knowledge`, `connector`.
+- **version** — SemVer (see § Version waterfall). Two assets with the same tuple
+  MUST be byte-identical.
+
+## 2. The canonical reference grammar
+
+```
+kind:@<publisher>/name[#version]
+```
+
+| Token | Role |
+|---|---|
+| `kind:` | asset kind + colon. `mcp:` is shorthand for `mcp-server:`. |
+| `@` | **scope sigil** — introduces the publisher, npm-style. |
+| `<publisher>/` | publisher namespace + slash. |
+| `name` | asset name. Permissive: anything except `/`, `#`, whitespace. |
+| `#version` | optional **version sigil** + pin. |
+
+Reads as an npm scoped package: `@skaile-ai/audit`.
+
+### Examples
+
+```
+skill:@skaile-ai/audit
+skill:@skaile-ai/audit#^1.4.0
+bundle:@skaile-ai/skaile-development#~2.0
+agent:@vercel-labs/reviewer
+mcp:@skaile-ai/excel                  # == mcp-server:@skaile-ai/excel
+contract:@skaile-ai/implementation-contract#1.0.0
+skill:@skaile-ai/audit#6a5266fdda9d1c697f537968532691f6d70c779a   # 40-char SHA pin
+```
+
+## 3. Pins
+
+| Pin form | Meaning |
+|---|---|
+| `#1.4.0` | exact SemVer |
+| `#^1.4.0`, `#^1` | caret range |
+| `#~1.4.0`, `#~1.4` | tilde range |
+| `#1.x`, `#1.4.x` | wildcard |
+| `#<40-char-sha>` | exact source-commit pin |
+| absent | resolver picks the highest SemVer-sorted candidate |
+| `#main`, `#latest`, `#HEAD`, any floating ref | **parse-time error** |
+
+Floating refs are rejected by design — resolution must be reproducible.
+
+## 4. SHA-synthetic versions
+
+When no version can be derived (no `assets[].version`, no source `version:`, no
+SemVer git tag), the resolver mints `0.0.0-sha.<7char>` from the commit. These:
+
+- participate in resolution,
+- satisfy **only** their exact literal pin (`#0.0.0-sha.abc1234`) or the
+  commit-SHA pin that produced them,
+- never match caret/tilde/wildcard ranges.
+
+Consequence: an untagged source resolves only when pinned exactly. **Tag
+releases** to enable ranged (`^`, `~`, `x`) installs.
+
+## 5. `requires:` vs `dependencies:` — the split that trips authors
+
+There are two distinct dependency channels. They use **different grammars**.
+
+### `requires:` — content frontmatter, intra-source, bare `kind:name`
+
+In a `SKILL.md` / `agent.yaml` / `MCP.md`, `requires:` lists peer assets the
+asset needs. Form is **`kind:name`** — no `@publisher`, no `#version`. The
+publisher is **inherited from the same source** (same-source assumption).
+
+```yaml
+# SKILL.md frontmatter
+metadata:
+  requires:
+    - contract:implementation-contract
+    - skill:use-exa
+```
+
+Accepted as a comma-separated string or a YAML list. Read from either the
+top level or under `metadata:`.
+
+### `dependencies:` — bundle & project manifests, full canonical refs
+
+A **bundle** (`*.bundle.yaml`) and a **project** `skaile.yaml` use
+`dependencies:` with the **full canonical grammar** and can cross publishers and
+pin versions:
+
+```yaml
+# a bundle, or a project skaile.yaml
+dependencies:
+  - skill:@skaile-ai/audit#^1.4
+  - agent:@skaile-ai/impl-build-implement
+  - skill:@vercel-labs/agent-skills
+```
+
+> Putting a full canonical ref in a content `requires:` (or a bare `kind:name`
+> in a project `dependencies:`) is the most common authoring mistake. Keep them
+> in their lanes: **`requires:` = bare same-source; `dependencies:` = canonical
+> cross-source.**
+
+### Transitive expansion
+
+Installing a bundle resolves every `dependencies:` ref, recursing into nested
+bundles to arbitrary depth. A shared dep is de-duped; cycles are broken by a
+`seen` set. A bare transitive ref inherits its parent candidate's publisher.
+
+## 6. Resolution algorithm (per dep)
+
+1. Gather **source candidates** from every cloned `sources[]` repo (provenance
+   index, keyed `<publisher>/<kind>:<name>`).
+2. Optionally gather **store candidates** from every `stores[]` catalog.
+3. Filter by the pin (SemVer range / SHA / exact).
+4. Pick the **highest** matching version.
+5. **Conflict check:** if ≥2 finalists at that version have divergent content
+   `sha256`, raise `CanonicalRefConflictError` with the dep chain — unless an
+   `overrides[]` entry selects one source.
+6. Cross-check: when a source and a store both produced the chosen version,
+   probe `catalog.getCanonicalDigest` and compare `sha256`.
+
+### Conflict error shape
+
+```
+error: divergent sha256 for skill:@skaile-ai/audit#1.4.0
+  pulled in via:
+    bundle:@skaile-ai/skaile-development#^2.0
+      skill:@skaile-ai/audit#~1.4
+  candidates:
+    https://github.com/skaile-ai/ai-assets @ 6a5266fd   sha256: 1da6294a...
+    https://github.com/mortegro/ai-assets-fork @ ab12cd34  sha256: 9e3f7c01...
+resolve by:
+  1. removing one source from skaile.yaml,
+  2. configuring a store and using its canonical digest, or
+  3. adding to overrides: (with a non-empty reason:)
+```
+
+## 7. Overrides
+
+```yaml
+overrides:
+  - ref: skill:@skaile-ai/audit#1.4.0      # the canonical, fully-pinned ref
+    source: https://github.com/skaile-ai/ai-assets   # which candidate wins
+    reason: "vendored patch for #42; revert when upstream merges"   # REQUIRED, non-empty
+```
+
+`reason:` is mandatory — empty/missing is a parse error. Use overrides only to
+break a genuine sha conflict; the right long-term fix is to stop publishing
+divergent bytes under the same coordinates.
+
+## 8. Version waterfall (recap)
+
+1. `assets[].version` in the source `skaile.yaml`
+2. source top-level `version:`
+3. SemVer git tag (`git describe --tags`, `v` stripped)
+4. synthetic `0.0.0-sha.<7char>`
+
+## 9. What changed from legacy (migration cheatsheet)
+
+| Legacy | Canonical (now) |
+|---|---|
+| `skill:audit@skaile-ai` | `skill:@skaile-ai/audit` |
+| `skill:audit@skaile-ai#1.4.0` | `skill:@skaile-ai/audit#1.4.0` |
+| bare `skill:audit` in a project dep | `skill:@<publisher>/audit` (publisher now required) |
+| `@skaile` publisher | `@skaile-ai` (rebrand) |
+| `repositories:` / `ai_resources:` top-level keys | `sources:` / `dependencies:` |
+
+**The legacy `kind:name@<publisher>` grammar no longer parses** — it is a hard
+error (`publisher required in asset ref`). The older `manifest-schema.md` line
+about "still parses for one release with a deprecation warning" is stale; the
+aliases were removed. Run the `migrate-skaile-manifest` skill to convert.
+
+## 10. Lock key
+
+The lock file (`skaile.lock.yaml`, schema v3) keys each entry by the
+fully-pinned canonical ref `kind:@<publisher>/name#version` and records the
+contributing source URL + commit and per-file `sha256`. Regenerate, never
+hand-edit: `rm skaile.lock.yaml && skaile install`.

package/dist/factory-assets/skills/manifest-compliance/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: manifest-compliance
+description: "Use when an AI-asset repo has manifests or skaile.yaml refs that fail canonical-name rules — the symptom is a runtime hard error like `publisher required in asset ref \"flow:@skaile-ai/CLI Concept\"` or `invalid asset name \"…\"` thrown by parseAssetRef at install/apply time. Scans a repo with `skaile validate`, then fixes each non-compliant asset identity (skill/agent `name`, flow `id`) to lowercase kebab-case and rewrites every reference (skaile.yaml dependencies/overrides, flow node skill refs, directory names). Trigger when the user says 'fix asset names', 'my manifest is invalid', 'publisher required error', 'invalid asset name', 'make my assets compliant', or 'migrate legacy manifest names'."
+metadata:
+  version: 1.0.0
+  source: AUTHORED
+  stage: beta
+  tags: [asset-store, manifest, compliance, validation, naming, migration, repo-author]
+  prerequisites:
+    inputs_optional:
+      - id: repo_path
+        label: "Path to the asset repo / library to check"
+        type: text
+        default: "."
+        hint: "Repo root — the tree containing SKILL.md / *.flow.yaml / skaile.yaml files"
+      - id: write
+        label: "Apply fixes vs report only"
+        type: boolean
+        default: false
+        hint: "If false, only report violations; if true, rename + rewrite refs"
+    reads:
+      - path: skills/authoring-skaile-manifests/references/dependency-standard.md
+        description: "Canonical dependency grammar + asset-ref shape"
+keywords: [manifest, compliance, asset-name, kebab-case, parseAssetRef, validate]
+---
+
+# Manifest Compliance
+
+Detect and fix asset manifests that violate the **canonical asset-name rule**,
+then rewrite every reference so the repo installs and applies without the
+`parseAssetRef` hard error.
+
+## The rule
+
+A canonical asset **name** (and a flow's **id**) is **lowercase kebab-case**:
+
+- allowed: `a-z`, `0-9`, single hyphens between segments
+- forbidden: uppercase, spaces, underscores, dots, leading/trailing or double hyphens
+
+A full reference is `kind:@<publisher>/name[#version]` — e.g.
+`flow:@skaile-ai/cli-concept`. A name like `"CLI Concept"` (space + uppercase)
+breaks the grammar; because the publisher is present, older builds reported the
+*misleading* `publisher required …` error — the real fault is the name.
+
+> A flow's `name:` frontmatter is a human-readable **display title** and may
+> contain spaces/uppercase. The asset identity is the flow's `id:` field —
+> that is what must be kebab-case. Fix `id`, leave `name` alone.
+
+## Step 0: Confirm context
+
+1. Resolve `repo_path` (default `.`).
+2. Confirm it's a repo/library tree (has `SKILL.md`, `*.flow.yaml`, or
+   `skaile.yaml` files somewhere under it).
+
+## Step 1: Detect (always run first)
+
+Run the repo-wide compliance check:
+
+```bash
+bun run cli validate <repo_path>
+```
+
+`skaile validate [path]` walks the tree and reports, per file:
+
+- `invalid asset name "…"` / `invalid asset id "…"` — a manifest identity that
+  isn't kebab-case (skill/agent `name`, flow `id`).
+- `[dependencies] / [overrides.ref] — …` — a `skaile.yaml` ref that fails
+  `parseAssetRef` (the exact path that hard-errors at runtime).
+- `[assets] — invalid asset name "…"` — a published `assets[]` entry identity.
+
+Exit code is `1` when any violation is found. Collect the full list before
+fixing — there are usually several, and references are interlinked.
+
+If validate is clean, report "compliant" and stop.
+
+## Step 2: Plan the renames
+
+For each violation, derive the compliant name and present the mapping to the
+user **before** writing:
+
+| Bad identity | Proposed kebab-case |
+|---|---|
+| `CLI Concept` | `cli-concept` |
+| `Test Echo Flow` | `test-echo-flow` |
+| `my_audit` | `my-audit` |
+
+Kebab-case derivation: lowercase, replace runs of non-`[a-z0-9]` with a single
+hyphen, trim leading/trailing hyphens. Flag collisions (two assets mapping to
+the same name) for the user to disambiguate — never auto-merge.
+
+## Step 3: Apply fixes (`write = true`)
+
+For each renamed asset, apply **all** of these so no dangling reference remains:
+
+1. **Manifest identity** — edit the `name:` (or, for flows, `id:`) field in the
+   asset's own manifest (`SKILL.md` frontmatter, `agent.yaml`, `*.flow.yaml`,
+   `MCP.md`, `CONNECTOR.md`, `*.preset.yaml`, etc.).
+2. **Directory name** — if the asset's folder is named after the old identity,
+   rename the directory to match (use `git mv` so history is preserved).
+3. **Inbound references** — grep the whole tree for the old identity and update
+   every occurrence:
+   - `skaile.yaml` → `dependencies:`, `overrides[].ref`, `assets[].name`
+   - flow nodes → `data.skill` / node refs that name the asset
+   - any `kind:@publisher/<old-name>` ref string anywhere
+
+   ```bash
+   grep -rn "<old-name>" <repo_path> --include="*.yaml" --include="*.md" --include="*.json"
+   ```
+
+   Review each hit — only rewrite genuine asset-ref occurrences, not prose.
+
+## Step 4: Verify
+
+Re-run the detector and confirm a clean tree:
+
+```bash
+bun run cli validate <repo_path>
+```
+
+Expect `All manifests valid` and exit `0`. If violations remain, return to
+Step 3 (a missed inbound reference, or a second-order collision).
+
+## Step 5: Suggest commit
+
+Summarize the renames applied (old → new) and the files touched, and suggest a
+commit message, e.g.:
+
+```
+fix(assets): make asset identities canonical kebab-case
+
+- flow "CLI Concept" → cli-concept (+ refs)
+```
+
+## CHECKLIST
+
+- [ ] Ran `skaile validate <repo_path>` and collected every violation
+- [ ] Proposed kebab-case mapping reviewed with the user (collisions flagged)
+- [ ] Fixed flow identity in `id:`, not `name:` (display title left intact)
+- [ ] Updated manifest identity, directory name, AND all inbound references
+- [ ] Re-ran `skaile validate` to a clean (exit 0) tree before committing

package/dist/factory-assets/skills/skaile-author-asset/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: "skaile-author-asset"
+description: "Use when an asset author needs to build a skill in a local library and publish it. Covers the source/library/store model, structuring a repo into domains, the SKILL.md format, and the .skaile-source.yaml manifest (v1 glob vs v2 author-shipped inventory) and publish flow via the skaile CLI."
+metadata:
+  version: "0.1.0"
+  tags:
+    - "authoring"
+    - "skill"
+    - "library"
+    - "publish"
+    - "manifest"
+    - "domain"
+    - "ai-assets"
+    - "asset-manager"
+  stage: "alpha"
+  requires:
+    - "skill:authoring-skaile-assets"
+---
+
+# Author an AI-Asset
+
+How to author a **skill** (or any asset kind) in a local library, structure the
+repository into **domains**, write the `.skaile-source.yaml` **manifest**, and
+**publish** it through the store.
+
+For the canonical skill folder layout and frontmatter spec, read the companion
+**[authoring-skaile-assets]** skill first. This skill adds the
+library/manifest/publish lifecycle on top of it.
+
+## The three nouns
+
+Everything below maps to one of three concepts. Keep them straight:
+
+| Noun        | What it is                                                        | Holds bytes? |
+| ----------- | ----------------------------------------------------------------- | ------------ |
+| **source**  | A GitHub repo of AI-assets (yours, your team's, a third party's). | Yes          |
+| **library** | A registered place *on your machine* where you author/hold assets.| Yes          |
+| **store**   | A remote catalog of **manifests** that point at sources.          | No — pointers only |
+
+The store never hosts asset bytes. It returns a pointer triple — upstream repo
+URL + pinned commit SHA + per-file SHA256 — and the bytes are fetched directly
+from GitHub and hash-verified on install.
+
+## Asset kinds
+
+A skill is one of several discoverable kinds. Each is recognized by a filename
+glob:
+
+| Kind         | Discovery pattern                              |
+| ------------ | ---------------------------------------------- |
+| `skill`      | `**/SKILL.md`                                  |
+| `agent`      | `**/agent.yaml` or `**/AGENT.md`               |
+| `contract`   | `**/CONTRACT.md`                               |
+| `flow`       | `**/*.flow.yaml` / `**/*.flow.json`            |
+| `connector`  | `**/CONNECTOR.md`                              |
+| `prompt`     | `**/*.prompt.md`                               |
+| `preset`     | `**/*.preset.yaml`                             |
+| `mcp-server` | `**/MCP.md`                                    |
+| `knowledge`  | `**/knowledge.yaml` / `**/knowledge/index.yaml`|
+
+## 1. Create a library and scaffold the skill
+
+```bash
+# One-time: register a personal authoring library at ~/.skaile/libraries/personal
+skaile library init personal
+
+# Scaffold a new asset inside the default (or named) library
+skaile library create skill my-skill --library personal
+```
+
+Libraries live at `~/.skaile/libraries/<name>/`; the local index that tracks
+them is `~/.skaile/index.db` (SQLite — never hand-edit it).
+
+## 2. Structure: domains
+
+A **domain** is the **first-level directory** of an asset repo. It groups
+related assets and defines the publisher namespace. Lay out assets by
+`<domain>/<kind-plural>/<name>/`:
+
+```
+my-assets/                       # repo root (a "source")
+├── .skaile-source.yaml          # manifest (see §4)
+├── research/                    # DOMAIN  → publisher @research
+│   ├── DOMAIN.md                # domain description (recommended)
+│   ├── skills/
+│   │   ├── brief/SKILL.md
+│   │   └── summarize/SKILL.md
+│   ├── agents/
+│   │   └── analyst/agent.yaml
+│   └── contracts/
+│       └── brief-format/CONTRACT.md
+└── ops/                         # DOMAIN  → publisher @ops
+    └── skills/...
+```
+
+With `publisher_default: '@<domain>'` in the manifest, every asset under
+`research/` is published as `@research/<name>`. Override per-path with
+`publisher_overrides`. Use `domain-builder` to scaffold a new domain.
+
+## 3. Write the SKILL.md
+
+A skill is `SKILL.md` = YAML frontmatter + a markdown body (the body is the
+prompt injected to the LLM). Only `name` and `description` are required; all
+skaile-specific fields go inside `metadata:` per `skill-builder-contract`.
+Optional companions in the same folder: `validator.py` (deterministic
+MUST/NEVER/CHECKLIST rules), `CLI.md`, `references/`, and nested sub-skills.
+
+```yaml
+---
+name: brief
+description: Generate a concise project brief from a research question
+metadata:
+  version: "1.0.0"
+  author: skaile
+  tags: [research, brief]
+  stage: alpha          # alpha | beta | stable | deprecated
+  requires:             # cross-asset dependencies (optional)
+    - "@research/brief-format@^2"
+---
+
+# Brief
+
+## When to use
+...
+
+## How it works
+1. ...
+```
+
+Keep the body tight — it ships as a prompt.
+
+## 4. The manifest — `.skaile-source.yaml`
+
+One file at the **repo root** declares how the repo maps to publisher
+namespaces. Two modes:
+
+### v1 — glob mode (default)
+
+Discovery walks the tree, matches kind globs, and resolves publishers from the
+template. Use this while a repo is evolving fast.
+
+```yaml
+version: 1
+publisher_default: '@<domain>'   # <domain> → first-level dir name
+default_ref: main
+publisher_overrides:
+  - path: research-contracts/
+    publisher: '@research-contracts'
+```
+
+### v2 — author-shipped inventory (pinned)
+
+Add an `assets:` block and bump to `version: 2`. Discovery then treats the
+block as authoritative: it **skips the glob walk**, uses your curated `files[]`
+filter, your per-entry publisher, your `requires[]` graph, and verifies your
+`sha256`. Use this for reproducible, signed, audit-friendly releases.
+
+```yaml
+version: 2
+publisher_default: '@<domain>'
+default_ref: main
+assets:
+  - path: research/skills/brief    # relative to repo root
+    kind: skill
+    publisher: '@research'         # required per entry
+    name: brief
+    version: 1.0.0
+    sha256: "<64-hex>"             # optional locally, REQUIRED to publish
+    files:                         # explicit; no wildcards; ≥1
+      - SKILL.md
+      - validator.py
+      - references/template.md
+    requires:
+      - "@research/brief-format@^2"
+    metadata:
+      description: Generates a project brief
+      keywords: [research, brief]
+```
+
+**Never hand-edit the `assets:` block.** Generate it from the asset files (this
+is what `source-manifest-builder` automates):
+
+```bash
+skaile source build-manifest --path ./my-assets            # preview
+skaile source build-manifest --path ./my-assets --diff     # show drift (CI-friendly, non-zero on drift)
+skaile source build-manifest --path ./my-assets --write    # write the manifest
+skaile source verify-manifest --path ./my-assets --strict  # verify before commit/publish
+```
+
+Hash = sort `files[]` lexicographically, then SHA256 over
+`<relpath>\0<content>\0` per file. Author-computed hashes are wire-compatible
+with server-computed ones. Missing files are a hard error in manifest mode.
+
+## 5. Publish
+
+```bash
+# Attach a GitHub remote so the library is store-publishable
+skaile library link personal https://github.com/you/my-assets
+
+# Push bytes to GitHub + register the manifest in the store, atomically
+skaile library publish @research/brief@1.0.0
+
+# Or register a manifest for bytes already on GitHub (no push)
+skaile library register @research/brief@1.0.0
+
+# Retract a catalog entry
+skaile library yank @research/brief@1.0.0
+```
+
+Consumers then install pointer-only: `skaile install @research/brief@1.0.0`
+fetches from your repo at the pinned commit and verifies SHA256 per file.
+
+## Dev-only assets — `dev_paths` + `--dev`
+
+A package can ship two sets of assets: **public** skills its consumers want
+(conventionally under `ai-assets/`), and skills only useful for developing *the
+project itself* — scaffolders, validators, skill-on-skill tooling (under
+`ai-assets-dev/`). The dev set should be **excluded from a normal run** and
+pulled in only when a contributor opts in.
+
+- **Folder name:** keep dev assets under one top-level folder named
+  **`ai-assets-dev/`** (intention-revealing; treat the `-dev` suffix as
+  reserved).
+- **Mechanism:** declare it in `.skaile-source.yaml` under `dev_paths`:
+
+  ```yaml
+  version: 1
+  publisher_default: '@<domain>'
+  dev_paths:               # excluded from a normal discovery run
+    - ai-assets-dev
+  ```
+
+  Normal sync → `ai-assets-dev/` is skipped. `skaile source sync <name> --dev`
+  (or `skaile source add <url> --dev`) re-includes it and indexes the dev
+  assets so `manage` / `install` / `add` can see them. Re-sync without `--dev`
+  to drop them again. Matching is whole-segment, so `ai-assets-dev` excludes
+  `ai-assets-dev/…` but not a sibling like `ai-assets-development`.
+
+  Full guide: `docs/discovery/dev-assets.md`.