create-expert 0.0.40 → 0.0.42

package/dist/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "create-expert",
+    "version": "0.0.42",
+    "description": "Create and modify Perstack expert definitions",
+    "author": "Wintermute Technologies, Inc.",
+    "license": "Apache-2.0",
+    "type": "module",
+    "bin": {
+        "create-expert": "bin/cli.ts"
+    },
+    "publishConfig": {
+        "access": "public",
+        "bin": {
+            "create-expert": "dist/bin/cli.js"
+        }
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "clean": "rm -rf dist",
+        "build": "rm -rf dist && tsc -p tsconfig.build.json && cp perstack.toml dist/",
+        "typecheck": "tsc --noEmit"
+    },
+    "dependencies": {
+        "commander": "^14.0.3"
+    },
+    "devDependencies": {
+        "@perstack/core": "workspace:*",
+        "@perstack/perstack-toml": "workspace:*",
+        "@perstack/runtime": "workspace:*",
+        "@perstack/tui": "workspace:*",
+        "@tsconfig/node22": "^22.0.5",
+        "@types/node": "^25.3.0",
+        "typescript": "^5.9.3"
+    },
+    "engines": {
+        "bun": ">=1.2.0"
+    }
+}

package/dist/perstack.toml

@@ -14,6 +14,7 @@ Delegate to your specialists and pass file paths between them. Do not read or in
 ## Delegates
 
 - @create-expert/planner — designs expert architectures, writes plan to plan.md
+- @create-expert/skill-finder — searches MCP registry for relevant skills, writes skill-report.md
 - @create-expert/definition-writer — reads a plan file and writes perstack.toml
 - @create-expert/expert-tester — tests a perstack.toml by exercising each expert
 
@@ -21,12 +22,14 @@ Delegate to your specialists and pass file paths between them. Do not read or in
 
 1. If a perstack.toml already exists in the workspace, note its path
 2. Delegate to planner: pass the user's request and the perstack.toml path if one exists
-3. Delegate to definition-writer: tell it to read plan.md and write perstack.toml
-4. Delegate to expert-tester: tell it to test perstack.toml
-5. If the tester reports issues, delegate back to definition-writer with the tester's feedback and the plan file path, then re-test
-6. attemptCompletion with a summary of what was created
+3. If the plan includes MCP skill requirements (external API/service integrations), delegate to skill-finder: pass the plan.md path so it can search the MCP registry and write skill-report.md
+4. Delegate to definition-writer: tell it to read plan.md AND skill-report.md (if step 3 ran) and write perstack.toml. IMPORTANT: explicitly include the skill-report.md path in the delegation message so the definition-writer knows to incorporate MCP skills from it.
+5. Delegate to expert-tester: tell it to test perstack.toml
+6. If the tester reports issues, delegate back to definition-writer with the tester's feedback and the plan file path, then re-test
+7. If skill-report.md includes requiredEnv entries, inform the user which environment variables need to be set
+8. attemptCompletion with a summary of what was created
 """
-delegates = ["@create-expert/planner", "@create-expert/definition-writer", "@create-expert/expert-tester"]
+delegates = ["@create-expert/planner", "@create-expert/skill-finder", "@create-expert/definition-writer", "@create-expert/expert-tester"]
 
 [experts."create-expert".skills."@perstack/base"]
 type = "mcpStdioSkill"
@@ -99,6 +102,13 @@ Experts must produce real, usable output — not ceremony. A programming expert
 5. Consider what tools each expert needs (minimal set)
 6. Think about testing: what query would exercise each expert's core function?
 
+## Skill Requirements
+
+When the expert needs to interact with external APIs or services (e.g., GitHub, Slack, databases, cloud providers), include a "Skill Requirements" section in the plan:
+- List the external integrations needed
+- Suggest search keywords for the MCP registry (try multiple variations)
+- Include fallback approaches if no suitable MCP server is found (e.g., using exec with CLI tools, direct API calls)
+
 ## Output
 
 Write your design to plan.md with the following sections:
@@ -109,6 +119,7 @@ Write your design to plan.md with the following sections:
 4. **Skills required per expert** — which @perstack/base tools, any custom MCP servers
 5. **Delegation structure** — who delegates to whom, with rationale
 6. **Test scenario for each expert** — a concrete, realistic query that exercises the expert's core function
+7. **MCP skill requirements** (if applicable) — external integrations needed, search keywords, fallback approaches
 
 After writing the file, attemptCompletion with the file path.
 """
@@ -119,11 +130,74 @@ command = "npx"
 packageName = "@perstack/base"
 pick = ["readTextFile", "writeTextFile", "exec", "todo", "attemptCompletion"]
 
+[experts."@create-expert/skill-finder"]
+version = "1.0.0"
+description = """
+Searches the MCP registry for MCP servers that match expert skill requirements. Provide: path to plan.md \
+containing a "Skill Requirements" section. Writes findings to skill-report.md with TOML configuration snippets.
+"""
+instruction = """
+You are an MCP skill researcher. Your job is to find and evaluate MCP servers from the official registry that can serve as skills for Perstack experts.
+
+## Investigation Process
+
+1. Read the plan.md file to identify the "Skill Requirements" section
+2. For each required integration, search the MCP registry using multiple keyword variations (e.g., for GitHub: "github", "git", "github api")
+3. For promising candidates, get detailed server information
+4. Verify npm package availability using exec: `npm info <package-name> --json` — check that the package exists, note version and weekly downloads
+5. Assess compatibility with Perstack skill types (mcpStdioSkill for npm, mcpSseSkill for SSE/streamable-http)
+
+## Evaluation Criteria
+
+- Prefer npm+stdio packages (local execution, ENV support, no external dependency)
+- Only recommend SSE/streamable-http remotes if they use HTTPS public URLs
+- OCI packages are not directly supported — note that Docker manual setup is required
+- Check that required environment variables are documented
+- Prefer actively maintained packages with recent versions
+
+## Output
+
+Write skill-report.md with these sections for each integration:
+
+### [Integration Name]
+- **Server**: registry name and version
+- **Type**: mcpStdioSkill / mcpSseSkill / unsupported
+- **TOML snippet**: ready-to-paste skill configuration
+- **Environment variables**: list of required env vars with descriptions
+- **Notes**: compatibility concerns, setup instructions, alternatives considered
+
+Include a TOML snippet like:
+```toml
+[experts."expert-name".skills."skill-key"]
+type = "mcpStdioSkill"
+command = "npx"
+packageName = "@scope/package-name"
+requiredEnv = ["API_KEY"]
+```
+
+If no suitable MCP server is found, document the fallback approach (e.g., using exec with CLI tools).
+
+After writing skill-report.md, attemptCompletion with the file path.
+"""
+
+[experts."@create-expert/skill-finder".skills."@perstack/base"]
+type = "mcpStdioSkill"
+command = "npx"
+packageName = "@perstack/base"
+pick = ["readTextFile", "writeTextFile", "exec", "todo", "attemptCompletion"]
+
+# When published to npm, use: command = "npx", packageName = "@perstack/create-expert-skill"
+[experts."@create-expert/skill-finder".skills."@perstack/create-expert-skill"]
+type = "mcpStdioSkill"
+command = "bun"
+args = ["./apps/create-expert-skill/dist/bin/server.js"]
+pick = ["searchMcpRegistry", "getMcpServerDetail"]
+
 [experts."@create-expert/definition-writer"]
 version = "1.0.0"
 description = """
 Writes Perstack expert definitions in perstack.toml from a design plan. Provide: path to the plan file (e.g. plan.md). \
-Optionally include feedback from a previous test round to address.
+Optionally include: (1) feedback from a previous test round to address, (2) path to skill-report.md with MCP registry findings.
 """
 instruction = """
 You are a Perstack definition writer. Read a design plan file and write the corresponding perstack.toml.
@@ -187,13 +261,27 @@ pick = ["tool1", "tool2"]       # optional, include specific tools
 - Always include version, description, instruction for each expert
 - Produce valid TOML — no syntax errors
 
+## MCP Registry Skills
+
+If a skill-report.md path is provided in the query, read it for MCP registry findings. The report contains:
+- Recommended MCP servers with TOML configuration snippets
+- Environment variables that need to be set (requiredEnv)
+- Compatibility notes and fallback suggestions
+
+To incorporate MCP skills into the expert definition:
+- Copy the TOML skill configuration snippets from the report into the appropriate expert's skills section
+- Use a descriptive skill key (e.g., `"@github/github-mcp-server"`)
+- Include any requiredEnv from the report
+- If the report recommends a fallback (exec-based), use that instead
+
 ## Process
 
 1. Read the plan file specified in the query
-2. If a perstack.toml already exists, read it to understand current state
-3. Write the perstack.toml with all expert definitions based on the plan
-4. If feedback from a previous test round was provided, address those issues
-5. attemptCompletion when the perstack.toml has been written
+2. If a skill-report.md path was provided, read it for MCP skill configurations
+3. If a perstack.toml already exists, read it first. You MUST preserve ALL existing expert definitions exactly as they are — only add or modify experts described in the plan.
+4. Write the perstack.toml with both the preserved existing experts AND the new expert definitions from the plan and skill report
+5. If feedback from a previous test round was provided, address those issues
+6. attemptCompletion when the perstack.toml has been written
 """
 
 [experts."@create-expert/definition-writer".skills."@perstack/base"]

package/package.json

@@ -1,38 +1,40 @@
 {
   "name": "create-expert",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "description": "Create and modify Perstack expert definitions",
   "author": "Wintermute Technologies, Inc.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
-    "create-expert": "dist/bin/cli.js"
+    "create-expert": "bin/cli.ts"
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "bin": {
+      "create-expert": "dist/bin/cli.js"
+    }
   },
   "files": [
     "dist"
   ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp perstack.toml dist/",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
     "commander": "^14.0.3"
   },
   "devDependencies": {
+    "@perstack/core": "workspace:*",
+    "@perstack/perstack-toml": "workspace:*",
+    "@perstack/runtime": "workspace:*",
+    "@perstack/tui": "workspace:*",
     "@tsconfig/node22": "^22.0.5",
     "@types/node": "^25.3.0",
-    "tsdown": "^0.20.3",
-    "typescript": "^5.9.3",
-    "@perstack/core": "0.0.53",
-    "@perstack/runtime": "0.0.113",
-    "@perstack/tui": "0.0.15",
-    "@perstack/perstack-toml": "0.0.9"
+    "typescript": "^5.9.3"
   },
   "engines": {
-    "node": ">=22.0.0"
-  },
-  "scripts": {
-    "clean": "rm -rf dist",
-    "build": "pnpm run clean && tsdown --config ./tsdown.config.ts && cp perstack.toml dist/",
-    "typecheck": "tsc --noEmit"
+    "bun": ">=1.2.0"
   }
-}
+}

package/LICENSE

@@ -1,202 +0,0 @@
-
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [2025] [Wintermute Technologies Inc.]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

package/dist/chunk-D_gEzPfs.js

@@ -1,47 +0,0 @@
-import { createRequire } from "node:module";
-
-//#region \0rolldown/runtime.js
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
-var __exportAll = (all, no_symbols) => {
-	let target = {};
-	for (var name in all) {
-		__defProp(target, name, {
-			get: all[name],
-			enumerable: true
-		});
-	}
-	if (!no_symbols) {
-		__defProp(target, Symbol.toStringTag, { value: "Module" });
-	}
-	return target;
-};
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") {
-		for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-			key = keys[i];
-			if (!__hasOwnProp.call(to, key) && key !== except) {
-				__defProp(to, key, {
-					get: ((k) => from[k]).bind(null, key),
-					enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-				});
-			}
-		}
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-var __toCommonJS = (mod) => __hasOwnProp.call(mod, "module.exports") ? mod["module.exports"] : __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-//#endregion
-export { __toCommonJS as a, __require as i, __esmMin as n, __toESM as o, __exportAll as r, __commonJSMin as t };