@canons-dev/canons 0.1.0 → 0.1.2
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.
- package/README.md +23 -2
- package/README.zh-CN.md +23 -2
- package/doc/CHANGELOG.md +19 -0
- package/out/doctor.js +1 -1
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -13,6 +13,27 @@ Teams that use more than one coding agent end up with `AGENTS.md`, `CLAUDE.md`,
|
|
|
13
13
|
- **A shared baseline.** A managed block in `AGENTS.md` carries agent conventions (Git authority, verification, handoffs, documentation hygiene). Your project rules live outside the block.
|
|
14
14
|
- **Deterministic guards.** `canons check` catches hand-edited managed content, copies instead of links, broken rule links, an `AGENTS.override.md` that would make Codex skip `AGENTS.md`, and instruction chains over the 32 KiB Codex reads.
|
|
15
15
|
|
|
16
|
+
## Set up with your coding agent
|
|
17
|
+
|
|
18
|
+
Paste this into Codex, Claude Code or any other coding agent, from the root of your repository. Paste it again later to update: the same steps install canons the first time and update it afterwards.
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
Install or update canons (https://github.com/canons-dev/canons) in this repository. canons keeps coding-agent instructions in one place: AGENTS.md, .agents/rules/ and .agents/skills/.
|
|
22
|
+
|
|
23
|
+
1. Run `git status`. If there are uncommitted changes, list them and ask me before going on.
|
|
24
|
+
2. Check that Node 22 or newer is available. If the repository has no package.json, ask me before creating one.
|
|
25
|
+
3. Run `npm install --save-dev @canons-dev/canons@latest`.
|
|
26
|
+
4. If canons.json does not exist, run `npx canons init` (add `--locale zh-CN` only if I ask for Chinese rules). Otherwise run `npx canons sync`.
|
|
27
|
+
5. If the command stops:
|
|
28
|
+
- On a breaking upgrade: show me the entries in node_modules/@canons-dev/canons/doc/CHANGELOG.md between the old and new versions, and run `npx canons sync --accept-major` only after I agree.
|
|
29
|
+
- On hand edits to managed content: show me the edits. Do not pass `--force` unless I say so.
|
|
30
|
+
- Because CLAUDE.md, .claude/rules or .claude/skills is a real file or directory: move its content into AGENTS.md (outside the canons block), .agents/rules/ or .agents/skills/, then rerun. Ask me before deleting anything.
|
|
31
|
+
- Because your sandbox may not write to .agents/ (the Codex sandbox protects it): ask me to approve running the command outside the sandbox, or to run it myself.
|
|
32
|
+
6. Run `npx canons check` and fix what it reports.
|
|
33
|
+
7. Read the canons block in AGENTS.md and follow it from now on.
|
|
34
|
+
8. Change nothing beyond what these steps need. Summarize what changed (`git diff --stat`) and anything you need from me. Do not commit unless I ask.
|
|
35
|
+
```
|
|
36
|
+
|
|
16
37
|
## Quick start
|
|
17
38
|
|
|
18
39
|
Requires Node 22 or newer and a git repository.
|
|
@@ -52,7 +73,7 @@ npx canons scopes --changed # which rules apply to my diff?
|
|
|
52
73
|
| `canons sync [--accept-major] [--force]` | Update the managed block, managed rules, client links and lock. Refuses to overwrite hand edits unless `--force`; refuses breaking rule upgrades unless `--accept-major`. |
|
|
53
74
|
| `canons check [--strict]` | Deterministic checks; exit code 1 on errors (or on warnings with `--strict`). |
|
|
54
75
|
| `canons scopes [--changed] [--json] <path>...` | List the rules whose `paths` match. Rules without `paths` are global and always listed. |
|
|
55
|
-
| `canons doctor` | Environment hints (symlink support, Codex
|
|
76
|
+
| `canons doctor` | Environment hints (symlink support, Codex hooks, other clients). |
|
|
56
77
|
|
|
57
78
|
## Configuration
|
|
58
79
|
|
|
@@ -78,7 +99,7 @@ npx canons scopes --changed # which rules apply to my diff?
|
|
|
78
99
|
|
|
79
100
|
| Client | How it sees the instructions |
|
|
80
101
|
| --- | --- |
|
|
81
|
-
| Codex | Reads `AGENTS.md` from the repository root down to the working directory and `.agents/skills/` natively.
|
|
102
|
+
| Codex | Reads `AGENTS.md` from the repository root down to the working directory and `.agents/skills/` natively. |
|
|
82
103
|
| Claude Code | `CLAUDE.md -> AGENTS.md`, `.claude/rules -> ../.agents/rules`, `.claude/skills -> ../.agents/skills`; rules load natively by `paths`. |
|
|
83
104
|
| Cursor, GitHub Copilot | Read `AGENTS.md` natively. |
|
|
84
105
|
| Gemini CLI | Set `context.fileName` to `["AGENTS.md"]`. |
|
package/README.zh-CN.md
CHANGED
|
@@ -13,6 +13,27 @@
|
|
|
13
13
|
- **共享基线。** `AGENTS.md` 里的托管区块承载通用的 agent 约定(Git 授权、验证、交接、文档卫生)。项目自己的规则写在区块之外。
|
|
14
14
|
- **确定性守护。** `canons check` 能发现:托管内容被手改、用复制代替软链接、规则里的死链、会让 Codex 跳过 `AGENTS.md` 的 `AGENTS.override.md`,以及超出 Codex 读取上限(32 KiB)的指令链。
|
|
15
15
|
|
|
16
|
+
## 交给 coding agent 安装
|
|
17
|
+
|
|
18
|
+
在仓库根目录,把下面这段粘贴给 Codex、Claude Code 或其他 coding agent。以后再粘贴一次就是更新:同一套步骤第一次是安装,之后是升级。
|
|
19
|
+
|
|
20
|
+
```text
|
|
21
|
+
在这个仓库里安装或更新 canons(https://github.com/canons-dev/canons)。canons 把 coding agent 的指令集中在一处:AGENTS.md、.agents/rules/ 和 .agents/skills/。
|
|
22
|
+
|
|
23
|
+
1. 运行 `git status`。如果有未提交的改动,列出来并先问我再继续。
|
|
24
|
+
2. 确认有 Node 22 或更高版本。如果仓库里没有 package.json,先问我再创建。
|
|
25
|
+
3. 运行 `npm install --save-dev @canons-dev/canons@latest`。
|
|
26
|
+
4. 如果没有 canons.json,运行 `npx canons init --locale zh-CN`;否则运行 `npx canons sync`。
|
|
27
|
+
5. 如果命令停下来:
|
|
28
|
+
- 因为破坏性升级:把 node_modules/@canons-dev/canons/doc/CHANGELOG.md 里新旧版本之间的条目给我看,我同意后再运行 `npx canons sync --accept-major`。
|
|
29
|
+
- 因为托管内容被手改:把改动给我看。除非我说可以,不要加 `--force`。
|
|
30
|
+
- 因为 CLAUDE.md、.claude/rules 或 .claude/skills 是实体文件或目录:把内容移进 AGENTS.md(canons 区块之外)、.agents/rules/ 或 .agents/skills/,然后重跑。删除任何东西前先问我。
|
|
31
|
+
- 因为沙箱不允许写 .agents/(Codex 的沙箱会保护这个目录):请我批准在沙箱外运行该命令,或者由我自己运行。
|
|
32
|
+
6. 运行 `npx canons check`,修复它报告的问题。
|
|
33
|
+
7. 阅读 AGENTS.md 里的 canons 区块,此后照它执行。
|
|
34
|
+
8. 不要改动这些步骤以外的任何东西。总结改了什么(`git diff --stat`)以及需要我做什么。除非我要求,不要提交。
|
|
35
|
+
```
|
|
36
|
+
|
|
16
37
|
## 快速开始
|
|
17
38
|
|
|
18
39
|
需要 Node 22 及以上,并且在 git 仓库里运行。
|
|
@@ -52,7 +73,7 @@ npx canons scopes --changed # 我的改动适用哪些规则?
|
|
|
52
73
|
| `canons sync [--accept-major] [--force]` | 更新托管区块、托管规则、客户端软链接和 lock。默认拒绝覆盖手工修改(`--force` 才覆盖),拒绝破坏性的规则升级(`--accept-major` 才放行)。 |
|
|
53
74
|
| `canons check [--strict]` | 确定性检查;有 error 时退出码为 1(`--strict` 下 warning 也算失败)。 |
|
|
54
75
|
| `canons scopes [--changed] [--json] <路径>...` | 列出 `paths` 命中的规则。没有 `paths` 的规则是全局规则,始终列出。 |
|
|
55
|
-
| `canons doctor` | 环境提示(软链接支持、Codex
|
|
76
|
+
| `canons doctor` | 环境提示(软链接支持、Codex hooks、其他客户端)。 |
|
|
56
77
|
|
|
57
78
|
## 配置
|
|
58
79
|
|
|
@@ -78,7 +99,7 @@ npx canons scopes --changed # 我的改动适用哪些规则?
|
|
|
78
99
|
|
|
79
100
|
| 客户端 | 如何读到指令 |
|
|
80
101
|
| --- | --- |
|
|
81
|
-
| Codex | 原生从仓库根往下读到工作目录的各级 `AGENTS.md`,并读取 `.agents/skills
|
|
102
|
+
| Codex | 原生从仓库根往下读到工作目录的各级 `AGENTS.md`,并读取 `.agents/skills/`。 |
|
|
82
103
|
| Claude Code | `CLAUDE.md -> AGENTS.md`、`.claude/rules -> ../.agents/rules`、`.claude/skills -> ../.agents/skills`;规则按 `paths` 原生加载。 |
|
|
83
104
|
| Cursor、GitHub Copilot | 原生读取 `AGENTS.md`。 |
|
|
84
105
|
| Gemini CLI | 把 `context.fileName` 设为 `["AGENTS.md"]`。 |
|
package/doc/CHANGELOG.md
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.1.2 (2026-11-16)
|
|
4
|
+
|
|
5
|
+
- READMEs: a prompt to paste into a coding agent that installs or updates canons.
|
|
6
|
+
- The package now ships `doc/CHANGELOG.md`, so agents can read upgrade notes offline.
|
|
7
|
+
- `doctor` and the READMEs no longer claim that Codex skips `AGENTS.md` in an untrusted project: `codex exec` reads it either way.
|
|
8
|
+
|
|
9
|
+
## 0.1.1 (2026-11-16)
|
|
10
|
+
|
|
11
|
+
- Released through npm trusted publishing (OIDC). No changes to the CLI or rules.
|
|
12
|
+
|
|
13
|
+
## 0.1.0 (2026-11-16)
|
|
14
|
+
|
|
15
|
+
- Published as `@canons-dev/canons`; the command is `canons`.
|
|
16
|
+
|
|
17
|
+
- `canons init`, `sync`, `check`, `scopes`, `doctor`.
|
|
18
|
+
- Core rules: managed `AGENTS.md` block (C1–C15), `layout` (L1–L6) and `vendor` (V1–V4) path-scoped rules, in English and Simplified Chinese.
|
|
19
|
+
- Client adapters for Codex (native) and Claude Code (relative symlinks).
|
package/out/doctor.js
CHANGED
|
@@ -29,7 +29,7 @@ export function doctor(root) {
|
|
|
29
29
|
out.push(`fix ${error.message}`);
|
|
30
30
|
}
|
|
31
31
|
if (clients.includes("codex"))
|
|
32
|
-
out.push("note Codex
|
|
32
|
+
out.push("note Codex reads AGENTS.md from the repository root down to the working directory; no adapter needed.", "note Codex reads .agents/skills natively; no adapter needed.");
|
|
33
33
|
if (clients.includes("claude"))
|
|
34
34
|
out.push("note Claude Code loads .claude/rules recursively and honors only the `paths` frontmatter key; queries via `canons scopes` still apply.");
|
|
35
35
|
out.push("note Cursor and GitHub Copilot read AGENTS.md natively. For Gemini CLI set context.fileName to [\"AGENTS.md\"] in .gemini/settings.json.");
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@canons-dev/canons",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.2",
|
|
4
4
|
"description": "One source of truth for coding-agent instructions (AGENTS.md, path-scoped rules, skills) shared by Codex, Claude Code and other clients, with deterministic checks.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"type": "module",
|
|
@@ -12,7 +12,8 @@
|
|
|
12
12
|
"LICENSE",
|
|
13
13
|
"NOTICE",
|
|
14
14
|
"README.md",
|
|
15
|
-
"README.zh-CN.md"
|
|
15
|
+
"README.zh-CN.md",
|
|
16
|
+
"doc/CHANGELOG.md"
|
|
16
17
|
],
|
|
17
18
|
"engines": {
|
|
18
19
|
"node": ">=22"
|