@ksuchoi216/ahe 0.1.6 → 0.1.7

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

@@ -1,236 +1,195 @@
 #!/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 COMMON_ROUTING_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.",
+  "",
+  "2. Inspect current harness state before choosing a workflow:",
+  "   - Check `AGENTS.md`.",
+  "   - Check `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` as the product/specification source of truth.",
+  "   - Check `feature-list.json` as a derived tracker.",
+  "   - Check `PROGRESS.md`.",
+  "   - Use `ahe-thinker` as the internal decision layer before choosing the next action.",
+  "   - Before reading large harness files wholesale, let `ahe-thinker` run the `ahe-compression` size detector and call `ahe-compression` if compression is required.",
+  "",
+  "3. 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.",
+  "",
+  "4. 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:",
+  "",
+  ...COMMON_ROUTING_LINES,
+  "",
+  "5. Decide the next AHE workflow with `ahe-thinker`:",
+  "   - If no harness files exist, route to `$ahe-init`.",
+  "   - 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.",
+  "   - 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-reviewer` when repo or code understanding is needed.",
+  "   - Call `ahe-conversator` 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-solver` when the next job is solving or planning a feature.",
+  "",
+  "6. 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_INIT_DIRECTIVE = [
+  AHE_DIRECTIVE_MARKER,
+  "AHE automatic operation activated.",
+  "",
+  "The user sent the exact AHE init command. Treat this as a possible new start request:",
+  "",
+  "1. Route to `$ahe-init` first.",
+  "2. If no AHE-managed harness files exist, start initialization normally.",
+  "3. 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.",
+  "4. Do not remove, overwrite, or refresh existing harness files before the user answers the restart-scope question.",
+  "5. If the chosen restart scope replaces prior harness history, summarize that replaced state in the refreshed tracking artifacts instead of creating backup copies.",
+  "6. Interpret the restart scope from the user's free-form answer; examples like `purpose` and `product` are not a closed list.",
+  "7. Product/instructions specification details belong in `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md`, not `AGENTS.md`.",
+  "8. After setup, call `ahe-harness` to build the initial product, instructions, and tracking state.",
+  "9. Use `ahe-thinker` before clarification when the next setup step is uncertain.",
+  "10. If clarification is needed, call `ahe-conversator` for the exact missing detail.",
+].join("\n");
+
+function getQueryDirective(prompt) {
+  return [
     AHE_DIRECTIVE_MARKER,
     "AHE automatic operation activated.",
     "",
-    "The user sent the exact AHE command. Operate as the Awesome Harness Engineering router:",
-    "",
-    "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.",
+    `Original prompt: "${prompt}"`,
     "",
-    "2. Inspect current harness state before choosing a workflow:",
-    "   - Check `AGENTS.md`.",
-    "   - Check `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` as the product/specification source of truth.",
-    "   - Check `feature-list.json` as a derived tracker.",
-    "   - Check `PROGRESS.md`.",
-    "   - Use `ahe-thinking` as the internal decision layer before choosing the next action.",
-    "   - Before reading large harness files wholesale, let `ahe-thinking` run the `ahe-compression` size detector and call `ahe-compression` if compression is required.",
+    "The user sent an explicit AHE query. Route it through `ahe-thinker`:",
     "",
-    "3. 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.",
+    ...COMMON_ROUTING_LINES,
     "",
-    "4. Make the first response a simple harness engineering status report table before proceeding:",
-    "   - 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.",
-    "",
-    "5. Decide the next AHE workflow with `ahe-thinking`:",
-    "   - If no harness files exist, route to `$ahe-init`.",
-    "   - If `docs/PRODUCT.md` or `docs/INSTRUCTIONS.md` is missing or empty, classify the state as `harness engineering not enough` and prioritize product/instructions specification.",
-    "   - 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.",
-    "   - 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.",
-    "   - Respect dependencies listed in `feature-list.json`; do not start a dependent feature before prerequisites are done.",
-    "   - 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.",
-    "   - Judge the active `project`, `feature`, or `sub-feature` before moving forward.",
-    "   - For a `project`, require `Why`, `What`, and `How` by default.",
-    "   - For a `feature` or `sub-feature`, require only the minimum of `Why`, `What`, and `How` needed to proceed safely.",
+    "5. Decide the next AHE workflow with `ahe-thinker` based on the original prompt:",
+    "   - Use `ahe-reviewer` for code or harness review work.",
+    "   - Use `ahe-harness` for product, instructions, progress, feature-list, todo, or compression maintenance.",
+    "   - For `ahe compress feature-list`, replace old completed feature entries with one summarized done feature, preserve unfinished details, and reconcile `feature-list.json` against `docs/PRODUCT.md`.",
+    "   - If no new feature can be derived from `docs/PRODUCT.md`, call `ahe-conversator` to ask what next feature, product direction, or goal should be tracked.",
+    "   - Use `ahe-solver` for feature-solving work.",
+    "   - If multiple plausible next steps remain, use `ahe-conversator` to ask the minimum question needed.",
     "",
-    "6. Ask for clarification instead of guessing:",
-    "   - If multiple plausible next steps exist, feature data conflicts, dependencies are unclear, or CodeGraph review points to several valid directions, use `ahe-thinking` to judge the missing detail.",
-    "   - If clarity is missing, call `ahe-conversation` for the exact missing `Why`, `What`, or `How`.",
-    "   - Continue only after one safe next step is clear.",
-    "",
-    "7. After the table, classify the harness into exactly one state.",
+    "6. 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.",
-    "   - Follow this loop: `thinking -> conversation if needed -> execution -> thinking`.",
-].join("\\n");
+  ].join("\n");
+}
 
-const AHE_INIT_DIRECTIVE = [
-    AHE_DIRECTIVE_MARKER,
-    "AHE automatic operation activated.",
-    "",
-    "The user sent the exact AHE init command. Treat this as a possible new start request:",
-    "",
-    "1. Route to `$ahe-init` first.",
-    "2. If no AHE-managed harness files exist, start initialization normally.",
-    "3. 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.",
-    "4. Do not back up, remove, overwrite, or refresh existing harness files before the user answers the restart-scope question.",
-    "5. Interpret the restart scope from the user's free-form answer; examples like `purpose` and `product` are not a closed list.",
-    "6. Product/instructions specification details belong in `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md`, not `AGENTS.md`.",
-    "7. Use `ahe-thinking` before clarification when the next setup step is uncertain.",
-    "8. If clarification is needed, call `ahe-conversation` for the exact missing detail.",
-    "9. Continue through initialization work until the new start path is clear.",
-].join("\\n");
+function normalizePrompt(prompt) {
+  return prompt.trim().toLowerCase();
+}
 
 function isExactAheCommand(prompt) {
-    return normalizePrompt(prompt) === "ahe";
+  return normalizePrompt(prompt) === "ahe";
 }
 
 function isExactAheInitCommand(prompt) {
-    const normalizedPrompt = normalizePrompt(prompt);
-    return (
-        normalizedPrompt === "ahe init" ||
-        normalizedPrompt === "ahe-init" ||
-        normalizedPrompt === "$ahe-init"
-    );
+  const normalizedPrompt = normalizePrompt(prompt);
+  return (
+    normalizedPrompt === "ahe init" ||
+    normalizedPrompt === "ahe-init" ||
+    normalizedPrompt === "$ahe-init"
+  );
 }
 
-function isBroadAheIntent(prompt) {
-    if (isExactAheCommand(prompt) || isExactAheInitCommand(prompt)) {
-        return false;
-    }
-    
-    const p = normalizePrompt(prompt);
-    
-    const hasAction = /(add|new|update|change|track|manage)/.test(p);
-    const hasTarget = /(product|feature|instruction|requirement|spec|work|todo)/.test(p);
-    
-    if (!(hasAction && hasTarget)) {
-        return false;
-    }
-    
-    const falsePositives = [
-        /what is/,
-        /explain/,
-        /how to/,
-        /how do/,
-        /file/,
-        /error/,
-        /issue/
-    ];
-    
-    for (const fp of falsePositives) {
-        if (fp.test(p)) return false;
-    }
-    
-    return true;
+function isExplicitAheQuery(prompt) {
+  const normalizedPrompt = normalizePrompt(prompt);
+  if (isExactAheCommand(prompt) || isExactAheInitCommand(prompt)) {
+    return false;
+  }
+  return normalizedPrompt.startsWith("ahe ");
 }
 
-function getAdaptiveDirective(prompt) {
-    return [
-        AHE_DIRECTIVE_MARKER,
-        "AHE automatic operation activated.",
-        "",
-        `Original prompt: "${prompt}"`,
-        "",
-        "The user provided a broad natural-language AHE work intent.",
-        "Operate as the Awesome Harness Engineering router with an adaptive workflow:",
-        "",
-        "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.",
-        "",
-        "2. Inspect current harness state before choosing a workflow:",
-        "   - Check `AGENTS.md`.",
-        "   - Check `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` as the product/specification source of truth.",
-        "   - Check `feature-list.json` as a derived tracker.",
-        "   - Check `PROGRESS.md`.",
-        "   - Use `ahe-thinking` as the internal decision layer before choosing the next action.",
-        "   - Before reading large harness files wholesale, let `ahe-thinking` run the `ahe-compression` size detector and call `ahe-compression` if compression is required.",
-        "",
-        "3. Review code through CodeGraph when available.",
-        "",
-        "4. Make the first response a simple harness engineering status report table before proceeding:",
-        "   - 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.",
-        "",
-        "5. Decide the next AHE workflow with `ahe-thinking` based on the original prompt:",
-        "   - Classify the user intent from the original prompt as: `product/spec changes`, `instruction changes`, `feature/todo tracking`, or `unclear AHE work`.",
-        "   - Route product/spec changes to `ahe-spec`.",
-        "   - Route instruction changes to `ahe-spec`, and create `docs/INSTRUCTIONS.md` from the template when needed.",
-        "   - Route feature/todo tracking to `ahe-update`.",
-        "   - Route unclear AHE work to `ahe-conversation`.",
-        "",
-        "6. Ask for clarification instead of guessing:",
-        "   - If the request is vague, ask exactly one detail question before editing.",
-        "   - Call `ahe-conversation` for missing `Why`, `What`, or `How`.",
-        "   - Continue only after one safe next step is clear.",
-        "",
-        "7. 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.",
-        "   - Follow this loop: `thinking -> conversation if needed -> execution -> thinking`.",
-    ].join("\\n");
-}
+async function main() {
+  let raw = "";
+  process.stdin.setEncoding("utf8");
+  for await (const chunk of process.stdin) {
+    raw += chunk;
+  }
 
-function normalizePrompt(prompt) {
-    return prompt.trim().toLowerCase();
-}
+  if (!raw.trim()) {
+    return;
+  }
 
-async function main() {
-    let raw = "";
-    process.stdin.setEncoding("utf8");
-    for await (const chunk of process.stdin) {
-        raw += chunk;
-    }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return;
+  }
 
-    if (!raw.trim()) 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;
+    }
 
-    let parsed;
-    try {
-        parsed = JSON.parse(raw);
-    } catch (e) {
-        return;
+    if (isExactAheInitCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_INIT_DIRECTIVE,
+          },
+        }) + "\n"
+      );
+      return;
     }
 
-    if (
-        parsed &&
-        parsed.hook_event_name === "UserPromptSubmit" &&
-        typeof parsed.prompt === "string"
-    ) {
-        if (isExactAheCommand(parsed.prompt)) {
-            const output = {
-                hookSpecificOutput: {
-                    hookEventName: "UserPromptSubmit",
-                    additionalContext: AHE_PROGRESS_DIRECTIVE
-                }
-            };
-            process.stdout.write(JSON.stringify(output) + "\n");
-        } else if (isExactAheInitCommand(parsed.prompt)) {
-            const output = {
-                hookSpecificOutput: {
-                    hookEventName: "UserPromptSubmit",
-                    additionalContext: AHE_INIT_DIRECTIVE
-                }
-            };
-            process.stdout.write(JSON.stringify(output) + "\n");
-        } else if (isBroadAheIntent(parsed.prompt)) {
-            const output = {
-                hookSpecificOutput: {
-                    hookEventName: "UserPromptSubmit",
-                    additionalContext: getAdaptiveDirective(parsed.prompt)
-                }
-            };
-            process.stdout.write(JSON.stringify(output) + "\n");
-        }
+    if (isExplicitAheQuery(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: getQueryDirective(parsed.prompt),
+          },
+        }) + "\n"
+      );
     }
+  }
 }
 
 main().catch(() => {});

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

@@ -1,6 +1,6 @@
 ---
 name: ahe-compression
-description: Internal AHE compression workflow for detecting oversized harness-engineering files and compacting them before AHE thinking reads or routes large context. Use when AGENTS.md, docs/PRODUCT.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.
+description: Internal AHE compression workflow for detecting oversized harness-engineering files and compacting them before AHE thinker or harness routing reads large context. Use when AGENTS.md, docs/PRODUCT.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.
 ---
 
 # AHE Compression
@@ -8,7 +8,7 @@ description: Internal AHE compression workflow for detecting oversized harness-e
 This is an internal AHE workflow skill, not a user-facing command.
 
 Do not treat `$ahe-compression` as a user command.
-Use it after `ahe-thinking` decides that harness context is too large to read
+Use it after `ahe-thinker` or `ahe-harness` decides that harness context is too large to read
 efficiently.
 
 ## Size Detection
@@ -73,9 +73,10 @@ Exit code meanings:
   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. Shorten old completed-feature evidence,
-  but preserve each feature `id`, `name`, `description`, `dependencies`,
-  `status`, and current unfinished details.
+- 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.
@@ -83,9 +84,8 @@ Exit code meanings:
   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.
-- Back up material before deleting substantial historical context by moving it
-  under `.ahe/backups/compression-YYYYMMDD-HHMMSS/` when that context may still
-  be useful.
+- Do not create backup copies when compressing harness history. Preserve useful
+  context through concise summaries in the refreshed harness files instead.
 
 ## Completion
 

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

@@ -0,0 +1,44 @@
+---
+name: ahe-conversator
+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-conversator` as a user command.
+Use it after `ahe-thinker` 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 `.ahe/process_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 `.ahe/process_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/.codex/skills/ahe-harness/SKILL.md

@@ -0,0 +1,115 @@
+---
+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-thinker` or another worker decides that harness artifacts must
+be created, updated, reconciled, or compressed.
+
+## Command Workflow: ahe-harness
+
+### Harness Inspection
+
+- Read `docs/PRODUCT.md` if it exists.
+- Read `docs/INSTRUCTIONS.md` if it exists.
+- Read `AGENTS.md`, `feature-list.json`, `PROGRESS.md`, `SESSION-HANDOFF.md`,
+  and `docs/todo.md` when they exist.
+- Read `.ahe/process_status.json` when it exists.
+- Treat `docs/PRODUCT.md` as the canonical source of truth and
+  `feature-list.json` as a derived tracker.
+
+### 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 init`.
+- 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.
+- 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 feature-list`, 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-conversator` to ask what next feature, product direction, or goal should be tracked.
+- Call `ahe-reviewer` 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 `.ahe/process_status.json` aligned with the active workflow.
+
+## Clarification Rule
+
+When the next harness 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.
+
+### 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 `.ahe/process_status.json` at workflow start.
+- Update `.ahe/process_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.