cclaw-cli 7.7.1 → 8.1.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 (284) hide show
  1. package/README.md +211 -134
  2. package/dist/artifact-frontmatter.d.ts +51 -0
  3. package/dist/artifact-frontmatter.js +131 -0
  4. package/dist/artifact-paths.d.ts +7 -27
  5. package/dist/artifact-paths.js +20 -249
  6. package/dist/cancel.d.ts +16 -0
  7. package/dist/cancel.js +66 -0
  8. package/dist/cli.d.ts +2 -27
  9. package/dist/cli.js +107 -511
  10. package/dist/compound.d.ts +26 -0
  11. package/dist/compound.js +96 -0
  12. package/dist/config.d.ts +14 -51
  13. package/dist/config.js +23 -359
  14. package/dist/constants.d.ts +11 -18
  15. package/dist/constants.js +19 -106
  16. package/dist/content/antipatterns.d.ts +1 -0
  17. package/dist/content/antipatterns.js +109 -0
  18. package/dist/content/artifact-templates.d.ts +10 -0
  19. package/dist/content/artifact-templates.js +550 -0
  20. package/dist/content/cancel-command.d.ts +2 -2
  21. package/dist/content/cancel-command.js +25 -17
  22. package/dist/content/core-agents.d.ts +9 -233
  23. package/dist/content/core-agents.js +39 -768
  24. package/dist/content/decision-protocol.d.ts +1 -12
  25. package/dist/content/decision-protocol.js +27 -20
  26. package/dist/content/examples.d.ts +8 -42
  27. package/dist/content/examples.js +293 -425
  28. package/dist/content/idea-command.d.ts +2 -0
  29. package/dist/content/idea-command.js +38 -0
  30. package/dist/content/iron-laws.d.ts +4 -138
  31. package/dist/content/iron-laws.js +18 -197
  32. package/dist/content/meta-skill.d.ts +1 -3
  33. package/dist/content/meta-skill.js +57 -134
  34. package/dist/content/node-hooks.d.ts +12 -8
  35. package/dist/content/node-hooks.js +188 -838
  36. package/dist/content/recovery.d.ts +8 -0
  37. package/dist/content/recovery.js +179 -0
  38. package/dist/content/reference-patterns.d.ts +4 -13
  39. package/dist/content/reference-patterns.js +260 -389
  40. package/dist/content/research-playbooks.d.ts +8 -8
  41. package/dist/content/research-playbooks.js +108 -121
  42. package/dist/content/review-loop.d.ts +6 -192
  43. package/dist/content/review-loop.js +29 -731
  44. package/dist/content/skills.d.ts +8 -38
  45. package/dist/content/skills.js +681 -732
  46. package/dist/content/specialist-prompts/architect.d.ts +1 -0
  47. package/dist/content/specialist-prompts/architect.js +225 -0
  48. package/dist/content/specialist-prompts/brainstormer.d.ts +1 -0
  49. package/dist/content/specialist-prompts/brainstormer.js +168 -0
  50. package/dist/content/specialist-prompts/index.d.ts +2 -0
  51. package/dist/content/specialist-prompts/index.js +14 -0
  52. package/dist/content/specialist-prompts/planner.d.ts +1 -0
  53. package/dist/content/specialist-prompts/planner.js +182 -0
  54. package/dist/content/specialist-prompts/reviewer.d.ts +1 -0
  55. package/dist/content/specialist-prompts/reviewer.js +193 -0
  56. package/dist/content/specialist-prompts/security-reviewer.d.ts +1 -0
  57. package/dist/content/specialist-prompts/security-reviewer.js +133 -0
  58. package/dist/content/specialist-prompts/slice-builder.d.ts +1 -0
  59. package/dist/content/specialist-prompts/slice-builder.js +232 -0
  60. package/dist/content/stage-playbooks.d.ts +8 -0
  61. package/dist/content/stage-playbooks.js +404 -0
  62. package/dist/content/start-command.d.ts +2 -12
  63. package/dist/content/start-command.js +221 -207
  64. package/dist/flow-state.d.ts +21 -178
  65. package/dist/flow-state.js +67 -170
  66. package/dist/fs-utils.d.ts +6 -26
  67. package/dist/fs-utils.js +29 -162
  68. package/dist/gitignore.d.ts +2 -1
  69. package/dist/gitignore.js +51 -34
  70. package/dist/harness-detect.d.ts +10 -0
  71. package/dist/harness-detect.js +29 -0
  72. package/dist/harness-prompt.d.ts +26 -0
  73. package/dist/harness-prompt.js +142 -0
  74. package/dist/install.d.ts +35 -15
  75. package/dist/install.js +238 -1347
  76. package/dist/knowledge-store.d.ts +19 -163
  77. package/dist/knowledge-store.js +56 -590
  78. package/dist/logger.d.ts +8 -3
  79. package/dist/logger.js +13 -4
  80. package/dist/orchestrator-routing.d.ts +29 -0
  81. package/dist/orchestrator-routing.js +156 -0
  82. package/dist/run-persistence.d.ts +7 -118
  83. package/dist/run-persistence.js +29 -845
  84. package/dist/runtime/run-hook.entry.d.ts +1 -3
  85. package/dist/runtime/run-hook.entry.js +19 -4
  86. package/dist/runtime/run-hook.mjs +13 -1024
  87. package/dist/types.d.ts +25 -261
  88. package/dist/types.js +8 -36
  89. package/package.json +6 -3
  90. package/dist/artifact-linter/brainstorm.d.ts +0 -2
  91. package/dist/artifact-linter/brainstorm.js +0 -353
  92. package/dist/artifact-linter/design.d.ts +0 -18
  93. package/dist/artifact-linter/design.js +0 -444
  94. package/dist/artifact-linter/findings-dedup.d.ts +0 -56
  95. package/dist/artifact-linter/findings-dedup.js +0 -232
  96. package/dist/artifact-linter/plan.d.ts +0 -2
  97. package/dist/artifact-linter/plan.js +0 -826
  98. package/dist/artifact-linter/review-army.d.ts +0 -49
  99. package/dist/artifact-linter/review-army.js +0 -520
  100. package/dist/artifact-linter/review.d.ts +0 -2
  101. package/dist/artifact-linter/review.js +0 -113
  102. package/dist/artifact-linter/scope.d.ts +0 -2
  103. package/dist/artifact-linter/scope.js +0 -158
  104. package/dist/artifact-linter/shared.d.ts +0 -637
  105. package/dist/artifact-linter/shared.js +0 -2163
  106. package/dist/artifact-linter/ship.d.ts +0 -2
  107. package/dist/artifact-linter/ship.js +0 -250
  108. package/dist/artifact-linter/spec.d.ts +0 -2
  109. package/dist/artifact-linter/spec.js +0 -176
  110. package/dist/artifact-linter/tdd.d.ts +0 -118
  111. package/dist/artifact-linter/tdd.js +0 -1404
  112. package/dist/artifact-linter.d.ts +0 -15
  113. package/dist/artifact-linter.js +0 -517
  114. package/dist/codex-feature-flag.d.ts +0 -58
  115. package/dist/codex-feature-flag.js +0 -193
  116. package/dist/content/closeout-guidance.d.ts +0 -14
  117. package/dist/content/closeout-guidance.js +0 -44
  118. package/dist/content/diff-command.d.ts +0 -1
  119. package/dist/content/diff-command.js +0 -43
  120. package/dist/content/harness-doc.d.ts +0 -1
  121. package/dist/content/harness-doc.js +0 -65
  122. package/dist/content/hook-events.d.ts +0 -9
  123. package/dist/content/hook-events.js +0 -23
  124. package/dist/content/hook-manifest.d.ts +0 -81
  125. package/dist/content/hook-manifest.js +0 -156
  126. package/dist/content/hooks.d.ts +0 -11
  127. package/dist/content/hooks.js +0 -1972
  128. package/dist/content/idea.d.ts +0 -60
  129. package/dist/content/idea.js +0 -416
  130. package/dist/content/language-policy.d.ts +0 -2
  131. package/dist/content/language-policy.js +0 -13
  132. package/dist/content/learnings.d.ts +0 -6
  133. package/dist/content/learnings.js +0 -141
  134. package/dist/content/observe.d.ts +0 -19
  135. package/dist/content/observe.js +0 -86
  136. package/dist/content/opencode-plugin.d.ts +0 -1
  137. package/dist/content/opencode-plugin.js +0 -635
  138. package/dist/content/review-prompts.d.ts +0 -1
  139. package/dist/content/review-prompts.js +0 -104
  140. package/dist/content/runtime-shared-snippets.d.ts +0 -8
  141. package/dist/content/runtime-shared-snippets.js +0 -80
  142. package/dist/content/session-hooks.d.ts +0 -7
  143. package/dist/content/session-hooks.js +0 -107
  144. package/dist/content/skills-elicitation.d.ts +0 -1
  145. package/dist/content/skills-elicitation.js +0 -167
  146. package/dist/content/stage-command.d.ts +0 -2
  147. package/dist/content/stage-command.js +0 -17
  148. package/dist/content/stage-schema.d.ts +0 -117
  149. package/dist/content/stage-schema.js +0 -955
  150. package/dist/content/stages/_lint-metadata/index.d.ts +0 -2
  151. package/dist/content/stages/_lint-metadata/index.js +0 -97
  152. package/dist/content/stages/brainstorm.d.ts +0 -2
  153. package/dist/content/stages/brainstorm.js +0 -184
  154. package/dist/content/stages/design.d.ts +0 -2
  155. package/dist/content/stages/design.js +0 -288
  156. package/dist/content/stages/index.d.ts +0 -8
  157. package/dist/content/stages/index.js +0 -11
  158. package/dist/content/stages/plan.d.ts +0 -2
  159. package/dist/content/stages/plan.js +0 -191
  160. package/dist/content/stages/review.d.ts +0 -2
  161. package/dist/content/stages/review.js +0 -240
  162. package/dist/content/stages/schema-types.d.ts +0 -203
  163. package/dist/content/stages/schema-types.js +0 -1
  164. package/dist/content/stages/scope.d.ts +0 -2
  165. package/dist/content/stages/scope.js +0 -254
  166. package/dist/content/stages/ship.d.ts +0 -2
  167. package/dist/content/stages/ship.js +0 -159
  168. package/dist/content/stages/spec.d.ts +0 -2
  169. package/dist/content/stages/spec.js +0 -170
  170. package/dist/content/stages/tdd.d.ts +0 -4
  171. package/dist/content/stages/tdd.js +0 -273
  172. package/dist/content/state-contracts.d.ts +0 -1
  173. package/dist/content/state-contracts.js +0 -63
  174. package/dist/content/status-command.d.ts +0 -4
  175. package/dist/content/status-command.js +0 -109
  176. package/dist/content/subagent-context-skills.d.ts +0 -4
  177. package/dist/content/subagent-context-skills.js +0 -279
  178. package/dist/content/subagents.d.ts +0 -3
  179. package/dist/content/subagents.js +0 -997
  180. package/dist/content/templates.d.ts +0 -26
  181. package/dist/content/templates.js +0 -1692
  182. package/dist/content/track-render-context.d.ts +0 -18
  183. package/dist/content/track-render-context.js +0 -53
  184. package/dist/content/tree-command.d.ts +0 -1
  185. package/dist/content/tree-command.js +0 -64
  186. package/dist/content/utility-skills.d.ts +0 -30
  187. package/dist/content/utility-skills.js +0 -160
  188. package/dist/content/view-command.d.ts +0 -2
  189. package/dist/content/view-command.js +0 -92
  190. package/dist/delegation.d.ts +0 -649
  191. package/dist/delegation.js +0 -1539
  192. package/dist/early-loop.d.ts +0 -70
  193. package/dist/early-loop.js +0 -302
  194. package/dist/execution-topology.d.ts +0 -44
  195. package/dist/execution-topology.js +0 -95
  196. package/dist/gate-evidence.d.ts +0 -85
  197. package/dist/gate-evidence.js +0 -631
  198. package/dist/harness-adapters.d.ts +0 -151
  199. package/dist/harness-adapters.js +0 -756
  200. package/dist/harness-selection.d.ts +0 -31
  201. package/dist/harness-selection.js +0 -214
  202. package/dist/hook-schema.d.ts +0 -6
  203. package/dist/hook-schema.js +0 -114
  204. package/dist/hook-schemas/claude-hooks.v1.json +0 -10
  205. package/dist/hook-schemas/codex-hooks.v1.json +0 -10
  206. package/dist/hook-schemas/cursor-hooks.v1.json +0 -13
  207. package/dist/init-detect.d.ts +0 -2
  208. package/dist/init-detect.js +0 -50
  209. package/dist/internal/advance-stage/advance.d.ts +0 -89
  210. package/dist/internal/advance-stage/advance.js +0 -655
  211. package/dist/internal/advance-stage/cancel-run.d.ts +0 -8
  212. package/dist/internal/advance-stage/cancel-run.js +0 -19
  213. package/dist/internal/advance-stage/flow-state-coercion.d.ts +0 -3
  214. package/dist/internal/advance-stage/flow-state-coercion.js +0 -81
  215. package/dist/internal/advance-stage/helpers.d.ts +0 -14
  216. package/dist/internal/advance-stage/helpers.js +0 -145
  217. package/dist/internal/advance-stage/hook.d.ts +0 -8
  218. package/dist/internal/advance-stage/hook.js +0 -40
  219. package/dist/internal/advance-stage/parsers.d.ts +0 -72
  220. package/dist/internal/advance-stage/parsers.js +0 -357
  221. package/dist/internal/advance-stage/proactive-delegation-trace.d.ts +0 -24
  222. package/dist/internal/advance-stage/proactive-delegation-trace.js +0 -56
  223. package/dist/internal/advance-stage/review-loop.d.ts +0 -16
  224. package/dist/internal/advance-stage/review-loop.js +0 -199
  225. package/dist/internal/advance-stage/rewind.d.ts +0 -14
  226. package/dist/internal/advance-stage/rewind.js +0 -108
  227. package/dist/internal/advance-stage/start-flow.d.ts +0 -13
  228. package/dist/internal/advance-stage/start-flow.js +0 -241
  229. package/dist/internal/advance-stage/verify.d.ts +0 -21
  230. package/dist/internal/advance-stage/verify.js +0 -185
  231. package/dist/internal/advance-stage.d.ts +0 -7
  232. package/dist/internal/advance-stage.js +0 -138
  233. package/dist/internal/cohesion-contract-stub.d.ts +0 -24
  234. package/dist/internal/cohesion-contract-stub.js +0 -148
  235. package/dist/internal/compound-readiness.d.ts +0 -23
  236. package/dist/internal/compound-readiness.js +0 -102
  237. package/dist/internal/detect-public-api-changes.d.ts +0 -5
  238. package/dist/internal/detect-public-api-changes.js +0 -45
  239. package/dist/internal/detect-supply-chain-changes.d.ts +0 -6
  240. package/dist/internal/detect-supply-chain-changes.js +0 -138
  241. package/dist/internal/early-loop-status.d.ts +0 -7
  242. package/dist/internal/early-loop-status.js +0 -93
  243. package/dist/internal/envelope-validate.d.ts +0 -7
  244. package/dist/internal/envelope-validate.js +0 -66
  245. package/dist/internal/flow-state-repair.d.ts +0 -20
  246. package/dist/internal/flow-state-repair.js +0 -104
  247. package/dist/internal/plan-split-waves.d.ts +0 -190
  248. package/dist/internal/plan-split-waves.js +0 -764
  249. package/dist/internal/runtime-integrity.d.ts +0 -7
  250. package/dist/internal/runtime-integrity.js +0 -268
  251. package/dist/internal/slice-commit.d.ts +0 -7
  252. package/dist/internal/slice-commit.js +0 -619
  253. package/dist/internal/tdd-loop-status.d.ts +0 -14
  254. package/dist/internal/tdd-loop-status.js +0 -68
  255. package/dist/internal/tdd-red-evidence.d.ts +0 -7
  256. package/dist/internal/tdd-red-evidence.js +0 -153
  257. package/dist/internal/waiver-grant.d.ts +0 -62
  258. package/dist/internal/waiver-grant.js +0 -294
  259. package/dist/internal/wave-status.d.ts +0 -74
  260. package/dist/internal/wave-status.js +0 -506
  261. package/dist/managed-resources.d.ts +0 -53
  262. package/dist/managed-resources.js +0 -313
  263. package/dist/policy.d.ts +0 -10
  264. package/dist/policy.js +0 -167
  265. package/dist/retro-gate.d.ts +0 -9
  266. package/dist/retro-gate.js +0 -47
  267. package/dist/run-archive.d.ts +0 -61
  268. package/dist/run-archive.js +0 -391
  269. package/dist/runs.d.ts +0 -2
  270. package/dist/runs.js +0 -2
  271. package/dist/stack-detection.d.ts +0 -116
  272. package/dist/stack-detection.js +0 -489
  273. package/dist/streaming/event-stream.d.ts +0 -31
  274. package/dist/streaming/event-stream.js +0 -114
  275. package/dist/tdd-cycle.d.ts +0 -107
  276. package/dist/tdd-cycle.js +0 -289
  277. package/dist/tdd-verification-evidence.d.ts +0 -17
  278. package/dist/tdd-verification-evidence.js +0 -122
  279. package/dist/track-heuristics.d.ts +0 -27
  280. package/dist/track-heuristics.js +0 -154
  281. package/dist/util/slice-id.d.ts +0 -58
  282. package/dist/util/slice-id.js +0 -89
  283. package/dist/worktree-manager.d.ts +0 -20
  284. package/dist/worktree-manager.js +0 -108
@@ -0,0 +1,2 @@
1
+ export declare const IDEA_COMMAND_BODY = "# /cc-idea \u2014 capture an idea outside of any active flow\n\nThis command does **not** participate in plan/build/review/ship. Its only job is to drop a half-formed idea into the backlog without spinning up a full flow.\n\n## Behaviour\n\n1. Open `.cclaw/ideas.md`. If it does not exist, seed it from `.cclaw/lib/templates/ideas.md`.\n2. Append a new entry with this shape:\n\n ```\n ## YYYY-MM-DDTHH:MM:SSZ \u2014 <one-line summary>\n\n <short paragraph or bullet list with the idea body>\n ```\n\n3. Save the file. Do not slugify, do not create artifacts under `.cclaw/flows/<slug>/`, do not modify `flow-state.json`, do not invoke specialists.\n\n## Hard rules\n\n- One entry per invocation. If the user pastes multiple ideas, ask whether to file them as one entry or several.\n- Never auto-promote an idea to a plan. Promotion happens only when the user explicitly invokes `/cc <task>`.\n- Never delete or edit prior ideas inside `/cc-idea`. Trimming the backlog is a separate manual step.\n\n## Suggested entry shape\n\n```\n## 2026-05-07T19:30:12Z \u2014 switch knowledge.jsonl to ndjson\n\nRight now `.cclaw/knowledge.jsonl` is one JSON object per line, but tooling\nexpects RFC 8259-compliant NDJSON. Worth verifying once the tooling adopts\nthe standard formally.\n```\n\nThe orchestrator surfaces ideas back to the user only when an explicit `/cc` invocation references them; otherwise they stay quiet.\n";
2
+ export declare function renderIdeaCommand(): string;
@@ -0,0 +1,38 @@
1
+ export const IDEA_COMMAND_BODY = `# /cc-idea — capture an idea outside of any active flow
2
+
3
+ This command does **not** participate in plan/build/review/ship. Its only job is to drop a half-formed idea into the backlog without spinning up a full flow.
4
+
5
+ ## Behaviour
6
+
7
+ 1. Open \`.cclaw/ideas.md\`. If it does not exist, seed it from \`.cclaw/lib/templates/ideas.md\`.
8
+ 2. Append a new entry with this shape:
9
+
10
+ \`\`\`
11
+ ## YYYY-MM-DDTHH:MM:SSZ — <one-line summary>
12
+
13
+ <short paragraph or bullet list with the idea body>
14
+ \`\`\`
15
+
16
+ 3. Save the file. Do not slugify, do not create artifacts under \`.cclaw/flows/<slug>/\`, do not modify \`flow-state.json\`, do not invoke specialists.
17
+
18
+ ## Hard rules
19
+
20
+ - One entry per invocation. If the user pastes multiple ideas, ask whether to file them as one entry or several.
21
+ - Never auto-promote an idea to a plan. Promotion happens only when the user explicitly invokes \`/cc <task>\`.
22
+ - Never delete or edit prior ideas inside \`/cc-idea\`. Trimming the backlog is a separate manual step.
23
+
24
+ ## Suggested entry shape
25
+
26
+ \`\`\`
27
+ ## 2026-05-07T19:30:12Z — switch knowledge.jsonl to ndjson
28
+
29
+ Right now \`.cclaw/knowledge.jsonl\` is one JSON object per line, but tooling
30
+ expects RFC 8259-compliant NDJSON. Worth verifying once the tooling adopts
31
+ the standard formally.
32
+ \`\`\`
33
+
34
+ The orchestrator surfaces ideas back to the user only when an explicit \`/cc\` invocation references them; otherwise they stay quiet.
35
+ `;
36
+ export function renderIdeaCommand() {
37
+ return IDEA_COMMAND_BODY;
38
+ }
@@ -1,141 +1,7 @@
1
- import type { FlowStage } from "../types.js";
2
- export type IronLawEnforcementPoint = "PreToolUse" | "PostToolUse" | "SessionStart" | "Stop" | "advisory";
3
- export type IronLawSeverity = "hard-gate" | "soft-gate";
4
- export interface IronLawDefinition {
1
+ export interface IronLaw {
5
2
  id: string;
6
3
  title: string;
7
- rule: string;
8
- rationale: string;
9
- enforcement: IronLawEnforcementPoint;
10
- severity: IronLawSeverity;
11
- appliesTo: "all" | FlowStage[];
12
- hookMatcher?: {
13
- toolPattern?: string;
14
- payloadPattern?: string;
15
- };
4
+ description: string;
16
5
  }
17
- export interface IronLawRuntimeRecord {
18
- id: string;
19
- title: string;
20
- rule: string;
21
- enforcement: IronLawEnforcementPoint;
22
- severity: IronLawSeverity;
23
- appliesTo: "all" | FlowStage[];
24
- strict: boolean;
25
- hookMatcher?: {
26
- toolPattern?: string;
27
- payloadPattern?: string;
28
- };
29
- }
30
- export interface IronLawRuntimeDocument {
31
- version: 1;
32
- generatedAt: string;
33
- mode: "advisory" | "strict";
34
- strictLaws: string[];
35
- laws: IronLawRuntimeRecord[];
36
- }
37
- export declare const IRON_LAWS: readonly [{
38
- readonly id: "tdd-red-before-write";
39
- readonly title: "RED before production write";
40
- readonly rule: "Do not edit production code in tdd stage before a failing RED test exists for the slice.";
41
- readonly rationale: "Prevents implementation-first behavior and keeps RED as executable specification.";
42
- readonly enforcement: "PreToolUse";
43
- readonly severity: "hard-gate";
44
- readonly appliesTo: ["tdd"];
45
- readonly hookMatcher: {
46
- readonly toolPattern: "write|edit|multiedit|applypatch|shell|bash";
47
- readonly payloadPattern: "\\.(ts|tsx|js|jsx|py|go|java|rs|rb|php|c|cc|cpp|h|hpp)";
48
- };
49
- }, {
50
- readonly id: "plan-requires-approval";
51
- readonly title: "No implementation before plan approval";
52
- readonly rule: "Do not perform write-like actions while plan stage is pending WAIT_FOR_CONFIRM approval.";
53
- readonly rationale: "Locks intent before execution and reduces expensive rework from unapproved paths.";
54
- readonly enforcement: "PreToolUse";
55
- readonly severity: "hard-gate";
56
- readonly appliesTo: ["plan"];
57
- }, {
58
- readonly id: "runtime-writes-managed-only";
59
- readonly title: "Runtime writes are managed";
60
- readonly rule: "Do not mutate .cclaw/state, .cclaw/hooks, or .cclaw/skills by ad-hoc edits unless using cclaw-managed commands.";
61
- readonly rationale: "Protects generated runtime integrity and avoids drift that silently breaks hooks or skills.";
62
- readonly enforcement: "PreToolUse";
63
- readonly severity: "hard-gate";
64
- readonly appliesTo: "all";
65
- readonly hookMatcher: {
66
- readonly toolPattern: "write|edit|multiedit|delete|applypatch|shell|bash";
67
- readonly payloadPattern: "\\.cclaw/(state|hooks|skills)";
68
- };
69
- }, {
70
- readonly id: "flow-state-read-fresh";
71
- readonly title: "Fresh flow-state read required";
72
- readonly rule: "Before mutating actions, a fresh read of .cclaw/state/flow-state.json must exist within guard freshness window.";
73
- readonly rationale: "Prevents stale-stage mutations after context shifts or multi-agent divergence.";
74
- readonly enforcement: "PreToolUse";
75
- readonly severity: "hard-gate";
76
- readonly appliesTo: "all";
77
- }, {
78
- readonly id: "review-layer-order";
79
- readonly title: "Review layers are sequential";
80
- readonly rule: "Review stage must complete Layer 1 spec compliance before Layer 2 quality/security passes.";
81
- readonly rationale: "Stops premature quality discussion when acceptance criteria are not yet satisfied.";
82
- readonly enforcement: "PreToolUse";
83
- readonly severity: "hard-gate";
84
- readonly appliesTo: ["review"];
85
- }, {
86
- readonly id: "review-criticals-close-before-ship";
87
- readonly title: "No ship with open criticals";
88
- readonly rule: "Ship decisions are blocked when review-army contains open Critical findings or ship blockers.";
89
- readonly rationale: "Enforces explicit risk closure before release finalization.";
90
- readonly enforcement: "PreToolUse";
91
- readonly severity: "hard-gate";
92
- readonly appliesTo: ["ship"];
93
- }, {
94
- readonly id: "ship-preflight-required";
95
- readonly title: "Preflight required before finalization";
96
- readonly rule: "Do not execute release finalization actions until ship preflight gate is passed.";
97
- readonly rationale: "Catches regressions before irreversible release steps.";
98
- readonly enforcement: "PreToolUse";
99
- readonly severity: "hard-gate";
100
- readonly appliesTo: ["ship"];
101
- }, {
102
- readonly id: "review-coverage-complete-before-ship";
103
- readonly title: "Review layer coverage before ship";
104
- readonly rule: "Block ship finalization when review-army does not confirm full Layer 1/2 coverage map.";
105
- readonly rationale: "Prevents finalization when multi-pass review evidence is incomplete or partially missing.";
106
- readonly enforcement: "PreToolUse";
107
- readonly severity: "hard-gate";
108
- readonly appliesTo: ["ship"];
109
- }, {
110
- readonly id: "subagent-task-self-contained";
111
- readonly title: "Subagent tasks are self-contained";
112
- readonly rule: "Delegated tasks must include explicit objective, constraints, and expected output, not just references.";
113
- readonly rationale: "Avoids context loss and low-quality delegation in isolated worker contexts.";
114
- readonly enforcement: "advisory";
115
- readonly severity: "soft-gate";
116
- readonly appliesTo: "all";
117
- }, {
118
- readonly id: "no-secrets-in-artifacts";
119
- readonly title: "Never log secrets in artifacts";
120
- readonly rule: "Secrets/tokens/passwords must not be written to review, ship, or runtime state artifacts.";
121
- readonly rationale: "Prevents accidental credential leakage through generated workflow artifacts.";
122
- readonly enforcement: "PostToolUse";
123
- readonly severity: "hard-gate";
124
- readonly appliesTo: "all";
125
- }, {
126
- readonly id: "stop-clean-or-handoff";
127
- readonly title: "Stop only from clean handoff";
128
- readonly rule: "Do not end a session with dirty state unless the current artifact records unresolved work and blockers.";
129
- readonly rationale: "Protects continuity and prevents silent half-finished sessions.";
130
- readonly enforcement: "Stop";
131
- readonly severity: "hard-gate";
132
- readonly appliesTo: "all";
133
- }];
134
- export declare function isIronLawId(value: string): boolean;
135
- export declare function normalizeStrictLawIds(ids: string[] | undefined): string[];
136
- export declare function ironLawRuntimeDocument(options?: {
137
- mode?: "advisory" | "strict";
138
- strictLaws?: string[];
139
- nowIso?: string;
140
- }): IronLawRuntimeDocument;
141
- export declare function ironLawsSkillMarkdown(): string;
6
+ export declare const IRON_LAWS: IronLaw[];
7
+ export declare function ironLawsMarkdown(): string;
@@ -1,210 +1,31 @@
1
- import { RUNTIME_ROOT } from "../constants.js";
2
1
  export const IRON_LAWS = [
3
2
  {
4
- id: "tdd-red-before-write",
5
- title: "RED before production write",
6
- rule: "Do not edit production code in tdd stage before a failing RED test exists for the slice.",
7
- rationale: "Prevents implementation-first behavior and keeps RED as executable specification.",
8
- enforcement: "PreToolUse",
9
- severity: "hard-gate",
10
- appliesTo: ["tdd"],
11
- hookMatcher: {
12
- toolPattern: "write|edit|multiedit|applypatch|shell|bash",
13
- payloadPattern: "\\.(ts|tsx|js|jsx|py|go|java|rs|rb|php|c|cc|cpp|h|hpp)"
14
- }
3
+ id: "think-before-coding",
4
+ title: "Think Before Coding",
5
+ description: "Read enough of the codebase to write the change correctly the first time. Skipping the read step is the most common cause of cascading errors and hallucinated actions."
15
6
  },
16
7
  {
17
- id: "plan-requires-approval",
18
- title: "No implementation before plan approval",
19
- rule: "Do not perform write-like actions while plan stage is pending WAIT_FOR_CONFIRM approval.",
20
- rationale: "Locks intent before execution and reduces expensive rework from unapproved paths.",
21
- enforcement: "PreToolUse",
22
- severity: "hard-gate",
23
- appliesTo: ["plan"]
8
+ id: "simplicity-first",
9
+ title: "Simplicity First",
10
+ description: "Pick the smallest design that satisfies the acceptance criteria. Resist abstractions, configuration knobs, and indirection that no AC asks for."
24
11
  },
25
12
  {
26
- id: "runtime-writes-managed-only",
27
- title: "Runtime writes are managed",
28
- rule: `Do not mutate ${RUNTIME_ROOT}/state, ${RUNTIME_ROOT}/hooks, or ${RUNTIME_ROOT}/skills by ad-hoc edits unless using cclaw-managed commands.`,
29
- rationale: "Protects generated runtime integrity and avoids drift that silently breaks hooks or skills.",
30
- enforcement: "PreToolUse",
31
- severity: "hard-gate",
32
- appliesTo: "all",
33
- hookMatcher: {
34
- toolPattern: "write|edit|multiedit|delete|applypatch|shell|bash",
35
- payloadPattern: "\\.cclaw/(state|hooks|skills)"
36
- }
13
+ id: "surgical-changes",
14
+ title: "Surgical Changes",
15
+ description: "Touch only what each AC requires. If a change starts pulling in unrelated files, stop and split the task scope creep is one of the five review failure modes."
37
16
  },
38
17
  {
39
- id: "flow-state-read-fresh",
40
- title: "Fresh flow-state read required",
41
- rule: `Before mutating actions, a fresh read of ${RUNTIME_ROOT}/state/flow-state.json must exist within guard freshness window.`,
42
- rationale: "Prevents stale-stage mutations after context shifts or multi-agent divergence.",
43
- enforcement: "PreToolUse",
44
- severity: "hard-gate",
45
- appliesTo: "all"
18
+ id: "goal-driven-execution",
19
+ title: "Goal-Driven Execution",
20
+ description: "Every action must move a specific AC closer to committed status. If the action does not, do not run it; record the question for the user."
46
21
  },
47
22
  {
48
- id: "review-layer-order",
49
- title: "Review layers are sequential",
50
- rule: "Review stage must complete Layer 1 spec compliance before Layer 2 quality/security passes.",
51
- rationale: "Stops premature quality discussion when acceptance criteria are not yet satisfied.",
52
- enforcement: "PreToolUse",
53
- severity: "hard-gate",
54
- appliesTo: ["review"]
55
- },
56
- {
57
- id: "review-criticals-close-before-ship",
58
- title: "No ship with open criticals",
59
- rule: "Ship decisions are blocked when review-army contains open Critical findings or ship blockers.",
60
- rationale: "Enforces explicit risk closure before release finalization.",
61
- enforcement: "PreToolUse",
62
- severity: "hard-gate",
63
- appliesTo: ["ship"]
64
- },
65
- {
66
- id: "ship-preflight-required",
67
- title: "Preflight required before finalization",
68
- rule: "Do not execute release finalization actions until ship preflight gate is passed.",
69
- rationale: "Catches regressions before irreversible release steps.",
70
- enforcement: "PreToolUse",
71
- severity: "hard-gate",
72
- appliesTo: ["ship"]
73
- },
74
- {
75
- id: "review-coverage-complete-before-ship",
76
- title: "Review layer coverage before ship",
77
- rule: "Block ship finalization when review-army does not confirm full Layer 1/2 coverage map.",
78
- rationale: "Prevents finalization when multi-pass review evidence is incomplete or partially missing.",
79
- enforcement: "PreToolUse",
80
- severity: "hard-gate",
81
- appliesTo: ["ship"]
82
- },
83
- {
84
- id: "subagent-task-self-contained",
85
- title: "Subagent tasks are self-contained",
86
- rule: "Delegated tasks must include explicit objective, constraints, and expected output, not just references.",
87
- rationale: "Avoids context loss and low-quality delegation in isolated worker contexts.",
88
- enforcement: "advisory",
89
- severity: "soft-gate",
90
- appliesTo: "all"
91
- },
92
- {
93
- id: "no-secrets-in-artifacts",
94
- title: "Never log secrets in artifacts",
95
- rule: "Secrets/tokens/passwords must not be written to review, ship, or runtime state artifacts.",
96
- rationale: "Prevents accidental credential leakage through generated workflow artifacts.",
97
- enforcement: "PostToolUse",
98
- severity: "hard-gate",
99
- appliesTo: "all"
100
- },
101
- {
102
- id: "stop-clean-or-handoff",
103
- title: "Stop only from clean handoff",
104
- rule: "Do not end a session with dirty state unless the current artifact records unresolved work and blockers.",
105
- rationale: "Protects continuity and prevents silent half-finished sessions.",
106
- enforcement: "Stop",
107
- severity: "hard-gate",
108
- appliesTo: "all"
23
+ id: "red-before-green",
24
+ title: "No Production Code Without a Failing Test First",
25
+ description: "Build is a TDD cycle. Every AC starts with a failing test (RED), then the minimal implementation that makes it pass (GREEN), then the refactor that keeps it passing (REFACTOR). The RED failure is the spec; never write production code before it exists."
109
26
  }
110
27
  ];
111
- export function isIronLawId(value) {
112
- return IRON_LAWS.some((law) => law.id === value);
113
- }
114
- export function normalizeStrictLawIds(ids) {
115
- if (!Array.isArray(ids))
116
- return [];
117
- const unique = new Set();
118
- for (const id of ids) {
119
- if (typeof id !== "string")
120
- continue;
121
- const trimmed = id.trim();
122
- if (!trimmed || !isIronLawId(trimmed))
123
- continue;
124
- unique.add(trimmed);
125
- }
126
- return [...unique];
127
- }
128
- export function ironLawRuntimeDocument(options = {}) {
129
- const mode = options.mode === "strict" ? "strict" : "advisory";
130
- const strictLawSet = new Set(normalizeStrictLawIds(options.strictLaws));
131
- const laws = IRON_LAWS.map((law) => ({
132
- id: law.id,
133
- title: law.title,
134
- rule: law.rule,
135
- enforcement: law.enforcement,
136
- severity: law.severity,
137
- appliesTo: law.appliesTo === "all" ? "all" : [...law.appliesTo],
138
- strict: mode === "strict" || strictLawSet.has(law.id),
139
- hookMatcher: "hookMatcher" in law ? law.hookMatcher : undefined
140
- }));
141
- return {
142
- version: 1,
143
- generatedAt: options.nowIso ?? new Date().toISOString(),
144
- mode,
145
- strictLaws: [...strictLawSet],
146
- laws
147
- };
148
- }
149
- function appliesToLabel(law) {
150
- return law.appliesTo === "all" ? "all stages" : law.appliesTo.join(", ");
151
- }
152
- function hardGateReference(law) {
153
- if (law.appliesTo === "all") {
154
- return "the active stage `HARD-GATE` block in `.cclaw/skills/<stage>/SKILL.md`";
155
- }
156
- return law.appliesTo
157
- .map((stage) => `\`${RUNTIME_ROOT}/skills/${stage}/SKILL.md\` (${stage} HARD-GATE)`)
158
- .join(", ");
159
- }
160
- export function ironLawsSkillMarkdown() {
161
- // Phase A purged the `PreToolUse` / `PostToolUse` / pre-tool
162
- // pipeline handlers, so `review-coverage-complete-before-ship` is no
163
- // longer hook-enforced — it now lives in the ship stage HARD-GATE.
164
- // Only `stop-clean-or-handoff` (Stop hook) is still hook-enforced;
165
- // everything else is stage-owned advisory.
166
- const enforcedLawIds = new Set([
167
- "stop-clean-or-handoff"
168
- ]);
169
- const enforced = IRON_LAWS.filter((law) => enforcedLawIds.has(law.id));
170
- const advisory = IRON_LAWS.filter((law) => !enforcedLawIds.has(law.id));
171
- const enforcedSections = enforced.map((law, index) => {
172
- return `### ${index + 1}. ${law.title}
173
-
174
- - **ID:** \`${law.id}\`
175
- - **Rule:** ${law.rule}
176
- - **Why:** ${law.rationale}
177
- - **Applies to:** ${appliesToLabel(law)}
178
- - **Enforced by:** ${law.enforcement} (${law.severity})
179
- `;
180
- }).join("\n");
181
- const advisoryList = advisory
182
- .map((law) => `- \`${law.id}\` — applies to ${appliesToLabel(law)}; see ${hardGateReference(law)}.`)
183
- .join("\n");
184
- return `---
185
- name: iron-laws
186
- description: "Non-negotiable workflow constraints enforced by cclaw hooks and routing."
187
- ---
188
-
189
- # Iron Laws
190
-
191
- These are cclaw's non-negotiable constraints for harness sessions.
192
- Use them as the final arbitration layer when local instructions conflict.
193
-
194
- ## Hook-Enforced Runtime Laws
195
-
196
- ${enforcedSections}
197
-
198
- ## Advisory Laws (Stage-Owned)
199
-
200
- The following laws remain active guidance, but their canonical enforcement surface
201
- is each stage's \`HARD-GATE\` contract:
202
-
203
- ${advisoryList}
204
-
205
- ## Practical rule
206
-
207
- If a law says stop, stop and surface the blocking reason with the smallest safe
208
- next step.
209
- `;
28
+ export function ironLawsMarkdown() {
29
+ const sections = IRON_LAWS.map((law, index) => `${index + 1}. **${law.title}** ${law.description}`).join("\n");
30
+ return `## Iron Laws (Karpathy)\n\n${sections}\n`;
210
31
  }
@@ -1,3 +1 @@
1
- export declare const META_SKILL_NAME = "using-cclaw";
2
- export declare const META_SKILL_GENERATED_HELPER_SKILLS: readonly ["subagent-dev", "parallel-dispatch", "session", "iron-laws"];
3
- export declare function usingCclawSkillMarkdown(): string;
1
+ export declare const META_SKILL = "---\nname: cclaw-meta\ntrigger: always-on; loaded with every /cc invocation\n---\n\n# Meta-skill \u2014 how to be a cclaw orchestrator\n\nThis skill is loaded by the harness with every `/cc` invocation. It does not duplicate `/cc` itself; it tells you **how to use** the rest of cclaw's content.\n\n## What is in your context\n\nWhen `/cc` runs, the harness has access to:\n\n- `.cursor/commands/cc.md` \u2014 your operating manual (also in `.cursor/skills/cclaw/` mirrors).\n- `.cclaw/lib/agents/*.md` \u2014 six specialist prompts.\n- `.cclaw/lib/skills/*.md` \u2014 six auto-trigger skills.\n- `.cclaw/lib/templates/*.md` \u2014 ten artifact templates.\n- `.cclaw/lib/runbooks/*.md` \u2014 four stage runbooks.\n- `.cclaw/lib/patterns/*.md` \u2014 eight task patterns.\n- `.cclaw/lib/research/*.md` \u2014 five research playbooks.\n- `.cclaw/lib/recovery/*.md` \u2014 five recovery playbooks.\n- `.cclaw/lib/decision-protocol.md` \u2014 D-N record format.\n- `.cclaw/lib/examples/*.md` \u2014 thirteen worked examples.\n- `.cclaw/lib/antipatterns.md` \u2014 twelve known failure modes.\n\n## How to read this content efficiently\n\nYou do not need to read everything. The right loading pattern:\n\n1. **Always read `/cc`** \u2014 your operating manual.\n2. **Read the runbook** for the stage you are in (`.cclaw/lib/runbooks/<stage>.md`).\n3. **Read the pattern(s)** that match the task (`.cclaw/lib/patterns/`).\n4. **Read the specialist prompt** when you invoke a specialist (`.cclaw/lib/agents/<id>.md`).\n5. **Read the recovery playbook** when an automated check fails.\n6. **Read examples** when authoring an artifact you have not seen before.\n\nDon't read research playbooks unless you're invoking planner mode=`research`. Don't read antipatterns proactively; the reviewer cites them as findings.\n\n## Your responsibilities as orchestrator\n\n1. **Sanity check first.** Always verify `flow-state.json` schemaVersion=2 before doing anything.\n2. **Detect existing plans.** Always run existing-plan detection before authoring a new plan.\n3. **Calibrate routing.** Always run Phase 0 calibration; never skip to specialists for a trivial task.\n4. **Ask before invoking specialists.** Never silently invoke. The user picks.\n5. **Ask before push / PR.** Always; every time; per turn.\n6. **Surface, don't decide.** When a checkpoint, conflict, or cap-reached situation appears, present options to the user. Do not decide on their behalf.\n7. **Cite, don't invent.** Every file:line reference in your output must be real. Reviewer adversarial mode will catch you.\n\n## Your boundaries\n\n- You do not write code. `slice-builder` does.\n- You do not author decisions alone. `architect` does.\n- You do not enforce AC traceability. `commit-helper.mjs` does.\n- You do not delete artifacts. `/cc-cancel` does.\n- You do not push or open PRs without explicit user approval.\n\n## Iron laws (always-on)\n\n1. **Think before coding.** Read the targets first. Cite `file:line`.\n2. **Simplicity first.** The smallest correct change wins.\n3. **Surgical changes.** Touch only declared files.\n4. **Goal-driven execution.** AC are the contract; everything else is implementation detail.\n\n## Five failure modes (always-on)\n\nWhen in doubt, ask: am I about to commit one of these?\n\n1. Hallucinated actions (invented files / ids / flags).\n2. Scope creep (changes outside declared AC).\n3. Cascading errors (fix breaks something else).\n4. Context loss (forgot earlier decision).\n5. Tool misuse (wrong mode / destructive action).\n\nIf yes, stop and surface.\n\n## When the user pushes back\n\nTrust the user's calibration. If they say \"this feels weak\", they are not asking for reassurance \u2014 they are asking for more depth. Open more content (patterns, examples, recovery), broaden the AC set, invoke the missing specialist. Do not defend the current state.\n\nIf they say \"this feels overcomplicated\", they are asking for less. Skip specialists, shorten Context, drop optional sections. Trivial tasks should not run the full chain.\n";