@ksuchoi216/ahe 0.1.7 → 0.1.10

package/README.md

@@ -1,41 +1,84 @@
 # Awesome Harness Engineering (AHE)
 
-AHE installs Codex skills that manage harness files through chat. The public
-entrypoints stay small: use `ahe init` to start or reset harness work, `ahe` to
-continue existing work, and `ahe <query>` for explicit AHE requests such as
-`ahe compress feature-list`.
+AHE installs global Codex and Antigravity skills that manage harness files through chat. The repository uses a one-package, two-internal-packages layout (`packages/ahe-codex` and `packages/ahe-antigravity`) shipped as a single npm package. The
+public entrypoints stay small: use `ahe new` to start or reset harness work,
+`ahe` to continue existing work, `ahe ship` to save the latest plan (in Codex) or refresh and execute a saved plan (in Antigravity),
+`ahe fix` to create a `.plans` fix plan, and
+`ahe <query>` or `<query> ahe` for explicit AHE requests such as `ahe compress`
+or `compress ahe`. For a detailed in-chat explanation of the AHE architecture and workflows, use `ahe-overview`.
+
+## Core Command Workflows
+
+Here are intuitive flow examples for the primary AHE commands. While `ahe`, `ahe-new`, `ahe-ship`, and `ahe-fix` are the explicit commands, you can also use conversational queries (e.g., `ahe add dashboard export feature`) which are automatically routed.
+
+### `ahe new` Flow
+1. **Empty Workspace**: You have a new or existing repo that needs AHE.
+2. **ahe-new calling**: You type `ahe new` in Codex.
+3. **Initialization**: It prepares the workspace, creates templates, and hands off to `ahe-harness` to sync your product docs.
+
+### `ahe ship` Flow
+1. **plan mode in codex**: Generate an implementation plan inside Codex.
+2. **ahe-ship calling in codex**: If in Plan Mode, the Codex host exits Plan Mode and replays the command. Outside Plan Mode, Codex saves the plan to `.plans/` and stops.
+3. **ahe-ship calling in antigravity**: Antigravity refreshes the saved plan against current code, executes it, and cleans it up.
+
+### `ahe fix` Flow
+1. **Error Encountered**: A test fails or intent changes after execution.
+2. **ahe-fix calling**: You type `ahe fix` (or `ahe fix stale tests`) in Codex.
+3. **Fix Plan Creation**: It generates a dedicated fix plan in `.plans/` ready for Antigravity to refresh and execute.
+
+### General `ahe` Flow
+1. **Ongoing Work**: You need to implement a feature or update docs.
+2. **ahe calling**: You type `ahe` or a specific query like `ahe update product spec` in Codex.
+3. **Automatic Routing**: `ahe-think` evaluates your request and automatically routes it to the right agent (like `ahe-solve` or `ahe-harness`).
 
 ## Installed Skills
 
 | Skill | Role |
 | --- | --- |
-| `ahe-init` | New-start workflow that prepares the workspace and hands product/tracking work to `ahe-harness`. |
-| `ahe-thinker` | Centered internal router that judges what is missing and chooses the next agent. |
-| `ahe-reviewer` | Review agent for repo code, harness state, and CodeGraph context. |
-| `ahe-conversator` | Clarification agent for recursive user conversation. |
+| `ahe` | Top-level user-facing continuation skill that routes exact `ahe` and `ahe` query forms through `ahe-think`. |
+| `ahe-new` | New-start workflow that prepares the workspace and hands product/tracking work to `ahe-harness`. |
+| `ahe-think` | Centered internal router that judges what is missing and chooses the next agent. |
+| `ahe-review` | Review agent for repo code, harness state, and CodeGraph context. |
+| `ahe-converse` | Clarification agent for recursive user conversation. |
 | `ahe-harness` | Harness-management agent for product docs, instructions, feature tracking, todo sync, and compression-aware maintenance. |
-| `ahe-solver` | Feature-solving agent that divides and plans implementation work. |
-| `ahe-compression` | Internal helper that detects oversized harness files before broad reads. |
+| `ahe-feature` | Internal helper for deriving feature-list entries from product context. |
+| `ahe-fix` | Independent fix planner that writes `.plans/{plan_name}.md` for errors or changed user intent. |
+| `ahe-solve` | Feature-solving agent that divides and plans implementation work. |
+| `ahe-compress` | Internal helper that detects oversized harness files before broad reads. |
+| `ahe-overview` | Explains the AHE concept, entrypoints, and main workflows in chat with Mermaid diagrams. |
+| `ahe-ship` | In Codex: saves Plan Mode plan to `.plans/`. In Antigravity: refreshes and executes exactly one plan from `.plans/`. |
 
 ## Routing Model
 
-The internal model is centered but flexible:
+The Codex-side model is centered but flexible:
 
-`query -> ahe-thinker -> ahe-reviewer | ahe-conversator | ahe-harness | ahe-solver`
+- exact `ahe` -> `ahe-think` -> `ahe-review | ahe-converse | ahe-harness | ahe-solve`
+- `ahe <query>` or `<query> ahe` -> `ahe-think` -> `ahe-review | ahe-converse | ahe-harness | ahe-solve`
+- exact `ahe new` -> dedicated new-start workflow first, then `ahe-harness`
+- exact `ahe ship` -> independent plan-export workflow (Codex) or execution workflow (Antigravity)
+- exact `ahe fix`, `ahe fix <query>`, or `<query> ahe fix` -> independent fix-plan workflow
 
-- `ahe-thinker` is the center of judgment.
+- `ahe-think` is the center of judgment.
 - Worker agents can call each other directly when that is the logical next
   action.
-- Typical direct handoffs are `ahe-harness -> ahe-conversator`,
-  `ahe-solver -> ahe-reviewer`, and `ahe-reviewer -> ahe-harness`.
+- Typical direct handoffs are `ahe-harness -> ahe-converse`,
+  `ahe-solve -> ahe-review`, and `ahe-review -> ahe-harness`.
 
 ## Query Examples
 
 - `ahe`
-- `ahe init`
-- `ahe compress feature-list`
+- `ahe new`
+- `ahe ship`
+- `ahe fix`
+- `ahe fix stale tests`
+- `stale tests ahe fix`
+- `ahe compress`
+- `compress ahe`
 - `ahe update product spec`
 - `ahe add dashboard export feature`
 
-Only exact `ahe`, exact `ahe init`, exact `ahe-init`, exact `$ahe-init`, and
-explicit `ahe <query>` activate the hook. Broad non-prefixed prompts do not.
+Only exact `ahe`, exact `ahe new`, exact `ahe-new`, exact `$ahe-new`, and
+exact `ahe ship`, exact `ahe-ship`, exact `$ahe-ship`, exact `ahe fix`, exact
+exact `ahe-fix`, exact `$ahe-fix`, `ahe fix <query>`, `<query> ahe fix`,
+`ahe-overview`, `ahe <query>`, and `<query> ahe` activate the hook.
+Middle mentions that do not fit those command shapes do not.

package/bin/ahe

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-readonly VERSION="0.1.0"
+readonly VERSION="0.1.7"
 SCRIPT_PATH="${BASH_SOURCE[0]}"
 
 while [ -L "${SCRIPT_PATH}" ]; do
@@ -16,20 +16,6 @@ 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 AHE_CONFIG_BLOCK_START="# BEGIN AHE MANAGED CONFIG"
-readonly AHE_CONFIG_BLOCK_END="# END AHE MANAGED CONFIG"
-readonly MANAGED_SKILLS=(
-  "ahe-init"
-  "ahe-compression"
-  "ahe-conversator"
-  "ahe-harness"
-  "ahe-reviewer"
-  "ahe-solver"
-  "ahe-thinker"
-)
 
 usage() {
   cat <<'EOF'
@@ -41,224 +27,42 @@ Usage:
 EOF
 }
 
-backup_existing_installation() {
-  local target_dir="$1"
-  local backup_root="$2"
-  local backup_name="$3"
-  local timestamp
+dispatch() {
+  local command="$1"
+  shift
 
-  timestamp="$(date '+%Y%m%d-%H%M%S')"
-  mkdir -p "${backup_root}"
-  mv "${target_dir}" "${backup_root}/${backup_name}-${timestamp}"
-}
+  local codex_bin="${PACKAGE_ROOT}/packages/ahe-codex/bin/ahe-codex"
+  local antigravity_bin="${PACKAGE_ROOT}/packages/ahe-antigravity/bin/ahe-antigravity"
 
-cleanup_ahe_config_entries() {
-  local config_path="$1"
-  local temp_path=""
+  local codex_status=0
+  local antigravity_status=0
 
-  if [ ! -f "${config_path}" ]; then
-    return 0
+  if [ "${command}" != "doctor" ]; then
+    echo "=== Dispatching to ahe-codex ==="
   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
+  if [ -x "${codex_bin}" ]; then
+    "${codex_bin}" "${command}" "$@" || codex_status=$?
+  else
+    echo "Warning: ahe-codex script not found or not executable at ${codex_bin}"
+    codex_status=1
   fi
 
-  if [ ! -d "${SOURCE_SHARED_DIR}" ]; then
-    printf 'Packaged shared files are missing: %s\n' "${SOURCE_SHARED_DIR}" >&2
-    exit 1
+  if [ "${command}" != "doctor" ]; then
+    echo ""
+    echo "=== Dispatching to ahe-antigravity ==="
+  else
+    echo ""
   fi
-
-  local target_skills_dir="${PWD}/.codex/skills"
-  local target_shared_dir="${PWD}/.codex/ahe-shared"
-  local target_hooks_dir="${PWD}/.codex/hooks"
-  local target_config_path="${PWD}/.codex/config.toml"
-  local backup_dir="${PWD}/.codex/_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
+  if [ -x "${antigravity_bin}" ]; then
+    "${antigravity_bin}" "${command}" "$@" || antigravity_status=$?
+  else
+    echo "Warning: ahe-antigravity script not found or not executable at ${antigravity_bin}"
+    antigravity_status=1
   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
+  if [ "${codex_status}" -ne 0 ] || [ "${antigravity_status}" -ne 0 ]; then
+    return 1
   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}"
-
- cat <<EOF
-AHE Codex skill installed.
-
-Next:
-1. Open Codex chat in this workspace.
-2. Use \`ahe init\` for a new start.
-3. Use exact \`ahe\` to continue existing harness work.
-4. Use \`ahe <query>\` for explicit AHE requests such as \`ahe compress feature-list\`.
-EOF
-}
-
-doctor() {
-  local target_skills_dir="${PWD}/.codex/skills"
-  local target_shared_dir="${PWD}/.codex/ahe-shared"
-  local target_hooks_dir="${PWD}/.codex/hooks"
-  local skill_name=""
-
-  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
-      exit 1
-    fi
-  done
-
-  if [ ! -f "${target_shared_dir}/config.yaml" ]; then
-    printf 'Missing: %s/config.yaml\n' "${target_shared_dir}" >&2
-    exit 1
-  fi
-
-  if [ ! -d "${target_shared_dir}/templates" ]; then
-    printf 'Missing: %s/templates\n' "${target_shared_dir}" >&2
-    exit 1
-  fi
-
-  if [ ! -d "${target_shared_dir}/schemas" ]; then
-    printf 'Missing: %s/schemas\n' "${target_shared_dir}" >&2
-    exit 1
-  fi
-
-  if [ ! -f "${target_hooks_dir}/hooks.json" ]; then
-    printf 'Missing: %s/hooks.json\n' "${target_hooks_dir}" >&2
-    exit 1
-  fi
-
-  printf 'AHE skill installation looks healthy.\n'
-}
-
-uninstall_skill() {
-  local target_skills_dir="${PWD}/.codex/skills"
-  local target_shared_dir="${PWD}/.codex/ahe-shared"
-  local target_hooks_dir="${PWD}/.codex/hooks"
-  local target_config_path="${PWD}/.codex/config.toml"
-  local skill_name=""
-
-  echo "Uninstalling AHE skills from ${PWD}/.codex..."
-
-  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}"
-  cleanup_ahe_config_entries "${target_config_path}"
-
-  echo "AHE skills uninstalled successfully."
 }
 
 main() {
@@ -268,21 +72,18 @@ main() {
   fi
 
   local command="$1"
-  shift
-
+  
   case "${command}" in
-    install)
-      install_skill "$@"
-      ;;
-    uninstall)
-      uninstall_skill
-      ;;
-    doctor)
-      doctor
+    install|uninstall|doctor)
+      dispatch "$@"
       ;;
     version)
       printf '%s\n' "${VERSION}"
       ;;
+    -h|--help|help)
+      usage
+      exit 0
+      ;;
     *)
       printf 'Unknown command: %s\n' "${command}" >&2
       usage >&2

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "@ksuchoi216/ahe",
-  "version": "0.1.7",
+  "version": "0.1.10",
   "description": "Codex chat workflow skill installer for Awesome Harness Engineering",
   "publishConfig": {
     "access": "public"
   },
+  "workspaces": [
+    "packages/*"
+  ],
   "bin": {
     "ahe": "./bin/ahe"
   },
   "scripts": {
     "test": "pytest tests/ -x",
     "prepublishOnly": "npm run test",
-    "postinstall": "echo \"\" && echo \"Awesome Harness Engineering CLI installed!\" && echo \"To install the skills in your project, run: ahe install\" && echo \"\" && echo \"If you wish to uninstall later, run: npm uninstall -g @ksuchoi216/ahe\""
+    "postinstall": "echo \"\" && echo \"Awesome Harness Engineering CLI installed!\" && echo \"To install the skills, run: ahe install\" && echo \"\" && echo \"If you wish to uninstall later, run: npm uninstall -g @ksuchoi216/ahe\""
   },
   "repository": {
     "type": "git",
@@ -28,7 +31,7 @@
   "author": "ksuchoi216",
   "files": [
     "bin/",
-    ".codex/"
+    "packages/"
   ],
   "license": "MIT"
-}
+}