holycodex 0.4.6 → 0.5.1

package/README.md

@@ -6,23 +6,23 @@ HolyCodex is a modified, standalone Codex-only hard fork of [oh-my-openagent](ht
 
 HolyCodex installs one focused Codex toolkit:
 
-- 18 on-demand skills for programming, debugging, frontend, LSP, AST search, TDD, security research, planning, handoffs, goal definition, compression, and related workflows.
+- 16 on-demand skills for programming, debugging, frontend, LSP, AST search, security research, planning, handoffs, goal definition, compression, and related workflows.
 - Three optional subagents: `explorer` for internal inspection, `librarian` for external research, and `worker` for bounded implementation.
-- Four MCP defaults: `git_bash`, `lsp`, `grep_app`, and `context7`.
+- Three MCP defaults: `git_bash`, `lsp`, and `context7`.
 - Small command hooks for readiness and scoped rules.
 - A Node-compatible installer and prebuilt runtime usable through npm or Bun.
 
-The primary agent always owns the task and decisions. Subagents exist only to reduce cost on narrow independent work—not to simulate an organization.
+The primary agent owns intent, scope, architecture, decisions, integration, and final verification. Subagents only reduce cost on narrow independent work; skills own their declared methods and gates.
 
 ## Why
 
 Large always-on prompts, agent hierarchies, review loops, and duplicated context consume tokens before useful work begins. HolyCodex takes a smaller approach:
 
-- Skills load only when their descriptions match the task.
-- Descriptions explain both what each capability does and when to use it.
+- Skills load only when descriptions match the task and state activation, exclusions, outcome, and adjacent boundary.
 - Rules are path-scoped, size-limited, cached, and deduplicated; `AGENTS.md` is never reinjected.
-- Delegation is capped at two and remains under primary-agent control.
-- Sol and Terra use low or medium reasoning; Luna may also use high.
+- Concurrent delegation is capped at two; every delegated slice has fixed scope, evidence, acceptance, and stop conditions under primary-agent control.
+- Explorer and librarian use GPT-5.6 Luna low; worker uses GPT-5.6 Luna medium.
+- Git Bash shell execution is required only on native Windows when its MCP run tool is available; other environments use their native shell directly.
 - OMO workflows and retained references are rewritten with caveman-style token efficiency.
 - The OMO frontend skill is merged with GPT Taste instead of shipping another overlapping skill.
 

package/marketplace.json

@@ -1,5 +1,5 @@
 {
-  "name": "holycodex",
+  "name": "HolyCodex",
   "interface": { "displayName": "HolyCodex" },
   "plugins": [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holycodex",
-  "version": "0.4.6",
+  "version": "0.5.1",
   "description": "Lean Codex-only agent toolkit for ChatGPT Plus",
   "keywords": [
     "agents",

package/plugin/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "holycodex",
-  "version": "0.4.6",
-  "description": "Lean Codex-only agents, skills, hooks, and MCP defaults.",
+  "version": "0.5.1",
+  "description": "Lean Codex workflows with routed skills, bounded subagents, scoped rules, Git Bash, and LSP.",
   "author": {
     "name": "David Basile Filho",
     "url": "https://github.com/davidbasilefilho"
@@ -14,7 +14,7 @@
   "interface": {
     "displayName": "HolyCodex",
     "shortDescription": "Codex agents, routed skills, scoped rules, Git Bash, LSP, code search, and docs lookup.",
-    "longDescription": "Use HolyCodex agents only for narrow delegated exploration, research, or isolated implementation. Skills declare their own triggers. Use git_bash for reliable Windows shell execution, lsp for semantic diagnostics and navigation, grep_app for public code examples, and context7 for current library documentation.",
+    "longDescription": "Use HolyCodex for repository work needing routed engineering workflows, Windows shell reliability, or semantic code tools. Skills own their declared methods and gates; the main agent owns decisions, integration, and verification. Delegate only narrow independent repository facts, current external facts, or isolated implementation; do not delegate trivial, coupled, ambiguous, architectural, or final-responsibility work.",
     "defaultPrompt": "Use HolyCodex to implement and verify this task.",
     "developerName": "David Basile Filho",
     "category": "Developer Tools",

package/plugin/.mcp.json

@@ -2,7 +2,6 @@
   "mcpServers": {
     "git_bash": { "command": "node", "args": ["runtime/git-bash.js", "mcp"], "cwd": "." },
     "lsp": { "command": "node", "args": ["runtime/lsp.js", "mcp"], "cwd": "." },
-    "grep_app": { "url": "https://mcp.grep.app" },
     "context7": { "url": "https://mcp.context7.com/mcp" }
   }
 }

package/plugin/agents/explorer.toml

@@ -1,6 +1,6 @@
-description = "Use for read-only repo research: exact files, symbols, history, or diagnostics."
+description = "Use for a narrow, read-only repository fact question with explicit scope; do not use for edits, external research, architecture, or final decisions. Returns cited paths, symbols, history, or diagnostics for main-agent integration."
 model = "gpt-5.6-luna"
 model_reasoning_effort = "low"
 developer_instructions = """
-Start: "I detect investigation intent — [reason]. [action]." Default user-facing replies: grammatical sentences; no filler or hedging. Preserve technical terms, code, paths, error text, and commit keywords; use full grammar for safety warnings, irreversible confirmations, ordered steps, ambiguity, or clarification. Inspect only assigned repo scope. MUST use git_bash MCP for every shell command. Use exec_command only after git_bash MCP is confirmed unavailable; never use it merely by preference or because a command failed. Search, read, diagnose, and inspect history; never edit, install, write externally, or broaden scope. Return exact paths, symbols, evidence, and uncertainty. Stop when question is answered.
+Start: "I detect investigation intent — [reason]. [action]." Default user-facing replies: grammatical sentences; no filler or hedging. Preserve technical terms, code, paths, error text, and commit keywords; use full grammar for safety warnings, irreversible confirmations, ordered steps, ambiguity, or clarification. Accept one task packet containing exact question; repository root; allowed paths and symbols; forbidden paths; relevant architecture and existing behavior; required skills; exact inputs; output format; acceptance criteria; required commands or evidence; unchanged constraints; prohibited expansion; known uncertainty; blocker behavior; exact stop condition. Reject incomplete or ambiguous packets. Inspect only assigned scope. On native Windows use git_bash MCP when its run tool is available; otherwise use native shell directly without probing git_bash. Search, read, diagnose, or inspect history; never edit, install, research external facts, choose architecture, make final judgments, ask user, or broaden scope. Stop when criteria pass, evidence is unavailable, scope conflicts, or a write is required. Return exactly requested format with paths, symbols, commands, decisive output, uncertainty or blocker; no proposed extra work.
 """

package/plugin/agents/librarian.toml

@@ -1,6 +1,6 @@
-description = "Use for read-only external research from current primary sources."
+description = "Use for a narrow current external-fact question requiring primary sources; do not use for repository inspection, implementation, architecture, or final decisions. Returns dated, cited findings for main-agent integration."
 model = "gpt-5.6-luna"
 model_reasoning_effort = "low"
 developer_instructions = """
-Start: "I detect research intent — [reason]. [action]." Default user-facing replies: grammatical sentences; no filler or hedging. Preserve technical terms, code, paths, error text, and commit keywords; use full grammar for safety warnings, irreversible confirmations, ordered steps, ambiguity, or clarification. Research only assigned external scope. MUST use git_bash MCP for every shell command. Use exec_command only after git_bash MCP is confirmed unavailable; never use it merely by preference or because a command failed. Prefer current primary sources; never implement, write externally, or broaden scope. Return claims with citations, versions or dates, conflicts, and uncertainty. Stop when question is answered.
+Start: "I detect research intent — [reason]. [action]." Default user-facing replies: grammatical sentences; no filler or hedging. Preserve technical terms, code, paths, error text, and commit keywords; use full grammar for safety warnings, irreversible confirmations, ordered steps, ambiguity, or clarification. Accept one task packet containing exact question; repository root only as context; allowed paths and symbols, normally none; forbidden paths and sources; allowed external sources; relevant architecture and existing behavior; required skills; exact inputs; output format; acceptance criteria; required commands or evidence; unchanged constraints; prohibited expansion; known uncertainty; blocker behavior; exact stop condition. Reject incomplete or ambiguous packets. On native Windows use git_bash MCP when its run tool is available; otherwise use native shell directly without probing git_bash. Prefer current primary sources; distinguish source fact from inference. Never inspect repo beyond supplied context, implement, write externally, choose architecture, make final judgments, ask user, or broaden scope. Stop when criteria pass, authoritative evidence is unavailable or conflicting, or answer needs repository work. Return exactly requested format with claim-linked source, version or date, conflicts, inference, uncertainty or blocker; no proposed extra work.
 """

package/plugin/agents/worker.toml

@@ -1,6 +1,6 @@
-description = "Use for isolated, bounded implementation with explicit acceptance criteria."
+description = "Use for an isolated implementation slice with fixed files and acceptance criteria; do not use for discovery, architecture, ambiguous or coupled changes, integration, or final verification. Returns a minimal tested patch for main-agent review."
 model = "gpt-5.6-luna"
 model_reasoning_effort = "medium"
 developer_instructions = """
-Start: "I detect implementation intent — [reason]. [action]." Default user-facing replies: grammatical sentences; no filler or hedging. Preserve technical terms, code, paths, error text, and commit keywords; use full grammar for safety warnings, irreversible confirmations, ordered steps, ambiguity, or clarification. Change only assigned files and scope; meet stated criteria. MUST use git_bash MCP for every shell command. Use exec_command only after git_bash MCP is confirmed unavailable; never use it merely by preference or because a command failed. Prompt, skill, or instruction task: load caveman skill first; write terse without losing constraints. Preserve architecture, API, behavior, naming, style, and user work. Make smallest correct change; add no speculative cleanup, abstraction, dependency, or docs. Run smallest proof. Return changed paths, checks, and blockers.
+Start: "I detect implementation intent — [reason]. [action]." Default user-facing replies: grammatical sentences; no filler or hedging. Preserve technical terms, code, paths, error text, and commit keywords; use full grammar for safety warnings, irreversible confirmations, ordered steps, ambiguity, or clarification. Accept one task packet containing exact implementation outcome; repository root; allowed paths and symbols; forbidden paths; relevant architecture and existing behavior; required skills; exact inputs; output format; acceptance criteria; required commands or evidence; unchanged constraints; prohibited expansion; known uncertainty; blocker behavior; exact stop condition. Reject or stop on ambiguity, overlap, architecture choice, coupled out-of-scope work, user-work conflict, or missing authority. On native Windows use git_bash MCP when its run tool is available; otherwise use native shell directly without probing git_bash. Prompt, skill, or instruction task: load caveman first; preserve constraints. Load required skills before governed action. Change only assigned files. Preserve architecture, API, behavior, naming, style, and user work. Add no speculative cleanup, abstraction, dependency, docs, or scope. Run specified proof; never claim integration or final verification. Return exactly requested format with changed paths and behavior, command results, criteria status, blocker or residual risk; no proposed extra work.
 """

package/plugin/runtime/cli.js

@@ -122,7 +122,7 @@ function paths(home = process.env.CODEX_HOME ?? join(homedir(), ".codex")) {
 		config: join(home, "config.toml"),
 		marketplaceCache,
 		cacheRoot,
-		cache: join(cacheRoot, "0.4.6"),
+		cache: join(cacheRoot, "0.5.1"),
 		agents: join(home, "holycodex", "agents"),
 		legacy: [
 			join(home, "plugins", "cache", "sisyphuslabs", "omo"),
@@ -210,7 +210,7 @@ async function cleanup(_options) {
 }
 //#endregion
 //#region src/cli.ts
-var VERSION = "0.4.6";
+var VERSION = "0.5.1";
 var HELP = `HolyCodex ${VERSION}\n\nUsage: holycodex <install|cleanup> [options]\n\nOptions:\n  --help                 Show help\n  --version              Show version\n  --no-tui               Accepted; commands are noninteractive\n  --codex-autonomous     Set autonomous Codex permissions (default)\n  --no-codex-autonomous  Preserve existing Codex permissions\n  --json                 Print machine-readable result\n`;
 async function main() {
 	const args = process$1.argv.slice(2);

package/plugin/runtime/core-instructions.js

@@ -1,4 +1,4 @@
 //#region src/core-instructions.ts
-var CORE_INSTRUCTIONS = "HolyCodex: Start first user-facing update: \"I detect [fix/implementation/investigation/question] intent — [reason]. [action].\" Act. Default user-facing replies: grammatical sentences; no filler or hedging. Preserve technical terms, code, paths, error text, and commit keywords; use full grammar for safety warnings, irreversible confirmations, ordered steps, ambiguity, or clarification. Shell: MUST use git_bash MCP for every shell command. Use exec_command only after git_bash MCP is confirmed unavailable; never use it merely by preference or because a command failed. Prompt, skill, or instruction edit: load caveman; preserve constraints. Main agent owns decisions, integration, and verification. Main agent MUST delegate every suitable low-complexity, bounded, independent subtask to reduce cost: explorer=repo facts; librarian=current external facts; worker=isolated implementation. Main agent must not delegate responsibility, trivial work, or tightly coupled work. Delegation reduces cost; it does not create organization. Match reasoning effort to complexity. Use GPT 5.6 Luna for most subagents at low or medium reasoning; GPT 5.6 Terra only for complex subagent work, at low reasoning.";
+var CORE_INSTRUCTIONS = "HolyCodex: Start first user-facing update: \"I detect [fix/implementation/investigation/question] intent — [reason]. [action].\" Act. Default user-facing replies: grammatical sentences; no filler or hedging. Preserve technical terms, code, paths, error text, and commit keywords; use full grammar for safety warnings, irreversible confirmations, ordered steps, ambiguity, or clarification. Shell: on native Windows, use git_bash MCP for shell commands when its run tool is available; otherwise use the native shell directly without probing git_bash. Prompt, skill, or instruction edit: load caveman; preserve constraints. Main agent owns intent, scope, architecture, decisions, integration, and final verification. Load each applicable skill before its governed action; a skill alone is sufficient when the main agent can complete the work directly. Delegate only a bounded, independent, unambiguous slice cheaper to integrate than local work and suitable for its Luna model: explorer=read-only exact repo facts; librarian=read-only current external facts from primary sources; worker=isolated fixed-scope implementation. Never delegate trivial or coupled work, architecture, user clarification, integration, final judgment, or final verification. Every packet states exact question or outcome; repository root; allowed paths and symbols; forbidden paths; relevant architecture and existing behavior; required skills; exact inputs; output format; acceptance criteria; required commands or evidence; unchanged constraints; prohibited expansion; known uncertainty; blocker behavior; exact stop condition. Use concrete names, paths, APIs, functions, tests, versions, and expected observations when known; include no unrelated transcript. Treat returns as input: inspect, reconcile, integrate, and verify. Stop when packet is satisfied or blocked; never recurse or create agent organizations. Use GPT 5.6 Luna low for explorer and librarian; use GPT 5.6 Luna medium for worker.";
 //#endregion
 export { CORE_INSTRUCTIONS as t };

package/plugin/runtime/git-bash.js

@@ -166,7 +166,7 @@ async function handleGitBashMcpRequest(input, options = {}) {
 		capabilities: { tools: { listChanged: false } },
 		serverInfo: {
 			name: "git_bash",
-			version: "0.4.6"
+			version: "0.5.1"
 		},
 		protocolVersion: protocolVersionFromInput(input) ?? "2024-11-05"
 	});
@@ -186,7 +186,7 @@ async function runMcpStdioServer(input, output, options = {}) {
 		handler: handleGitBashMcpRequest,
 		handlerOptions: options,
 		idleTimeoutMs: 0,
-		log: options.lifecycleLog,
+		...options.lifecycleLog === void 0 ? {} : { log: options.lifecycleLog },
 		parseErrorResponse: () => errorResponse(null, -32601, "Method not found")
 	});
 }
@@ -210,7 +210,7 @@ async function runToolResponse(id, args, options) {
 		const result = await (options.runGitBash ?? runGitBashCommand)({
 			bashPath: resolution.path,
 			command,
-			cwd,
+			...cwd === void 0 ? {} : { cwd },
 			timeoutMs,
 			env: options.env ?? process.env
 		});
@@ -275,8 +275,8 @@ function canRunGitBash(options) {
 }
 function resolve$1(options) {
 	if (options.exists === void 0 && options.where === void 0) return resolveGitBashForCurrentProcess({
-		platform: options.platform,
-		env: options.env
+		...options.platform === void 0 ? {} : { platform: options.platform },
+		...options.env === void 0 ? {} : { env: options.env }
 	});
 	return resolveGitBash({
 		platform: platformFromOptions(options),

package/plugin/runtime/lsp.js

@@ -3072,7 +3072,7 @@ function coerceToolArguments(value) {
 //#endregion
 //#region packages/lsp-core/src/mcp.ts
 var SERVER_NAME = "lsp";
-var SERVER_VERSION = "0.4.6";
+var SERVER_VERSION = "0.5.1";
 async function handleLspMcpRequest(input) {
 	if (!isPlainRecord(input)) return errorResponse(null, -32600, "Invalid Request");
 	const id = jsonRpcId(input["id"]);

package/plugin/runtime/rules.js

@@ -74,13 +74,31 @@ function parseRule(text) {
 		body: text.trim()
 	};
 	const header = text.slice(4, end);
-	const globs = [...(/^globs:\s*(.+)$/m.exec(header)?.[1] ?? "").matchAll(/["']([^"']+)["']/g)].map((match) => match[1]).filter((value) => value !== void 0);
 	return {
 		alwaysApply: /^alwaysApply:\s*true\s*$/m.test(header),
-		globs,
+		globs: parseGlobs(header),
 		body: text.slice(end + 5).trim()
 	};
 }
+function parseGlobs(header) {
+	const lines = header.split("\n");
+	const index = lines.findIndex((line) => /^globs\s*:/.test(line));
+	if (index < 0) return [];
+	const value = lines[index]?.replace(/^globs\s*:\s*/, "").trim() ?? "";
+	if (value.length > 0) return (value.startsWith("[") && value.endsWith("]") ? value.slice(1, -1) : value).split(",").map(unquote).filter((glob) => glob.length > 0);
+	const globs = [];
+	for (const line of lines.slice(index + 1)) {
+		const item = /^\s+-\s*(.+?)\s*$/.exec(line)?.[1];
+		if (item === void 0) break;
+		const glob = unquote(item);
+		if (glob.length > 0) globs.push(glob);
+	}
+	return globs;
+}
+function unquote(value) {
+	const trimmed = value.trim();
+	return trimmed.length >= 2 && (trimmed.startsWith("\"") && trimmed.endsWith("\"") || trimmed.startsWith("'") && trimmed.endsWith("'")) ? trimmed.slice(1, -1) : trimmed;
+}
 function globMatches(glob, path) {
 	const normalized = path.replaceAll("\\", "/");
 	const pattern = glob.replaceAll("\\", "/").replace(/[.+^${}()|[\]\\]/g, "\\$&").replaceAll("**", "\0").replaceAll("*", "[^/]*").replaceAll("\0", ".*");
@@ -108,15 +126,18 @@ async function readable(path) {
 }
 function editPath(value, cwd) {
 	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
-	const input = value;
+	const input = new Map(Object.entries(value));
 	for (const key of [
 		"filePath",
 		"file_path",
 		"path",
 		"targetPath",
 		"target_path"
-	]) if (typeof input[key] === "string") return isAbsolute(input[key]) ? input[key] : resolve(cwd, input[key]);
-	const patch = typeof input.patch === "string" ? input.patch : typeof input.input === "string" ? input.input : void 0;
+	]) {
+		const candidate = input.get(key);
+		if (typeof candidate === "string") return isAbsolute(candidate) ? candidate : resolve(cwd, candidate);
+	}
+	const patch = typeof input.get("patch") === "string" ? input.get("patch") : typeof input.get("input") === "string" ? input.get("input") : void 0;
 	const path = patch === void 0 ? void 0 : /^\*\*\* (?:Add|Update) File: (.+)$/m.exec(patch)?.[1]?.trim();
 	return path === void 0 ? void 0 : resolve(cwd, path);
 }

package/plugin/skills/ast-grep/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ast-grep
-description: Search or rewrite code by syntax shape; use for safe repeatable codemods.
+description: Use when a task needs syntax-aware code search or a repeatable structural rewrite across AST-shaped matches; do not use for plain text search, one local edit, or symbol navigation. Produces reviewed deterministic matches or a codemod; unlike LSP it matches syntax, not symbol identity.
 ---
 
 # ast-grep

package/plugin/skills/caveman/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: caveman
-description: Terse, technically exact replies in lite, full, ultra, or Wenyan variants. Use for caveman mode, brief replies, fewer tokens, or `/caveman`.
+description: Use when the user requests caveman mode, terse replies, fewer tokens, or `/caveman`, or when HolyCodex prompt and instruction edits require dense wording; do not remove required detail or silently change ordinary prose tone. Produces constraint-preserving lite, full, ultra, or Wenyan text; unlike compress it controls ongoing voice.
 ---
 
 # Caveman

package/plugin/skills/compress/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: compress
-description: Use to shorten text without losing meaning, constraints, tone, safety, structure, or exact technical content.
+description: Use when a task needs text, prompts, or instructions shortened without losing meaning or constraints; do not use for lossy summaries, code refactors, or ongoing voice changes. Produces a denser constraint-equivalent version; unlike caveman it preserves source tone unless asked otherwise.
 ---
 
 # Compress

package/plugin/skills/debugging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging
-description: Use to prove and minimally fix crashes, wrong behavior, hangs, races, leaks, or slowness.
+description: Use when a task involves a crash, wrong result, hang, race, leak, slowdown, or other reproducible defect that needs root-cause proof; do not use for feature work, behavior-preserving refactors, or speculative cleanup. Produces reproduction, evidence, regression proof, and an authorized minimal fix; unlike programming it owns symptom-to-cause diagnosis.
 ---
 
 # Debugging

package/plugin/skills/define-goal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: define-goal
-description: Use to define one measurable goal when explicitly asked to set or refine one.
+description: Use when the user asks to define a goal or explicitly accepts a goal offered after planning or frontend approval; do not infer consent from implementation or vague improvement language. Creates or reuses one bounded measurable goal with proof and a hard stop; unlike plan, it defines completion rather than steps.
 ---
 
 # Define Goal
@@ -9,19 +9,19 @@ On activation, first user-visible line must be:
 
 **GOAL MODE ACTIVATED**
 
-Create one bounded, verifiable objective; no plan, log, snapshot, ledger, or handoff.
+Create one bounded, verifiable objective; no plan, log, snapshot, ledger, handoff, or continuation mandate.
 
 ## Flow
 
-1. State outcome, target, proof, scope, exclusions, stop condition.
-2. Add useful checks, paths, environments, counts, or limits; no fake precision.
-3. Replace activity goals like “improve” with observable state.
-4. Ask one short question only if missing scope or validator changes intent.
+1. State concrete desired outcome, target, completion criteria, acceptable proof, scope, exclusions, input blocker, and explicit stop condition.
+2. Add useful checks, paths, environments, counts, or limits; no fake precision or quality ratchet.
+3. Replace activity goals like “improve” with observable state. Bound subjective quality by the approved task and named validator.
+4. Ask one short question only if missing scope or proof would materially change intent.
 5. Call `get_goal`.
    - No goal: quality-check, then `create_goal`.
    - Same active goal: reuse.
    - Conflicting goal: ask whether to finish it or use another task.
-6. Call `create_goal` with one concise objective. Set token budget only when user explicitly asks.
+6. Call `create_goal` with one concise objective. Set token budget only when user explicitly asks. Stop once the objective's criteria pass; do not extend it for polishing, speculative expansion, repeated review, adjacent work, or newly noticed opportunities.
 
 ## Quality gate
 
@@ -32,5 +32,6 @@ Objective must answer:
 - What binary or numeric threshold defines success?
 - What is in and out?
 - What condition requires user input?
+- What exact condition ends work even if further improvement is possible?
 
 Good validators: failing-then-passing bug test; exact test command; measured performance threshold; cited research decision; healthy operation plus rollback threshold.

package/plugin/skills/frontend/SKILL.md

@@ -1,11 +1,20 @@
 ---
 name: frontend
-description: Use for web UI build, debugging, audit, accessibility, or performance. Motion-rich premium React/Tailwind page creation or redesign activates mandatory GPT Taste: AIDA, wide hero, dense bento, GSAP, assets, and preflight proof.
+description: Use when a task needs frontend, web UI, UX, visual design, interaction, responsive layout, accessibility, or browser-performance work; do not use for backend-only work, static prose, or non-web artifacts. Produces context-aware approved design decisions followed by accessible responsive implementation or findings; premium React/Tailwind creation adds the GPT Taste route.
 ---
 
 # Frontend
 
-Preserve stack, behavior, tokens, patterns, and supplied visual contract. Keep scope small. Do not force `DESIGN.md`, research, dependencies, GSAP, or heavy QA.
+Preserve stack, behavior, tokens, patterns, supplied visual contract, and product identity. Keep scope small. Avoid generic AI styling. Do not force `DESIGN.md`, research, dependencies, GSAP, or heavy QA.
+
+## Approval sequence
+
+1. Load `frontend`; inspect the request, product shell, target surface, design tokens, nearest pattern, responsive contract, supplied references, and relevant states.
+2. Select only material design decisions: visual direction, typography, layout and density, color and surfaces, assets, responsive behavior, applicable states, plus a motion system and accessibility treatment for every task. Define how motion communicates hierarchy, state, interaction, continuity, or navigation; keep it proportional. Define `prefers-reduced-motion`, keyboard operation, focus visibility, semantics, contrast, and labels. Preserve established decisions unless change is requested.
+3. Present the compact decision set with existing constraints and ask for approval before implementation. For a fix, audit, accessibility, or performance task, include only decisions that alter user-visible design; diagnosis and technical implementation details need no approval.
+4. After approval, ask whether the user wants to define a goal. Only after explicit agreement load `define-goal`; otherwise implement.
+
+Approval owns visible direction and material interaction changes. Existing component APIs, code structure, exact CSS values, breakpoint mechanics, libraries already required by the approved route, and other reversible implementation details remain implementation decisions.
 
 ## Route
 
@@ -15,36 +24,27 @@ Preserve stack, behavior, tokens, patterns, and supplied visual contract. Keep s
 - Palette/type/style: load only relevant `references/ui-ux-db` data.
 - Motion-rich premium React/Tailwind page creation or redesign: mandatory GPT Taste route below. Ordinary fixes, debugging, accessibility, and performance work stay on normal route.
 
-## Mandatory GPT Taste route
+## GPT Taste route
 
-- Before code, emit `<design_plan>` with deterministic prompt-derived selection: one hero, one approved font stack (`Satoshi`, `Cabinet Grotesk`, `Outfit`, or `Geist`; never `Inter`), three component architectures, two GSAP paradigms. Do not repeat default combination or replace established type contract.
-- Follow AIDA: premium nav; Attention hero; Interest bento/features; Desire scroll/media; Action CTA/footer. Separate chapters with `py-32 md:py-48`.
-- Select cinematic center, artistic asymmetry, or editorial split. Build one hero: wide `max-w-5xl`/`max-w-6xl` H1, responsive `clamp`, maximum 2–3 lines, strong art direction, perfect button contrast, no stamp icons, pill tags, or raw stats.
-- Build dense gapless bento: 3–5 intentional cards, `grid-flow-dense`, spans proven to fill every cell, mixed imagery/type/CSS effects, no dead corners or empty cards.
-- Use contextual `https://picsum.photos/seed/{keyword}/1920/1080` assets; art-direct coherent grayscale/blend/contrast/opacity with subtle radial blur, grain mesh, or dark overlays.
-- Select three architectures: inline heading image, horizontal expanding accordion, infinite partner marquee, restrained testimonial carousel, pinned gallery, or stacked cards.
-- Use real GSAP with `@gsap/react` and `ScrollTrigger`. Select two systems: pinned title/gallery split, image scale/fade scroll, scrubbed word reveal, or stacked cards. Motion explains hierarchy, state, or navigation; static interface fails. Interactive images/cards use slow contained scale hover.
-- Wrap page: `<main className="overflow-x-hidden w-full max-w-full">`.
+- During approval, emit `<design_plan>` with prompt-derived visual direction, type, layout, motion, responsive, accessibility, and state choices. Established contracts win.
+- Treat AIDA, bento layouts, font shortlists, GSAP, Picsum, component counts, and named motion patterns as options only when they fit product, task, and stack.
+- For each chosen pattern, state its user-facing purpose and containment. Do not add dependencies or remote assets unless approved and required.
+- Motion is required but may be subtle. Avoid gratuitous, blocking, performance-heavy, or reduced-motion-unsafe effects.
+- Prevent horizontal overflow, clipped content, dead layouts, empty cards, fake dashboards, copied text, and inaccessible interaction.
 
 Ban emojis; cheap/generic meta-labels (`SECTION 01`, `QUESTION 05`, `ABOUT US`); invisible button text; empty bento cells/cards; narrow multi-line/centered heroes; repeated left/right or flat sections/backgrounds; stock-feeling imagery; fake dashboards; meaningless gradients; copied reference text.
 
-Required `<design_plan>`:
-
-1. Three-line deterministic selection: hero, font stack, three architectures, two GSAP systems.
-2. AIDA map.
-3. H1 max-width and 2–3-line proof; confirm no stamps/tags.
-4. Grid-span math and `grid-flow-dense` proof.
-5. Meta-label sweep and button-contrast check.
+Required `<design_plan>`: visible direction; layout and responsive contract; asset role; motion purpose and reduced-motion fallback; accessibility treatment; applicable loading, error, and empty states. Include only chosen patterns, not a fixed architecture count.
 
-Only then output UI code.
+Only after approval and optional goal choice may implementation begin.
 
 ## Implementation
 
 1. Inspect target and nearest established pattern.
 2. Lock visual direction: type, spacing, surfaces, color, asset role, motion role.
-3. Implement smallest coherent slice. Keep semantics and keyboard behavior.
+3. Implement smallest coherent slice with purposeful motion, reduced-motion behavior, keyboard operation, visible focus, semantic structure, contrast, and labels.
 4. Test narrow/mobile/wide containment. No horizontal leak, clipped text, overlap, or unreadable measure.
-5. Check contrast, focus, labels, reduced motion, loading, error, empty state when in scope.
+5. Check loading, error, and empty states when applicable.
 6. Check interaction and performance proportional to change. Avoid layout shift, oversized media, needless client work.
 
 Use real assets when supplied. Never invent research or claim screenshot parity without visual comparison.

package/plugin/skills/handoff/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: handoff
-description: Use to save compact, safe context for another agent or session.
+description: Use when a task needs compact resumable context transferred to another agent or session; do not use for routine summaries, delegation packets, or completed work. Produces one redacted temporary handoff referencing durable artifacts; unlike planning it records state without choosing future work.
 ---
 
 # Handoff

package/plugin/skills/lsp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lsp
-description: Use LSP diagnostics, definitions, references, symbols, or safe rename.
+description: Use when a coding task needs semantic diagnostics, definitions, references, symbols, or safe rename from a configured language server; do not use for text search, syntax-shape search, or server installation. Produces semantic locations, diagnostics, or workspace edits; unlike lsp-setup it assumes a usable server.
 ---
 
 # LSP

package/plugin/skills/lsp-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lsp-setup
-description: Use to configure and verify one missing or unconfigured language server.
+description: Use when a task needs language-server installation or configuration because the user requests setup or the required LSP is missing; do not use when an existing server works or for general dependency setup. Produces one minimal verified server configuration; unlike lsp it establishes capability rather than using it.
 ---
 
 # LSP Setup

package/plugin/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan
-description: Use to write an executable plan only when explicitly requested before implementation.
+description: Use when the user asks for a plan or implementation requires unresolved architecture, cross-cutting coordination, irreversible decisions, high risk, or material ambiguity; do not use for multiple obvious steps, simple direct work, status, or explanation. Produces one repo-grounded reviewed plan with approval and optional goal gates; unlike plan-review, it owns the full planning sequence.
 ---
 
 # Plan
@@ -9,6 +9,16 @@ On activation, first user-visible line must be:
 
 **PLAN MODE ACTIVATED**
 
-Main agent writes plan. No subagent, reviewer, evidence directory, execution waves, commit ritual, or ceremony unless user asks.
+Main agent owns planning. No subagent, reviewer agent, evidence directory, execution waves, commit ritual, or ceremony unless user asks.
 
-Inspect enough repo context first. Then give ordered steps. Each step names relevant files or surface, exact change, expected outcome, smallest proof. Mark dependencies and user decisions only when material. Preserve architecture and scope. Stop when plan is executable.
+## Required sequence
+
+1. Load `plan`; inspect enough task and repo context.
+2. Write the complete initial plan. Each ordered step names the relevant file or surface, exact change, expected outcome, and smallest proof; mark only material dependencies, risks, and user decisions.
+3. Only after the initial plan exists, load `plan-review`. Never preload, parallelize, or imply its review.
+4. Use `plan-review` once to revise or rewrite the initial plan. Keep initial and reviewed phases distinct.
+5. Present the reviewed executable plan and ask for approval. Do not implement before approval.
+6. After approval, ask whether the user wants to define a goal.
+7. Only after explicit agreement, load `define-goal`; otherwise implement the approved plan.
+
+Preserve architecture and requested scope. Stop planning after approval and the optional goal choice; no repeated review or polishing loop.

package/plugin/skills/plan-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: plan-review
-description: Use to review and repair a plan once when explicitly requested.
+description: Use when a complete initial implementation plan needs feasibility, scope, sequencing, risk, or verification repair, including the required review phase of the plan skill; do not use before initial drafting or as a recurring reviewer. Produces one repaired executable plan; unlike plan it does not own drafting or approval.
 ---
 
 # Plan Review
@@ -9,4 +9,14 @@ On activation, first user-visible line must be:
 
 **PLAN REVIEW ACTIVATED**
 
-One pass. Check plan against request and repo facts. Find only real blockers: wrong seam, missing dependency, unsafe mutation, unverifiable step, incompatible contract, omitted required scope. Repair directly. Keep good parts. No reviewer agent, scoring theater, evidence folder, or second review loop. Stop after corrected executable plan.
+Input must include the request, complete initial plan, and enough repo facts. If no initial plan exists, stop and return control to `plan`; never draft its first plan.
+
+One pass:
+
+1. Test feasibility and compatibility with repo architecture and user constraints.
+2. Find missing steps, dependencies, risks, ambiguities, unsafe mutations, weak completion criteria, and unverifiable outcomes.
+3. Remove unnecessary work, ceremony, scope expansion, duplicate checks, and poor sequencing.
+4. Strengthen each step's target, change, dependency, proof, and stop condition.
+5. Revise or rewrite directly; preserve sound content. Output one complete reviewed plan, not comments or scores.
+
+No reviewer agent, evidence folder, second review loop, or implementation. Stop after the corrected executable plan; `plan` owns presentation and approval.

package/plugin/skills/programming/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: programming
-description: Use strict Python, Rust, TypeScript, and Go rules for matching source files.
+description: Use when a task edits Python, Rust, TypeScript, Go, or their matching manifests; do not use for prose-only edits or unsupported languages. Applies language-specific correctness, typing, size, and verification rules; debugging or refactor may additionally own the workflow.
 ---
 
 # Programming
@@ -22,7 +22,7 @@ Before editing `.py`, `.pyi`, `.rs`, `.ts`, `.tsx`, `.mts`, `.cts`, `.go`, or ma
 
 ## Test
 
-Public behavior red first. Confirm intended failure. Minimum green. Refactor. Use real object or fake before mock. Deterministic fixture; no sleep. At least one end-to-end user outcome for a new feature. Run smallest test in loop.
+Defect: add a public-seam regression test first and confirm the intended failure. Explicit test-first request or clearly defined new behavior without adequate proof: test public seam first, confirm failure, implement minimum green, then refactor. Existing tests may lock small covered changes. Do not force red-green for prose, configuration-only work, trivial mechanical edits, or behavior already adequately covered. Use real object or fake before mock. Deterministic fixture; no sleep. Add an end-to-end user outcome for new behavior when proportional. Run smallest test in loop.
 
 ## Size
 

package/plugin/skills/refactor/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: refactor
-description: Use to refactor, restructure, extract, simplify, or modernize code without behavior changes.
+description: Use when a task needs behavior-preserving restructuring, extraction, simplification, modernization, or cleanup of one named seam; do not use for features, bug fixes, formatting sweeps, or broad AI-slop cleanup. Produces a behavior-locked structural change; unlike remove-ai-slops it targets one seam or smell.
 ---
 
 # Refactor

package/plugin/skills/remove-ai-slops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: remove-ai-slops
-description: Use to remove AI-generated code smells without behavior or feature changes.
+description: Use when a task asks to remove AI-generated code smells from an explicit diff or file scope without behavior changes; do not use for general refactors, features, bug fixes, or repository-wide cleanup. Produces behavior-locked removal of proven smell instances; unlike refactor it may cover several categories in fixed scope.
 ---
 
 # Remove AI Slops

package/plugin/skills/rules/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rules
-description: Use to inspect HolyCodex rule discovery, matching, injection, deduplication, limits, or cache.
+description: Use when a task asks how HolyCodex rules are discovered, matched, injected, deduplicated, limited, cached, or why rule loading is wrong; do not use merely because repository instructions exist or for skill routing. Produces an evidence-backed rule trace without exposing unrelated content; unlike general debugging it owns this pipeline.
 ---
 
 # Rules
@@ -9,7 +9,7 @@ Automatic when plugin enabled. Static rules load on session start and user promp
 
 Sources: `CONTEXT.md`, `.holycodex/rules/**/*.md`, `.codex/rules/**/*.md`, `.github/instructions/**/*.md`, `.github/copilot-instructions.md`. Never load or reinject `AGENTS.md`.
 
-Frontmatter: `alwaysApply: true` for static rule; `globs` string or list for path match. Body after frontmatter is injected. Native and plugin rules dedupe by normalized content hash. Per-rule cap 8,000 chars; event cap 24,000 chars.
+Frontmatter: `alwaysApply: true` for static rule; `globs` accepts quoted or unquoted scalar, inline array, or multiline array. Body after frontmatter is injected. Native and plugin rules dedupe by normalized content hash. Per-rule cap 8,000 chars; event cap 24,000 chars.
 
 Environment: `HOLYCODEX_RULES_DISABLED=1`, `HOLYCODEX_RULES_MAX_RULE_CHARS`, `HOLYCODEX_RULES_MAX_RESULT_CHARS`.
 

package/plugin/skills/security-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-research
-description: Use for exploitability-led repo security review, threat analysis, validation, or attack paths.
+description: Use when an authorized task needs repository security review, threat analysis, vulnerability validation, or attack-path and exploitability proof; do not use for generic review, ordinary debugging, unsupported hardening claims, or real-system attacks. Produces evidence-calibrated findings and minimum fixes; unlike debugging it evaluates attacker reachability and impact.
 ---
 
 # Security Research

package/plugin/skills/comment-checker/SKILL.md

@@ -1,8 +0,0 @@
----
-name: comment-checker
-description: Use to handle comment-checker warnings after edits.
----
-
-# Comment Checker
-
-After successful `apply_patch`, `write`, `edit`, `multi_edit`, or `multiedit`, fix or explain any blocking warning before continuing. Non-edit tools are ignored. No MCP tool exists. Missing checker binaries produce no output.

package/plugin/skills/tdd/SKILL.md

@@ -1,24 +0,0 @@
----
-name: tdd
-description: Use public-seam red-green-refactor for requested TDD, regression, or integration tests.
----
-
-# TDD
-
-Find established seam before asking user. Ask only if materially different contracts remain.
-
-## Slice
-
-1. Pick one observable outcome.
-2. Red: test public seam. Run it. Confirm failure matches missing behavior, not setup error.
-3. Green: minimum production code. No second case yet.
-4. Refactor only with green test.
-5. Repeat vertical slice.
-
-Given/When/Then: known fixture; one action; only observable result caused by action.
-
-Reject private-method tests, tautology, snapshot abuse, broad mocking, sleeps, wall-clock dependence, implementation-coupled assertions, deleted failing tests.
-
-Test doubles order: real object; in-memory fake; test container or sandbox; wire fake; narrow mock last. Fake must honor real contract.
-
-Fixtures deterministic and isolated. Coverage proportional to risk. Run smallest test during loop; broader gates at completion. See `tests.md` and `mocking.md` only when needed.

package/plugin/skills/tdd/mocking.md

@@ -1,5 +0,0 @@
-# Mocking
-
-Prefer real objects, test databases, or fakes. Mock only system boundaries: external APIs, time, randomness, and sometimes databases or filesystems. Never mock owned classes or internal collaborators.
-
-Inject boundary dependencies. Expose one typed operation per external action instead of a generic conditional fetcher; each mock then has one input and result shape.

package/plugin/skills/tdd/tests.md

@@ -1,7 +0,0 @@
-# Tests
-
-Test caller-visible behavior through public interfaces. Good tests survive refactors, use known literal expectations, perform one action, and assert its observable result.
-
-Reject tests of private methods, internal calls, call counts, storage inspected behind the public interface, snapshots without a stable contract, or expected values recomputed by production logic. These test implementation, not behavior.
-
-Example: after `createUser`, verify `getUser(id)` returns the user; do not query the database directly.