Merge pull request 'fix: simplify prompt subcommands, framework-agnostic bootstrap' (#100) from fix/99-prompt-cleanup into main

packages/cli/src/__tests__/prompt.test.ts

@@ -9,31 +9,25 @@ import {
   cmdPromptAdapterDeveloping,
   cmdPromptBootstrap,
   cmdPromptList,
-  cmdPromptSetup,
   cmdPromptUsage,
-  cmdPromptUsageReference,
   cmdPromptWorkflowAuthoring,
 } from "../commands/prompt.js";
 
 describe("prompt commands", () => {
-  test("prompt list returns new prompt names", () => {
+  test("prompt list returns prompt names (no bootstrap)", () => {
     const result = cmdPromptList();
     expect(result).toBeInstanceOf(Array);
     expect(result).toContain("usage");
     expect(result).toContain("workflow-authoring");
     expect(result).toContain("adapter-developing");
-    expect(result).toContain("bootstrap");
-    expect(result).not.toContain("user");
-    expect(result).not.toContain("author");
-    expect(result).not.toContain("developer");
-    expect(result).not.toContain("adapter");
+    expect(result).not.toContain("bootstrap");
     for (const name of result) {
       expect(name).toMatch(/^\S+$/);
     }
   });
 
-  test("prompt usage-reference returns non-empty markdown string with frontmatter", () => {
-    const result = cmdPromptUsageReference();
+  test("prompt usage returns only the usage reference with frontmatter", () => {
+    const result = cmdPromptUsage();
     expect(typeof result).toBe("string");
     expect(result).toContain("uwf");
     expect(result).toContain("thread");
@@ -42,6 +36,9 @@ describe("prompt commands", () => {
     expect(result).toContain("---");
     expect(result).toContain("name:");
     expect(result).toContain("version:");
+    // Should NOT contain other references
+    expect(result).not.toContain("Workflow Authoring Reference");
+    expect(result).not.toContain("Adapter Developing Reference");
     expect(result.length).toBeGreaterThan(500);
   });
 
@@ -71,44 +68,19 @@ describe("prompt commands", () => {
     expect(result.length).toBeGreaterThan(500);
   });
 
-  test("prompt bootstrap returns non-empty skill with frontmatter", () => {
+  test("prompt bootstrap returns framework-agnostic setup instructions", () => {
     const result = cmdPromptBootstrap();
     expect(typeof result).toBe("string");
-    expect(result).toContain("uwf");
-    expect(result).toContain("---");
-    expect(result.length).toBeGreaterThan(100);
-  });
-
-  test("prompt usage combines remaining references (no developer)", () => {
-    const result = cmdPromptUsage();
-    expect(typeof result).toBe("string");
-    expect(result).toContain("Usage Reference");
-    expect(result).toContain("Workflow Authoring Reference");
-    expect(result).toContain("Adapter Developing Reference");
-    expect(result).not.toContain("Developer Reference");
-    expect(result).toContain("---");
-    expect(result.length).toBeGreaterThan(2000);
-  });
-
-  test("prompt setup returns simplified setup instructions", () => {
-    const result = cmdPromptSetup();
-    expect(typeof result).toBe("string");
-    expect(result).toContain("uwf Skill Setup");
-    expect(result).toContain("uwf prompt bootstrap");
-    expect(result).toContain("SKILL.md");
-    expect(result).toContain("version");
-    expect(result).not.toMatch(/\bbun (install|run|test|changeset|version|release)\b/);
-  });
-
-  test("prompt setup references new subcommand names", () => {
-    const result = cmdPromptSetup();
     expect(result).toContain("uwf prompt usage");
     expect(result).toContain("uwf prompt workflow-authoring");
     expect(result).toContain("uwf prompt adapter-developing");
-    expect(result).not.toContain("uwf prompt user");
-    expect(result).not.toContain("uwf prompt author");
-    expect(result).not.toContain("uwf prompt developer");
-    expect(result).not.toMatch(/uwf prompt adapter\b(?!-developing)/);
+    expect(result).toContain("uwf-usage");
+    expect(result).toContain("uwf-workflow-authoring");
+    expect(result).toContain("uwf-adapter-developing");
+    // Should NOT contain Hermes-specific paths
+    expect(result).not.toContain("~/.hermes/skills/");
+    expect(result).not.toContain("> ~/.hermes/");
+    expect(result.length).toBeGreaterThan(100);
   });
 
   test("prompt help subcommand is suppressed", { timeout: 30_000 }, () => {
@@ -119,11 +91,12 @@ describe("prompt commands", () => {
     });
     expect(output).not.toMatch(/help\s+\[command\]/i);
     expect(output).toContain("usage");
-    expect(output).toContain("setup");
+    expect(output).toContain("bootstrap");
     expect(output).toContain("workflow-authoring");
     expect(output).toContain("adapter-developing");
-    expect(output).toContain("bootstrap");
     expect(output).toContain("list");
-    expect(output).not.toContain("developer");
+    // Removed subcommands should not appear as command names
+    expect(output).not.toMatch(/^\s+setup\s/m);
+    expect(output).not.toContain("usage-reference");
   });
 });

packages/cli/src/cli.ts

@@ -8,9 +8,7 @@ import {
   cmdPromptAdapterDeveloping,
   cmdPromptBootstrap,
   cmdPromptList,
-  cmdPromptSetup,
   cmdPromptUsage,
-  cmdPromptUsageReference,
   cmdPromptWorkflowAuthoring,
 } from "./commands/prompt.js";
 import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js";
@@ -509,23 +507,16 @@ prompt.addHelpCommand(false);
 
 prompt
   .command("usage")
-  .description("Print the complete skill content (all references combined)")
+  .description("Print the usage reference (CLI guide + typical workflows)")
   .action(() => {
     console.log(cmdPromptUsage());
   });
 
 prompt
-  .command("setup")
-  .description("Print setup instructions for installing the uwf skill")
+  .command("bootstrap")
+  .description("Print setup instructions for installing uwf skills")
   .action(() => {
-    console.log(cmdPromptSetup());
-  });
-
-prompt
-  .command("usage-reference")
-  .description("Print the usage reference (CLI guide + typical workflows)")
-  .action(() => {
-    console.log(cmdPromptUsageReference());
+    console.log(cmdPromptBootstrap());
   });
 
 prompt
@@ -542,13 +533,6 @@ prompt
     console.log(cmdPromptAdapterDeveloping());
   });
 
-prompt
-  .command("bootstrap")
-  .description("Print the bootstrap skill YAML for Hermes agents")
-  .action(() => {
-    console.log(cmdPromptBootstrap());
-  });
-
 prompt
   .command("list")
   .description("List all available prompt names")

packages/cli/src/commands/prompt.ts

@@ -1,14 +1,13 @@
 import {
   generateAdapterDevelopingReference,
-  generateBootstrapReference,
   generateUsageReference,
   generateWorkflowAuthoringReference,
+  VERSION,
 } from "@united-workforce/util";
 
 export {
   generateAdapterDevelopingReference as cmdPromptAdapterDeveloping,
-  generateBootstrapReference as cmdPromptBootstrap,
-  generateUsageReference as cmdPromptUsageReference,
+  generateUsageReference as cmdPromptUsage,
   generateWorkflowAuthoringReference as cmdPromptWorkflowAuthoring,
 };
 
@@ -16,24 +15,16 @@ const PROMPT_ENTRIES: ReadonlyArray<{ name: string; generate: () => string }> =
   { name: "usage", generate: generateUsageReference },
   { name: "workflow-authoring", generate: generateWorkflowAuthoringReference },
   { name: "adapter-developing", generate: generateAdapterDevelopingReference },
-  { name: "bootstrap", generate: generateBootstrapReference },
 ];
 
 export function cmdPromptList(): ReadonlyArray<string> {
   return PROMPT_ENTRIES.map((e) => e.name);
 }
 
-export function cmdPromptUsage(): string {
-  return PROMPT_ENTRIES.filter((e) => e.name !== "bootstrap")
-    .map((e) => e.generate())
-    .join("\n\n---\n\n");
-}
+export function cmdPromptBootstrap(): string {
+  return `# uwf Skill Bootstrap
 
-export function cmdPromptSetup(): string {
-  return `# uwf Skill Setup
-
-You are being asked to install or update the uwf (United Workforce) skill
-so that you know how to use the \`uwf\` CLI for workflow orchestration.
+Install or update the uwf (United Workforce) skills for your agent.
 
 ## Steps
 
@@ -42,40 +33,30 @@ so that you know how to use the \`uwf\` CLI for workflow orchestration.
    uwf --help
    \`\`\`
    If not installed: \`npm install -g @united-workforce/cli\`
+   Current version: ${VERSION}
 
-2. **Clean up old versions of the skill** (if any exist):
-   - Look for any existing uwf/workflow skill files in your skill directories
-     (e.g. \`~/.hermes/skills/uwf/SKILL.md\` or similar paths).
-   - If a skill exists, read its \`version\` from the YAML frontmatter.
-   - If the version matches the current CLI version (\`uwf --version\`), you're done — no update needed.
-   - If the version is older, **delete the old skill file** before proceeding.
+2. **Install the skills** by running each command below and creating a skill from its output:
+   - Run \`uwf prompt usage\` → create a skill named \`uwf-usage\`
+   - Run \`uwf prompt workflow-authoring\` → create a skill named \`uwf-workflow-authoring\`
+   - Run \`uwf prompt adapter-developing\` → create a skill named \`uwf-adapter-developing\`
 
-3. **Install the bootstrap skill:**
-   \`\`\`bash
-   uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md
-   \`\`\`
-   The bootstrap prompt already includes complete YAML frontmatter — no editing needed.
+   Each command outputs a complete SKILL.md with YAML frontmatter — use your agent framework's skill creation API to save them.
 
-4. **Verify** the skill is loadable by your agent framework.
+3. **Verify** the skills are loadable by your agent framework.
 
-## Individual prompts
+## Updating
 
-Each prompt outputs a complete SKILL.md with frontmatter — pipe directly to a file:
+When \`uwf\` is upgraded, re-run \`uwf prompt bootstrap\` and follow the steps again.
+The skill content is bundled with the CLI — always use \`uwf prompt <name>\` to get
+content matching your installed version.
+
+## Available prompts
 
 \`\`\`bash
-uwf prompt list                                              # list available prompt names
-uwf prompt usage > ~/.hermes/skills/uwf-usage/SKILL.md      # CLI usage guide
-uwf prompt workflow-authoring > ~/.hermes/skills/uwf-workflow-authoring/SKILL.md
-uwf prompt adapter-developing > ~/.hermes/skills/uwf-adapter-developing/SKILL.md
-uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md        # bootstrap skill
+uwf prompt list                # list available prompt names
+uwf prompt usage               # CLI usage guide
+uwf prompt workflow-authoring  # workflow YAML design guide
+uwf prompt adapter-developing  # building agent adapters
 \`\`\`
-
-## Notes
-
-- The skill content is bundled with the CLI and versioned with it — always use
-  \`uwf prompt usage\` to get the content matching your installed version.
-- Do NOT hand-edit the skill body. If the CLI is updated, re-run \`uwf prompt setup\`
-  and follow the steps again.
-- When upgrading, always delete the old skill first to avoid stale instructions.
 `;
 }

packages/util/src/bootstrap-reference.ts

@@ -1,40 +0,0 @@
-export function generateBootstrapReference(): string {
-  return `---
-name: uwf
-description: "United Workforce (uwf) — YAML 状态机工作流引擎。任务涉及 workflow 时加载此 skill。"
-tags: [workflow, uwf]
-triggers:
-  - uwf
-  - workflow
-  - 工作流
----
-
-# uwf (United Workforce)
-
-YAML 状态机工作流引擎。当用户提到「workflow」「工作流」时，指的是 **uwf workflow**（YAML 定义的状态机），不是 Hermes skill。用 \`uwf\` CLI 操作，不要混淆。
-
-## 首次使用
-
-运行以下命令获取完整用法：
-
-\`\`\`bash
-uwf prompt usage                 # 完整用法文档（所有引用合并）
-uwf prompt workflow-authoring    # workflow 编写指南（role 定义、graph 路由、schema）
-uwf prompt adapter-developing    # adapter 开发指南（构建新的 agent adapter）
-\`\`\`
-
-## 快速参考
-
-\`\`\`bash
-uwf workflow list                          # 查看已注册 workflow
-uwf workflow add <file.yaml>               # 注册 workflow
-uwf thread start <workflow> -p "prompt"    # 创建 thread
-uwf thread exec <thread-id> -c 10          # 执行最多 10 步
-uwf thread list                            # 查看所有 thread
-\`\`\`
-
-## 示例 workflow
-
-参考项目 \`examples/\` 目录下的 YAML 文件（analyze-topic、debate、solve-issue）。
-`;
-}

packages/util/src/index.ts

@@ -2,7 +2,6 @@ export { generateActorReference } from "./actor-reference.js";
 export { generateAdapterDevelopingReference } from "./adapter-developing-reference.js";
 export { generateArchitectureReference } from "./architecture-reference.js";
 export { encodeUint64AsCrockford } from "./base32.js";
-export { generateBootstrapReference } from "./bootstrap-reference.js";
 export { generateCliReference } from "./cli-reference.js";
 export { env } from "./env.js";
 export type {