@ksuchoi216/ahe 0.1.7 → 0.1.10

package/packages/ahe-codex/.codex/skills/ahe-fix/scripts/write_fix_plan.py

@@ -0,0 +1,108 @@
+#!/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_fix_plan.py --root "$PWD" --plan-name "Fix Plan Title" < /tmp/fix-plan.md
+# 3. Or with Python when dependencies are already available:
+#      python3 write_fix_plan.py --root "$PWD" --plan-name "Fix Plan Title" < /tmp/fix-plan.md
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class WriteFixPlanArgs:
+    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]) -> WriteFixPlanArgs:
+    root: Path | None = None
+    plan_name: str | None = None
+    overwrite = False
+    index = 0
+
+    while index < len(argv):
+        argument = argv[index]
+        match argument:
+            case "--root":
+                index += 1
+                if index >= len(argv):
+                    raise ArgumentError("--root requires a value")
+                root = Path(argv[index])
+            case "--plan-name":
+                index += 1
+                if index >= len(argv):
+                    raise ArgumentError("--plan-name requires a value")
+                plan_name = argv[index]
+            case "--overwrite":
+                overwrite = True
+            case _:
+                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 WriteFixPlanArgs(root=root, plan_name=plan_name, overwrite=overwrite)
+
+
+def write_fix_plan(args: WriteFixPlanArgs, 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_fix_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-git/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: ahe-git
+description: Use when the user explicitly invokes `ahe git` or `ahe-git` to manage and commit changes across repositories and submodules.
+---
+
+# AHE Git
+
+`ahe-git` is a user-facing AHE command independent from the normal AHE agent network.
+
+Use this skill only to orchestrate safe Git pulls and commits across the active repository and its nested Git repositories or submodules.
+Do not route through `ahe-think`. You must not call `ahe-harness`, `ahe-solve`, or any other AHE workflow agent.
+
+## Workflow
+
+1. **Discover**: Scan for both `.git` directories and `.git` files to find all nested repositories, worktrees, and submodules. Normalize and deduplicate the repo roots. Process them deepest-first (so submodules commit before parent gitlink updates).
+2. **Safe Pull**: For each repo, run `git fetch` and inspect the current branch and upstream state:
+   - If the repo is clean and upstream is ahead, fast-forward with `git pull --ff-only`.
+   - If the repo is already at upstream head, continue.
+   - If the repo is locally ahead of upstream and has local changes, continue to Dirty-State Review.
+   - If the repo has local changes and upstream has commits not present locally, **stop and explain the issue**.
+   - If upstream is missing, detached, diverged, rebasing, merging, cherry-picking, or cannot fast-forward cleanly, **stop and explain the issue**.
+   - *Never* auto-stash, auto-merge, auto-rebase, auto-resolve conflicts, or change branch topology.
+3. **Failure Policy**: On any hard Git state, stop immediately and report:
+   - Which repo is blocked.
+   - The exact detected condition.
+   - Why `ahe-git` is refusing to continue.
+   - Concrete manual steps the user should perform next (e.g., set upstream, finish merge, clean changes).
+   - Do not attempt partial recovery beyond safe read-only diagnosis.
+4. **Dirty-State Review**: Inspect `git status --short`. Read unstaged diffs first, then staged diffs, and include untracked files so the commit message covers the full pending change.
+5. **Commit-Message Drafting**: Generate one concise conventional-style message per repo (`feat:`, `fix:`, `chore:`, etc.) based on the actual diff.
+   - Run an explicit self-check pass to reject vague or misleading messages before commit.
+   - If the message is still ambiguous after self-check, stop and ask the user instead of committing a generic summary.
+6. **Commit**: Stage with `git add -A` inside that repo. Commit exactly once per dirty repo with its reviewed message.
+7. **Re-evaluate**: After submodule commits, re-evaluate parent repos so gitlink updates are committed if they became dirty.

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

@@ -0,0 +1,128 @@
+---
+name: ahe-harness
+description: Internal AHE harness workflow for managing product docs, instructions, feature tracking, session artifacts, todo sync, and compression-aware maintenance.
+---
+
+# AHE Harness
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-harness` as a user command.
+Use it when `ahe-think` or another worker decides that harness artifacts must
+be created, updated, reconciled, or compressed. It remains responsible for tracker compression, while test-suite cleanup is routed by `ahe-think` through `ahe-review` first and then `ahe-solve` or `ahe-harness` as needed.
+
+## Command Workflow: harness
+
+### Harness Inspection
+
+- Discover and read scoped docs anywhere in the repo. Treat every docs file as supporting project context, even when `AGENTS.md` does not name it directly.
+- Treat `docs/product.md`, `docs/architecture.md`, and `docs/INSTRUCTIONS.md` (or `docs/instructions.md`) as overview docs.
+- Especially read `docs/product{number}.md` files when present because they explain what to do.
+- Read `AGENTS.md`, `feature-list.json`, `progress.md`, `session-handoff.md`,
+  and `docs/todo.md` when they exist.
+- Read `status.json` when it exists.
+- Treat `docs/product.md` as the canonical source of truth and
+  `feature-list.json` as a derived tracker.
+- Treat `docs/product.md` as overview context even when a numbered product stage is active.
+- Recognize only `docs/product{number}.md` files as ordered product stages.
+- Ignore non-numeric product files such as `docs/product-alpha.md` for stage ordering.
+- Choose the lowest-numbered product stage whose derived feature work is not complete.
+- Use `docs/product.md` as the normal overview-only source when no numbered product stage exists.
+
+### Harness Decision Paths
+
+- Clarify product goal, scope, and success criteria when `docs/product.md`
+  needs to change.
+- Clarify project instructions when `docs/INSTRUCTIONS.md` needs to change.
+- Clarify what next feature or goal should be tracked when the next work item is
+  unclear.
+- `docs/product.md` is the canonical home for product specification details collected during `ahe-new`.
+- Write product behavior, scope, requirements, success criteria, and workflow details into `docs/product.md`.
+- `docs/product.md` is the canonical source of truth. Concrete feature items for `feature-list.json` must be derived from it only after it has been populated.
+- Derive concrete feature items from only the active product stage, not future stages.
+- Advance from `docs/product1.md` to `docs/product2.md` only after all feature-list items derived from `docs/product1.md` are `done`.
+- Apply the same done-before-advance rule for later stages such as `docs/product2.md` to `docs/product3.md`.
+- Do not move product specification details into `AGENTS.md`.
+- Update only the relevant docs among `docs/product.md` and
+  `docs/INSTRUCTIONS.md`.
+- If the user is adding new work, append it into the last `## TODO` section of
+  `docs/todo.md`, create that section when needed, and update
+  `feature-list.json`.
+- Apply the queued `docs/todo.md` content to `docs/product.md`.
+- Remove the applied content from `docs/todo.md` because that todo content is
+  already reflected in `docs/product.md`.
+- Update `feature-list.json` to derive the specific feature items from the updated `docs/product.md`.
+- Update `progress.md`.
+- Update `session-handoff.md`.
+- For `ahe compress`, if the harness-size detector signals compression pressure, replace old completed feature entries with one summarized done feature.
+- Keep the summarized feature valid for the existing schema by preserving its
+  own `id`, `name`, `description`, `dependencies`, `status`, and short
+  evidence.
+- Preserve unfinished, blocked, or active feature items in full detail.
+- Reconcile `feature-list.json` against `docs/product.md` after compression.
+- If no new feature can be derived from `docs/product.md`, call `ahe-converse` to ask what next feature, product direction, or goal should be tracked.
+- If a numbered product stage is active and no new feature can be derived from
+  that active product stage, call `ahe-converse` with the same clarification
+  target.
+- Call `ahe-review` directly when code or progress evidence must be checked
+  before updating harness files.
+
+### Harness Completion
+
+- Keep `feature-list.json` valid JSON.
+- Do not create backup copies when compressing harness history.
+- Keep `progress.md` focused on current work, decisions that still matter,
+  blockers, and recent verification evidence.
+- Keep `session-handoff.md` focused on the next-session startup path.
+- Keep `status.json` aligned with the active workflow.
+- When harness files are created or refreshed, hand off to `ahe-harness-checker` before considering the harness ready.
+
+## Clarification Rule
+
+When the next harness step is not clear, follow the `ahe-think` protocol first. If `ahe-think` finds missing information, follow the `ahe-converse` protocol. Ask again recursively using a Codex-supported structured response request, provide 2-3 meaningful mutually exclusive options
+when possible, and allow custom input when predefined options are not enough.
+
+### User Response Target
+
+- Collect the product, instruction, tracking, or next-feature details required
+  to update harness artifacts safely.
+
+### Questions to Ask
+
+- Ask who the product is for and what problem it solves when product intent is
+  unclear.
+- Ask what behavior, scope boundaries, and success criteria should be
+  documented.
+- Ask what rule, practice, or guideline belongs in `docs/INSTRUCTIONS.md`.
+- Ask what work should be added next when `docs/product.md` does not imply a new
+  feature safely.
+
+### Clarification Criteria
+
+- The answer must be concrete enough to update the relevant harness files
+  without guessing.
+- The answer must describe actionable work, the affected area, and the intended
+  outcome when queuing a todo item.
+
+### Re-ask When
+
+- Ask again when the answer is vague, contradictory, or incomplete.
+- Ask again when the response names a topic without enough detail to update the
+  harness safely.
+
+## Session Tracking and Handoff Sync
+
+### Tracking Update Rules
+
+- Update `status.json` at workflow start.
+- Update `status.json` after every answered question.
+- Refresh `updated_at` every time workflow state changes.
+- Keep `current_command`, `current_step`, and `workflow_complete` aligned with the active workflow state.
+- Keep the `files` status map aligned with the actual workspace files.
+
+### Progress and Handoff Content Requirements
+
+- Update `progress.md` whenever the active feature, workflow status, blockers, or verification state changes.
+- Update `session-handoff.md` whenever the current objective, completed work, important files, verification evidence, or recommended next step changes.
+- progress.md must reflect the current active feature and latest completed work.
+- session-handoff.md must leave the next Codex session with a concrete startup path.

package/packages/ahe-codex/.codex/skills/ahe-harness-checker/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ahe-harness-checker
+description: Internal AHE harness validation and repair protocol for checking artifacts after generation or maintenance.
+---
+
+# AHE Harness Checker
+
+**CRITICAL: This is an internal AHE workflow skill, not a user-facing command.**
+
+Do not treat `$ahe-harness-checker` as a user command.
+Use it when `ahe-think`, `ahe-harness`, or `ahe-new` decides that generated or maintained harness files must be validated and repaired.
+
+## Protocol and Purpose
+
+Your primary purpose is to validate and repair generated harness artifacts after bootstrap/initialization or harness maintenance work.
+
+**CRITICAL MANDATORY STEP**: You MUST read and review the actual contents of all harness files before attempting to validate or repair them. You have explicit authority and the obligation to inspect the contents of the following key files:
+- `AGENTS.md`
+- `docs/product.md`
+- `docs/INSTRUCTIONS.md`
+- `feature-list.json`
+- `progress.md`
+- `session-handoff.md`
+- `init.sh`
+- `status.json`
+
+## Detectable Failure Classes
+
+You must detect and classify the following issues during your validation check:
+
+1. **Missing Required File**: A key harness file is completely absent from the workspace.
+2. **Empty Required File**: A key harness file exists but contains zero bytes or only whitespace.
+3. **Invalid Tracker JSON**: `feature-list.json` or `status.json` contains malformed JSON or violates the required schema.
+4. **Wrong Filename Casing**: A harness file uses an incorrect case (e.g., `PROGRESS.md` instead of `progress.md`). Note: `AGENTS.md` is the only file that must remain uppercase.
+5. **Forbidden AGENTS.md Edits**: Edits to `AGENTS.md` have occurred outside the allowed changeable section / `PROJECT_PURPOSE`.
+6. **Missing Product Docs**: `docs/product.md` is absent or does not contain valid specification text.
+7. **Template/Bootstrap Drift**: Workspace files contradict the intended layout or templates defined by AHE.
+
+## Repair Behavior
+
+- **Direct Fix**: If the detected failure is deterministic and local (e.g., wrong casing, missing template placeholders, local syntax drift, malformed but fixable JSON), fix the issue directly in the workspace without prompting.
+- **Escalation**: If the issue is ambiguous or requires understanding the user's intent (e.g., missing project purpose, contradictory requirements, or major data loss in tracker files), escalate the issue by handing off to `ahe-converse` to query the user for clarification.
+
+## Sequence Completion
+
+Once all detected issues have been either directly fixed or safely escalated, summarize the fixes applied and exit. Do not proceed to other workflow steps on your own.

package/{.codex/skills/ahe-init → packages/ahe-codex/.codex/skills/ahe-new}/SKILL.md

@@ -1,33 +1,41 @@
 ---
-name: ahe-init
+name: ahe-new
 description: Initialize AHE in the current workspace and create the base harness files.
 ---
 
-# AHE Init
+# AHE New
 
-Use this skill when the user invokes `$ahe-init`.
+Use this skill when the user invokes `$ahe-new`.
 
-## Command Workflow: ahe-init
+## Command Workflow: new
 
 ### Workspace Inspection
 
 - Read `AGENTS.md` if it already exists.
-- Read `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` when they exist.
-- Read `docs/ARCHITECTURE.md` if it exists, but treat it as an optional document.
-- Read existing workspace-root harness files that may be copied from templates, including `PROGRESS.md`, `SESSION-HANDOFF.md`, `feature-list.json`, and `init.sh`.
-- Read `.ahe/process_status.json` when it exists.
-- Treat `AGENTS.md`, `docs/PRODUCT.md`, `docs/INSTRUCTIONS.md`, `PROGRESS.md`, `SESSION-HANDOFF.md`, `feature-list.json`, `init.sh`, and `.ahe/process_status.json` as AHE-managed harness files for restart-scope decisions.
+- Read all `docs/*.md` files when they exist. Treat every docs file as
+  supporting project context, even when `AGENTS.md` does not name it directly.
+- Especially read `docs/product.md` and
+  `docs/product{number}.md` files when present because they explain what to do.
+- Treat `docs/product.md` as overview context and numbered
+  `docs/product{number}.md` files as ordered product stages.
+- Ignore non-numeric product docs such as `docs/product-alpha.md` for stage
+  ordering.
+- Read existing workspace-root harness files that may be copied from templates, including `progress.md`, `session-handoff.md`, `feature-list.json`, and `init.sh`.
+- Read `status.json` when it exists.
+- Treat `AGENTS.md`, `docs/product.md`, `docs/INSTRUCTIONS.md`, `progress.md`, `session-handoff.md`, `feature-list.json`, `init.sh`, and `status.json` as AHE-managed harness files for restart-scope decisions.
 
 ### Sequential Conversation Flow
 
-- Treat exact `ahe init` as a possible new start request.
+- Treat exact `ahe new` as a possible new start request.
 - If no AHE-managed harness files exist, start initialization normally without asking a restart-scope question.
 - If any AHE-managed harness file already exists, read the existing files first.
 - When existing harness files are present, summarize the current project purpose and product specification state, then ask what restart scope the user wants before removing, overwriting, or refreshing existing harness files.
 - Do not remove, overwrite, or refresh existing harness files until the restart scope is clear.
 - Interpret the restart scope from the user's free-form answer; examples are guidance only and must not limit valid answers.
 - If the answer says `purpose`, full restart, or equivalent, `purpose` means restart the whole harness from the project purpose.
-- If the answer says `product`, product spec, or equivalent, `product` means preserve the project purpose in `AGENTS.md` and restart product specification work in `docs/PRODUCT.md`.
+- If the answer says `product`, product spec, or equivalent, `product` means preserve the project purpose in `AGENTS.md` and restart product specification work in `docs/product.md`.
+- If the answer names staged product work, restart only the named product stage
+  files unless the user also requests the overview product spec.
 - If the answer names a narrower custom scope, preserve unrelated harness files and restart only the named scope.
 - If `AGENTS.md` already exists, ask the user whether the current `AGENTS.md` is right.
 - If the current `AGENTS.md` is not right or does not exist, ask for the purpose of this project.
@@ -35,36 +43,39 @@ Use this skill when the user invokes `$ahe-init`.
 - Update only the `PROJECT_PURPOSE` portion of `AGENTS.md`.
 - Keep `AGENTS.md` limited to the project purpose and base agent settings.
 - Do not put product specification details in `AGENTS.md`.
-- Send product behavior, scope, requirements, success criteria, and workflow details to `ahe-harness` so they are written in `docs/PRODUCT.md` first.
-- Generating an empty `feature-list.json` from a template is allowed, but do not write concrete feature items until `docs/PRODUCT.md` is populated.
+- Send product behavior, scope, requirements, success criteria, and workflow details to `ahe-harness` so they are written in `docs/product.md` first.
+- Generating an empty `feature-list.json` from a template is allowed, but do not write concrete feature items until `docs/product.md` is populated.
+- When staged product docs exist, let `ahe-harness` derive concrete feature
+  items from only the active product stage.
 - Ask whether the project language is Python using a Codex-supported structured response request with meaningful options and custom input.
 - If the user answers that the project language is not Python, ask again: "Which language do you use?".
 - Do not create backup copies of the replaced harness files.
 - When a restart scope replaces prior harness history, summarize the replaced harness history in the refreshed tracking artifacts instead of creating backups.
-- Remove the previous `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` when the chosen restart scope includes product specification.
-- Remove the previous `PROGRESS.md` when the chosen restart scope includes progress tracking.
-- Remove the previous `SESSION-HANDOFF.md` when the chosen restart scope includes session handoff.
+- Remove the previous `docs/product.md` and `docs/INSTRUCTIONS.md` when the chosen restart scope includes product specification.
+- Remove the previous `progress.md` when the chosen restart scope includes progress tracking.
+- Remove the previous `session-handoff.md` when the chosen restart scope includes session handoff.
 - Remove the previous `feature-list.json` when the chosen restart scope includes feature tracking.
 - Remove only the files included in the chosen restart scope before continuing the new start flow.
 - Find all template files under `.codex/ahe-shared/templates/`.
-- Ignore `AGENTS.md` and `PRODUCT.md` when copying template files.
+- Ignore `AGENTS.md` and `product.md` when copying template files.
 - Before copying a template file into the workspace root, check whether the target file already exists and ask for explicit overwrite confirmation when needed.
-- Execute the following two steps sequentially, updating the progress status (`current_step` in `.ahe/process_status.json`):
-  1. complete the embedded init setup work (status: "ahe-init")
+- Execute the following three steps sequentially, updating the progress status (`current_step` in `status.json`):
+  1. complete the embedded init setup work (status: "new")
   2. call "ahe-harness" (status: "ahe-harness")
+  3. call "ahe-harness-checker" (status: "ahe-harness-checker")
 
 ### Harness Generation
 
 - Create or refresh `AGENTS.md`.
 - Create or refresh missing workspace-root harness files from `.codex/ahe-shared/templates/`, converting markdown filenames to uppercase when needed.
-- Create `.ahe/process_status.json` and update it at each step to indicate the active status from the three-step sequence.
+- Create `status.json` and update it at each step to indicate the active status from the three-step sequence.
 - Create missing harness files from `.codex/ahe-shared/templates/`.
 - Keep the generated files aligned with the installed shared templates.
 - Only allow additions/removals/edits to `docs/INSTRUCTIONS.md` inside `## CAN CHANGE INSTRUCTIONS`; preserve `## MUST NOT CHANGE INSTRUCTIONS`.
 
 ## Clarification Rule
 
-When the next setup step is not clear, follow the `ahe-thinker` protocol first. If `ahe-thinker` finds missing information, follow the `ahe-conversator` protocol. Ask again recursively using a Codex-supported structured response request, provide 2-3 meaningful mutually exclusive options when possible, and allow custom input when predefined options are not enough.
+When the next setup step is not clear, follow the `ahe-think` protocol first. If `ahe-think` finds missing information, follow the `ahe-converse` protocol. Ask again recursively using a Codex-supported structured response request, provide 2-3 meaningful mutually exclusive options when possible, and allow custom input when predefined options are not enough.
 
 ### User Response Target
 

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

@@ -0,0 +1,119 @@
+---
+name: ahe-overview
+description: Provides an overview of Awesome Harness Engineering (AHE), its architecture, and available commands.
+---
+
+# Awesome Harness Engineering (AHE) Overview
+
+AHE is a framework and set of managed skills designed to maintain project harnesses (documentation, requirements, testing) and route work systematically through AI agents.
+
+## Public Entrypoints
+
+You interact with AHE using the following user-facing commands:
+- **`ahe` / `ahe <query>`**: Automatically inspects the harness state and routes to the correct next step. For example: `ahe`, `ahe update product spec`, or `ahe compress`.
+- **`ahe new` / `ahe-new`**: Starts the initialization or reset flow for a workspace.
+- **`ahe fix` / `ahe fix <query>`**: Starts fix planning when an error occurs or user intent shifts, skipping normal continuation. For example: `ahe fix stale tests`.
+- **`ahe ship`**: In Codex, saves the latest Plan Mode plan into `.plans/{plan_name}.md` without automatically executing it. In Antigravity, refreshes and executes exactly one plan from `.plans/`.
+- **`ahe-git`**: In Antigravity, safely pulls and commits all nested repositories.
+
+## Thinker-Centered Routing Model
+
+AHE operates through a central decision layer: **`ahe-think`**. This internal agent determines the current state of the harness and delegates tasks to specialized sub-skills:
+- **`ahe-harness`**: Builds and maintains product docs, instructions, and tracking state.
+- **`ahe-review`**: Explores the codebase and reads files to understand context.
+- **`ahe-converse`**: Pauses and asks the user for clarification when blocked.
+- **`ahe-feature`**: Sizes and extracts new features from product documentation.
+- **`ahe-solve`**: Solves or plans specific features.
+- **`ahe-compress`**: Handles artifact size reduction when the harness grows too large.
+
+These internal sub-skills are not user-facing commands.
+
+## Main Flows
+
+### 1. `ahe` (Continuous Execution)
+```mermaid
+graph TD;
+    User[User: ahe] --> Hook[ahe-hook.js]
+    Hook --> Think[ahe-think]
+    Think --> State{State?}
+    State -- Harness Missing --> New[ahe-new]
+    State -- Building Features --> Solve[ahe-solve]
+    State -- Need Context --> Review[ahe-review]
+    State -- Blocked --> Converse[ahe-converse]
+    State -- Harness Work --> Harness[ahe-harness]
+    State -- Compress --> Compress[ahe-compress]
+```
+
+### 2. `ahe new` (Initialization)
+```mermaid
+graph TD;
+    User[User: ahe new] --> Hook[ahe-hook.js]
+    Hook --> Think[ahe-think]
+    Think --> New[ahe-new]
+    New --> Scope{Check Scope}
+    Scope -- Clarification --> Converse[ahe-converse]
+    Scope -- Done --> Harness[ahe-harness]
+```
+
+### 3. `ahe fix` (Fix Planning)
+```mermaid
+graph TD;
+    User[User: ahe fix] --> Hook[ahe-hook.js]
+    Hook --> Think[ahe-think]
+    Think --> Fix[ahe-fix]
+    Fix --> Clarify{Clear?}
+    Clarify -- No --> Converse[ahe-converse]
+    Clarify -- Yes --> Write[Write Fix Plan]
+```
+
+### 4. `ahe ship` (Export / Execute Plan)
+
+**In Codex (Export):**
+```mermaid
+graph TD;
+    User[User: ahe ship] --> Hook[ahe-hook.js]
+    Hook --> Think[ahe-think]
+    Think --> Ship[ahe-ship]
+    Ship --> Write[Write .plans/*.md]
+```
+
+**In Antigravity (Execute):**
+```mermaid
+graph TD;
+    User[User: ahe-ship] --> Antigravity
+    Antigravity --> ShipSkill[ahe-ship skill]
+    ShipSkill --> Read[Read .plans/*.md]
+    Read --> Execute[Execute Plan]
+```
+
+### 5. `ahe-git` (Repository Sync)
+
+**In Antigravity:**
+```mermaid
+graph TD;
+    User[User: ahe-git] --> Antigravity
+    Antigravity --> GitSkill[ahe-git skill]
+    GitSkill --> Pull[Pull Remote]
+    Pull --> Commit[Commit Local Changes]
+```
+
+## Example of How to Use
+
+### Harness Engineering
+1. `ahe new`
+(initialize the workspace)
+2. `ahe update product spec`
+(update product documentation)
+3. `ahe add dashboard export feature`
+(implement a specific feature)
+
+### ahe-ship in Codex and Antigravity
+after planning in codex
+1. `ahe-ship` in codex
+(save the plan to .plans)
+2. `ahe-ship` in antigravity
+(implement one of plans in .plans)
+
+### ahe-git
+1. `ahe-git` in antigravity
+(safely pull and commit all nested repositories)

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

@@ -0,0 +1,43 @@
+---
+name: ahe-review
+description: Internal AHE review workflow for understanding repo code, harness files, and CodeGraph context before another agent acts.
+---
+
+# AHE Reviewer
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-review` as a user command.
+Use it when `ahe-think` or another worker needs evidence from code or harness
+state before deciding what to do next.
+
+## Review Scope
+
+- Inspect repo code, harness files, verification history, and feature progress.
+- If `.codegraph/` exists, prefer `.codegraph` or CodeGraph-backed review
+  context when available.
+- Check `AGENTS.md`, all existing `docs/*.md` files, `feature-list.json`,
+  `progress.md`, `session-handoff.md`, and `docs/todo.md` when the question is
+  about harness state.
+- Treat `docs/product.md` as overview context and `docs/product{number}.md`
+  files as ordered product stages when reviewing product or feature drift.
+- Ignore non-numeric product docs such as `docs/product-alpha.md` for stage
+  ordering.
+- Verify that `feature-list.json` reflects only the active product stage, not
+  future product stages.
+- Especially read `docs/product.md` and
+  `docs/product{number}.md` files when present because they explain what to do.
+
+## Handoffs
+
+- Report findings back to `ahe-think` by default.
+- Call `ahe-harness` directly when review finds harness drift, stale tracking,
+  or product doc / feature-list mismatches.
+- Call `ahe-converse` only when the missing information must come from the
+  user.
+
+## Output
+
+- State what was reviewed.
+- State the relevant evidence or mismatch.
+- State the recommended next agent.

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

@@ -0,0 +1,58 @@
+---
+name: ahe-ship
+description: Use when the user explicitly invokes `$ship`, `ship`, or `ahe ship` after a plan has just been created and wants Codex to save it.
+---
+
+# AHE Ship
+
+`ship` is a user-facing AHE command, but it is independent from the AHE
+agent network.
+
+Use this skill only to export a completed Codex Plan Mode plan and save it to `.plans/`.
+Do not route through `think`. You must not call `harness`, `solve`, or any
+other AHE workflow agent.
+
+## Workflow
+
+1. Detect if the current conversation is still in Plan Mode.
+2. If Plan Mode is active, the Codex host must exit Plan Mode and replay the command.
+3. Outside Plan Mode, locate the most recent completed `<proposed_plan>` already visible in the
+   current conversation.
+4. If the latest plan is clear, use it directly. Do not ask the user to paste
+   the plan again.
+5. Derive `plan_name` from the plan title. Use a short lowercase hyphenated
+   name. If no title or safe name can be derived, ask one focused question for
+   the plan name.
+6. Build a compact markdown handoff with these sections:
+   - `# {Plan Title}`
+   - `## Handoff Summary`
+   - `## Source Plan`
+   - `## Execution Context`
+   - `## Assumptions`
+   - `## Constraints`
+   - `## Verification Plan`
+   - `## Risks and Open Questions`
+   - `## Instructions for Next Agent`
+7. Write the final markdown through `scripts/write_plan.py`.
+8. Report that the plan was saved to `.plans/{plan_name}.md` and stop.
+
+## Missing Context
+
+- If there is no recent `<proposed_plan>` in context, ask the user for the plan
+  text instead of inventing one.
+- If the target file already exists, ask whether to overwrite it or choose a
+  distinct plan name.
+
+## Writer Script
+
+Use:
+
+```bash
+python .codex/skills/ship/scripts/write_plan.py \
+  --root "$PWD" \
+  --plan-name "Plan Title" \
+  < /tmp/ahe-plan.md
+```
+
+Add `--overwrite` only after the user explicitly confirms replacing an existing
+file.

package/packages/ahe-codex/.codex/skills/ahe-ship/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AHE Ship"
+  short_description: "Export Codex plans to .plans handoff files"
+  default_prompt: "Use $ship to export the latest Codex Plan Mode plan into a .plans handoff file."