@ksuchoi216/ahe 0.1.7 → 0.1.12

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

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

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

@@ -0,0 +1,96 @@
+---
+name: ahe-overview
+description: Provides an overview of Awesome Harness Engineering (AHE), its architecture, and available commands.
+---
+
+# Awesome Harness Engineering (AHE) Overview
+
+AHE is a framework and set of managed skills designed to maintain project harnesses (documentation, requirements, testing) and route work systematically through AI agents.
+
+## Public Entrypoints
+
+You interact with AHE using the following user-facing commands:
+- **`ahe` / `ahe <query>` / `<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:
+- **`ahe-harness`**: Builds and maintains product docs, instructions, and tracking state.
+- **`ahe-review`**: Explores the codebase and reads files to understand context.
+- **`ahe-converse`**: Pauses and asks the user for clarification when blocked.
+- **`ahe-feature`**: Sizes and extracts new features from product documentation.
+- **`ahe-solve`**: Solves or plans specific features.
+- **`ahe-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.
+
+## Main Flows
+
+### 1. `ahe` (Continuous Execution)
+```mermaid
+graph TD;
+    User[User: ahe] --> Hook[ahe-hook.js]
+    Hook --> Think[ahe-think]
+    Think --> State{State?}
+    State -- Harness Missing --> New[ahe-new]
+    State -- Building Features --> Solve[ahe-solve]
+    State -- Need Context --> Review[ahe-review]
+    State -- Blocked --> Converse[ahe-converse]
+    State -- Harness Work --> Harness[ahe-harness]
+```
+
+### 2. `ahe ship` (Export / Execute Plan)
+
+**In Codex (Export):**
+```mermaid
+graph TD;
+    User[User: ahe ship] --> Hook[ahe-hook.js]
+    Hook --> Think[ahe-think]
+    Think --> Ship[ahe-ship]
+    Ship --> Write[Write .plans/*.md]
+```
+
+**In Antigravity (Execute):**
+```mermaid
+graph TD;
+    User[User: ahe-ship] --> Antigravity
+    Antigravity --> ShipSkill[ahe-ship skill]
+    ShipSkill --> Read[Read .plans/*.md]
+    Read --> Execute[Execute Plan]
+```
+
+### 3. `ahe-git` (Repository Sync)
+
+**In Antigravity:**
+```mermaid
+graph TD;
+    User[User: ahe-git] --> Antigravity
+    Antigravity --> GitSkill[ahe-git skill]
+    GitSkill --> Pull[Pull Remote]
+    Pull --> Commit[Commit Local Changes]
+```
+
+## Example of How to Use
+
+### Harness Engineering
+1. `ahe`
+(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`
+(implement a specific feature)
+
+### ahe-ship in Codex and Antigravity
+after planning in codex
+1. `ahe-ship` in codex
+(save the plan to .plans)
+2. `ahe-ship` in antigravity
+(implement one of plans in .plans)
+
+### ahe-git
+1. `ahe-git` in antigravity
+(safely pull and commit all nested repositories)

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

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

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

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

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

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

package/packages/ahe-codex/.codex/skills/ahe-ship/scripts/write_plan.py

@@ -0,0 +1,107 @@
+#!/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_plan.py --root "$PWD" --plan-name "Plan Title" < /tmp/ahe-plan.md
+# 3. Or with Python when dependencies are already available:
+#      python write_plan.py --root "$PWD" --plan-name "Plan Title" < /tmp/ahe-plan.md
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class WritePlanArgs:
+    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]) -> WritePlanArgs:
+    root: Path | None = None
+    plan_name: str | None = None
+    overwrite = False
+    index = 0
+
+    while index < len(argv):
+        argument = argv[index]
+        if argument == "--root":
+            index += 1
+            if index >= len(argv):
+                raise ArgumentError("--root requires a value")
+            root = Path(argv[index])
+        elif argument == "--plan-name":
+            index += 1
+            if index >= len(argv):
+                raise ArgumentError("--plan-name requires a value")
+            plan_name = argv[index]
+        elif argument == "--overwrite":
+            overwrite = True
+        else:
+            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 WritePlanArgs(root=root, plan_name=plan_name, overwrite=overwrite)
+
+
+def write_plan(args: WritePlanArgs, 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_plan(args, sys.stdin.read())
+    except (ArgumentError, PlanAlreadyExistsError) as error:
+        print(error, file=sys.stderr)
+        return 1
+
+    print(plan_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,30 @@
+---
+name: ahe-solve
+description: Internal AHE feature-solving workflow for dividing, planning, and solving feature work after the active goal is clear enough.
+---
+
+# AHE Solver
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-solve` as a user command.
+Use it when `ahe-think` decides that the next job is building or planning a
+feature.
+
+## Command Workflow: solve
+
+- Read the active feature context from `docs/product.md`, `feature-list.json`,
+  `progress.md`, and any relevant code files.
+- Read all existing `docs/*.md` files as supporting context.
+- When numbered product stages exist, solve against the active product stage:
+  start with `docs/product1.md`, advance to later numeric stages only after the
+  current stage's derived feature-list items are `done`, and keep future product stages as context rather than implementation scope.
+- Keep `docs/product.md` as overview context while working from an active
+  product stage.
+- Divide broad work into smaller problems when useful.
+- Plan each smaller problem before implementation.
+- Call `ahe-review` when repo or code understanding is needed.
+- Call `ahe-converse` when feature requirements, scope, or success criteria
+  are still unclear.
+- Report the solved step, remaining work, and recommended next agent back to
+  `ahe-think`.

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

@@ -0,0 +1,125 @@
+---
+name: ahe-think
+description: Internal AHE orchestration protocol for routing exact `ahe`, `ahe <query>`, and `<query> ahe` requests through the AHE agent network.
+---
+
+# AHE Thinker
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-think` as a user command.
+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-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.
+- `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.
+
+## Startup Contract
+
+- Check whether the copied harness files are correct before reading their contents.
+- Read files strictly in this order:
+  `AGENTS.md` -> `docs/product.md` plus `docs/product{n}.md` -> `docs/architecture.md` -> `docs/instructions.md` -> `init.sh` -> `feature-list.json` -> `status.json` -> `progress.md` -> `session-handoff.md`
+- `ahe-think` explicitly owns the "what to do next" decisions for Codex-side AHE work.
+
+## Decision Rules
+
+- 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.
+- Read all existing `docs/*.md` files before choosing product work.
+- Treat `docs/product.md` as overview context.
+- Treat only `docs/product{number}.md` files as ordered product stages, starting
+  with `docs/product1.md` and then `docs/product2.md`.
+- Ignore non-numeric product docs such as `docs/product-alpha.md` for stage
+  ordering.
+- 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, 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
+
+- `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`
+  - `ahe-think -> ahe-solve -> ahe-think`
+  - `ahe-think -> ahe-harness-checker -> ahe-think`
+- Allowed direct handoffs include:
+  - `ahe-harness -> ahe-converse`
+  - `ahe-solve -> ahe-review`
+  - `ahe-review -> ahe-harness`
+  - `ahe-harness -> ahe-harness-checker`
+  - `ahe-new -> ahe-harness -> ahe-harness-checker`
+- Every handoff must state the goal, reason, relevant files or context, and the
+  expected result.
+
+## Broad Intent Routing
+
+- Use `ahe-review` for review-first requests.
+- Use `ahe-harness` for product, instructions, progress, feature-list, todo, or
+  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.
+
+## Hard Editing Rule
+
+- `AGENTS.md` and any `instructions.md` file may only be modified inside an explicitly changeable section.
+- If no changeable section exists, AHE must ask via `ahe-converse` instead of editing.
+- Reference and template folders must be strictly excluded from reads and edits per project rules.
+
+## Completion
+
+- Continue to the next skill or next unfinished feature until the active unit is
+  resolved.
+- Keep `docs/product.md` as overview context and `feature-list.json` as a
+  derived tracker.
+- Derive features from only the active product stage.
+- Advance from one numbered product stage to the next only after all
+  feature-list items derived from the current active stage are `done`.