@fro.bot/systematic 1.5.0 → 1.7.0

package/LICENSE

@@ -0,0 +1,20 @@
+# The MIT License (MIT)
+
+Copyright (c) 2022 Marcus R. Brown <git@mrbro.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,122 +1,324 @@
-# Systematic
+<div align="center">
 
-An OpenCode plugin providing systematic engineering workflows from the [Compound Engineering Plugin (CEP)](https://github.com/EveryInc/compound-engineering-plugin) Claude Code plugin, adapted for OpenCode.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="./assets/banner.svg">
+  <source media="(prefers-color-scheme: light)" srcset="./assets/banner.svg">
+  <img alt="Systematic - Structured Engineering Workflows for OpenCode" src="./assets/banner.svg" width="100%">
+</picture>
 
-## Installation
+<br><br>
+
+[![Build Status](https://img.shields.io/github/actions/workflow/status/marcusrbrown/systematic/main.yaml?style=flat-square&label=build&labelColor=1a1a2e&color=4FD1C5)](https://github.com/marcusrbrown/systematic/actions)
+[![npm version](https://img.shields.io/npm/v/@fro.bot/systematic?style=flat-square&label=npm&labelColor=1a1a2e&color=E91E8C)](https://www.npmjs.com/package/@fro.bot/systematic)
+[![License](https://img.shields.io/badge/license-MIT-F5A623?style=flat-square&labelColor=1a1a2e)](LICENSE)
+
+<br>
+
+**[Overview](#overview)** · **[Quick Start](#quick-start)** · **[Skills](#skills)** · **[Agents](#agents)** · **[Commands](#commands)** · **[Development](#development)**
+
+</div>
+
+---
+
+## Overview
+
+Systematic is an [OpenCode](https://opencode.ai/) plugin that transforms your AI assistant into a **disciplined engineering collaborator**. It provides battle-tested workflows adapted from the [Compound Engineering Plugin (CEP)](https://github.com/EveryInc/compound-engineering-plugin) for Claude Code.
+
+### Why Systematic?
+
+Most AI coding assistants respond to requests without structure or methodology. This leads to inconsistent outputs, missed requirements, and wasted iterations.
+
+**Systematic solves this with structured workflows.** The plugin injects proven engineering processes directly into your AI's system prompt, enabling it to:
+
+- **Brainstorm systematically** before jumping to implementation
+- **Plan with rigor** using multi-phase workflows
+- **Review code architecturally** with specialized agents
+- **Follow consistent patterns** across your entire team
+
+### Key Features
+
+- **🧠 Structured Skills** — Pre-built workflows for brainstorming, planning, and code review
+- **🤖 Specialized Agents** — Purpose-built subagents for architecture, security, and performance
+- **⚡ Zero Configuration** — Works immediately after installation via config hooks
+- **🔧 Extensible** — Add project-specific skills and commands alongside bundled ones
+- **📦 Batteries Included** — Skills, agents, and commands ship with the npm package
+
+## Quick Start
+
+### Prerequisites
+
+- [OpenCode](https://opencode.ai/) installed and configured
+- Node.js 18+ or Bun runtime
+
+### Installation
+
+Install the plugin via npm:
 
 ```bash
 npm install @fro.bot/systematic
 ```
 
-Add to your OpenCode config (`~/.config/opencode/opencode.json`):
+Add it to your OpenCode configuration (`~/.config/opencode/opencode.json`):
 
 ```json
 {
-  "plugin": ["@fro.bot/systematic"]
+  "plugins": ["@fro.bot/systematic"]
 }
 ```
 
-## Features
+That's it. Restart OpenCode and the plugin's skills, agents, and commands are available immediately.
+
+> [!NOTE]
+> Systematic uses OpenCode's `config` hook to automatically register all bundled content. No manual file copying required.
+
+### Verify Installation
+
+In any OpenCode conversation, type:
+
+```
+/systematic:using-systematic
+```
+
+If the skill loads and displays usage instructions, the plugin is working correctly.
 
-### Skills
+## Skills
 
-Systematic includes battle-tested engineering workflows:
+Skills are structured workflows that guide the AI through systematic engineering processes. They're loaded via the `systematic_skill` tool.
 
 | Skill | Description |
 |-------|-------------|
-| `using-systematic` | Bootstrap skill for discovering and using other skills |
-| `brainstorming` | Collaborative design workflow |
-| `agent-browser` | Browser automation with Playwright |
-| `agent-native-architecture` | Design systems for AI agents |
-| `compound-docs` | Create and maintain compound documentation |
-| `create-agent-skills` | Write new skills for AI agents |
-| `file-todos` | Manage TODO items in files |
-| `git-worktree` | Use git worktrees for isolated development |
+| `using-systematic` | Bootstrap skill — teaches the AI how to discover and use other skills |
+| `brainstorming` | Collaborative design workflow for exploring ideas before planning |
+| `agent-browser` | Browser automation using Vercel's agent-browser CLI |
+| `agent-native-architecture` | Design systems where AI agents are first-class citizens |
+| `compound-docs` | Capture solved problems as categorized documentation |
+| `create-agent-skills` | Expert guidance for writing and refining skills |
+| `file-todos` | File-based todo tracking with status and dependency management |
+| `git-worktree` | Manage git worktrees for isolated parallel development |
 
-### Commands
+### How Skills Work
 
-Quick shortcuts to invoke workflows:
+Skills are Markdown files with YAML frontmatter. When loaded, their content is injected into the conversation, guiding the AI's behavior:
 
-**Workflows:**
+```markdown
+---
+name: brainstorming
+description: This skill should be used before implementing features...
+---
 
-- `/workflows:brainstorm` - Start collaborative brainstorming
-- `/workflows:compound` - Build compound documentation
-- `/workflows:plan` - Create implementation plans
-- `/workflows:review` - Run code review with agents
-- `/workflows:work` - Execute planned work
+# Brainstorming
 
-**Utilities:**
+This skill provides detailed process knowledge for effective brainstorming...
+```
 
-- `/agent-native-audit` - Audit code for agent-native patterns
-- `/create-agent-skill` - Create a new skill
-- `/deepen-plan` - Add detail to existing plans
-- `/lfg` - Let's go - start working immediately
+The AI is instructed to invoke skills **before** taking action — even with a 1% chance a skill might apply.
 
-### Agents
+## Agents
 
-Specialized agents organized by category:
+Agents are specialized subagents with pre-configured prompts and expertise. They're registered automatically via the config hook.
 
-**Review:**
+### Review Agents
 
-- `architecture-strategist` - Architectural review
-- `security-sentinel` - Security review
-- `code-simplicity-reviewer` - Complexity review
-- `pattern-recognition-specialist` - Pattern analysis
-- `performance-oracle` - Performance review
+| Agent | Purpose |
+|-------|---------|
+| `architecture-strategist` | Analyze code changes from an architectural perspective |
+| `security-sentinel` | Security audits, vulnerability assessment, OWASP compliance |
+| `code-simplicity-reviewer` | Final review pass for simplicity and YAGNI principles |
+| `pattern-recognition-specialist` | Detect design patterns, anti-patterns, and code smells |
+| `performance-oracle` | Performance analysis, bottleneck identification, scalability |
 
-**Research:**
+### Research Agents
 
-- `framework-docs-researcher` - Documentation research
+| Agent | Purpose |
+|-------|---------|
+| `framework-docs-researcher` | Gather framework documentation and best practices |
 
-## Config Hook
+### Using Agents
 
-Systematic uses OpenCode's `config` hook to automatically register bundled agents, commands, and skills directly into OpenCode's configuration. This means:
+Agents are invoked via OpenCode's `@mention` syntax or `delegate_task`:
 
-- **Zero configuration required** - All bundled content is available immediately after installing the plugin
-- **No file copying** - Skills, agents, and commands ship with the npm package
-- **Existing config preserved** - Your OpenCode configuration settings take precedence over bundled content
+```
+@architecture-strategist Review the authentication refactoring in this PR
+```
 
-## Tools
+Or programmatically in skills/commands:
+
+```
+delegate_task(subagent_type="architecture-strategist", prompt="Review...")
+```
 
-The plugin provides these tools to OpenCode:
+## Commands
 
-| Tool | Description |
-|------|-------------|
-| `systematic_skill` | Load Systematic bundled skills |
+Commands are slash-invokable shortcuts that trigger workflows or actions.
+
+### Workflow Commands
 
-The bootstrap skill instructs OpenCode to use the native `skill` tool to load non-Systematic skills.
+| Command | Description |
+|---------|-------------|
+| `/workflows:brainstorm` | Explore requirements through collaborative dialogue |
+| `/workflows:plan` | Create detailed implementation plans |
+| `/workflows:review` | Run code review with specialized agents |
+| `/workflows:work` | Execute planned work systematically |
+| `/workflows:compound` | Build compound documentation |
+
+### Utility Commands
+
+| Command | Description |
+|---------|-------------|
+| `/lfg` | "Let's go" — start working immediately |
+| `/create-agent-skill` | Create a new skill with guidance |
+| `/deepen-plan` | Add detail to existing plans |
+| `/agent-native-audit` | Audit code for agent-native patterns |
 
 ## Configuration
 
+Systematic works out of the box, but you can customize it via configuration files.
+
+### Plugin Configuration
+
 Create `~/.config/opencode/systematic.json` or `.opencode/systematic.json` to disable specific bundled content:
 
 ```json
 {
-  "disabled_skills": [],
+  "disabled_skills": ["git-worktree"],
   "disabled_agents": [],
   "disabled_commands": []
 }
 ```
 
+### Project-Specific Content
+
+Add your own skills, agents, and commands alongside bundled ones:
+
+```
+.opencode/
+├── skills/
+│   └── my-skill/
+│       └── SKILL.md
+├── agents/
+│   └── my-agent.md
+└── commands/
+    └── my-command.md
+```
+
+Project-level content takes precedence over bundled content with the same name.
+
+## Tools
+
+The plugin exposes one tool to OpenCode:
+
+| Tool | Description |
+|------|-------------|
+| `systematic_skill` | Load Systematic bundled skills by name |
+
+For non-Systematic skills (project or user-level), use OpenCode's native `skill` tool.
+
+## How It Works
+
+Systematic uses three OpenCode plugin hooks:
+
+```mermaid
+flowchart TB
+    A[Plugin Loaded] --> B[config hook]
+    A --> C[tool hook]
+    A --> D[system.transform hook]
+
+    B --> E[Merge bundled agents/commands/skills into OpenCode config]
+    C --> F[Register systematic_skill tool]
+    D --> G[Inject bootstrap prompt into every conversation]
+
+    style A fill:#e1f5fe
+    style E fill:#f1f8e9
+    style F fill:#fff3e0
+    style G fill:#fce4ec
+```
+
+1. **`config` hook** — Merges bundled assets into your OpenCode configuration
+2. **`tool` hook** — Registers the `systematic_skill` tool for loading skills
+3. **`system.transform` hook** — Injects the "Using Systematic" guide into system prompts
+
+This architecture ensures skills, agents, and commands are available immediately without manual setup.
+
 ## Development
 
+### Prerequisites
+
+- [Bun](https://bun.sh/) runtime
+- Node.js 18+ (for compatibility)
+
+### Setup
+
 ```bash
+# Clone the repository
+git clone https://github.com/marcusrbrown/systematic.git
+cd systematic
+
 # Install dependencies
 bun install
 
-# Build
+# Build the plugin
 bun run build
 
-# Typecheck
+# Run type checking
 bun run typecheck
 
-# Lint
+# Run linter
 bun run lint
 
-# Run tests
+# Run unit tests
 bun test
 ```
 
+### Project Structure
+
+```
+├── src/
+│   ├── index.ts              # Plugin entry point
+│   ├── cli.ts                # CLI entry point
+│   └── lib/
+│       ├── bootstrap.ts      # System prompt injection
+│       ├── config.ts         # JSONC config loading
+│       ├── config-handler.ts # OpenCode config hook
+│       ├── skill-tool.ts     # systematic_skill tool
+│       ├── skills.ts         # Skill discovery
+│       ├── agents.ts         # Agent discovery
+│       └── commands.ts       # Command discovery
+├── skills/                   # Bundled skills (SKILL.md files)
+├── agents/                   # Bundled agents (Markdown)
+├── commands/                 # Bundled commands (Markdown)
+├── tests/
+│   ├── unit/                 # Unit tests
+│   └── integration/          # Integration tests
+└── dist/                     # Build output
+```
+
+### Testing
+
+```bash
+# Run all unit tests
+bun test tests/unit
+
+# Run a specific test file
+bun test tests/unit/skills.test.ts
+
+# Run integration tests
+bun test tests/integration
+```
+
+### Contributing
+
+See [`AGENTS.md`](./AGENTS.md) for detailed development guidelines, code style conventions, and architecture overview.
+
+## Converting from Claude Code
+
+Migrating skills, agents, or commands from Claude Code (CEP) to Systematic? See the [Conversion Guide](./docs/CONVERSION-GUIDE.md) for field mappings and examples.
+
+## References
+
+- [OpenCode Documentation](https://opencode.ai/docs/) — Official OpenCode platform docs
+- [Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin) — Original Claude Code workflows
+- [Plugin Source Code](https://github.com/marcusrbrown/systematic) — View the implementation
+
 ## License
 
-MIT
+[MIT](LICENSE) © Marcus R. Brown

package/dist/cli.js

@@ -6,7 +6,7 @@ import {
   findCommandsInDir,
   findSkillsInDir,
   getConfigPaths
-} from "./index-kjhs9jeg.js";
+} from "./index-yxbcy3s7.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/{index-kjhs9jeg.js → index-yxbcy3s7.js}

@@ -96,9 +96,103 @@ function formatFrontmatter(data) {
   return ["---", yamlContent, "---"].join(`
 `);
 }
-function stripFrontmatter(content) {
-  const { body, hadFrontmatter } = parseFrontmatter(content);
-  return hadFrontmatter ? body.trim() : content.trim();
+
+// src/lib/validation.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPermissionSetting(value) {
+  return value === "ask" || value === "allow" || value === "deny";
+}
+function isToolsMap(value) {
+  if (!isRecord(value))
+    return false;
+  return Object.values(value).every((entry) => typeof entry === "boolean");
+}
+function isAgentMode(value) {
+  return value === "subagent" || value === "primary" || value === "all";
+}
+function extractSimplePermission(data, key) {
+  if (!(key in data))
+    return;
+  const value = data[key];
+  return isPermissionSetting(value) ? value : null;
+}
+function extractBashPermission(data) {
+  if (!("bash" in data))
+    return;
+  const bash = data.bash;
+  if (isPermissionSetting(bash))
+    return bash;
+  if (isRecord(bash)) {
+    const entries = Object.entries(bash);
+    if (entries.every(([, setting]) => isPermissionSetting(setting))) {
+      return Object.fromEntries(entries);
+    }
+  }
+  return null;
+}
+function buildPermissionObject(edit, bash, webfetch, doom_loop, external_directory) {
+  const permission = {};
+  if (edit)
+    permission.edit = edit;
+  if (bash)
+    permission.bash = bash;
+  if (webfetch)
+    permission.webfetch = webfetch;
+  if (doom_loop)
+    permission.doom_loop = doom_loop;
+  if (external_directory)
+    permission.external_directory = external_directory;
+  return Object.keys(permission).length > 0 ? permission : undefined;
+}
+function normalizePermission(value) {
+  if (!isRecord(value))
+    return;
+  const bash = extractBashPermission(value);
+  if (bash === null)
+    return;
+  const edit = extractSimplePermission(value, "edit");
+  if (edit === null)
+    return;
+  const webfetch = extractSimplePermission(value, "webfetch");
+  if (webfetch === null)
+    return;
+  const doom_loop = extractSimplePermission(value, "doom_loop");
+  if (doom_loop === null)
+    return;
+  const external_directory = extractSimplePermission(value, "external_directory");
+  if (external_directory === null)
+    return;
+  return buildPermissionObject(edit, bash, webfetch, doom_loop, external_directory);
+}
+function extractString(data, key, fallback = "") {
+  const value = data[key];
+  return typeof value === "string" ? value : fallback;
+}
+function extractNonEmptyString(data, key) {
+  const value = data[key];
+  if (typeof value !== "string")
+    return;
+  const trimmed = value.trim();
+  return trimmed !== "" ? trimmed : undefined;
+}
+function extractNumber(data, key) {
+  const value = data[key];
+  return typeof value === "number" ? value : undefined;
+}
+function extractBoolean(data, key) {
+  const value = data[key];
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true")
+      return true;
+    if (normalized === "false")
+      return false;
+  }
+  return;
 }
 
 // src/lib/walk-dir.ts
@@ -147,11 +241,23 @@ function findAgentsInDir(dir, maxDepth = 2) {
   }));
 }
 function extractAgentFrontmatter(content) {
-  const { data, parseError } = parseFrontmatter(content);
+  const { data, parseError, body } = parseFrontmatter(content);
+  if (parseError) {
+    return { name: "", description: "", prompt: body.trim() };
+  }
   return {
-    name: !parseError && typeof data.name === "string" ? data.name : "",
-    description: !parseError && typeof data.description === "string" ? data.description : "",
-    prompt: stripFrontmatter(content)
+    name: extractString(data, "name"),
+    description: extractString(data, "description"),
+    prompt: body.trim(),
+    model: extractNonEmptyString(data, "model"),
+    temperature: extractNumber(data, "temperature"),
+    top_p: extractNumber(data, "top_p"),
+    tools: isToolsMap(data.tools) ? data.tools : undefined,
+    disable: extractBoolean(data, "disable"),
+    mode: isAgentMode(data.mode) ? data.mode : undefined,
+    color: extractNonEmptyString(data, "color"),
+    maxSteps: extractNumber(data, "maxSteps"),
+    permission: normalizePermission(data.permission)
   };
 }
 
@@ -173,11 +279,24 @@ function findCommandsInDir(dir, maxDepth = 2) {
 }
 function extractCommandFrontmatter(content) {
   const { data, parseError } = parseFrontmatter(content);
-  const argumentHintRaw = !parseError && typeof data["argument-hint"] === "string" ? data["argument-hint"] : "";
+  if (parseError) {
+    return {
+      name: "",
+      description: "",
+      argumentHint: "",
+      agent: undefined,
+      model: undefined,
+      subtask: undefined
+    };
+  }
+  const argumentHintRaw = extractString(data, "argument-hint");
   return {
-    name: !parseError && typeof data.name === "string" ? data.name : "",
-    description: !parseError && typeof data.description === "string" ? data.description : "",
-    argumentHint: argumentHintRaw.replace(/^["']|["']$/g, "")
+    name: extractString(data, "name"),
+    description: extractString(data, "description"),
+    argumentHint: argumentHintRaw.replace(/^["']|["']$/g, ""),
+    agent: extractNonEmptyString(data, "agent"),
+    model: extractNonEmptyString(data, "model"),
+    subtask: extractBoolean(data, "subtask")
   };
 }
 
@@ -293,30 +412,48 @@ function normalizeModel(model) {
     return `google/${model}`;
   return `anthropic/${model}`;
 }
+function addOptionalFields(target, data) {
+  if (typeof data.top_p === "number")
+    target.top_p = data.top_p;
+  if (isToolsMap(data.tools))
+    target.tools = data.tools;
+  if (typeof data.disable === "boolean")
+    target.disable = data.disable;
+  if (typeof data.color === "string")
+    target.color = data.color;
+  if (typeof data.maxSteps === "number")
+    target.maxSteps = data.maxSteps;
+  const permission = normalizePermission(data.permission);
+  if (permission)
+    target.permission = permission;
+}
 function transformAgentFrontmatter(data, agentMode) {
   const name = typeof data.name === "string" ? data.name : "";
   const description = typeof data.description === "string" ? data.description : "";
-  const newData = {
-    description: description || `${name} agent`,
-    mode: agentMode
-  };
+  const mode = isAgentMode(data.mode) ? data.mode : agentMode;
+  const newData = { mode };
+  if (description) {
+    newData.description = description;
+  } else if (name) {
+    newData.description = `${name} agent`;
+  }
   if (typeof data.model === "string" && data.model !== "inherit") {
     newData.model = normalizeModel(data.model);
   }
-  if (typeof data.temperature === "number") {
-    newData.temperature = data.temperature;
-  } else {
-    newData.temperature = inferTemperature(name, description);
-  }
+  newData.temperature = typeof data.temperature === "number" ? data.temperature : inferTemperature(name, description);
+  addOptionalFields(newData, data);
   return newData;
 }
 function convertContent(content, type, options = {}) {
   if (content === "")
     return "";
-  const { data, body, hadFrontmatter } = parseFrontmatter(content);
+  const { data, body, hadFrontmatter, parseError } = parseFrontmatter(content);
   if (!hadFrontmatter) {
     return options.skipBodyTransform ? content : transformBody(content);
   }
+  if (parseError) {
+    return content;
+  }
   const shouldTransformBody = !options.skipBodyTransform;
   const transformedBody = shouldTransformBody ? transformBody(body) : body;
   if (type === "agent") {
@@ -365,9 +502,29 @@ function extractFrontmatter(filePath) {
     if (parseError) {
       return { name: "", description: "" };
     }
+    const metadataRaw = data.metadata;
+    let metadata;
+    if (isRecord(metadataRaw)) {
+      const entries = Object.entries(metadataRaw);
+      if (entries.every(([, v]) => typeof v === "string")) {
+        metadata = Object.fromEntries(entries);
+      }
+    }
+    const argumentHintRaw = extractNonEmptyString(data, "argument-hint");
+    const argumentHint = argumentHintRaw?.replace(/^["']|["']$/g, "") || undefined;
     return {
-      name: typeof data.name === "string" ? data.name : "",
-      description: typeof data.description === "string" ? data.description : ""
+      name: extractString(data, "name"),
+      description: extractString(data, "description"),
+      license: extractNonEmptyString(data, "license"),
+      compatibility: extractNonEmptyString(data, "compatibility"),
+      metadata,
+      disableModelInvocation: extractBoolean(data, "disable-model-invocation"),
+      userInvocable: extractBoolean(data, "user-invocable"),
+      subtask: data.context === "fork" ? true : undefined,
+      agent: extractNonEmptyString(data, "agent"),
+      model: extractNonEmptyString(data, "model"),
+      argumentHint: argumentHint !== "" ? argumentHint : undefined,
+      allowedTools: extractNonEmptyString(data, "allowed-tools")
     };
   } catch {
     return { name: "", description: "" };
@@ -382,34 +539,26 @@ function findSkillsInDir(dir, maxDepth = 3) {
   for (const entry of entries) {
     const skillFile = path3.join(entry.path, "SKILL.md");
     if (fs4.existsSync(skillFile)) {
-      const { name, description } = extractFrontmatter(skillFile);
+      const frontmatter = extractFrontmatter(skillFile);
       skills.push({
         path: entry.path,
         skillFile,
-        name: name || entry.name,
-        description: description || ""
+        name: frontmatter.name || entry.name,
+        description: frontmatter.description || "",
+        license: frontmatter.license,
+        compatibility: frontmatter.compatibility,
+        metadata: frontmatter.metadata,
+        disableModelInvocation: frontmatter.disableModelInvocation,
+        userInvocable: frontmatter.userInvocable,
+        subtask: frontmatter.subtask,
+        agent: frontmatter.agent,
+        model: frontmatter.model,
+        argumentHint: frontmatter.argumentHint,
+        allowedTools: frontmatter.allowedTools
       });
     }
   }
   return skills;
 }
-function formatSkillsXml(skills) {
-  if (skills.length === 0)
-    return "";
-  const skillsXml = skills.map((skill) => {
-    const lines = [
-      "  <skill>",
-      `    <name>systematic:${skill.name}</name>`,
-      `    <description>${skill.description}</description>`
-    ];
-    lines.push("  </skill>");
-    return lines.join(`
-`);
-  }).join(`
-`);
-  return `<available_skills>
-${skillsXml}
-</available_skills>`;
-}
 
-export { stripFrontmatter, loadConfig, getConfigPaths, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, convertContent, convertFileWithCache, findSkillsInDir, formatSkillsXml };
+export { parseFrontmatter, loadConfig, getConfigPaths, findAgentsInDir, extractAgentFrontmatter, findCommandsInDir, extractCommandFrontmatter, convertContent, convertFileWithCache, findSkillsInDir };

package/dist/index.js

@@ -6,10 +6,9 @@ import {
   findAgentsInDir,
   findCommandsInDir,
   findSkillsInDir,
-  formatSkillsXml,
   loadConfig,
-  stripFrontmatter
-} from "./index-kjhs9jeg.js";
+  parseFrontmatter
+} from "./index-yxbcy3s7.js";
 
 // src/index.ts
 import fs2 from "fs";
@@ -54,7 +53,8 @@ function getBootstrapContent(config, deps) {
   if (!fs.existsSync(usingSystematicPath))
     return null;
   const fullContent = fs.readFileSync(usingSystematicPath, "utf8");
-  const content = stripFrontmatter(fullContent);
+  const { body } = parseFrontmatter(fullContent);
+  const content = body.trim();
   const toolMapping = getToolMappingTemplate(bundledSkillsDir);
   return `<SYSTEMATIC_WORKFLOWS>
 You have access to structured engineering workflows via the systematic plugin.
@@ -106,7 +106,7 @@ function loadSkill(skillInfo) {
     const converted = convertFileWithCache(skillInfo.skillFile, "skill", {
       source: "bundled"
     });
-    const body = stripFrontmatter(converted);
+    const { body } = parseFrontmatter(converted);
     const wrappedTemplate = wrapSkillTemplate(skillInfo.skillFile, body);
     return {
       name: skillInfo.name,
@@ -114,7 +114,13 @@ function loadSkill(skillInfo) {
       description: formatSkillDescription(skillInfo.description, skillInfo.name),
       path: skillInfo.path,
       skillFile: skillInfo.skillFile,
-      wrappedTemplate
+      wrappedTemplate,
+      disableModelInvocation: skillInfo.disableModelInvocation,
+      userInvocable: skillInfo.userInvocable,
+      subtask: skillInfo.subtask,
+      agent: skillInfo.agent,
+      model: skillInfo.model,
+      argumentHint: skillInfo.argumentHint
     };
   } catch {
     return null;
@@ -128,11 +134,42 @@ function loadAgentAsConfig(agentInfo) {
       source: "bundled",
       agentMode: "subagent"
     });
-    const { description, prompt } = extractAgentFrontmatter(converted);
-    return {
+    const {
+      description,
+      prompt,
+      model,
+      temperature,
+      top_p,
+      tools,
+      disable,
+      mode,
+      color,
+      maxSteps,
+      permission
+    } = extractAgentFrontmatter(converted);
+    const config = {
       description: description || `${agentInfo.name} agent`,
-      prompt: prompt || stripFrontmatter(converted)
+      prompt
     };
+    if (model !== undefined)
+      config.model = model;
+    if (temperature !== undefined)
+      config.temperature = temperature;
+    if (top_p !== undefined)
+      config.top_p = top_p;
+    if (tools !== undefined)
+      config.tools = tools;
+    if (disable !== undefined)
+      config.disable = disable;
+    if (mode !== undefined)
+      config.mode = mode;
+    if (color !== undefined)
+      config.color = color;
+    if (maxSteps !== undefined)
+      config.maxSteps = maxSteps;
+    if (permission !== undefined)
+      config.permission = permission;
+    return config;
   } catch {
     return null;
   }
@@ -142,21 +179,36 @@ function loadCommandAsConfig(commandInfo) {
     const converted = convertFileWithCache(commandInfo.file, "command", {
       source: "bundled"
     });
-    const { name, description } = extractCommandFrontmatter(converted);
+    const { name, description, agent, model, subtask } = extractCommandFrontmatter(converted);
+    const { body } = parseFrontmatter(converted);
     const cleanName = commandInfo.name.replace(/^\//, "");
-    return {
-      template: stripFrontmatter(converted),
+    const config = {
+      template: body.trim(),
       description: description || `${name || cleanName} command`
     };
+    if (agent !== undefined)
+      config.agent = agent;
+    if (model !== undefined)
+      config.model = model;
+    if (subtask !== undefined)
+      config.subtask = subtask;
+    return config;
   } catch {
     return null;
   }
 }
 function loadSkillAsCommand(loaded) {
-  return {
+  const config = {
     template: loaded.wrappedTemplate,
     description: loaded.description
   };
+  if (loaded.agent !== undefined)
+    config.agent = loaded.agent;
+  if (loaded.model !== undefined)
+    config.model = loaded.model;
+  if (loaded.subtask !== undefined)
+    config.subtask = loaded.subtask;
+  return config;
 }
 function collectAgents(dir, disabledAgents) {
   const agents = {};
@@ -193,6 +245,8 @@ function collectSkillsAsCommands(dir, disabledSkills) {
       continue;
     const loaded = loadSkill(skillInfo);
     if (loaded) {
+      if (loaded.userInvocable === false)
+        continue;
       commands[loaded.prefixedName] = loadSkillAsCommand(loaded);
     }
   }
@@ -222,13 +276,27 @@ function createConfigHandler(deps) {
 // src/lib/skill-tool.ts
 import path3 from "path";
 import { tool } from "@opencode-ai/plugin/tool";
+function formatSkillsXml(skills) {
+  if (skills.length === 0)
+    return "";
+  const skillLines = skills.flatMap((skill) => [
+    "  <skill>",
+    `    <name>systematic:${skill.name}</name>`,
+    `    <description>${skill.description}</description>`,
+    "  </skill>"
+  ]);
+  return ["<available_skills>", ...skillLines, "</available_skills>"].join(" ");
+}
 function createSkillTool(options) {
   const { bundledSkillsDir, disabledSkills } = options;
   const getSystematicSkills = () => {
-    return findSkillsInDir(bundledSkillsDir).filter((s) => !disabledSkills.includes(s.name)).map((skillInfo) => loadSkill(skillInfo)).filter((s) => s !== null).sort((a, b) => a.name.localeCompare(b.name));
+    return findSkillsInDir(bundledSkillsDir).filter((s) => !disabledSkills.includes(s.name)).map((skillInfo) => loadSkill(skillInfo)).filter((s) => s !== null).filter((s) => s.disableModelInvocation !== true).sort((a, b) => a.name.localeCompare(b.name));
   };
   const buildDescription = () => {
     const skills = getSystematicSkills();
+    if (skills.length === 0) {
+      return "Load a skill to get detailed instructions for a specific task. No skills are currently available.";
+    }
     const skillInfos = skills.map((s) => ({
       name: s.name,
       description: s.description,
@@ -236,15 +304,22 @@ function createSkillTool(options) {
       skillFile: s.skillFile
     }));
     const systematicXml = formatSkillsXml(skillInfos);
-    const baseDescription = `Load a skill to get detailed instructions for a specific task.
-
-Skills provide specialized knowledge and step-by-step guidance.
-Use this when a task matches an available skill's description.`;
-    return `${baseDescription}
-
-${systematicXml}`;
+    return [
+      "Load a skill to get detailed instructions for a specific task.",
+      "Skills provide specialized knowledge and step-by-step guidance.",
+      "Use this when a task matches an available skill's description.",
+      "Only the skills listed here are available:",
+      systematicXml
+    ].join(" ");
+  };
+  const buildParameterHint = () => {
+    const skills = getSystematicSkills();
+    const examples = skills.slice(0, 3).map((s) => `'systematic:${s.name}'`).join(", ");
+    const hint = examples.length > 0 ? ` (e.g., ${examples}, ...)` : "";
+    return `The skill identifier from available_skills${hint}`;
   };
   let cachedDescription = null;
+  let cachedParameterHint = null;
   return tool({
     get description() {
       if (cachedDescription == null) {
@@ -253,24 +328,45 @@ ${systematicXml}`;
       return cachedDescription;
     },
     args: {
-      name: tool.schema.string().describe("The skill identifier from available_skills (e.g., 'systematic:brainstorming')")
+      name: tool.schema.string().describe((() => {
+        if (cachedParameterHint == null) {
+          cachedParameterHint = buildParameterHint();
+        }
+        return cachedParameterHint;
+      })())
     },
-    async execute(args) {
+    async execute(args, context) {
       const requestedName = args.name;
       const normalizedName = requestedName.startsWith("systematic:") ? requestedName.slice("systematic:".length) : requestedName;
       const skills = getSystematicSkills();
       const matchedSkill = skills.find((s) => s.name === normalizedName);
-      if (matchedSkill) {
-        const body = extractSkillBody(matchedSkill.wrappedTemplate);
-        const dir = path3.dirname(matchedSkill.skillFile);
-        return `## Skill: ${matchedSkill.prefixedName}
-
-**Base directory**: ${dir}
-
-${body}`;
+      if (!matchedSkill) {
+        const availableSystematic = skills.map((s) => s.prefixedName);
+        throw new Error(`Skill "${requestedName}" not found. Available systematic skills: ${availableSystematic.join(", ")}`);
       }
-      const availableSystematic = skills.map((s) => s.prefixedName);
-      throw new Error(`Skill "${requestedName}" not found. Available systematic skills: ${availableSystematic.join(", ")}`);
+      const body = extractSkillBody(matchedSkill.wrappedTemplate);
+      const dir = path3.dirname(matchedSkill.skillFile);
+      await context.ask({
+        permission: "skill",
+        patterns: [matchedSkill.prefixedName],
+        always: [matchedSkill.prefixedName],
+        metadata: {}
+      });
+      context.metadata({
+        title: `Loaded skill: ${matchedSkill.prefixedName}`,
+        metadata: {
+          name: matchedSkill.prefixedName,
+          dir
+        }
+      });
+      return [
+        `## Skill: ${matchedSkill.prefixedName}`,
+        "",
+        `**Base directory**: ${dir}`,
+        "",
+        body.trim()
+      ].join(`
+`);
     }
   });
 }

package/dist/lib/agents.d.ts

@@ -1,7 +1,29 @@
+import { type PermissionConfig } from './validation.js';
 export interface AgentFrontmatter {
+    /** Name of the agent */
     name: string;
+    /** Description of the agent's purpose */
     description: string;
+    /** The system prompt for the agent */
     prompt: string;
+    /** Model to use (provider/model format) */
+    model?: string;
+    /** Temperature for generation */
+    temperature?: number;
+    /** Top-p sampling */
+    top_p?: number;
+    /** Tool whitelist/blacklist */
+    tools?: Record<string, boolean>;
+    /** Disable this agent */
+    disable?: boolean;
+    /** Agent mode */
+    mode?: 'subagent' | 'primary' | 'all';
+    /** Hex color code */
+    color?: string;
+    /** Max agentic iterations */
+    maxSteps?: number;
+    /** Permission settings */
+    permission?: PermissionConfig;
 }
 export interface AgentInfo {
     name: string;

package/dist/lib/commands.d.ts

@@ -2,6 +2,12 @@ export interface CommandFrontmatter {
     name: string;
     description: string;
     argumentHint: string;
+    /** Agent ID to use for this command */
+    agent?: string;
+    /** Model override for this command */
+    model?: string;
+    /** Whether this command should run as a subtask */
+    subtask?: boolean;
 }
 export interface CommandInfo {
     name: string;

package/dist/lib/converter.d.ts

@@ -1,6 +1,6 @@
+import { type AgentMode } from './validation.js';
 export type ContentType = 'skill' | 'agent' | 'command';
 export type SourceType = 'bundled' | 'external';
-export type AgentMode = 'primary' | 'subagent';
 export interface ConvertOptions {
     source?: SourceType;
     agentMode?: AgentMode;

package/dist/lib/frontmatter.d.ts

@@ -15,4 +15,8 @@ export interface FrontmatterResult<T = Record<string, unknown>> {
  */
 export declare function parseFrontmatter<T = Record<string, unknown>>(content: string): FrontmatterResult<T>;
 export declare function formatFrontmatter(data: Record<string, unknown>): string;
+/**
+ * Removes YAML frontmatter from content and returns the body.
+ * Convenience wrapper around parseFrontmatter.
+ */
 export declare function stripFrontmatter(content: string): string;

package/dist/lib/skill-loader.d.ts

@@ -6,6 +6,12 @@ export interface LoadedSkill {
     path: string;
     skillFile: string;
     wrappedTemplate: string;
+    disableModelInvocation?: boolean;
+    userInvocable?: boolean;
+    subtask?: boolean;
+    agent?: string;
+    model?: string;
+    argumentHint?: string;
 }
 export declare function formatSkillCommandName(name: string): string;
 export declare function formatSkillDescription(description: string, fallbackName: string): string;

package/dist/lib/skill-tool.d.ts

@@ -1,6 +1,12 @@
 import type { ToolDefinition } from '@opencode-ai/plugin';
+import { type SkillInfo } from './skills.js';
 export interface SkillToolOptions {
     bundledSkillsDir: string;
     disabledSkills: string[];
 }
+/**
+ * Formats skills as XML for tool description.
+ * Uses indented format matching OpenCode's native skill tool.
+ */
+export declare function formatSkillsXml(skills: SkillInfo[]): string;
 export declare function createSkillTool(options: SkillToolOptions): ToolDefinition;

package/dist/lib/skills.d.ts

@@ -1,13 +1,32 @@
 export interface SkillFrontmatter {
     name: string;
     description: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    disableModelInvocation?: boolean;
+    userInvocable?: boolean;
+    subtask?: boolean;
+    agent?: string;
+    model?: string;
+    argumentHint?: string;
+    allowedTools?: string;
 }
 export interface SkillInfo {
     path: string;
     skillFile: string;
     name: string;
     description: string;
+    license?: string;
+    compatibility?: string;
+    metadata?: Record<string, string>;
+    disableModelInvocation?: boolean;
+    userInvocable?: boolean;
+    subtask?: boolean;
+    agent?: string;
+    model?: string;
+    argumentHint?: string;
+    allowedTools?: string;
 }
 export declare function extractFrontmatter(filePath: string): SkillFrontmatter;
 export declare function findSkillsInDir(dir: string, maxDepth?: number): SkillInfo[];
-export declare function formatSkillsXml(skills: SkillInfo[]): string;

package/dist/lib/validation.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared type guards and validation utilities for agent/skill/command frontmatter.
+ */
+export type AgentMode = 'subagent' | 'primary' | 'all';
+export type PermissionSetting = 'ask' | 'allow' | 'deny';
+export interface PermissionConfig {
+    edit?: PermissionSetting;
+    bash?: PermissionSetting | Record<string, PermissionSetting>;
+    webfetch?: PermissionSetting;
+    doom_loop?: PermissionSetting;
+    external_directory?: PermissionSetting;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isPermissionSetting(value: unknown): value is PermissionSetting;
+export declare function isToolsMap(value: unknown): value is Record<string, boolean>;
+export declare function isAgentMode(value: unknown): value is AgentMode;
+export declare function normalizePermission(value: unknown): PermissionConfig | undefined;
+/**
+ * Shared frontmatter extraction helpers.
+ * Centralized to ensure consistent behavior across agents, commands, and skills.
+ */
+export declare function extractString(data: Record<string, unknown>, key: string, fallback?: string): string;
+export declare function extractNonEmptyString(data: Record<string, unknown>, key: string): string | undefined;
+export declare function extractNumber(data: Record<string, unknown>, key: string): number | undefined;
+export declare function extractBoolean(data: Record<string, unknown>, key: string): boolean | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fro.bot/systematic",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",