@kindgi/cli 0.0.0-bootstrap.0 → 0.1.1

package/dist/sdk-skills/kindgi-authoring-tools/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: kindgi-authoring-tools
+description: >
+  Covers writing tools for a Kindgi pack with @kindgi/sdk:
+  defining tools via defineTool with either an imperative handler or a
+  declarative HTTP spec, choosing between Zod v4 and JSON Schema for
+  input/output, tool id naming conventions, handling the Result return
+  shape, and how tools reach agents via ToolRef versioning. Load this
+  whenever you are authoring or editing code inside a pack's tools/
+  directory, defining a tool, or wiring a tool onto an agent. Getting
+  started with a new pack is covered by kindgi-getting-started;
+  authoring agents is covered by kindgi-authoring-agents.
+type: core
+library: "@kindgi/sdk"
+version: "0.4.3"
+sdk_version: "0.1.1"
+pack_languages: [node]
+sources:
+  - packages/tools/src/types.ts
+  - packages/tools/src/define.ts
+---
+
+# Authoring Kindgi tools
+
+> **Running `kindgi`:** the CLI is a devDependency of the project (`@kindgi/cli`),
+> not a global command. Run it through the project's package manager —
+> `pnpm exec kindgi …`, `npx --no kindgi …` (npm), `yarn kindgi …` or
+> `bun run kindgi …`. Commands below are written `kindgi …` for brevity.
+
+A **tool** is a callable unit of work an agent invokes: a function with a
+typed input, a typed output, and either author-written logic or a
+declarative spec the framework synthesizes into logic. Tools live at
+`tools/<name>/index.ts` inside a pack; the pack indexer discovers
+them by folder convention.
+
+Before writing a tool, establish what it should DO — its purpose,
+inputs, outputs, and whether it extends an existing tool or is fresh.
+Requests like "add a tool" without a purpose are conversation openers,
+not tickets. Ask what it should compute or fetch, what shape the caller
+provides, what shape it returns. The pack's existing tools are examples
+that prove the framework runs end-to-end — they are NOT the shape you
+imitate unless the user explicitly asks for that.
+
+## Two authoring modes
+
+Both use `defineTool` from `@kindgi/sdk/define`. Pick based on where the
+logic lives:
+
+- **`handler`** — imperative TS function. Use when the tool computes,
+  transforms, calls a proprietary library, or has non-trivial logic
+  that lives in the pack's source.
+- **`spec`** — declarative descriptor. Use when the tool is a
+  straightforward remote call. `spec: {kind: 'http', ...}` is the kind
+  that ships with the framework; other kinds can be added with
+  `registerToolSpecSynthesizer`. The framework synthesizes the handler
+  from the spec — URL substitution, timeout, abort propagation, secret
+  resolution and the status check are handled for you (there is no
+  automatic retry).
+
+`handler` and `spec` are MUTUALLY EXCLUSIVE. Setting both (or neither)
+makes `defineTool` return an `invalid-tool-definition` error.
+
+## Imperative handler
+
+```ts
+// tools/verify-citation/index.ts
+import { defineTool } from '@kindgi/sdk/define';
+import type { ToolId } from '@kindgi/sdk/types';
+import { z } from 'zod';
+
+const Input = z.object({
+  citation: z.string().min(1),
+  jurisdiction: z.enum(['US', 'UK', 'EU']),
+});
+
+const Output = z.object({
+  found: z.boolean(),
+  canonicalCite: z.string().optional(),
+});
+
+const defined = defineTool({
+  id: 'acme.verify-citation' as ToolId,
+  description:
+    'Verify a legal citation against the jurisdictional citator. Returns whether the citation resolves and the canonical form.',
+  version: '0.1.0',
+  input: Input,
+  output: Output,
+  effects: [],
+  mutating: false,
+  handler: async (input, ctx) => {
+    // ctx.tenantId, ctx.abortSignal, ctx.secrets (what needsSpec declares) available
+    // Return type MUST match Output schema (validated at invoke time)
+    return { found: true, canonicalCite: '...' };
+  },
+});
+
+if (defined.kind === 'err') {
+  throw new Error(`acme.verify-citation failed to compile: ${defined.error.message}`);
+}
+
+export default defined.value;
+```
+
+A handler must return a Promise; one with nothing to `await` can return `Promise.resolve({ … })` instead of being `async`, which keeps lint rules like `require-await` quiet.
+
+### What the handler receives
+
+The handler gets the **parsed** input, typed `z.infer` of `input` (Zod's output type):
+
+- **Defaults.** A `.default()` field is optional to the caller, the model included. The tool's advertised schema doesn't list it as required, and the handler always gets a value.
+- **Transforms and refinements.** `.transform()` results and `.refine()` checks apply before the handler runs. A failed refinement comes back as `input-validation-failed`.
+- **Extra keys.** A plain `z.object` accepts them and strips them. Use `z.strictObject` to reject them.
+- **JSON-Schema-authored tools** get each property's `default` filled in the same way.
+
+The output side is the reverse: the advertised output schema requires every field, defaulted ones included. Return them all.
+
+### Configuration and secrets
+
+A secret that belongs to the tenant — an API key a customer gives you — is declared, and read from `ctx.secrets`:
+
+```ts
+const defined = defineTool({
+  // …id, description, version, input, output, effects…
+  needsSpec: { secrets: { CITATOR_KEY: { type: 'string', minLength: 20 } } },
+  handler: async (input, ctx) => {
+    const key = ctx.secrets?.CITATOR_KEY;
+    // …
+  },
+});
+```
+
+The runtime resolves every declared secret on every call, for the call's tenant, in its env (`KINDGI_ENV`; in `kindgi dev`, `local`: the pack's `.env` and `.env.local`). It checks each value against its schema, and fails the call, naming the secret, when one is missing or doesn't match. Every declared secret is required, so in a runtime call `ctx.secrets` holds them all; it's optional in the type because a unit test builds its own context and passes `secrets: { CITATOR_KEY: '…' }`.
+
+Everything else comes from the process environment: `process.env.CITATOR_URL`. The pack service runs with the pack's env files in `kindgi dev`, and with the container's environment in an image. Declare the names your code reads in `kindgi.config.ts`, `env: { required: ['CITATOR_URL'], optional: [...] }`: a deployment injects exactly those, a pack service missing a required one isn't ready and says which, and `kindgi dev` warns about it. Values per environment go in `environments.<name>.env`, secrets only as references.
+
+## Declarative HTTP spec
+
+```ts
+// tools/fetch-order/index.ts
+import { defineTool } from '@kindgi/sdk/define';
+import type { ToolId } from '@kindgi/sdk/types';
+import { z } from 'zod';
+
+const defined = defineTool({
+  id: 'shop.fetch-order' as ToolId,
+  description: 'Fetch an order by id from the storefront API.',
+  version: '0.1.0',
+  input: z.object({ orderId: z.string() }),
+  output: z.object({ id: z.string(), status: z.string(), total: z.number() }),
+  effects: [],
+  mutating: false,
+  spec: {
+    kind: 'http',
+    method: 'GET',
+    urlTemplate: 'https://api.shop.example/orders/{orderId}',
+    // Every {placeholder} MUST be a key on the input schema
+    authorization: {
+      kind: 'bearer',
+      secretRef: { envName: 'production', name: 'shop-api-token' },
+    },
+    successStatus: { min: 200, max: 299 },
+  },
+});
+
+if (defined.kind === 'err') throw new Error(defined.error.message);
+export default defined.value;
+```
+
+## Read-only tools: `mutating`
+
+`mutating: false` declares that the tool changes nothing outside Kindgi; it only reads. Leaving `mutating` out counts as mutating, the same as `true`. It decides two things, in both authoring modes:
+
+- **Dry runs.** `kindgi runs start --dry-run` runs a tool only if it's `mutating: false` and its `effects` declare no `writes`, `deletes`, `spawns-run`, `emits-event` or `external-side-effect`. The first other tool stops the run with `dry-run-effectful-tool`.
+- **Approval gates.** When an agent turns tool gates on (`conversationPolicy.hitl.tools`) and sets neither an override for the tool nor a `default`, a `mutating: false` tool runs straight through, and any other tool asks for approval on its first use.
+
+So declare `mutating: false` on every tool that only reads, and never on one that writes.
+
+## Tool id convention
+
+`<pack-id>.<tool-name>` — kebab-case, dot-namespaced. The `<pack-id>`
+prefix scopes the tool to its pack; `<tool-name>` names the operation.
+Enforced by `defineTool` at author time. Examples:
+`acme.verify-citation`, `shop.fetch-order`, `demo.echo`.
+
+## Iterating on a tool
+
+Edit the source file (`tools/<tool>/index.ts`), save. The next
+`kindgi runs start` sees the change — new input/output schema, new
+description, new handler behavior. No version bump, no restart, no
+re-registration ceremony. Source is truth in dev.
+
+The `version` field is a **semver contract for humans** — it declares
+what callers can rely on. Bump it because the *contract with
+downstream callers* changed (removed a field, tightened a type,
+narrowed enum values), not because you saved the file. If you're
+iterating in dev and the shape isn't finalized, leave `version`
+alone.
+
+**When version matters:** `kindgi deploy` publishes to a durable
+production registry that enforces the immutable `(id, version)`
+contract — a re-publish of the same version with different bytes
+gets rejected. That's when semver discipline kicks in. The deploy
+tooling surfaces the check; you don't have to think about it while
+authoring.
+
+**Downstream callers still pin ranges.** An agent's `tools: [{id,
+version: '^0.1.0'}]` picks the highest active version matching the
+range at run start. Compatible tool updates (patch, minor) reach the
+agent without editing agent source; breaking updates (major) require
+the agent-author to opt in.
+
+## Wiring the tool onto an agent
+
+Agents reference tools via `ToolRef[]`, NOT `string[]`. Each entry is
+`{id, version}` where `version` is an npm-style semver **range**:
+
+```ts
+// agents/brief-writer/index.ts
+tools: [
+  { id: 'acme.verify-citation' as ToolId, version: '^0.1.0' },
+  { id: 'acme.fetch-precedent' as ToolId, version: '~0.2.0' },
+],
+```
+
+The resolver picks the highest active version matching the range at
+run start via `semver.maxSatisfying`. No implicit `:latest`.
+
+## Common mistakes
+
+1. **Copying another tool's shape without user intent.** The pack may
+   ship `tools/echo/` as a starter example. Copying its skeleton to
+   make `tools/lookup/` produces plausible-looking code that solves
+   the wrong problem. Ask the user what the new tool should DO first.
+
+2. **Passing bare strings to `agent.tools`.** `tools: ['acme.verify-citation']`
+   doesn't type-check (`tools` is `ToolRef[]`), and `defineAgent`
+   returns `invalid-agent` for a bare string that slips through. Use
+   `[{id: 'acme.verify-citation', version: '^0.1.0'}]`.
+
+3. **Forgetting the `Result` unwrap.** `defineTool` returns
+   `Result<DefinedTool, ToolError>` — a bad schema doesn't throw at import
+   time unless you check `defined.kind === 'err'`. Always unwrap at
+   module load so a broken pack fails LOUDLY, not on first invocation.
+
+4. **`handler` and `spec` together.** Mutually exclusive.
+   `defineTool` returns `invalid-tool-definition` with both set.
+
+5. **`{placeholder}` in `urlTemplate` without a matching input key.**
+   HTTP tools substitute placeholders from the input at invoke time.
+   Missing keys throw a clear error at invoke time — check both sides
+   line up.
+
+6. **An HTTP tool's `secretRef` in the wrong env.** The runtime
+   resolves `authorization.secretRef` itself, on every call, in the env
+   the ref names: `{ envName: 'local', … }` is the pack's `.env` /
+   `.env.local` under `kindgi dev`, while `'production'` reads
+   `.env.production`. A secret it can't find fails the call with
+   `secret-unavailable`, naming it. Only a harness of your own that
+   calls `invokeTool` directly has to pass `ctx.resolveSecret`.
+7. **Reading a secret from `process.env` in a tool that runs for many
+   tenants.** The pack service's environment is one for all of them.
+   Declare the secret in `needsSpec.secrets` and read `ctx.secrets`.
+
+8. **Bumping `version` on every dev save.** Old habit from
+   frameworks that stored manifests immutably by `(id, version)`.
+   Kindgi's dev mode reads tool manifests directly from source —
+   version doesn't gate iteration. Bump it when the *contract*
+   changes (breaking schema shape, semantic behavior), not when you
+   save. See the "Iterating on a tool" section above.
+
+9. **A package a tool imports, listed only in `devDependencies`.** The
+   deployed pack installs the app's production dependencies only, so the
+   import works under `kindgi dev` and fails in the image. When a tool
+   imports a new package (an ORM client such as `@prisma/client`, an API
+   SDK), check that the app's `package.json` lists it under
+   `dependencies`. Build-time tools (the `prisma` CLI, `typescript`) stay
+   in `devDependencies`. `kindgi dev` warns as soon as a tool imports one
+   ("⚠ The pack imports @prisma/client (in kindgi/tools/…), which
+   package.json lists only in devDependencies: …"), and `kindgi build`
+   refuses the pack until it moves.
+
+## References
+
+- Type surface: `hover any @kindgi/sdk/define export` in your editor
+  for full JSDoc — every field on `DefineToolSpec` / `ToolManifest`
+  documents purpose, when to set it, and gotchas.
+- API reference: https://docs.kindgi.com/v0.1/reference/typescript/sdk/kindgi/sdk/define/ (every `define*` spec, field by field).
+- Common patterns: check the `sample` template (`kindgi init
+  --template=sample`) for working examples of both authoring modes.
+
+## When the framework itself is the problem
+
+If you diagnose that the bug lives in Kindgi/`@kindgi/sdk` itself (SDK
+type drift, wire schema silently dropping a field, indexer allowlist
+gap, misleading error, CLI friction) — not in the pack's own code —
+load the `kindgi-framework-feedback` skill and file a structured report
+with `kindgi feedback write`. That diagnostic is high-signal input the
+maintainers can act on; don't let it disappear into the transcript.

package/dist/sdk-skills/kindgi-framework-feedback/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: kindgi-framework-feedback
+description: >
+  Capture framework-level feedback about Kindgi/@kindgi/sdk when you
+  diagnose a problem that isn't in the pack's own code — SDK type
+  drift, API wire schema gaps, adapter regressions, CLI
+  friction, skill/code mismatches, misleading errors, UX cliffs.
+  Load whenever you have just diagnosed such a problem during pack
+  authoring. Also load when the pack author asks you to remove,
+  mark-fixed, or re-order entries in FEEDBACK.md — the file is a
+  simple markdown list you edit directly with the Edit tool. Distinct
+  from authoring skills (which help you build packs) and from
+  getting-started (which onboards new packs); this skill turns your
+  diagnostic output into durable input for framework improvement.
+type: core
+library: "@kindgi/sdk"
+version: "0.4.0"
+sdk_version: "0.1.1"
+pack_languages: [node, python]
+---
+
+# Capturing framework feedback
+
+> **Running `kindgi`:** in a Node project the CLI is a devDependency
+> (`@kindgi/cli`), not a global command. Run it through the project's
+> package manager — `pnpm exec kindgi …`, `npx --no kindgi …` (npm),
+> `yarn kindgi …` or `bun run kindgi …`. A Python pack (`[tool.kindgi]` in
+> `pyproject.toml`) has no Node project: run the `kindgi` on `PATH`.
+> Commands below are written `kindgi …` for brevity.
+
+You just spent time diagnosing a Kindgi-framework issue. That diagnostic
+is exactly the kind of report the framework maintainers need — file:line
+pointers, exact reproducers, honest severity, what you expected vs. what
+you observed. **This skill exists to make sure that value doesn't get
+lost in the transcript.**
+
+## The mechanism is deliberately simple
+
+One file: `FEEDBACK.md` at the pack root. Each entry is a markdown
+section with two identifiers:
+
+- **`id: YYYY-MM-DD.N`** — per-day counter, unique within this pack.
+  Used for local navigation and hand-editing ("remove 2026-09-25.3").
+- **`hash: feedback-<8-hex>`** — deterministic hash of the
+  normalized title. Two packs (or two peers) filing the same issue
+  produce the same hash, so p2p sync and framework-side clustering
+  work without a central registry.
+
+`kindgi feedback write` appends new entries with both stamps. To mark
+an item fixed, add a `> **Fixed:** <note>` line right after its
+header. To remove an item, delete the section (including the
+trailing `---` separator). All of that is plain markdown editing —
+no `kindgi feedback update`, no `kindgi feedback delete`, no
+separate tracking database.
+
+## When to file
+
+File an entry when you diagnose:
+
+- **SDK type drift** — a skill or docs claim a field that the SDK's
+  `.d.ts` doesn't have (or vice versa).
+- **Wire schema gaps** — the API silently drops a field you sent
+  (usually `additionalProperties: false` missing a property).
+- **Adapter regressions** — behavior changed between rebuilds.
+- **CLI friction** — command failures with unhelpful error messages,
+  missing verbs, stubs that pretend to work.
+- **Skill/code mismatches** — the skill example doesn't work as
+  written.
+- **Misleading errors** — the error message points at the wrong
+  thing.
+- **UX cliffs** — the "obvious next step" fails and the recovery
+  isn't documented.
+
+Do NOT file when:
+
+- The bug is in the pack's own code (that's a normal debug loop).
+- You haven't actually reproduced it — file with `--kind=question`
+  instead so it's flagged as unconfirmed.
+
+## How to file — the command
+
+```sh
+kindgi feedback write \
+  --kind=bug \
+  --severity=high \
+  --title="preferredProvider silently dropped by wire schema" \
+  --authored-by=claude-code \
+  --body=@/tmp/report.md
+```
+
+Body-input modes:
+
+- `--body=@<file>` — reads the file at path.
+- `--body="<literal text>"` — literal content inline. Useful for
+  short entries.
+- `--body-stdin` — reads from stdin (`diagnose | kindgi feedback write ...`).
+- `--interactive` (or omit all of the above) — opens `$EDITOR` with
+  a template.
+
+The entry lands as a new `## <title>` section appended to
+`FEEDBACK.md`, stamped with a fresh `id: YYYY-MM-DD.N`. The file is
+created with a header if it doesn't yet exist.
+
+## Entry shape (what the CLI produces)
+
+```md
+## preferredProvider silently dropped by wire schema
+
+- **id:** 2026-09-25.3
+- **hash:** feedback-a3f2c1d0
+- **kind:** bug
+- **severity:** high
+- **date:** 2026-09-25T14:32:07.104Z
+- **sdk:** 0.1.2 · **cli:** 0.1.2 · **by:** claude-code
+
+### Summary
+One-line: what the report is about.
+
+### Observed
+What happened, with file:line pointers when possible.
+
+### Expected
+What should have happened.
+
+### Reproducer
+Exact commands, spec files, output.
+
+### Suggested fix
+Optional; leave blank if you don't have one.
+
+---
+```
+
+## Editing FEEDBACK.md directly
+
+Entries are referenced locally by their `id` (e.g. `2026-09-25.3`)
+or by their title; across packs (or between peers) they are referenced
+by their `hash` (e.g. `feedback-a3f2c1d0`). When the pack author says
+something like:
+
+- **"Remove 2026-09-25.3"** / **"Remove the preferredProvider
+  entry"** → find the section whose `id` matches (or whose `##
+  <title>` matches), delete from the header down through the next
+  `---` separator (inclusive). Do NOT renumber other entries — ids
+  are historical identifiers, gaps are expected.
+- **"Mark 2026-09-25.3 fixed"** / **"That preferredProvider one
+  landed in commit abc123"** → find the section, insert a line
+  right after the header:
+  ```md
+  > **Fixed:** landed in commit abc123 (2026-09-25). <optional context>
+  ```
+- **"Note that 2026-09-25.5 is a duplicate of feedback-a3f2c1d0"** /
+  **"Merge these — same hash"** → find the section, insert:
+  ```md
+  > **Duplicate of:** feedback-a3f2c1d0 (<optional context>)
+  ```
+  Prefer the `hash` when the duplicate lives in another pack (peer /
+  framework side); prefer the `id` when it's a local duplicate.
+- **Restructuring / re-ordering** → use the Edit tool to move the
+  section; keep the header + `- **id:** …` + `- **hash:** …` lines
+  intact so both identifiers stay stable.
+
+Do NOT try to re-file the same item through `kindgi feedback write`
+— that would create a new entry with a new id (though the hash
+would match, which is exactly the p2p-dedup signal). Always edit
+directly for maintenance operations within one pack.
+
+## Fields to fill precisely
+
+- **`kind`** — honest classification.
+  - `bug` — the framework did the wrong thing (crashed, silently
+    dropped a field, contradicted its own docs).
+  - `friction` — the framework did the "right" thing but the UX cost
+    more time than the task warranted.
+  - `question` — you don't understand something and the docs don't
+    answer it.
+  - `design` — you observed something that works as designed but the
+    design might be wrong.
+
+- **`severity`** — honest impact.
+  - `blocker` — nothing useful can happen until this is fixed.
+  - `high` — a common workflow is broken; users will hit this.
+  - `medium` — real friction, but there's a documented workaround.
+  - `low` — cosmetic, tiny annoyance, or affects one obscure path.
+
+- **`authored_by`** — `claude-code` when the diagnostic came entirely
+  from an AI coding assistant; `human` when the pack author wrote
+  it; `mixed` when it's a combination.
+
+## Common mistakes
+
+1. **File-path-only entries** ("bug in router.ts").
+   Without a reproducer + expected behavior, the maintainer has to
+   reverse-engineer your session. File:line is necessary but not
+   sufficient.
+2. **Skipping "Suggested fix" when you have one.** If you diagnosed
+   the root cause, name it. "Add `preferredProvider` to `AgentSchema`
+   in `packages/api/src/openapi/schemas.ts:667`" is worth a dozen
+   back-and-forth clarifications.
+3. **Bundling multiple bugs into one entry.** Run `kindgi feedback
+   write` once per bug. Each gets its own number, its own fix
+   status, its own removal path.
+4. **Sensitive state in reproducers.** Reproducer sections sometimes
+   contain API keys, tenant IDs, secrets — review before committing.
+5. **Filing "the way I'd design it" as a bug.** Design disagreements
+   are `--kind=design`, not `--kind=bug`. Both are welcome; the
+   classification helps prioritization.
+
+## References
+
+- `FEEDBACK.md` at the pack root — the running list itself.