@fenglimg/fabric-cli 1.7.0 → 1.8.0-rc.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.
@@ -9,7 +9,7 @@ import {
9
9
 
10
10
  // src/commands/serve.ts
11
11
  import { defineCommand } from "citty";
12
- import { startHttpServer } from "@fenglimg/fabric-server";
12
+ import { acquireLock, releaseLock, startHttpServer } from "@fenglimg/fabric-server";
13
13
  var DEFAULT_PORT = 7373;
14
14
  var serveCommand = defineCommand({
15
15
  meta: {
@@ -35,6 +35,11 @@ var serveCommand = defineCommand({
35
35
  type: "boolean",
36
36
  description: t("cli.serve.args.debug.description"),
37
37
  default: false
38
+ },
39
+ force: {
40
+ type: "boolean",
41
+ description: t("cli.serve.args.force.description"),
42
+ default: false
38
43
  }
39
44
  },
40
45
  async run({ args }) {
@@ -45,6 +50,11 @@ var serveCommand = defineCommand({
45
50
  const requestedHost = parseHost(args.host);
46
51
  const authToken = readAuthTokenFromEnv();
47
52
  const host = validateHost(requestedHost, authToken);
53
+ const projectRoot = resolution.target;
54
+ acquireLock(projectRoot, { force: args.force });
55
+ process.on("exit", () => {
56
+ releaseLock(projectRoot);
57
+ });
48
58
  logger(`serve target source: ${resolution.source}`);
49
59
  for (const step of resolution.chain) {
50
60
  logger(step);
@@ -52,14 +62,16 @@ var serveCommand = defineCommand({
52
62
  try {
53
63
  await startHttpServer({
54
64
  port,
55
- projectRoot: resolution.target,
65
+ projectRoot,
56
66
  host,
57
67
  authToken
58
68
  });
59
69
  } catch (error) {
60
70
  if (isNodeError(error) && error.code === "EADDRINUSE") {
71
+ releaseLock(projectRoot);
61
72
  throw new Error(t("cli.serve.error.port-in-use", { port: String(port), nextPort: String(port + 1) }));
62
73
  }
74
+ releaseLock(projectRoot);
63
75
  throw error;
64
76
  }
65
77
  console.log(`${symbol.ok} ${paint.ai(t("cli.serve.ready.title"))} ${paint.human(`http://${host}:${port}`)}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fenglimg/fabric-cli",
3
- "version": "1.7.0",
3
+ "version": "1.8.0-rc.1",
4
4
  "type": "module",
5
5
  "bin": {
6
6
  "fab": "dist/index.js",
@@ -14,19 +14,16 @@
14
14
  ],
15
15
  "dependencies": {
16
16
  "@clack/prompts": "^1.2.0",
17
- "@iarna/toml": "^2.2.5",
18
17
  "citty": "^0.2.2",
19
- "minimatch": "^10.0.1",
20
18
  "picocolors": "^1.1.1",
21
19
  "string-width": "^7.2.0",
22
20
  "tree-sitter-javascript": "^0.25.0",
23
21
  "tree-sitter-typescript": "^0.23.2",
24
22
  "web-tree-sitter": "^0.26.8",
25
- "@fenglimg/fabric-server": "1.7.0",
26
- "@fenglimg/fabric-shared": "1.7.0"
23
+ "@fenglimg/fabric-server": "1.8.0-rc.1",
24
+ "@fenglimg/fabric-shared": "1.8.0-rc.1"
27
25
  },
28
26
  "devDependencies": {
29
- "@types/iarna__toml": "^2.0.5",
30
27
  "@types/node": "^22.15.0",
31
28
  "tsup": "^8.5.0",
32
29
  "typescript": "^5.8.3"
@@ -34,6 +31,7 @@
34
31
  "scripts": {
35
32
  "build": "tsup",
36
33
  "dev": "tsup --watch",
37
- "test": "vitest run"
34
+ "test": "vitest run",
35
+ "test:coverage": "vitest run --coverage"
38
36
  }
39
37
  }
@@ -0,0 +1,163 @@
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,27 +1,162 @@
1
1
  ---
2
2
  name: fabric-init
3
- description: Use this skill when `.fabric/forensic.json` exists and this repository still needs the remaining Fabric initialization steps.
3
+ description: Use this skill when .fabric/forensic.json exists and this repository still needs the remaining Fabric initialization steps.
4
4
  ---
5
5
 
6
- ## Hard Rules (不要翻译受保护 token)
6
+ # fabric-init Canonical Skill Source
7
7
 
8
- MUST: 先读取 `.fabric/forensic.json`,再做其他动作。
9
- MUST: `.fabric/bootstrap/README.md` 视为当前仓库的初始化说明。
10
- MUST: 如果 `.fabric/init-context.json` 已存在,立即停止并报告当前仓库看起来已经完成后续初始化。
11
- MUST: 使用 `.fabric/forensic.json` 和仓库结构中的依据,判断接下来该做什么。
12
- MUST: Preserve protected tokens exactly: `AGENTS.md`, `FABRIC.md`, `.fabric/agents.meta.json`, `.fabric/init-context.json`, `.fabric/forensic.json`, `MUST`, `NEVER`.
13
- NEVER: 在没有检查 `.fabric/init-context.json` 的情况下声称初始化已经完成。
14
- NEVER: 改写或翻译受保护 token。
15
- NEVER: 在判断下一步初始化动作时忽略 `.fabric/bootstrap/README.md`。
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.
16
11
 
17
- ## Purpose
12
+ ## Precondition
18
13
 
19
- 当你在 Codex 中处理这个仓库,并且 `fab init` 已经生成 `.fabric/forensic.json` 时,使用这个 skill 继续完成仓库专属的 Fabric 初始化。目标是基于当前仓库的初始化依据和内部说明,明确下一步该做什么,而不是重新解释一遍通用流程。
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.
20
17
 
21
- ## Workflow
18
+ MUST: Check `.fabric/init-context.json`. If it already exists, stop and report that this
19
+ repository appears to have completed initialization already.
22
20
 
23
- 1. 读取 `.fabric/forensic.json`。
24
- 2. 读取 `.fabric/bootstrap/README.md`。
25
- 3. 检查 `.fabric/init-context.json` 是否已经存在。
26
- 4. 如果初始化仍未完成,明确总结当前仓库接下来要做的初始化动作。
27
- 5. 只讨论这个仓库的后续初始化,不扩展到无关建议。
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 |
@@ -0,0 +1,157 @@
1
+ # fabric-init — Canonical Skill Source
2
+
3
+ > This file is the single source of truth for the fabric-init skill.
4
+ > Do NOT edit the per-client SKILL.md files directly.
5
+ > Run `packages/cli/scripts/derive-skills.ts` to regenerate them from this source.
6
+
7
+ ## Precondition
8
+
9
+ MUST: Read `.fabric/forensic.json` before taking any other action. If the file does not
10
+ exist, stop immediately and tell the user: run `fab init` first to generate the evidence
11
+ package.
12
+
13
+ MUST: Check `.fabric/init-context.json`. If it already exists, stop and report that this
14
+ repository appears to have completed initialization already.
15
+
16
+ MUST: Treat `.fabric/bootstrap/README.md` as the authoritative initialization guide for
17
+ the current repository.
18
+
19
+ MUST: Use `.fabric/forensic.json` and repository structure as evidence when deciding what
20
+ to do next.
21
+
22
+ MUST: Preserve protected tokens exactly as written — see the Protected Tokens section.
23
+
24
+ NEVER: Claim initialization is complete without having checked `.fabric/init-context.json`.
25
+
26
+ NEVER: Rewrite or translate protected tokens.
27
+
28
+ NEVER: Ignore `.fabric/bootstrap/README.md` when determining the next initialization step.
29
+
30
+ Treat the following state as initialization pending:
31
+
32
+ - `.fabric/forensic.json` exists
33
+ - `.fabric/init-context.json` does not exist
34
+
35
+ ## Execution Flow — 3 Phases / 3 Rounds
36
+
37
+ ### Phase 1 — Framework Confirmation (1 round, efficient)
38
+
39
+ Display a summary of `framework`, `topology.by_ext`, and `entry_points` from
40
+ `.fabric/forensic.json`. Ask the user 1–2 clarifying questions about the framework
41
+ architecture.
42
+
43
+ Example (Cocos Creator 3.x):
44
+
45
+ > I detected a Cocos Creator 3.8 project. Main scripts are in `assets/scripts` using the
46
+ > `@ccclass + extends Component` pattern. Please confirm: (1) Is this a TypeScript project
47
+ > (not JavaScript)? (2) Are node references injected mainly via `@property(Node)`, or via
48
+ > `find/getChildByName`?
49
+
50
+ Store the user's answers as verified framework assumptions before proceeding to Phase 2.
51
+
52
+ ### Phase 2 — Invariant Extraction (1 round, critical)
53
+
54
+ Based on the `recommendations_for_skill` list in `.fabric/forensic.json`, ask the user
55
+ 3–5 invariant questions covering three categories:
56
+
57
+ - `ban`: things that must never appear — e.g. `any`, `async` in `update()`, find-by-name
58
+ - `require`: things that must always be present — e.g. strict TypeScript, `@ccclass`
59
+ decorator, imports only from `cc`
60
+ - `protect`: directories or files that AI must not modify — typically
61
+ `assets/prefabs/**`, `assets/scenes/**`, `**/*.meta`
62
+
63
+ Principles:
64
+
65
+ - Ask only about invariants, not about preferences.
66
+ - Each question accepts only yes / no / a concrete rule — never accept vague answers.
67
+ - Do not auto-infer hard constraints the user has not confirmed.
68
+
69
+ ### Phase 3 — Construction and Landing (1 round, automated)
70
+
71
+ #### 3.1 Write `.fabric/init-context.json`
72
+
73
+ Fields required:
74
+
75
+ - `framework`
76
+ - `architecture_patterns`
77
+ - `invariants`
78
+ - `domain_groups`
79
+ - `interview_trail`
80
+ - `forensic_ref`
81
+
82
+ Writing rules:
83
+
84
+ - `invariants[].type` MUST be one of `ban`, `require`, `protect`.
85
+ - `domain_groups` is inferred from `entry_points` and interview results.
86
+ - `interview_trail[]` MUST record the raw Q&A from Phase 1 and Phase 2.
87
+ - `forensic_ref` MUST be `.fabric/forensic.json`.
88
+
89
+ #### 3.2 Generate layered `AGENTS.md`
90
+
91
+ Root `AGENTS.md` requirements:
92
+
93
+ - MUST be within 300 lines.
94
+ - Structure:
95
+ - `# {projectName} — L0 AGENTS.md`
96
+ - `<!-- fab:index -->`: populated with the `domain_groups` index
97
+ - `## L0 AI Constraints`: derived from invariants, grouped by `ban`, `require`, `protect`
98
+ - `## @HUMAN`: protect paths and any human-declared protection rules
99
+ - `## L1 Candidate Notes`: candidate sub-module descriptions for each domain group
100
+
101
+ If `domain_groups.length >= 2`, generate a `{group_path}/AGENTS.md` for each group.
102
+ Maximum depth is L3; total nesting MUST NOT exceed 4 levels.
103
+
104
+ #### 3.3 Update `.fabric/agents.meta.json`
105
+
106
+ - The `nodes` tree MUST match the generated AGENTS hierarchy.
107
+ - Update the hash of every AGENTS.md file that was written.
108
+ - Maintain a consistent internal revision hash chain.
109
+
110
+ #### 3.4 Final output
111
+
112
+ List all generated files for the user and recommend running `fabric doctor --fix` for
113
+ ongoing maintenance.
114
+
115
+ ## Hard Rules
116
+
117
+ - Zero TODO: never generate `TODO`, `TBD`, placeholders, or stubs in output files.
118
+ - No YAML frontmatter in outputs: generated `AGENTS.md` files MUST NOT contain YAML
119
+ frontmatter.
120
+ - Root `AGENTS.md` MUST be <= 300 lines.
121
+ - Total AGENTS nesting MUST be <= 4 levels.
122
+ - Do not auto-infer invariants the user has not confirmed.
123
+ - When content is uncertain, omit it — do not leave placeholders.
124
+
125
+ ## Output Contract
126
+
127
+ On successful completion the following files exist or are updated:
128
+
129
+ | File | Action |
130
+ |------|--------|
131
+ | `.fabric/init-context.json` | Created with all required fields |
132
+ | `AGENTS.md` | Created (root L0) |
133
+ | `{group_path}/AGENTS.md` | Created for each domain group (when applicable) |
134
+ | `.fabric/agents.meta.json` | Updated nodes tree + hashes |
135
+
136
+ On failure or early termination the skill MUST leave no partial files. If a write fails
137
+ mid-sequence, report the failure and the exact file that was not written.
138
+
139
+ ## Protected Tokens
140
+
141
+ The following tokens MUST be preserved exactly as shown — same casing, same punctuation,
142
+ never translated:
143
+
144
+ | Token | Type |
145
+ |-------|------|
146
+ | `AGENTS.md` | Filename |
147
+ | `FABRIC.md` | Filename |
148
+ | `.fabric/agents.meta.json` | Path |
149
+ | `.fabric/init-context.json` | Path |
150
+ | `.fabric/forensic.json` | Path |
151
+ | `.fabric/bootstrap/README.md` | Path |
152
+ | `MUST` | Keyword |
153
+ | `NEVER` | Keyword |
154
+ | `fab init` | CLI command |
155
+ | `fabric doctor --fix` | CLI command |
156
+ | `<!-- fab:index -->` | HTML comment marker |
157
+ | `@HUMAN` | Section marker |
@@ -0,0 +1,17 @@
1
+ {
2
+ "claude": {
3
+ "outputName": "fabric-init",
4
+ "frontmatter": {
5
+ "name": "fabric-init",
6
+ "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.",
7
+ "allowed-tools": ["Read", "Write", "Glob", "Grep", "Bash"]
8
+ }
9
+ },
10
+ "codex": {
11
+ "outputName": "fabric-init",
12
+ "frontmatter": {
13
+ "name": "fabric-init",
14
+ "description": "Use this skill when .fabric/forensic.json exists and this repository still needs the remaining Fabric initialization steps."
15
+ }
16
+ }
17
+ }