fix(bootstrap): simplify skill usage guidance (#368)

* fix(bootstrap): simplify skill usage guidance

* fix(bootstrap): update standalone brainstorm reference

Author: marcusrbrown

README.md

@@ -402,7 +402,7 @@ The plugin exposes one tool to OpenCode:
 |------|-------------|
 | `systematic_skill` | Load Systematic bundled skills by name. Lists available skills in its description and returns formatted skill content when invoked. |
 
-For non-Systematic skills (project or user-level), use OpenCode's native `skill` tool.
+For non-Systematic skills (project or user-level), use OpenCode's `skill` tool.
 
 ## How It Works
 

docs/CONVERSION-GUIDE.md

@@ -306,28 +306,19 @@ systematic/
 
 1. **Project skills**: `.opencode/skills/` in current project
 2. **User skills**: `~/.config/opencode/skills/`
-3. **Bundled skills**: Provided by systematic plugin
+3. **Bundled skills**: Provided by the Systematic plugin
 
-### Tool Mapping Instruction
+### Tool References
 
-Include this instruction in skills that reference tools:
-
-```markdown
-**Tool Mapping for OpenCode:**
-When skills reference tools you don't have, substitute OpenCode equivalents:
-- `TodoWrite` → `todowrite`
-- `Task` tool with subagents → Use OpenCode's subagent system (@mention)
-- `Skill` tool → OpenCode's native `skill` tool
-- `SystematicSkill` tool → `systematic_skill` (Systematic plugin skills)
-- `Read`, `Write`, `Edit`, `Bash` → Your native tools
-- `AskUserQuestion` tool → Use OpenCode's native `question` tool
-```
+Author Systematic skills directly against OpenCode tool names. Do not add a
+generic tool-mapping block to converted skills; converter output should use the
+actual tool names the runtime exposes.
 
 ### Bootstrap Skill Pattern
 
 The `using-systematic` skill is injected into the system prompt and teaches the agent:
 - How to discover available skills
-- When to use `systematic_skill` vs native `skill` tool
+- When to use `systematic_skill` vs the `skill` tool
 - Skill invocation discipline (invoke BEFORE any response)
 
 ---

docs/src/content/docs/guides/conversion-guide.mdx

@@ -307,28 +307,19 @@ systematic/
 
 1. **Project skills**: `.opencode/skills/` in current project
 2. **User skills**: `~/.config/opencode/skills/`
-3. **Bundled skills**: Provided by systematic plugin
+3. **Bundled skills**: Provided by the Systematic plugin
 
-### Tool Mapping Instruction
+### Tool References
 
-Include this instruction in skills that reference tools:
-
-```markdown
-**Tool Mapping for OpenCode:**
-When skills reference tools you don't have, substitute OpenCode equivalents:
-- `TodoWrite` → `todowrite`
-- `Task` tool with subagents → Use OpenCode's subagent system (@mention)
-- `Skill` tool → OpenCode's native `skill` tool
-- `SystematicSkill` tool → `systematic_skill` (Systematic plugin skills)
-- `Read`, `Write`, `Edit`, `Bash` → Your native tools
-- `AskUserQuestion` tool → Use OpenCode's native `question` tool
-```
+Author Systematic skills directly against OpenCode tool names. Do not add a
+generic tool-mapping block to converted skills; converter output should use the
+actual tool names the runtime exposes.
 
 ### Bootstrap Skill Pattern
 
 The `using-systematic` skill is injected into the system prompt and teaches the agent:
 - How to discover available skills
-- When to use `systematic_skill` vs native `skill` tool
+- When to use `systematic_skill` vs the `skill` tool
 - Skill invocation discipline (invoke BEFORE any response)
 
 ---

registry/files/profiles/omo/AGENTS.md

@@ -71,15 +71,15 @@ This loads Systematic's skills guide. Then check OMO:
 
 ### Typical Systematic-only Flow
 ```
-/systematic:brainstorming → Design
+/ce:brainstorm → Design
 /workflows:plan → Create detailed plan
 /workflows:review → Architectural review
 /workflows:work → Disciplined execution
 ```
 
 ### Combined OMO + Systematic Flow (Recommended)
 ```
-1. /systematic:brainstorming → Explore design space
+1. /ce:brainstorm → Explore design space
 2. @Metis → Find hidden requirements
 3. /workflows:plan → Create executable plan
 4. @Sisyphus with parallel agents → Execute with OMO power:
@@ -95,7 +95,7 @@ This loads Systematic's skills guide. Then check OMO:
 
 | Need | Tool | Why |
 |------|------|-----|
-| Systematic exploration | `/systematic:brainstorming` | Structured dialogue, captures requirements |
+| Systematic exploration | `/ce:brainstorm` | Structured dialogue, captures requirements |
 | Finding hidden issues | `@Metis` | Pre-planning expert finds gaps |
 | Detailed planning | `/workflows:plan` | Multi-phase plans with resource allocation |
 | Codebase research | `@Sisyphus` + `@explore` | Parallel search across files |
@@ -134,7 +134,7 @@ Results documented in compound-docs
 | Skill | Command | Use Case |
 |-------|---------|----------|
 | `using-systematic` | `/systematic:using-systematic` | Bootstrap — learn Systematic |
-| `brainstorming` | `/systematic:brainstorming` | Explore features, requirements |
+| `ce:brainstorm` | `/ce:brainstorm` | Explore features, requirements |
 | `git-worktree` | `/systematic:git-worktree` | Isolated parallel development |
 | `frontend-design` | `/systematic:frontend-design` | Production-grade UI implementation |
 | `create-agent-skill` | `/systematic:create-agent-skill` | Author new skills |

registry/files/profiles/standalone/AGENTS.md

@@ -40,7 +40,7 @@ This skill teaches you how to discover and use all available Systematic skills.
 Before implementing features, explore requirements systematically:
 
 ```
-/systematic:brainstorming
+/ce:brainstorm
 ```
 
 This guides collaborative design thinking and requirement clarification.
@@ -84,7 +84,7 @@ Full workflow from plan to execution:
 | Skill | Use Case |
 |-------|----------|
 | `using-systematic` | Bootstrap — learn how to use Systematic |
-| `brainstorming` | Explore features before planning |
+| `ce:brainstorm` | Explore features before planning |
 | `git-worktree` | Isolated parallel development with git |
 | `frontend-design` | Production-grade UI implementation |
 | `agent-native-architecture` | Design systems where agents are first-class |

skills/using-systematic/SKILL.md

@@ -13,7 +13,7 @@ This is not negotiable. This is not optional. You cannot rationalize your way ou
 
 ## How to Access Skills
 
-Use the `systematic_skill` tool for Systematic bundled skills. Use the native `skill` tool for non-Systematic skills. When you invoke a skill, its content is loaded and presented to you—follow it directly.
+Use the `systematic_skill` tool for Systematic bundled skills. Use the `skill` tool for non-Systematic skills. When you invoke a skill, its content is loaded and presented to you—follow it directly.
 
 # Using Skills
 
@@ -94,4 +94,4 @@ Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
 
 ## Skill Resolution
 
-Systematic bundled skills are listed in the `systematic_skill` tool description. Use the native `skill` tool for skills outside the Systematic plugin.
+Systematic bundled skills are listed in the `systematic_skill` tool description. Use the `skill` tool for skills outside the Systematic plugin.

src/lib/bootstrap.ts

@@ -109,22 +109,15 @@ export interface BootstrapDeps {
   bundledSkillsDir: string
 }
 
-function getToolMappingTemplate(): string {
-  return `**Tool Mapping for OpenCode:**
-When skills reference tools you don't have, substitute OpenCode equivalents:
-- \`TodoWrite\` → \`todowrite\`
-- \`Task\` tool with subagents → Use OpenCode's subagent system (@mention)
-- \`Skill\` tool → OpenCode's native \`skill\` tool
-- \`SystematicSkill\` tool → \`systematic_skill\` (Systematic plugin skills)
-- \`Read\`, \`Write\`, \`Edit\`, \`Bash\` → Your native tools
-
-**Skills naming:**
-- Bundled skills use the \`systematic:\` prefix (e.g., \`systematic:brainstorming\`)
+function getSkillUsageTemplate(): string {
+  return `**Skills naming:**
+- Systematic bundled skills use the \`systematic:\` prefix (e.g., \`systematic:setup\`)
+- Workflow skills with their own namespace keep it (e.g., \`ce:brainstorm\`)
 - Skills can also be invoked without prefix if unambiguous
 
 **Skills usage:**
 - Use \`systematic_skill\` to load Systematic bundled skills
-- Use the native \`skill\` tool for non-Systematic skills
+- Use the \`skill\` tool for non-Systematic skills
 
 **Skills location:**
 Bundled skills ship with the Systematic plugin and are discoverable via \`systematic_skill\`.`
@@ -156,20 +149,20 @@ export function getBootstrapContent(
   const fullContent = fs.readFileSync(usingSystematicPath, 'utf8')
   const { body } = parseFrontmatter(fullContent)
   const content = body.trim()
-  const toolMapping = getToolMappingTemplate()
+  const skillUsage = getSkillUsageTemplate()
   const catalog = renderCatalogVerbose({
     bundledSkillsDir,
     disabledSkills: config.disabled_skills,
   })
   const catalogSection = catalog.length > 0 ? `\n\n${catalog}` : ''
 
   return `<SYSTEMATIC_WORKFLOWS>
-You have access to structured engineering workflows via the systematic plugin.
+You have access to structured engineering workflows via the Systematic plugin.
 
 **IMPORTANT: The using-systematic skill content is included below. It is ALREADY LOADED - you are currently following it. Do NOT use the systematic_skill tool to load "using-systematic" again - that would be redundant.**
 
 ${content}
 
-${toolMapping}${catalogSection}
+${skillUsage}${catalogSection}
 </SYSTEMATIC_WORKFLOWS>`
 }

tests/unit/bootstrap.test.ts

@@ -1,19 +1,11 @@
-import {
-  afterAll,
-  afterEach,
-  beforeEach,
-  describe,
-  expect,
-  test,
-} from 'bun:test'
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
 import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import {
   getBootstrapContent,
   INTERNAL_AGENT_SIGNATURES,
 } from '../../src/lib/bootstrap.ts'
-import { TOOL_NAME_MAP } from '../../src/lib/converter.ts'
 
 /**
  * Reconstruct the production skip predicate from src/index.ts:91-97 using the
@@ -76,7 +68,8 @@ describe('getBootstrapContent', () => {
     expect(content).toContain('<SYSTEMATIC_WORKFLOWS>')
     expect(content).toContain('</SYSTEMATIC_WORKFLOWS>')
     expect(content).toContain('Bootstrap body content here.')
-    expect(content).toContain('**Tool Mapping for OpenCode:**')
+    expect(content).toContain('**Skills naming:**')
+    expect(content).not.toContain('**Tool Mapping for OpenCode:**')
   })
 
   test('config.bootstrap.enabled = false returns null', () => {
@@ -181,7 +174,7 @@ describe('getBootstrapContent', () => {
     expect(content).not.toContain('description: Test skill')
   })
 
-  test('tool-mapping template does not embed bundledSkillsDir as a raw path', () => {
+  test('skill-usage template does not embed bundledSkillsDir as a raw path', () => {
     const bundledSkillsDir = makeBundledSkillsDir(
       '---\nname: using-systematic\n---\nbody',
     )
@@ -194,16 +187,16 @@ describe('getBootstrapContent', () => {
     const content = getBootstrapContent(config, { bundledSkillsDir })
 
     expect(content).not.toBeNull()
-    // The tool-mapping prose must not embed the raw path. Slice from the
+    // The skill-usage prose must not embed the raw path. Slice from the
     // heading up to the catalog block (or end of string if no catalog).
-    const toolMappingHeading = '**Tool Mapping for OpenCode:**'
-    const toolMappingStart = (content ?? '').indexOf(toolMappingHeading)
-    expect(toolMappingStart).toBeGreaterThan(-1)
-    const afterHeading = (content ?? '').slice(toolMappingStart)
+    const skillUsageHeading = '**Skills naming:**'
+    const skillUsageStart = (content ?? '').indexOf(skillUsageHeading)
+    expect(skillUsageStart).toBeGreaterThan(-1)
+    const afterHeading = (content ?? '').slice(skillUsageStart)
     const catalogStart = afterHeading.indexOf('<available_skills>')
-    const toolMappingProse =
+    const skillUsageProse =
       catalogStart >= 0 ? afterHeading.slice(0, catalogStart) : afterHeading
-    expect(toolMappingProse).not.toContain(bundledSkillsDir)
+    expect(skillUsageProse).not.toContain(bundledSkillsDir)
     expect(content).toContain(
       'Bundled skills ship with the Systematic plugin and are discoverable via `systematic_skill`.',
     )
@@ -426,124 +419,3 @@ describe('INTERNAL_AGENT_SIGNATURES skip heuristic', () => {
     expect(shouldSkipBootstrap(legitimate)).toBe(true)
   })
 })
-
-// ---------------------------------------------------------------------------
-// TOOL_NAME_MAP ↔ bootstrap template consistency
-// ---------------------------------------------------------------------------
-
-describe('TOOL_NAME_MAP / bootstrap template consistency', () => {
-  // Track temp dirs created by createTempBundledSkillsDir for cleanup.
-  const tempDirs: string[] = []
-  afterAll(() => {
-    for (const dir of tempDirs) {
-      fs.rmSync(dir, { recursive: true, force: true })
-    }
-  })
-  /**
-   * Extract all CC tool names from the left side of `→` arrows in the
-   * "Tool Mapping for OpenCode" section of the bootstrap template.
-   *
-   * Handles all three bullet forms found in the template:
-   *   - `X` → `y`              (simple 1:1, backtick-delimited OC name)
-   *   - `X` tool with … → prose  (prose RHS; extracts X only)
-   *   - `A`, `B`, `C` → prose  (multi-name LHS; extracts A, B, C)
-   *
-   * Note: this is an overlap-subset check, not a full-map consistency check.
-   * The bootstrap prose and the converter map only partially overlap by design —
-   * the bootstrap is instructional text, not a serialised TOOL_NAME_MAP.
-   */
-  // Section heading used to locate the tool-mapping block in the bootstrap
-  // template. Must match the literal heading in src/lib/bootstrap.ts's
-  // getToolMappingTemplate(). If that heading changes, this must be updated.
-  const TOOL_MAPPING_HEADING = '**Tool Mapping for OpenCode:**'
-
-  // Matches the start of the NEXT bold markdown heading after the tool-mapping
-  // section. The negative lookahead (?!Tool Mapping) prevents matching the
-  // section's own heading if it appears in a self-referential context.
-  // A new bold heading starting with "Tool" (but not "Tool Mapping") will
-  // correctly terminate the section — the lookahead only exempts the exact
-  // phrase "Tool Mapping".
-  const NEXT_BOLD_HEADING_RE = /\n\*\*(?!Tool Mapping)/
-
-  function extractCCToolNames(template: string): string[] {
-    // Isolate the tool-mapping section to avoid false-positive matches on
-    // unrelated `→` arrows elsewhere in the bootstrap content.
-    const sectionStart = template.indexOf(TOOL_MAPPING_HEADING)
-    if (sectionStart === -1) return []
-    const rest = template.slice(sectionStart)
-    const nextHeading = rest.search(NEXT_BOLD_HEADING_RE)
-    const section = nextHeading >= 0 ? rest.slice(0, nextHeading) : rest
-
-    // For each bullet line, extract backtick-quoted tokens from the LHS of `→`.
-    // Uses flatMap to avoid nested loops that inflate cognitive complexity.
-    return section
-      .split('\n')
-      .filter((line) => line.startsWith('- '))
-      .flatMap((line) => {
-        const arrowIdx = line.indexOf(' → ')
-        const lhs = arrowIdx >= 0 ? line.slice(0, arrowIdx) : line
-        return [...lhs.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? '')
-      })
-      .filter(Boolean)
-  }
-
-  /**
-   * Names that appear in the template mapping section but are intentionally
-   * Systematic-specific rather than imported from CC. These do not need a
-   * TOOL_NAME_MAP entry (the map covers CC→Systematic converter renames only).
-   */
-  const SYSTEMATIC_ONLY_TOOLS = new Set(['systematicskill'])
-
-  test('rendered template contains at least one CC tool reference', () => {
-    const content = getBootstrapContent(
-      {
-        bootstrap: { enabled: true, file: undefined },
-        disabled_skills: [],
-        disabled_agents: [],
-        disabled_commands: [],
-      },
-      { bundledSkillsDir: createTempBundledSkillsDir() },
-    )
-    expect(content).not.toBeNull()
-    expect(extractCCToolNames(content ?? '').length).toBeGreaterThan(0)
-  })
-
-  test('every CC tool name in the template mapping section is a key in TOOL_NAME_MAP', () => {
-    const content = getBootstrapContent(
-      {
-        bootstrap: { enabled: true, file: undefined },
-        disabled_skills: [],
-        disabled_agents: [],
-        disabled_commands: [],
-      },
-      { bundledSkillsDir: createTempBundledSkillsDir() },
-    )
-    const ccNames = extractCCToolNames(content ?? '')
-    // Guard against section-parse regressions
-    expect(ccNames.length).toBeGreaterThan(0)
-
-    for (const cc of ccNames) {
-      const normalized = cc.toLowerCase()
-      if (SYSTEMATIC_ONLY_TOOLS.has(normalized)) continue
-      expect(
-        TOOL_NAME_MAP,
-        `Bootstrap template references "${cc}" but TOOL_NAME_MAP has no key "${normalized}"`,
-      ).toHaveProperty(normalized)
-    }
-  })
-
-  function createTempBundledSkillsDir(): string {
-    const dir = fs.mkdtempSync(
-      path.join(os.tmpdir(), 'systematic-bootstrap-consistency-'),
-    )
-    tempDirs.push(dir)
-    fs.mkdirSync(path.join(dir, 'skills', 'using-systematic'), {
-      recursive: true,
-    })
-    fs.writeFileSync(
-      path.join(dir, 'skills', 'using-systematic', 'SKILL.md'),
-      '---\nname: using-systematic\n---\nbody',
-    )
-    return path.join(dir, 'skills')
-  }
-})