@ksuchoi216/ahe 0.1.6 → 0.1.10

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

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+const AHE_DIRECTIVE_MARKER = "<ahe-mode>";
+
+const STATUS_TABLE_LINES = [
+  "   - Start the response with a concise status report table.",
+  "   - Use this consistent Markdown table format:",
+  "     | Item | Content |",
+  "     |---|---|",
+  "     | AGENTS.md | Exists/missing, purpose status, and any obvious issue. |",
+  "     | product.md | Exists/missing, completion state, and whether product scope needs work. |",
+  "     | INSTRUCTIONS.md | Exists/missing, and whether instruction boundaries need work. |",
+  "     | feature-list.json | Valid/missing/invalid, unfinished feature summary, and all-done status. |",
+  "     | progress.md | Exists/missing and current session state. |",
+  "   - Keep the table short and readable.",
+  "   - Do not include the next step inside the table.",
+];
+
+const CODEGRAPH_PREFLIGHT_LINES = [
+  "1. Run CodeGraph preflight before inspecting harness status:",
+  "   - Check whether the CodeGraph CLI is installed with `command -v codegraph`.",
+  "   - If the `codegraph` command is not installed, report `NOT INSTALLATION of codegraph`, skip `codegraph init` and `codegraph sync`, and continue with normal repo inspection.",
+  "   - If `.codegraph/` does not exist, run `codegraph init` before reviewing code.",
+  "   - If `.codegraph/` exists, run `codegraph sync` before reviewing code.",
+  "",
+];
+
+const COMMON_ROUTING_LINES = [
+  ...CODEGRAPH_PREFLIGHT_LINES,
+  "2. Inspect current harness state before choosing a workflow:",
+  "   - Check `AGENTS.md`.",
+  "   - Read all existing `docs/*.md` files as supporting project context, even when `AGENTS.md` does not name them directly.",
+  "   - Check `docs/product.md` and `docs/INSTRUCTIONS.md` as the product/specification source of truth.",
+  "   - Treat `docs/product.md` as overview context and optional `docs/product1.md`, `docs/product2.md`, and later numeric suffix files as ordered product stages.",
+  "   - Ignore non-numeric product docs such as `docs/product-alpha.md` when choosing product stage order.",
+  "   - Choose the active product source by numeric suffix order: first `docs/product1.md`, then `docs/product2.md`, and so on, using the first stage whose derived work is not complete.",
+  "   - Always derive features from only the active product stage; keep future product stages as context until earlier stages are done.",
+  "   - 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.",
+  "   - If CodeGraph is not installed, skip CodeGraph review and rely on normal repo inspection.",
+  "",
+  "3. Make the first response a simple harness engineering status report table before proceeding:",
+  ...STATUS_TABLE_LINES,
+];
+
+const AHE_PROGRESS_DIRECTIVE = [
+  AHE_DIRECTIVE_MARKER,
+  "AHE automatic operation activated.",
+  "",
+  "The user sent the exact AHE command. Operate as the Awesome Harness Engineering router:",
+  "",
+  ...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.",
+  "   - 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.",
+  "   - When numbered product stages exist, let `ahe-feature` derive feature-list items from only the active product stage.",
+  "   - Advance from `docs/product1.md` to `docs/product2.md` only after all feature-list items derived from `docs/product1.md` are `done`; repeat this rule for later numeric stages.",
+  "   - 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-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-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.",
+  "",
+  "5. After the table, classify the harness into exactly one state.",
+  "   - Use exactly one state: `harness engineering not enough`, `in the middle of building features`, or `completed all`.",
+  "   - Do not include the next step inside the table.",
+  "   - Continue automatically after classification.",
+];
+
+const AHE_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.",
+  "",
+  "The user invoked `ahe-ship`.",
+  "",
+  ...CODEGRAPH_PREFLIGHT_LINES,
+  "2. Immediately call the `ahe-ship` skill.",
+  "3. Detect if the current conversation is still in Plan Mode.",
+  "4. If Plan Mode is active, the Codex host must exit Plan Mode and replay the command.",
+  "5. Outside Plan Mode, use the most recent `<proposed_plan>` already visible in this conversation.",
+  "6. Do not ask for the plan again when the latest plan is unambiguous.",
+  "7. Derive `plan_name` from the plan title and create `.plans/{plan_name}.md`.",
+  "8. Add compact handoff context for Antigravity or another LLM platform.",
+  "9. Use `.codex/skills/ahe-ship/scripts/write_plan.py` to write the final markdown and stop.",
+  "",
+  "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.",
+  "",
+  "The user invoked `ahe-git`.",
+  "",
+  ...CODEGRAPH_PREFLIGHT_LINES,
+  "2. Route to `ahe-think` first.",
+  "3. `ahe-think` must immediately call the `ahe-git` skill.",
+  "",
+  "Do not run the normal AHE harness workflow.",
+].join("\n");
+
+const AHE_OVERVIEW_DIRECTIVE = [
+  AHE_DIRECTIVE_MARKER,
+  "AHE overview activated.",
+  "",
+  "The user invoked `ahe-overview`.",
+  "",
+  ...CODEGRAPH_PREFLIGHT_LINES,
+  "2. Read `.codex/skills/ahe-overview/SKILL.md`.",
+  "3. Present its contents to explain the AHE concept to the user.",
+  "",
+  "Do not run the normal AHE harness workflow.",
+].join("\n");
+
+function normalizePrompt(prompt) {
+  return prompt.trim().replace(/\s+/g, " ").toLowerCase();
+}
+
+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";
+}
+
+function isExactAheOverviewCommand(prompt) {
+  return normalizePrompt(prompt) === "ahe-overview";
+}
+
+async function main() {
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) {
+    raw += chunk;
+  }
+
+  if (!raw.trim()) {
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  if (
+    parsed &&
+    parsed.hook_event_name === "UserPromptSubmit" &&
+    typeof parsed.prompt === "string"
+  ) {
+    if (isExactAheCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_PROGRESS_DIRECTIVE.join("\n"),
+          },
+        }) + "\n"
+      );
+      return;
+    }
+
+    if (isExactAheNewCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_NEW_DIRECTIVE,
+          },
+        }) + "\n"
+      );
+      return;
+    }
+
+    if (isExactAheShipCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_SHIP_DIRECTIVE,
+          },
+        }) + "\n"
+      );
+      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({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_GIT_DIRECTIVE,
+          },
+        }) + "\n"
+      );
+      return;
+    }
+
+    if (isExactAheOverviewCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_OVERVIEW_DIRECTIVE,
+          },
+        }) + "\n"
+      );
+      return;
+    }
+  }
+}
+
+main().catch(() => {});

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

@@ -0,0 +1,34 @@
+---
+name: ahe
+description: Continue existing harness work and route exact `ahe`, `ahe <query>`, and `<query> ahe` requests through the AHE agent network.
+---
+
+# AHE
+
+`ahe` is the top-level user-facing Codex skill for continuing existing AHE
+work in the current workspace.
+
+## Command Contract
+
+- Exact `ahe` means continue existing harness work.
+- `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`
+  workflows when the user's prompt matches those command contracts.
+
+## Routing
+
+- Call `ahe-think` first.
+- Let `ahe-think` choose `ahe-review`, `ahe-converse`, `ahe-harness`, or
+  `ahe-solve`.
+- Keep `docs/product.md` as overview context and `feature-list.json` as the
+  derived tracker.
+- Actualize the final product through `docs/product{number}.md` stages in
+  numeric order when staged product docs exist.
+
+## 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.

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

@@ -0,0 +1,120 @@
+---
+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/{.codex/skills/ahe-compression → packages/ahe-codex/.codex/skills/ahe-compress}/agents/openai.yaml

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

package/{.codex/skills/ahe-compression → packages/ahe-codex/.codex/skills/ahe-compress}/scripts/check-harness-size.sh

@@ -56,12 +56,23 @@ compression_required=0
 if [ "$#" -eq 0 ]; then
   set -- \
     "AGENTS.md" \
-    "docs/PRODUCT.md" \
+    "docs/product.md" \
     "docs/INSTRUCTIONS.md" \
     "feature-list.json" \
-    "PROGRESS.md" \
-    "SESSION-HANDOFF.md" \
+    "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
@@ -77,11 +88,12 @@ for file_path in "$@"; do
   current_limit=180
   case "${file_path}" in
     "AGENTS.md") current_limit="${limit_agent_md}" ;;
-    "docs/PRODUCT.md") current_limit="${limit_product_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}" ;;
+    "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

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

@@ -0,0 +1,30 @@
+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-converse/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ahe-converse
+description: Internal AHE conversation protocol for recursive clarification, conversation state, and resume-aware workflow guidance.
+---
+
+# AHE Conversator
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-converse` as a user command.
+Use it after `ahe-think` or another AHE agent identifies a missing decision or
+missing `Why`, `What`, or `How`.
+
+## When To Converse
+
+- Ask one question at a time.
+- Use conversation state when multiple answers are needed across turns.
+- Clarify product intent, instructions, next feature, restart scope, or any
+  decision that materially changes the workflow.
+- If the answer can be derived safely from repo state, do that instead of
+  asking.
+
+## Conversation Protocol
+
+- Inspect relevant files before asking.
+- Explain the blocked decision briefly.
+- Use a Codex-supported structured response request when it helps.
+- Ask exactly one focused question at a time.
+- Continue recursively until the answer is specific enough to unblock the
+  calling workflow.
+
+## State Persistence
+
+- Update `status.json` before pausing for user input.
+- Preserve the current command, current_step, workflow_complete, and files map.
+- Update `progress.md` and `session-handoff.md` when the pending question
+  changes the workflow state.
+
+## Resume Protocol
+
+- Read `status.json` and the relevant workflow artifacts.
+- Summarize the current state briefly.
+- Ask the next focused question or return control to the caller when the answer
+  resolves the missing detail.

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

@@ -0,0 +1,25 @@
+---
+name: ahe-feature
+description: Internal AHE workflow skill for creating right-sized feature-list.json entries from product context.
+---
+
+# AHE Feature
+
+This is an internal AHE workflow skill, not a user-facing command.
+Use it when `ahe-think` or another worker decides that feature sizes must be evaluated or when generating new features from product context.
+
+## Command Workflow: ahe-feature
+
+### Feature Generation and Sizing
+
+- Derive concrete feature items from only the active product stage (e.g. `docs/product1.md`), not future stages.
+- Create right-sized `feature-list.json` entries from product context.
+- Avoid tiny task fragments. A feature should represent a meaningful, verifiable unit of work.
+- Avoid vague, oversized features. Break large epics down into testable, implementable features.
+- If product context is insufficient to create right-sized features, use `ahe-converse` to ask the user for clarification.
+- Update `feature-list.json` with the newly derived, well-sized features.
+- Ensure that features are actionable and have clear success criteria based on the product documentation.
+
+### Clarification Rule
+
+When feature sizing or extraction is ambiguous, follow the `ahe-think` protocol first. If `ahe-think` finds missing information, follow the `ahe-converse` protocol to ask the user for the exact missing detail.

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

@@ -0,0 +1,59 @@
+---
+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.