@aiwg/cli 2026.11.4 → 2026.11.6

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 (192) hide show
  1. package/agentic/code/providers/capability-matrix.yaml +75 -5
  2. package/agentic/code/providers/model-capabilities.v1.json +44 -36
  3. package/bin/aiwg.mjs +6 -4
  4. package/dist/src/activity-log/cli.js +1 -1
  5. package/dist/src/agents/agent-deployer.js +1 -1
  6. package/dist/src/artifacts/audit/types.js +1 -1
  7. package/dist/src/artifacts/discover-facets.js +1 -1
  8. package/dist/src/artifacts/enrichment/prompt.js +1 -1
  9. package/dist/src/artifacts/enrichment/types.js +1 -1
  10. package/dist/src/artifacts/index-builder.js +4 -2
  11. package/dist/src/artifacts/query-engine-rules.js +2 -2
  12. package/dist/src/artifacts/types.js +1 -1
  13. package/dist/src/artifacts/views/definition.js +1 -1
  14. package/dist/src/artifacts/views/types.js +1 -1
  15. package/dist/src/catalog/cli.js +1 -1
  16. package/dist/src/catalog/cli.mjs +1 -1
  17. package/dist/src/catalog/loader.js +1 -1
  18. package/dist/src/catalog/loader.mjs +1 -1
  19. package/dist/src/catalog/types.js +1 -1
  20. package/dist/src/cli/cli-extension-loader.js +19 -5
  21. package/dist/src/cli/cli-extension-paths.js +65 -0
  22. package/dist/src/cli/handlers/best-practices-audit.js +1 -1
  23. package/dist/src/cli/handlers/help.js +3 -4
  24. package/dist/src/cli/handlers/index.js +1 -1
  25. package/dist/src/cli/handlers/marketplace-plugin-search.js +37 -0
  26. package/dist/src/cli/handlers/marketplace.js +3 -1
  27. package/dist/src/cli/handlers/models.js +1 -1
  28. package/dist/src/cli/handlers/ralph-launcher.js +8 -2
  29. package/dist/src/cli/handlers/ralph.js +1 -1
  30. package/dist/src/cli/handlers/runtime-info.js +1 -1
  31. package/dist/src/cli/handlers/scaffolding.js +2 -2
  32. package/dist/src/cli/handlers/script-runner.js +8 -5
  33. package/dist/src/cli/handlers/sdlc-accelerate.js +1 -1
  34. package/dist/src/cli/handlers/steward-format.js +12 -0
  35. package/dist/src/cli/handlers/subcommands-bundles.js +1 -1
  36. package/dist/src/cli/handlers/subcommands-list-format.js +19 -1
  37. package/dist/src/cli/handlers/types.js +1 -1
  38. package/dist/src/cli/handlers/use.js +15 -6
  39. package/dist/src/cli/handlers/utilities.js +1 -1
  40. package/dist/src/cli/handlers/utility-doctor.js +4 -0
  41. package/dist/src/cli/handlers/version.js +1 -1
  42. package/dist/src/cli/handlers/workspace.js +1 -1
  43. package/dist/src/cli/help-generator.js +9 -11
  44. package/dist/src/cli/hooks/builtin/activity-log-hook.js +1 -1
  45. package/dist/src/cli/router.js +1 -1
  46. package/dist/src/cli/workflow-orchestrator.js +1 -1
  47. package/dist/src/config/worker-context.js +37 -7
  48. package/dist/src/config/worker-parallelism.js +11 -0
  49. package/dist/src/contributors/detect.js +1 -1
  50. package/dist/src/contributors/discover.js +1 -1
  51. package/dist/src/contributors/heuristic.js +1 -1
  52. package/dist/src/contributors/index.js +1 -1
  53. package/dist/src/contributors/types.js +1 -1
  54. package/dist/src/contributors/validation.js +1 -1
  55. package/dist/src/effects/worker-delivery.js +83 -0
  56. package/dist/src/extensions/capability-index.js +1 -1
  57. package/dist/src/extensions/commands/definitions.js +2 -2
  58. package/dist/src/extensions/deployment-registration.js +1 -1
  59. package/dist/src/extensions/index.js +1 -1
  60. package/dist/src/extensions/loader.js +1 -1
  61. package/dist/src/extensions/manifest.js +10 -2
  62. package/dist/src/extensions/project-local-activity.js +1 -1
  63. package/dist/src/extensions/project-local-discovery.js +23 -3
  64. package/dist/src/extensions/project-local-doctor.js +7 -3
  65. package/dist/src/extensions/project-local-promote.js +3 -3
  66. package/dist/src/extensions/project-local-remove.js +3 -3
  67. package/dist/src/extensions/project-local-scaffold.js +20 -8
  68. package/dist/src/extensions/registry.js +1 -1
  69. package/dist/src/extensions/shadow-resolver.js +1 -1
  70. package/dist/src/extensions/types.js +1 -1
  71. package/dist/src/extensions/upstream-registry.js +1 -1
  72. package/dist/src/extensions/validation.js +1 -1
  73. package/dist/src/intake/git-history-analyzer.js +1 -1
  74. package/dist/src/kb/cli.js +1 -1
  75. package/dist/src/marketplace/plugin-directory.js +36 -0
  76. package/dist/src/marketplace/plugin-search.js +180 -0
  77. package/dist/src/mcp/cli.mjs +2 -2
  78. package/dist/src/mcp/helpers.mjs +1 -1
  79. package/dist/src/mcp/http-tools.mjs +8 -6
  80. package/dist/src/mcp/http-transport.mjs +3 -1
  81. package/dist/src/mcp/server.mjs +1 -1
  82. package/dist/src/mcp/tools/command-run.mjs +1 -1
  83. package/dist/src/mcp/tools/discovery.mjs +1 -1
  84. package/dist/src/mcp/tools/subsystems.mjs +1 -1
  85. package/dist/src/mcp/tools/worker-invoke.mjs +68 -22
  86. package/dist/src/mcp/tools/worker-local-only-preflight.mjs +79 -0
  87. package/dist/src/mcp/tools/worker-recorded-launch.mjs +26 -0
  88. package/dist/src/mcp/tools/worker-stdin-runtime.mjs +33 -6
  89. package/dist/src/mcp/tools/worker-verify-deliver-schema.mjs +33 -0
  90. package/dist/src/mcp/tools/worker-verify-deliver.mjs +27 -0
  91. package/dist/src/models/catalog-policy.js +2 -2
  92. package/dist/src/models/conductor-data-policy.mjs +83 -14
  93. package/dist/src/models/config-loader.js +2 -2
  94. package/dist/src/models/factory-models.js +144 -0
  95. package/dist/src/models/index.js +2 -2
  96. package/dist/src/models/local-endpoint-models.js +155 -0
  97. package/dist/src/models/model-capabilities.v1.json +44 -36
  98. package/dist/src/models/model-discovery.js +16 -8
  99. package/dist/src/models/opencode-worker-model.mjs +16 -0
  100. package/dist/src/models/resolver.js +2 -2
  101. package/dist/src/models/worker-installation.d.mts +2 -0
  102. package/dist/src/models/worker-installation.mjs +16 -5
  103. package/dist/src/models/worker-invocation-policy.js +25 -1
  104. package/dist/src/models/worker-plan.js +1 -1
  105. package/dist/src/models/wrapper-enforcement.js +1 -1
  106. package/dist/src/plugin/plugin-installer.js +2 -2
  107. package/dist/src/plugin/registry-validator.js +2 -2
  108. package/dist/src/plugin/skill-command-translator.js +1 -1
  109. package/dist/src/policy/repo-access.js +3 -1
  110. package/dist/src/providers/capability-matrix.yaml +75 -5
  111. package/dist/src/providers/deployment-ownership.mjs +8 -1
  112. package/dist/src/providers/deployment-preservation.mjs +44 -3
  113. package/dist/src/providers/grok-build-acp.js +13 -5
  114. package/dist/src/providers/grok-build-dispatch.js +35 -2
  115. package/dist/src/providers/grok-build-headless.js +2 -1
  116. package/dist/src/rlm/cache/hash.js +1 -1
  117. package/dist/src/rlm/cache/store.js +1 -1
  118. package/dist/src/rlm/cache/types.js +1 -1
  119. package/dist/src/serve/worker-invocation-preparation.js +13 -0
  120. package/dist/src/serve/worker-invocation.js +21 -6
  121. package/dist/src/serve/worker-stdin-frame.mjs +1 -1
  122. package/dist/src/sessions/adapters/grok-build-native-records.js +77 -7
  123. package/dist/src/sessions/adapters/grok-build-native.js +148 -1
  124. package/dist/src/sessions/adapters/grok-build.js +36 -14
  125. package/dist/src/sessions/normalization.js +1 -1
  126. package/dist/src/skills/run.js +0 -11
  127. package/dist/src/smiths/agentsmith/generator.js +1 -1
  128. package/dist/src/smiths/context-pipeline/index.js +1 -1
  129. package/dist/src/smiths/context-pipeline/provider-policy.js +1 -1
  130. package/dist/src/smiths/context-pipeline/types.js +1 -1
  131. package/dist/src/smiths/context-pipeline/workspace-doctor.js +4 -0
  132. package/dist/src/smiths/hook-bridge/factory-trust.js +2 -2
  133. package/dist/src/smiths/hook-bridge/hermes-prompt-discovery.js +10 -7
  134. package/dist/src/smiths/hook-bridge/hermes-trust.js +65 -0
  135. package/dist/src/smiths/mcpsmith/analyzers/cli-analyzer.js +2 -2
  136. package/dist/src/smiths/mcpsmith/generator.js +2 -2
  137. package/dist/src/smiths/mcpsmith/index.js +2 -2
  138. package/dist/src/smiths/mcpsmith/types.js +2 -2
  139. package/dist/src/smiths/skillsmith/collision-detector.js +1 -1
  140. package/dist/src/smiths/skillsmith/namespace-adapter.js +1 -1
  141. package/dist/src/smiths/toolsmith/runtime-discovery.mjs +2 -2
  142. package/dist/src/smiths/toolsmith/types.js +2 -2
  143. package/dist/src/storage/backends/fortemi.js +1 -1
  144. package/dist/src/storage/backends/fs.js +1 -1
  145. package/dist/src/storage/backends/logseq.js +1 -1
  146. package/dist/src/storage/backends/obsidian.js +1 -1
  147. package/dist/src/storage/cli.js +2 -2
  148. package/dist/src/storage/config.js +1 -1
  149. package/dist/src/storage/index.js +1 -1
  150. package/dist/src/storage/subsystem-cli.js +1 -1
  151. package/dist/src/storage/types.js +1 -1
  152. package/dist/src/testing/generators/test-case-generator.js +1 -1
  153. package/dist/src/writing/validation-engine.js +1 -1
  154. package/package.json +11 -1
  155. package/schemas/models/model-catalog.v1.schema.json +6 -3
  156. package/tools/agents/deploy-agents.mjs +4 -2
  157. package/tools/agents/deploy-options.mjs +2 -0
  158. package/tools/agents/providers/base-inventory.mjs +3 -1
  159. package/tools/agents/providers/base-kernel-skills.mjs +11 -5
  160. package/tools/agents/providers/conductor-data-guard.mjs +1 -1
  161. package/tools/agents/providers/grok-build.mjs +31 -40
  162. package/tools/agents/providers/model-wrapper.mjs +2 -5
  163. package/tools/agents/providers/rule-deployment-commit.mjs +3 -0
  164. package/tools/agents/providers/rule-deployment-prepare.mjs +2 -2
  165. package/tools/agents/providers/rule-projection.mjs +39 -4
  166. package/tools/agents/providers/skill-copy-prune.mjs +12 -0
  167. package/tools/agents/providers/stale-artifact-prune.mjs +24 -10
  168. package/tools/ralph-external/lib/claude-adapter.mjs +2 -0
  169. package/tools/ralph-external/lib/factory-adapter.mjs +6 -2
  170. package/tools/ralph-external/lib/mcp-worker-launch.mjs +67 -0
  171. package/tools/ralph-external/lib/opencode-adapter.mjs +9 -7
  172. package/tools/ralph-external/lib/trusted-verification.mjs +1021 -0
  173. package/tools/ralph-external/lib/typed-stop-delivery.mjs +46 -0
  174. package/tools/ralph-external/lib/verification-isolation.mjs +509 -0
  175. package/tools/ralph-external/lib/worker-context.mjs +3 -3
  176. package/tools/ralph-external/lib/worker-delivery-guards.mjs +95 -0
  177. package/tools/ralph-external/lib/worker-delivery-record.mjs +15 -0
  178. package/tools/ralph-external/lib/worker-final.mjs +4 -1
  179. package/tools/ralph-external/lib/worker-inputs.mjs +20 -1
  180. package/tools/ralph-external/lib/worker-isolation-status.mjs +3 -0
  181. package/tools/ralph-external/lib/worker-isolation.mjs +1 -0
  182. package/tools/ralph-external/lib/worker-launch-cli.mjs +8 -0
  183. package/tools/ralph-external/lib/worker-local-only-paths.mjs +45 -0
  184. package/tools/ralph-external/lib/worker-prompt.mjs +4 -1
  185. package/tools/ralph-external/lib/worker-retry-evidence.mjs +2 -1
  186. package/tools/ralph-external/lib/worker-run-directory.mjs +45 -0
  187. package/tools/ralph-external/lib/worker-termination.mjs +21 -12
  188. package/tools/ralph-external/lib/worker-unit-cleanup.mjs +10 -2
  189. package/tools/ralph-external/lib/worker-verification-cli.mjs +164 -0
  190. package/tools/ralph-external/lib/worktree-preparation.mjs +417 -0
  191. package/tools/ralph-external/session-launcher.mjs +30 -32
  192. package/vscode-extension/schemas/aiwg.config.v1.json +27 -0
@@ -11,7 +11,7 @@
11
11
  * Failures are non-blocking: if the entry can't be written, we log to
12
12
  * stderr and let the primary command's success stand.
13
13
  *
14
- * @design @.aiwg/architecture/storage-design.md
14
+ * @design @docs/storage/overview.md
15
15
  * @issue #934
16
16
  * @issue #978
17
17
  */
@@ -6,7 +6,7 @@
6
6
  * Integrates hook system for lifecycle events.
7
7
  *
8
8
  * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
9
- * @architecture @.aiwg/architecture/decisions/ADR-001-unified-extension-system.md
9
+ * @architecture @docs/architecture/cli/adr-001-unified-extension-registry.md
10
10
  * @tests @test/unit/cli/router.test.ts
11
11
  * @issue #33
12
12
  * @issue #58
@@ -5,7 +5,7 @@
5
5
  * Supports batch processing, watch mode, auto-fix, and multiple output formats.
6
6
  *
7
7
  * @implements @.aiwg/requirements/use-cases/UC-001-validate-ai-generated-content.md
8
- * @architecture @.aiwg/architecture/software-architecture-doc.md - Section 4.2 Core Orchestrator
8
+ * @architecture @docs/architecture/cli/index.md
9
9
  * @tests @test/unit/cli/workflow-orchestrator.test.ts
10
10
  * @depends @src/writing/validation-engine.ts
11
11
  * @depends @src/writing/prompt-optimizer.ts
@@ -13,7 +13,8 @@
13
13
  * config through `readAiwgConfig` and injects it here; direct callers may
14
14
  * pass an already-loaded config object instead.
15
15
  */
16
- import { existsSync, readdirSync, readFileSync } from 'node:fs';
16
+ import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
17
+ import { tmpdir } from 'node:os';
17
18
  import { spawnSync } from 'node:child_process';
18
19
  import path from 'node:path';
19
20
  import { getProviderArtifactPathStrings, getProviderDefinition, normalizeProviderDefinitionId, } from '../providers/provider-definitions.js';
@@ -239,7 +240,8 @@ export async function syncWorkerContextProviders(options) {
239
240
  }
240
241
  /**
241
242
  * Canonical one-pass deploy argv: a single `aiwg use all` invocation
242
- * covering every listed provider. Never one deploy per provider:
243
+ * covering every listed provider, or explicitly selecting one project-local
244
+ * launch provider. Never one deploy per provider in a union preparation:
243
245
  * per-provider invocations rewrite AGENTS.md piecemeal and clobber each
244
246
  * other's rule sections, while one pass keeps them all. No `--providers`
245
247
  * flag: it feeds only the global bootstrap and the orchestrated
@@ -249,14 +251,32 @@ export async function syncWorkerContextProviders(options) {
249
251
  * configured-provider path: `syncWorkerContextProviders` first, then this
250
252
  * single pass reads the union back from the worktree config.
251
253
  */
252
- export function buildWorkerContextDeployArgs({ providers, target }) {
254
+ export function buildWorkerContextDeployArgs({ providers, target, selectedProvider }) {
253
255
  // Fail fast on a hostile list; the synced worktree config carries the set.
254
256
  validateExplicitWorkerContextProviders(providers);
257
+ if (selectedProvider !== undefined) {
258
+ validateExplicitWorkerContextProviders([selectedProvider]);
259
+ return ['use', 'all', '--provider', selectedProvider, '--scope', 'project', '--target', target, '--yes'];
260
+ }
255
261
  return ['use', 'all', '--target', target, '--yes'];
256
262
  }
263
+ /** Keep CLI bootstrap state and caches local to a launch-time context deploy. */
264
+ export function workerContextDeployEnv(workdir, env = process.env, scratch) {
265
+ const local = path.join(workdir, '.aiwg');
266
+ // Data and cache hold regenerable deploy output (the framework search index
267
+ // alone exceeds 100 MB). Inside the worker tree they break the verifier's
268
+ // tree digest, so a scratch directory outside the tree takes them (#4150).
269
+ return { ...env, HOME: workdir, USERPROFILE: workdir, AIWG_CONFIG: local,
270
+ XDG_CONFIG_HOME: path.join(local, 'config'), XDG_CACHE_HOME: path.join(scratch ?? local, 'cache'),
271
+ XDG_DATA_HOME: path.join(scratch ?? local, 'data'), XDG_STATE_HOME: path.join(local, 'state'),
272
+ AIWG_USER_REGISTRY_PATH: path.join(local, 'installed.json'),
273
+ AIWG_ARTIFACTS_PATH: local, AIWG_PROJECT_AIWG_DIR: local,
274
+ CODEX_HOME: path.join(workdir, '.codex'), HERMES_HOME: path.join(workdir, '.hermes') };
275
+ }
257
276
  /**
258
277
  * Ensure a worker workdir carries its CLI's AIWG bootstrap before launch.
259
- * Present: no-op. Missing: sync the union set into the workdir config,
278
+ * Present: no-op. Missing: select one provider for projectLocal launches;
279
+ * otherwise sync the union set into the workdir config,
260
280
  * then exactly one `aiwg use all` pass into the workdir (never anywhere
261
281
  * else), then re-verify. Impossible (no binary, failed deploy, still
262
282
  * missing afterwards): throw `WorkerContextBootstrapError` naming the
@@ -280,14 +300,15 @@ export async function ensureWorkerContextBootstrap(options) {
280
300
  const sync = options.syncFn ?? syncWorkerContextProviders;
281
301
  let synced;
282
302
  try {
283
- synced = await sync({ workdir, providers });
303
+ synced = options.projectLocal ? { providers: [provider], updated: false } : await sync({ workdir, providers });
284
304
  }
285
305
  catch (error) {
286
306
  if (error instanceof WorkerContextBootstrapError)
287
307
  throw error;
288
308
  throw new WorkerContextBootstrapError(`worker context sync failed: ${error instanceof Error ? error.message : String(error)}`, `write the union providers into ${path.join(workdir, '.aiwg', 'aiwg.config')} (or run 'aiwg use all --target ${workdir} --yes' manually) before launch`, { provider, workdir });
289
309
  }
290
- const argv = buildWorkerContextDeployArgs({ providers: synced.providers, target: workdir });
310
+ const argv = buildWorkerContextDeployArgs({ providers: synced.providers, target: workdir,
311
+ ...(options.projectLocal ? { selectedProvider: provider } : {}) });
291
312
  const deploy = options.deployFn ?? (({ worktreePath, providers: deployProviders, aiwgBin: bin }) => {
292
313
  // worktreePath IS the worker workdir by construction: the only
293
314
  // `--target` ever passed is `workdir` above, and the spawn cwd is the
@@ -295,7 +316,16 @@ export async function ensureWorkerContextBootstrap(options) {
295
316
  if (path.resolve(worktreePath) !== path.resolve(workdir)) {
296
317
  throw new WorkerContextBootstrapError(`refusing worker context deploy outside the worker workdir (${worktreePath} !== ${workdir})`, 'deploy worker context only into the worker workdir', { provider, workdir });
297
318
  }
298
- const result = spawn(bin, argv, { cwd: workdir, encoding: 'utf8', timeout: timeoutMs });
319
+ const scratch = options.projectLocal ? mkdtempSync(path.join(tmpdir(), 'aiwg-worker-deploy-')) : undefined;
320
+ let result;
321
+ try {
322
+ result = spawn(bin, argv, { cwd: workdir, encoding: 'utf8', timeout: timeoutMs,
323
+ ...(options.projectLocal ? { env: workerContextDeployEnv(workdir, process.env, scratch) } : {}) });
324
+ }
325
+ finally {
326
+ if (scratch)
327
+ rmSync(scratch, { recursive: true, force: true });
328
+ }
299
329
  if (result.error) {
300
330
  throw new WorkerContextBootstrapError(`worker context deploy failed to run (${result.error?.message});`
301
331
  + ` missing in ${workdir}: ${status.missing.join('; ')}`, `install the aiwg CLI on PATH or set AIWG_BIN to its location (tried '${bin}'),`
@@ -7,6 +7,7 @@ import { fileURLToPath } from 'node:url';
7
7
  import { PROVIDER_IDS } from '../providers/provider-definitions.js';
8
8
  import { isCanonicalWorkerModelKey, loadProviderModelCapabilities, resolveWorkerInstallation } from '../models/provider-policy.js';
9
9
  import { resolveDispatchHostThresholds } from './dispatch-thresholds-runtime.mjs';
10
+ import { localModelsUrl } from '../models/local-endpoint-models.js';
10
11
  import { expandWorkerGroupTemplates } from './worker-group-templates.js';
11
12
  let parallelismValidator;
12
13
  /** Offline shape and declaration validation. Qualification is checked at use time. */
@@ -37,6 +38,16 @@ export function validateParallelismConfig(value) {
37
38
  const error = (pointer, message) => { errors.push(`OG_CONFIG_REFERENCE /parallelism/${pointer}: ${message}`); };
38
39
  const builtinIds = new Set(PROVIDER_IDS.filter(id => id !== 'generic'));
39
40
  for (const [id, installation] of Object.entries(policy.clis ?? {})) {
41
+ if (installation.localModels) {
42
+ try {
43
+ localModelsUrl(installation.localModels);
44
+ }
45
+ catch {
46
+ error(`clis/${id}/localModels/endpoint`, 'Requires a credential-free HTTP endpoint on loopback or allowedHosts');
47
+ }
48
+ if (new Set(installation.localModels.models.map(model => model.id)).size !== installation.localModels.models.length)
49
+ error(`clis/${id}/localModels/models`, 'Duplicate model ID');
50
+ }
40
51
  if (installation.adapter.startsWith('providers:') && !builtinIds.has(installation.adapter.slice(10)))
41
52
  error(`clis/${id}/adapter`, 'Unknown provider binding');
42
53
  }
@@ -5,7 +5,7 @@
5
5
  * Determines whether the contributor's framework is *in use* on this project,
6
6
  * not just installed. Pure I/O — no code execution.
7
7
  *
8
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
8
+ * @architecture @docs/contributing/contributor-quickstart.md
9
9
  * @issue #938
10
10
  */
11
11
  import { glob } from 'glob';
@@ -6,7 +6,7 @@
6
6
  * runs detection on each candidate. Returns kept records and skipped entries
7
7
  * with reasons. Failures of one contributor never abort discovery.
8
8
  *
9
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
9
+ * @architecture @docs/contributing/contributor-quickstart.md
10
10
  * @issue #938
11
11
  */
12
12
  import { existsSync } from 'fs';
@@ -12,7 +12,7 @@
12
12
  * it only checks a small number of well-known paths and runs a handful of
13
13
  * bounded globs.
14
14
  *
15
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
15
+ * @architecture @docs/contributing/contributor-quickstart.md
16
16
  * @issue #941
17
17
  */
18
18
  import { existsSync, statSync } from 'fs';
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * Contributor Discovery — Public API
3
3
  *
4
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
4
+ * @architecture @docs/contributing/contributor-quickstart.md
5
5
  * @issue #938
6
6
  */
7
7
  export { discoverContributors } from './discover.js';
@@ -6,7 +6,7 @@
6
6
  * best-practices-audit, ...) by shipping `<framework>/<kind>/contributor.md`
7
7
  * files. The aggregator discovers, validates, and runs detection against them.
8
8
  *
9
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
9
+ * @architecture @docs/contributing/contributor-quickstart.md
10
10
  * @issue #938
11
11
  */
12
12
  export {};
@@ -5,7 +5,7 @@
5
5
  * keyed by kind so future consumers register their schema without forking the
6
6
  * discovery module.
7
7
  *
8
- * @architecture @.aiwg/architecture/decisions/ADR-023-contributor-discovery-convention.md
8
+ * @architecture @docs/contributing/contributor-quickstart.md
9
9
  * @issue #938
10
10
  */
11
11
  import { z } from 'zod';
@@ -0,0 +1,83 @@
1
+ // Signed publication receipts and current-byte lookup for verified worker artifacts.
2
+ import { readFile, realpath } from 'node:fs/promises';
3
+ import { dirname, basename, join } from 'node:path';
4
+ import { randomUUID } from 'node:crypto';
5
+ import { assertKeyring } from './keyring.js';
6
+ import { sha256Digest } from './identity.js';
7
+ import { recordIntent, recordOutcome } from './ledger.js';
8
+ import { readAllSegments, readKeyring, lineFailures } from './reader.js';
9
+ import { verifyLedger } from './verify.js';
10
+ import { ensureLedgerDirectories, withLedgerLock } from './store.js';
11
+ const canonicalDestination = async (destination) => join(await realpath(dirname(destination)), basename(destination));
12
+ /** A signed intent reserves the path even if publication crashed or bytes changed. */
13
+ async function reserveDelivery(ledger, delivery, target) {
14
+ const paths = ledger.paths();
15
+ await ensureLedgerDirectories(paths);
16
+ return withLedgerLock(paths, 'worker-delivery', ledger.lockTimeoutMs, async () => {
17
+ if (!(await verifyLedger(ledger, { checkIndex: false })).ok)
18
+ throw new Error('Delivery ledger integrity failed; publication refused');
19
+ const records = (await readAllSegments(paths)).flatMap(segment => segment.lines.flatMap(line => line.decoded ? [line.decoded] : []));
20
+ const conflict = records.some(({ statement: { predicate: p } }) => p.kind === 'file.digest' && p.target === `file:${target}`
21
+ && typeof p.context?.deliveryId === 'string' && (delivery.kind === 'typed-stop' || p.context?.kind === 'typed-stop'));
22
+ if (conflict)
23
+ throw Object.assign(new Error('TYPED_STOP_CONFLICT: a delivery record already exists for this path'), { code: 'TYPED_STOP_CONFLICT' });
24
+ const context = { artifactDigest: delivery.artifactDigest, verifierId: delivery.verifierId,
25
+ deliverablePath: target, deliveryId: randomUUID() };
26
+ if (delivery.kind)
27
+ context.kind = delivery.kind;
28
+ if (delivery.kind !== 'typed-stop') {
29
+ context.runDir = delivery.runDir;
30
+ context.invocationId = delivery.invocationId;
31
+ }
32
+ return recordIntent(ledger, { kind: 'file.digest', target: `file:${target}`, context, payloadDigest: delivery.artifactDigest });
33
+ });
34
+ }
35
+ /** Persist intent before publication, then complete only after the digest-checked rename. */
36
+ export async function prepareWorkerDelivery(ledger, delivery) {
37
+ if (delivery.kind === 'typed-stop' && (delivery.verifierId !== 'typed-stop@1' || 'runDir' in delivery || 'invocationId' in delivery)) {
38
+ throw Object.assign(new Error('TYPED_STOP_INVALID: typed stops cannot have worker lineage'), { code: 'TYPED_STOP_INVALID' });
39
+ }
40
+ const target = await canonicalDestination(delivery.deliverablePath);
41
+ const intent = await reserveDelivery(ledger, delivery, target);
42
+ return async () => {
43
+ if (sha256Digest(await readFile(target)) !== delivery.artifactDigest)
44
+ throw new Error('Published deliverable digest does not match acceptance; delivery record refused');
45
+ return recordOutcome(ledger, intent.effectId, { phase: 'completed', payloadDigest: delivery.artifactDigest,
46
+ verification: { verifier: { kind: 'file.digest', version: '1.0.0', canReportAbsent: false }, result: 'present', reason: 'digest-match', complete: true, checkedAt: ledger.now(), evidenceDigest: delivery.artifactDigest } });
47
+ };
48
+ }
49
+ /** Read-only: signatures/chains and a completed delivery must match the current bytes. */
50
+ export async function lookupWorkerDelivery(ledger, deliverablePath) {
51
+ let target, artifactDigest;
52
+ try {
53
+ target = await canonicalDestination(deliverablePath);
54
+ artifactDigest = sha256Digest(await readFile(target));
55
+ }
56
+ catch {
57
+ return { verified: false, deliverablePath, reason: 'deliverable-unreadable' };
58
+ }
59
+ const verification = await verifyLedger(ledger, { checkIndex: false });
60
+ if (!verification.ok)
61
+ return { verified: false, deliverablePath: target, artifactDigest, reason: 'ledger-integrity-failed' };
62
+ const records = (await readAllSegments(ledger.paths())).flatMap(segment => segment.lines.flatMap(line => line.decoded ? [line.decoded] : []));
63
+ const keyring = await readKeyring(ledger.paths());
64
+ if (!keyring)
65
+ return { verified: false, deliverablePath: target, artifactDigest, reason: 'ledger-empty' };
66
+ assertKeyring(keyring, ledger.scope);
67
+ const previous = new Map();
68
+ for (const record of records) {
69
+ if (lineFailures(keyring, ledger.scope, record.line.writer, record.line.seq, record, previous.get(record.line.writer) ?? null).length)
70
+ return { verified: false, deliverablePath: target, artifactDigest, reason: 'ledger-integrity-failed' };
71
+ previous.set(record.line.writer, record.line.recordHash);
72
+ }
73
+ const match = records.reverse().find(({ statement: { predicate: p } }) => p.kind === 'file.digest' && p.phase === 'completed'
74
+ && p.target === `file:${target}` && p.payloadDigest === artifactDigest && p.context?.artifactDigest === artifactDigest
75
+ && typeof p.context?.deliveryId === 'string' && typeof p.context?.verifierId === 'string'
76
+ && (p.context?.kind === 'typed-stop'
77
+ ? p.context.verifierId === 'typed-stop@1' && !('runDir' in p.context) && !('invocationId' in p.context)
78
+ : typeof p.context?.runDir === 'string' && typeof p.context?.invocationId === 'string'));
79
+ if (!match)
80
+ return { verified: false, deliverablePath: target, artifactDigest, reason: 'matching-delivery-missing' };
81
+ return { verified: true, ...match.statement.predicate.context, recordHash: match.line.recordHash };
82
+ }
83
+ //# sourceMappingURL=worker-delivery.js.map
@@ -2,7 +2,7 @@
2
2
  * CapabilityIndex - Capability-based extension discovery system
3
3
  *
4
4
  * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
5
- * @architecture @.aiwg/architecture/software-architecture-doc.md
5
+ * @architecture @docs/architecture/cli/index.md
6
6
  * @tests @test/unit/extensions/capability-index.test.ts
7
7
  */
8
8
  /**
@@ -4,8 +4,8 @@
4
4
  * Defines Extension objects for all CLI commands. Maps command handlers to the
5
5
  * unified Extension schema for discovery, semantic search, and help generation.
6
6
  *
7
- * @implements @.aiwg/architecture/decisions/ADR-001-unified-extension-system.md
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
7
+ * @implements @docs/architecture/cli/adr-001-unified-extension-registry.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  * @source @src/cli/handlers/index.ts
10
10
  * @tests @test/unit/extensions/commands/definitions.test.ts
11
11
  * @issue #42
@@ -5,7 +5,7 @@
5
5
  * and registers them in the extension registry for discovery.
6
6
  *
7
7
  * @implements #56, #57
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  * @tests @test/unit/extensions/deployment-registration.test.ts
10
10
  */
11
11
  import fs from 'fs';
@@ -5,7 +5,7 @@
5
5
  * capability indexing, and loading functionality for all extension types.
6
6
  *
7
7
  * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  */
10
10
  // Core types
11
11
  export * from './types.js';
@@ -5,7 +5,7 @@
5
5
  * capability indexes for fast lookup.
6
6
  *
7
7
  * @implements @.aiwg/requirements/use-cases/UC-004-extension-system.md
8
- * @architecture @.aiwg/architecture/unified-extension-schema.md
8
+ * @architecture @docs/architecture/cli/extending-cli.md
9
9
  * @tests @test/unit/extensions/loader.test.ts
10
10
  */
11
11
  import { getRegistry, createRegistry } from './registry.js';
@@ -3,14 +3,14 @@
3
3
  *
4
4
  * Validates `.aiwg/{extensions,addons,frameworks,plugins,providers}/<name>/manifest.json`
5
5
  * for project-local artifact bundles. Implements the design in
6
- * `.aiwg/architecture/design-manifest-schema.md` (#1044).
6
+ * `docs/project-local/manifest-reference.md` (#1044).
7
7
  *
8
8
  * Layered above the per-artifact Extension type validation in `validation.ts`:
9
9
  * the bundle manifest declares the bundle (a directory containing artifacts);
10
10
  * the existing schemas validate individual artifact bodies inside the bundle.
11
11
  *
12
12
  * @implements #1044
13
- * @architecture .aiwg/architecture/design-manifest-schema.md
13
+ * @architecture docs/project-local/manifest-reference.md
14
14
  */
15
15
  import { z } from 'zod';
16
16
  import { integer, dateTime, url } from '../schema/zod-validation.mjs';
@@ -49,6 +49,7 @@ const bundleNamePattern = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
49
49
  // Per-type config blocks
50
50
  // ============================================
51
51
  const ArtifactListsSchema = z.object({
52
+ flows: z.array(z.string()).max(200).optional(),
52
53
  agents: z.array(z.string()).max(200).optional(),
53
54
  skills: z.array(z.string()).max(500).optional(),
54
55
  rules: z.array(z.string()).max(200).optional(),
@@ -60,6 +61,7 @@ const ArtifactListsSchema = z.object({
60
61
  gatePacks: z.array(z.string().min(1).max(128)).max(50).optional(),
61
62
  });
62
63
  const EntryPathsSchema = z.strictObject({
64
+ flows: safeRelativePath.optional(),
63
65
  agents: safeRelativePath.optional(),
64
66
  skills: safeRelativePath.optional(),
65
67
  rules: safeRelativePath.optional(),
@@ -221,6 +223,12 @@ export const BundleManifestSchema = z.strictObject({
221
223
  author: z.string().max(128).optional(),
222
224
  license: z.string().max(64).optional(),
223
225
  repository: url().max(512).optional(),
226
+ // Addon inventory/flags use the same top-level shape as validate-addon and
227
+ // upstream manifests. Nested *Config declarations remain supported.
228
+ ...ArtifactListsSchema.shape,
229
+ core: z.boolean().optional(),
230
+ autoInstall: z.boolean().optional(),
231
+ devOnly: z.boolean().optional(),
224
232
  // Type-discriminated nested config (exactly one matches `type`)
225
233
  addonConfig: AddonConfigSchema.optional(),
226
234
  frameworkConfig: FrameworkConfigSchema.optional(),
@@ -10,7 +10,7 @@
10
10
  * per-event entries (per-bundle, per-provider) at finer granularity, as
11
11
  * specified by the design doc.
12
12
  *
13
- * @design @.aiwg/architecture/design-doctor-log-promote.md
13
+ * @design @docs/customization/project-local-lifecycle.md
14
14
  * @implements #1037
15
15
  * @issue #1049
16
16
  */
@@ -6,13 +6,31 @@
6
6
  * deployment side effects.
7
7
  *
8
8
  * @implements #1034
9
- * @architecture .aiwg/architecture/adr-aiwg-directory-layout.md (#1039)
10
- * @architecture .aiwg/architecture/design-manifest-schema.md (#1044)
9
+ * @architecture docs/architecture/cli/extending-cli.md (#1039)
10
+ * @architecture docs/project-local/manifest-reference.md (#1044)
11
11
  */
12
12
  import { readFile, readdir, lstat, stat, access, realpath } from 'fs/promises';
13
13
  import { join, relative, resolve, sep } from 'path';
14
14
  import { BundleManifestSchema, zodErrorToValidationErrors, MANIFEST_MAX_BYTES, MAX_BUNDLES_PER_PROJECT, } from './manifest.js';
15
15
  import { ensureTrailingSlash, projectLocalDisplayPath, PROJECT_LOCAL_DIR_TO_TYPE, PROJECT_LOCAL_SCAN_DIRS, resolveProjectLocalSearchRoots, } from './project-local-paths.js';
16
+ /** Format rejected target diagnostics using the same roots as discovery. */
17
+ export function formatProjectLocalTargetErrors(projectDir, target, discovery) {
18
+ const candidates = resolveProjectLocalSearchRoots(projectDir).flatMap(root => PROJECT_LOCAL_SCAN_DIRS.flatMap(dir => {
19
+ const bundlePath = join(root.rootPath, dir, target);
20
+ return [bundlePath, projectLocalDisplayPath(projectDir, bundlePath, root)];
21
+ }));
22
+ const errors = discovery.errors.filter(error => error.severity === 'error'
23
+ && (error.bundleId === target || candidates.some(candidate => {
24
+ const errorPath = error.path.split(sep).join('/');
25
+ const candidatePath = candidate.split(sep).join('/');
26
+ return errorPath === candidatePath || errorPath.startsWith(`${candidatePath}/`);
27
+ })));
28
+ if (errors.length === 0)
29
+ return undefined;
30
+ return `Error: Project-local bundle '${target}' failed manifest validation:\n`
31
+ + errors.map(error => ` ${error.path}\n ${error.field}: expected ${error.expected}, got ${error.actual}`
32
+ + (error.hint ? `\n hint: ${error.hint}` : '')).join('\n');
33
+ }
16
34
  /**
17
35
  * Scan all project-local `.aiwg/<type>/` directories for bundles. Returns
18
36
  * a structured result with bundles, errors, and counts. Missing directories
@@ -228,7 +246,9 @@ export async function loadAndValidateManifest(manifestPath, expectedType, projec
228
246
  }
229
247
  const result = BundleManifestSchema.safeParse(parsed);
230
248
  if (!result.success) {
231
- return { errors: zodErrorToValidationErrors(result.error, manifestPath, parsed) };
249
+ const id = BundleManifestSchema.shape.id.safeParse(parsed && typeof parsed === 'object' ? parsed.id : undefined);
250
+ return { errors: zodErrorToValidationErrors(result.error, manifestPath, parsed)
251
+ .map(error => id.success ? { ...error, bundleId: id.data } : error) };
232
252
  }
233
253
  const manifest = result.data;
234
254
  // Cross-check: manifest declared type must match the directory it lives in.
@@ -2,17 +2,18 @@
2
2
  * Project-Local Doctor Section
3
3
  *
4
4
  * Builds the "Project-local artifacts" section for `aiwg doctor` output
5
- * per the spec at @.aiwg/architecture/design-doctor-log-promote.md (#1049).
5
+ * per the spec at @docs/customization/project-local-lifecycle.md (#1049).
6
6
  *
7
7
  * Pure function over (projectDir, frameworkRoot) — returns a string. The
8
8
  * doctor handler in src/cli/handlers/utilities.ts is responsible for
9
9
  * printing it. Section is fully suppressed when no project-local dirs
10
10
  * are present.
11
11
  *
12
- * @design @.aiwg/architecture/design-doctor-log-promote.md
12
+ * @design @docs/customization/project-local-lifecycle.md
13
13
  * @implements #1037
14
14
  */
15
15
  import { join } from 'path';
16
+ import { cliExtensionSourceWarnings } from '../cli/cli-extension-paths.js';
16
17
  import { readFile, readdir } from 'fs/promises';
17
18
  import { discoverProjectLocalBundles } from './project-local-discovery.js';
18
19
  import { parseRuleFrontmatter, formatRuleFrontmatterError } from '../rules/activation.mjs';
@@ -103,6 +104,7 @@ async function collectBundleRuleFiles(artifactPath) {
103
104
  export async function buildProjectLocalDoctorSection(opts) {
104
105
  const { projectDir, frameworkRoot, config, quiet = false } = opts;
105
106
  const discovery = await discoverProjectLocalBundles(projectDir);
107
+ const cliWarnings = await cliExtensionSourceWarnings(projectDir);
106
108
  const quickrefAudit = await auditProjectQuickref(projectDir, config?.providers ?? []);
107
109
  const quickrefErrors = [...quickrefAudit.errors];
108
110
  if (quickrefAudit.exists) {
@@ -118,10 +120,12 @@ export async function buildProjectLocalDoctorSection(opts) {
118
120
  }
119
121
  }
120
122
  // No project-local content → no section at all
121
- if (discovery.isEmpty && discovery.errors.length === 0 && !quickrefAudit.exists && quickrefErrors.length === 0) {
123
+ if (discovery.isEmpty && discovery.errors.length === 0 && !quickrefAudit.exists && quickrefErrors.length === 0 && cliWarnings.length === 0) {
122
124
  return { output: '', validationErrors: 0, denylistViolations: 0, driftCount: 0, undeployedCount: 0, hasFailures: false };
123
125
  }
124
126
  const lines = ['', '── Project-local artifacts ────────────────────────────────────'];
127
+ for (const warning of cliWarnings)
128
+ lines.push(` ⚠ ${warning}`);
125
129
  // Counts
126
130
  if (!quiet) {
127
131
  lines.push(` Discovered: ${discovery.bundles.length} bundle${discovery.bundles.length === 1 ? '' : 's'}`);
@@ -2,11 +2,11 @@
2
2
  * Project-Local Bundle Promotion (Graduate)
3
3
  *
4
4
  * Operationalizes the identical-form portability invariant from
5
- * @.aiwg/architecture/adr-identical-form-portability.md (#1038): a
5
+ * @docs/customization/project-local-lifecycle.md (#1038): a
6
6
  * project-local bundle should graduate to upstream (or to a private
7
7
  * corpus path) by byte-identical copy.
8
8
  *
9
- * Per the design at @.aiwg/architecture/design-doctor-log-promote.md
9
+ * Per the design at @docs/customization/project-local-lifecycle.md
10
10
  * (#1049), promote performs:
11
11
  * 1. Pre-flight checks (bundle exists, manifest valid, no project-
12
12
  * local @-refs, destination doesn't exist, identical-form layout)
@@ -17,7 +17,7 @@
17
17
  * 6. Optional --cleanup: remove .aiwg/<type>/<name>/ source
18
18
  * 7. Activity log entry
19
19
  *
20
- * @design @.aiwg/architecture/design-doctor-log-promote.md
20
+ * @design @docs/customization/project-local-lifecycle.md
21
21
  * @implements #1037
22
22
  */
23
23
  import { createHash } from 'crypto';
@@ -2,14 +2,14 @@
2
2
  * Project-Local Bundle Remove
3
3
  *
4
4
  * Reverts a project-local bundle's deployed artifacts from provider paths
5
- * per the case table in `.aiwg/architecture/design-aiwg-remove-revert.md`
5
+ * per the case table in `docs/customization/project-local-lifecycle.md`
6
6
  * (#1048). Reads artifactHashes from the registry to detect pristine vs
7
7
  * mutated vs replaced files.
8
8
  *
9
9
  * Source under `.aiwg/<type>/<name>/` is NEVER deleted (load-bearing
10
10
  * invariant — `--force` does not change this).
11
11
  *
12
- * @design @.aiwg/architecture/design-aiwg-remove-revert.md
12
+ * @design @docs/customization/project-local-lifecycle.md
13
13
  * @implements #1037
14
14
  */
15
15
  import { lstat, readdir, readFile, stat, unlink, rmdir } from 'fs/promises';
@@ -232,7 +232,7 @@ function resolveOwnership(config, selfBundleId, provider, sourceRel) {
232
232
  }
233
233
  /**
234
234
  * Remove a project-local bundle's deploys per the design at
235
- * `.aiwg/architecture/design-aiwg-remove-revert.md`.
235
+ * `docs/customization/project-local-lifecycle.md`.
236
236
  *
237
237
  * Pure function over (config, projectDir, opts). The caller is responsible
238
238
  * for persisting the returned (mutated) config.
@@ -8,7 +8,7 @@
8
8
  * The output is byte-identical-shaped to upstream addon directories so
9
9
  * `aiwg promote` can graduate it without any rewrite.
10
10
  *
11
- * @design @.aiwg/architecture/adr-identical-form-portability.md (#1038)
11
+ * @design @docs/customization/project-local-lifecycle.md (#1038)
12
12
  * @implements #1050
13
13
  */
14
14
  import { mkdir, writeFile, stat } from 'fs/promises';
@@ -18,11 +18,12 @@ import { PROJECT_LOCAL_TYPE_TO_DIR as TYPE_TO_DIR } from './project-local-paths.
18
18
  const NAME_REGEX = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
19
19
  function buildManifest(opts) {
20
20
  const { type, name, description = `Project-local ${type} '${name}'` } = opts;
21
+ const now = new Date();
21
22
  const base = {
22
23
  id: name,
23
24
  type,
24
25
  name,
25
- version: '0.1.0',
26
+ version: `${now.getUTCFullYear()}.${now.getUTCMonth() + 1}.0`,
26
27
  description,
27
28
  manifestVersion: '1',
28
29
  platforms: { claude: 'full' },
@@ -30,7 +31,14 @@ function buildManifest(opts) {
30
31
  deployment: { pathTemplate: '.{platform}/skills/{id}.md' },
31
32
  };
32
33
  if (type === 'addon') {
33
- base['addonConfig'] = { entry: { skills: 'skills/' } };
34
+ const starter = opts.starter ?? 'skill';
35
+ const kind = starter === 'agent' ? 'agents' : starter === 'rule' ? 'rules' : 'skills';
36
+ base['core'] = false;
37
+ base['autoInstall'] = false;
38
+ base['agents'] = starter === 'agent' ? [name] : [];
39
+ base['skills'] = starter === 'skill' ? [`${name}-skill`] : [];
40
+ base['rules'] = starter === 'rule' ? [name] : [];
41
+ base['addonConfig'] = { entry: starter === 'minimal' ? {} : { [kind]: `${kind}/` } };
34
42
  }
35
43
  else if (type === 'framework') {
36
44
  base['frameworkConfig'] = { path: 'src/' };
@@ -103,7 +111,7 @@ Keep this directory shaped like upstream so \`aiwg promote\` works.
103
111
  ## Customization tips
104
112
 
105
113
  - Edit \`manifest.json\` to set a real \`description\`, bump \`version\` to
106
- \`1.0.0\` when stable, and add platforms beyond \`claude\` if needed.
114
+ the next CalVer patch when changed, and add platforms beyond \`claude\` if needed.
107
115
  - Add new artifacts under \`skills/\`, \`rules/\`, \`agents/\`, or \`commands/\`
108
116
  per AIWG conventions.
109
117
  - Use \`@\`-references for cross-artifact links: \`@$AIWG_ROOT/...\` for
@@ -133,7 +141,7 @@ Replace this body with the workflow your skill performs.
133
141
 
134
142
  Describe the trigger conditions for this skill.
135
143
 
136
- ## Steps
144
+ ## Process
137
145
 
138
146
  1. Step one
139
147
  2. Step two
@@ -159,13 +167,15 @@ Explain the motivation. Future-you will thank you.
159
167
  State when this rule fires and what action it requires.
160
168
  `;
161
169
  const STARTER_AGENT = (name) => `---
162
- name: ${name}-agent
170
+ name: ${name}
163
171
  description: Starter agent for the ${name} project-local bundle.
172
+ model: haiku
173
+ tools: [Read, Glob, Grep]
164
174
  model-role: efficiency
165
175
  model-tier: economy
166
176
  ---
167
177
 
168
- # ${name}-agent
178
+ # ${name}
169
179
 
170
180
  You are a specialist for [domain]. Customize this body with the agent's
171
181
  focus, allowed tools, and termination conditions.
@@ -196,7 +206,7 @@ export async function scaffoldProjectLocalBundle(options) {
196
206
  if (starter === 'skill')
197
207
  filesCreated.push(`skills/${options.name}-skill/SKILL.md`);
198
208
  else if (starter === 'rule')
199
- filesCreated.push(`rules/${options.name}.md`);
209
+ filesCreated.push(`rules/${options.name}.md`, 'rules/RULES-INDEX.md');
200
210
  else if (starter === 'agent')
201
211
  filesCreated.push(`agents/${options.name}.md`);
202
212
  if (options.type === 'framework')
@@ -228,6 +238,8 @@ export async function scaffoldProjectLocalBundle(options) {
228
238
  await mkdir(rulesDir, { recursive: true });
229
239
  await writeFile(join(rulesDir, `${options.name}.md`), STARTER_RULE(options.name), 'utf-8');
230
240
  filesCreated.push(`rules/${options.name}.md`);
241
+ await writeFile(join(rulesDir, 'RULES-INDEX.md'), `# Rules Index\n\n- [${options.name}](${options.name}.md)\n`, 'utf-8');
242
+ filesCreated.push('rules/RULES-INDEX.md');
231
243
  }
232
244
  else if (starter === 'agent') {
233
245
  const agentsDir = join(bundlePath, 'agents');