@omnidev-ai/core 0.1.0

package/src/capability/subagents.test.ts

@@ -0,0 +1,478 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadSubagents } from "./subagents";
+
+describe("loadSubagents", () => {
+	const testDir = join(process.cwd(), "test-subagents-temp");
+	const capabilityPath = join(testDir, "test-capability");
+
+	beforeEach(() => {
+		mkdirSync(capabilityPath, { recursive: true });
+	});
+
+	afterEach(() => {
+		if (testDir) {
+			rmSync(testDir, { recursive: true, force: true });
+		}
+	});
+
+	test("returns empty array when subagents directory does not exist", async () => {
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+		expect(subagents).toEqual([]);
+	});
+
+	test("returns empty array when subagents directory is empty", async () => {
+		mkdirSync(join(capabilityPath, "subagents"), { recursive: true });
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+		expect(subagents).toEqual([]);
+	});
+
+	test("loads single subagent with valid frontmatter and system prompt", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "test-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: test-subagent
+description: A test subagent
+---
+
+You are a test subagent.
+
+## Instructions
+
+Do testing things.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]).toEqual({
+			name: "test-subagent",
+			description: "A test subagent",
+			systemPrompt: "You are a test subagent.\n\n## Instructions\n\nDo testing things.",
+			capabilityId: "test-cap",
+		});
+	});
+
+	test("loads subagent with tools field", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "tools-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: tools-subagent
+description: Subagent with tools
+tools: Read, Glob, Grep
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.tools).toEqual(["Read", "Glob", "Grep"]);
+	});
+
+	test("loads subagent with disallowedTools field", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "disallowed-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: disallowed-subagent
+description: Subagent with disallowed tools
+disallowedTools: Write, Edit
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.disallowedTools).toEqual(["Write", "Edit"]);
+	});
+
+	test("loads subagent with model field", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "model-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: model-subagent
+description: Subagent with model
+model: haiku
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.model).toBe("haiku");
+	});
+
+	test("loads subagent with permissionMode field", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "permission-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: permission-subagent
+description: Subagent with permission mode
+permissionMode: dontAsk
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.permissionMode).toBe("dontAsk");
+	});
+
+	test("loads subagent with skills field", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "skills-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: skills-subagent
+description: Subagent with skills
+skills: prd, ralph
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.skills).toEqual(["prd", "ralph"]);
+	});
+
+	test("loads subagent with all optional fields", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "full-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: full-subagent
+description: Subagent with all fields
+tools: Read, Glob, Grep, Bash
+disallowedTools: Write, Edit
+model: sonnet
+permissionMode: acceptEdits
+skills: prd, ralph, mcp-builder
+---
+
+You are a fully configured subagent.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.name).toBe("full-subagent");
+		expect(subagents[0]?.description).toBe("Subagent with all fields");
+		expect(subagents[0]?.tools).toEqual(["Read", "Glob", "Grep", "Bash"]);
+		expect(subagents[0]?.disallowedTools).toEqual(["Write", "Edit"]);
+		expect(subagents[0]?.model).toBe("sonnet");
+		expect(subagents[0]?.permissionMode).toBe("acceptEdits");
+		expect(subagents[0]?.skills).toEqual(["prd", "ralph", "mcp-builder"]);
+		expect(subagents[0]?.systemPrompt).toBe("You are a fully configured subagent.");
+	});
+
+	test("loads multiple subagents from different directories", async () => {
+		const subagent1Dir = join(capabilityPath, "subagents", "subagent-1");
+		const subagent2Dir = join(capabilityPath, "subagents", "subagent-2");
+		mkdirSync(subagent1Dir, { recursive: true });
+		mkdirSync(subagent2Dir, { recursive: true });
+
+		writeFileSync(
+			join(subagent1Dir, "SUBAGENT.md"),
+			`---
+name: subagent-1
+description: First subagent
+---
+
+First subagent prompt.`,
+		);
+
+		writeFileSync(
+			join(subagent2Dir, "SUBAGENT.md"),
+			`---
+name: subagent-2
+description: Second subagent
+---
+
+Second subagent prompt.`,
+		);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(2);
+		expect(subagents[0]?.name).toBe("subagent-1");
+		expect(subagents[1]?.name).toBe("subagent-2");
+	});
+
+	test("skips subagent directories without SUBAGENT.md file", async () => {
+		const validDir = join(capabilityPath, "subagents", "valid-subagent");
+		const invalidDir = join(capabilityPath, "subagents", "no-file");
+		mkdirSync(validDir, { recursive: true });
+		mkdirSync(invalidDir, { recursive: true });
+
+		writeFileSync(
+			join(validDir, "SUBAGENT.md"),
+			`---
+name: valid-subagent
+description: Valid subagent
+---
+
+Valid prompt.`,
+		);
+
+		// No SUBAGENT.md in invalidDir
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.name).toBe("valid-subagent");
+	});
+
+	test("handles YAML frontmatter with quoted values", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "quoted-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: "quoted-subagent"
+description: "A subagent with quoted values"
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.name).toBe("quoted-subagent");
+		expect(subagents[0]?.description).toBe("A subagent with quoted values");
+	});
+
+	test("trims whitespace from system prompt", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "whitespace-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: whitespace-subagent
+description: Test whitespace trimming
+---
+
+
+System prompt with leading/trailing whitespace.
+
+	`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.systemPrompt).toBe("System prompt with leading/trailing whitespace.");
+	});
+
+	test("throws error when SUBAGENT.md has no frontmatter", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "no-frontmatter");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `# Just Instructions
+
+No frontmatter here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		await expect(loadSubagents(capabilityPath, "test-cap")).rejects.toThrow(
+			/Invalid SUBAGENT\.md format.*missing YAML frontmatter/,
+		);
+	});
+
+	test("throws error when SUBAGENT.md is missing name field", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "missing-name");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+description: Missing name field
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		await expect(loadSubagents(capabilityPath, "test-cap")).rejects.toThrow(
+			/name and description required/,
+		);
+	});
+
+	test("throws error when SUBAGENT.md is missing description field", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "missing-description");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: missing-description
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		await expect(loadSubagents(capabilityPath, "test-cap")).rejects.toThrow(
+			/name and description required/,
+		);
+	});
+
+	test("handles empty system prompt after frontmatter", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "empty-prompt");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: empty-prompt
+description: Subagent with no prompt
+---
+`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.systemPrompt).toBe("");
+	});
+
+	test("preserves markdown formatting in system prompt", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "markdown-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: markdown-subagent
+description: Subagent with markdown
+---
+
+# Header
+
+- List item 1
+- List item 2
+
+**Bold text** and *italic text*.
+
+\`\`\`typescript
+const code = "example";
+\`\`\``;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.systemPrompt).toContain("# Header");
+		expect(subagents[0]?.systemPrompt).toContain("- List item 1");
+		expect(subagents[0]?.systemPrompt).toContain("**Bold text**");
+		expect(subagents[0]?.systemPrompt).toContain("```typescript");
+	});
+
+	test("ignores non-directory entries in subagents folder", async () => {
+		const subagentsDir = join(capabilityPath, "subagents");
+		const validDir = join(subagentsDir, "valid-subagent");
+		mkdirSync(validDir, { recursive: true });
+
+		writeFileSync(
+			join(validDir, "SUBAGENT.md"),
+			`---
+name: valid-subagent
+description: Valid subagent
+---
+
+Valid prompt.`,
+		);
+
+		// Create a file directly in subagents/ directory (should be ignored)
+		writeFileSync(join(subagentsDir, "README.md"), "This should be ignored");
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.name).toBe("valid-subagent");
+	});
+
+	test("associates subagents with correct capability ID", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "test-subagent");
+		mkdirSync(subagentDir, { recursive: true });
+
+		writeFileSync(
+			join(subagentDir, "SUBAGENT.md"),
+			`---
+name: test-subagent
+description: Test subagent
+---
+
+System prompt.`,
+		);
+
+		const subagents = await loadSubagents(capabilityPath, "my-capability");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.capabilityId).toBe("my-capability");
+	});
+
+	test("model field accepts inherit value", async () => {
+		const subagentDir = join(capabilityPath, "subagents", "inherit-model");
+		mkdirSync(subagentDir, { recursive: true });
+
+		const subagentContent = `---
+name: inherit-model
+description: Subagent with inherit model
+model: inherit
+---
+
+System prompt here.`;
+
+		writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+		const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+		expect(subagents).toHaveLength(1);
+		expect(subagents[0]?.model).toBe("inherit");
+	});
+
+	test("permissionMode field accepts all valid values", async () => {
+		const modes = ["default", "acceptEdits", "dontAsk", "bypassPermissions", "plan"] as const;
+
+		for (const mode of modes) {
+			// Clean up from previous iteration
+			const subagentsDir = join(capabilityPath, "subagents");
+			rmSync(subagentsDir, { recursive: true, force: true });
+
+			const subagentDir = join(capabilityPath, "subagents", `${mode}-subagent`);
+			mkdirSync(subagentDir, { recursive: true });
+
+			const subagentContent = `---
+name: ${mode}-subagent
+description: Subagent with ${mode} permission mode
+permissionMode: ${mode}
+---
+
+System prompt here.`;
+
+			writeFileSync(join(subagentDir, "SUBAGENT.md"), subagentContent);
+
+			const subagents = await loadSubagents(capabilityPath, "test-cap");
+
+			expect(subagents).toHaveLength(1);
+			expect(subagents[0]?.permissionMode).toBe(mode);
+		}
+	});
+});

package/src/capability/subagents.ts

@@ -0,0 +1,103 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import type { Subagent, SubagentHooks, SubagentModel, SubagentPermissionMode } from "../types";
+import { parseFrontmatterWithMarkdown } from "./yaml-parser";
+
+interface SubagentFrontmatter {
+	name: string;
+	description: string;
+	tools?: string;
+	disallowedTools?: string;
+	model?: SubagentModel;
+	permissionMode?: SubagentPermissionMode;
+	skills?: string;
+	hooks?: SubagentHooks;
+}
+
+/**
+ * Load subagents from the subagents/ directory of a capability.
+ * Each subagent is a SUBAGENT.md file in its own subdirectory.
+ */
+export async function loadSubagents(
+	capabilityPath: string,
+	capabilityId: string,
+): Promise<Subagent[]> {
+	const subagentsDir = join(capabilityPath, "subagents");
+
+	if (!existsSync(subagentsDir)) {
+		return [];
+	}
+
+	const subagents: Subagent[] = [];
+	const entries = readdirSync(subagentsDir, { withFileTypes: true });
+
+	for (const entry of entries) {
+		if (entry.isDirectory()) {
+			const subagentPath = join(subagentsDir, entry.name, "SUBAGENT.md");
+			if (existsSync(subagentPath)) {
+				const subagent = await parseSubagentFile(subagentPath, capabilityId);
+				subagents.push(subagent);
+			}
+		}
+	}
+
+	return subagents;
+}
+
+async function parseSubagentFile(filePath: string, capabilityId: string): Promise<Subagent> {
+	const content = await Bun.file(filePath).text();
+
+	const parsed = parseFrontmatterWithMarkdown<SubagentFrontmatter>(content);
+
+	if (!parsed) {
+		throw new Error(`Invalid SUBAGENT.md format at ${filePath}: missing YAML frontmatter`);
+	}
+
+	const frontmatter = parsed.frontmatter;
+	const systemPrompt = parsed.markdown;
+
+	if (!frontmatter.name || !frontmatter.description) {
+		throw new Error(`Invalid SUBAGENT.md at ${filePath}: name and description required`);
+	}
+
+	const result: Subagent = {
+		name: frontmatter.name,
+		description: frontmatter.description,
+		systemPrompt: systemPrompt.trim(),
+		capabilityId,
+	};
+
+	// Add optional fields if present
+	if (frontmatter.tools) {
+		result.tools = parseCommaSeparatedList(frontmatter.tools);
+	}
+
+	if (frontmatter.disallowedTools) {
+		result.disallowedTools = parseCommaSeparatedList(frontmatter.disallowedTools);
+	}
+
+	if (frontmatter.model) {
+		result.model = frontmatter.model;
+	}
+
+	if (frontmatter.permissionMode) {
+		result.permissionMode = frontmatter.permissionMode;
+	}
+
+	if (frontmatter.skills) {
+		result.skills = parseCommaSeparatedList(frontmatter.skills);
+	}
+
+	if (frontmatter.hooks) {
+		result.hooks = frontmatter.hooks;
+	}
+
+	return result;
+}
+
+function parseCommaSeparatedList(value: string): string[] {
+	return value
+		.split(",")
+		.map((item) => item.trim())
+		.filter(Boolean);
+}

package/src/capability/yaml-parser.ts

@@ -0,0 +1,81 @@
+/**
+ * YAML Frontmatter Parser Utility
+ *
+ * Consolidates YAML frontmatter parsing logic that was duplicated across
+ * skills.ts, commands.ts, and subagents.ts.
+ *
+ * This utility provides:
+ * - parseSimpleYamlFrontmatter: Parse key: value pairs from YAML
+ * - parseFrontmatterWithMarkdown: Extract frontmatter + markdown content
+ */
+
+/**
+ * Parse simple YAML key: value pairs
+ * Supports basic key: value syntax (not full YAML spec)
+ * Handles quoted and unquoted values
+ *
+ * @param yaml - YAML content string to parse
+ * @returns Record of key-value pairs
+ */
+export function parseSimpleYamlFrontmatter<T>(yaml: string): T {
+	const result: Record<string, string> = {};
+
+	for (const line of yaml.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) {
+			continue;
+		}
+
+		// Support: key: value and key: "quoted value"
+		const colonIndex = trimmed.indexOf(":");
+		if (colonIndex === -1) {
+			continue;
+		}
+
+		const rawKey = trimmed.slice(0, colonIndex).trim();
+		let value = trimmed.slice(colonIndex + 1).trim();
+
+		// Remove quotes if present (double or single)
+		if (
+			(value.startsWith('"') && value.endsWith('"')) ||
+			(value.startsWith("'") && value.endsWith("'"))
+		) {
+			value = value.slice(1, -1);
+		}
+
+		// Convert kebab-case to camelCase
+		const key = rawKey.replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
+
+		result[key] = value;
+	}
+
+	return result as unknown as T;
+}
+
+/**
+ * Parse content with YAML frontmatter separated from markdown
+ * Expected format:
+ * ```
+ * ---
+ * key: value
+ * ---
+ * Markdown content here
+ * ```
+ *
+ * @param content - Full content with frontmatter and markdown
+ * @returns Object with frontmatter (parsed) and markdown (remaining) or null if no frontmatter
+ */
+export function parseFrontmatterWithMarkdown<T>(
+	content: string,
+): { frontmatter: T; markdown: string } | null {
+	const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/s);
+
+	if (!match?.[1] || match[2] === undefined) {
+		return null;
+	}
+
+	const frontmatter = parseSimpleYamlFrontmatter<T>(match[1]);
+	const markdown = match[2];
+
+	return { frontmatter, markdown };
+}

package/src/config/AGENTS.md

@@ -0,0 +1,46 @@
+# CONFIGURATION SUBSYSTEM
+
+**Generated:** 2026-01-12T10:36:46
+**Commit:** (not specified)
+**Branch:** (not specified)
+
+## OVERVIEW
+Configuration loading and parsing system using TOML format with profile-based capability management.
+
+## WHERE TO LOOK
+| Task | Location | Notes |
+|------|----------|-------|
+| Config merge logic | loader.ts | Merges config.toml + config.local.toml |
+| Environment loading | env.ts | Loads .omni/.env, validates declarations |
+| TOML parsing | parser.ts | Uses smol-toml, validates capability.toml |
+| Provider selection | provider.ts | Loads provider.toml, parses CLI flags |
+| Profile management | profiles.ts | Active profile tracking, resolves capabilities |
+| Capability enable/disable | capabilities.ts | Updates profiles + gitignore patterns |
+
+## CONVENTIONS
+
+**Config File Locations:**
+- `.omni/config.toml` - main config (project name, default profile, profiles)
+- `.omni/config.local.toml` - local overrides (gitignored)
+- `.omni/provider.toml` - provider selection (claude/codex/both)
+- `.omni/.env` - secrets, always gitignored
+
+**Profile-Based Capability Management:**
+- Profiles define capability sets in `[profiles.name].capabilities`
+- `active_profile` in config.toml selects current profile
+- `always_enabled_capabilities` list merged with profile capabilities
+- Use `enableCapability()` / `disableCapability()` to update active profile
+
+**Environment Variable Handling:**
+- capability.toml `[env]` section declares requirements
+- `required = true` → must be present or default
+- `secret = true` → masked in logs/error messages
+- `default = "value"` → optional with fallback
+
+## ANTI-PATTERNS (THIS SUBSYSTEM)
+
+- **NEVER** edit config.toml directly for capability changes - use enableCapability()/disableCapability()
+- **NEVER** commit .omni/.env or config.local.toml - both gitignored
+- **NEVER** parse TOML manually - use parseOmniConfig() / parseCapabilityConfig()
+- **NEVER** ignore validateEnv() errors - required env vars block capability load
+- **NEVER** assume process.env is complete - merge with .omni/.env via loadEnvironment()