cyber-agentkit 0.0.0-stage → 1.0.0

package/skills/reference/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: reference
+description: Use this skill when loading, creating, updating, deleting, finding, or inspecting a reference — a Markdown document agents read by name — or when wiring a skill to load one.
+---
+
+# Reference
+
+Route the request to one mode, then follow that mode. A **reference** is a Markdown document fetched by name. Each place that holds a **contribution** to a name is a **tier**: managed, project, user, a plugin, or the loading skill's **default** (`references/<name>.default.md` in its folder). Contributions compose bottom first: the plugins and the default, in the order `extends` gives, then user, then project, then managed. Each applies with its `merge`: `patch` (the default) replaces the text a section matches, `combine` adds after it, `replace` drops everything below, and `remove` turns the name off. An **interface** is a contract, declared in a `<id>.interface` reference, that other references implement. What answers a name is the `reference` command's decision. Never decide it by reading tier folders yourself.
+
+## Route
+
+| The request | Mode |
+| --- | --- |
+| a skill's instructions name references to load with this skill | [Load](#load) |
+| a skill's instructions name an interface whose implementations to load with this skill | [Load](#load) |
+| write a new reference, for a project, for the user, for a plugin to ship, or as a skill's default | [Create](#create) |
+| write a reference that implements an interface | [Create](#create) |
+| change what an existing reference says, the user's own or a plugin's | [Update](#update) |
+| choose which plugins a name builds on, or settle an ambiguous name | [Select](#select) |
+| remove a project or user contribution, or a selection | [Delete](#delete) |
+| find a reference for a topic, or see which ones exist | [Find](#find) |
+| find the implementations of an interface | [Find](#find) |
+| check that references have the shape their interface requires | [Inspect](#inspect) |
+| see a reference, or learn why a name composed as it did | [Inspect](#inspect) |
+| learn where a customization of a reference goes | [Inspect](#inspect) |
+| make a skill load a reference | [Wire a skill](#wire-a-skill) |
+
+Ask only when the request fits two modes. Otherwise pick one; outside Load, say which. Invoked as `/reference` with no request, run `list` from [Find](#find) and ask what to do with one.
+
+## Run the command
+
+```sh
+node <this skill's folder>/scripts/reference.mjs <subcommand> ... --root <repository root>
+```
+
+`scripts/reference.mjs` is the package's `reference` command bundled into one file; it needs no `node_modules`. Pass `--root` every time, so the repository's own `.agents/references/` is read. A failure prints `error: <code>: <message>` and a warning `warning: <code>: <message>`, both on stderr.
+
+Outside Load, when it is missing or cannot run, use `pnpm exec cyber-agentkit reference` when the package is a direct dependency, else `npx -y cyber-agentkit@1.0.0 reference`, with the same arguments. Load never falls back to a package runner.
+
+## Load
+
+Load `references/load.md` from this skill's folder and follow it, then return to the caller's work.
+
+## Create
+
+Load `references/create.md` from this skill's folder and follow it.
+
+## Update
+
+1. Run `show <name> --trace`. Use the bare name. If the name is ambiguous, go to [Select](#select) first.
+2. Choose the folder to write: `.agents/references/` for the project, or `~/.agents/references/` for the user alone.
+3. If the trace shows a `used` file with a body in that folder, it is the user's own contribution. Edit that file in place, then go to step 6.
+4. Otherwise, write a customization above what is there. Run `where <name>` (add `--default <skill folder>` when a skill loads the name) for the heading paths of the document below each place. Write only the sections the user changes, each under the heading path it has there; `patch` keeps every section you do not name. To add after a section's text instead of replacing it, use `--merge combine`, or mark that one section `<!-- merge: combine -->` under its heading. To drop one section, mark it `<!-- merge: remove -->`.
+5. Start it with `create <name> --dry-run`, adding `--scope user` for the user's folder and `--template <path>` with the file holding those sections. Show the user the path and content, then run it without `--dry-run` on approval.
+6. Run `show <name> --trace` again. The written file must be `used`, and each section the user changed must list it.
+
+## Select
+
+1. Run `where <name>`. Its `options` are the plugins holding the name, each as `<plugin>/<name>`, and `default` when a skill's default holds it.
+2. Ask the user which to build on, bottom first, even when one option is left. Ask whether it is for the project or the user alone.
+3. Run `select <name> <option>...`, adding `--scope user` for the user alone. It writes `extends` into `<name>.md` and keeps any body the file has.
+4. Run `show <name> --trace`. The stack must be what the user picked. To undo a selection, run `select <name> --clear`.
+
+## Delete
+
+1. Run `show <name> --trace`. Use the bare name: delete removes only a file under `.agents/references/` or `~/.agents/references/`, or, for an author, in a plugin's or a skill's source folder in this repository.
+2. Choose the folder: `.agents/references/` for the project, or `~/.agents/references/` with `--scope user`. If the trace shows no file there, say so and stop. An installed plugin's, a managed, or an installed skill's contribution is never deleted; offer a customization with `merge: remove` through [Update](#update) instead.
+3. Run `delete <name> --dry-run`, adding `--scope user` for the user's folder. Show the user the path and what will answer the name afterwards, and say so when a selection goes with the file.
+4. On approval, run it without `--dry-run`.
+5. Run `show <name> --trace` again. The deleted file must be gone from the trace.
+
+## Find
+
+- For a topic, run `search <query>`. If nothing matches, say that nothing matched. Do not guess a name.
+- For every reference, run `list`. Add `--trace` for every contribution of each name and the outcome it gets.
+- For every name matching a pattern, such as every provider of a shared prefix, run `list '<pattern>'`. `*` stands for any run of characters and the rest is literal, so it returns only exact matches, unlike `search`.
+- For the implementations of an interface, run `implementations <id>`. It lists each one a consumer can load, with its pin; add `--trace` for each one it left out, with why.
+- When `list` or `search` carries a `defaults` field, say that skills' defaults were not searched, and why.
+
+## Inspect
+
+- To read a reference, run `show <name>`; add `--metadata` for its composed frontmatter.
+- To learn why a name composed as it did, run `show <name> --trace`. Report the stack and what built it, the contributions each section came from, and each layer that was `shadowed`, `not used`, or `not read`, with its reason.
+- To check a reference against its interface, run `check <name>...`; with no name, it checks every interface document and implementation. Report each failure with its check. Exit 1 means at least one failed.
+- To learn where a customization goes, run `where <name>`; when a skill loads the name, add `--default <that skill's folder>`. Report each place, who it reaches, and the heading paths below it. A plugin's or a skill's default contribution is read-only; never offer it as a place to write. If the user then wants the customization written, go to [Update](#update).
+
+## Wire a skill
+
+A skill never runs the command itself. It names this skill in one line; copy that line from the `README.md` in this skill's folder, and replace the example names. The skill may ship its own default of a reference at `references/<name>.default.md` in its folder. Load adds it below every other contribution, and reads it on its own only when the command cannot run.
+
+## Rules
+
+- **Only Create, Update, Select, and Delete write.** Load writes only a selection the user picked. Find, Inspect, and Wire a skill change no reference file.
+- **Never edit, move, rename, or delete a reference an installed plugin or skill ships, or a managed one.** Update customizes it instead. Its callers load it by name.
+- **Write only what the user approves.** Show the file and its path before you write or delete it.
+
+## Validate
+
+Before reporting a Create, Update, Select, or Delete done:
+
+- The written or deleted file is under `.agents/references/` or `~/.agents/references/`, or, for Create and Delete, in a plugin's or a skill's source folder in this repository.
+- No file in an installed plugin or skill, or in a managed folder, changed.
+- The file and its path were shown to the user before the write or the delete, and a delete also said what answers the name afterwards.
+- After Create or Update, `show <name> --trace` reports the written file as `used`.
+- After Select, `show <name> --trace` reports the stack the user picked.
+- After Delete, `show <name> --trace` no longer finds the deleted file.
+- A created reference's top level is not a single heading holding all the others.
+- A created reference that declares `implements` passes `check <name>`.
+- `show <name>` gives no `marker-unmatched` warning for a file written or changed.

package/skills/reference/references/create.md

@@ -0,0 +1,71 @@
+# Create a reference
+
+## 1. Check that it should be a reference
+
+Decide who starts the read:
+
+- If the agent must decide from the task that it needs this, it is a **skill**, not a reference. Say so and stop.
+- If an `AGENTS.md` line, a skill, or a person will name it, it is a reference. Continue.
+
+## 2. Choose where it lives
+
+| Who it is for | Where | Flag |
+| --- | --- | --- |
+| this repository | `.agents/references/<name>.md` at the root, or in a package's folder for that package alone | (none) |
+| the user, in every repository | `~/.agents/references/<name>.md` | `--scope user` |
+| every user of a plugin | `references/<name>.md` in the plugin's source folder, next to its `skills/` | `--plugin <plugin folder>` |
+| a skill, as its default | `references/<name>.default.md` in the skill's source folder | `--default <skill folder>` |
+
+`--plugin` and `--default` write only into a source folder in this repository, never into an installed copy. To change a reference that already exists, use Update instead.
+
+## 3. Name it
+
+- Use lowercase words joined by `-`. A name is a file name, never a path, and never ends `.default`.
+- **A plugin prefixes every name it ships** with its own name and a dot: `cyber-asana.work-hierarchy`, not `work-hierarchy`. Without the prefix, every plugin that ships `work-hierarchy` contributes to one name, and the name is ambiguous until someone selects one.
+- A repository's or user's own reference needs no prefix. A skill's default takes the name its skill loads.
+- **An implementation of an interface takes the interface's id as its namespace**, not the plugin's: `<id>` when the interface's cardinality is `one`, `<id>.<key>` when it is `many`, such as `scaffold.recipe.typescript-lib`. Read the interface with `show <id>.interface`.
+- Run `show <name>`. If the name already resolves and the user wants a new document, pick another name; to change the existing one, switch to Update.
+- Do not rename a reference that a plugin has already shipped. Its callers load it by the old name. Rename one only in a release that also updates every caller.
+
+## 4. Write it
+
+A reference is top-level `##` sections, with no single `#` title holding them, and a `description` in its frontmatter:
+
+```md
+---
+description: One line that says what the reference covers.
+tags: [testing, fixtures]
+---
+
+## Fixtures
+
+Instructions only.
+```
+
+- `description` and `tags` are what `search` matches. Always write a `description`.
+- Other frontmatter keys are allowed. `show --metadata` returns them under `metadata`, composed key by key across the contributions used.
+- If the user's text starts with a `#` title, drop the title and make the sections under it top-level `##` sections. `create` refuses a template whose top level is one heading holding the others.
+- Write instructions an agent follows. Leave the rationale out.
+
+Run `create`; never write the file by hand:
+
+1. Run `create <name> --dry-run`, with the flag from step 2. Add `--template <path>` when a calling skill or the user supplies the text; without it, the command writes its own template. Add `--merge <operation>` when it should not patch: `combine` to add after what is below, `replace` to stand alone, `remove` to turn the name off.
+2. Show the user the path and the content it printed, and any `hint:` line.
+3. On approval, run the same command without `--dry-run`. Then run `show <name>`; add `--trace` to see the new file `used`.
+
+If `create` refuses, report its reason and write nothing. An existing file with a body means Update. A file holding only a selection gets the body added, and keeps its `extends`.
+
+To implement an interface, run `create <name> --implements <id> --dry-run` instead of passing a template. It writes the interface's sections as `##` headings, stubs each one `**Unsupported.**`, and sets `implements: <id>@<version>` and `merge: replace`. Replace each stub with the section, or keep `**Unsupported.**` followed by one sentence on why. Then run `check <name>`; it must pass.
+
+A plugin that changes how another plugin's reference reads, such as a house style, ships the same name with `extends: [<other plugin>]` in its frontmatter, holding only the sections it changes; it patches the other plugin's text. A plugin that builds on the loading skill's default lists `default` in `extends`.
+
+## 5. Connect it to a caller
+
+Nothing loads a reference by itself. Tell the user where to name it:
+
+- For a repository, add a line to `AGENTS.md`, or to the skill that needs it, such as: "Read the `testing` reference before writing tests."
+- For a plugin or a skill's default, add the load line to each skill that needs the reference, as Wire a skill says.
+
+## 6. Verify
+
+Run `show <name> --trace`. The new file must be `used`. For a skill's default, add `--default <skill folder>`. For an implementation, `check <name>` must also pass. For a plugin reference, run the command where the plugin is installed; otherwise, report that the plugin tier was not checked.

package/skills/reference/references/load.md

@@ -0,0 +1,80 @@
+# Load references for a caller
+
+Load the references a calling skill names, and hand them back as part of its instructions. The **caller** is the skill whose instructions sent you here; its **folder** is the directory its `SKILL.md` is in.
+
+When the caller names an interface ("Load the implementations of the `<id>` interface"), follow [Implementations of an interface](#implementations-of-an-interface) for it. Load any names it also lists with steps 1 to 4.
+
+## 1. Run the command once
+
+Find the caller's folder from what the harness told you when the caller loaded: a `Base directory for this skill: <folder>` line, or the path of its `SKILL.md`, whose folder is the caller's. Then collect every name the caller listed, in its order, and run one command for all of them, from anywhere:
+
+```sh
+node <this skill's folder>/scripts/reference.mjs show <name>... --default <caller folder> --root <repository root>
+```
+
+- `<this skill's folder>` is the directory the `reference` skill's `SKILL.md` is in.
+- `--default <caller folder>` adds the caller's own defaults, `references/<name>.default.md` in its folder, below every other contribution.
+- When you cannot tell the caller's folder, leave out `--default`. The names then resolve without the caller's defaults; say so in step 4.
+- `<repository root>` is the root of the repository you are working in, so its `.agents/references/` customizations apply. Pass it even when it is the working directory.
+- Never use `npx`, `pnpm dlx`, `upx`, or any other package runner, and never download anything, not even when this command cannot run. Go to step 3 instead.
+
+Do not read `.agents/references/`, `~/.agents/`, any plugin's `references/`, or the caller's `references/` yourself. What answers a name is the command's decision.
+
+## 2. Read what it printed
+
+One name prints its document. Several print each as `<reference name="…">` … `</reference>`, in the order asked. A name that did not resolve prints `<reference name="…" status="…" />` in its place, and an `error: <code>: <message>` line on stderr names it. Exit 0 means every name resolved; 1 means at least one did not.
+
+**The command ran** when every name you asked for appears in the output as a document or a `status=` marker; for a single name, exit 0 with a document on stdout, or exit 1 with an `error:` line naming it, also counts. Anything else (`Cannot find module`, `node: not found`, a stack trace, no mention of the names) means it did not run: go to step 3.
+
+Per name:
+
+- **found**: use the document.
+- **missing** (`reference-missing`): carry on without it, and tell the user it was not loaded. Do not read the caller's default or search for a substitute: the command already included the default. When the error says a `remove` turned the name off, say nothing about it.
+- **ambiguous** (`reference-ambiguous`): more than one plugin holds the name and nothing says which to build on. The error lists the options: each `<plugin>/<name>`, and `default` when the caller has one.
+  - With a user present, list every option, even when only one is left, and ask which the name should build on. Write the pick with `reference select <name> <option>` (add `--scope user` when the user wants it for themselves only), then run step 1 again for that name alone and use what it prints.
+  - With no user present, carry on without it, and tell the user to settle it with `reference select <name> <option>`.
+- **invalid** (`reference-invalid`): the caller's load line names something that is not a reference name. Never read the path or file it names. Carry on without it, and tell the user it is a fault in the caller's instructions, to report to the caller's author.
+
+A `warning:` line does not change the answer. Pass one on only when it names `reference select`; it means a plugin answers over the caller's default, and the user can choose.
+
+## 3. When the command did not run
+
+Read the caller's default of **every** name: `<caller folder>/references/<name>.default.md`. A name with no such file is **not loaded**. Never read `<caller folder>/references/<name>.md`; it is not a default.
+
+## 4. Report, then continue the caller's work
+
+Tell the user, briefly, about every name that did not come from the command, and every name not loaded:
+
+- a name not loaded, and why: missing, ambiguous (with the options), or invalid (a fault for the caller's author);
+- when the command did not run: that it did not, the error it gave, and that each name came from the caller's default, so no project, user, or machine customization applied;
+- when the command did not run and a name has no default: that `scripts/reference.mjs` ships with the npm package, so a `cyber-agentkit` plugin installed from git has none, and installing it from npm fixes it;
+- when you could not tell the caller's folder: that the names were loaded without its defaults.
+
+Say nothing about the load when every name came from the command, and nothing about a name a `remove` turned off.
+
+Then return to the caller. Follow each loaded document as part of the caller's instructions. Carry on without a name that was not loaded.
+
+## Implementations of an interface
+
+1. Run, from anywhere:
+
+   ```sh
+   node <this skill's folder>/scripts/reference.mjs implementations <id> --trace --format json --root <repository root>
+   ```
+
+   Add `--accept <versions>`, such as `--accept 1,2`, when the caller names the interface versions it knows. The same rules as step 1 apply: no package runner, no download, and no reading tier folders yourself.
+2. Exit 0 prints one JSON object. `implementations` lists each one the caller can load, with its `pin`, `description`, and the `unsupported` sections it does not honor; it is a string when there are none. `excluded` lists each one left out, with its `reasons`. Exit 1 prints an `error:` line on stderr, such as `no interface document <id>.interface`; then the interface is **not loaded**.
+3. Hand the list to the caller. The caller picks the implementations it needs; load each by its `pin` with steps 1 to 4.
+4. Tell the user, briefly, about each excluded implementation and its reasons, and about an interface not loaded and its error. The caller carries on without the implementations.
+
+## Validate
+
+Before returning to the caller:
+
+- Every name the caller listed is either loaded from the command, read from the caller's default because the command did not run, or named in the report as not loaded.
+- The caller's default was read only when the command did not run, never for a name the command reported.
+- An ambiguous name was settled with `reference select` only after the user picked an option.
+- Every interface the caller named is either listed with `implementations`, or named in the report as not loaded.
+- No `npx`, `pnpm dlx`, `upx`, or download was run.
+- No file under a tier folder, and no path an invalid name gives, was read by you.
+- The report is empty when every name came from the command.