@ksuchoi216/ahe 0.1.7 → 0.1.10

package/packages/ahe-codex/.codex/skills/ahe-ship/scripts/write_plan.py

@@ -0,0 +1,107 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+#
+# How to run:
+# 1. Install uv (if not installed):
+#      curl -LsSf https://astral.sh/uv/install.sh | sh
+# 2. Run directly:
+#      uv run write_plan.py --root "$PWD" --plan-name "Plan Title" < /tmp/ahe-plan.md
+# 3. Or with Python when dependencies are already available:
+#      python write_plan.py --root "$PWD" --plan-name "Plan Title" < /tmp/ahe-plan.md
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class WritePlanArgs:
+    root: Path
+    plan_name: str
+    overwrite: bool
+
+
+class ArgumentError(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class PlanAlreadyExistsError(Exception):
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        super().__init__(f"Plan file already exists: {path}")
+
+
+def sanitize_plan_name(plan_name: str) -> str:
+    normalized_name = re.sub(r"[^a-z0-9]+", "-", plan_name.strip().lower()).strip("-")
+    if normalized_name:
+        return normalized_name
+    raise ArgumentError("plan name must contain at least one letter or digit")
+
+
+def parse_args(argv: list[str]) -> WritePlanArgs:
+    root: Path | None = None
+    plan_name: str | None = None
+    overwrite = False
+    index = 0
+
+    while index < len(argv):
+        argument = argv[index]
+        if argument == "--root":
+            index += 1
+            if index >= len(argv):
+                raise ArgumentError("--root requires a value")
+            root = Path(argv[index])
+        elif argument == "--plan-name":
+            index += 1
+            if index >= len(argv):
+                raise ArgumentError("--plan-name requires a value")
+            plan_name = argv[index]
+        elif argument == "--overwrite":
+            overwrite = True
+        else:
+            raise ArgumentError(f"unknown argument: {argument}")
+        index += 1
+
+    if root is None:
+        raise ArgumentError("--root is required")
+    if plan_name is None:
+        raise ArgumentError("--plan-name is required")
+
+    return WritePlanArgs(root=root, plan_name=plan_name, overwrite=overwrite)
+
+
+def write_plan(args: WritePlanArgs, markdown: str) -> Path:
+    filename = f"{sanitize_plan_name(args.plan_name)}.md"
+    plans_dir = args.root / ".plans"
+    plan_path = plans_dir / filename
+
+    if plan_path.exists() and not args.overwrite:
+        raise PlanAlreadyExistsError(plan_path)
+
+    plans_dir.mkdir(parents=True, exist_ok=True)
+    plan_path.write_text(markdown, encoding="utf-8")
+    return plan_path
+
+
+def main() -> int:
+    try:
+        args = parse_args(sys.argv[1:])
+        plan_path = write_plan(args, sys.stdin.read())
+    except (ArgumentError, PlanAlreadyExistsError) as error:
+        print(error, file=sys.stderr)
+        return 1
+
+    print(plan_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/packages/ahe-codex/.codex/skills/ahe-solve/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: ahe-solve
+description: Internal AHE feature-solving workflow for dividing, planning, and solving feature work after the active goal is clear enough.
+---
+
+# AHE Solver
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-solve` as a user command.
+Use it when `ahe-think` decides that the next job is building or planning a
+feature.
+
+## Command Workflow: solve
+
+- Read the active feature context from `docs/product.md`, `feature-list.json`,
+  `progress.md`, and any relevant code files.
+- Read all existing `docs/*.md` files as supporting context.
+- When numbered product stages exist, solve against the active product stage:
+  start with `docs/product1.md`, advance to later numeric stages only after the
+  current stage's derived feature-list items are `done`, and keep future product stages as context rather than implementation scope.
+- Keep `docs/product.md` as overview context while working from an active
+  product stage.
+- Divide broad work into smaller problems when useful.
+- Plan each smaller problem before implementation.
+- Call `ahe-review` when repo or code understanding is needed.
+- Call `ahe-converse` when feature requirements, scope, or success criteria
+  are still unclear.
+- Report the solved step, remaining work, and recommended next agent back to
+  `ahe-think`.

package/packages/ahe-codex/.codex/skills/ahe-think/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: ahe-think
+description: Internal AHE orchestration protocol for routing exact `ahe`, `ahe <query>`, and `<query> ahe` requests through the AHE agent network.
+---
+
+# AHE Thinker
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-think` as a user command.
+Use it as the central decision layer for AHE work.
+
+## Purpose
+
+- Judge what is missing before another agent acts.
+- Judge the active `project`, `feature`, or `sub-feature`.
+- Decide which of `Why`, `What`, and `How` are still missing.
+- Choose the next internal agent: `ahe-review`, `ahe-converse`,
+  `ahe-harness`, or `ahe-solve`.
+- Receive each agent result, reassess the state, and decide the next step.
+
+## Routing Inputs
+
+- Exact `ahe` means continue existing harness work.
+- Exact `ahe init`, exact `ahe-new`, and exact `$ahe-new` stay on the
+  `$ahe-new` path.
+- `ahe <query>` and `<query> ahe` mean route the query through `ahe-think`.
+- Broad non-prefixed prompts must not activate AHE.
+
+## Size and Stale-Test Preflight
+
+- Before reading full harness files, run
+  `sh .codex/skills/ahe-compress/scripts/check-harness-size.sh`.
+- Run the test-overlap detector `python .codex/skills/ahe-compress/scripts/detect_stale_tests.py`
+  when the user's explicit AHE query is compression-oriented (e.g., `ahe compress`).
+- Run both compression detectors before choosing the next compression step.
+- If either detector exits with `COMPRESSION_REQUIRED` or code `2`, call
+  `ahe-compress` before normal routing. However, `ahe-compress` must not delete tests directly;
+  for test compression, `ahe-think` must decide whether the next step is `ahe-harness` for
+  harness-file compaction, `ahe-review` for stale-test confirmation and keeper selection,
+  or both in sequence.
+- Do not read oversized harness files wholesale before compression routing is
+  settled.
+
+## Startup Contract
+
+- Check whether the copied harness files are correct before reading their contents.
+- Read files strictly in this order:
+  `AGENTS.md` -> `docs/product.md` plus `docs/product{n}.md` -> `docs/architecture.md` -> `docs/instructions.md` -> `init.sh` -> `feature-list.json` -> `status.json` -> `progress.md` -> `session-handoff.md`
+- `ahe-think` explicitly owns the "what to do next" decisions for Codex-side AHE work.
+
+## Decision Rules
+
+- For a `project`, require `Why`, `What`, and `How` by default.
+- For a `feature` or `sub-feature`, require only the minimum of `Why`, `What`,
+  and `How` needed to proceed safely.
+- Read all existing `docs/*.md` files before choosing product work.
+- Treat `docs/product.md` as overview context.
+- Treat only `docs/product{number}.md` files as ordered product stages, starting
+  with `docs/product1.md` and then `docs/product2.md`.
+- Ignore non-numeric product docs such as `docs/product-alpha.md` for stage
+  ordering.
+- Choose the active product source as the lowest-numbered stage whose derived
+  feature work is not complete, or `docs/product.md` when no numbered stage
+  exists.
+- If the need is understanding repo code, harness drift, progress evidence, or
+  CodeGraph context, call `ahe-review`.
+- If the need is user clarification, call `ahe-converse`.
+- If the need is updating harness artifacts, product docs, feature tracking,
+  todo sync, or compression of completed history, call `ahe-harness`.
+- If the need is solving or decomposing feature work, call `ahe-solve`.
+
+## Interaction Model
+
+- `ahe-think` is centered, but direct worker-to-worker calls are allowed when
+  they are the obvious next step.
+- Typical loops:
+  - `ahe-think -> ahe-review -> ahe-think`
+  - `ahe-think -> ahe-harness -> ahe-think`
+  - `ahe-think -> ahe-converse -> ahe-think`
+  - `ahe-think -> ahe-solve -> ahe-think`
+  - `ahe-think -> ahe-harness-checker -> ahe-think`
+- Allowed direct handoffs include:
+  - `ahe-harness -> ahe-converse`
+  - `ahe-solve -> ahe-review`
+  - `ahe-review -> ahe-harness`
+  - `ahe-harness -> ahe-harness-checker`
+  - `ahe-new -> ahe-harness -> ahe-harness-checker`
+- Every handoff must state the goal, reason, relevant files or context, and the
+  expected result.
+
+## Broad Intent Routing
+
+- Use `ahe-review` for review-first requests.
+- Use `ahe-harness` for product, instructions, progress, feature-list, todo, or
+  compression maintenance.
+- Use `ahe-solve` for feature implementation planning or execution work.
+- Use `ahe-converse` when no safe next step exists without user input.
+
+## Hard Editing Rule
+
+- `AGENTS.md` and any `instructions.md` file may only be modified inside an explicitly changeable section.
+- If no changeable section exists, AHE must ask via `ahe-converse` instead of editing.
+- Reference and template folders must be strictly excluded from reads and edits per project rules.
+
+## Completion
+
+- Continue to the next skill or next unfinished feature until the active unit is
+  resolved.
+- Keep `docs/product.md` as overview context and `feature-list.json` as a
+  derived tracker.
+- Derive features from only the active product stage.
+- Advance from one numbered product stage to the next only after all
+  feature-list items derived from the current active stage are `done`.

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-compress"
+  "ahe-converse"
+  "ahe-feature"
+  "ahe-fix"
+  "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 ~ /^\[agents\."?ahe[-_][^]]*"?\]$/ ||
+        line ~ /^\[hooks\.state\."ahe[^"]*"\]$/ ||
+        line ~ /^\[plugins\."?ahe[^]]*"?\]$/ ||
+        line ~ /^\[plugins\."@ksuchoi216\/ahe[^"]*"\]$/
+    }
+
+    $0 == block_start {
+      skip = 1
+      next
+    }
+
+    $0 == block_end {
+      skip = 0
+      next
+    }
+
+    /^\[/ {
+      if (is_ahe_header($0)) {
+        skip = 1
+        next
+      }
+      skip = 0
+    }
+
+    skip != 1 {
+      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 \`ahe new\` for a new start.
+3. Use exact \`ahe\` to continue existing harness work.
+4. Use \`ahe ship\` after Plan Mode to write the latest plan to .plans.
+5. Use \`ahe fix\` to create a .plans fix plan for errors or changed intent.
+6. Use \`ahe <query>\` for explicit AHE requests such as \`ahe compress\`.
+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 [ ! -f "${target_shared_dir}/config.yaml" ]; then
+    printf 'Missing: %s/config.yaml\n' "${target_shared_dir}" >&2
+    errors=$((errors + 1))
+  fi
+
+  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.8",
+  "description": "Awesome Harness Engineering Codex skill package",
+  "author": "ksuchoi216",
+  "license": "MIT"
+}