Skip to content

Commit a201c8c

Browse files
elkaixelkaix
committed
chore: initial commit
0 parents  commit a201c8c

2,082 files changed

Lines changed: 423091 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/gen-changesets/SKILL.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
---
2+
name: gen-changesets
3+
description: Use when generating changesets in the pythinker-code repository, including package bump selection, internal package and CLI bundle handling, bump levels, major confirmation, and English changelog wording.
4+
---
5+
6+
# Generate Changesets
7+
8+
`pythinker-code` uses changesets to manage versions and changelogs. The current user-facing published package is:
9+
10+
- `@pythoughts-ai/pythinker-code`: the CLI
11+
12+
All other `@pythoughts-ai/*` packages are treated as internal packages, including `@pythoughts-ai/pythinker-code-sdk`, `agent-core`, `kosong`, `kaos`, `pythinker-code-oauth`, `pythinker-telemetry`, and `migration-legacy`.
13+
14+
## Core Rules
15+
16+
1. **Inspect the actual changes first.** Use `git status` / `git diff --name-only` to identify which packages were actually changed.
17+
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.
18+
3. **Map ignored internal changes to the affected released package.** If an ignored internal package changes CLI output or behavior, list `@pythoughts-ai/pythinker-code` and describe the actual user-visible or release-artifact change in the changelog text.
19+
4. **Internal package source changes that enter the CLI bundle must manually list the CLI.** `@pythoughts-ai/pythinker-code` inline-bundles `@pythoughts-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, list `@pythoughts-ai/pythinker-code`.
20+
- **Web app (`@pythoughts-ai/pythinker-web`) changes always enter the CLI bundle.** `@pythoughts-ai/pythinker-web` is ignored by changesets (see `.changeset/config.json`) and cannot be mixed with `@pythoughts-ai/pythinker-code` in one changeset frontmatter. Describe the web change in the changelog text, but list `@pythoughts-ai/pythinker-code` so the CLI release carries the bundled `dist-web` output.
21+
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.
22+
6. `@pythoughts-ai/dashboard` / `dashboard-server` / `dashboard-web` are ignored by changesets and should not be handled.
23+
24+
## Workflow
25+
26+
1. List the changed packages and check whether each one is ignored by `.changeset/config.json`.
27+
2. Choose a bump level for each package.
28+
3. If an ignored internal package change enters the CLI bundle, put `@pythoughts-ai/pythinker-code` in frontmatter instead of mixing the ignored package into the same changeset.
29+
4. Create a short kebab-case file under `.changeset/`.
30+
5. Split unrelated changes into separate changesets; keep one logical change in one file.
31+
32+
Format:
33+
34+
```markdown
35+
---
36+
"<package A>": patch
37+
"<package B>": minor
38+
---
39+
40+
<English changelog entry>
41+
```
42+
43+
## Bump Levels
44+
45+
| Level | When to use |
46+
|---|---|
47+
| `patch` | Bug fixes; build/package fixes; internal refactors that do not change behavior; wording tweaks; small dependency upgrades |
48+
| `minor` | New backwards-compatible features or capabilities |
49+
| `major` | Breaking changes: incompatible config changes, renamed or removed commands/arguments, behavior semantics changes, and similar |
50+
51+
### Major Rule
52+
53+
Never write `major` on your own.
54+
55+
If you believe a change qualifies as major, stop first, explain why, and ask the user for confirmation. Only write `major` after the user explicitly agrees. If the user does not reply, replies ambiguously, or disagrees, fall back to `minor`; if `minor` is also unclear, fall back to `patch`.
56+
57+
## Wording Rules
58+
59+
- Changelog entries **must be written in English**.
60+
- **Keep it short — ideally a single sentence that states what was done.** Do not write a paragraph, do not pile on technical detail, and do not enumerate every sub-change.
61+
- User-facing CLI wording should only be used when CLI users can perceive the change.
62+
- Internal changes that do not affect CLI users can still share a changeset with the CLI, but the wording must describe the real change honestly and must not present it as a user-facing feature.
63+
- Do not mention file names, class names, function names, PR numbers, or commit hashes.
64+
- Do not include real internal endpoints, key names, account names, or service names. If an example is needed, use neutral placeholders such as `example.com`, `example.test`, or `YOUR_API_KEY`.
65+
- Avoid vague words such as `refactor`, `optimize`, and `improve`. Describe the actual change, or use more specific wording.
66+
67+
## Common Examples
68+
69+
An internal package fixes a bug visible to CLI users:
70+
71+
```markdown
72+
---
73+
"@pythoughts-ai/pythinker-code": patch
74+
---
75+
76+
Fix occasional loss of tool call results in long conversations.
77+
```
78+
79+
An internal package has an internal-only change, but it enters the CLI bundle:
80+
81+
```markdown
82+
---
83+
"@pythoughts-ai/pythinker-code": patch
84+
---
85+
86+
Unify tool execution metadata handling.
87+
```
88+
89+
Only SDK source changed, and the CLI does not use it:
90+
91+
```markdown
92+
---
93+
"@pythoughts-ai/pythinker-code-sdk": patch
94+
---
95+
96+
Clarify session status typing for internal SDK callers.
97+
```
98+
99+
## Web app changes
100+
101+
`@pythoughts-ai/pythinker-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 `@pythoughts-ai/pythinker-code` instead and describe the actual web-facing change in the text.
102+
103+
- If a PR contains both web UI changes and server API changes, split them into separate changesets so each entry has a focused description.
104+
- Do not enumerate every micro-tweak; keep it to one sentence that captures what the web user gets.
105+
106+
Web-only fix:
107+
108+
```markdown
109+
---
110+
"@pythoughts-ai/pythinker-code": patch
111+
---
112+
113+
Fix the web chat not scrolling to the bottom after sending a message.
114+
```
115+
116+
Web UI plus server APIs in the same PR (split into two changesets):
117+
118+
```markdown
119+
---
120+
"@pythoughts-ai/pythinker-code": minor
121+
---
122+
123+
Add the server-hosted web UI, including chat layout and session list behaviors.
124+
```
125+
126+
```markdown
127+
---
128+
"@pythoughts-ai/pythinker-code": minor
129+
---
130+
131+
Add the server REST and WebSocket APIs that power the web UI.
132+
```
133+
134+
## Red Flags
135+
136+
- You are about to write `major` without asking the user.
137+
- Internal package source enters the CLI bundle, but `@pythoughts-ai/pythinker-code` is missing.
138+
- A changeset frontmatter mixes ignored internal packages with non-ignored packages.
139+
- `packages/node-sdk` was not changed, but `@pythoughts-ai/pythinker-code-sdk` was listed for "internal package sync".
140+
- The changelog entry is in Chinese.
141+
- The wording claims more than the diff actually did.
142+
- The CLI wording mentions internal package names, class names, or PR numbers.
143+
- The entry includes real internal identifiers instead of neutral placeholders.

‎.agents/skills/gen-docs/SKILL.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
name: gen-docs
3+
description: Update Pythinker Code CLI user documentation after meaningful code changes that affect product behavior or user experience.
4+
---
5+
6+
# Gen Docs
7+
8+
## Overview
9+
10+
This repository maintains English user documentation under `docs/en/`.
11+
12+
Use this skill to update the corresponding documentation whenever the codebase has changes that affect product behavior or user experience.
13+
14+
For a **full pre-release audit** of all pages (detecting hallucinations and coverage gaps), use the `audit-docs` skill instead.
15+
16+
## Prerequisites
17+
18+
This skill depends on the following being in place. If any are missing, stop and report to the user before continuing:
19+
20+
- `docs/` directory with `docs/en/` and `docs/.vitepress/config.ts` set up (VitePress site).
21+
- `docs/AGENTS.md` style guide — defines terminology, typography, and writing style.
22+
- `docs/scripts/sync-changelog.mjs` — auto-syncs root `CHANGELOG.md` to `docs/en/release-notes/changelog.md`.
23+
24+
## Workflow
25+
26+
1. **Inspect changes**
27+
28+
- `git log main..HEAD --oneline` — commits on the current branch
29+
- `git diff main..HEAD --stat` — file-level scope
30+
- `ls .changeset/*.md` (excluding `README.md`) — pending changeset entries
31+
- Read `CHANGELOG.md` and any subpackage `packages/*/CHANGELOG.md` for already-recorded entries.
32+
33+
2. **Understand user-facing impact**
34+
35+
For each change, read the actual implementation when needed; **do not infer behavior from commit messages or PR titles alone**. Skip:
36+
37+
- Internal refactors with no externally visible behavior change
38+
- Tests, CI, type-only changes
39+
- Tooling / build-system changes that do not change how users invoke the CLI
40+
41+
If after the scan you conclude there is no user-facing impact, say so and stop.
42+
43+
3. **Sync English changelog**
44+
45+
Run:
46+
47+
```bash
48+
node docs/scripts/sync-changelog.mjs
49+
```
50+
51+
This updates `docs/en/release-notes/changelog.md` from the root `CHANGELOG.md`. Never edit the docs changelog by hand.
52+
53+
4. **Update user docs**
54+
55+
Following the rules in `docs/AGENTS.md`, edit the affected pages under `docs/en/`. Match terminology with the term table in `docs/AGENTS.md` and the existing wording in surrounding pages.
56+
57+
Cover all relevant sections:
58+
59+
- Guides (getting-started, use cases, interaction, sessions, IDE integration)
60+
- Customization (skills, agents, MCP, hooks, plugins, etc.)
61+
- Configuration (config files, env vars, providers, data locations)
62+
- Reference (CLI subcommands, slash commands, keyboard shortcuts)
63+
- Release notes (`docs/en/release-notes/breaking-changes.md` if a breaking change is involved)
64+
65+
## Rules and conventions
66+
67+
- **Terminology**: Use the term table in `docs/AGENTS.md` exactly. Do not invent synonyms.
68+
- **Scope discipline**: Only update sections affected by the recent changes. Do not opportunistically rewrite unrelated docs.
69+
- **Public examples**: Never write real internal endpoints, key names, account names, or service names into docs. Use neutral placeholders such as `https://api.example.com/v1`, `https://registry.example.com/v1/models/api.json`, `example.test`, and `YOUR_API_KEY`.
70+
- **Breaking changes**: If any change is breaking, also update `docs/en/release-notes/breaking-changes.md` (under `## Unreleased`) with `**Affected**` + `**Migration**` subsections.
71+
- **Do not edit auto-synced files**: `docs/en/release-notes/changelog.md` is regenerated by the sync script; any manual edit will be overwritten.
72+
73+
## Common mistakes
74+
75+
- Describing what code changed instead of what the user can now do (or can no longer do).
76+
- Adding a new section heading per feature instead of weaving the change into existing prose.

0 commit comments

Comments
 (0)