@ksuchoi216/ahe 0.1.10 → 0.1.12

package/README.md

@@ -1,30 +1,30 @@
 # Awesome Harness Engineering (AHE)
 
 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`.
+public entrypoints stay small: use exact `ahe` for bootstrap or continuation,
+`ahe ship` to save the latest plan (in Codex) or refresh and execute a saved plan (in Antigravity),
+and `ahe git` for safe git orchestration. Use `ahe <query>` or `<query> ahe`
+for explicit AHE requests such as `ahe update product spec` or `ahe stale tests`.
+For a detailed in-chat explanation of the AHE architecture and workflows, use the helper `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.
+Here are intuitive flow examples for the primary AHE commands. The public work-routing surface is `ahe`, `ahe-ship`, and `ahe-git`; conversational queries such as `ahe add dashboard export feature` are routed through `ahe`.
 
-### `ahe new` Flow
+### `ahe` Bootstrap 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.
+2. **ahe calling**: You type `ahe` or `ahe new` in Codex.
+3. **Initialization**: `ahe-think` detects the missing harness, calls internal `ahe-new`, and then hands off to `ahe-harness` to sync 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
+### `ahe` Follow-Up 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.
+2. **ahe query**: You type `ahe stale tests` or another explicit follow-up request in Codex.
+3. **Normal Routing**: `ahe-think` treats that request as ordinary AHE work and routes it to the right internal worker.
 
 ### General `ahe` Flow
 1. **Ongoing Work**: You need to implement a feature or update docs.
@@ -36,17 +36,16 @@ Here are intuitive flow examples for the primary AHE commands. While `ahe`, `ahe
 | Skill | Role |
 | --- | --- |
 | `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-new` | Internal bootstrap workflow that `ahe-think` calls when the workspace has no usable harness yet. |
 | `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-harness` | Harness-management agent for product docs, instructions, feature tracking, and todo sync. |
 | `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-overview` | Helper skill that explains the AHE concept, entrypoints, and main workflows in chat. |
 | `ahe-ship` | In Codex: saves Plan Mode plan to `.plans/`. In Antigravity: refreshes and executes exactly one plan from `.plans/`. |
+| `ahe-git` | Independent git orchestration workflow for safe fetch, review, and commit handling. |
 
 ## Routing Model
 
@@ -54,9 +53,9 @@ The Codex-side model is centered but flexible:
 
 - 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`
+- `ahe-think` may call internal `ahe-new` when the workspace needs bootstrap or restart handling
 - 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
+- exact `ahe git` -> independent git workflow
 
 - `ahe-think` is the center of judgment.
 - Worker agents can call each other directly when that is the logical next
@@ -69,16 +68,11 @@ The Codex-side model is centered but flexible:
 - `ahe`
 - `ahe new`
 - `ahe ship`
-- `ahe fix`
-- `ahe fix stale tests`
-- `stale tests ahe fix`
-- `ahe compress`
-- `compress ahe`
+- `ahe stale tests`
 - `ahe update product spec`
 - `ahe add dashboard export feature`
 
-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.
+Only exact `ahe`, exact `ahe ship`, exact `ahe-ship`, exact `$ahe-ship`,
+exact `ahe git`, exact `ahe-git`, exact `$ahe-git`, `ahe-overview`,
+`ahe <query>`, and `<query> ahe` activate the hook. Middle mentions that do
+not fit those command shapes do not.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ksuchoi216/ahe",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Codex chat workflow skill installer for Awesome Harness Engineering",
   "publishConfig": {
     "access": "public"

package/packages/ahe-antigravity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahe/antigravity",
-  "version": "0.1.8",
+  "version": "0.1.12",
   "description": "Awesome Harness Engineering Antigravity skill package",
   "author": "ksuchoi216",
   "license": "MIT"

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

@@ -37,7 +37,6 @@ const COMMON_ROUTING_LINES = [
   "   - Check `feature-list.json` as a derived tracker.",
   "   - Check `progress.md`.",
   "   - Use `ahe-think` as the internal decision layer before choosing the next action.",
-  "   - Before reading large harness files wholesale, let `ahe-think` run the `ahe-compress` size detector and test-overlap detector. Call `ahe-compress` if compression is required.",
   "",
   "2. Review code through CodeGraph when available:",
   "   - Prefer CodeGraph MCP or CodeGraph exploration for code review and impact context after the preflight command succeeds.",
@@ -51,14 +50,14 @@ 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:",
+  "The user sent an AHE continuation request. Operate as the Awesome Harness Engineering router:",
   "",
   ...CODEGRAPH_PREFLIGHT_LINES,
   ...COMMON_ROUTING_LINES,
   "",
   "4. Decide the next AHE workflow with `ahe-think`:",
-  "   - Automatically invoke `@ahe-harness-manager` before `ahe-think` chooses the next workflow if the harness state needs supervision (missing/invalid harness files, unfinished features, completed trackers with possible next work, or code/docs/tracker mismatch).",
   "   - Route through `ahe-think` first.",
+  "   - let `ahe-think` decide whether `@ahe-harness-manager` supervision is needed before choosing the next workflow.",
   "   - If no harness files exist, route to `ahe-new`.",
   "   - 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.",
@@ -67,8 +66,9 @@ const AHE_PROGRESS_DIRECTIVE = [
   "   - 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-review` when repo or code understanding is needed.",
+  "   - Call `ahe-clean` when stale completed tracking history makes the current next step harder to see.",
   "   - Call `ahe-converse` 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-harness` when product docs, instructions, tracking, or todo sync must change.",
   "   - Call `ahe-harness-checker` to validate and repair generated harness artifacts after bootstrap or harness maintenance work.",
   "   - Call `ahe-feature` to size and extract new features.",
   "   - Call `ahe-solve` when the next job is solving or planning a feature.",
@@ -79,27 +79,6 @@ const AHE_PROGRESS_DIRECTIVE = [
   "   - Continue automatically after classification.",
 ];
 
-const AHE_NEW_DIRECTIVE = [
-  AHE_DIRECTIVE_MARKER,
-  "AHE automatic operation activated.",
-  "",
-  "The user sent the exact AHE new command. Treat this as a possible new start request:",
-  "",
-  ...CODEGRAPH_PREFLIGHT_LINES,
-  "2. Route to `ahe-think` first.",
-  "3. `ahe-think` must route to `ahe-new`.",
-  "4. Automatically invoke `@ahe-harness-manager` only when existing harness files need review before determining the restart scope.",
-  "5. If no AHE-managed harness files exist, start initialization normally.",
-  "6. 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.",
-  "7. Do not remove, overwrite, or refresh existing harness files before the user answers the restart-scope question.",
-  "8. If the chosen restart scope replaces prior harness history, summarize that replaced state in the refreshed tracking artifacts instead of creating backup copies.",
-  "9. Interpret the restart scope from the user's free-form answer; examples like `purpose` and `product` are not a closed list.",
-  "10. Product/instructions specification details belong in `docs/product.md` and `docs/INSTRUCTIONS.md`, not `AGENTS.md`.",
-  "11. After setup, call `ahe-harness` to build the initial product, instructions, and tracking state, and end with `ahe-harness-checker` validation/fix before the harness is considered usable.",
-  "12. Use `ahe-think` before clarification when the next setup step is uncertain.",
-  "13. If clarification is needed, call `ahe-converse` for the exact missing detail.",
-].join("\n");
-
 const AHE_SHIP_DIRECTIVE = [
   AHE_DIRECTIVE_MARKER,
   "AHE plan export activated.",
@@ -119,25 +98,6 @@ const AHE_SHIP_DIRECTIVE = [
   "Do not run the normal AHE harness workflow.",
 ].join("\n");
 
-const AHE_FIX_DIRECTIVE = [
-  AHE_DIRECTIVE_MARKER,
-  "AHE fix planning activated.",
-  "",
-  "The user invoked `ahe-fix`.",
-  "",
-  ...CODEGRAPH_PREFLIGHT_LINES,
-  "2. Route to `ahe-think` first.",
-  "3. `ahe-think` must immediately call the `ahe-fix` skill.",
-  "4. Automatically invoke `@ahe-harness-manager` only when the fix target may conflict with current harness state.",
-  "5. Understand the user's error, bug, mismatch, or intended change from the current conversation and repository context.",
-  "6. Create a concrete fix plan for fixing errors or following the user's intention when it differs from normal AHE continuation.",
-  "7. If the fix goal, scope, or success criteria are unclear, call `ahe-converse` and ask one focused question before writing the plan.",
-  "8. Derive `plan_name` from the fix goal and create `.plans/{plan_name}.md`.",
-  "9. Use `.codex/skills/ahe-fix/scripts/write_fix_plan.py` to write the final markdown.",
-  "",
-  "Do not run the normal AHE harness workflow.",
-].join("\n");
-
 const AHE_GIT_DIRECTIVE = [
   AHE_DIRECTIVE_MARKER,
   "AHE Git activated.",
@@ -172,21 +132,11 @@ function isExactAheCommand(prompt) {
   return normalizePrompt(prompt) === "ahe";
 }
 
-function isExactAheNewCommand(prompt) {
-  const normalizedPrompt = normalizePrompt(prompt);
-  return normalizedPrompt === "ahe-new" || normalizedPrompt === "ahe new";
-}
-
 function isExactAheShipCommand(prompt) {
   const normalizedPrompt = normalizePrompt(prompt);
   return normalizedPrompt === "ahe-ship" || normalizedPrompt === "ahe ship";
 }
 
-function isExactAheFixCommand(prompt) {
-  const normalizedPrompt = normalizePrompt(prompt);
-  return normalizedPrompt === "ahe-fix" || normalizedPrompt === "ahe fix";
-}
-
 function isExactAheGitCommand(prompt) {
   const normalizedPrompt = normalizePrompt(prompt);
   return normalizedPrompt === "ahe-git" || normalizedPrompt === "ahe git";
@@ -196,6 +146,21 @@ function isExactAheOverviewCommand(prompt) {
   return normalizePrompt(prompt) === "ahe-overview";
 }
 
+function isAheQueryCommand(prompt) {
+  const normalizedPrompt = normalizePrompt(prompt);
+
+  if (
+    isExactAheCommand(prompt) ||
+    isExactAheShipCommand(prompt) ||
+    isExactAheGitCommand(prompt) ||
+    isExactAheOverviewCommand(prompt)
+  ) {
+    return false;
+  }
+
+  return /^ahe .+/.test(normalizedPrompt) || /^.+ ahe$/.test(normalizedPrompt);
+}
+
 async function main() {
   let raw = "";
   process.stdin.setEncoding("utf8");
@@ -231,12 +196,12 @@ async function main() {
       return;
     }
 
-    if (isExactAheNewCommand(parsed.prompt)) {
+    if (isAheQueryCommand(parsed.prompt)) {
       process.stdout.write(
         JSON.stringify({
           hookSpecificOutput: {
             hookEventName: "UserPromptSubmit",
-            additionalContext: AHE_NEW_DIRECTIVE,
+            additionalContext: AHE_PROGRESS_DIRECTIVE.join("\n"),
           },
         }) + "\n"
       );
@@ -255,18 +220,6 @@ async function main() {
       return;
     }
 
-    if (isExactAheFixCommand(parsed.prompt)) {
-      process.stdout.write(
-        JSON.stringify({
-          hookSpecificOutput: {
-            hookEventName: "UserPromptSubmit",
-            additionalContext: AHE_FIX_DIRECTIVE,
-          },
-        }) + "\n"
-      );
-      return;
-    }
-
     if (isExactAheGitCommand(parsed.prompt)) {
       process.stdout.write(
         JSON.stringify({

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

@@ -14,7 +14,9 @@ work in the current workspace.
 - `ahe <query>` and `<query> ahe` mean continue AHE work with the user's
   explicit query.
 - `ahe` must route through `ahe-think` as the central decision layer.
-- `ahe` must not replace the dedicated `ahe-new`, `ahe-fix`, or `ahe-ship`
+- `ahe-think` may call `ahe-new` internally when the workspace has no usable
+  harness yet.
+- `ahe` must stay separate from the dedicated `ahe-ship` and `ahe-git`
   workflows when the user's prompt matches those command contracts.
 
 ## Routing
@@ -30,5 +32,5 @@ work in the current workspace.
 ## Scope
 
 - Use this skill for ongoing harness work, product updates, and explicit AHE
-  requests such as `ahe compress`.
-- Do not use this skill for standalone fix-plan export or ship-plan export.
+  requests such as `ahe update product spec` or `ahe fix stale tests`.
+- Do not use this skill for standalone ship-plan export or git orchestration.

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

@@ -0,0 +1,67 @@
+---
+name: ahe-clean
+description: Use when valid harness tracking artifacts contain too much stale completed history and the current next step is harder to see.
+---
+
+# AHE Clean
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-clean` as a user command.
+Use it when `ahe-think` decides that completed tracker history should be compacted
+to restore clarity for current work.
+
+## Purpose
+
+- Reduce stale completed history in `feature-list.json`.
+- Reduce stale completed history in `session-handoff.md`.
+- Keep the active work legible without turning tracking artifacts into archives.
+- Follow the tracking-policy contract owned by `ahe-harness`.
+
+## Scope
+
+- Read only the context needed to judge relevance:
+  - `docs/product.md`
+  - active `docs/product{number}.md` stage when present
+  - `feature-list.json`
+  - `progress.md`
+  - `session-handoff.md`
+- Do not become a general harness editor.
+- Do not rewrite `docs/product.md` or `docs/INSTRUCTIONS.md`.
+- Touch `progress.md` only when the active-feature or latest-completed-work text
+  must stay consistent after cleanup.
+
+## Cleanup Rules For `feature-list.json`
+
+- Preserve all non-`done` features.
+- Preserve the active feature from `progress.md`.
+- Preserve completed dependency features needed for the active feature.
+- Preserve completed features still needed to understand the active product
+  stage or the current next work.
+- Remove `done` features that are not relevant under those rules.
+- Replace removed completed history with one stable summary feature entry.
+- The summary entry must stay `status: "done"`.
+- The summary entry must explain that older unrelated completed work was
+  compacted.
+- The summary entry must record a covered feature ID span or covered count.
+- The summary entry must be updated in place on future cleanup runs instead of
+  duplicating summaries.
+
+## Cleanup Rules For `session-handoff.md`
+
+- In `## Last Completed Work`, preserve only:
+  - items directly related to the active feature;
+  - items needed to explain current harness state;
+  - items needed to justify the next recommended step.
+- Remove unrelated older completed bullets.
+- Replace removed bullets with one compact summary bullet describing that older
+  unrelated completed work was condensed.
+- Keep `## Current Product Context`, `## Important Files`,
+  `## Next Recommended Action`, and `## Verification Status` governed by the
+  normal handoff rules; do not broadly compress them here.
+
+## Completion
+
+- Keep `feature-list.json` valid JSON.
+- Keep `session-handoff.md` focused on the next-session startup path.
+- Preserve current-work clarity rather than long-form history.

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

@@ -1,6 +1,6 @@
 ---
 name: ahe-harness
-description: Internal AHE harness workflow for managing product docs, instructions, feature tracking, session artifacts, todo sync, and compression-aware maintenance.
+description: Internal AHE harness workflow for managing product docs, instructions, feature tracking, session artifacts, and todo sync.
 ---
 
 # AHE Harness
@@ -9,7 +9,7 @@ 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.
+be created, updated, or reconciled.
 
 ## Command Workflow: harness
 
@@ -54,12 +54,12 @@ be created, updated, reconciled, or compressed. It remains responsible for track
 - 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.
+- Treat `feature-list.json` and `session-handoff.md` as current-work artifacts,
+  not archival logs; they are current-work artifacts, and unrelated completed
+  history may be compacted when it no longer helps the active work.
+- unrelated completed feature entries may be compacted.
+- unrelated completed handoff bullets may be compacted.
+- current-work-relevant completed context must remain.
 - 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
@@ -70,10 +70,11 @@ be created, updated, reconciled, or compressed. It remains responsible for track
 ### 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 tracking artifacts concise enough that the current next step is easy to
+  identify.
 - 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.
 

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

@@ -5,7 +5,10 @@ description: Initialize AHE in the current workspace and create the base harness
 
 # AHE New
 
-Use this skill when the user invokes `$ahe-new`.
+This is an internal AHE workflow skill, not a user-facing command.
+
+Use this skill when `ahe-think` decides the workspace needs bootstrap or
+restart handling.
 
 ## Command Workflow: new
 
@@ -26,7 +29,8 @@ Use this skill when the user invokes `$ahe-new`.
 
 ### Sequential Conversation Flow
 
-- Treat exact `ahe new` as a possible new start request.
+- Treat new-start or reset intent arriving through the normal `ahe` path 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.

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

@@ -10,12 +10,12 @@ AHE is a framework and set of managed skills designed to maintain project harnes
 ## 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` / `ahe <query>` / `<query> ahe`**: Automatically inspects the harness state and routes to the correct next step. This same entrypoint covers new-workspace bootstrap, normal continuation, and user-directed follow-up such as `ahe update product spec` or `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.
 
+`ahe-overview` remains an explanation helper, not part of the normal work-routing surface.
+
 ## 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:
@@ -24,7 +24,7 @@ AHE operates through a central decision layer: **`ahe-think`**. This internal ag
 - **`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.
+- **`ahe-new`**: Internal bootstrap worker used when `ahe-think` detects that the workspace has no usable harness yet.
 
 These internal sub-skills are not user-facing commands.
 
@@ -41,32 +41,9 @@ graph TD;
     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)
+### 2. `ahe ship` (Export / Execute Plan)
 
 **In Codex (Export):**
 ```mermaid
@@ -86,7 +63,7 @@ graph TD;
     Read --> Execute[Execute Plan]
 ```
 
-### 5. `ahe-git` (Repository Sync)
+### 3. `ahe-git` (Repository Sync)
 
 **In Antigravity:**
 ```mermaid
@@ -100,8 +77,8 @@ graph TD;
 ## Example of How to Use
 
 ### Harness Engineering
-1. `ahe new`
-(initialize the workspace)
+1. `ahe`
+(in a workspace with no harness, `ahe-think` routes internally to `ahe-new`)
 2. `ahe update product spec`
 (update product documentation)
 3. `ahe add dashboard export feature`

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

@@ -13,35 +13,24 @@ Use it as the central decision layer for AHE work.
 ## Purpose
 
 - Judge what is missing before another agent acts.
+- Optionally invoke `@ahe-harness-manager` as a pre-routing supervisor when the
+  harness state itself is unclear or contradictory.
+- Optionally invoke `ahe-clean` when tracking artifacts are valid but noisy
+  enough that stale completed history makes the current next step harder to see.
 - 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`,
+- Choose the next internal agent: `ahe-clean`, `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`.
+- New-start intent such as `ahe new` arrives through the normal `ahe` query
+  path, and `ahe-think` decides whether to call `ahe-new`.
 - 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.
@@ -63,11 +52,29 @@ Use it as the central decision layer for AHE work.
 - 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.
+- Use `@ahe-harness-manager` as an optional pre-routing supervisor when:
+  - missing or invalid harness artifacts;
+  - `docs/*.md`, `feature-list.json`, `progress.md`, `session-handoff.md`, and
+    code appear to disagree;
+  - all tracked features are done but likely next work exists;
+  - the harness state is ambiguous enough that `ahe-review` vs `ahe-harness` vs `ahe-converse` is not yet clear.
+- Keep `@ahe-harness-manager` advisory. It reports findings back to
+  `ahe-think`; it does not replace `ahe-think` as the decision layer.
+- Use `ahe-clean` when the harness is valid but noisy, including:
+  - too many `done` entries in `feature-list.json` that are unrelated to active work;
+  - too many stale bullets in `session-handoff.md`;
+  - current next work is harder to identify because old completed detail dominates the trackers.
+- Treat `ahe-clean` as distinct from `@ahe-harness-manager` escalation:
+  `ahe-clean` handles valid but noisy tracking state, while
+  `@ahe-harness-manager` handles missing, invalid, mismatched, or otherwise
+  ambiguous harness state.
 - 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 updating harness artifacts, product docs, feature tracking, or
+  todo sync, call `ahe-harness`.
+- If the need is compacting stale completed tracking history without changing
+  product or instruction content, call `ahe-clean`.
 - If the need is solving or decomposing feature work, call `ahe-solve`.
 
 ## Interaction Model
@@ -75,6 +82,8 @@ Use it as the central decision layer for AHE work.
 - `ahe-think` is centered, but direct worker-to-worker calls are allowed when
   they are the obvious next step.
 - Typical loops:
+  - `ahe-think -> @ahe-harness-manager -> ahe-think`
+  - `ahe-think -> ahe-clean -> ahe-think`
   - `ahe-think -> ahe-review -> ahe-think`
   - `ahe-think -> ahe-harness -> ahe-think`
   - `ahe-think -> ahe-converse -> ahe-think`
@@ -93,7 +102,9 @@ Use it as the central decision layer for AHE work.
 
 - Use `ahe-review` for review-first requests.
 - Use `ahe-harness` for product, instructions, progress, feature-list, todo, or
-  compression maintenance.
+  tracker-policy maintenance.
+- Use `ahe-clean` for reducing stale completed history in `feature-list.json`
+  and `session-handoff.md`.
 - Use `ahe-solve` for feature implementation planning or execution work.
 - Use `ahe-converse` when no safe next step exists without user input.
 

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

@@ -24,10 +24,9 @@ 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-clean"
   "ahe-converse"
   "ahe-feature"
-  "ahe-fix"
   "ahe-git"
   "ahe-harness"
   "ahe-harness-checker"
@@ -80,31 +79,38 @@ cleanup_ahe_config_entries() {
   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[^"]*"\]$/ ||
+      return line ~ /^\[hooks\.state\."ahe[^"]*"\]$/ ||
         line ~ /^\[plugins\."?ahe[^]]*"?\]$/ ||
         line ~ /^\[plugins\."@ksuchoi216\/ahe[^"]*"\]$/
     }
 
     $0 == block_start {
-      skip = 1
+      in_block = 1
       next
     }
 
     $0 == block_end {
-      skip = 0
+      in_block = 0
+      next
+    }
+
+    in_block == 1 {
       next
     }
 
     /^\[/ {
       if (is_ahe_header($0)) {
-        skip = 1
+        skip_section = 1
         next
       }
-      skip = 0
+      skip_section = 0
     }
 
-    skip != 1 {
+    skip_section == 1 {
+      next
+    }
+
+    {
       print
     }
   ' "${config_path}" > "${temp_path}"
@@ -249,11 +255,10 @@ Global 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\`.
+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
 }
 
@@ -278,11 +283,6 @@ doctor() {
     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))

package/packages/ahe-codex/package.json

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

package/packages/ahe-codex/.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/packages/ahe-codex/.codex/skills/ahe-compress/SKILL.md

@@ -1,120 +0,0 @@
----
-name: ahe-compress
-description: Internal AHE compression workflow for detecting oversized harness-engineering files or stale overlapping tests, and compacting them before AHE thinker or harness routing reads large context. Use when AGENTS.md, docs/product.md, docs/product{number}.md, docs/INSTRUCTIONS.md, feature-list.json, progress.md, session-handoff.md, docs/todo.md, or other AHE harness artifacts have too many lines or waste context. It also covers stale overlapping tests.
----
-
-# AHE Compression
-
-This is an internal AHE workflow skill, not a user-facing command.
-
-Do not treat `$ahe-compress` as a user command.
-Use it after `think` or `harness` decides that harness context is too large to read
-efficiently, or when test-suite cleanup is needed. When the user explicitly asks
-for `ahe compress`, this skill must check both harness-file size pressure and
-stale overlapping tests before deciding the next action.
-
-## Test Overlap Detection
-
-Run the deterministic test-overlap detector script:
-
-```bash
-python .codex/skills/compress/scripts/detect_stale_tests.py
-```
-
-The script checks for legacy tests already covered by newer canonical files and prints `REVIEW_TEST\t<legacy-file>\tcovered_by=<keeper-files>`.
-It exits with code `2` and prints `TEST_COMPRESSION_REQUIRED` when stale candidates exist.
-
-Note: `compress` must not directly delete tests; it only signals compression pressure. The actual test consolidation must be routed by `think` through `review` first and then `solve` or `harness` as needed.
-
-## Size Detection
-
-Run the deterministic line-count preflight before reading full harness files:
-
-```bash
-sh .codex/skills/compress/scripts/check-harness-size.sh
-```
-
-The script checks these AHE-managed files when they exist:
-
-- `AGENTS.md`
-- `docs/product.md`
-- numbered product stage docs such as `docs/product1.md` and `docs/product2.md`
-- `docs/INSTRUCTIONS.md`
-- `feature-list.json`
-- `progress.md`
-- `session-handoff.md`
-- `docs/todo.md`
-
-Default thresholds are configured in `.codex/ahe-shared/config.yaml`:
-
-- `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 (combined harness context limit)
-
-Override thresholds only when the workspace has an explicit local rule using environment variables (e.g., `AHE_AGENT_MD_LIMIT`, `AHE_FILE_LINE_LIMIT`, `AHE_TOTAL_LINE_LIMIT`):
-
-```bash
-AHE_AGENT_MD_LIMIT=100 AHE_TOTAL_LINE_LIMIT=900 sh .codex/skills/compress/scripts/check-harness-size.sh
-```
-
-Exit code meanings:
-
-- `0`: no compression needed.
-- `2`: compression needed.
-- Output ending in `COMPRESSION_REQUIRED`: compression needed.
-- Any other nonzero code: detector failed; fall back to `wc -l` on the same
-  file set and continue the decision manually.
-
-## Compression Decision
-
-- Run both compression detectors before choosing the next compression step.
-- If the detector exits `2`, compress before normal AHE routing continues.
-- If the harness-size detector exits `2`, compact harness files first.
-- If the stale-test detector exits `2`, route through `review` before any test cleanup.
-- If only one file exceeds the per-file threshold, compress that file first.
-- If total harness context exceeds the total threshold, compress the largest
-  AHE-managed files until the total is under the threshold.
-- If `AGENTS.md` is oversized, obey the local `AGENTS.md` instructions before
-  editing it. Compress only sections that local rules allow. If no section is
-  safely editable, report the blocker and compress other harness files instead.
-- Do not read an oversized file wholesale after detection. Read headings,
-  current-status sections, JSON keys, or bounded line ranges needed to preserve
-  behavior.
-
-## Compression Rules
-
-- Preserve active requirements, current decisions, incomplete work, blockers,
-  dependencies, and verification evidence.
-- Preserve required headers and file formats for `progress.md`,
-  `session-handoff.md`, `feature-list.json`, and `AGENTS.md`.
-- Keep `feature-list.json` valid JSON. Replace stale completed-feature history
-  with one summarized done feature, preserve its `id`, `name`, `description`,
-  `dependencies`, `status`, and short evidence, and keep current unfinished
-  details as-is.
-- Keep `docs/product.md` and `docs/INSTRUCTIONS.md` as the current harness
-  contract. Remove duplicate historical wording only when the active contract
-  remains clear.
-- Keep numbered product stage docs in numeric suffix order. Ignore non-numeric
-  product docs such as `docs/product-alpha.md` for stage ordering.
-- Preserve the active product stage and do not merge future product stages into
-  current feature-list work during compression.
-- Keep `progress.md` focused on current status, recent completed work,
-  decisions that still matter, blockers, and latest verification.
-- Keep `session-handoff.md` focused on the startup path for the next session,
-  important files, open questions, and current verification status.
-- Do not create backup copies when compressing harness history. Preserve useful
-  context through concise summaries in the refreshed harness files instead.
-
-## Completion
-
-- Re-run the size detector after compression.
-- Run JSON validation when `feature-list.json` changed.
-- Run the repository's normal harness verification command when compression
-  changed tracked harness files.
-- Update `progress.md` and `session-handoff.md` with the compression evidence
-  when they changed or when compression affects the active workflow.

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

@@ -1,6 +0,0 @@
-interface:
-  display_name: "AHE Compression"
-  short_description: "Compress oversized harness context"
-  default_prompt: "Use $ahe-compress to compact oversized AHE harness files before continuing."
-policy:
-  allow_implicit_invocation: false

package/packages/ahe-codex/.codex/skills/ahe-compress/scripts/check-harness-size.sh

@@ -1,121 +0,0 @@
-#!/usr/bin/env sh
-set -eu
-
-limit_agent_md=180
-limit_product_md=180
-limit_instructions_md=180
-limit_feature_list_json=180
-limit_progress_md=180
-limit_session_handoff_md=180
-limit_todo_md=180
-limit_total=750
-
-config_file=".codex/ahe-shared/config.yaml"
-if [ -f "${config_file}" ]; then
-  while IFS= read -r line || [ -n "$line" ]; do
-    line="${line#"${line%%[![:space:]]*}"}"
-    line="${line%"${line##*[![:space:]]}"}"
-    case "$line" in
-      "" | \#*) continue ;;
-    esac
-    
-    key="${line%%:*}"
-    val="${line#*:}"
-    key="${key%"${key##*[![:space:]]}"}"
-    val="${val#"${val%%[![:space:]]*}"}"
-    
-    case "$val" in
-      ''|*[!0-9]*) continue ;;
-    esac
-
-    case "$key" in
-      agent_md) limit_agent_md="$val" ;;
-      product_md) limit_product_md="$val" ;;
-      instructions_md) limit_instructions_md="$val" ;;
-      feature_list_json) limit_feature_list_json="$val" ;;
-      progress_md) limit_progress_md="$val" ;;
-      session_handoff_md) limit_session_handoff_md="$val" ;;
-      todo_md) limit_todo_md="$val" ;;
-      total) limit_total="$val" ;;
-    esac
-  done < "${config_file}"
-fi
-
-limit_agent_md="${AHE_AGENT_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_agent_md}}"
-limit_product_md="${AHE_PRODUCT_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_product_md}}"
-limit_instructions_md="${AHE_INSTRUCTIONS_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_instructions_md}}"
-limit_feature_list_json="${AHE_FEATURE_LIST_JSON_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_feature_list_json}}"
-limit_progress_md="${AHE_PROGRESS_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_progress_md}}"
-limit_session_handoff_md="${AHE_SESSION_HANDOFF_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_session_handoff_md}}"
-limit_todo_md="${AHE_TODO_MD_LIMIT:-${AHE_FILE_LINE_LIMIT:-$limit_todo_md}}"
-total_limit="${AHE_TOTAL_LINE_LIMIT:-$limit_total}"
-
-total_lines=0
-compression_required=0
-
-if [ "$#" -eq 0 ]; then
-  set -- \
-    "AGENTS.md" \
-    "docs/product.md" \
-    "docs/INSTRUCTIONS.md" \
-    "feature-list.json" \
-    "progress.md" \
-    "session-handoff.md" \
-    "docs/todo.md"
-
-  if [ -d "docs" ]; then
-    product_stage_number=1
-    while [ "${product_stage_number}" -le 999 ]; do
-      product_stage_path="docs/product${product_stage_number}.md"
-      if [ -f "${product_stage_path}" ]; then
-        set -- "$@" "${product_stage_path}"
-      fi
-      product_stage_number=$((product_stage_number + 1))
-    done
-  fi
-fi
-
-for file_path in "$@"; do
-  if [ ! -f "${file_path}" ]; then
-    continue
-  fi
-
-  line_count="$(wc -l < "${file_path}")"
-  line_count="${line_count#"${line_count%%[![:space:]]*}"}"
-  line_count="${line_count%"${line_count##*[![:space:]]}"}"
-  total_lines=$((total_lines + line_count))
-
-  current_limit=180
-  case "${file_path}" in
-    "AGENTS.md") current_limit="${limit_agent_md}" ;;
-    "docs/product.md") current_limit="${limit_product_md}" ;;
-    "docs/product"[0-9]*".md") current_limit="${limit_product_md}" ;;
-    "docs/INSTRUCTIONS.md") current_limit="${limit_instructions_md}" ;;
-    "feature-list.json") current_limit="${limit_feature_list_json}" ;;
-    "progress.md") current_limit="${limit_progress_md}" ;;
-    "session-handoff.md") current_limit="${limit_session_handoff_md}" ;;
-    "docs/todo.md") current_limit="${limit_todo_md}" ;;
-    *) current_limit="${AHE_FILE_LINE_LIMIT:-180}" ;;
-  esac
-
-  if [ "${line_count}" -ge "${current_limit}" ]; then
-    compression_required=1
-    printf 'COMPRESS\t%s\t%s\tlimit=%s\n' "${file_path}" "${line_count}" "${current_limit}"
-  else
-    printf 'OK\t%s\t%s\tlimit=%s\n' "${file_path}" "${line_count}" "${current_limit}"
-  fi
-done
-
-if [ "${total_lines}" -ge "${total_limit}" ]; then
-  compression_required=1
-  printf 'COMPRESS_TOTAL\t%s\tlimit=%s\n' "${total_lines}" "${total_limit}"
-else
-  printf 'OK_TOTAL\t%s\tlimit=%s\n' "${total_lines}" "${total_limit}"
-fi
-
-if [ "${compression_required}" -eq 1 ]; then
-  printf 'COMPRESSION_REQUIRED\n'
-  exit 2
-fi
-
-printf 'COMPRESSION_NOT_REQUIRED\n'

package/packages/ahe-codex/.codex/skills/ahe-compress/scripts/detect_stale_tests.py

@@ -1,30 +0,0 @@
-import sys
-import os
-
-def main():
-    test_dir = "tests"
-    if not os.path.isdir(test_dir):
-        sys.exit(0)
-
-    overlap_map = {
-        "test_new_workflow.py": ["test_ahe_new.py"],
-        "test_spec_workflow.py": ["test_clarification_prompt.py", "test_ahe_new.py"],
-        "test_specialized_workflows.py": ["test_ahe_new.py", "test_clarification_prompt.py", "test_command_set.py"]
-    }
-
-    stale_found = False
-    for legacy_file, keeper_files in overlap_map.items():
-        legacy_path = os.path.join(test_dir, legacy_file)
-        if os.path.exists(legacy_path):
-            stale_found = True
-            keepers_str = ",".join(f"tests/{f}" for f in keeper_files)
-            print(f"REVIEW_TEST\ttests/{legacy_file}\tcovered_by={keepers_str}")
-
-    if stale_found:
-        print("TEST_COMPRESSION_REQUIRED")
-        sys.exit(2)
-    else:
-        sys.exit(0)
-
-if __name__ == "__main__":
-    main()

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

@@ -1,59 +0,0 @@
----
-name: ahe-fix
-description: Create a concrete `.plans/{plan_name}.md` fix plan for errors, bugs, or user-intent changes. Use when the user explicitly invokes `$fix`, `fix`, `ahe fix`, `ahe fix <query>`, or `<query> ahe fix`, and call `converse` when the plan needs clarification.
----
-
-# AHE Fix
-
-`fix` is a user-facing AHE command for creating a fix plan. It is separate
-from the normal `ahe` continuation workflow, including the thinker-routed
-`ahe <query>` and `<query> ahe` forms.
-
-Use this skill when the user wants a plan for fixing errors or following their
-current intention when it differs from the previous AHE flow.
-
-## Workflow
-
-1. Inspect the current conversation and relevant repository context.
-2. Identify the fix target:
-   - error, failure, regression, or broken behavior to repair.
-   - user intention that differs from the existing AHE direction.
-3. If the fix goal, scope, or success criteria are unclear, call
-   `converse` and ask one focused question before writing the plan.
-4. Derive `plan_name` from the fix goal. Use a short lowercase hyphenated name.
-   If no safe name can be derived, ask one focused question for the plan name.
-5. Build a compact markdown plan with these sections:
-   - `# {Fix Plan Title}`
-   - `## Fix Goal`
-   - `## Current Evidence`
-   - `## Assumptions`
-   - `## Scope`
-   - `## Steps`
-   - `## Verification Plan`
-   - `## Risks and Open Questions`
-   - `## Instructions for Next Agent`
-6. Write the final markdown through `scripts/write_fix_plan.py`.
-7. Report the created `.plans/{plan_name}.md` path.
-
-## Missing Context
-
-- If the requested fix is ambiguous, use `converse` instead of guessing.
-- If the target file already exists, ask whether to overwrite it or choose a
-  distinct plan name.
-- Do not update `feature-list.json`, `progress.md`, or `session-handoff.md`
-  for a normal fix-plan export unless the user explicitly asks for harness
-  tracking changes too.
-
-## Writer Script
-
-Use:
-
-```bash
-python3 .codex/skills/fix/scripts/write_fix_plan.py \
-  --root "$PWD" \
-  --plan-name "Fix Plan Title" \
-  < /tmp/fix-plan.md
-```
-
-Add `--overwrite` only after the user explicitly confirms replacing an existing
-file.

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

@@ -1,108 +0,0 @@
-#!/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())