opencodekit 0.20.2 → 0.20.4

package/dist/template/.opencode/plugin/lib/memory-tools.ts

@@ -1,7 +1,8 @@
 /**
  * Memory Plugin — Core Tools
  *
- * observation, memory-search, memory-get, memory-read, memory-update, memory-timeline
+ * observation, memory-search, memory-get, memory-read, memory-update, memory-timeline,
+ * memory-graph-add, memory-graph-query, memory-graph-invalidate, memory-compact
  *
  * Uses factory pattern: createCoreTools(deps) returns tool definitions
  * that can be spread into plugin's tool:{} export.
@@ -11,17 +12,23 @@ import { readdir } from "node:fs/promises";
 import path from "node:path";
 import { tool } from "@opencode-ai/plugin/tool";
 import {
+	addEntityTriple,
 	type ConfidenceLevel,
 	checkFTS5Available,
+	getMemoryDB,
 	getMemoryFile,
 	getObservationsByIds,
 	getTimelineAroundObservation,
+	invalidateTriple,
 	type ObservationSource,
 	type ObservationType,
+	queryEntity,
 	searchDistillationsFTS,
 	searchObservationsFTS,
 	storeObservation,
 	upsertMemoryFile,
+	type HallType,
+	VALID_HALLS,
 } from "./memory-db.js";
 import {
 	autoDetectFiles,
@@ -31,6 +38,8 @@ import {
 	TYPE_ICONS,
 	VALID_TYPES,
 } from "./memory-helpers.js";
+import { validateObservation } from "./validate.js";
+import { compactObservations } from "./compact.js";
 
 /**
  * Wrap a memory tool execute function with DB error handling.
@@ -117,6 +126,22 @@ export function createCoreTools(deps: CoreToolDeps) {
 					.string()
 					.optional()
 					.describe("manual, curator, imported"),
+				wing: tool.schema
+					.string()
+					.optional()
+					.describe("Navigation wing (project or person name)"),
+				hall: tool.schema
+					.string()
+					.optional()
+					.describe("Navigation hall: facts, events, discoveries, preferences, advice"),
+				room: tool.schema
+					.string()
+					.optional()
+					.describe("Navigation room (topic name, e.g. auth-migration)"),
+				raw_source: tool.schema
+					.string()
+					.optional()
+					.describe("Verbatim source text to preserve losslessly alongside narrative"),
 			},
 			execute: withDBErrorHandling(async (args) => {
 				const obsType = args.type as ObservationType;
@@ -156,6 +181,37 @@ export function createCoreTools(deps: CoreToolDeps) {
 				}
 
 				const source = (args.source ?? "manual") as ObservationSource;
+				const hall = args.hall as HallType | undefined;
+				if (hall && !VALID_HALLS.includes(hall)) {
+					return `Error: Invalid hall "${args.hall}". Valid: ${VALID_HALLS.join(", ")}`;
+				}
+
+				// Validation gate: check for duplicates, contradictions, low quality
+				const validation = validateObservation({
+					type: obsType,
+					title: args.title,
+					subtitle: args.subtitle,
+					facts,
+					narrative,
+					concepts,
+					files_read: filesRead,
+					files_modified: filesModified,
+					confidence,
+					bead_id: args.bead_id,
+					supersedes,
+					source,
+					wing: args.wing,
+					hall,
+					room: args.room,
+				});
+
+				if (validation.verdict === "reject") {
+					const reasons = validation.issues.map(i => i.message).join("; ");
+					const dupHint = validation.duplicateOf
+						? ` Use \`observation({ supersedes: "${validation.duplicateOf}", ... })\` to update it.`
+						: "";
+					return `Rejected: ${reasons}.${dupHint}`;
+				}
 
 				const id = storeObservation({
 					type: obsType,
@@ -163,6 +219,7 @@ export function createCoreTools(deps: CoreToolDeps) {
 					subtitle: args.subtitle,
 					facts,
 					narrative,
+					raw_source: args.raw_source,
 					concepts,
 					files_read: filesRead,
 					files_modified: filesModified,
@@ -170,9 +227,16 @@ export function createCoreTools(deps: CoreToolDeps) {
 					bead_id: args.bead_id,
 					supersedes,
 					source,
+					wing: args.wing,
+					hall,
+					room: args.room,
 				});
 
-				return `${TYPE_ICONS[obsType] ?? "\uD83D\uDCCC"} Observation #${id} stored [${obsType}] "${args.title}" (confidence: ${confidence}, source: ${source})`;
+				const warnings = validation.issues.length > 0
+					? `\n⚠️ Warnings: ${validation.issues.map(i => i.message).join("; ")}`
+					: "";
+
+				return `${TYPE_ICONS[obsType] ?? "\uD83D\uDCCC"} Observation #${id} stored [${obsType}] "${args.title}" (confidence: ${confidence}, source: ${source})${warnings}`;
 			}),
 		}),
 
@@ -366,5 +430,106 @@ export function createCoreTools(deps: CoreToolDeps) {
 				return lines.join("\n");
 			}),
 		}),
+
+		"memory-graph-add": tool({
+			description: `Add a triple to the entity knowledge graph.\n\nStores a subject-predicate-object relationship with optional temporal bounds and confidence.\nUse for structured facts like "project uses typescript" or "user prefers dark-mode".\n\nExample:\nmemory-graph-add({ subject: "project", predicate: "uses", object: "typescript" })\nmemory-graph-add({ subject: "auth", predicate: "depends-on", object: "jwt", confidence: 0.9, source_observation_id: 42 })`,
+			args: {
+				subject: tool.schema.string().describe("Entity subject"),
+				predicate: tool.schema.string().describe("Relationship type (e.g. uses, depends-on, prefers)"),
+				object: tool.schema.string().describe("Entity object"),
+				valid_from: tool.schema.string().optional().describe("Start date (ISO, default: today)"),
+				valid_to: tool.schema.string().optional().describe("End date (ISO, null = still active)"),
+				confidence: tool.schema.number().optional().describe("Confidence 0.0-1.0 (default: 1.0)"),
+				source_observation_id: tool.schema.number().optional().describe("Link to source observation"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				if (!args.subject?.trim() || !args.predicate?.trim() || !args.object?.trim()) {
+					return "Error: subject, predicate, and object are required.";
+				}
+				const id = addEntityTriple({
+					subject: args.subject,
+					predicate: args.predicate,
+					object: args.object,
+					valid_from: args.valid_from,
+					valid_to: args.valid_to,
+					confidence: args.confidence,
+					source_observation_id: args.source_observation_id,
+				});
+				return `Triple #${id} added: ${args.subject} —[${args.predicate}]→ ${args.object}`;
+			}),
+		}),
+
+		"memory-graph-query": tool({
+			description: `Query the entity knowledge graph.\n\nFind relationships for an entity with optional time and direction filters.\nReturns triples where the entity appears as subject, object, or both.\n\nExample:\nmemory-graph-query({ entity: "typescript" })\nmemory-graph-query({ entity: "auth", direction: "out", active_only: true })\nmemory-graph-query({ entity: "project", as_of: "2025-06-01" })`,
+			args: {
+				entity: tool.schema.string().describe("Entity to query"),
+				direction: tool.schema.string().optional().describe("out (subject), in (object), both (default)"),
+				predicate: tool.schema.string().optional().describe("Filter by predicate"),
+				as_of: tool.schema.string().optional().describe("ISO date for point-in-time query"),
+				active_only: tool.schema.boolean().optional().describe("Only active triples (default: false)"),
+				limit: tool.schema.number().optional().describe("Max results (default: 50)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				if (!args.entity?.trim()) return "Error: entity is required.";
+				const results = queryEntity(args.entity, {
+					direction: args.direction as "out" | "in" | "both" | undefined,
+					predicate: args.predicate,
+					as_of: args.as_of,
+					activeOnly: args.active_only,
+					limit: args.limit,
+				});
+				if (results.length === 0) return `No triples found for entity "${args.entity}".`;
+				const lines: string[] = [
+					`## Entity Graph: ${args.entity} (${results.length} triples)\n`,
+					"| ID | Subject | Predicate | Object | Active | Confidence |",
+					"|---|---|---|---|---|---|",
+				];
+				for (const r of results) {
+					lines.push(`| ${r.id} | ${r.subject} | ${r.predicate} | ${r.object} | ${r.is_active ? "\u2705" : "\u274C"} | ${(r.confidence * 100).toFixed(0)}% |`);
+				}
+				return lines.join("\n");
+			}),
+		}),
+
+		"memory-graph-invalidate": tool({
+			description: `Invalidate (close) entity triples in the knowledge graph.\n\nMarks active triples matching subject+predicate+object as no longer valid by setting valid_to.\nUse when a fact is no longer true (e.g. project stopped using a library).\n\nExample:\nmemory-graph-invalidate({ subject: "project", predicate: "uses", object: "moment.js" })`,
+			args: {
+				subject: tool.schema.string().describe("Entity subject"),
+				predicate: tool.schema.string().describe("Relationship type"),
+				object: tool.schema.string().describe("Entity object"),
+				end_date: tool.schema.string().optional().describe("End date (ISO, default: today)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				if (!args.subject?.trim() || !args.predicate?.trim() || !args.object?.trim()) {
+					return "Error: subject, predicate, and object are required.";
+				}
+				const count = invalidateTriple(args.subject, args.predicate, args.object, args.end_date);
+				return count > 0
+					? `Invalidated ${count} triple(s): ${args.subject} —[${args.predicate}]→ ${args.object}`
+					: `No active triples found matching ${args.subject} —[${args.predicate}]→ ${args.object}.`;
+			}),
+		}),
+
+		"memory-compact": tool({
+			description: `Compact observations into a dense, token-efficient format.\n\nUses AAAK-inspired pipe-separated compression achieving ~3-5x token reduction.\nUseful for injecting memory into prompts with minimal token cost.\n\nExample:\nmemory-compact({})\nmemory-compact({ limit: 20 })`,
+			args: {
+				limit: tool.schema.number().optional().describe("Max observations to compact (default: all)"),
+			},
+			execute: withDBErrorHandling(async (args) => {
+				const db = getMemoryDB();
+				const limitClause = args.limit ? `LIMIT ${Number(args.limit)}` : "";
+				const observations = db.query(
+					`SELECT id, type, title, narrative, concepts, wing, hall, room, confidence, created_at
+					 FROM observations
+					 WHERE superseded_by IS NULL
+					 ORDER BY created_at_epoch DESC ${limitClause}`
+				).all() as { id: number; type: string; title: string; narrative?: string | null; concepts?: string | null; wing?: string | null; hall?: string | null; room?: string | null; confidence?: string | null; created_at?: string | null }[];
+				if (observations.length === 0) return "No observations to compact.";
+				const result = compactObservations(observations);
+				if (!result.compressed) return "No observations to compact.";
+				const ratio = result.compression_ratio > 0 ? ` (${(result.compression_ratio * 100).toFixed(0)}% of original)` : "";
+				return `## Compact Memory (${observations.length} observations, ~${result.token_estimate} tokens${ratio})\n\n${result.compressed}`;
+			}),
+		}),
 	};
 }

package/dist/template/.opencode/plugin/lib/operation-log.ts

@@ -0,0 +1,109 @@
+/**
+ * Memory Operation Log — Append-Only Audit Trail
+ *
+ * Inspired by Karpathy's LLM Wiki log.md:
+ * chronological record of all memory operations for provenance tracking.
+ *
+ * Stored in memory_files as "log" — append-only, never overwritten.
+ */
+
+import { getMemoryFile, upsertMemoryFile } from "./db/maintenance.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type OperationType =
+	| "observation-created"
+	| "observation-superseded"
+	| "observation-validated"
+	| "observation-rejected"
+	| "index-generated"
+	| "lint-run"
+	| "compile-run"
+	| "maintenance-run"
+	| "distillation-created"
+	| "curation-run";
+
+export interface LogEntry {
+	timestamp: string;
+	operation: OperationType;
+	targets: string[];
+	summary: string;
+}
+
+// ============================================================================
+// Log Operations
+// ============================================================================
+
+/**
+ * Append an entry to the operation log.
+ * The log is append-only and stored in memory_files.
+ */
+export function appendOperationLog(entry: Omit<LogEntry, "timestamp">): void {
+	const timestamp = new Date().toISOString().slice(0, 19);
+	const targets = entry.targets.length > 0 ? entry.targets.join(", ") : "-";
+	const line = `[${timestamp}] ${entry.operation} | ${targets} | ${entry.summary}`;
+
+	// Check if log exists
+	const existing = getMemoryFile("log");
+	if (existing) {
+		// Append with newline
+		upsertMemoryFile("log", line, "append");
+	} else {
+		// Create with header
+		const header = [
+			"# Memory Operation Log",
+			"",
+			"> Append-only chronological record of all memory operations.",
+			"> Format: [timestamp] operation | targets | summary",
+			"",
+			"---",
+			"",
+			line,
+		].join("\n");
+		upsertMemoryFile("log", header, "replace");
+	}
+}
+
+/**
+ * Get recent log entries (parsed from the log file).
+ */
+export function getRecentLogEntries(limit = 20): LogEntry[] {
+	const existing = getMemoryFile("log");
+	if (!existing) return [];
+
+	const lines = existing.content
+		.split("\n")
+		.filter((line) => line.startsWith("["))
+		.slice(-limit);
+
+	return lines.map((line) => {
+		const match = line.match(/^\[(.+?)\] (.+?) \| (.+?) \| (.+)$/);
+		if (!match) {
+			return {
+				timestamp: "",
+				operation: "observation-created" as OperationType,
+				targets: [],
+				summary: line,
+			};
+		}
+		return {
+			timestamp: match[1],
+			operation: match[2] as OperationType,
+			targets: match[3].split(",").map((t) => t.trim()),
+			summary: match[4],
+		};
+	});
+}
+
+/**
+ * Get the full log content as a string.
+ */
+export function getLogContent(): string {
+	const existing = getMemoryFile("log");
+	return (
+		existing?.content ??
+		"No operation log found. Run a memory operation to start logging."
+	);
+}

package/dist/template/.opencode/plugin/lib/validate.ts

@@ -0,0 +1,243 @@
+/**
+ * Observation Validation Gate
+ *
+ * Inspired by jumperz's Secondmate Hermes validation:
+ * checks for duplicates and contradictions BEFORE storing an observation.
+ *
+ * Unlike Secondmate's approach (separate LLM model), this uses
+ * FTS5 similarity search + heuristic contradiction detection.
+ *
+ * Returns a validation result that can:
+ * - PASS: store normally
+ * - WARN: store but flag issues
+ * - REJECT: don't store, return reason
+ */
+
+import type { ObservationInput, ObservationRow } from "./db/types.js";
+import { getMemoryDB } from "./memory-db.js";
+import { hasWord } from "./memory-helpers.js";
+import { appendOperationLog } from "./operation-log.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ValidationVerdict = "pass" | "warn" | "reject";
+
+export interface ValidationResult {
+	verdict: ValidationVerdict;
+	issues: ValidationIssue[];
+	/** If a near-duplicate was found, its ID */
+	duplicateOf?: number;
+}
+
+export interface ValidationIssue {
+	type: "duplicate" | "near-duplicate" | "contradiction" | "low-quality";
+	severity: "high" | "medium" | "low";
+	message: string;
+	relatedId?: number;
+}
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validate an observation before storing.
+ * Returns verdict (pass/warn/reject) with issues.
+ */
+export function validateObservation(input: ObservationInput): ValidationResult {
+	const issues: ValidationIssue[] = [];
+
+	// Check 1: Exact title duplicate
+	const exactDup = findExactDuplicate(input);
+	if (exactDup) {
+		// If it's explicitly superseding, that's fine
+		if (input.supersedes === exactDup.id) {
+			// Intentional supersede — pass
+		} else {
+			issues.push({
+				type: "duplicate",
+				severity: "high",
+				message: `Exact duplicate of #${exactDup.id}: "${exactDup.title}"`,
+				relatedId: exactDup.id,
+			});
+
+			appendOperationLog({
+				operation: "observation-duplicate-warning",
+				targets: [`#${exactDup.id}`],
+				summary: `Duplicate warning: "${input.title}" (matches #${exactDup.id})`,
+			});
+
+			return {
+				verdict: "warn",
+				issues,
+				duplicateOf: exactDup.id,
+			};
+		}
+	}
+
+	// Check 2: Near-duplicate via FTS5
+	const nearDup = findNearDuplicate(input);
+	if (nearDup) {
+		issues.push({
+			type: "near-duplicate",
+			severity: "medium",
+			message: `Similar to #${nearDup.id}: "${nearDup.title}" (consider superseding)`,
+			relatedId: nearDup.id,
+		});
+	}
+
+	// Check 3: Contradiction with existing decisions
+	if (input.type === "decision") {
+		const contradiction = findContradiction(input);
+		if (contradiction) {
+			issues.push({
+				type: "contradiction",
+				severity: "medium",
+				message: `May contradict #${contradiction.id}: "${contradiction.title}"`,
+				relatedId: contradiction.id,
+			});
+		}
+	}
+
+	// Check 4: Low quality (no narrative, no concepts)
+	if (!input.narrative && !input.concepts) {
+		issues.push({
+			type: "low-quality",
+			severity: "low",
+			message:
+				"Observation has no narrative and no concepts — low knowledge value",
+		});
+	}
+
+	// Determine verdict
+	const hasHigh = issues.some((i) => i.severity === "high");
+	const verdict: ValidationVerdict = hasHigh
+		? "reject"
+		: issues.length > 0
+			? "warn"
+			: "pass";
+
+	if (verdict === "pass" || verdict === "warn") {
+		appendOperationLog({
+			operation: "observation-validated",
+			targets: [input.title],
+			summary: `Validated [${input.type}] "${input.title}" — ${verdict}${issues.length > 0 ? ` (${issues.length} issues)` : ""}`,
+		});
+	}
+
+	return { verdict, issues };
+}
+
+// ============================================================================
+// Internal Checks
+// ============================================================================
+
+/**
+ * Check for exact title match (same type, active).
+ */
+function findExactDuplicate(input: ObservationInput): ObservationRow | null {
+	const db = getMemoryDB();
+	return db
+		.query(
+			`SELECT * FROM observations
+			 WHERE type = ? AND LOWER(title) = LOWER(?) AND superseded_by IS NULL
+			 LIMIT 1`,
+		)
+		.get(input.type, input.title) as ObservationRow | null;
+}
+
+/**
+ * Check for near-duplicate via FTS5 title search.
+ */
+function findNearDuplicate(input: ObservationInput): ObservationRow | null {
+	const db = getMemoryDB();
+
+	// Build FTS query from title words
+	// Strip FTS5 special operators and characters to prevent query syntax errors
+	const FTS5_OPERATORS = /\b(AND|OR|NOT|NEAR)\b/gi;
+	const words = input.title
+		.replace(FTS5_OPERATORS, "")
+		.replace(/['"*^+(){}]/g, "")
+		.split(/\s+/)
+		.filter((w) => w.length > 2)
+		.map((w) => `"${w}"*`)
+		.join(" AND ");
+
+	if (!words) return null;
+
+	try {
+		const result = db
+			.query(
+				`SELECT o.* FROM observations o
+				 JOIN observations_fts fts ON fts.rowid = o.id
+				 WHERE observations_fts MATCH ?
+				   AND o.type = ?
+				   AND o.superseded_by IS NULL
+				   AND o.id != COALESCE(?, -1)
+				 ORDER BY bm25(observations_fts) LIMIT 1`,
+			)
+			.get(
+				words,
+				input.type,
+				input.supersedes ?? null,
+			) as ObservationRow | null;
+
+		return result;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * Check for contradictions with existing decisions.
+ */
+function findContradiction(input: ObservationInput): ObservationRow | null {
+	if (!input.concepts || input.concepts.length === 0) return null;
+
+	const db = getMemoryDB();
+
+	// Search for decisions with overlapping concepts
+	const conceptQuery = input.concepts.map((c) => `"${c}"*`).join(" OR ");
+
+	try {
+		const candidates = db
+			.query(
+				`SELECT o.* FROM observations o
+				 JOIN observations_fts fts ON fts.rowid = o.id
+				 WHERE observations_fts MATCH ?
+				   AND o.type = 'decision'
+				   AND o.superseded_by IS NULL
+				 ORDER BY bm25(observations_fts) LIMIT 5`,
+			)
+			.all(conceptQuery) as ObservationRow[];
+
+		// Check for opposing signals
+		const inputText = `${input.title} ${input.narrative ?? ""}`.toLowerCase();
+		const contradictionPairs = [
+			["use", "don't use"],
+			["enable", "disable"],
+			["add", "remove"],
+			["prefer", "avoid"],
+			["always", "never"],
+		];
+
+		for (const candidate of candidates) {
+			const candidateText =
+				`${candidate.title} ${candidate.narrative ?? ""}`.toLowerCase();
+			for (const [wordA, wordB] of contradictionPairs) {
+				if (
+					(hasWord(inputText, wordA) && hasWord(candidateText, wordB)) ||
+					(hasWord(inputText, wordB) && hasWord(candidateText, wordA))
+				) {
+					return candidate;
+				}
+			}
+		}
+	} catch {
+		// FTS5 query failed
+	}
+
+	return null;
+}

package/dist/template/.opencode/plugin/memory.ts

@@ -11,7 +11,8 @@
  * 5. Context Management — messages.transform → token budget enforcement
  *
  * Tools: observation, memory-search, memory-get, memory-read,
- *        memory-update, memory-timeline, memory-admin
+ *        memory-update, memory-timeline, memory-graph-add, memory-graph-query,
+ *        memory-graph-invalidate, memory-compact, memory-admin
  *
  * Module structure:
  *   memory.ts              — Plugin entry (this file)

package/dist/template/.opencode/skill/design-taste-frontend/SKILL.md

@@ -1,8 +1,20 @@
 ---
 name: design-taste-frontend
-description: Use as the BASE aesthetic skill for any web UI to override default LLM design biases. Enforces strict typography, color, spacing, and component architecture rules. Load BEFORE frontend-design when premium visual quality is required.
+description: Use when building any web UI as the BASE aesthetic layer to override default LLM design biases. Enforces strict typography, color, spacing, and component architecture rules. Load BEFORE frontend-design when premium visual quality is required.
 ---
 
+## When to Use
+
+- When building any web UI that needs to override default LLM design biases
+- Before loading `frontend-design` skill when premium visual quality is required
+- As the base aesthetic layer for any UI implementation task
+
+## When NOT to Use
+
+- When a more specific aesthetic overlay is loaded (high-end-visual-design, minimalist-ui, industrial-brutalist-ui)
+- For non-UI tasks (backend, CLI, data processing)
+
+
 # High-Agency Frontend Skill
 
 ## 1. ACTIVE BASELINE CONFIGURATION

package/dist/template/.opencode/skill/figma-go/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: figma-go
-description: Use for Figma read/write access WITHOUT an API token, via figma-mcp-go plugin bridge. Prefer over figma skill when no API token is available. MUST load when user needs Figma data and has the desktop plugin installed.
+description: Use when you need Figma read/write access WITHOUT an API token, via figma-mcp-go plugin bridge. Prefer over figma skill when no API token is available. MUST load when user needs Figma data and has the desktop plugin installed.
 mcp:
   figma-mcp-go:
     command: npx

package/dist/template/.opencode/skill/full-output-enforcement/SKILL.md

@@ -3,6 +3,19 @@ name: full-output-enforcement
 description: MUST load when generating complete files, long code blocks, or any output where truncation or placeholder comments like '// ... rest of code' would be harmful. Bans all placeholder patterns and enforces exhaustive, unabridged output.
 ---
 
+## When to Use
+
+- When generating complete files, long code blocks, or full configuration outputs
+- When truncation or placeholder comments like `// ... rest of code` would be harmful
+- When the user needs exhaustive, unabridged output
+
+## When NOT to Use
+
+- For short code snippets or single-function responses
+- When summarization is explicitly requested
+- For conversational responses that don't involve code generation
+
+
 # Full-Output Enforcement
 
 ## Baseline

package/dist/template/.opencode/skill/high-end-visual-design/SKILL.md

@@ -3,6 +3,19 @@ name: high-end-visual-design
 description: Use INSTEAD OF design-taste-frontend when user explicitly requests premium, agency-quality, or luxury visual design. Defines exact fonts, spacing, shadows, and animations that make websites feel expensive. Blocks cheap AI defaults.
 ---
 
+## When to Use
+
+- When the user explicitly requests premium, agency-quality, or luxury visual design
+- Instead of design-taste-frontend when high-end aesthetics are the priority
+- For landing pages, marketing sites, or portfolio projects that need to feel expensive
+
+## When NOT to Use
+
+- For internal tools, admin panels, or dashboards where function > form
+- When minimalist-ui or industrial-brutalist-ui aesthetics are requested instead
+- For rapid prototyping where visual polish is not yet needed
+
+
 # Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
 
 ## 1. Meta Information & Core Directive

package/dist/template/.opencode/skill/industrial-brutalist-ui/SKILL.md

@@ -3,6 +3,19 @@ name: industrial-brutalist-ui
 description: Use INSTEAD OF design-taste-frontend when user requests brutalist, military-terminal, or raw mechanical aesthetics. Swiss typographic print meets utilitarian color. For data-heavy dashboards or editorial sites needing declassified-blueprint energy.
 ---
 
+## When to Use
+
+- When the user requests brutalist, military-terminal, or raw mechanical aesthetics
+- For data-heavy dashboards or editorial sites needing declassified-blueprint energy
+- Instead of design-taste-frontend when utilitarian aesthetics are requested
+
+## When NOT to Use
+
+- For consumer-facing marketing or e-commerce sites
+- When clean, minimalist, or luxury aesthetics are requested
+- For accessibility-critical applications where brutalist patterns may reduce readability
+
+
 # SKILL: Industrial Brutalism & Tactical Telemetry UI
 
 ## 1. Skill Meta