From 1696f6fcaf7dc7964ace6898c6e6753360bf32ec Mon Sep 17 00:00:00 2001 From: samzong Date: Tue, 25 Aug 2026 22:11:19 -0400 Subject: [PATCH] docs(skill): recommend install instead of plan and update Signed-off-by: samzong --- .agents/skills/kitup-release/SKILL.md | 3 ++- .github/PULL_REQUEST_TEMPLATE.md | 2 +- AGENTS.md | 6 +++--- CONTRIBUTING.md | 9 +++++---- README.md | 9 ++++++++- docs/API.md | 5 ++++- docs/vision.md | 2 +- skills/kitup/SKILL.md | 27 ++++++++++++++++++++++++--- 8 files changed, 48 insertions(+), 15 deletions(-) diff --git a/.agents/skills/kitup-release/SKILL.md b/.agents/skills/kitup-release/SKILL.md index 6aea526..26b1657 100644 --- a/.agents/skills/kitup-release/SKILL.md +++ b/.agents/skills/kitup-release/SKILL.md @@ -38,6 +38,7 @@ git push origin vX.Y.Z Release prep must keep these in sync: - `ts/package.json` +- `python/pyproject.toml` - `rust/Cargo.toml` - `rust/Cargo.lock` - `examples/rust/Cargo.lock` @@ -45,6 +46,6 @@ Release prep must keep these in sync: ## Automation -The root `vX.Y.Z` tag triggers `.github/workflows/release.yml`. The workflow runs `make check`, verifies package versions, publishes npm and crates.io packages, creates `go/vX.Y.Z` and `go-cobra/vX.Y.Z`, creates GitHub Release notes, and runs `scripts/smoke-release.sh X.Y.Z`. +The root `vX.Y.Z` tag triggers `.github/workflows/release.yml`. The workflow runs `make check`, verifies package versions, publishes npm, PyPI, and crates.io packages, creates `go/vX.Y.Z` and `go-cobra/vX.Y.Z`, creates GitHub Release notes, and runs `scripts/smoke-release.sh X.Y.Z`. If a registry already accepted a version, do not delete and recreate tags without an explicit recovery plan. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c51bd5a..d3b0f66 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -5,7 +5,7 @@ ## Scope Check - [ ] Stays within the v0.1 bundled-skill installer boundary. -- [ ] Does not add marketplace, registry, remote install, script execution, GUI, MCP server, or agent runtime behavior. +- [ ] Does not add marketplace, registry, private remote install, script execution, GUI, MCP server, or agent runtime behavior. - [ ] Updates golden cases for observable installer behavior changes. - [ ] Regenerates host constants after `spec/hosts.json` changes. diff --git a/AGENTS.md b/AGENTS.md index b9ae299..4aa31d0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -44,7 +44,7 @@ Use the live repository state, not memory or aspiration. - `spec/hosts.json` is the host adapter database. - `spec/*.schema.json` defines accepted shared data shape. - `testdata/cases/*.json` defines cross-language behavior. -- Generated host constants in `ts/`, `go/`, and `rust/` come from `spec/hosts.json`; never edit them by hand. +- Generated host constants in `ts/`, `go/`, `rust/`, and `python/` come from `spec/hosts.json`; never edit them by hand. - `scripts/sync-hosts.mjs` refreshes and checks generated host constants. - `scripts/check.mjs` is the current parity gate. - `docs/host-adapter-contract.md` explains host adapter semantics. @@ -99,7 +99,7 @@ Ownership is controlled by `.kitup.json`: Conflict is the safe default. `force` and `adopt` must stay explicit, tested, and narrow. -Content hashes must be deterministic across TypeScript, Go, and Rust. Hash bundled skill files by sorted relative path and bytes, excluding `.kitup.json` and transient files. +Content hashes must be deterministic across TypeScript, Go, Rust, and Python. Hash bundled skill files by sorted relative path and bytes, excluding `.kitup.json` and transient files. Reports are API contracts. Return structured `installed`, `updated`, `skipped`, `conflicts`, and `errors` data instead of relying on logs. @@ -107,7 +107,7 @@ Skill bundles are directory trees. `SKILL.md` must live at the bundle root, but ## Multi-Language Parity -TypeScript, Go, and Rust should be native SDKs that consume the same shared spec and fixtures. +TypeScript, Go, Rust, and Python should be native SDKs that consume the same shared spec and fixtures. Do not replace this with a single binary core, cross-language FFI, shelling out to another runtime, or generated behavior unless the project direction is explicitly changed. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af08b6b..d5f79d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,7 +14,7 @@ Keep changes inside the v0.1 boundary: - copy, update, and uninstall kitup-owned installs - preserve `.kitup.json` ownership safety - return structured reports -- keep TypeScript, Go, and Rust behavior aligned through golden cases +- keep TypeScript, Go, Rust, and Python behavior aligned through golden cases Do not add marketplace, registry, private remote install, custom provider, script execution, MCP server, GUI, or agent runtime behavior unless the product boundary changes first. @@ -39,7 +39,7 @@ scripts/check.mjs spec, fixture, and SDK parity validation scripts/sync-hosts.mjs generated host constants ``` -TypeScript, Go, and Rust SDKs live in `ts/`, `go/`, and `rust/`. +TypeScript, Go, Rust, and Python SDKs live in `ts/`, `go/`, `rust/`, and `python/`. ## Common Commands @@ -47,7 +47,7 @@ TypeScript, Go, and Rust SDKs live in `ts/`, `go/`, and `rust/`. make generate # refresh generated host constants make generate-check # verify generated host constants are current make check # full parity and example gate -make fmt # format TypeScript, Go, and Rust files +make fmt # format TypeScript, Go, Rust, and Python files make clean # remove local build outputs ``` @@ -59,7 +59,7 @@ Run the full parity gate before opening a pull request: make check ``` -This validates the shared spec, fixtures, generated host constants, standalone Go modules, TypeScript, Go, Rust, and examples. +This validates the shared spec, fixtures, generated host constants, standalone Go modules, TypeScript, Go, Rust, Python, and examples. ## Host Adapter Changes @@ -72,6 +72,7 @@ Host support is data-first. - `ts/src/hosts.generated.ts` - `go/hosts_gen.go` - `rust/src/hosts_generated.rs` + - `python/src/kitup/_hosts_generated.py` ## SDK Behavior Changes diff --git a/README.md b/README.md index 82e2252..a04ee7d 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,10 @@ Your CLI owns the command name and framework shell. `kitup` owns the standard in host detection, safe selection policy, summary text, confirmation, workflow exit classification, target paths, bundle validation, copy/update semantics, metadata, and conflicts. +The recommended user-facing command is `skill install`. Use `--dry-run` to preview writes. Do not add `plan`, +`update`, or `upgrade` subcommands; another install updates kitup-owned copies. Optional `status` and `uninstall` +commands call the primitive APIs. Only the Go Cobra adapter ships those commands. + ### TypeScript Install: @@ -231,11 +235,14 @@ from kitup import resources_bundle bundle = resources_bundle(files("mycli.skills") / "mycli") ``` -For non-interactive or embedding scenarios, call `install_bundled_skill`, `plan_bundled_skill`, `update_bundled_skill`, `status_bundled_skill`, `read_installed_metadata`, or `uninstall_bundled_skill` directly. +For non-interactive or embedding scenarios, call `install_bundled_skill`, `status_bundled_skill`, +`read_installed_metadata`, or `uninstall_bundled_skill` directly. `plan_bundled_skill` is dry-run install; +`update_bundled_skill` is install again. ## Docs - [API](docs/API.md) +- [Architecture](docs/architecture.mmd) - [Contributing](CONTRIBUTING.md) - [Host adapter contract](docs/host-adapter-contract.md) - [Release](docs/RELEASE.md) diff --git a/docs/API.md b/docs/API.md index 50661b4..b2e9fd5 100644 --- a/docs/API.md +++ b/docs/API.md @@ -437,11 +437,14 @@ Recommended CLI behavior: ```bash mycli skill install +mycli skill install --dry-run mycli skill install --scope user --agent codex mycli skill install --scope project --agent codex --agent claude-code mycli skill install --scope user --agent codex --force ``` +Do not expose `plan`, `update`, or `upgrade` as separate commands. `planBundledSkill` / `updateBundledSkill` are the same install path: `--dry-run` plans, and another install updates kitup-owned copies. Optional `status` and `uninstall` commands call the primitive APIs; only the Go Cobra adapter ships those commands. + The lower-level selection resolver remains available for custom shells. It returns one of: - `install`: proceed to plan and confirmation with `selectedHostIds` @@ -481,6 +484,6 @@ Uninstall reports include: TypeScript returns typed report objects. Go exposes `InstallReport`, `UninstallReport`, `TargetResult`, `TargetStatus`, and `ReportError`. Rust exposes `InstallReport`, `UninstallReport`, `TargetResult`, `TargetStatus`, and `ReportError`. -The serialized JSON report shape is the same across TypeScript, Go, and Rust. `installed`, `updated`, and `removed` contain target results. `skipped` and `conflicts` contain target results plus `reason`. +The serialized JSON report shape is the same across TypeScript, Go, Rust, and Python. `installed`, `updated`, and `removed` contain target results. `skipped` and `conflicts` contain target results plus `reason`. Conflict is the safe default. A target directory without matching `.kitup.json` ownership metadata is reported as a conflict, not overwritten unless `force` / `--force` is explicit. diff --git a/docs/vision.md b/docs/vision.md index 7ac3b4e..0751fa6 100644 --- a/docs/vision.md +++ b/docs/vision.md @@ -115,7 +115,7 @@ Most host support is path data. Put it in a shared host adapter database. Keep t ### Native over clever -TypeScript, Go, and Rust users should get native SDKs. Avoid forcing a Go CLI to shell out to Node, or a Rust CLI to ship a JS runtime. +TypeScript, Go, Rust, and Python users should get native SDKs. Avoid forcing a Go CLI to shell out to Node, or a Rust CLI to ship a JS runtime. ### Copy over symlink diff --git a/skills/kitup/SKILL.md b/skills/kitup/SKILL.md index 6bee684..4548653 100644 --- a/skills/kitup/SKILL.md +++ b/skills/kitup/SKILL.md @@ -1,11 +1,11 @@ --- name: kitup -description: Use when integrating kitup into a CLI that ships bundled Agent Skills and needs to install, update, plan, or uninstall those skills across local agent hosts. +description: Use when integrating the kitup SDK into a CLI that ships a bundled Agent Skill and needs to install it on local agent hosts. Also use when wiring install flags, optional status or uninstall, or the Go Cobra adapter. --- # Kitup -Use kitup as a producer-side SDK. The embedding CLI owns the bundled skill; kitup owns host resolution, skill validation, copy/update/uninstall behavior, `.kitup.json` metadata, conflict safety, and structured reports. +Use kitup as a producer-side SDK. The embedding CLI owns the bundled skill and command names. kitup owns host resolution, skill validation, copy/update/uninstall behavior, `.kitup.json` metadata, conflict safety, and structured reports. Call the SDK with: @@ -14,4 +14,25 @@ Call the SDK with: - `scope`: `user` or `project` - `agents`: explicit host ids, `auto`, or all supported hosts -Prefer `plan` before install when showing users what will change. Treat conflicts as stop conditions unless the SDK has explicit tested support for the desired override. +## CLI surface + +Recommended user-facing command: + +```bash +mycli skill install +mycli skill install --dry-run +``` + +Standard install flags: `--scope`, repeatable `--agent`, `--dry-run`, `--yes` / `-y`, `--force`. + +Do not add `plan`, `update`, or `upgrade` subcommands. `--dry-run` is the plan. Re-running install updates kitup-owned copies of the same `appId`. `planBundledSkill` and `updateBundledSkill` are that same install path, not extra commands. + +Optional `status` and `uninstall` commands call `statusBundledSkill` and `uninstallBundledSkill`. Uninstall writes immediately; require `--yes` when stdin is not a TTY, and confirm in TTY mode. There is no uninstall force mode. Only the Go Cobra adapter ships these commands; other languages wire their own shell. + +## Wiring + +For user-facing install, parse flags with `parseInstallFlags` and call `runBundledSkillInstall` with `promptScope: true`. Set `stdinTTY` from the process terminal. Map exits with `installFlagError` and `installWorkflowError`. + +For scripts or tests that already know scope and agents, call `installBundledSkill` directly. + +Treat conflicts as stop conditions unless the caller passed explicit `--force`.