@geraldmaron/construct 1.0.16 → 1.0.18

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 (191) hide show
  1. package/README.md +4 -1
  2. package/bin/construct +236 -21
  3. package/bin/construct-postinstall.mjs +17 -2
  4. package/commands/design/flow.md +2 -0
  5. package/commands/design/ui.md +2 -0
  6. package/lib/cli-commands.mjs +65 -13
  7. package/lib/embed/semantic.mjs +5 -3
  8. package/lib/embedded-contract/audit.mjs +52 -0
  9. package/lib/embedded-contract/capability.mjs +179 -0
  10. package/lib/embedded-contract/contract-version.mjs +39 -0
  11. package/lib/embedded-contract/envelope.mjs +70 -0
  12. package/lib/embedded-contract/index.mjs +71 -0
  13. package/lib/embedded-contract/ingest.mjs +77 -0
  14. package/lib/embedded-contract/model-resolve.mjs +186 -0
  15. package/lib/embedded-contract/redaction.mjs +91 -0
  16. package/lib/embedded-contract/role-facts.mjs +66 -0
  17. package/lib/embedded-contract/triage.mjs +134 -0
  18. package/lib/embedded-contract/workflow-defs.mjs +125 -0
  19. package/lib/embedded-contract/workflow-invoke.mjs +218 -0
  20. package/lib/hooks/config-protection.mjs +12 -5
  21. package/lib/init-unified.mjs +36 -26
  22. package/lib/intake/classify.mjs +6 -0
  23. package/lib/intake/tables/rnd.mjs +33 -0
  24. package/lib/mcp/server.mjs +69 -0
  25. package/lib/mcp/tools/embedded-contract.mjs +77 -0
  26. package/lib/model-router.mjs +40 -0
  27. package/lib/op-log.mjs +61 -0
  28. package/lib/roles/catalog.mjs +26 -95
  29. package/lib/service-manager.mjs +33 -11
  30. package/lib/setup.mjs +21 -3
  31. package/lib/validators/skills.mjs +21 -0
  32. package/package.json +12 -7
  33. package/scripts/sync-specialists.mjs +12 -3
  34. package/skills/ai/agent-dev.md +2 -0
  35. package/skills/ai/llm-security.md +2 -0
  36. package/skills/ai/ml-ops.md +2 -0
  37. package/skills/ai/orchestration-workflow.md +2 -0
  38. package/skills/ai/prompt-and-eval.md +2 -0
  39. package/skills/ai/prompt-optimizer.md +2 -0
  40. package/skills/ai/rag-system.md +2 -0
  41. package/skills/ai/trace-triage.md +36 -0
  42. package/skills/architecture/api-design.md +2 -0
  43. package/skills/architecture/caching.md +2 -0
  44. package/skills/architecture/cloud-native.md +2 -0
  45. package/skills/architecture/message-queue.md +2 -0
  46. package/skills/architecture/security-arch.md +2 -0
  47. package/skills/compliance/ai-disclosure.md +2 -0
  48. package/skills/compliance/data-privacy.md +2 -0
  49. package/skills/compliance/license-audit.md +2 -0
  50. package/skills/compliance/regulatory-review.md +2 -0
  51. package/skills/development/cpp.md +2 -0
  52. package/skills/development/go.md +2 -0
  53. package/skills/development/java.md +2 -0
  54. package/skills/development/kotlin.md +2 -0
  55. package/skills/development/mobile-crossplatform.md +2 -0
  56. package/skills/development/python.md +2 -0
  57. package/skills/development/rust.md +2 -0
  58. package/skills/development/shell.md +2 -0
  59. package/skills/development/swift.md +2 -0
  60. package/skills/development/typescript.md +2 -0
  61. package/skills/devops/ci-cd.md +2 -0
  62. package/skills/devops/containerization.md +2 -0
  63. package/skills/devops/cost-optimization.md +2 -0
  64. package/skills/devops/data-engineering.md +2 -0
  65. package/skills/devops/database.md +2 -0
  66. package/skills/devops/dependency-management.md +2 -0
  67. package/skills/devops/devsecops.md +2 -0
  68. package/skills/devops/git-workflow.md +2 -0
  69. package/skills/devops/incident-response.md +2 -0
  70. package/skills/devops/monorepo.md +2 -0
  71. package/skills/devops/observability.md +2 -0
  72. package/skills/devops/performance.md +2 -0
  73. package/skills/devops/testing.md +2 -0
  74. package/skills/docs/adr-workflow.md +2 -0
  75. package/skills/docs/backlog-proposal-workflow.md +2 -0
  76. package/skills/docs/customer-profile-workflow.md +2 -0
  77. package/skills/docs/document-ingest-workflow.md +2 -0
  78. package/skills/docs/evidence-ingest-workflow.md +2 -0
  79. package/skills/docs/init-docs.md +2 -0
  80. package/skills/docs/init-project.md +2 -0
  81. package/skills/docs/memo-and-decision-capture.md +45 -0
  82. package/skills/docs/prd-workflow.md +2 -0
  83. package/skills/docs/prfaq-workflow.md +2 -0
  84. package/skills/docs/product-intelligence-review.md +2 -0
  85. package/skills/docs/product-intelligence-workflow.md +2 -0
  86. package/skills/docs/product-signal-workflow.md +2 -0
  87. package/skills/docs/research-workflow.md +2 -0
  88. package/skills/docs/runbook-workflow.md +2 -0
  89. package/skills/docs/strategy-workflow.md +2 -0
  90. package/skills/docs/transcript-synthesis.md +43 -0
  91. package/skills/exploration/dependency-graph-reading.md +2 -0
  92. package/skills/exploration/repo-map.md +2 -0
  93. package/skills/exploration/tracer-bullet-method.md +2 -0
  94. package/skills/exploration/unknown-codebase-onboarding.md +2 -0
  95. package/skills/frameworks/django.md +2 -0
  96. package/skills/frameworks/nextjs.md +2 -0
  97. package/skills/frameworks/react.md +2 -0
  98. package/skills/frameworks/spring-boot.md +2 -0
  99. package/skills/frontend-design/accessibility.md +2 -0
  100. package/skills/frontend-design/component-patterns.md +2 -0
  101. package/skills/frontend-design/engineering.md +2 -0
  102. package/skills/frontend-design/screen-reader-testing.md +34 -0
  103. package/skills/frontend-design/state-management.md +2 -0
  104. package/skills/frontend-design/ui-aesthetics.md +2 -0
  105. package/skills/frontend-design/ux-principles.md +2 -0
  106. package/skills/operating/change-management.md +2 -0
  107. package/skills/operating/incident-response.md +2 -0
  108. package/skills/operating/oncall-rotation.md +2 -0
  109. package/skills/operating/orchestration-reference.md +2 -0
  110. package/skills/operating/raw-data-structuring.md +44 -0
  111. package/skills/operating/unstructured-triage.md +45 -0
  112. package/skills/quality-gates/premortem.md +37 -0
  113. package/skills/quality-gates/review-work.md +2 -0
  114. package/skills/quality-gates/verify-change.md +2 -0
  115. package/skills/quality-gates/verify-module.md +2 -0
  116. package/skills/quality-gates/verify-quality.md +2 -0
  117. package/skills/quality-gates/verify-security.md +2 -0
  118. package/skills/roles/architect.ai-systems.md +2 -0
  119. package/skills/roles/architect.data.md +2 -0
  120. package/skills/roles/architect.enterprise.md +2 -0
  121. package/skills/roles/architect.integration.md +2 -0
  122. package/skills/roles/architect.md +2 -0
  123. package/skills/roles/architect.platform.md +2 -0
  124. package/skills/roles/data-analyst.experiment.md +2 -0
  125. package/skills/roles/data-analyst.md +2 -0
  126. package/skills/roles/data-analyst.product-intelligence.md +2 -0
  127. package/skills/roles/data-analyst.product.md +2 -0
  128. package/skills/roles/data-analyst.telemetry.md +2 -0
  129. package/skills/roles/data-engineer.pipeline.md +2 -0
  130. package/skills/roles/data-engineer.vector-retrieval.md +2 -0
  131. package/skills/roles/data-engineer.warehouse.md +2 -0
  132. package/skills/roles/debugger.md +2 -0
  133. package/skills/roles/designer.accessibility.md +2 -0
  134. package/skills/roles/designer.md +2 -0
  135. package/skills/roles/engineer.ai.md +2 -0
  136. package/skills/roles/engineer.data.md +2 -0
  137. package/skills/roles/engineer.md +2 -0
  138. package/skills/roles/engineer.platform.md +2 -0
  139. package/skills/roles/operator.docs.md +2 -0
  140. package/skills/roles/operator.md +2 -0
  141. package/skills/roles/operator.release.md +2 -0
  142. package/skills/roles/operator.sre.md +2 -0
  143. package/skills/roles/orchestrator.md +2 -0
  144. package/skills/roles/product-manager.ai-product.md +2 -0
  145. package/skills/roles/product-manager.business-strategy.md +2 -0
  146. package/skills/roles/product-manager.enterprise.md +2 -0
  147. package/skills/roles/product-manager.growth.md +2 -0
  148. package/skills/roles/product-manager.md +2 -0
  149. package/skills/roles/product-manager.platform.md +2 -0
  150. package/skills/roles/product-manager.product.md +2 -0
  151. package/skills/roles/qa.ai-eval.md +2 -0
  152. package/skills/roles/qa.api-contract.md +2 -0
  153. package/skills/roles/qa.data-pipeline.md +2 -0
  154. package/skills/roles/qa.md +2 -0
  155. package/skills/roles/qa.test-automation.md +2 -0
  156. package/skills/roles/qa.web-ui.md +2 -0
  157. package/skills/roles/researcher.explorer.md +2 -0
  158. package/skills/roles/researcher.md +2 -0
  159. package/skills/roles/researcher.ux.md +2 -0
  160. package/skills/roles/reviewer.devil-advocate.md +2 -0
  161. package/skills/roles/reviewer.evaluator.md +2 -0
  162. package/skills/roles/reviewer.md +2 -0
  163. package/skills/roles/reviewer.trace.md +2 -0
  164. package/skills/roles/security.ai.md +2 -0
  165. package/skills/roles/security.appsec.md +2 -0
  166. package/skills/roles/security.cloud.md +2 -0
  167. package/skills/roles/security.legal-compliance.md +2 -0
  168. package/skills/roles/security.md +2 -0
  169. package/skills/roles/security.privacy.md +2 -0
  170. package/skills/roles/security.supply-chain.md +2 -0
  171. package/skills/security/blue-team.md +2 -0
  172. package/skills/security/code-audit.md +2 -0
  173. package/skills/security/pentest.md +2 -0
  174. package/skills/security/red-team.md +2 -0
  175. package/skills/security/threat-intel.md +2 -0
  176. package/skills/security/vuln-research.md +2 -0
  177. package/skills/strategy/competitive-landscape.md +2 -0
  178. package/skills/strategy/jobs-to-be-done.md +38 -0
  179. package/skills/strategy/market-research-methods.md +2 -0
  180. package/skills/strategy/narrative-arc.md +2 -0
  181. package/skills/strategy/pricing-positioning.md +2 -0
  182. package/skills/utility/clean-code.md +2 -0
  183. package/specialists/prompts/cx-architect.md +1 -0
  184. package/specialists/prompts/cx-designer.md +1 -1
  185. package/specialists/prompts/cx-engineer.md +1 -1
  186. package/specialists/prompts/cx-operations.md +1 -0
  187. package/specialists/prompts/cx-rd-lead.md +1 -0
  188. package/specialists/prompts/cx-sre.md +1 -0
  189. package/specialists/registry.json +20 -11
  190. package/specialists/role-manifests.json +1 -1
  191. package/templates/docs/test-plan.md +96 -0
@@ -442,9 +442,22 @@ async function tryStartDockerDaemon({
442
442
  return false;
443
443
  }
444
444
 
445
+ // The optional services a user can pick from with `construct dev --select` /
446
+ // `--only=`. Pressure Guard (cleanup) and Doctor (the L0 supervisor daemon)
447
+ // are infrastructure, always on — they are intentionally not selectable.
448
+
449
+ export const SELECTABLE_SERVICES = Object.freeze([
450
+ { key: 'postgres', label: 'Postgres', description: 'Managed pgvector container (or external DATABASE_URL).' },
451
+ { key: 'dashboard', label: 'Dashboard', description: 'Local operations dashboard on http://127.0.0.1:4242.' },
452
+ { key: 'telemetry', label: 'Telemetry', description: 'Trace export / local JSONL traces.' },
453
+ { key: 'memory', label: 'Memory (cm)', description: 'Persistent memory service (cm).' },
454
+ { key: 'opencode', label: 'OpenCode', description: 'OpenCode bridge server.' },
455
+ ]);
456
+
445
457
  export async function startServices({
446
458
  rootDir,
447
459
  homeDir = os.homedir(),
460
+ selected = null,
448
461
  describeRuntimeSupportFn = describeRuntimeSupport,
449
462
  getRuntimePortsFn = getRuntimePorts,
450
463
  startDashboardFn = startDashboard,
@@ -461,6 +474,11 @@ export async function startServices({
461
474
  const ports = await getRuntimePortsFn(homeDir);
462
475
  const envPath = getUserEnvPath(homeDir);
463
476
 
477
+ // A null selection means "start everything" (the default). A Set restricts
478
+ // startup to the chosen optional services; always-on infrastructure ignores it.
479
+
480
+ const wants = (key) => selected === null || selected.has(key);
481
+
464
482
  // On macOS, auto-launch Docker Desktop when the CLI is present but the
465
483
  // daemon is down. Polls up to 60s so downstream Postgres startup sees a working
466
484
  // compose runner instead of "Docker not available".
@@ -487,7 +505,7 @@ export async function startServices({
487
505
  const databaseUrl = liveEnv.DATABASE_URL || '';
488
506
  const usesManagedPostgres = isManagedConstructPostgresUrl(databaseUrl);
489
507
 
490
- if (usesManagedPostgres) {
508
+ if (wants('postgres') && usesManagedPostgres) {
491
509
  if (!isConstructPostgresRunning()) {
492
510
  const pgStart = startConstructPostgres({ rootDir, homeDir, spawnSyncFn: spawnSync, detectDockerComposeFn: detectDockerComposeFn });
493
511
  if (pgStart.status === 'started') {
@@ -515,20 +533,23 @@ export async function startServices({
515
533
  note: pgvector ? 'pgvector enabled' : 'pgvector not installed',
516
534
  });
517
535
  }
518
- } else if (databaseUrl) {
536
+ } else if (wants('postgres') && databaseUrl) {
519
537
  results.push({ name: 'Postgres', url: databaseUrl, status: 'configured', note: 'external database' });
520
538
  }
521
539
 
522
540
  // Dashboard
523
- const dashboard = await startDashboardFn({ rootDir, homeDir, preferredPort: ports.dashboard });
524
- results.push({
525
- name: 'Dashboard',
526
- url: dashboard.url,
527
- status: dashboard.reused ? 'reused' : 'started',
528
- });
541
+ if (wants('dashboard')) {
542
+ const dashboard = await startDashboardFn({ rootDir, homeDir, preferredPort: ports.dashboard });
543
+ results.push({
544
+ name: 'Dashboard',
545
+ url: dashboard.url,
546
+ status: dashboard.reused ? 'reused' : 'started',
547
+ });
548
+ }
529
549
 
530
550
  const telemetryUrl = liveEnv.CONSTRUCT_TELEMETRY_URL ?? '';
531
551
  const traceBackend = resolveTraceBackend(liveEnv);
552
+ if (wants('telemetry')) {
532
553
  if (traceBackend === 'local') {
533
554
  results.push({
534
555
  name: 'Telemetry',
@@ -561,21 +582,22 @@ export async function startServices({
561
582
  } else {
562
583
  results.push({ name: 'Telemetry', status: 'unavailable', note: 'remote export requested but endpoint is not configured' });
563
584
  }
585
+ }
564
586
 
565
587
  // Memory (cm)
566
- if (support.cm) {
588
+ if (wants('memory') && support.cm) {
567
589
  if (await memoryProbeFn(ports.memory)) {
568
590
  results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'reused' });
569
591
  } else {
570
592
  spawnDetachedFn('cm', ['serve', '--port', String(ports.memory)], homeDir, 'cm.log');
571
593
  results.push({ name: 'Memory (cm)', url: `http://127.0.0.1:${ports.memory}`, status: 'started' });
572
594
  }
573
- } else {
595
+ } else if (wants('memory')) {
574
596
  results.push({ name: 'Memory (cm)', status: 'unavailable', note: 'cm not installed — run: construct init or brew install dicklesworthstone/tap/cm' });
575
597
  }
576
598
 
577
599
  // OpenCode (optional)
578
- if (support.opencode) {
600
+ if (wants('opencode') && support.opencode) {
579
601
  if (await openCodeProbeFn(ports.bridge)) {
580
602
  results.push({ name: 'OpenCode', url: `http://127.0.0.1:${ports.bridge}`, status: 'reused' });
581
603
  } else {
package/lib/setup.mjs CHANGED
@@ -45,7 +45,12 @@ function printHelp() {
45
45
  console.log(`Construct install — machine setup (once per machine)
46
46
 
47
47
  Usage:
48
- construct install [--yes] [--no-docker]
48
+ construct install [--yes] [--no-docker] [--reconfigure]
49
+
50
+ Flags:
51
+ --yes accept detected defaults without prompting
52
+ --no-docker skip local Postgres / Docker service setup
53
+ --reconfigure re-prompt for service consent, ignoring cached answers
49
54
 
50
55
  What it does:
51
56
  - creates ~/.construct/config.env
@@ -58,8 +63,7 @@ What it does:
58
63
  - runs construct doctor
59
64
  - detects the project tech stack and writes .cx/project-profile.json
60
65
 
61
- For project setup (once per repo): construct init
62
- Use --yes to run without prompts and accept detected environment defaults.`);
66
+ For project setup (once per repo): construct init`);
63
67
  }
64
68
 
65
69
  function runConstruct(argsList, { optional = false } = {}) {
@@ -505,12 +509,24 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
505
509
  const argSet = new Set(args);
506
510
  const isYes = argSet.has('--yes');
507
511
  const skipDocker = argSet.has('--no-docker');
512
+ const reconfigure = argSet.has('--reconfigure');
508
513
 
509
514
  if (argSet.has('--help') || argSet.has('-h')) {
510
515
  printHelp();
511
516
  return;
512
517
  }
513
518
 
519
+ // Reject unknown flags loudly so a typo (e.g. --reconfig) fails fast with the
520
+ // help text instead of silently running defaults.
521
+
522
+ const KNOWN_FLAGS = new Set(['--yes', '--no-docker', '--reconfigure', '--help', '-h']);
523
+ const unknownFlags = args.filter((a) => a.startsWith('-') && !KNOWN_FLAGS.has(a));
524
+ if (unknownFlags.length) {
525
+ console.error(`Unknown flag(s): ${unknownFlags.join(', ')}`);
526
+ printHelp();
527
+ throw new Error(`Unknown setup flag(s): ${unknownFlags.join(', ')}`);
528
+ }
529
+
514
530
  console.log('Construct setup');
515
531
  console.log('────────────────');
516
532
 
@@ -565,6 +581,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
565
581
  const pgConsent = await consentToInstall({
566
582
  name: 'postgres',
567
583
  isYes,
584
+ force: reconfigure,
568
585
  alreadyConfigured: Boolean(process.env.DATABASE_URL),
569
586
  alreadyConfiguredNote: 'DATABASE_URL already set — using external database.',
570
587
  envPath,
@@ -620,6 +637,7 @@ export async function runSetup({ rootDir = ROOT_DIR, args = [], homeDir = HOME }
620
637
  const cheapestConsent = await consentToInstall({
621
638
  name: 'cheapest-provider',
622
639
  isYes,
640
+ force: reconfigure,
623
641
  alreadyConfigured: false,
624
642
  envPath,
625
643
  defaultYes: false,
@@ -6,6 +6,8 @@
6
6
  * ---
7
7
  * name: <kebab-case>
8
8
  * description: "<≤1024 chars, includes a 'use when' trigger>"
9
+ * [inputs: [<string>, …] — optional, surfaced by capability discovery]
10
+ * [artifactType: <string> — optional, surfaced by capability discovery]
9
11
  * [role/applies_to/inherits/version/profiles/cap for role files]
10
12
  * ---
11
13
  * # <Title>
@@ -100,6 +102,23 @@ function validateDescription(description) {
100
102
  return null;
101
103
  }
102
104
 
105
+ // Optional embedded-contract metadata: surfaced by capability discovery when
106
+ // present. Validated only when present so the field stays opt-in and is
107
+ // populated incrementally — inputs is a list of strings, artifactType a string.
108
+
109
+ function validateOptionalMetadata(frontmatter) {
110
+ const issues = [];
111
+ if ('inputs' in frontmatter && frontmatter.inputs !== null) {
112
+ if (!Array.isArray(frontmatter.inputs) || frontmatter.inputs.some((i) => typeof i !== 'string')) {
113
+ issues.push('frontmatter.inputs must be a list of strings when present');
114
+ }
115
+ }
116
+ if ('artifactType' in frontmatter && frontmatter.artifactType !== null && typeof frontmatter.artifactType !== 'string') {
117
+ issues.push('frontmatter.artifactType must be a string when present');
118
+ }
119
+ return issues;
120
+ }
121
+
103
122
  export function validateSkills(roots) {
104
123
  const dirs = Array.isArray(roots) ? roots : [roots];
105
124
  const errors = [];
@@ -150,6 +169,8 @@ export function validateSkills(roots) {
150
169
  const descErr = validateDescription(frontmatter.description);
151
170
  if (descErr) errors.push(`${rel}: ${descErr}`);
152
171
 
172
+ for (const issue of validateOptionalMetadata(frontmatter)) errors.push(`${rel}: ${issue}`);
173
+
153
174
  const { title, opener } = extractTitleAndOpener(body);
154
175
 
155
176
  if (!title) {
package/package.json CHANGED
@@ -1,11 +1,17 @@
1
1
  {
2
2
  "name": "@geraldmaron/construct",
3
- "version": "1.0.16",
3
+ "version": "1.0.18",
4
4
  "type": "module",
5
5
  "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
6
6
  "bin": {
7
7
  "construct": "bin/construct"
8
8
  },
9
+ "exports": {
10
+ ".": "./lib/embedded-contract/index.mjs",
11
+ "./embedded-contract": "./lib/embedded-contract/index.mjs",
12
+ "./lib/*": "./lib/*",
13
+ "./package.json": "./package.json"
14
+ },
9
15
  "files": [
10
16
  "bin/construct",
11
17
  "bin/construct-postinstall.mjs",
@@ -63,29 +69,28 @@
63
69
  "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
64
70
  "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node scripts/lint-commits-pr.mjs",
65
71
  "release:gate": "node --test tests/functional/release-gate.functional.test.mjs",
72
+ "audit:published": "node scripts/audit-published-artifact.mjs",
66
73
  "release:preflight": "node scripts/pre-release-check.mjs",
67
74
  "release:preflight:no-auth": "node scripts/pre-release-check.mjs --skip-auth",
68
75
  "npm:publish": "npm run release:check && npm publish --access public",
69
76
  "postinstall": "node ./bin/construct-postinstall.mjs"
70
77
  },
71
78
  "dependencies": {
72
- "@huggingface/transformers": "^4.2.0",
73
79
  "@modelcontextprotocol/sdk": "^1.12.0",
74
- "@xenova/transformers": "^2.0.1",
75
80
  "js-yaml": "^4.2.0",
76
81
  "node-webvtt": "^1.9.3",
77
82
  "postgres": "^3.4.9"
78
83
  },
79
84
  "optionalDependencies": {
85
+ "@huggingface/transformers": "^4.2.0",
80
86
  "@opentelemetry/api": "^1.9.0",
81
- "@opentelemetry/core": "^1.25.0",
82
- "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",
87
+ "@opentelemetry/core": "^2.7.1",
88
+ "@opentelemetry/exporter-trace-otlp-http": "^0.218.0",
83
89
  "@opentelemetry/resources": "^1.25.0",
84
90
  "@opentelemetry/sdk-trace-node": "^1.25.0",
85
91
  "@opentelemetry/semantic-conventions": "^1.25.0"
86
92
  },
87
93
  "overrides": {
88
- "express-rate-limit": "8.5.1",
89
- "protobufjs": "^8.4.2"
94
+ "express-rate-limit": "8.5.1"
90
95
  }
91
96
  }
@@ -172,8 +172,17 @@ function detectConstructProject(cwd) {
172
172
 
173
173
  const detectedProject = (!PROJECT_FLAG && !GLOBAL_FLAG) ? detectConstructProject(process.cwd()) : null;
174
174
  const projectDir = PROJECT_FLAG ? process.cwd() : detectedProject;
175
- const lockPath = path.join(projectDir || root, ".cx", "sync.lock");
176
- const stagingDir = path.join(projectDir || root, ".cx", "sync-staging");
175
+
176
+ // Lock and staging are scoped to the tier we actually mutate: a project dir for
177
+ // project-tier writes, the user's HOME for global-tier writes (which land in
178
+ // ~/.claude, ~/.codex, …). Keying the global tier to HOME — not the repo root —
179
+ // means two --global syncs against different HOMEs (e.g. parallel test files in
180
+ // isolated sandboxes) never collide on a shared repo-root lock, and staging
181
+ // renames stay on the same filesystem as their destinations.
182
+
183
+ const stateBase = projectDir || home;
184
+ const lockPath = path.join(stateBase, ".cx", "sync.lock");
185
+ const stagingDir = path.join(stateBase, ".cx", "sync-staging");
177
186
 
178
187
  // Project-tier writes carry every registry entry. Global-tier writes carry only
179
188
  // the `construct` front-door agent — specialists live with the project, not the
@@ -243,7 +252,7 @@ function writeFile(file, content, { stamp = true } = {}) {
243
252
  }
244
253
 
245
254
  // Two-phase: write to staging, commit later.
246
- const rel = path.relative(projectDir || root, file);
255
+ const rel = path.relative(stateBase, file);
247
256
  const stagingPath = path.join(stagingDir, rel);
248
257
  mkdirp(path.dirname(stagingPath));
249
258
  fs.writeFileSync(stagingPath, stamped);
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: ai-agent-dev
3
3
  description: Use this skill when building AI agents, tool-use systems, or multi-agent workflows.
4
+ inputs: [agent-spec, task-context]
5
+ artifactType: agent-implementation
4
6
  ---
5
7
  # AI Agent Development
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: ai-llm-security
3
3
  description: Use this skill when securing LLM-powered applications against prompt injection, data leakage, and misuse.
4
+ inputs: [prompt, model-output, agent-spec]
5
+ artifactType: guidance
4
6
  ---
5
7
  # LLM Security
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: ai-ml-ops
3
3
  description: Patterns, anti-patterns, and reference guidance for ML Operations (MLOps). Use when the task involves ml operations (mlops).
4
+ inputs: [eval-dataset, model-output]
5
+ artifactType: guidance
4
6
  ---
5
7
  # ML Operations (MLOps)
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: ai-orchestration-workflow
3
3
  description: Use this skill when the request involves agent orchestration, phase transitions, task keys, handoff quality, workflow state, or project alignment.
4
+ inputs: [agent-spec, workflow-state]
5
+ artifactType: guidance
4
6
  ---
5
7
  # Construct Orchestration Workflow
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: ai-prompt-and-eval
3
3
  description: Use this skill when designing prompts, evaluating model performance, or optimizing LLM behavior.
4
+ inputs: [prompt, eval-dataset, model-output]
5
+ artifactType: eval-report
4
6
  ---
5
7
  # Prompt Engineering and Evaluation
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: ai-prompt-optimizer
3
3
  description: Closed-loop prompt auto-optimization guide. Use when the task matches the trigger conditions described in the body.
4
+ inputs: [prompt, model-output, eval-dataset]
5
+ artifactType: prompt
4
6
  ---
5
7
  # Prompt Auto-Optimization Loop
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: ai-rag-system
3
3
  description: Use this skill when building retrieval-augmented generation pipelines, vector search, or knowledge-grounded AI systems.
4
+ inputs: [eval-dataset, prompt]
5
+ artifactType: guidance
4
6
  ---
5
7
  # RAG System Design
6
8
 
@@ -0,0 +1,36 @@
1
+ ---
2
+ name: ai-trace-triage
3
+ description: "Use when: agent telemetry traces need triage to find where a run went wrong — the failing step, the cause category, and whether it is a regression or a one-off."
4
+ inputs: [telemetry-traces]
5
+ artifactType: trace-findings
6
+ ---
7
+ # Trace Triage
8
+
9
+ Use this skill when agent telemetry traces need to be triaged to locate failures and separate systemic regressions from one-off noise.
10
+
11
+ A stable median score hides high-variance agents failing silently. Triage works the tail and the deltas, not the average.
12
+
13
+ ## Steps
14
+
15
+ 1. **Frame the window and baseline.** Compare the current window against a prior baseline of the same agents/skills; an absolute score means little without the delta.
16
+ 2. **Sort by the tail, not the mean.** Surface the worst p10 runs and the largest score drops since baseline — that is where real failures live.
17
+ 3. **For each failing run, locate the failing step**: which role/tool call produced the bad output or error. Read the span, not just the verdict.
18
+ 4. **Classify the cause**: prompt/instruction gap, wrong model tier, missing context/evidence, tool error, or genuine task ambiguity. Do not default to "prompt issue".
19
+ 5. **Regression vs one-off**: does the same failure recur across runs (systemic) or appear once (noise)? Only systemic failures warrant a fix; flag one-offs for watch.
20
+ 6. **Hand off** systemic findings with the trace id, the failing span, the cause class, and a proposed direction (to prompt-optimizer, engineer, or evaluator).
21
+
22
+ ## Output shape
23
+
24
+ ```
25
+ ## Window: <range> vs baseline <range>
26
+ | traceId | agent/skill | failing step | cause class | regression? | Δ score |
27
+ |---|---|---|---|---|---|
28
+
29
+ ## Systemic (fix) vs one-off (watch)
30
+ ```
31
+
32
+ ## Verification bar
33
+
34
+ - Every finding cites a real traceId and the specific span that failed.
35
+ - Regression claims are backed by recurrence across runs, not a single bad sample.
36
+ - Cause classification is evidence-based; "unclear" is a valid class when the trace doesn't show why.
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: architecture-api-design
3
3
  description: Use this skill when designing REST, GraphQL, or gRPC APIs.
4
+ inputs: [system-design, requirements]
5
+ artifactType: api-design
4
6
  ---
5
7
  # API Design
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: architecture-caching
3
3
  description: Use this skill when designing caching strategies for applications, APIs, or infrastructure.
4
+ inputs: [system-design, requirements]
5
+ artifactType: guidance
4
6
  ---
5
7
  # Caching
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: architecture-cloud-native
3
3
  description: Use this skill when designing containerized, orchestrated, or microservice-based systems.
4
+ inputs: [system-design, requirements]
5
+ artifactType: guidance
4
6
  ---
5
7
  # Cloud-Native Architecture
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: architecture-message-queue
3
3
  description: Use this skill when designing asynchronous communication, event-driven systems, or message-based integrations.
4
+ inputs: [system-design, requirements]
5
+ artifactType: guidance
4
6
  ---
5
7
  # Message Queues and Event-Driven Architecture
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: architecture-security-arch
3
3
  description: Use this skill when designing authentication, authorization, network security, or zero-trust architectures.
4
+ inputs: [system-design, requirements]
5
+ artifactType: guidance
4
6
  ---
5
7
  # Security Architecture
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: compliance-ai-disclosure
3
3
  description: Use this skill when reviewing AI features for disclosure requirements, transparency obligations, or emerging AI regulation compliance.
4
+ inputs: [artifact, data-flow]
5
+ artifactType: privacy-assessment
4
6
  ---
5
7
  # AI Disclosure
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: compliance-data-privacy
3
3
  description: Use this skill when reviewing data collection, storage, processing, or retention for privacy regulation compliance.
4
+ inputs: [data-flow, artifact]
5
+ artifactType: privacy-assessment
4
6
  ---
5
7
  # Data Privacy
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: compliance-license-audit
3
3
  description: Use this skill when auditing dependency licenses, evaluating OSS compliance risk, or preparing license inventories for legal review.
4
+ inputs: [dependency-manifest]
5
+ artifactType: license-report
4
6
  ---
5
7
  # License Audit
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: compliance-regulatory-review
3
3
  description: Use this skill when conducting a compliance review before shipping features that handle user data, financial transactions, AI decisions, or regulated content.
4
+ inputs: [artifact, data-flow, dependency-manifest]
5
+ artifactType: compliance-review
4
6
  ---
5
7
  # Regulatory Review
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-cpp
3
3
  description: Use this skill when writing, reviewing, or debugging C or C++ code.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # C/C++ Best Practices
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-go
3
3
  description: Use this skill when writing, reviewing, or debugging Go code.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # Go Best Practices
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-java
3
3
  description: Use this skill when writing, reviewing, or debugging Java or Kotlin code on the JVM.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # Java Best Practices
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-kotlin
3
3
  description: Patterns, anti-patterns, and reference guidance for Kotlin / Android Development. Use when the task involves kotlin / android development.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # Kotlin / Android Development
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-mobile-crossplatform
3
3
  description: Before choosing a framework, answer:. Use when the task matches the trigger conditions described in the body.
4
+ inputs: [requirements, code]
5
+ artifactType: guidance
4
6
  ---
5
7
  # Mobile Cross-Platform Development
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-python
3
3
  description: Use this skill when writing, reviewing, or debugging Python code.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # Python Best Practices
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-rust
3
3
  description: Use this skill when writing, reviewing, or debugging Rust code.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # Rust Best Practices
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-shell
3
3
  description: Use this skill when writing, reviewing, or debugging Bash, Zsh, or POSIX shell scripts.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # Shell Scripting Best Practices
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-swift
3
3
  description: Swift 6 enforces data-race safety at compile time. Annotate isolation boundary explicitly:. Use when the task matches the trigger conditions described in the body.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # Swift / iOS Development
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: development-typescript
3
3
  description: Use this skill when writing, reviewing, or debugging TypeScript or JavaScript code.
4
+ inputs: [code, repo]
5
+ artifactType: code
4
6
  ---
5
7
  # TypeScript Best Practices
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: devops-ci-cd
3
3
  description: Use this skill when designing, debugging, or optimizing CI/CD pipelines.
4
+ inputs: [pipeline-config, repo]
5
+ artifactType: ci-pipeline
4
6
  ---
5
7
  # CI/CD
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: devops-containerization
3
3
  description: Use this skill when writing Dockerfiles, optimizing image size, or securing container builds.
4
+ inputs: [service, repo]
5
+ artifactType: dockerfile
4
6
  ---
5
7
  # Containerization
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: devops-cost-optimization
3
3
  description: Use this skill when reducing cloud spend, right-sizing resources, or implementing FinOps practices.
4
+ inputs: [service, cost-data]
5
+ artifactType: cost-optimization-plan
4
6
  ---
5
7
  # Cloud Cost Optimization
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: devops-data-engineering
3
3
  description: "1. **Idempotency**: pipelines can run multiple times without duplicating data 2. **Observability**: every pipeline run logs row counts, latency, and anomalies 3. **Data contracts**: producers and consumers agree on schema and SLAs 4. **Lineage**: know where every column came from and what it feeds. Use when the task matches the trigger conditions described in the body."
4
+ inputs: [pipeline-config, data-contract]
5
+ artifactType: data-pipeline
4
6
  ---
5
7
  # Data Engineering
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: devops-database
3
3
  description: Use this skill when designing schemas, writing migrations, optimizing queries, or selecting databases.
4
+ inputs: [schema, query]
5
+ artifactType: schema-design
4
6
  ---
5
7
  # Database Patterns
6
8
 
@@ -1,6 +1,8 @@
1
1
  ---
2
2
  name: devops-dependency-management
3
3
  description: Use this skill when managing package upgrades, resolving CVEs, or establishing lock file and versioning policy.
4
+ inputs: [dependency-manifest, repo]
5
+ artifactType: dependency-report
4
6
  ---
5
7
  # Dependency Management
6
8