@ksuchoi216/ahe 0.1.2 → 0.1.7

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.

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

@@ -23,42 +23,35 @@ Use this skill when the user invokes `$ahe-init`.
 - Treat exact `ahe init` 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 backing up, removing, overwriting, or refreshing existing harness files.
-- Do not back up, remove, overwrite, or refresh existing harness files until the restart scope is clear.
+- 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`, back up the current product/specification files in scope, and restart product specification work in `docs/PRODUCT.md`.
-- If the answer names a narrower custom scope, preserve unrelated harness files and restart only the named scope after backing up the affected files.
+- 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 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.
 - If `AGENTS.md` does not exist, copy `AGENTS.md` from `.codex/ahe-shared/templates/`.
 - 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-spec` so they are written in `docs/PRODUCT.md` first.
+- 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.
 - 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?".
-- If the workspace already has active harness files and the user chooses a restart scope, create a timestamped backup directory under `.ahe/backups/`.
-- Copy `AGENTS.md` into the backup directory when it exists.
-- Copy the current `docs/PRODUCT.md` into the backup directory when it exists.
-- Copy the current `PROGRESS.md` into the backup directory when it exists.
-- Copy the current `SESSION-HANDOFF.md` into the backup directory when it exists.
-- Copy the current `feature-list.json` into the backup directory when it exists.
-- Copy `init.sh` into the backup directory when it exists.
-- Copy the `docs/` folder into the backup directory when it exists.
-- Remove the previous `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` when the chosen restart scope includes product specification after backup.
-- Remove the previous `PROGRESS.md` when the chosen restart scope includes progress tracking after backup.
-- Remove the previous `SESSION-HANDOFF.md` when the chosen restart scope includes session handoff after backup.
-- Remove the previous `feature-list.json` when the chosen restart scope includes feature tracking after backup.
-- After backup, remove only the files included in the chosen restart scope before continuing the new start flow.
+- 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 `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.
 - 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 three steps sequentially, updating the progress status (`current_step` in `.ahe/process_status.json`):
+- 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")
-  2. call "ahe-spec" (status: "ahe-spec")
-  3. call "ahe-update" (status: "ahe-update")
+  2. call "ahe-harness" (status: "ahe-harness")
 
 ### Harness Generation
 
@@ -71,7 +64,7 @@ Use this skill when the user invokes `$ahe-init`.
 
 ## Clarification Rule
 
-When the next setup step is not clear, follow the `ahe-thinking` protocol first. If `ahe-thinking` finds missing information, follow the `ahe-conversation` 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-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
 
@@ -91,7 +84,7 @@ When the next setup step is not clear, follow the `ahe-thinking` protocol first.
 - The answer must be specific enough to update `PROJECT_PURPOSE`.
 - The answer must make it clear whether initialization should continue with the current `AGENTS.md` or with a new purpose.
 - The answer must clearly identify whether Python guidance applies.
-- The answer must make the restart scope clear when existing harness files must be backed up or replaced.
+- The answer must make the restart scope clear when existing harness files must be replaced.
 - The answer must make overwrite intent explicit for existing template targets.
 - The answer must resolve any setup choice that blocks the next workflow step.
 

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

@@ -0,0 +1,35 @@
+---
+name: ahe-reviewer
+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-reviewer` as a user command.
+Use it when `ahe-thinker` 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`, `docs/PRODUCT.md`, `docs/INSTRUCTIONS.md`,
+  `feature-list.json`, `PROGRESS.md`, `SESSION-HANDOFF.md`, and `docs/todo.md`
+  when the question is about harness state.
+
+## Handoffs
+
+- Report findings back to `ahe-thinker` by default.
+- Call `ahe-harness` directly when review finds harness drift, stale tracking,
+  or Product.md / feature-list mismatches.
+- Call `ahe-conversator` 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/.codex/skills/ahe-solver/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: ahe-solver
+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-solver` as a user command.
+Use it when `ahe-thinker` decides that the next job is building or planning a
+feature.
+
+## Command Workflow: ahe-solver
+
+- Read the active feature context from `docs/PRODUCT.md`, `feature-list.json`,
+  `PROGRESS.md`, and any relevant code files.
+- Divide broad work into smaller problems when useful.
+- Plan each smaller problem before implementation.
+- Call `ahe-reviewer` when repo or code understanding is needed.
+- Call `ahe-conversator` when feature requirements, scope, or success criteria
+  are still unclear.
+- Report the solved step, remaining work, and recommended next agent back to
+  `ahe-thinker`.

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

@@ -0,0 +1,80 @@
+---
+name: ahe-thinker
+description: Internal AHE orchestration protocol for routing exact `ahe` and explicit `ahe <query>` requests through the AHE agent network.
+---
+
+# AHE Thinker
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-thinker` as a user command.
+Use it as the central decision layer for AHE work.
+
+## Purpose
+
+- Judge what is missing before another agent acts.
+- Judge the active `project`, `feature`, or `sub-feature`.
+- Decide which of `Why`, `What`, and `How` are still missing.
+- Choose the next internal agent: `ahe-reviewer`, `ahe-conversator`,
+  `ahe-harness`, or `ahe-solver`.
+- Receive each agent result, reassess the state, and decide the next step.
+
+## Routing Inputs
+
+- Exact `ahe` means continue existing harness work.
+- Exact `ahe init`, exact `ahe-init`, and exact `$ahe-init` stay on the
+  `$ahe-init` path.
+- Explicit `ahe <query>` means route the query through `ahe-thinker`.
+- Broad non-prefixed prompts must not activate AHE.
+
+## Size Preflight
+
+- Before reading full harness files, run
+  `sh .codex/skills/ahe-compression/scripts/check-harness-size.sh`.
+- If the detector exits with `COMPRESSION_REQUIRED` or code `2`, call
+  `ahe-compression` before normal routing.
+- Do not read oversized harness files wholesale before compression routing is
+  settled.
+
+## 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.
+- If the need is understanding repo code, harness drift, progress evidence, or
+  CodeGraph context, call `ahe-reviewer`.
+- If the need is user clarification, call `ahe-conversator`.
+- If the need is updating harness artifacts, product docs, feature tracking,
+  todo sync, or compression of completed history, call `ahe-harness`.
+- If the need is solving or decomposing feature work, call `ahe-solver`.
+
+## Interaction Model
+
+- `ahe-thinker` is centered, but direct worker-to-worker calls are allowed when
+  they are the obvious next step.
+- Typical loops:
+  - `ahe-thinker -> ahe-reviewer -> ahe-thinker`
+  - `ahe-thinker -> ahe-harness -> ahe-thinker`
+  - `ahe-thinker -> ahe-conversator -> ahe-thinker`
+  - `ahe-thinker -> ahe-solver -> ahe-thinker`
+- Allowed direct handoffs include:
+  - `ahe-harness -> ahe-conversator`
+  - `ahe-solver -> ahe-reviewer`
+  - `ahe-reviewer -> ahe-harness`
+- Every handoff must state the goal, reason, relevant files or context, and the
+  expected result.
+
+## Broad Intent Routing
+
+- Use `ahe-reviewer` for review-first requests.
+- Use `ahe-harness` for product, instructions, progress, feature-list, todo, or
+  compression maintenance.
+- Use `ahe-solver` for feature implementation planning or execution work.
+- Use `ahe-conversator` when no safe next step exists without user input.
+
+## Completion
+
+- Continue to the next skill or next unfinished feature until the active unit is
+  resolved.
+- Keep `docs/PRODUCT.md` as the canonical contract and `feature-list.json` as a
+  derived tracker.

package/README.md

@@ -1,204 +1,41 @@
 # Awesome Harness Engineering (AHE)
 
-AHE automatically builds and maintains project harnesses through Codex chat. It installs a set of Codex skills into your workspace, then guides you through defining your project specification, tracking features, and managing progress — all via natural conversation.
+AHE installs Codex skills that manage harness files through chat. The public
+entrypoints stay small: use `ahe init` to start or reset harness work, `ahe` to
+continue existing work, and `ahe <query>` for explicit AHE requests such as
+`ahe compress feature-list`.
 
----
-
-## 1. Installation
-
-### Quick Start (Recommended)
-
-```bash
-npx --yes --package=@ksuchoi216/ahe ahe install
-```
-
-### Global Install
-
-```bash
-npm install -g @ksuchoi216/ahe
-ahe install
-```
-
-### Local Development
-
-After cloning the repository:
-
-```bash
-npx --yes --package=file:. ahe install
-```
-
-### CLI Commands
-
-| Command | Description |
-|---|---|
-| `ahe install` | Install AHE skills into `.codex/` |
-| `ahe install --force` | Overwrite existing installation |
-| `ahe install --backup` | Backup existing installation before overwriting |
-| `ahe uninstall` | Remove all AHE skills, shared assets, and hooks |
-| `ahe doctor` | Check installation health and integrity |
-| `ahe version` | Print the current version |
-
----
-
-## 2. How to Use
-
-AHE works inside **Codex chat**. After installing via the terminal, open Codex chat in your workspace and type one of the commands below.
-
-### Chat Commands
-
-| Command | What it does |
-|---|---|
-| `ahe init` | **Start a new harness.** Creates harness skeleton files, asks about your project, and writes the product specification. |
-| `ahe` | **Continue existing work.** Inspects the current state, reports status, decides the next step, and keeps working. |
-
-> **Note:** Only exact commands trigger AHE. Normal messages like "explain ahe" or "what does ahe do" will not start any workflow.
-
-### Typical Workflow
-
-```
-# Step 1: Install AHE skills into your project
-$ ahe install
-
-# Step 2: Open Codex chat and initialize the harness
-> ahe init
-  → AHE asks about your project purpose, language, tech stack, constraints...
-  → Creates AGENTS.md, feature-list.json, PROGRESS.md, docs/PRODUCT.md, etc.
-
-# Step 3: Continue working — just type "ahe"
-> ahe
-  → AHE inspects the harness state and prints a status report
-  → Picks the next unfinished feature or asks for missing info
-  → Works on it, then updates tracking artifacts
-
-# Step 4: Keep iterating
-> ahe
-  → Reports progress, moves to the next feature
-  → Repeat until all features are done
-```
-
----
-
-## 3. How It Works
-
-### Skills Overview
-
-AHE is composed of five internal skills that coordinate automatically:
+## Installed Skills
 
 | Skill | Role |
-|---|---|
-| **ahe-init** | Entry point for new projects. Creates harness files, asks for project info, then calls ahe-spec and ahe-update. |
-| **ahe-thinking** | Internal decision engine. Evaluates clarity on **Why** / **What** / **How** for each work unit and routes to the right action. |
-| **ahe-conversation** | Internal question protocol. Asks exactly one focused question at a time when information is missing. |
-| **ahe-spec** | Writes and updates `docs/PRODUCT.md` (canonical source of truth) and `docs/INSTRUCTIONS.md`. |
-| **ahe-update** | Syncs tracking artifacts: `feature-list.json`, `PROGRESS.md`, `SESSION-HANDOFF.md`. |
-
-### Process Flow
-
-```mermaid
-flowchart TD
-    Install["<b>Terminal</b><br/>ahe install"] --> Chat["Open Codex chat<br/>in the workspace"]
-
-    Chat --> Command{"What did you type?"}
-    Command -->|"ahe init"| Init["<b>ahe-init</b><br/>New-start workflow"]
-    Command -->|"ahe"| Router["<b>AHE Router</b><br/>Inspect harness &amp; print status"]
-    Command -->|"other message"| Noop["No AHE workflow triggered"]
-
-    Router --> Classify{"Classify harness state"}
-    Classify -->|"Not enough spec"| Init
-    Classify -->|"Building features"| Feature["Continue next<br/>unfinished feature"]
-    Classify -->|"All completed"| AskNext["Ask user for<br/>the next task"]
-
-    Init --> Step1["<b>Step 1:</b> Setup<br/>AGENTS.md + templates"]
-    Step1 --> Step2["<b>Step 2: ahe-spec</b><br/>Write PRODUCT.md<br/>and INSTRUCTIONS.md"]
-    Step2 --> Step3["<b>Step 3: ahe-update</b><br/>Sync feature-list.json<br/>and PROGRESS.md"]
-    Step3 --> Done["Harness ready ✓"]
-
-    Feature --> Thinking["<b>ahe-thinking</b><br/>Check Why / What / How"]
-    Thinking --> Clear{"Clear enough<br/>to proceed?"}
-    Clear -->|"No"| Convo["<b>ahe-conversation</b><br/>Ask one focused question"]
-    Convo --> UserAnswer["User answers"]
-    UserAnswer --> Thinking
-    Clear -->|"Yes"| Execute["Execute the<br/>next safe step"]
-    Execute --> Update["<b>ahe-update</b><br/>Sync tracking artifacts"]
-    Update --> Done2["Ready for next<br/><code>ahe</code> command ✓"]
-```
-
-### Detailed Steps
-
-#### `ahe init` — New Start
-
-1. Scans the workspace for existing harness files.
-2. If files exist, asks the user what scope to restart (full restart, product-only, or custom).
-3. Backs up affected files to `.ahe/backups/`.
-4. Asks about project purpose, language, and tech stack.
-5. Deploys template files (`AGENTS.md`, `PROGRESS.md`, `SESSION-HANDOFF.md`, `feature-list.json`, `init.sh`).
-6. Calls **ahe-spec** → writes `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md`.
-7. Calls **ahe-update** → derives features and syncs tracking artifacts.
-
-#### `ahe` — Continue Work
-
-1. Hook injects the AHE router directive into the agent context.
-2. Router inspects all harness files and prints a status table.
-3. Classifies the current state:
-   - **"Not enough spec"** → routes to `ahe-init` to fill gaps.
-   - **"Building features"** → picks the next unfinished feature from `feature-list.json`.
-   - **"All completed"** → asks the user for the next task.
-4. **ahe-thinking** checks clarity (Why / What / How) for the current work unit.
-5. If unclear → **ahe-conversation** asks exactly one question, then re-evaluates.
-6. If clear → executes the next safe step.
-7. **ahe-update** syncs all tracking artifacts at the end.
-
-#### Execution Loop
-
-The core loop repeats until the work unit is done:
-
-```
-thinking → conversation (if needed) → execution → thinking
-```
-
----
-
-## Project Structure
-
-After `ahe install`, the following structure is added to your workspace:
+| --- | --- |
+| `ahe-init` | New-start workflow that prepares the workspace and hands product/tracking work to `ahe-harness`. |
+| `ahe-thinker` | Centered internal router that judges what is missing and chooses the next agent. |
+| `ahe-reviewer` | Review agent for repo code, harness state, and CodeGraph context. |
+| `ahe-conversator` | Clarification agent for recursive user conversation. |
+| `ahe-harness` | Harness-management agent for product docs, instructions, feature tracking, todo sync, and compression-aware maintenance. |
+| `ahe-solver` | Feature-solving agent that divides and plans implementation work. |
+| `ahe-compression` | Internal helper that detects oversized harness files before broad reads. |
 
-```
-your-project/
-├── .codex/
-│   ├── skills/
-│   │   ├── ahe-init/           # New-start workflow skill
-│   │   ├── ahe-conversation/   # Internal question protocol
-│   │   ├── ahe-thinking/       # Internal decision engine
-│   │   ├── ahe-spec/           # Specification writer
-│   │   └── ahe-update/         # Tracking artifact syncer
-│   ├── ahe-shared/
-│   │   ├── templates/          # Harness file templates
-│   │   └── schemas/            # Validation schemas
-│   └── hooks/
-│       ├── hooks.json          # Chat command trigger patterns
-│       └── ahe-hook.js         # Hook script that injects directives
-```
+## Routing Model
 
-After `ahe init`, the harness files are created in your project root:
+The internal model is centered but flexible:
 
-```
-your-project/
-├── docs/
-│   ├── PRODUCT.md              # Product specification (source of truth)
-│   └── INSTRUCTIONS.md         # Implementation instructions
-├── .ahe/
-│   └── process_status.json     # Workflow state persistence
-├── AGENTS.md                   # Project objectives and agent rules
-├── feature-list.json           # Feature state tracker (derived from PRODUCT.md)
-├── PROGRESS.md                 # Session continuity log
-├── SESSION-HANDOFF.md          # Handoff notes between sessions
-└── init.sh                     # Standard startup/verification script
-```
+`query -> ahe-thinker -> ahe-reviewer | ahe-conversator | ahe-harness | ahe-solver`
 
-## Agent Working Rules
+- `ahe-thinker` is the center of judgment.
+- Worker agents can call each other directly when that is the logical next
+  action.
+- Typical direct handoffs are `ahe-harness -> ahe-conversator`,
+  `ahe-solver -> ahe-reviewer`, and `ahe-reviewer -> ahe-harness`.
 
-If you are an AI agent working on this repository, please strictly follow the guidelines in [AGENTS.md](AGENTS.md). It includes critical instructions regarding the definition of done, verification commands, and file modification rules (e.g., you must update `PROGRESS.md` and `feature-list.json` appropriately).
+## Query Examples
 
-## License
+- `ahe`
+- `ahe init`
+- `ahe compress feature-list`
+- `ahe update product spec`
+- `ahe add dashboard export feature`
 
-MIT
+Only exact `ahe`, exact `ahe init`, exact `ahe-init`, exact `$ahe-init`, and
+explicit `ahe <query>` activate the hook. Broad non-prefixed prompts do not.