Skip to content
This repository was archived by the owner on Aug 25, 2026. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/skills/agent-core-dev/verify.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Run from the package (or with `--filter @moonshot-ai/agent-core-v2`):

## Changesets (when the change ships through the CLI)

If the change is user-facing and ships through the CLI, generate a changeset with the repository's `gen-changesets` skill (root `AGENTS.md` workflow). `agent-core-v2` is an internal package; if its change enters the CLI bundle, the changeset lists `@moonshot-ai/kimi-code` and describes the real change — do not present an internal-only change as a user-facing feature. Never write a `major` bump without explicit user confirmation.
If the change is user-facing and ships through the CLI, generate a changeset with the repository's `gen-changesets` skill (root `AGENTS.md` workflow). `agent-core-v2` is an internal package; if its change enters the CLI bundle, the changeset lists `echadron` and describes the real change — do not present an internal-only change as a user-facing feature. Never write a `major` bump without explicit user confirmation.

## Pre-submit checklist

Expand All @@ -28,5 +28,5 @@ Then re-read the [global red lines](SKILL.md#global-red-lines) once — they cat
## Red lines (this stage)

- Do not skip `lint:domain` — it is the only automated check for the dependency-direction rules.
- Do not list internal packages in a changeset when the change enters the CLI bundle — list `@moonshot-ai/kimi-code` and describe the real change.
- Do not list internal packages in a changeset when the change enters the CLI bundle — list `echadron` and describe the real change.
- Never write a `major` changeset without explicit user confirmation.
46 changes: 23 additions & 23 deletions .agents/skills/gen-changesets/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
name: gen-changesets
description: Use when generating changesets in the kimi-code repository, including package bump selection, internal package and CLI bundle handling, bump levels, major confirmation, and English changelog wording.
description: Use when generating changesets in the Echadron repository, including package bump selection, internal package and CLI bundle handling, bump levels, major confirmation, and English changelog wording.
---

# Generate Changesets

`kimi-code` uses changesets to manage versions and changelogs. The current user-facing published package is:
Echadron uses changesets to manage versions and changelogs. The current user-facing published package is:

- `@moonshot-ai/kimi-code`: the CLI
- `echadron`: the CLI

All other `@moonshot-ai/*` packages are treated as internal packages, including `@moonshot-ai/kimi-code-sdk`, `agent-core`, `kosong`, `kaos`, `kimi-code-oauth`, `kimi-telemetry`, and `migration-legacy`.

Expand All @@ -17,14 +17,14 @@ All other `@moonshot-ai/*` packages are treated as internal packages, including

1. **Inspect the actual changes first.** Use `git status` / `git diff --name-only` to identify which packages were actually changed.
2. **List packages that changesets can release.** If a changed package is ignored in `.changeset/config.json`, do not put that ignored package in frontmatter together with a non-ignored package; changesets rejects mixed ignored/non-ignored frontmatter.
3. **Map ignored internal changes to the affected released package.** If an ignored internal package changes CLI output or behavior, list `@moonshot-ai/kimi-code` and describe the actual user-visible or release-artifact change in the changelog text.
4. **Internal package source changes that enter the CLI bundle must manually list the CLI — when they get a changeset at all.** `@moonshot-ai/kimi-code` inline-bundles `@moonshot-ai/*` source, but those internal packages are devDependencies from the CLI's perspective, so changesets will not automatically propagate bumps. If a change enters the CLI output and is user-perceivable, list `@moonshot-ai/kimi-code`. See rule 6 for when to skip the changeset entirely.
- **Web app (`@moonshot-ai/kimi-web`) changes always enter the CLI bundle.** `@moonshot-ai/kimi-web` is ignored by changesets (see `.changeset/config.json`) and cannot be mixed with `@moonshot-ai/kimi-code` in one changeset frontmatter. Describe the web change in the changelog text, but list `@moonshot-ai/kimi-code` so the CLI release carries the bundled `dist-web` output.
3. **Map ignored internal changes to the affected released package.** If an ignored internal package changes CLI output or behavior, list `echadron` and describe the actual user-visible or release-artifact change in the changelog text.
4. **Internal package source changes that enter the CLI bundle must manually list the CLI — when they get a changeset at all.** `echadron` inline-bundles `@moonshot-ai/*` source, but those internal packages are devDependencies from the CLI's perspective, so changesets will not automatically propagate bumps. If a change enters the CLI output and is user-perceivable, list `echadron`. See rule 6 for when to skip the changeset entirely.
- **Web app (`@moonshot-ai/kimi-web`) changes always enter the CLI bundle.** `@moonshot-ai/kimi-web` is ignored by changesets (see `.changeset/config.json`) and cannot be mixed with `echadron` in one changeset frontmatter. Describe the web change in the changelog text, but list `echadron` so the CLI release carries the bundled `dist-web` output.
5. **Docs-only and tests-only changes usually do not need a changeset.** README, internal docs, and `test/` changes that do not enter package output do not trigger a CLI bump.
6. **Skip changes users cannot perceive — write no changeset at all.** The CLI changelog is user-facing; a changeset is a changelog entry, not a shipping gate. Internal changes merged to `main` still ship in the next release triggered by any user-facing changeset, so skipping the changeset loses nothing. Do not write changesets for:
- `agent-core-v2` internal architecture: new services, refactors, config-persistence or journal/wire mechanisms.
- `kap-server` WebSocket / REST protocol changes consumed only by the bundled web UI, kimi-inspect, or other dev tooling (new endpoints, subscribe protocols, stream baselines). A web-facing feature they back gets its own `web:` entry instead.
- Behavior that only takes effect on the experimental engine (e.g. experimental `kimi -p`), unless it exposes documented user configuration such as a `config.toml` section or env vars that also work on a shipped surface (TUI or `kimi web`).
- Behavior that only takes effect on the experimental engine, unless it exposes documented user configuration such as a `config.toml` section or env vars that also work on a shipped surface.
- When unsure whether users can perceive a change, ask before writing.
7. `@moonshot-ai/vis` / `vis-server` / `vis-web` are ignored by changesets and should not be handled. `@moonshot-ai/kimi-inspect` (a private dev app that never ships) is likewise ignored and must never appear in a changeset frontmatter.

Expand All @@ -33,7 +33,7 @@ All other `@moonshot-ai/*` packages are treated as internal packages, including
1. List the changed packages and check whether each one is ignored by `.changeset/config.json`.
2. Decide whether the change is user-perceivable (Core Rule 6); if not, stop — no changeset.
3. Choose a bump level for each package.
4. If an ignored internal package change enters the CLI bundle, put `@moonshot-ai/kimi-code` in frontmatter instead of mixing the ignored package into the same changeset.
4. If an ignored internal package change enters the CLI bundle, put `echadron` in frontmatter instead of mixing the ignored package into the same changeset.
5. Create a short kebab-case file under `.changeset/`.
6. Split unrelated changes into separate changesets; keep one logical change in one file.

Expand Down Expand Up @@ -74,7 +74,7 @@ If you believe a change qualifies as major, stop first, explain why, and ask the
- **Keep the whole entry concise.** Aim for one short sentence that states what was done; at most a short sentence plus a one-line usage hint. Do not write a paragraph, do not pile on technical detail, and do not enumerate every sub-change.
- **For new user-facing features, append a brief usage hint** so users know how to try it. Keep it to a single short line — a command name, a subcommand, a flag, or a one-line "how to use". Do not explain design rationale or list edge cases. Skip the hint for bug fixes, internal changes, and refactors.
- Slash command: `Add the /foo slash command to list active sessions. Run /foo to see them.`
- CLI subcommand: `Add the kimi web subcommand to open the web UI. Run kimi web to launch it.`
- CLI subcommand: `Add the echadron web subcommand to open the web UI. Run echadron web to launch it.`
- Flag: `Add a --bar flag to skip confirmation prompts. Pass --bar to skip.`
- Too long: `Add the /foo command to list active sessions. It accepts an optional --all flag to include background sessions, supports filtering by name with /foo <name>, and writes the result to the transcript...`
- User-facing CLI wording should only be used when CLI users can perceive the change.
Expand All @@ -97,7 +97,7 @@ An internal package fixes a bug visible to CLI users:

```markdown
---
"@moonshot-ai/kimi-code": patch
"echadron": patch
---

Fix occasional loss of tool call results in long conversations.
Expand All @@ -107,7 +107,7 @@ A new user-facing slash command (note the short usage hint):

```markdown
---
"@moonshot-ai/kimi-code": minor
"echadron": minor
---

Add the /foo slash command to list active sessions. Run /foo to see them.
Expand All @@ -117,17 +117,17 @@ A new CLI subcommand:

```markdown
---
"@moonshot-ai/kimi-code": minor
"echadron": minor
---

Add the kimi web subcommand to open the web UI. Run kimi web to launch it.
Add the echadron web subcommand to open the web UI. Run echadron web to launch it.
```

A new flag on an existing command:

```markdown
---
"@moonshot-ai/kimi-code": patch
"echadron": patch
---

Add a --bar flag to skip confirmation prompts. Pass --bar to skip.
Expand All @@ -137,7 +137,7 @@ An internal package has an internal-only change, but it enters the CLI bundle:

```markdown
---
"@moonshot-ai/kimi-code": patch
"echadron": patch
---

Unify tool execution metadata handling.
Expand All @@ -155,7 +155,7 @@ Clarify session status typing for internal SDK callers.

## Web app changes

`@moonshot-ai/kimi-web` is ignored by changesets and must **never** appear in a changeset frontmatter. Because the web app is bundled into the CLI release artifact, any web change that ships must list `@moonshot-ai/kimi-code` instead and describe the actual web-facing change in the text.
`@moonshot-ai/kimi-web` is ignored by changesets and must **never** appear in a changeset frontmatter. Because the web app is bundled into the CLI release artifact, any web change that ships must list `echadron` instead and describe the actual web-facing change in the text.

- Prefix the changelog entry text with `web: ` (for example `web: Fix the chat not scrolling to the bottom after sending a message.`) so the synced docs changelog can mark web UI entries. Apply this whenever the change is to the web project (`@moonshot-ai/kimi-web`).
- If a PR ships a web UI feature backed by server API changes that exist solely to power that feature, prefer a single `web:` entry describing what the web user gets. Do not add a separate server-API changeset unless the API has independent user value (a public endpoint that SDK or server consumers call directly). The docs changelog sync also deduplicates this pattern, but catching it here avoids duplicate changesets.
Expand All @@ -165,7 +165,7 @@ Web-only fix:

```markdown
---
"@moonshot-ai/kimi-code": patch
"echadron": patch
---

web: Fix the chat not scrolling to the bottom after sending a message.
Expand All @@ -175,7 +175,7 @@ Web UI plus backing server APIs in the same PR (prefer a single `web:` entry; th

```markdown
---
"@moonshot-ai/kimi-code": minor
"echadron": minor
---

web: Add the server-hosted web UI, including chat layout and session list behaviors.
Expand All @@ -185,10 +185,10 @@ Split into two changesets only when the API has independent user value on its ow

## `@moonshot-ai/pi-tui` changes

`@moonshot-ai/pi-tui` is a vendored fork that lives in `packages/pi-tui`. It is `private: true` and is never published, but it is **not** ignored by changesets: changesets versions it and writes `packages/pi-tui/CHANGELOG.md` so the fork keeps its own history. Because it is bundled into the CLI like other internal packages, it is an exception to Core Rule 4 — do **not** list `@moonshot-ai/kimi-code` for a change that only touches pi-tui.
`@moonshot-ai/pi-tui` is a vendored fork that lives in `packages/pi-tui`. It is `private: true` and is never published, but it is **not** ignored by changesets: changesets versions it and writes `packages/pi-tui/CHANGELOG.md` so the fork keeps its own history. Because it is bundled into the CLI like other internal packages, it is an exception to Core Rule 4 — do **not** list `echadron` for a change that only touches pi-tui.

- Changes that only affect pi-tui (build, package, strict-mode cleanup, renderer fixes): list `@moonshot-ai/pi-tui` only. No CLI changeset.
- If the same change is also user-visible in the CLI (for example a terminal rendering fix that CLI users can see), add a **separate** changeset that lists `@moonshot-ai/kimi-code` with CLI-focused wording, in addition to the pi-tui changeset. Do not mix both packages in one frontmatter — the two changelogs need different wording.
- If the same change is also user-visible in the CLI (for example a terminal rendering fix that CLI users can see), add a **separate** changeset that lists `echadron` with CLI-focused wording, in addition to the pi-tui changeset. Do not mix both packages in one frontmatter — the two changelogs need different wording.

pi-tui-only change:

Expand All @@ -212,7 +212,7 @@ Clamp the differential render to the visible viewport so scrolling up during str

```markdown
---
"@moonshot-ai/kimi-code": patch
"echadron": patch
---

Fix the transcript jumping to the top when scrolling up through history during streaming output.
Expand All @@ -225,13 +225,13 @@ Fix the transcript jumping to the top when scrolling up through history during s
- A new env var overlay or config fallback for an existing feature is bumped `minor` — configuration additions to existing features are `patch`.
- A new user-facing feature entry has no usage hint, or the hint runs to multiple lines and explains design rationale.
- You guessed wording for a change you do not understand instead of asking the user whether you may dig into the repo.
- Internal package source enters the CLI bundle, but `@moonshot-ai/kimi-code` is missing.
- Internal package source enters the CLI bundle, but `echadron` is missing.
- A changeset frontmatter mixes ignored internal packages with non-ignored packages.
- `packages/node-sdk` was not changed, but `@moonshot-ai/kimi-code-sdk` was listed for "internal package sync".
- The changelog entry is in Chinese.
- The wording claims more than the diff actually did.
- The CLI wording mentions internal package names, class names, or PR numbers.
- The entry includes real internal identifiers instead of neutral placeholders.
- A change that only touches `@moonshot-ai/pi-tui` lists `@moonshot-ai/kimi-code` instead of `@moonshot-ai/pi-tui`, or mixes both packages in one frontmatter.
- A change that only touches `@moonshot-ai/pi-tui` lists `echadron` instead of `@moonshot-ai/pi-tui`, or mixes both packages in one frontmatter.
- A web app change entry is missing the `web: ` prefix.
- A server/API changeset exists only to back a web feature that a `web:` changeset already describes (use one `web:` entry instead, unless the API has independent user value).
Loading
Loading