holycodex 0.15.0 → 0.15.1-dev.35.1

package/README.md

@@ -3,3 +3,7 @@
 The public `holycodex` CLI composes the workspace installer, doctor, cleanup,
 version, and workflow lifecycle commands. The normative command contract is
 in the repository [CLI contract](../../docs/CLI.md).
+
+The Codex plugin is installed officially with `codex plugin marketplace add`
+followed by `codex plugin add holycodex@holycodex`. Use `bunx holycodex` only for the
+standalone CLI, including diagnostics and legacy payload repair.

package/dist/assets/plugin/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bun \"${PLUGIN_ROOT}/hooks/version.ts\"",
+            "commandWindows": "\"C:/Program Files/Git/bin/bash.exe\" -lc \"bun \\\"${PLUGIN_ROOT}/hooks/version.ts\\\"\"",
+            "timeout": 10,
+            "statusMessage": "HolyCodex: reporting version"
+          }
+        ]
+      }
+    ]
+  }
+}

package/dist/assets/plugin/hooks/version.ts

@@ -0,0 +1,54 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const VERSION_PATTERN = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:-[0-9A-Za-z.-]+)?$/u;
+const WINDOWS_GIT_BASH_INSTRUCTION =
+  " Use C:/Program Files/Git/bin/bash.exe for every shell command.";
+type VersionManifest = Readonly<{ readonly version: string }>;
+
+export function renderVersionContext(version: string, platform: NodeJS.Platform): string {
+  const suffix = platform === "win32" ? WINDOWS_GIT_BASH_INSTRUCTION : "";
+  return `HolyCodex ${version}.${suffix}`;
+}
+
+export function renderSessionStartOutput(
+  version: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  return `${JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: renderVersionContext(version, platform),
+    },
+  })}\n`;
+}
+
+export async function readInstalledPluginVersion(pluginRoot: string): Promise<string> {
+  const manifestPath = join(pluginRoot, ".codex-plugin", "plugin.json");
+  const parsed: unknown = JSON.parse(await readFile(manifestPath, "utf8"));
+  if (!isVersionManifest(parsed)) {
+    throw new Error("HolyCodex plugin manifest has no valid version.");
+  }
+  return parsed.version;
+}
+
+function isVersionManifest(value: unknown): value is VersionManifest {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    "version" in value &&
+    typeof value.version === "string" &&
+    VERSION_PATTERN.test(value.version)
+  );
+}
+
+if (import.meta.main) {
+  const pluginRoot = process.env["PLUGIN_ROOT"]?.trim();
+  if (!pluginRoot) {
+    throw new Error("PLUGIN_ROOT is required.");
+  }
+  process.stdout.write(await readInstalledPluginVersion(pluginRoot).then(renderSessionStartOutput));
+}

package/dist/assets/plugin/plugin.json

@@ -1,39 +1,34 @@
 {
   "name": "holycodex",
+  "version": "0.15.1",
   "description": "Root-directed capabilities and deterministic installed assets for HolyCodex.",
+  "author": {
+    "name": "David Basile Filho",
+    "url": "https://github.com/davidbasilefilho"
+  },
+  "homepage": "https://github.com/davidbasilefilho/holycodex",
+  "repository": "https://github.com/davidbasilefilho/holycodex",
   "license": "Apache-2.0",
-  "skills": [
-    "plan",
+  "keywords": [
+    "codex",
+    "agents",
     "workflows",
-    "programming",
-    "code-review",
-    "debugging",
-    "context7-cli",
-    "writing-for-agents",
-    "babysit-ci",
-    "ast-grep",
-    "commit",
-    "compress",
-    "handoff",
-    "lsp-setup",
-    "lsp",
-    "plan-review",
-    "refactor",
-    "remove-slop",
-    "rules",
-    "ponytail"
+    "developer-tools"
   ],
-  "assets": [
-    "agents/root.md",
-    "agents/explorer.md",
-    "agents/librarian.md",
-    "agents/worker.md",
-    "agents/reviewer.md",
-    "skills/ponytail/LICENSE",
-    "skills/ponytail/NOTICE",
-    "skills/ponytail/metadata.json"
-  ],
-  "hooks": ["hooks/manifest.json"],
-  "rules": ["rules/manifest.json", "rules/holycodex.md"],
-  "compaction": ["compaction/manifest.json", "compaction/holycodex.md"]
+  "skills": "./skills",
+  "interface": {
+    "displayName": "HolyCodex",
+    "shortDescription": "Root-directed Codex workflows and bounded specialist skills.",
+    "longDescription": "HolyCodex provides plan-aware workflows, bounded specialist agents, and deterministic verification for Codex tasks.",
+    "developerName": "David Basile Filho",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Skills",
+      "Hooks",
+      "Code Intelligence"
+    ],
+    "defaultPrompt": [
+      "Use HolyCodex to implement and verify this task."
+    ]
+  }
 }

package/dist/assets/plugin/skills/writing-for-agents/SKILL.md

@@ -1,10 +1,26 @@
 ---
 name: writing-for-agents
-description: Use when authoring or reviewing prompts, skills, profiles, delegations, handoffs, workflows, or other agent steering.
+description: Use when authoring or reviewing instructions consumed by agents, including prompts, skills, profiles, delegations, handoffs, and workflows.
 ---
 
-Write agent instructions as an interface, because a receiving agent needs a concrete outcome, evidence packet, authority boundary, and checkable finish rather than a role label alone.
+# Writing for agents
 
-Owner: the authoring role within its approved scope. Boundary: state behavior beside the reason, keep one source of truth, disclose branch-only detail progressively, preserve retained constraints, and leave material decisions with the owning authority.
+Treat instructions as a small interface, not a role description. Start with one contract:
 
-Completion: the instruction is compact, independently authored, triggerable at the right branch, explicit about exclusions and escalation, and testable through the receiving agent's output and completion criterion.
+Owner: the authoring role within its approved scope.
+Boundary: keep policy in one source of truth and return material decisions to the owning agent.
+Completion: the receiving agent can act, prove, and stop from this instruction alone.
+
+- **Objective and outcome:** what must be true when the assignment ends.
+- **Scope and authority:** exact files or decisions in scope, and who owns everything else.
+- **Constraints:** retained policy, tools, security, and non-goals.
+- **Evidence and completion:** the output shape, proof required, and the condition that permits stopping.
+- **Escalation:** the precise missing fact or conflict that returns to the owning agent.
+
+Write each behavior beside its reason when the reason changes a decision. Prefer direct positive steering, one source of truth, and pointers to branch-only detail. Remove duplicate policy, stale context, no-op prose, and instructions the environment already enforces. Keep a resumed assignment to its changed constraints and delta; do not replay the whole contract.
+
+For Sol, state invariants and decision boundaries. For Luna, name the exact files or actions, evidence fields, authority limit, and stop condition; do not leave operational choices implicit. Keep dynamic assignments short enough to preserve working context.
+
+Use the narrowest route: `programming` for implementation, `code-review` once after implementation, `workflows` for substantive orchestration, `context7-cli` for current external documentation, and `handoff` when context must pause or transfer. Read the selected route's skill only after choosing it.
+
+Completion means the instruction is independently actionable, triggerable at the right branch, explicit about exclusions and escalation, and testable through the receiver's output. Adapted from the supplied Matt Pocock skills-writing concepts.