holycodex 0.4.6 → 0.5.0

package/README.md

@@ -8,21 +8,20 @@ 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.
 - 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.
 - 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.0",
   "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.0",
+  "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: question, repo scope, deliverable, acceptance criteria, evidence needed, prohibited expansion, stop condition. Inspect only that 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, or inspect history; never edit, install, research external facts, choose architecture, make final judgments, ask the user, or broaden scope. Stop when criteria are met, evidence is unavailable, scope conflicts, or a write is required. Return exactly: answer; evidence with paths, symbols, commands, and 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: question, external scope, deliverable, acceptance criteria, evidence needed, prohibited expansion, stop condition. Research only that 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; distinguish source fact from inference. Never inspect the repo beyond supplied context, implement, write externally, choose architecture, make final judgments, ask the user, or broaden scope. Stop when criteria are met, authoritative evidence is unavailable or conflicting, or the answer needs repository work. Return exactly: findings; claim-linked citations with source, version or date; conflicts and 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: fixed files and scope, required behavior, acceptance criteria, necessary context, required skills, prohibited expansion, proof, stop condition. Reject or stop on ambiguity, overlap, architecture choice, coupled out-of-scope work, user-work conflict, or missing authority. 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. Load required skills before their 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 the smallest specified proof; never claim integration or final verification. Return exactly: changed paths and behavior; tests or checks with result; acceptance 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.0"),
 		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.0";
 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: 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 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 useful low-complexity slice that is bounded, independent, unambiguous, and cheaper to integrate than to do locally: explorer=read-only repo facts; librarian=read-only current external facts; worker=isolated implementation. Use skill then subagent when both apply; the skill owns method and gates, the main agent owns decisions, and the subagent owns only its assigned slice. Never delegate trivial work, tightly coupled work, architecture, final judgment, user clarification, integration, or verification. Give only necessary context plus exact scope, deliverable, acceptance criteria, evidence, prohibited expansion, and stop condition. Treat returned work as input: inspect it, resolve conflicts, integrate deliberately, and verify the user outcome. Stop delegation when the packet is satisfied or blocked; never recurse or create organization. Match reasoning effort to complexity. 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.0"
 		},
 		protocolVersion: protocolVersionFromInput(input) ?? "2024-11-05"
 	});

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.0";
 async function handleLspMcpRequest(input) {
 	if (!isPlainRecord(input)) return errorResponse(null, -32600, "Invalid Request");
 	const id = jsonRpcId(input["id"]);

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/comment-checker/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: comment-checker
-description: Use to handle comment-checker warnings after edits.
+description: Use when an edit produces a comment-checker warning that must be fixed or explained; do not use for ordinary comments, lint output, or before an edit. Produces a disposition for every blocking warning; unlike programming checks it handles the edit hook only.
 ---
 
 # Comment Checker

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 TDD it starts from a symptom.
 ---
 
 # 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 existing 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: theme or visual direction, typography, layout and density, color and surfaces, asset role, interaction and motion, responsive behavior, and accessibility or state treatment. 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
 
@@ -17,7 +26,7 @@ Preserve stack, behavior, tokens, patterns, and supplied visual contract. Keep s
 
 ## Mandatory 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.
+- During the approval decision set, 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 a default combination or replace an 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.
@@ -36,7 +45,7 @@ Required `<design_plan>`:
 4. Grid-span math and `grid-flow-dense` proof.
 5. Meta-label sweep and button-contrast check.
 
-Only then output UI code.
+Only after approval and optional goal choice may implementation begin.
 
 ## Implementation
 

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 when a complex, risky, ambiguous, or multi-stage task needs an approved plan before implementation; do not use for 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, TDD, or refactor may additionally own the workflow.
 ---
 
 # Programming

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

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/tdd/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tdd
-description: Use public-seam red-green-refactor for requested TDD, regression, or integration tests.
+description: Use when a task requests TDD, regression coverage, integration tests, or a public-seam failing test before implementation; do not use for test inspection, unrelated failures, or work with adequate existing proof. Produces deterministic red-green-refactor slices; unlike debugging it governs test-first delivery after behavior is known.
 ---
 
 # TDD