@fenglimg/fabric-cli 1.8.0-rc.3 → 2.0.0-rc.8

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 (46) hide show
  1. package/README.md +6 -6
  2. package/dist/chunk-6ICJICVU.js +10 -0
  3. package/dist/chunk-74SZWYPH.js +658 -0
  4. package/dist/chunk-EYIDD2YS.js +1000 -0
  5. package/dist/{chunk-QPCRBQ5Y.js → chunk-OBQU6NHO.js} +1 -52
  6. package/dist/chunk-WWNXR34K.js +49 -0
  7. package/dist/doctor-T7JWODKG.js +282 -0
  8. package/dist/hooks-Y74Y5LQS.js +12 -0
  9. package/dist/index.js +7 -5
  10. package/dist/{init-7EYGUJNJ.js → init-55WZSUK6.js} +312 -1022
  11. package/dist/plan-context-hint-QMUPAXIB.js +98 -0
  12. package/dist/scan-LMK3UCWL.js +22 -0
  13. package/dist/{serve-466QXQ5Q.js → serve-H554BHLG.js} +8 -4
  14. package/package.json +3 -3
  15. package/templates/agents-md/AGENTS.md.template +55 -17
  16. package/templates/bootstrap/CLAUDE.md +1 -1
  17. package/templates/bootstrap/codex-AGENTS-header.md +1 -1
  18. package/templates/bootstrap/cursor-fabric-bootstrap.mdc +1 -1
  19. package/templates/hooks/configs/README.md +73 -0
  20. package/templates/hooks/configs/claude-code.json +37 -0
  21. package/templates/hooks/configs/codex-hooks.json +20 -0
  22. package/templates/hooks/configs/cursor-hooks.json +20 -0
  23. package/templates/hooks/fabric-hint.cjs +1307 -0
  24. package/templates/hooks/knowledge-hint-broad.cjs +464 -0
  25. package/templates/hooks/knowledge-hint-narrow.cjs +826 -0
  26. package/templates/hooks/lib/session-digest-writer.cjs +172 -0
  27. package/templates/skills/fabric-archive/SKILL.md +486 -0
  28. package/templates/skills/fabric-import/SKILL.md +588 -0
  29. package/templates/skills/fabric-review/SKILL.md +382 -0
  30. package/dist/chunk-NMMUETVK.js +0 -216
  31. package/dist/doctor-F52XWWZC.js +0 -98
  32. package/dist/scan-NNBNGIZG.js +0 -12
  33. package/templates/agents-md/variants/cocos.md +0 -20
  34. package/templates/agents-md/variants/next.md +0 -20
  35. package/templates/agents-md/variants/vite.md +0 -20
  36. package/templates/bootstrap/GEMINI.md +0 -8
  37. package/templates/bootstrap/roo-fabric.md +0 -5
  38. package/templates/bootstrap/windsurf-fabric.md +0 -5
  39. package/templates/claude-hooks/fabric-init-reminder.cjs +0 -18
  40. package/templates/claude-skills/fabric-init/SKILL.md +0 -163
  41. package/templates/codex-hooks/fabric-session-start.cjs +0 -19
  42. package/templates/codex-hooks/fabric-stop-reminder.cjs +0 -18
  43. package/templates/codex-skills/fabric-init/SKILL.md +0 -162
  44. package/templates/husky/pre-commit +0 -9
  45. package/templates/skill-source/fabric-init/SOURCE.md +0 -157
  46. package/templates/skill-source/fabric-init/clients.json +0 -17
@@ -1,98 +0,0 @@
1
- #!/usr/bin/env node
2
- import {
3
- paint,
4
- resolveDevMode,
5
- symbol,
6
- t
7
- } from "./chunk-QPCRBQ5Y.js";
8
-
9
- // src/commands/doctor.ts
10
- import { defineCommand } from "citty";
11
- import { checkLockOrThrow, runDoctorFix, runDoctorReport } from "@fenglimg/fabric-server";
12
- var doctorCommand = defineCommand({
13
- meta: {
14
- name: "doctor",
15
- description: t("cli.doctor.description")
16
- },
17
- args: {
18
- target: {
19
- type: "string",
20
- description: t("cli.doctor.args.target.description")
21
- },
22
- fix: {
23
- type: "boolean",
24
- description: t("cli.doctor.args.fix.description"),
25
- default: false
26
- },
27
- json: {
28
- type: "boolean",
29
- description: t("cli.doctor.args.json.description"),
30
- default: false
31
- },
32
- strict: {
33
- type: "boolean",
34
- description: t("cli.doctor.args.strict.description"),
35
- default: false
36
- },
37
- force: {
38
- type: "boolean",
39
- description: t("cli.doctor.args.force.description"),
40
- default: false
41
- }
42
- },
43
- async run({ args }) {
44
- const workspaceRoot = process.cwd();
45
- const resolution = resolveDevMode(args.target, workspaceRoot);
46
- checkLockOrThrow(resolution.target, { force: args.force });
47
- const fixReport = args.fix === true ? await runDoctorFix(resolution.target) : null;
48
- const report = fixReport?.report ?? await runDoctorReport(resolution.target);
49
- if (args.json === true) {
50
- writeStdout(JSON.stringify(fixReport ?? report, null, 2));
51
- } else {
52
- if (fixReport !== null) {
53
- writeStdout(fixReport.message);
54
- }
55
- renderHumanReport(report);
56
- }
57
- if (report.status === "error" || args.strict === true && (report.status === "warn" || report.warnings.length > 0)) {
58
- process.exitCode = 1;
59
- }
60
- }
61
- });
62
- var doctor_default = doctorCommand;
63
- function renderHumanReport(report) {
64
- writeStdout(`${renderStatus(report.status)} ${paint.ai("fabric doctor")} ${paint.human(report.summary.target)}`);
65
- for (const check of report.checks) {
66
- writeStdout(`${renderStatus(check.status)} ${check.name}: ${check.message}`);
67
- }
68
- writeIssueSection(t("doctor.section.fixable"), report.fixable_errors);
69
- writeIssueSection(t("doctor.section.manual"), report.manual_errors);
70
- writeIssueSection(t("doctor.section.warnings"), report.warnings);
71
- }
72
- function writeIssueSection(title, issues) {
73
- if (issues.length === 0) {
74
- return;
75
- }
76
- writeStdout("");
77
- writeStdout(title);
78
- for (const issue of issues) {
79
- writeStdout(`- ${issue.code}: ${issue.message}`);
80
- }
81
- }
82
- function renderStatus(status) {
83
- if (status === "ok") {
84
- return symbol.ok;
85
- }
86
- if (status === "warn") {
87
- return symbol.warn;
88
- }
89
- return symbol.error;
90
- }
91
- function writeStdout(message) {
92
- process.stdout.write(`${message}
93
- `);
94
- }
95
- export {
96
- doctor_default as default,
97
- doctorCommand
98
- };
@@ -1,12 +0,0 @@
1
- #!/usr/bin/env node
2
- import {
3
- createScanReport,
4
- scanCommand,
5
- scan_default
6
- } from "./chunk-NMMUETVK.js";
7
- import "./chunk-QPCRBQ5Y.js";
8
- export {
9
- createScanReport,
10
- scan_default as default,
11
- scanCommand
12
- };
@@ -1,20 +0,0 @@
1
- # { projectName } — Fabric Bootstrap Protocol
2
-
3
- ## CORE RULES (DO NOT TRANSLATE)
4
-
5
- MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
6
- MUST: Treat `.fabric/rules/` as the source of truth for all Fabric rule bodies.
7
- MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_rule_sections`.
8
- MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
9
- MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/rules/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_rule_sections`, `rule sources`, `rule source mirroring`, `MUST`, `NEVER`.
10
- NEVER: Add import-style directive lines to this bootstrap file.
11
- NEVER: Put Cocos, asset, prefab, scene, repository rule bodies, or submodule rules in this file.
12
- NEVER: Create colocated `AGENTS.md` rule files under source directories.
13
-
14
- ## 使用说明 / Explanation
15
-
16
- - 本文件只负责启动 Fabric Bootstrap Protocol,不承载 Cocos 业务或编辑器规则。
17
- - Detected framework kind: `cocos-creator`.
18
- - This repository uses `rule source mirroring`: source directories contain ZERO rule files, while `.fabric/rules/` mirrors source paths for AI constraints.
19
- - 根级规则应放在 `.fabric/rules/root.md`;跨领域规则应放在 `.fabric/rules/_cross/`。
20
- - If `.fabric/rules/root.md` is missing, continue with the Fabric initialization flow before normal coding.
@@ -1,20 +0,0 @@
1
- # { projectName } — Fabric Bootstrap Protocol
2
-
3
- ## CORE RULES (DO NOT TRANSLATE)
4
-
5
- MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
6
- MUST: Treat `.fabric/rules/` as the source of truth for all Fabric rule bodies.
7
- MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_rule_sections`.
8
- MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
9
- MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/rules/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_rule_sections`, `rule sources`, `rule source mirroring`, `MUST`, `NEVER`.
10
- NEVER: Add import-style directive lines to this bootstrap file.
11
- NEVER: Put Next.js, route, repository rule bodies, or submodule rules in this file.
12
- NEVER: Create colocated `AGENTS.md` rule files under source directories.
13
-
14
- ## 使用说明 / Explanation
15
-
16
- - 本文件只负责启动 Fabric Bootstrap Protocol,不承载 Next.js 业务或路由规则。
17
- - Detected framework kind: `next`.
18
- - This repository uses `rule source mirroring`: source directories contain ZERO rule files, while `.fabric/rules/` mirrors source paths for AI constraints.
19
- - 根级规则应放在 `.fabric/rules/root.md`;跨领域规则应放在 `.fabric/rules/_cross/`。
20
- - If `.fabric/rules/root.md` is missing, continue with the Fabric initialization flow before normal coding.
@@ -1,20 +0,0 @@
1
- # { projectName } — Fabric Bootstrap Protocol
2
-
3
- ## CORE RULES (DO NOT TRANSLATE)
4
-
5
- MUST: Treat this file as the Fabric Protocol bootstrap for this repository.
6
- MUST: Treat `.fabric/rules/` as the source of truth for all Fabric rule bodies.
7
- MUST: Before ANY code reading, architecture planning, or logic modification, call `fab_plan_context(paths=[<target file>])`, then call `fab_get_rule_sections`.
8
- MUST: When creating or changing an L1/L2 rule node, keep `.fabric/agents.meta.json` synchronized through Fabric tooling.
9
- MUST: Preserve protected tokens exactly: `AGENTS.md`, `.fabric/rules/`, `.fabric/agents.meta.json`, `fab_plan_context`, `fab_get_rule_sections`, `rule sources`, `rule source mirroring`, `MUST`, `NEVER`.
10
- NEVER: Add import-style directive lines to this bootstrap file.
11
- NEVER: Put Vite, browser, repository rule bodies, or submodule rules in this file.
12
- NEVER: Create colocated `AGENTS.md` rule files under source directories.
13
-
14
- ## 使用说明 / Explanation
15
-
16
- - 本文件只负责启动 Fabric Bootstrap Protocol,不承载 Vite 业务或浏览器规则。
17
- - Detected framework kind: `vite`.
18
- - This repository uses `rule source mirroring`: source directories contain ZERO rule files, while `.fabric/rules/` mirrors source paths for AI constraints.
19
- - 根级规则应放在 `.fabric/rules/root.md`;跨领域规则应放在 `.fabric/rules/_cross/`。
20
- - If `.fabric/rules/root.md` is missing, continue with the Fabric initialization flow before normal coding.
@@ -1,8 +0,0 @@
1
- # Fabric Bootstrap
2
- - 主说明文档已收敛到 `.fabric/bootstrap/README.md`。
3
- - 项目级 bootstrap 入口仍然是 `AGENTS.md`。
4
- - 修改任何文件前必须调用 `fab_plan_context(paths=[<被改文件>])`,再调用 `fab_get_rule_sections` 获取规则段落。
5
- MCP 和 doctor 会写入 `.fabric/events.jsonl`。
6
- - 规则 baseline 变更通过 `fabric doctor --fix` 接受。
7
-
8
- @AGENTS.md
@@ -1,5 +0,0 @@
1
- # Fabric Bootstrap
2
- - 本项目使用 Fabric Protocol 管理规则。
3
- - **任何文件修改前**,必须先调 MCP tool `fab_plan_context(paths=[<被改文件>])`,再调 `fab_get_rule_sections` 获取规则段落。
4
- - 新建或调整 L1/L2 节点时,修改规则源文件后运行 `fabric doctor --fix` 接受 baseline,**严禁**直接编辑 `.fabric/agents.meta.json`。
5
- Fabric 会把 MCP 和 doctor 行为写入 `.fabric/events.jsonl`。
@@ -1,5 +0,0 @@
1
- # Fabric Bootstrap
2
- - 本项目使用 Fabric Protocol 管理规则。
3
- - **任何文件修改前**,必须先调 MCP tool `fab_plan_context(paths=[<被改文件>])`,再调 `fab_get_rule_sections` 获取规则段落。
4
- - 新建或调整 L1/L2 节点时,修改规则源文件后运行 `fabric doctor --fix` 接受 baseline,**严禁**直接编辑 `.fabric/agents.meta.json`。
5
- Fabric 会把 MCP 和 doctor 行为写入 `.fabric/events.jsonl`。
@@ -1,18 +0,0 @@
1
- #!/usr/bin/env node
2
- const { existsSync } = require("node:fs");
3
- const { join } = require("node:path");
4
-
5
- const forensicPath = join(process.cwd(), ".fabric", "forensic.json");
6
- const initContextPath = join(process.cwd(), ".fabric", "init-context.json");
7
-
8
- if (!existsSync(forensicPath) || existsSync(initContextPath)) {
9
- process.exit(0);
10
- }
11
-
12
- process.stdout.write(
13
- JSON.stringify({
14
- decision: "block",
15
- reason:
16
- "fab init 已完成证据收集,但项目 AGENTS.md 初始化尚未完成。调用 fabric-init skill (通过 Skill 工具) 完成 3 阶段初始化访谈。参考: .claude/skills/fabric-init/SKILL.md + .fabric/forensic.json",
17
- }),
18
- );
@@ -1,163 +0,0 @@
1
- ---
2
- name: fabric-init
3
- description: Use this skill when fab init just completed, when forensic.json was generated, or when the user is asking to initialize AGENTS.md. This skill runs a 3-phase initialization interview, writes .fabric/init-context.json, generates layered AGENTS.md, and updates .fabric/agents.meta.json.
4
- allowed-tools: ["Read", "Write", "Glob", "Grep", "Bash"]
5
- ---
6
-
7
- # fabric-init — Canonical Skill Source
8
-
9
- > This file is the single source of truth for the fabric-init skill.
10
- > Do NOT edit the per-client SKILL.md files directly.
11
- > Run `packages/cli/scripts/derive-skills.ts` to regenerate them from this source.
12
-
13
- ## Precondition
14
-
15
- MUST: Read `.fabric/forensic.json` before taking any other action. If the file does not
16
- exist, stop immediately and tell the user: run `fab init` first to generate the evidence
17
- package.
18
-
19
- MUST: Check `.fabric/init-context.json`. If it already exists, stop and report that this
20
- repository appears to have completed initialization already.
21
-
22
- MUST: Treat `.fabric/bootstrap/README.md` as the authoritative initialization guide for
23
- the current repository.
24
-
25
- MUST: Use `.fabric/forensic.json` and repository structure as evidence when deciding what
26
- to do next.
27
-
28
- MUST: Preserve protected tokens exactly as written — see the Protected Tokens section.
29
-
30
- NEVER: Claim initialization is complete without having checked `.fabric/init-context.json`.
31
-
32
- NEVER: Rewrite or translate protected tokens.
33
-
34
- NEVER: Ignore `.fabric/bootstrap/README.md` when determining the next initialization step.
35
-
36
- Treat the following state as initialization pending:
37
-
38
- - `.fabric/forensic.json` exists
39
- - `.fabric/init-context.json` does not exist
40
-
41
- ## Execution Flow — 3 Phases / 3 Rounds
42
-
43
- ### Phase 1 — Framework Confirmation (1 round, efficient)
44
-
45
- Display a summary of `framework`, `topology.by_ext`, and `entry_points` from
46
- `.fabric/forensic.json`. Ask the user 1–2 clarifying questions about the framework
47
- architecture.
48
-
49
- Example (Cocos Creator 3.x):
50
-
51
- > I detected a Cocos Creator 3.8 project. Main scripts are in `assets/scripts` using the
52
- > `@ccclass + extends Component` pattern. Please confirm: (1) Is this a TypeScript project
53
- > (not JavaScript)? (2) Are node references injected mainly via `@property(Node)`, or via
54
- > `find/getChildByName`?
55
-
56
- Store the user's answers as verified framework assumptions before proceeding to Phase 2.
57
-
58
- ### Phase 2 — Invariant Extraction (1 round, critical)
59
-
60
- Based on the `recommendations_for_skill` list in `.fabric/forensic.json`, ask the user
61
- 3–5 invariant questions covering three categories:
62
-
63
- - `ban`: things that must never appear — e.g. `any`, `async` in `update()`, find-by-name
64
- - `require`: things that must always be present — e.g. strict TypeScript, `@ccclass`
65
- decorator, imports only from `cc`
66
- - `protect`: directories or files that AI must not modify — typically
67
- `assets/prefabs/**`, `assets/scenes/**`, `**/*.meta`
68
-
69
- Principles:
70
-
71
- - Ask only about invariants, not about preferences.
72
- - Each question accepts only yes / no / a concrete rule — never accept vague answers.
73
- - Do not auto-infer hard constraints the user has not confirmed.
74
-
75
- ### Phase 3 — Construction and Landing (1 round, automated)
76
-
77
- #### 3.1 Write `.fabric/init-context.json`
78
-
79
- Fields required:
80
-
81
- - `framework`
82
- - `architecture_patterns`
83
- - `invariants`
84
- - `domain_groups`
85
- - `interview_trail`
86
- - `forensic_ref`
87
-
88
- Writing rules:
89
-
90
- - `invariants[].type` MUST be one of `ban`, `require`, `protect`.
91
- - `domain_groups` is inferred from `entry_points` and interview results.
92
- - `interview_trail[]` MUST record the raw Q&A from Phase 1 and Phase 2.
93
- - `forensic_ref` MUST be `.fabric/forensic.json`.
94
-
95
- #### 3.2 Generate layered `AGENTS.md`
96
-
97
- Root `AGENTS.md` requirements:
98
-
99
- - MUST be within 300 lines.
100
- - Structure:
101
- - `# {projectName} — L0 AGENTS.md`
102
- - `<!-- fab:index -->`: populated with the `domain_groups` index
103
- - `## L0 AI Constraints`: derived from invariants, grouped by `ban`, `require`, `protect`
104
- - `## @HUMAN`: protect paths and any human-declared protection rules
105
- - `## L1 Candidate Notes`: candidate sub-module descriptions for each domain group
106
-
107
- If `domain_groups.length >= 2`, generate a `{group_path}/AGENTS.md` for each group.
108
- Maximum depth is L3; total nesting MUST NOT exceed 4 levels.
109
-
110
- #### 3.3 Update `.fabric/agents.meta.json`
111
-
112
- - The `nodes` tree MUST match the generated AGENTS hierarchy.
113
- - Update the hash of every AGENTS.md file that was written.
114
- - Maintain a consistent internal revision hash chain.
115
-
116
- #### 3.4 Final output
117
-
118
- List all generated files for the user and recommend running `fabric doctor --fix` for
119
- ongoing maintenance.
120
-
121
- ## Hard Rules
122
-
123
- - Zero TODO: never generate `TODO`, `TBD`, placeholders, or stubs in output files.
124
- - No YAML frontmatter in outputs: generated `AGENTS.md` files MUST NOT contain YAML
125
- frontmatter.
126
- - Root `AGENTS.md` MUST be <= 300 lines.
127
- - Total AGENTS nesting MUST be <= 4 levels.
128
- - Do not auto-infer invariants the user has not confirmed.
129
- - When content is uncertain, omit it — do not leave placeholders.
130
-
131
- ## Output Contract
132
-
133
- On successful completion the following files exist or are updated:
134
-
135
- | File | Action |
136
- |------|--------|
137
- | `.fabric/init-context.json` | Created with all required fields |
138
- | `AGENTS.md` | Created (root L0) |
139
- | `{group_path}/AGENTS.md` | Created for each domain group (when applicable) |
140
- | `.fabric/agents.meta.json` | Updated nodes tree + hashes |
141
-
142
- On failure or early termination the skill MUST leave no partial files. If a write fails
143
- mid-sequence, report the failure and the exact file that was not written.
144
-
145
- ## Protected Tokens
146
-
147
- The following tokens MUST be preserved exactly as shown — same casing, same punctuation,
148
- never translated:
149
-
150
- | Token | Type |
151
- |-------|------|
152
- | `AGENTS.md` | Filename |
153
- | `FABRIC.md` | Filename |
154
- | `.fabric/agents.meta.json` | Path |
155
- | `.fabric/init-context.json` | Path |
156
- | `.fabric/forensic.json` | Path |
157
- | `.fabric/bootstrap/README.md` | Path |
158
- | `MUST` | Keyword |
159
- | `NEVER` | Keyword |
160
- | `fab init` | CLI command |
161
- | `fabric doctor --fix` | CLI command |
162
- | `<!-- fab:index -->` | HTML comment marker |
163
- | `@HUMAN` | Section marker |
@@ -1,19 +0,0 @@
1
- #!/usr/bin/env node
2
- const { existsSync } = require("node:fs");
3
- const { join } = require("node:path");
4
-
5
- const forensicPath = join(process.cwd(), ".fabric", "forensic.json");
6
- const initContextPath = join(process.cwd(), ".fabric", "init-context.json");
7
-
8
- if (!existsSync(forensicPath) || existsSync(initContextPath)) {
9
- process.exit(0);
10
- }
11
-
12
- process.stdout.write(
13
- JSON.stringify({
14
- hookSpecificOutput: {
15
- additionalContext:
16
- "这个仓库的 Fabric 初始化还没完成。继续操作前,请先查看 .fabric/forensic.json 和 .fabric/bootstrap/README.md,并使用仓库内的 .codex/skills/fabric-init/SKILL.md。若 Codex hooks 没有触发,请确认配置里已启用 features.codex_hooks = true。",
17
- },
18
- }),
19
- );
@@ -1,18 +0,0 @@
1
- #!/usr/bin/env node
2
- const { existsSync } = require("node:fs");
3
- const { join } = require("node:path");
4
-
5
- const forensicPath = join(process.cwd(), ".fabric", "forensic.json");
6
- const initContextPath = join(process.cwd(), ".fabric", "init-context.json");
7
-
8
- if (!existsSync(forensicPath) || existsSync(initContextPath)) {
9
- process.exit(0);
10
- }
11
-
12
- process.stdout.write(
13
- JSON.stringify({
14
- decision: "block",
15
- reason:
16
- "fab init 已经收集完当前仓库的初始化依据,但后续初始化还没完成。请先确认 Codex 已启用 features.codex_hooks = true,然后查看 .fabric/forensic.json 和 .fabric/bootstrap/README.md,并使用仓库内的 .codex/skills/fabric-init/SKILL.md 继续初始化。",
17
- }),
18
- );
@@ -1,162 +0,0 @@
1
- ---
2
- name: fabric-init
3
- description: Use this skill when .fabric/forensic.json exists and this repository still needs the remaining Fabric initialization steps.
4
- ---
5
-
6
- # fabric-init — Canonical Skill Source
7
-
8
- > This file is the single source of truth for the fabric-init skill.
9
- > Do NOT edit the per-client SKILL.md files directly.
10
- > Run `packages/cli/scripts/derive-skills.ts` to regenerate them from this source.
11
-
12
- ## Precondition
13
-
14
- MUST: Read `.fabric/forensic.json` before taking any other action. If the file does not
15
- exist, stop immediately and tell the user: run `fab init` first to generate the evidence
16
- package.
17
-
18
- MUST: Check `.fabric/init-context.json`. If it already exists, stop and report that this
19
- repository appears to have completed initialization already.
20
-
21
- MUST: Treat `.fabric/bootstrap/README.md` as the authoritative initialization guide for
22
- the current repository.
23
-
24
- MUST: Use `.fabric/forensic.json` and repository structure as evidence when deciding what
25
- to do next.
26
-
27
- MUST: Preserve protected tokens exactly as written — see the Protected Tokens section.
28
-
29
- NEVER: Claim initialization is complete without having checked `.fabric/init-context.json`.
30
-
31
- NEVER: Rewrite or translate protected tokens.
32
-
33
- NEVER: Ignore `.fabric/bootstrap/README.md` when determining the next initialization step.
34
-
35
- Treat the following state as initialization pending:
36
-
37
- - `.fabric/forensic.json` exists
38
- - `.fabric/init-context.json` does not exist
39
-
40
- ## Execution Flow — 3 Phases / 3 Rounds
41
-
42
- ### Phase 1 — Framework Confirmation (1 round, efficient)
43
-
44
- Display a summary of `framework`, `topology.by_ext`, and `entry_points` from
45
- `.fabric/forensic.json`. Ask the user 1–2 clarifying questions about the framework
46
- architecture.
47
-
48
- Example (Cocos Creator 3.x):
49
-
50
- > I detected a Cocos Creator 3.8 project. Main scripts are in `assets/scripts` using the
51
- > `@ccclass + extends Component` pattern. Please confirm: (1) Is this a TypeScript project
52
- > (not JavaScript)? (2) Are node references injected mainly via `@property(Node)`, or via
53
- > `find/getChildByName`?
54
-
55
- Store the user's answers as verified framework assumptions before proceeding to Phase 2.
56
-
57
- ### Phase 2 — Invariant Extraction (1 round, critical)
58
-
59
- Based on the `recommendations_for_skill` list in `.fabric/forensic.json`, ask the user
60
- 3–5 invariant questions covering three categories:
61
-
62
- - `ban`: things that must never appear — e.g. `any`, `async` in `update()`, find-by-name
63
- - `require`: things that must always be present — e.g. strict TypeScript, `@ccclass`
64
- decorator, imports only from `cc`
65
- - `protect`: directories or files that AI must not modify — typically
66
- `assets/prefabs/**`, `assets/scenes/**`, `**/*.meta`
67
-
68
- Principles:
69
-
70
- - Ask only about invariants, not about preferences.
71
- - Each question accepts only yes / no / a concrete rule — never accept vague answers.
72
- - Do not auto-infer hard constraints the user has not confirmed.
73
-
74
- ### Phase 3 — Construction and Landing (1 round, automated)
75
-
76
- #### 3.1 Write `.fabric/init-context.json`
77
-
78
- Fields required:
79
-
80
- - `framework`
81
- - `architecture_patterns`
82
- - `invariants`
83
- - `domain_groups`
84
- - `interview_trail`
85
- - `forensic_ref`
86
-
87
- Writing rules:
88
-
89
- - `invariants[].type` MUST be one of `ban`, `require`, `protect`.
90
- - `domain_groups` is inferred from `entry_points` and interview results.
91
- - `interview_trail[]` MUST record the raw Q&A from Phase 1 and Phase 2.
92
- - `forensic_ref` MUST be `.fabric/forensic.json`.
93
-
94
- #### 3.2 Generate layered `AGENTS.md`
95
-
96
- Root `AGENTS.md` requirements:
97
-
98
- - MUST be within 300 lines.
99
- - Structure:
100
- - `# {projectName} — L0 AGENTS.md`
101
- - `<!-- fab:index -->`: populated with the `domain_groups` index
102
- - `## L0 AI Constraints`: derived from invariants, grouped by `ban`, `require`, `protect`
103
- - `## @HUMAN`: protect paths and any human-declared protection rules
104
- - `## L1 Candidate Notes`: candidate sub-module descriptions for each domain group
105
-
106
- If `domain_groups.length >= 2`, generate a `{group_path}/AGENTS.md` for each group.
107
- Maximum depth is L3; total nesting MUST NOT exceed 4 levels.
108
-
109
- #### 3.3 Update `.fabric/agents.meta.json`
110
-
111
- - The `nodes` tree MUST match the generated AGENTS hierarchy.
112
- - Update the hash of every AGENTS.md file that was written.
113
- - Maintain a consistent internal revision hash chain.
114
-
115
- #### 3.4 Final output
116
-
117
- List all generated files for the user and recommend running `fabric doctor --fix` for
118
- ongoing maintenance.
119
-
120
- ## Hard Rules
121
-
122
- - Zero TODO: never generate `TODO`, `TBD`, placeholders, or stubs in output files.
123
- - No YAML frontmatter in outputs: generated `AGENTS.md` files MUST NOT contain YAML
124
- frontmatter.
125
- - Root `AGENTS.md` MUST be <= 300 lines.
126
- - Total AGENTS nesting MUST be <= 4 levels.
127
- - Do not auto-infer invariants the user has not confirmed.
128
- - When content is uncertain, omit it — do not leave placeholders.
129
-
130
- ## Output Contract
131
-
132
- On successful completion the following files exist or are updated:
133
-
134
- | File | Action |
135
- |------|--------|
136
- | `.fabric/init-context.json` | Created with all required fields |
137
- | `AGENTS.md` | Created (root L0) |
138
- | `{group_path}/AGENTS.md` | Created for each domain group (when applicable) |
139
- | `.fabric/agents.meta.json` | Updated nodes tree + hashes |
140
-
141
- On failure or early termination the skill MUST leave no partial files. If a write fails
142
- mid-sequence, report the failure and the exact file that was not written.
143
-
144
- ## Protected Tokens
145
-
146
- The following tokens MUST be preserved exactly as shown — same casing, same punctuation,
147
- never translated:
148
-
149
- | Token | Type |
150
- |-------|------|
151
- | `AGENTS.md` | Filename |
152
- | `FABRIC.md` | Filename |
153
- | `.fabric/agents.meta.json` | Path |
154
- | `.fabric/init-context.json` | Path |
155
- | `.fabric/forensic.json` | Path |
156
- | `.fabric/bootstrap/README.md` | Path |
157
- | `MUST` | Keyword |
158
- | `NEVER` | Keyword |
159
- | `fab init` | CLI command |
160
- | `fabric doctor --fix` | CLI command |
161
- | `<!-- fab:index -->` | HTML comment marker |
162
- | `@HUMAN` | Section marker |
@@ -1,9 +0,0 @@
1
- #!/bin/sh
2
- # Fabric pre-commit hook: block manual edits to generated metadata.
3
-
4
- if git diff --cached --name-only | grep -q '^\.fabric/agents\.meta\.json$'; then
5
- if [ "$FAB_ALLOW_META_EDIT" != '1' ]; then
6
- echo '.fabric/agents.meta.json cannot be manually edited; update .fabric/rules and run fabric doctor --fix, or set FAB_ALLOW_META_EDIT=1' >&2
7
- exit 1
8
- fi
9
- fi