codex-genesis-harness 0.1.0

package/.codex/skills/project-genesis-harness/scripts/run-verification.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="${1:-.}"
+cd "$root"
+
+run_if() {
+  local label="$1"
+  shift
+  echo "==> $label"
+  "$@"
+}
+
+if [ -f package.json ]; then
+  if command -v npm >/dev/null 2>&1; then
+    npm run lint --if-present
+    npm run typecheck --if-present
+    npm test --if-present
+    npm run build --if-present
+  fi
+elif [ -f pyproject.toml ] || [ -f requirements.txt ]; then
+  command -v pytest >/dev/null 2>&1 && run_if "pytest" pytest -q
+  command -v ruff >/dev/null 2>&1 && run_if "ruff" ruff check .
+  command -v mypy >/dev/null 2>&1 && run_if "mypy" mypy .
+elif [ -f Cargo.toml ]; then
+  run_if "cargo test" cargo test
+  run_if "cargo clippy" cargo clippy -- -D warnings
+elif [ -f go.mod ]; then
+  run_if "go test" go test ./...
+elif [ -f composer.json ]; then
+  command -v composer >/dev/null 2>&1 && composer test || true
+else
+  echo "No known verification command detected. Add project-specific commands to .planning/SMOKE_TESTS.md."
+fi
+
+for check in \
+  check-required-planning-files.sh \
+  check-task-tracking.sh \
+  check-no-debug-logs.sh \
+  check-spec-changelog.sh \
+  check-architecture-boundaries.sh
+do
+  script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+  if [ -x "$script_dir/$check" ]; then
+    run_if "$check" "$script_dir/$check" "$root"
+  fi
+done

package/.codex/skills/project-genesis-harness/scripts/update-state.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  echo "Usage: $0 <root> <current-phase> <active-work> <last-completed-task> <next-task> <latest-verification>" >&2
+  exit 2
+}
+
+root="${1:-}"
+phase="${2:-}"
+active="${3:-}"
+last="${4:-}"
+next="${5:-}"
+verification="${6:-}"
+
+[ -n "$root" ] && [ -n "$phase" ] && [ -n "$active" ] && [ -n "$last" ] && [ -n "$next" ] && [ -n "$verification" ] || usage
+
+cd "$root"
+mkdir -p .planning
+
+cat > .planning/STATE.md <<EOF
+# State
+
+Current project state: [~] Active
+Current phase: $phase
+Current feature or bug: $active
+Last completed task: $last
+Next task: $next
+Blocked items: None recorded
+Latest verification result: $verification
+EOF
+
+echo ".planning/STATE.md"

package/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "project-genesis-harness",
+  "version": "0.1.0",
+  "description": "Codex project operating harness for planning, tracking, verification, docs sync, and reviews.",
+  "author": {
+    "name": "Project Genesis Harness"
+  },
+  "license": "MIT",
+  "keywords": [
+    "codex",
+    "skill",
+    "planning",
+    "verification",
+    "engineering"
+  ],
+  "skills": "./.codex/skills/",
+  "interface": {
+    "displayName": "Project Genesis Harness",
+    "shortDescription": "Planning and verification harness for Codex",
+    "longDescription": "A Codex plugin that installs the project-genesis-harness skill for disciplined project initialization, feature planning, bug workflows, documentation synchronization, verification, audits, and completion reports.",
+    "developerName": "Project Genesis Harness",
+    "category": "Productivity",
+    "capabilities": [
+      "Write",
+      "Review"
+    ],
+    "defaultPrompt": [
+      "Use $project-genesis-harness and run /init.",
+      "Use $project-genesis-harness to plan this feature.",
+      "Use $project-genesis-harness to audit this repo."
+    ],
+    "brandColor": "#2563EB"
+  }
+}
+

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Project Genesis Harness contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,181 @@
+# Project Genesis Harness
+
+Project Genesis Harness is a Codex skill that turns Codex into a project operating harness: planning first, repository inspection, task tracking, test-first implementation, docs synchronization, architecture decisions, Mermaid diagrams, audits, and completion reports.
+
+## Install
+
+### From npm
+
+After the package is published to npm:
+
+```sh
+npm install -g codex-genesis-harness@latest
+```
+
+The package auto-installs the Codex skill into:
+
+```txt
+~/.agents/skills/project-genesis-harness
+~/.codex/skills/project-genesis-harness
+```
+
+You can also manage it manually:
+
+```sh
+genesis-harness install
+genesis-harness verify
+genesis-harness uninstall
+```
+
+Install only one target:
+
+```sh
+genesis-harness install --target agents
+genesis-harness install --target legacy
+genesis-harness install --target both
+```
+
+To skip auto-install during npm installation:
+
+```sh
+GENESIS_HARNESS_SKIP_POSTINSTALL=1 npm install -g codex-genesis-harness@latest
+```
+
+### From Git
+
+Clone or download this repository, then run:
+
+```sh
+./scripts/install.sh
+```
+
+By default, the installer copies the skill to:
+
+```txt
+~/.agents/skills/project-genesis-harness
+~/.codex/skills/project-genesis-harness
+```
+
+If you use a custom Codex home:
+
+```sh
+CODEX_HOME=/path/to/.codex ./scripts/install.sh
+```
+
+If you use a custom modern skills home:
+
+```sh
+GENESIS_HARNESS_HOME=/path/to/.agents ./scripts/install.sh
+```
+
+## Verify
+
+```sh
+./scripts/verify.sh
+```
+
+Verify an installed copy:
+
+```sh
+./scripts/verify.sh ~/.codex/skills/project-genesis-harness
+```
+
+## Uninstall
+
+```sh
+./scripts/uninstall.sh
+```
+
+## Use
+
+After installing, invoke the skill in Codex when working in a project:
+
+```txt
+Use $project-genesis-harness and run /init.
+```
+
+The skill supports:
+
+- `/init`
+- `/new-feature <description>`
+- `/fix-bug <description>`
+- `/plan <description>`
+- `/audit`
+- `/review`
+- `/status`
+
+## What Gets Installed
+
+```txt
+.codex/skills/project-genesis-harness/
+├── SKILL.md
+├── agents/openai.yaml
+├── resources/
+└── scripts/
+```
+
+The skill itself can initialize a target project with a `.planning/` knowledge base after the project brief is confirmed.
+
+## Plugin Metadata
+
+This repository includes:
+
+```txt
+.codex-plugin/plugin.json
+```
+
+The plugin manifest points Codex-compatible plugin tooling at the packaged skill under `.codex/skills/`.
+
+## Publish To npm
+
+The npm package name is:
+
+```txt
+codex-genesis-harness
+```
+
+Publish flow:
+
+```sh
+npm login
+npm run verify
+npm run eval
+npm run pack:check
+npm version patch
+npm publish --access public
+```
+
+The package is intentionally unscoped so it can be published by the token owner without requiring a pre-created npm organization or scope.
+
+## GitHub Actions npm Publish
+
+This repository includes `.github/workflows/publish-npm.yml`.
+
+On every push to `main`, the workflow:
+
+1. runs `npm run verify`
+2. runs `npm run eval`
+3. runs `npm run pack:check`
+4. derives a unique CI version like `0.1.0-ci.123.1`
+5. publishes `codex-genesis-harness` to npm with the `latest` tag
+
+Required GitHub secret:
+
+```txt
+NPM_TOKEN
+```
+
+Create it from npm with publish permission for `codex-genesis-harness`, then add it under:
+
+```txt
+GitHub repo -> Settings -> Secrets and variables -> Actions -> New repository secret
+```
+
+If GitHub Actions fails with `npm ERR! code E403` during `npm publish`, npm accepted the token format but rejected the publish authorization. Fix the npm-side credentials before re-running the workflow:
+
+1. Confirm the token belongs to an npm account that owns `codex-genesis-harness`, or can create the package if this is the first publish.
+2. Prefer an npm automation token with publish rights for CI. Granular tokens must include package write access.
+3. If the package name is already owned by another account or organization, either transfer/grant access on npm or rename/scope the package in `package.json`.
+4. Replace the GitHub `NPM_TOKEN` secret after rotating the token.
+
+The workflow validates `NPM_TOKEN` and package visibility before running the expensive verification and publish steps so credential problems fail with an actionable error.

package/VERSION

@@ -0,0 +1,2 @@
+0.1.0
+

package/bin/genesis-harness.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+const { spawnSync } = require("child_process");
+
+const packageRoot = path.resolve(__dirname, "..");
+const skillName = "project-genesis-harness";
+const sourceDir = path.join(packageRoot, ".codex", "skills", skillName);
+const codexHome = process.env.CODEX_HOME || path.join(process.env.HOME || "", ".codex");
+const agentsHome = process.env.GENESIS_HARNESS_HOME || path.join(process.env.HOME || "", ".agents");
+const legacyTargetDir = path.join(codexHome, "skills", skillName);
+const agentsTargetDir = path.join(agentsHome, "skills", skillName);
+
+function usage(exitCode = 0) {
+  const text = `
+Project Genesis Harness
+
+Usage:
+  genesis-harness install [--target agents|legacy|both]
+  genesis-harness verify [--target agents|legacy|both]
+  genesis-harness uninstall [--target agents|legacy|both]
+  genesis-harness path
+
+Environment:
+  CODEX_HOME=/custom/.codex  Override Codex home
+  GENESIS_HARNESS_HOME=/custom/.agents  Override modern skills home
+  GENESIS_HARNESS_SKIP_POSTINSTALL=1  Skip npm postinstall auto-install
+`;
+  console.log(text.trim());
+  process.exit(exitCode);
+}
+
+function fail(message) {
+  console.error(`genesis-harness: ${message}`);
+  process.exit(1);
+}
+
+function ensureSource() {
+  const skillFile = path.join(sourceDir, "SKILL.md");
+  if (!fs.existsSync(skillFile)) {
+    fail(`missing packaged skill at ${skillFile}`);
+  }
+}
+
+function parseTarget(args, fallback = "both") {
+  let target = fallback;
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--target") {
+      target = args[i + 1];
+      i++;
+      continue;
+    }
+    usage(2);
+  }
+  if (!["agents", "legacy", "both"].includes(target)) usage(2);
+  return target;
+}
+
+function targetDirs(target) {
+  if (target === "agents") return [agentsTargetDir];
+  if (target === "legacy") return [legacyTargetDir];
+  return [agentsTargetDir, legacyTargetDir];
+}
+
+function copySkill({ quiet = false, target = "both" } = {}) {
+  ensureSource();
+  for (const dir of targetDirs(target)) {
+    fs.mkdirSync(path.dirname(dir), { recursive: true });
+
+    if (fs.existsSync(dir)) {
+      const backupDir = `${dir}.backup.${timestamp()}`;
+      fs.renameSync(dir, backupDir);
+      if (!quiet) console.log(`Existing skill backed up to: ${backupDir}`);
+    }
+
+    fs.cpSync(sourceDir, dir, { recursive: true });
+    chmodScripts(path.join(dir, "scripts"));
+
+    if (!quiet) console.log(`Installed ${skillName} to: ${dir}`);
+  }
+
+  if (!quiet) console.log(`Restart Codex, then invoke: Use $${skillName}`);
+}
+
+function uninstallSkill(target = "both") {
+  for (const dir of targetDirs(target)) {
+    if (!fs.existsSync(dir)) {
+      console.log(`Skill is not installed at: ${dir}`);
+      continue;
+    }
+    fs.rmSync(dir, { recursive: true, force: true });
+    console.log(`Removed: ${dir}`);
+  }
+}
+
+function verifySkill(target = "both") {
+  const verifyScript = path.join(packageRoot, "scripts", "verify.sh");
+  if (!fs.existsSync(verifyScript)) fail(`missing verify script at ${verifyScript}`);
+
+  for (const verifyTarget of targetDirs(target)) {
+    const result = spawnSync("bash", [verifyScript, verifyTarget], {
+      stdio: "inherit",
+      env: process.env
+    });
+    if (result.status) process.exit(result.status);
+  }
+}
+
+function chmodScripts(dir) {
+  if (!fs.existsSync(dir)) return;
+  for (const entry of fs.readdirSync(dir)) {
+    const file = path.join(dir, entry);
+    if (entry.endsWith(".sh") && fs.statSync(file).isFile()) {
+      fs.chmodSync(file, 0o755);
+    }
+  }
+}
+
+function timestamp() {
+  const date = new Date();
+  const pad = (value) => String(value).padStart(2, "0");
+  return [
+    date.getFullYear(),
+    pad(date.getMonth() + 1),
+    pad(date.getDate()),
+    pad(date.getHours()),
+    pad(date.getMinutes()),
+    pad(date.getSeconds())
+  ].join("");
+}
+
+const command = process.argv[2] || "help";
+const args = process.argv.slice(3);
+
+switch (command) {
+  case "install":
+    copySkill({ target: parseTarget(args, "both") });
+    break;
+  case "postinstall":
+    if (process.env.GENESIS_HARNESS_SKIP_POSTINSTALL === "1") {
+      process.exit(0);
+    }
+    copySkill({ quiet: true, target: "both" });
+    break;
+  case "verify":
+    verifySkill(parseTarget(args, "both"));
+    break;
+  case "uninstall":
+    uninstallSkill(parseTarget(args, "both"));
+    break;
+  case "path":
+    console.log(agentsTargetDir);
+    console.log(legacyTargetDir);
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    usage(0);
+    break;
+  default:
+    usage(2);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "codex-genesis-harness",
+  "version": "0.1.0",
+  "description": "Install and manage the Project Genesis Harness Codex skill.",
+  "license": "MIT",
+  "bin": {
+    "genesis-harness": "bin/genesis-harness.js"
+  },
+  "scripts": {
+    "postinstall": "node bin/genesis-harness.js postinstall",
+    "verify": "bash scripts/verify.sh",
+    "eval": "bash scripts/run-evals.sh",
+    "pack:check": "npm pack --dry-run"
+  },
+  "files": [
+    ".codex-plugin",
+    ".codex/skills/project-genesis-harness",
+    "bin",
+    "scripts",
+    "README.md",
+    "LICENSE",
+    "VERSION"
+  ],
+  "keywords": [
+    "codex",
+    "codex-skill",
+    "planning",
+    "project-management",
+    "engineering-harness"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/install.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+skill_name="project-genesis-harness"
+source_dir="$repo_root/.codex/skills/$skill_name"
+codex_home="${CODEX_HOME:-$HOME/.codex}"
+agents_home="${GENESIS_HARNESS_HOME:-$HOME/.agents}"
+target="both"
+
+usage() {
+  echo "Usage: $0 [--target agents|legacy|both]" >&2
+  echo "  agents: install to ${agents_home}/skills/${skill_name}" >&2
+  echo "  legacy: install to ${codex_home}/skills/${skill_name}" >&2
+  echo "  both: install to both locations" >&2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)
+      target="${2:-}"
+      [ -n "$target" ] || { usage; exit 2; }
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+case "$target" in
+  agents|legacy|both) ;;
+  *) usage; exit 2 ;;
+esac
+
+if [ ! -f "$source_dir/SKILL.md" ]; then
+  echo "Missing skill source: $source_dir/SKILL.md" >&2
+  exit 1
+fi
+
+install_one() {
+  local target_dir="$1"
+  mkdir -p "$(dirname "$target_dir")"
+
+  if [ -e "$target_dir" ]; then
+    backup_dir="${target_dir}.backup.$(date +%Y%m%d%H%M%S)"
+    mv "$target_dir" "$backup_dir"
+    echo "Existing skill backed up to: $backup_dir"
+  fi
+
+  cp -R "$source_dir" "$target_dir"
+  find "$target_dir/scripts" -type f -name '*.sh' -exec chmod +x {} \;
+  echo "Installed $skill_name to: $target_dir"
+}
+
+if [ "$target" = "agents" ] || [ "$target" = "both" ]; then
+  install_one "$agents_home/skills/$skill_name"
+fi
+
+if [ "$target" = "legacy" ] || [ "$target" = "both" ]; then
+  install_one "$codex_home/skills/$skill_name"
+fi
+
+echo "Invoke it in Codex with: Use \$$skill_name"

package/scripts/run-evals.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+skill_dir="$repo_root/.codex/skills/project-genesis-harness"
+
+fail() {
+  echo "eval failed: $*" >&2
+  exit 1
+}
+
+assert_file() {
+  [ -f "$1" ] || fail "missing file: ${1#$repo_root/}"
+}
+
+assert_contains() {
+  local file="$1"
+  local text="$2"
+  grep -q -- "$text" "$file" || fail "missing '$text' in ${file#$repo_root/}"
+}
+
+assert_file "$repo_root/.codex-plugin/plugin.json"
+assert_contains "$repo_root/.codex-plugin/plugin.json" '"skills"'
+assert_contains "$repo_root/.codex-plugin/plugin.json" '"project-genesis-harness"'
+
+for ref in workflows.md planning-schema.md research-rubric.md quality-rubric.md; do
+  assert_file "$skill_dir/references/$ref"
+  assert_contains "$skill_dir/SKILL.md" "references/$ref"
+done
+
+assert_contains "$repo_root/scripts/install.sh" '--target agents|legacy|both'
+assert_contains "$repo_root/scripts/uninstall.sh" '--target agents|legacy|both'
+assert_contains "$repo_root/bin/genesis-harness.js" '--target agents|legacy|both'
+assert_contains "$repo_root/package.json" '".codex-plugin"'
+assert_contains "$repo_root/README.md" '.agents/skills'
+
+tmp="$(mktemp -d)"
+cleanup() {
+  rm -rf "$tmp"
+}
+trap cleanup EXIT
+
+CODEX_HOME="$tmp/codex" GENESIS_HARNESS_HOME="$tmp/agents" bash "$repo_root/scripts/install.sh" --target both >/dev/null
+[ -f "$tmp/agents/skills/project-genesis-harness/SKILL.md" ] || fail "agents install target missing"
+[ -f "$tmp/codex/skills/project-genesis-harness/SKILL.md" ] || fail "legacy install target missing"
+bash "$repo_root/scripts/verify.sh" "$tmp/agents/skills/project-genesis-harness" >/dev/null
+bash "$repo_root/scripts/verify.sh" "$tmp/codex/skills/project-genesis-harness" >/dev/null
+CODEX_HOME="$tmp/codex" GENESIS_HARNESS_HOME="$tmp/agents" bash "$repo_root/scripts/uninstall.sh" --target both >/dev/null
+[ ! -e "$tmp/agents/skills/project-genesis-harness" ] || fail "agents uninstall target remains"
+[ ! -e "$tmp/codex/skills/project-genesis-harness" ] || fail "legacy uninstall target remains"
+
+echo "evals passed"

package/scripts/uninstall.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+skill_name="project-genesis-harness"
+codex_home="${CODEX_HOME:-$HOME/.codex}"
+agents_home="${GENESIS_HARNESS_HOME:-$HOME/.agents}"
+target="both"
+
+usage() {
+  echo "Usage: $0 [--target agents|legacy|both]" >&2
+}
+
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --target)
+      target="${2:-}"
+      [ -n "$target" ] || { usage; exit 2; }
+      shift 2
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      usage
+      exit 2
+      ;;
+  esac
+done
+
+case "$target" in
+  agents|legacy|both) ;;
+  *) usage; exit 2 ;;
+esac
+
+remove_one() {
+  local target_dir="$1"
+  if [ ! -e "$target_dir" ]; then
+    echo "Skill is not installed at: $target_dir"
+    return
+  fi
+  rm -rf "$target_dir"
+  echo "Removed: $target_dir"
+}
+
+if [ "$target" = "agents" ] || [ "$target" = "both" ]; then
+  remove_one "$agents_home/skills/$skill_name"
+fi
+
+if [ "$target" = "legacy" ] || [ "$target" = "both" ]; then
+  remove_one "$codex_home/skills/$skill_name"
+fi