@ksuchoi216/ahe 0.1.7 → 0.1.12

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

@@ -0,0 +1,249 @@
+#!/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.",
+  "",
+  "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 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`:",
+  "   - 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.",
+  "   - 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-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, 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.",
+  "",
+  "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_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_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 isExactAheShipCommand(prompt) {
+  const normalizedPrompt = normalizePrompt(prompt);
+  return normalizedPrompt === "ahe-ship" || normalizedPrompt === "ahe ship";
+}
+
+function isExactAheGitCommand(prompt) {
+  const normalizedPrompt = normalizePrompt(prompt);
+  return normalizedPrompt === "ahe-git" || normalizedPrompt === "ahe git";
+}
+
+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");
+  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 (isAheQueryCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_PROGRESS_DIRECTIVE.join("\n"),
+          },
+        }) + "\n"
+      );
+      return;
+    }
+
+    if (isExactAheShipCommand(parsed.prompt)) {
+      process.stdout.write(
+        JSON.stringify({
+          hookSpecificOutput: {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: AHE_SHIP_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,36 @@
+---
+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-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
+
+- 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 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/{.codex/skills/ahe-conversator → packages/ahe-codex/.codex/skills/ahe-converse}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: ahe-conversator
+name: ahe-converse
 description: Internal AHE conversation protocol for recursive clarification, conversation state, and resume-aware workflow guidance.
 ---
 
@@ -7,8 +7,8 @@ description: Internal AHE conversation protocol for recursive clarification, con
 
 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
+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
@@ -31,14 +31,14 @@ missing `Why`, `What`, or `How`.
 
 ## State Persistence
 
-- Update `.ahe/process_status.json` before pausing for user input.
+- 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
+- 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.
+- 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-git/SKILL.md

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

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

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

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

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