@zyaiting/keelson 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +36 -21
  2. package/README_CN.md +36 -21
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -4,15 +4,16 @@
4
4
  <p align="center">Project memory, engineering guidance, and acceptance checks for your coding agent. Describe the outcome; keep decisions and verification alongside the code.</p>
5
5
 
6
6
  <p align="center">
7
- <a href="README_CN.md">简体中文</a> ·
7
+ <a href="https://github.com/Atingaii/keelson/blob/main/README_CN.md">简体中文</a> ·
8
8
  <a href="#quick-start">Quick start</a> ·
9
- <a href="docs/README.md">Documentation</a> ·
10
- <a href="docs/platforms.md">Agent support</a>
9
+ <a href="https://github.com/Atingaii/keelson/blob/main/docs/README.md">Documentation</a> ·
10
+ <a href="https://github.com/Atingaii/keelson/blob/main/docs/platforms.md">Agent support</a>
11
11
  </p>
12
12
 
13
13
  <p align="center">
14
+ <a href="https://www.npmjs.com/package/@zyaiting/keelson"><img src="https://img.shields.io/npm/v/%40zyaiting%2Fkeelson" alt="npm version"></a>
14
15
  <a href="https://github.com/Atingaii/keelson/actions/workflows/ci.yml"><img src="https://github.com/Atingaii/keelson/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
15
- <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
16
+ <a href="https://github.com/Atingaii/keelson/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
16
17
  </p>
17
18
 
18
19
  <p align="center"><img src="https://raw.githubusercontent.com/Atingaii/keelson/main/docs/assets/keelson-demo.gif" alt="Real agent conversation replay: a task-filter request followed by implementation, verification, and archiving" width="100%"></p>
@@ -20,14 +21,23 @@
20
21
 
21
22
  ## Why Keelson?
22
23
 
23
- Coding agents can write code. Ongoing development also needs shared context, clear boundaries, and a reliable way to establish that work is done.
24
+ Keelson brings software engineering practices into everyday agent conversations: agree on the outcome, preserve the reasoning, and check the result. It addresses four recurring problems.
24
25
 
25
- | A familiar problem | How Keelson helps |
26
- | --- | --- |
27
- | Every new session starts with another project explanation | Goals, decisions, and unfinished work stay in the repository for the next session. |
28
- | Implementation starts before the request is understood | The agent reads existing code, defines acceptance, and asks about decisions that change the direction. |
29
- | The code is written, but completion is unclear | Check records track the inputs they verified, keeping implementation, verification, and completion distinct. |
30
- | The page works, but its design and interactions feel unfinished | Design guidance covers typography, color, feedback, responsive behavior, and accessibility, with browser acceptance. |
26
+ **1. The agent builds the wrong thing.**
27
+
28
+ “Add a filter” leaves room for different defaults, edge cases, and compatibility choices. Keelson guides the agent to inspect the code and turn the request into concrete acceptance examples before implementation. This applies **behaviour-driven development**: use examples to expose disagreement early, asking only about choices that affect the direction.
29
+
30
+ **2. Every session needs the same explanation.**
31
+
32
+ The next agent sees the code but may miss what “member” means or why an alternative was rejected. Keelson keeps domain terms, decisions, and unfinished work alongside the code. **Ubiquitous language** and **decision records** give later sessions shared vocabulary and reasons to work from, reducing repeated explanations.
33
+
34
+ **3. “Done” does not say what was checked.**
35
+
36
+ A passing test can miss the requested behaviour; an old result can describe old code. Keelson guides small implementation steps and acceptance review, and ties check records to the inputs they verified. **Short feedback loops** become a concrete completion gate: missing or stale verification blocks normal archiving.
37
+
38
+ **4. The page works, but using it feels rough.**
39
+
40
+ Unclear feedback, lost form input, and awkward mobile controls are usability problems. Keelson turns **usability heuristics** into guidance for hierarchy, interaction, responsive behaviour, and accessibility. The agent reviews the actual interface in a browser and checks real interactions, alongside code checks.
31
41
 
32
42
  Keelson combines an **Agent Skill + local CLI**. The skill guides the agent's work; the CLI manages project state and verification records. Use it for features, bug fixes, refactoring, and frontend improvements.
33
43
 
@@ -37,7 +47,7 @@ Keelson combines an **Agent Skill + local CLI**. The skill guides the agent's wo
37
47
  - A coding agent that can read project files, make changes, and run commands.
38
48
  - A local project directory; Git is recommended for tracking code and project knowledge.
39
49
 
40
- Keelson generates integrations for Codex, Claude Code, OpenCode, Gemini CLI, and other hosts. See [Agent support](docs/platforms.md) for capabilities and validation coverage.
50
+ Keelson generates integrations for Codex, Claude Code, OpenCode, Gemini CLI, and other hosts. See [Agent support](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md) for capabilities and validation coverage.
41
51
 
42
52
  ## Quick start
43
53
 
@@ -58,7 +68,7 @@ keelson init --codex
58
68
 
59
69
  > Add a priority filter to the task list: show everything by default, with an option for high-priority tasks only. Keep existing calls compatible, add tests, and verify the result.
60
70
 
61
- To upgrade, run `npm install -g @zyaiting/keelson@latest`, then `keelson update` in your project. See the [setup guide](docs/getting-started.md) and [supported agents](docs/platforms.md).
71
+ To upgrade, run `npm install -g @zyaiting/keelson@latest`, then `keelson update` in your project. See the [setup guide](https://github.com/Atingaii/keelson/blob/main/docs/getting-started.md) and [supported agents](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md).
62
72
 
63
73
  ## From request to completion
64
74
 
@@ -72,7 +82,7 @@ You can also ask:
72
82
  - **Improve an interface:** “Polish the settings page, keep our brand, preserve input when saving fails, and check the mobile flow.”
73
83
  - **Resume:** “Continue the previous change. First check what's left.”
74
84
 
75
- Frontend work has 22 composable [design actions](docs/frontend.md), discoverable with `keelson design`, including critique, simplification, polish, and adaptation. Checking the actual interface requires the agent to use a browser.
85
+ Frontend work has 22 composable [design actions](https://github.com/Atingaii/keelson/blob/main/docs/frontend.md), discoverable with `keelson design`, including critique, simplification, polish, and adaptation. Checking the actual interface requires the agent to use a browser.
76
86
 
77
87
  ## What stays in your project?
78
88
 
@@ -85,17 +95,22 @@ Initialization creates a small foundation. Further documents appear as the work
85
95
  | `.keelson/changes/`, `.keelson/specs/`, `.keelson/rules/` | Changes, behavior contracts, and project rules created as needed. |
86
96
  | Host entry points such as `AGENTS.md` | Direct the agent to Keelson. |
87
97
 
88
- Guidance comes from the installed package by default. Use `--vendor` when you want to commit a copy alongside your project. See [configuration](docs/configuration.md) for paths and options.
98
+ Guidance comes from the installed package by default. Use `--vendor` when you want to commit a copy alongside your project. See [configuration](https://github.com/Atingaii/keelson/blob/main/docs/configuration.md) for paths and options.
89
99
 
90
100
  ## Engineering principles
91
101
 
92
- - **Start with the problem.** Establish outcomes, constraints, and invariants before choosing mechanisms. Additional complexity must earn its place.
93
- - **Load and retain what matters.** Small edits move directly; larger work adds contracts and plans. Preserve knowledge the next change will need.
94
- - **Build through feedback.** Use small steps, independent review, and focused checks. Record test results separately from browser observations.
95
- - **Ground completion in evidence.** Check records are tied to verified inputs; changed code needs fresh verification. Ending a conversation does not finish a task.
102
+ The ideas above come from established engineering and interaction design practices. Keelson adapts them to repository work:
103
+
104
+ | Principle | How it appears in Keelson |
105
+ | --- | --- |
106
+ | [Behaviour-driven development](https://cucumber.io/docs/bdd/) | Describe observable behaviour with acceptance examples; use them to guide implementation and review. |
107
+ | [Ubiquitous language](https://martinfowler.com/bliki/UbiquitousLanguage.html), from domain-driven design | Keep project terms and code-name mappings in a glossary as needed, so conversation and code use the same meanings. |
108
+ | [Architecture decision records](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) | Keep concise decisions and trade-offs in the repository, with their context available to the next session. |
109
+ | [Small iterations and feedback](https://agilemanifesto.org/principles.html) | Build a working slice, check it, and adjust; keep small changes lightweight and add planning when complexity warrants it. |
110
+ | [Usability heuristics](https://www.nngroup.com/articles/ten-usability-heuristics/) | Review visible status, consistent language, error recovery, and user control through actual interface interactions. |
96
111
 
97
- Review commands in `.keelson/config.yaml` before their first execution. The agent runs and records checks with `keelson check --trust --record`; passing exit codes still need an acceptance review. See [verification and trust](docs/verification.md).
112
+ Review commands in `.keelson/config.yaml` before their first execution. The agent runs and records checks with `keelson check --trust --record`; passing exit codes still need an acceptance review. See [verification and trust](https://github.com/Atingaii/keelson/blob/main/docs/verification.md).
98
113
 
99
114
  ## Documentation and contributing
100
115
 
101
- [Documentation](docs/README.md) · [CLI reference](docs/cli.md) · [Frontend design](docs/frontend.md) · [Contributing](CONTRIBUTING.md) · [Report an issue](https://github.com/Atingaii/keelson/issues) · [MIT](LICENSE)
116
+ [Documentation](https://github.com/Atingaii/keelson/blob/main/docs/README.md) · [CLI reference](https://github.com/Atingaii/keelson/blob/main/docs/cli.md) · [Frontend design](https://github.com/Atingaii/keelson/blob/main/docs/frontend.md) · [Contributing](https://github.com/Atingaii/keelson/blob/main/CONTRIBUTING.md) · [Report an issue](https://github.com/Atingaii/keelson/issues) · [MIT](https://github.com/Atingaii/keelson/blob/main/LICENSE)
package/README_CN.md CHANGED
@@ -4,15 +4,16 @@
4
4
  <p align="center">为编码 Agent 提供项目记忆、工程方法和验收流程。你描述目标，Agent 推进实现，把决策与验证留在代码旁。</p>
5
5
 
6
6
  <p align="center">
7
- <a href="README.md">English</a> ·
7
+ <a href="https://github.com/Atingaii/keelson/blob/main/README.md">English</a> ·
8
8
  <a href="#快速开始">快速开始</a> ·
9
- <a href="docs/zh/README.md">文档</a> ·
10
- <a href="docs/platforms.md">Agent 支持</a>
9
+ <a href="https://github.com/Atingaii/keelson/blob/main/docs/zh/README.md">文档</a> ·
10
+ <a href="https://github.com/Atingaii/keelson/blob/main/docs/platforms.md">Agent 支持</a>
11
11
  </p>
12
12
 
13
13
  <p align="center">
14
+ <a href="https://www.npmjs.com/package/@zyaiting/keelson"><img src="https://img.shields.io/npm/v/%40zyaiting%2Fkeelson" alt="npm 版本"></a>
14
15
  <a href="https://github.com/Atingaii/keelson/actions/workflows/ci.yml"><img src="https://github.com/Atingaii/keelson/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
15
- <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
16
+ <a href="https://github.com/Atingaii/keelson/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
16
17
  </p>
17
18
 
18
19
  <p align="center"><img src="https://raw.githubusercontent.com/Atingaii/keelson/main/docs/assets/keelson-demo-zh.gif" alt="真实 Agent 对话回放：用户提出任务筛选需求，Agent 完成实现、验证与归档" width="100%"></p>
@@ -20,14 +21,23 @@
20
21
 
21
22
  ## 为什么选择 Keelson？
22
23
 
23
- 编码 Agent 能写代码，但长期开发还需要持续的上下文、明确的边界和可信的验收。
24
+ Keelson 将软件工程中的成熟做法带进日常 Agent 对话：先对齐结果，留下决策依据，再检查实际产出。它围绕四个常见问题展开。
24
25
 
25
- | 开发中遇到的问题 | Keelson 如何处理 |
26
- | --- | --- |
27
- | 换个会话，又要解释整个项目 | 将目标、决策和未完成工作保存在仓库，下次继续读取。 |
28
- | 需求说完就开写，结果偏离预期 | 先读现有实现，明确验收；只对影响方向的关键选择提问。 |
29
- | 代码写完了，却不知道是否真的完成 | 保存与当前代码对应的检查记录，区分实现、验证和完成。 |
30
- | 页面能用，却缺少设计与交互细节 | 提供设计指导，覆盖排版、配色、状态反馈、响应式和无障碍，并要求浏览器验收。 |
26
+ **1. Agent 做出来的，并不是你想要的。**
27
+
28
+ “加个筛选”背后，还有默认行为、边界情况和兼容性。Keelson 引导 Agent 先读代码，把需求变成具体的验收示例，再开始实现。这借鉴了**行为驱动开发（BDD）**：通过例子尽早发现理解偏差，只对影响方向的选择提问。
29
+
30
+ **2. 换个会话，又得解释同一个项目。**
31
+
32
+ 新 Agent 看得到代码，却未必知道“成员”的业务含义，也不知道某个方案为什么被否决。Keelson 将领域术语、决策和未完成工作留在仓库。**统一语言**与**决策记录**让后续会话沿用已有词汇和理由，减少重复解释。
33
+
34
+ **3. 说“完成了”，却不知道验证了什么。**
35
+
36
+ 测试通过可能没有覆盖原始需求，旧结果也可能对应旧代码。Keelson 引导小步实现、逐项验收，并将检查记录绑定到受检输入。**短反馈循环**由此落实到完成条件：验证缺失或过期时，正常归档会被阻止。
37
+
38
+ **4. 页面能用，但用起来不顺手。**
39
+
40
+ 反馈不清楚、保存失败丢输入、手机上操作别扭，都是可用性问题。Keelson 将**可用性启发式原则**转成层级、交互、响应式和无障碍指导，由 Agent 在浏览器中观察界面、实际操作，并结合代码检查验收。
31
41
 
32
42
  Keelson 由 **Agent Skill + 本地 CLI** 组成：Skill 指导 Agent 如何工作，CLI 管理项目状态与验证记录。适用于新功能、问题修复、重构和前端体验优化。
33
43
 
@@ -37,7 +47,7 @@ Keelson 由 **Agent Skill + 本地 CLI** 组成：Skill 指导 Agent 如何工
37
47
  - 一个能读取项目、修改文件并执行命令的编码 Agent。
38
48
  - 一个本地项目目录；建议使用 Git 管理代码和项目知识。
39
49
 
40
- 支持生成 Codex、Claude Code、OpenCode、Gemini CLI 等宿主的集成入口；各宿主的能力与验证范围见 [Agent 支持](docs/platforms.md)。
50
+ 支持生成 Codex、Claude Code、OpenCode、Gemini CLI 等宿主的集成入口；各宿主的能力与验证范围见 [Agent 支持](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md)。
41
51
 
42
52
  ## 快速开始
43
53
 
@@ -58,7 +68,7 @@ keelson init --codex --lang zh
58
68
 
59
69
  > 给任务列表加一个优先级筛选：默认显示全部，也能只看高优先级。保持现有调用兼容，补齐测试并完成验证。
60
70
 
61
- 升级 CLI：`npm install -g @zyaiting/keelson@latest`，然后在项目中运行 `keelson update`。更多设置见[上手教程](docs/zh/getting-started.md)；其他宿主见 [Agent 支持](docs/platforms.md)。
71
+ 升级 CLI：`npm install -g @zyaiting/keelson@latest`，然后在项目中运行 `keelson update`。更多设置见[上手教程](https://github.com/Atingaii/keelson/blob/main/docs/zh/getting-started.md)；其他宿主见 [Agent 支持](https://github.com/Atingaii/keelson/blob/main/docs/platforms.md)。
62
72
 
63
73
  ## 从一句需求到一次完成
64
74
 
@@ -72,7 +82,7 @@ Agent 按任务读取需要的指导，维护验收标准并执行项目检查
72
82
  - **改善界面：**“优化设置页，保留品牌风格，保存失败时不要丢输入，并检查手机端体验。”
73
83
  - **接着开发：**“继续上次的改动，先确认还剩什么。”
74
84
 
75
- 前端任务有 22 个可组合的[设计动作](docs/zh/frontend.md)，可通过 `keelson design` 查看，包括审视、简化、打磨和适配。实际界面效果需要 Agent 使用浏览器检查。
85
+ 前端任务有 22 个可组合的[设计动作](https://github.com/Atingaii/keelson/blob/main/docs/zh/frontend.md)，可通过 `keelson design` 查看，包括审视、简化、打磨和适配。实际界面效果需要 Agent 使用浏览器检查。
76
86
 
77
87
  ## 项目里会留下什么？
78
88
 
@@ -85,17 +95,22 @@ Agent 按任务读取需要的指导，维护验收标准并执行项目检查
85
95
  | `.keelson/changes/`、`.keelson/specs/`、`.keelson/rules/` | 按需建立的变更、行为契约和项目规则。 |
86
96
  | 宿主入口，如 `AGENTS.md` | 引导 Agent 加载 Keelson。 |
87
97
 
88
- 默认从已安装的包读取指导。需要把指导副本一并提交时，才使用 `--vendor`。目录与选项详见[配置文档](docs/zh/configuration.md)。
98
+ 默认从已安装的包读取指导。需要把指导副本一并提交时，才使用 `--vendor`。目录与选项详见[配置文档](https://github.com/Atingaii/keelson/blob/main/docs/zh/configuration.md)。
89
99
 
90
100
  ## 工程学原理
91
101
 
92
- - **从问题出发。** 先确认结果、约束和不变量，再选择技术方案；额外机制必须证明有用。
93
- - **按需加载，逐步沉淀。** 小改动直接推进，复杂任务补充契约与计划；只保留下一次开发需要的知识。
94
- - **用反馈推动实现。** 小步实现、独立审阅、针对性验证；测试结果与界面观察分别记录。
95
- - **让完成有证据。** 检查记录绑定受检输入，代码变化后需要重新验证；结束对话不等于完成任务。
102
+ 前面的做法来自已有的软件工程与交互设计知识。Keelson 将它们用于仓库中的具体工作：
103
+
104
+ | 原理 | 在 Keelson 中如何落地 |
105
+ | --- | --- |
106
+ | [行为驱动开发（BDD）](https://cucumber.io/docs/bdd/) | 用验收示例描述可观察的行为，指导实现和需求核对。 |
107
+ | 领域驱动设计中的[统一语言](https://martinfowler.com/bliki/UbiquitousLanguage.html) | 按需记录业务术语及代码名称映射，让对话和代码中的词含义一致。 |
108
+ | [架构决策记录（ADR）](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) | 在仓库保留简短决策与取舍，让后续会话理解当时的背景。 |
109
+ | [小步迭代与反馈](https://agilemanifesto.org/principles.html) | 先做出可工作的切片，检查后调整；小改动保持轻量，复杂时再补充计划。 |
110
+ | [可用性启发式原则](https://www.nngroup.com/articles/ten-usability-heuristics/) | 通过实际界面操作，检查状态是否可见、用词是否一致、错误能否恢复、用户能否掌控操作。 |
96
111
 
97
- 首次执行前应审阅 `.keelson/config.yaml` 中的检查命令。Agent 使用 `keelson check --trust --record` 运行并记录检查；退出码通过仍需对照验收标准。详见[验证与信任](docs/zh/verification.md)。
112
+ 首次执行前应审阅 `.keelson/config.yaml` 中的检查命令。Agent 使用 `keelson check --trust --record` 运行并记录检查；退出码通过仍需对照验收标准。详见[验证与信任](https://github.com/Atingaii/keelson/blob/main/docs/zh/verification.md)。
98
113
 
99
114
  ## 文档与参与
100
115
 
101
- [完整文档](docs/zh/README.md) · [命令参考](docs/zh/cli.md) · [前端设计](docs/zh/frontend.md) · [贡献指南](CONTRIBUTING.md) · [反馈问题](https://github.com/Atingaii/keelson/issues) · [MIT](LICENSE)
116
+ [完整文档](https://github.com/Atingaii/keelson/blob/main/docs/zh/README.md) · [命令参考](https://github.com/Atingaii/keelson/blob/main/docs/zh/cli.md) · [前端设计](https://github.com/Atingaii/keelson/blob/main/docs/zh/frontend.md) · [贡献指南](https://github.com/Atingaii/keelson/blob/main/CONTRIBUTING.md) · [反馈问题](https://github.com/Atingaii/keelson/issues) · [MIT](https://github.com/Atingaii/keelson/blob/main/LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zyaiting/keelson",
3
- "version": "0.4.0",
3
+ "version": "0.4.1",
4
4
  "description": "Local, verifiable check records and durable decisions for AI-assisted code changes.",
5
5
  "type": "module",
6
6
  "bin": {