@ksuchoi216/ahe 0.1.7 → 0.1.12

package/packages/ahe-codex/bin/ahe-codex

@@ -0,0 +1,398 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+readonly VERSION="0.1.0"
+SCRIPT_PATH="${BASH_SOURCE[0]}"
+
+while [ -L "${SCRIPT_PATH}" ]; do
+  SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${SCRIPT_PATH}")" && pwd)"
+  SCRIPT_PATH="$(readlink "${SCRIPT_PATH}")"
+
+  case "${SCRIPT_PATH}" in
+    /*) ;;
+    *) SCRIPT_PATH="${SCRIPT_DIR}/${SCRIPT_PATH}" ;;
+  esac
+done
+
+readonly SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${SCRIPT_PATH}")" && pwd)"
+readonly PACKAGE_ROOT="$(CDPATH= cd -- "${SCRIPT_DIR}/.." && pwd)"
+readonly SOURCE_SKILLS_DIR="${PACKAGE_ROOT}/.codex/skills"
+readonly SOURCE_SHARED_DIR="${PACKAGE_ROOT}/.codex/ahe-shared"
+readonly SOURCE_HOOKS_DIR="${PACKAGE_ROOT}/.codex/hooks"
+readonly SOURCE_AGENTS_DIR="${PACKAGE_ROOT}/.codex/agents"
+readonly AHE_CONFIG_BLOCK_START="# BEGIN AHE MANAGED CONFIG"
+readonly AHE_CONFIG_BLOCK_END="# END AHE MANAGED CONFIG"
+readonly MANAGED_SKILLS=(
+  "ahe"
+  "ahe-clean"
+  "ahe-converse"
+  "ahe-feature"
+  "ahe-git"
+  "ahe-harness"
+  "ahe-harness-checker"
+  "ahe-new"
+  "ahe-overview"
+  "ahe-review"
+  "ahe-ship"
+  "ahe-solve"
+  "ahe-think"
+)
+
+codex_home() {
+  if [ -n "${CODEX_HOME:-}" ]; then
+    printf '%s\n' "${CODEX_HOME}"
+    return 0
+  fi
+
+  printf '%s\n' "${HOME}/.codex"
+}
+
+usage() {
+  cat <<'EOF'
+Usage:
+  ahe install [--force] [--backup]
+  ahe uninstall
+  ahe doctor
+  ahe version
+EOF
+}
+
+backup_existing_installation() {
+  local target_dir="$1"
+  local backup_root="$2"
+  local backup_name="$3"
+  local timestamp
+
+  timestamp="$(date '+%Y%m%d-%H%M%S')"
+  mkdir -p "${backup_root}"
+  mv "${target_dir}" "${backup_root}/${backup_name}-${timestamp}"
+}
+
+cleanup_ahe_config_entries() {
+  local config_path="$1"
+  local temp_path=""
+
+  if [ ! -f "${config_path}" ]; then
+    return 0
+  fi
+
+  temp_path="${config_path}.ahe-cleanup"
+  awk -v block_start="${AHE_CONFIG_BLOCK_START}" -v block_end="${AHE_CONFIG_BLOCK_END}" '
+    function is_ahe_header(line) {
+      return line ~ /^\[hooks\.state\."ahe[^"]*"\]$/ ||
+        line ~ /^\[plugins\."?ahe[^]]*"?\]$/ ||
+        line ~ /^\[plugins\."@ksuchoi216\/ahe[^"]*"\]$/
+    }
+
+    $0 == block_start {
+      in_block = 1
+      next
+    }
+
+    $0 == block_end {
+      in_block = 0
+      next
+    }
+
+    in_block == 1 {
+      next
+    }
+
+    /^\[/ {
+      if (is_ahe_header($0)) {
+        skip_section = 1
+        next
+      }
+      skip_section = 0
+    }
+
+    skip_section == 1 {
+      next
+    }
+
+    {
+      print
+    }
+  ' "${config_path}" > "${temp_path}"
+  mv "${temp_path}" "${config_path}"
+}
+
+install_skill() {
+  local force="false"
+  local backup="false"
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --force)
+        force="true"
+        ;;
+      --backup)
+        backup="true"
+        ;;
+      *)
+        printf 'Unknown install option: %s\n' "$1" >&2
+        usage >&2
+        exit 1
+        ;;
+    esac
+    shift
+  done
+
+  if [ ! -d "${SOURCE_SKILLS_DIR}" ]; then
+    printf 'Packaged skill files are missing: %s\n' "${SOURCE_SKILLS_DIR}" >&2
+    exit 1
+  fi
+
+  if [ ! -d "${SOURCE_SHARED_DIR}" ]; then
+    printf 'Packaged shared files are missing: %s\n' "${SOURCE_SHARED_DIR}" >&2
+    exit 1
+  fi
+
+  local target_codex_home
+  target_codex_home="$(codex_home)"
+
+  local target_skills_dir="${target_codex_home}/skills"
+  local target_shared_dir="${target_codex_home}/ahe-shared"
+  local target_hooks_dir="${target_codex_home}/hooks"
+  local target_agents_dir="${target_codex_home}/agents"
+  local target_config_path="${target_codex_home}/config.toml"
+  local backup_dir="${target_codex_home}/_backups"
+  local skill_name=""
+  local skill_target=""
+
+  cleanup_ahe_config_entries "${target_config_path}"
+
+  for skill_name in "${MANAGED_SKILLS[@]}"; do
+    skill_target="${target_skills_dir}/${skill_name}"
+
+    if [ -e "${skill_target}" ]; then
+      if [ "${backup}" = "true" ]; then
+        backup_existing_installation "${skill_target}" "${backup_dir}" "${skill_name}"
+      elif [ "${force}" != "true" ]; then
+        cat <<EOF >&2
+AHE skill is already installed at:
+  ${skill_target}
+
+Re-run with --force to overwrite or --backup to move the existing install aside first.
+EOF
+        exit 1
+      else
+        rm -rf "${skill_target}"
+      fi
+    fi
+  done
+
+  if [ -e "${target_shared_dir}" ]; then
+    if [ "${backup}" = "true" ]; then
+      backup_existing_installation "${target_shared_dir}" "${backup_dir}" "ahe-shared"
+    elif [ "${force}" = "true" ]; then
+      rm -rf "${target_shared_dir}"
+    else
+      cat <<EOF >&2
+AHE shared assets are already installed at:
+  ${target_shared_dir}
+
+Re-run with --force to overwrite or --backup to move the existing install aside first.
+EOF
+      exit 1
+    fi
+  fi
+
+  if [ -e "${target_hooks_dir}" ]; then
+    if [ "${backup}" = "true" ]; then
+      backup_existing_installation "${target_hooks_dir}" "${backup_dir}" "hooks"
+    elif [ "${force}" = "true" ]; then
+      rm -rf "${target_hooks_dir}"
+    else
+      cat <<EOF >&2
+AHE hooks are already installed at:
+  ${target_hooks_dir}
+
+Re-run with --force to overwrite or --backup to move the existing install aside first.
+EOF
+      exit 1
+    fi
+  fi
+
+  mkdir -p "${target_skills_dir}"
+  for skill_name in "${MANAGED_SKILLS[@]}"; do
+    cp -R "${SOURCE_SKILLS_DIR}/${skill_name}" "${target_skills_dir}/${skill_name}"
+  done
+  cp -R "${SOURCE_SHARED_DIR}" "${target_shared_dir}"
+  cp -R "${SOURCE_HOOKS_DIR}" "${target_hooks_dir}"
+  mkdir -p "${target_agents_dir}"
+  cp -R "${SOURCE_AGENTS_DIR}"/* "${target_agents_dir}/"
+
+  cat <<EOF >> "${target_config_path}"
+${AHE_CONFIG_BLOCK_START}
+[agents.ahe-harness-manager]
+config_file = "${target_agents_dir}/ahe-harness-manager.toml"
+${AHE_CONFIG_BLOCK_END}
+EOF
+  cat > "${target_hooks_dir}/hooks.json" <<EOF
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${target_hooks_dir}/ahe-hook.js\"",
+            "timeout": 5,
+            "statusMessage": "AHE: Checking Keyword Trigger"
+          }
+        ]
+      }
+    ]
+  }
+}
+EOF
+
+ cat <<EOF
+AHE Codex skill installed.
+Global Codex home:
+  ${target_codex_home}
+
+Next:
+1. Open Codex chat in any workspace.
+2. Use exact \`ahe\` to continue existing harness work or start a new harness when the workspace has none.
+3. Use \`ahe ship\` after Plan Mode to write the latest plan to .plans.
+4. Use \`ahe git\` for the safe git orchestration workflow.
+5. Use \`ahe <query>\` for explicit AHE requests such as \`ahe update product spec\`.
+EOF
+}
+
+doctor() {
+  printf '=== codex ===\n'
+
+  local target_codex_home
+  target_codex_home="$(codex_home)"
+
+  local target_skills_dir="${target_codex_home}/skills"
+  local target_shared_dir="${target_codex_home}/ahe-shared"
+  local target_hooks_dir="${target_codex_home}/hooks"
+  local target_agents_dir="${target_codex_home}/agents"
+  local target_config_path="${target_codex_home}/config.toml"
+  local skill_name=""
+  local errors=0
+
+  for skill_name in "${MANAGED_SKILLS[@]}"; do
+    if [ ! -f "${target_skills_dir}/${skill_name}/SKILL.md" ]; then
+      printf 'Missing: %s/%s/SKILL.md\n' "${target_skills_dir}" "${skill_name}" >&2
+      errors=$((errors + 1))
+    fi
+  done
+
+  if [ ! -d "${target_shared_dir}/templates" ]; then
+    printf 'Missing: %s/templates\n' "${target_shared_dir}" >&2
+    errors=$((errors + 1))
+  fi
+
+  if [ ! -d "${target_shared_dir}/schemas" ]; then
+    printf 'Missing: %s/schemas\n' "${target_shared_dir}" >&2
+    errors=$((errors + 1))
+  fi
+
+  if [ ! -f "${target_hooks_dir}/hooks.json" ]; then
+    printf 'Missing: %s/hooks.json\n' "${target_hooks_dir}" >&2
+    errors=$((errors + 1))
+  else
+    if ! TARGET_HOOKS_DIR="${target_hooks_dir}" node -e "
+      try {
+        const h = require(process.env.TARGET_HOOKS_DIR + '/hooks.json');
+        const cmd = h.hooks.UserPromptSubmit[0].hooks[0].command;
+        if (!cmd.includes(process.env.TARGET_HOOKS_DIR + '/ahe-hook.js')) {
+          process.exit(1);
+        }
+      } catch (e) {
+        process.exit(1);
+      }
+    " 2>/dev/null; then
+      printf 'Invalid hook command: %s/hooks.json does not point to %s/ahe-hook.js\n' "${target_hooks_dir}" "${target_hooks_dir}" >&2
+      errors=$((errors + 1))
+    fi
+  fi
+
+  if [ ! -f "${target_hooks_dir}/ahe-hook.js" ]; then
+    printf 'Missing: %s/ahe-hook.js\n' "${target_hooks_dir}" >&2
+    errors=$((errors + 1))
+  fi
+
+  if [ ! -f "${target_agents_dir}/ahe-harness-manager.toml" ]; then
+    printf 'Missing: %s/ahe-harness-manager.toml\n' "${target_agents_dir}" >&2
+    errors=$((errors + 1))
+  fi
+
+  if ! grep -q '\[agents\.ahe-harness-manager\]' "${target_config_path}" 2>/dev/null; then
+    printf 'Missing: [agents.ahe-harness-manager] in %s\n' "${target_config_path}" >&2
+    errors=$((errors + 1))
+  fi
+
+  if [ "${errors}" -gt 0 ]; then
+    printf 'AHE Codex skill installation is unhealthy (%d errors).\n' "${errors}" >&2
+    exit 1
+  fi
+
+  printf 'AHE Codex skill installation looks healthy.\n'
+}
+
+uninstall_skill() {
+  local target_codex_home
+  target_codex_home="$(codex_home)"
+
+  local target_skills_dir="${target_codex_home}/skills"
+  local target_shared_dir="${target_codex_home}/ahe-shared"
+  local target_hooks_dir="${target_codex_home}/hooks"
+  local target_agents_dir="${target_codex_home}/agents"
+  local target_config_path="${target_codex_home}/config.toml"
+  local skill_name=""
+
+  echo "Uninstalling AHE skills from ${target_codex_home}..."
+
+  for skill_name in "${MANAGED_SKILLS[@]}"; do
+    rm -rf "${target_skills_dir}/${skill_name}"
+  done
+
+  rm -rf "${target_shared_dir}"
+  rm -rf "${target_hooks_dir}"
+  rm -f "${target_agents_dir}/ahe-harness-manager.toml"
+  cleanup_ahe_config_entries "${target_config_path}"
+
+  echo "AHE skills uninstalled successfully."
+}
+
+main() {
+  if [ "$#" -eq 0 ]; then
+    usage
+    exit 1
+  fi
+
+  local command="$1"
+  shift
+
+  case "${command}" in
+    install)
+      install_skill "$@"
+      ;;
+    uninstall)
+      uninstall_skill
+      ;;
+    doctor)
+      doctor
+      ;;
+    version)
+      printf '%s\n' "${VERSION}"
+      ;;
+    -h|--help|help)
+      usage
+      exit 0
+      ;;
+    *)
+      printf 'Unknown command: %s\n' "${command}" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"

package/packages/ahe-codex/package.json

@@ -0,0 +1,7 @@
+{
+  "name": "@ahe/codex",
+  "version": "0.1.12",
+  "description": "Awesome Harness Engineering Codex skill package",
+  "author": "ksuchoi216",
+  "license": "MIT"
+}

package/.codex/ahe-shared/config.yaml

@@ -1,8 +0,0 @@
-agent_md: 80
-product_md: 180
-instructions_md: 180
-feature_list_json: 180
-progress_md: 180
-session_handoff_md: 180
-todo_md: 180
-total: 750

package/.codex/hooks/ahe-hook.js

@@ -1,195 +0,0 @@
-#!/usr/bin/env node
-const AHE_DIRECTIVE_MARKER = "<ahe-mode>";
-
-const STATUS_TABLE_LINES = [
-  "   - Start the response with a concise status report table.",
-  "   - Use this consistent Markdown table format:",
-  "     | Item | Content |",
-  "     |---|---|",
-  "     | AGENTS.md | Exists/missing, purpose status, and any obvious issue. |",
-  "     | PRODUCT.md | Exists/missing, completion state, and whether product scope needs work. |",
-  "     | INSTRUCTIONS.md | Exists/missing, and whether instruction boundaries need work. |",
-  "     | feature-list.json | Valid/missing/invalid, unfinished feature summary, and all-done status. |",
-  "     | PROGRESS.md | Exists/missing and current session state. |",
-  "   - Keep the table short and readable.",
-  "   - Do not include the next step inside the table.",
-];
-
-const COMMON_ROUTING_LINES = [
-  "1. Run CodeGraph preflight before inspecting harness status:",
-  "   - Check whether the CodeGraph CLI is installed with `command -v codegraph`.",
-  "   - If the `codegraph` command is not installed, report `NOT INSTALLATION of codegraph`, skip `codegraph init` and `codegraph sync`, and continue with normal repo inspection.",
-  "   - If `.codegraph/` does not exist, run `codegraph init` before reviewing code.",
-  "   - If `.codegraph/` exists, run `codegraph sync` before reviewing code.",
-  "",
-  "2. Inspect current harness state before choosing a workflow:",
-  "   - Check `AGENTS.md`.",
-  "   - Check `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` as the product/specification source of truth.",
-  "   - Check `feature-list.json` as a derived tracker.",
-  "   - Check `PROGRESS.md`.",
-  "   - Use `ahe-thinker` as the internal decision layer before choosing the next action.",
-  "   - Before reading large harness files wholesale, let `ahe-thinker` run the `ahe-compression` size detector and call `ahe-compression` if compression is required.",
-  "",
-  "3. Review code through CodeGraph when available:",
-  "   - Prefer CodeGraph MCP or CodeGraph exploration for code review and impact context after the preflight command succeeds.",
-  "   - If CodeGraph is not installed, skip CodeGraph review and rely on normal repo inspection.",
-  "",
-  "4. Make the first response a simple harness engineering status report table before proceeding:",
-  ...STATUS_TABLE_LINES,
-];
-
-const AHE_PROGRESS_DIRECTIVE = [
-  AHE_DIRECTIVE_MARKER,
-  "AHE automatic operation activated.",
-  "",
-  "The user sent the exact AHE command. Operate as the Awesome Harness Engineering router:",
-  "",
-  ...COMMON_ROUTING_LINES,
-  "",
-  "5. Decide the next AHE workflow with `ahe-thinker`:",
-  "   - If no harness files exist, route to `$ahe-init`.",
-  "   - If `docs/PRODUCT.md` or `docs/INSTRUCTIONS.md` is missing or empty, classify the state as `harness engineering not enough`.",
-  "   - If `feature-list.json` is missing or invalid, generating an empty one from template is allowed, but do not write specific features until `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` are created and organized.",
-  "   - If any feature in `feature-list.json` has a status other than `done`, classify the state as `in the middle of building features` and continue the first unfinished feature whose dependencies are satisfied.",
-  "   - If all features are `done` and no obvious harness gap remains, classify the state as `completed all` and ask the user for the next task.",
-  "   - Call `ahe-reviewer` when repo or code understanding is needed.",
-  "   - Call `ahe-conversator` when the next safe step is blocked on user input.",
-  "   - Call `ahe-harness` when product docs, instructions, tracking, todo sync, or compression-aware harness maintenance must change.",
-  "   - Call `ahe-solver` when the next job is solving or planning a feature.",
-  "",
-  "6. After the table, classify the harness into exactly one state.",
-  "   - Use exactly one state: `harness engineering not enough`, `in the middle of building features`, or `completed all`.",
-  "   - Do not include the next step inside the table.",
-  "   - Continue automatically after classification.",
-];
-
-const AHE_INIT_DIRECTIVE = [
-  AHE_DIRECTIVE_MARKER,
-  "AHE automatic operation activated.",
-  "",
-  "The user sent the exact AHE init command. Treat this as a possible new start request:",
-  "",
-  "1. Route to `$ahe-init` first.",
-  "2. If no AHE-managed harness files exist, start initialization normally.",
-  "3. If any AHE-managed harness file exists, read the existing files, summarize the current project purpose and product specification state, and ask what restart scope the user wants.",
-  "4. Do not remove, overwrite, or refresh existing harness files before the user answers the restart-scope question.",
-  "5. If the chosen restart scope replaces prior harness history, summarize that replaced state in the refreshed tracking artifacts instead of creating backup copies.",
-  "6. Interpret the restart scope from the user's free-form answer; examples like `purpose` and `product` are not a closed list.",
-  "7. Product/instructions specification details belong in `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md`, not `AGENTS.md`.",
-  "8. After setup, call `ahe-harness` to build the initial product, instructions, and tracking state.",
-  "9. Use `ahe-thinker` before clarification when the next setup step is uncertain.",
-  "10. If clarification is needed, call `ahe-conversator` for the exact missing detail.",
-].join("\n");
-
-function getQueryDirective(prompt) {
-  return [
-    AHE_DIRECTIVE_MARKER,
-    "AHE automatic operation activated.",
-    "",
-    `Original prompt: "${prompt}"`,
-    "",
-    "The user sent an explicit AHE query. Route it through `ahe-thinker`:",
-    "",
-    ...COMMON_ROUTING_LINES,
-    "",
-    "5. Decide the next AHE workflow with `ahe-thinker` based on the original prompt:",
-    "   - Use `ahe-reviewer` for code or harness review work.",
-    "   - Use `ahe-harness` for product, instructions, progress, feature-list, todo, or compression maintenance.",
-    "   - For `ahe compress feature-list`, replace old completed feature entries with one summarized done feature, preserve unfinished details, and reconcile `feature-list.json` against `docs/PRODUCT.md`.",
-    "   - If no new feature can be derived from `docs/PRODUCT.md`, call `ahe-conversator` to ask what next feature, product direction, or goal should be tracked.",
-    "   - Use `ahe-solver` for feature-solving work.",
-    "   - If multiple plausible next steps remain, use `ahe-conversator` to ask the minimum question needed.",
-    "",
-    "6. After the table, classify the harness into exactly one state.",
-    "   - Use exactly one state: `harness engineering not enough`, `in the middle of building features`, or `completed all`.",
-    "   - Do not include the next step inside the table.",
-    "   - Continue automatically after classification.",
-  ].join("\n");
-}
-
-function normalizePrompt(prompt) {
-  return prompt.trim().toLowerCase();
-}
-
-function isExactAheCommand(prompt) {
-  return normalizePrompt(prompt) === "ahe";
-}
-
-function isExactAheInitCommand(prompt) {
-  const normalizedPrompt = normalizePrompt(prompt);
-  return (
-    normalizedPrompt === "ahe init" ||
-    normalizedPrompt === "ahe-init" ||
-    normalizedPrompt === "$ahe-init"
-  );
-}
-
-function isExplicitAheQuery(prompt) {
-  const normalizedPrompt = normalizePrompt(prompt);
-  if (isExactAheCommand(prompt) || isExactAheInitCommand(prompt)) {
-    return false;
-  }
-  return normalizedPrompt.startsWith("ahe ");
-}
-
-async function main() {
-  let raw = "";
-  process.stdin.setEncoding("utf8");
-  for await (const chunk of process.stdin) {
-    raw += chunk;
-  }
-
-  if (!raw.trim()) {
-    return;
-  }
-
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    return;
-  }
-
-  if (
-    parsed &&
-    parsed.hook_event_name === "UserPromptSubmit" &&
-    typeof parsed.prompt === "string"
-  ) {
-    if (isExactAheCommand(parsed.prompt)) {
-      process.stdout.write(
-        JSON.stringify({
-          hookSpecificOutput: {
-            hookEventName: "UserPromptSubmit",
-            additionalContext: AHE_PROGRESS_DIRECTIVE.join("\n"),
-          },
-        }) + "\n"
-      );
-      return;
-    }
-
-    if (isExactAheInitCommand(parsed.prompt)) {
-      process.stdout.write(
-        JSON.stringify({
-          hookSpecificOutput: {
-            hookEventName: "UserPromptSubmit",
-            additionalContext: AHE_INIT_DIRECTIVE,
-          },
-        }) + "\n"
-      );
-      return;
-    }
-
-    if (isExplicitAheQuery(parsed.prompt)) {
-      process.stdout.write(
-        JSON.stringify({
-          hookSpecificOutput: {
-            hookEventName: "UserPromptSubmit",
-            additionalContext: getQueryDirective(parsed.prompt),
-          },
-        }) + "\n"
-      );
-    }
-  }
-}
-
-main().catch(() => {});