@fro.bot/systematic 1.5.0 → 1.6.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-95qwq9ph.js";
 
 // src/cli.ts
 import fs from "fs";

package/dist/{index-kjhs9jeg.js → index-95qwq9ph.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") {
@@ -412,4 +549,4 @@ ${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, formatSkillsXml };

package/dist/index.js

@@ -8,8 +8,8 @@ import {
   findSkillsInDir,
   formatSkillsXml,
   loadConfig,
-  stripFrontmatter
-} from "./index-kjhs9jeg.js";
+  parseFrontmatter
+} from "./index-95qwq9ph.js";
 
 // src/index.ts
 import fs2 from "fs";
@@ -54,7 +54,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 +107,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,
@@ -128,11 +129,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,12 +174,20 @@ 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;
   }

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/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.6.0",
   "description": "Structured engineering workflows for OpenCode",
   "type": "module",
   "main": "./dist/index.js",