@ksuchoi216/ahe 0.1.0

package/.codex/ahe-shared/schemas/feature-list-schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AHE Feature List",
+  "type": "object",
+  "required": [
+    "features"
+  ],
+  "properties": {
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/.codex/ahe-shared/schemas/process_status.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "AHE Process Status",
+  "type": "object",
+  "required": [
+    "version",
+    "current_command",
+    "current_step",
+    "workflow_complete",
+    "updated_at"
+  ],
+  "properties": {
+    "version": {
+      "type": "string"
+    },
+    "current_command": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "current_step": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "The current step of the active workflow. For the ahe-init command, it represents the active stage being executed sequentially: 'ahe-init', 'ahe-spec', or 'ahe-update'."
+    },
+    "workflow_complete": {
+      "type": "boolean"
+    },
+    "updated_at": {
+      "type": [
+        "string",
+        "null"
+      ]
+    }
+  },
+  "additionalProperties": true
+}

package/.codex/ahe-shared/templates/AGENTS.md

@@ -0,0 +1,64 @@
+# {{AGENT_FILE_NAME}}
+
+{{PROJECT_PURPOSE}}
+
+## Startup Workflow
+
+Before writing code:
+
+1. **Confirm working directory** with `pwd`
+2. **Read this file** completely
+3. **Read project docs if present** (`docs/ARCHITECTURE.md`, `docs/PRODUCT.md`, `docs/INSTRUCTIONS.md`, `docs/TODO.md`, README, or equivalent)
+4. **Run `./init.sh`** to verify environment is healthy
+5. **Read `feature_list.json`** to see current feature state
+6. **Review recent commits** with `git log --oneline -5`
+
+If baseline verification is failing, repair that first before adding new scope.
+
+## Working Rules
+
+- **One feature at a time**: Pick exactly one unfinished feature from `feature_list.json`
+- **Verification required**: Don't claim done without running verification commands
+- **Update artifacts**: Before ending session, update `progress.md` and `feature_list.json`
+- **Stay in scope**: Don't modify files unrelated to the current feature
+- **Leave clean state**: Next session must be able to run `./init.sh` immediately
+
+## Required Artifacts
+
+- `feature_list.json` — Feature state tracker (source of truth)
+- `progress.md` — Session continuity log
+- `init.sh` — Standard startup and verification path
+- `session-handoff.md` — Optional, for larger sessions
+
+## Definition of Done
+
+A feature is done only when ALL of the following are true:
+
+- [ ] Target behavior is implemented
+- [ ] Required verification actually ran (tests / lint / type-check)
+- [ ] Evidence recorded in `feature_list.json` or `progress.md`
+- [ ] Repository remains restartable from standard startup path
+
+## End of Session
+
+Before ending a session:
+
+1. Update `progress.md` with current state
+2. Update `feature_list.json` with new feature status
+3. Record any unresolved risks or blockers
+4. Commit with descriptive message once work is in safe state
+5. Leave repo clean enough for next session to run `./init.sh` immediately
+
+## Verification Commands
+- Tests: pytest tests/ -x
+- Type check: mypy src/ --strict
+- Lint: ruff check src/
+- Full verification: make check (includes all above)
+
+## Escalation
+
+If you encounter:
+- **Architecture decisions**: Consult project architecture docs if present, otherwise ask user
+- **Unclear requirements**: Check product/requirements docs if present, otherwise ask user
+- **Repeated test failures**: Update progress, flag for human review
+- **Scope ambiguity**: Re-read `feature_list.json` for definition of done

package/.codex/ahe-shared/templates/INSTRUCTIONS.md

@@ -0,0 +1,29 @@
+# Instructions
+
+## MUST NOT CHANGE INSTRUCTIONS
+### Code & Refactoring Style
+
+Write code that is easy to read, maintain, and test.
+
+Readability is the highest priority. Prefer simple, intuitive code that another developer can quickly understand.
+
+Follow these rules:
+
+1. Use clear and descriptive names.
+2. Keep functions and classes focused and cohesive.
+3. Remove unnecessary duplication.
+4. Prefer self-explanatory code over comments.
+5. Follow the project's existing style and conventions. Use PEP 8 for Python unless the project requires otherwise.
+6. Make exception handling explicit and easy to understand.
+7. Keep inputs, outputs, and side effects clear.
+8. Structure code so it is easy to test.
+9. Avoid excessive abstraction, indirection, and over-engineering.
+10. Do not split code into too many small functions, classes, or files.
+11. Prefer files under approximately 500 lines when reasonable.
+12. Do not introduce structural changes solely to satisfy line-count targets. Any extraction or separation should provide a clear readability or maintainability benefit.
+13. Favor practical simplicity over theoretical purity.
+
+When modifying existing code, preserve behavior unless a change is explicitly requested.
+
+## CAN CHANGE INSTRUCTIONS
+

package/.codex/ahe-shared/templates/PRODUCT.md

@@ -0,0 +1,7 @@
+# PRODUCT.md
+
+## Product Name
+
+## Product Objective
+
+## Requirements

package/.codex/ahe-shared/templates/PROGRESS.md

@@ -0,0 +1,51 @@
+# Session Progress Log
+
+## Current State
+
+**Last Updated:** YYYY-MM-DD HH:MM
+**Session ID:** [optional]
+**Active Feature:** [feat-XXX - Feature Name]
+
+## Status
+
+### What's Done
+
+- [x] [Completed item 1]
+- [x] [Completed item 2]
+
+### What's In Progress
+
+- [ ] [Current work item]
+  - Details: [specific task]
+  - Blockers: [if any]
+
+### What's Next
+
+1. [Next action item]
+2. [Following action item]
+
+## Blockers / Risks
+
+- [ ] [Blocker 1]: [description, impact]
+- [ ] [Risk 1]: [description, mitigation]
+
+## Decisions Made
+
+- **[Decision 1]**: [description]
+  - Context: [why this decision was made]
+  - Alternatives considered: [what else was discussed]
+
+## Files Modified This Session
+
+- `path/to/file1.ts` - [brief description of change]
+- `path/to/file2.ts` - [brief description of change]
+
+## Evidence of Completion
+
+- [ ] Tests pass: `[command and output]`
+- [ ] Type check clean: `[command and output]`
+- [ ] Manual verification: `[what was tested]`
+
+## Notes for Next Session
+
+[Free-form notes that will help the next session pick up context]

package/.codex/ahe-shared/templates/SESSION-HANDOFF.md

@@ -0,0 +1,40 @@
+# Session Handoff
+
+## Current Objective
+
+- Goal:
+- Current status:
+- Branch / commit:
+
+## Completed This Session
+
+- [ ] 
+
+## Verification Evidence
+
+| Check | Command | Result | Notes |
+|---|---|---|---|
+|  |  |  |  |
+
+## Files Changed
+
+- 
+
+## Decisions Made
+
+- 
+
+## Blockers / Risks
+
+- 
+
+## Next Session Startup
+
+1. Read `AGENTS.md`.
+2. Read `feature_list.json` and `progress.md`.
+3. Review this handoff.
+4. Run `./init.sh` or the documented verification command before editing.
+
+## Recommended Next Step
+
+- 

package/.codex/ahe-shared/templates/feature-list.json

@@ -0,0 +1,44 @@
+{
+  "features": [
+    {
+      "id": "feat-001",
+      "name": "Project Setup",
+      "description": "Confirm the project can install dependencies, run verification, and start from a clean checkout",
+      "dependencies": [],
+      "status": "not-started",
+      "evidence": ""
+    },
+    {
+      "id": "feat-002",
+      "name": "First User-Facing Feature",
+      "description": "Replace this placeholder with the first concrete behavior the agent should implement",
+      "dependencies": ["feat-001"],
+      "status": "not-started",
+      "evidence": ""
+    },
+    {
+      "id": "feat-003",
+      "name": "Verification Coverage",
+      "description": "Add or confirm tests, type checks, linting, or manual verification for the active feature",
+      "dependencies": ["feat-002"],
+      "status": "not-started",
+      "evidence": ""
+    },
+    {
+      "id": "feat-004",
+      "name": "Documentation Update",
+      "description": "Update README, architecture notes, or product docs affected by the implemented feature",
+      "dependencies": ["feat-003"],
+      "status": "not-started",
+      "evidence": ""
+    },
+    {
+      "id": "feat-005",
+      "name": "Cleanup and Handoff",
+      "description": "Record verification evidence, update progress.md, and leave a clear next-session path",
+      "dependencies": ["feat-004"],
+      "status": "not-started",
+      "evidence": ""
+    }
+  ]
+}

package/.codex/ahe-shared/templates/init.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+set -e
+
+echo "=== Harness Initialization ==="
+
+conda_env_name=""
+if [ -f environment.yml ]; then
+  conda_env_name="$(sed -n 's/^name:[[:space:]]*//p' environment.yml | head -n 1)"
+elif [ -f conda.yaml ]; then
+  conda_env_name="$(sed -n 's/^name:[[:space:]]*//p' conda.yaml | head -n 1)"
+fi
+if [ -n "$conda_env_name" ]; then
+  echo "=== Conda environment: $conda_env_name ==="
+fi
+
+if [ ! -f pyproject.toml ] && [ ! -f requirements.txt ] && [ ! -f setup.py ] && [ ! -f environment.yml ] && [ ! -f conda.yaml ]; then
+  echo "Error: No Python manifest (pyproject.toml, requirements.txt, setup.py, environment.yml, or conda.yaml) found."
+  exit 1
+fi
+
+# Ensure virtual environment exists
+if [ ! -d ".venv" ]; then
+  echo "=== Creating virtual environment ==="
+  uv venv
+fi
+
+# Activate virtual environment
+echo "=== Activating virtual environment ==="
+source .venv/bin/activate
+
+# Install dependencies
+echo "=== Installing dependencies ==="
+if [ -f pyproject.toml ]; then
+  if grep -q "^\[project\]" pyproject.toml || grep -q "^\[build-system\]" pyproject.toml; then
+    uv pip install -e .
+  fi
+fi
+if [ -f setup.py ]; then
+  uv pip install -e .
+fi
+if [ -f requirements.txt ]; then
+  uv pip install -r requirements.txt
+fi
+if [ -f requirements-dev.txt ]; then
+  uv pip install -r requirements-dev.txt
+fi
+if [ -f requirements-test.txt ]; then
+  uv pip install -r requirements-test.txt
+fi
+
+echo "=== Running Python verification ==="
+# Check if pytest is installed and run it, otherwise warn or skip
+if python -c "import pytest" >/dev/null 2>&1; then
+  python -m pytest
+else
+  echo "pytest not found. Skipping tests."
+fi
+
+# Compile Python source files to check for syntax errors
+python -m compileall .
+
+echo "=== Verification Complete ==="
+echo ""
+echo "Next steps:"
+echo "1. Read feature_list.json to see current feature state"
+echo "2. Pick ONE unfinished feature to work on"
+echo "3. Implement only that feature"
+echo "4. Re-run verification before claiming done"

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

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+const AHE_DIRECTIVE_MARKER = "<ahe-mode>";
+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:",
+    "",
+    "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.",
+    "",
+    "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:",
+    "   - 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.",
+    "",
+    "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.",
+    "   - 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");
+
+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 isExactAheCommand(prompt) {
+    return normalizePrompt(prompt) === "ahe";
+}
+
+function isExactAheInitCommand(prompt) {
+    const normalizedPrompt = normalizePrompt(prompt);
+    return (
+        normalizedPrompt === "ahe init" ||
+        normalizedPrompt === "ahe-init" ||
+        normalizedPrompt === "$ahe-init"
+    );
+}
+
+function normalizePrompt(prompt) {
+    return prompt.trim().toLowerCase();
+}
+
+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 (e) {
+        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");
+        }
+    }
+}
+
+main().catch(() => {});

package/.codex/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .codex/hooks/ahe-hook.js",
+            "timeout": 5,
+            "statusMessage": "AHE: Checking Keyword Trigger"
+          }
+        ]
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,73 @@
+---
+name: ahe-conversation
+description: Internal AHE protocol for recursive clarification, conversation state, and resume-aware workflow guidance.
+---
+
+# AHE Conversation
+
+This is an internal AHE protocol skill, not a user-facing command.
+
+Do not treat `$ahe-conversation` as a user command.
+Use it only when another AHE workflow skill needs more conversation before it can
+continue safely.
+Use it after `ahe-thinking` identifies a missing decision or missing `Why`,
+`What`, or `How`.
+
+## When to Converse
+
+Start or continue an AHE conversation when the missing answer materially changes
+one of these:
+
+- Project purpose or target user.
+- Product behavior, scope, success criteria, or out-of-scope boundaries.
+- Implementation instructions, architecture direction, or verification commands.
+- Harness file ownership, overwrite behavior, or reset behavior.
+- `.ahe/process_status.json`, `PROGRESS.md`, or `SESSION-HANDOFF.md` state.
+- The next workflow step when several valid paths are possible.
+- The missing `Why`, `What`, or `How` for the current `project`, `feature`, or
+  `sub-feature`.
+
+If the missing detail can be inferred safely from existing files, infer
+conservatively and record the assumption in the active workflow artifact.
+
+## Conversation Protocol
+
+- Inspect relevant existing files before asking.
+- Let `ahe-thinking` judge what is missing before you ask.
+- Explain the decision point briefly when context helps the user answer.
+- Ask exactly one question at a time.
+- Use a Codex-supported structured response request when meaningful options exist.
+- Provide 2-3 mutually exclusive options when useful, and allow custom input when
+  predefined options are not enough.
+- Keep each question specific to the active AHE workflow.
+- Think through what the answer will unlock before asking.
+- Ask again when the answer is vague, off-topic, contradictory, or incomplete
+  according to the calling skill's clarification criteria.
+- Continue until the calling workflow has enough information to act.
+- Do not expand the scope of questioning beyond the missing detail that
+  `ahe-thinking` identified.
+
+## State Persistence
+
+Before pausing for user input, update `.ahe/process_status.json` when it exists
+or when the active workflow uses it:
+
+- Set the active command or skill name.
+- Set `workflow_complete` to `false`.
+- Set `current_step` to the pending question, decision point, or missing field.
+- Refresh `updated_at`.
+- Preserve already collected project and product data.
+
+Update `PROGRESS.md` and `SESSION-HANDOFF.md` when the pending conversation
+changes the active workflow state, blocks completion, or affects the next
+session's startup path.
+
+## Resume Protocol
+
+When resuming after the user answers:
+
+- Read `.ahe/process_status.json` and the relevant workflow artifacts.
+- Summarize the already collected data briefly.
+- Identify the missing field or decision that is still blocking progress.
+- Ask the next focused question, or continue the calling workflow when the
+  answer satisfies its clarification criteria.

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

@@ -0,0 +1,103 @@
+---
+name: ahe-init
+description: Initialize AHE in the current workspace and create the base harness files.
+---
+
+# AHE Init
+
+Use this skill when the user invokes `$ahe-init`.
+
+## Command Workflow: ahe-init
+
+### 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.
+
+### Sequential Conversation Flow
+
+- 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.
+- 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 `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.
+- 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.
+- 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`):
+  1. complete the embedded init setup work (status: "ahe-init")
+  2. call "ahe-spec" (status: "ahe-spec")
+  3. call "ahe-update" (status: "ahe-update")
+
+### 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 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-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.
+
+### User Response Target
+
+- Collect the project purpose, language choice, and overwrite decisions needed to continue initialization safely.
+
+### Questions to Ask
+
+- Ask whether the existing `AGENTS.md` is correct.
+- Ask what restart scope the user wants when harness files already exist.
+- Ask what the purpose of this project is when `AGENTS.md` is missing or incorrect.
+- Ask whether the project language is Python and ask which language is used when the answer is no or custom.
+- Ask whether template files should be overwritten when target files already exist.
+- Ask follow-up questions when the restart scope, purpose, language, or overwrite choice is still unclear.
+
+### Clarification Criteria
+
+- 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 overwrite intent explicit for existing template targets.
+- The answer must resolve any setup choice that blocks the next workflow step.
+
+### Re-ask When
+
+- Ask again when the answer is vague, off-topic, contradictory, or incomplete.
+- Ask again when the answer does not identify the project goal, target user, or intended outcome clearly enough to continue initialization.
+- Ask again when the language answer is ambiguous or does not clearly name the language in use.
+- Ask again when the overwrite decision is not explicit.

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

@@ -0,0 +1,63 @@
+---
+name: ahe-spec
+description: Internal AHE specification workflow for updating product and instructions docs.
+---
+
+# AHE Spec
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-spec` as a user command.
+Use it after `ahe-thinking` decides that specification work must continue.
+
+## Command Workflow: ahe-spec
+
+### Spec Inspection
+
+- Read `docs/PRODUCT.md` if it exists.
+- Read `docs/INSTRUCTIONS.md` if it exists.
+- Read `AGENTS.md`, `feature-list.json`, `PROGRESS.md`, and `SESSION-HANDOFF.md`.
+
+### Sequential Spec Conversation Flow
+
+- `docs/PRODUCT.md` is the canonical home for product specification details collected during `ahe init`.
+- Clarify product goal, scope, and success criteria when `docs/PRODUCT.md` needs to change.
+- Clarify project instructions when `docs/INSTRUCTIONS.md` needs to change.
+- Draft the relevant specification updates in chat and ask for user approval.
+- Ask recursively for more detail until the affected specification areas are clear and approved.
+
+### Spec Completion
+
+- 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`.
+- When updating `docs/INSTRUCTIONS.md`, only allow additions/removals/edits to instructions inside `## CAN CHANGE INSTRUCTIONS`; preserve `## MUST NOT CHANGE INSTRUCTIONS`.
+- Update `.ahe/process_status.json`.
+- Update `PROGRESS.md` and `SESSION-HANDOFF.md` when specification changes affect active work.
+
+## Clarification Rule
+
+When the next specification 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.
+
+### User Response Target
+
+- Collect the product or instructions details required to update the relevant specification docs.
+
+### 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 should be documented as an instruction.
+
+### Clarification Criteria
+
+- The answer must identify the target user, product goal, main behavior, scope, and success signal when product details are changing.
+- The answer must describe any instruction and its practical meaning clearly enough that another engineer can follow it.
+- The answer must be concrete enough to update the relevant specification docs without guessing missing intent.
+
+### Re-ask When
+
+- Ask again when the answer is vague, contradictory, or incomplete.
+- Ask again when the response gives features without explaining the user goal or success criteria.
+- Ask again when the response names an instruction topic without the actual rule.

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

@@ -0,0 +1,88 @@
+---
+name: ahe-thinking
+description: Internal AHE orchestration protocol for deciding what to clarify, what to execute, and what to do next.
+---
+
+# AHE Thinking
+
+This is an internal AHE protocol skill, not a user-facing command.
+
+Do not treat `$ahe-thinking` as a user command.
+Use it before and between AHE workflow actions when the next safe step is not
+already obvious.
+
+## Purpose
+
+- Judge what is missing before another AHE workflow acts.
+- Decide whether the current unit is clear enough to execute safely.
+- Call `ahe-conversation` only when clarification is still needed.
+- Continue to the next skill or next unfinished feature when the path is clear.
+
+## Units of Work
+
+Inspect the current unit as `project`, `feature`, or `sub-feature`.
+
+- `project`: overall goal, target user, expected outcome, and delivery
+  direction.
+- `feature`: one concrete capability or work item under the project.
+- `sub-feature`: one smaller capability or step under a feature.
+
+## Clarity Judgment
+
+Judge the current unit against `Why`, `What`, and `How`.
+
+- `Why`: why this unit matters, what problem it solves, or what purpose it
+  serves.
+- `What`: what result, behavior, or output should be built.
+- `How`: how the work should be approached when methodology or architecture
+  matters.
+
+### Project Rule
+
+For a `project`, require `Why`, `What`, and `How` by default before moving
+forward.
+
+### Feature Rule
+
+For a `feature` or `sub-feature`, require only the minimum needed to proceed
+safely.
+
+- If the feature is already clear from the project context, do not ask all
+  three again.
+- If only the result is missing, ask only `What`.
+- If the feature goal is clear but the implementation direction is risky or
+  materially different, ask `How`.
+- If the feature exists but its purpose is unclear, ask `Why`.
+
+## Next-Step Decision
+
+- 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 work.
+- `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` form the required harness contract. `docs/PRODUCT.md` is the product/specification source of truth, and
+  `feature-list.json` is a derived tracker. Do not write specific feature items
+  to `feature-list.json` until `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` are established.
+- If other harness essentials are missing or inconsistent, classify the state as
+  `harness engineering not enough` and continue the harness-building workflow.
+- If the harness exists and there is unfinished tracked work, classify the
+  state as `in the middle of building features` and continue the first safe
+  unfinished feature.
+- If tracked work is complete and no obvious essential harness gap remains,
+  classify the state as `completed all` and ask for the next task.
+
+## Conversation Handoff
+
+If clarity is missing, call `ahe-conversation` with the exact missing `Why`,
+`What`, or `How`.
+
+- Explain which unit is blocked.
+- Explain what answer will unlock the next action.
+- Ask for only the minimum missing detail.
+- When the path is clear, continue to the next skill or next unfinished feature.
+
+## Execution Loop
+
+Follow this loop whenever AHE is routing or continuing work:
+
+`thinking -> conversation if needed -> execution -> thinking`
+
+After execution, reassess the active unit before choosing the next step.

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

@@ -0,0 +1,66 @@
+---
+name: ahe-update
+description: Internal AHE workflow for synchronizing tracked work and handoff artifacts.
+---
+
+# AHE Update
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-update` as a user command.
+Use it after `ahe-thinking` decides that tracked harness work should be synchronized.
+
+## Command Workflow: ahe-update
+
+- Read `feature-list.json`.
+- Read `PROGRESS.md` if it exists.
+- Read `SESSION-HANDOFF.md`.
+- Read `docs/todo.md` when it exists.
+- If the user is adding new work, clarify the todo item, append it under the last `## TODO` section in `docs/todo.md`, and create that section when it does not exist.
+- Apply the queued `docs/todo.md` content to `docs/PRODUCT.md`. If `docs/PRODUCT.md` does not exist, create it.
+- Remove the applied content from `docs/todo.md` because that todo content was already applied 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`.
+
+## Clarification Rule
+
+When the next update 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.
+
+### User Response Target
+
+- Collect either an actionable todo entry to queue or a clear instruction to synchronize the existing queued work.
+
+### Questions to Ask
+
+- Ask what work needs to be done when the user is adding a new todo item.
+- Ask which file, feature area, or workflow the todo affects.
+- Ask what outcome or completion signal the todo should capture.
+- Ask whether the user wants to queue new work, apply queued work, or do both when that is unclear.
+
+### Clarification Criteria
+
+- The answer must describe actionable work, the affected area, and the intended outcome when queuing a todo item.
+- The answer must be clear enough to decide whether to queue work, apply queued work, or do both.
+
+### Re-ask When
+
+- Ask again when the answer is too broad, off-topic, or only names a topic without describing the work.
+- Ask again when dependencies, affected area, intended outcome, or update action are still unclear.
+
+## 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/README.md

@@ -0,0 +1,59 @@
+# Awesome Harness Engineering (ahe-codex)
+
+Codex chat workflow skill installer for Awesome Harness Engineering.
+
+This project provides a set of Codex skills and templates to automatically build project harnesses. It is designed to be used directly within a Codex chat conversation, guiding users through the engineering workflow.
+
+## Installation
+
+### For End Users
+To install the Codex skills in your current workspace, run:
+
+```bash
+npx --yes --package=ahe-codex ahe install
+```
+
+Alternatively, you can install it globally:
+
+```bash
+npm install -g ahe-codex
+ahe install
+```
+
+### For Local Development
+If you have cloned the repository and want to install it locally:
+
+```bash
+npx --yes --package=file:. ahe install
+```
+
+## Usage
+
+Once installed, the `ahe` skills will be added to your `.codex` directory.
+
+1. **Open Codex chat** in your workspace.
+2. Use the `ahe init` skill to start a new harness.
+3. Use exact `ahe` skills (like `ahe-conversation`, `ahe-thinking`, `ahe-spec`, `ahe-update`) to continue your existing harness work.
+
+### Available CLI Commands
+
+The command-line interface is primarily used for the installation and maintenance of the Codex skills:
+
+- `ahe install [--force] [--backup]`: Installs or updates the skills in your `.codex/` directory.
+- `ahe doctor`: Checks the health and integrity of your AHE skill installation.
+- `ahe version`: Prints the current version.
+
+## Project Structure
+
+- `bin/ahe`: The main CLI executable for installing the skills.
+- `.codex/skills/`: Contains the managed Codex skills (`ahe-init`, `ahe-conversation`, `ahe-thinking`, `ahe-spec`, `ahe-update`).
+- `.codex/ahe-shared/`: Contains shared assets like `templates` and `schemas`.
+- `AGENTS.md`: Defines the project objectives, global rules, and startup workflow.
+
+## Agent Working Rules
+
+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).
+
+## License
+
+MIT

package/bin/ahe

@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+readonly VERSION="0.1.0"
+SCRIPT_PATH="${BASH_SOURCE[0]}"
+
+while [ -L "${SCRIPT_PATH}" ]; do
+  SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${SCRIPT_PATH}")" && pwd)"
+  SCRIPT_PATH="$(readlink "${SCRIPT_PATH}")"
+
+  case "${SCRIPT_PATH}" in
+    /*) ;;
+    *) SCRIPT_PATH="${SCRIPT_DIR}/${SCRIPT_PATH}" ;;
+  esac
+done
+
+readonly SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "${SCRIPT_PATH}")" && pwd)"
+readonly PACKAGE_ROOT="$(CDPATH= cd -- "${SCRIPT_DIR}/.." && pwd)"
+readonly SOURCE_SKILLS_DIR="${PACKAGE_ROOT}/.codex/skills"
+readonly SOURCE_SHARED_DIR="${PACKAGE_ROOT}/.codex/ahe-shared"
+readonly SOURCE_HOOKS_DIR="${PACKAGE_ROOT}/.codex/hooks"
+readonly MANAGED_SKILLS=(
+  "ahe-init"
+  "ahe-conversation"
+  "ahe-thinking"
+  "ahe-spec"
+  "ahe-update"
+)
+
+usage() {
+  cat <<'EOF'
+Usage:
+  ahe install [--force] [--backup]
+  ahe uninstall
+  ahe doctor
+  ahe version
+EOF
+}
+
+backup_existing_installation() {
+  local target_dir="$1"
+  local backup_root="$2"
+  local backup_name="$3"
+  local timestamp
+
+  timestamp="$(date '+%Y%m%d-%H%M%S')"
+  mkdir -p "${backup_root}"
+  mv "${target_dir}" "${backup_root}/${backup_name}-${timestamp}"
+}
+
+install_skill() {
+  local force="false"
+  local backup="false"
+
+  while [ "$#" -gt 0 ]; do
+    case "$1" in
+      --force)
+        force="true"
+        ;;
+      --backup)
+        backup="true"
+        ;;
+      *)
+        printf 'Unknown install option: %s\n' "$1" >&2
+        usage >&2
+        exit 1
+        ;;
+    esac
+    shift
+  done
+
+  if [ ! -d "${SOURCE_SKILLS_DIR}" ]; then
+    printf 'Packaged skill files are missing: %s\n' "${SOURCE_SKILLS_DIR}" >&2
+    exit 1
+  fi
+
+  if [ ! -d "${SOURCE_SHARED_DIR}" ]; then
+    printf 'Packaged shared files are missing: %s\n' "${SOURCE_SHARED_DIR}" >&2
+    exit 1
+  fi
+
+  local target_skills_dir="${PWD}/.codex/skills"
+  local target_shared_dir="${PWD}/.codex/ahe-shared"
+  local target_hooks_dir="${PWD}/.codex/hooks"
+  local backup_dir="${PWD}/.codex/_backups"
+  local skill_name=""
+  local skill_target=""
+
+  for skill_name in "${MANAGED_SKILLS[@]}"; do
+    skill_target="${target_skills_dir}/${skill_name}"
+
+    if [ -e "${skill_target}" ]; then
+      if [ "${backup}" = "true" ]; then
+        backup_existing_installation "${skill_target}" "${backup_dir}" "${skill_name}"
+      elif [ "${force}" != "true" ]; then
+        cat <<EOF >&2
+AHE skill is already installed at:
+  ${skill_target}
+
+Re-run with --force to overwrite or --backup to move the existing install aside first.
+EOF
+        exit 1
+      else
+        rm -rf "${skill_target}"
+      fi
+    fi
+  done
+
+  if [ -e "${target_shared_dir}" ]; then
+    if [ "${backup}" = "true" ]; then
+      backup_existing_installation "${target_shared_dir}" "${backup_dir}" "ahe-shared"
+    elif [ "${force}" = "true" ]; then
+      rm -rf "${target_shared_dir}"
+    else
+      cat <<EOF >&2
+AHE shared assets are already installed at:
+  ${target_shared_dir}
+
+Re-run with --force to overwrite or --backup to move the existing install aside first.
+EOF
+      exit 1
+    fi
+  fi
+
+  if [ -e "${target_hooks_dir}" ]; then
+    if [ "${backup}" = "true" ]; then
+      backup_existing_installation "${target_hooks_dir}" "${backup_dir}" "hooks"
+    elif [ "${force}" = "true" ]; then
+      rm -rf "${target_hooks_dir}"
+    else
+      cat <<EOF >&2
+AHE hooks are already installed at:
+  ${target_hooks_dir}
+
+Re-run with --force to overwrite or --backup to move the existing install aside first.
+EOF
+      exit 1
+    fi
+  fi
+
+  mkdir -p "${target_skills_dir}"
+  for skill_name in "${MANAGED_SKILLS[@]}"; do
+    cp -R "${SOURCE_SKILLS_DIR}/${skill_name}" "${target_skills_dir}/${skill_name}"
+  done
+  cp -R "${SOURCE_SHARED_DIR}" "${target_shared_dir}"
+  cp -R "${SOURCE_HOOKS_DIR}" "${target_hooks_dir}"
+
+ cat <<EOF
+AHE Codex skill installed.
+
+Next:
+1. Open Codex chat in this workspace.
+2. Use \`ahe init\` for a new start.
+3. Use exact \`ahe\` to continue existing harness work.
+EOF
+}
+
+doctor() {
+  local target_skills_dir="${PWD}/.codex/skills"
+  local target_shared_dir="${PWD}/.codex/ahe-shared"
+  local target_hooks_dir="${PWD}/.codex/hooks"
+  local skill_name=""
+
+  for skill_name in "${MANAGED_SKILLS[@]}"; do
+    if [ ! -f "${target_skills_dir}/${skill_name}/SKILL.md" ]; then
+      printf 'Missing: %s/%s/SKILL.md\n' "${target_skills_dir}" "${skill_name}" >&2
+      exit 1
+    fi
+  done
+
+  if [ ! -d "${target_shared_dir}/templates" ]; then
+    printf 'Missing: %s/templates\n' "${target_shared_dir}" >&2
+    exit 1
+  fi
+
+  if [ ! -d "${target_shared_dir}/schemas" ]; then
+    printf 'Missing: %s/schemas\n' "${target_shared_dir}" >&2
+    exit 1
+  fi
+
+  if [ ! -f "${target_hooks_dir}/hooks.json" ]; then
+    printf 'Missing: %s/hooks.json\n' "${target_hooks_dir}" >&2
+    exit 1
+  fi
+
+  printf 'AHE skill installation looks healthy.\n'
+}
+
+uninstall_skill() {
+  local target_skills_dir="${PWD}/.codex/skills"
+  local target_shared_dir="${PWD}/.codex/ahe-shared"
+  local target_hooks_dir="${PWD}/.codex/hooks"
+  local skill_name=""
+
+  echo "Uninstalling AHE skills from ${PWD}/.codex..."
+
+  for skill_name in "${MANAGED_SKILLS[@]}"; do
+    rm -rf "${target_skills_dir}/${skill_name}"
+  done
+
+  rm -rf "${target_shared_dir}"
+  rm -rf "${target_hooks_dir}"
+
+  echo "AHE skills uninstalled successfully."
+}
+
+main() {
+  if [ "$#" -eq 0 ]; then
+    usage
+    exit 1
+  fi
+
+  local command="$1"
+  shift
+
+  case "${command}" in
+    install)
+      install_skill "$@"
+      ;;
+    uninstall)
+      uninstall_skill
+      ;;
+    doctor)
+      doctor
+      ;;
+    version)
+      printf '%s\n' "${VERSION}"
+      ;;
+    *)
+      printf 'Unknown command: %s\n' "${command}" >&2
+      usage >&2
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ksuchoi216/ahe",
+  "version": "0.1.0",
+  "description": "Codex chat workflow skill installer for Awesome Harness Engineering",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ahe": "./bin/ahe"
+  },
+  "scripts": {
+    "test": "pytest tests/ -x",
+    "prepublishOnly": "npm run test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ksuchoi216/awesome_harness_engineering.git"
+  },
+  "keywords": [
+    "codex",
+    "agent",
+    "workflow",
+    "harness",
+    "ahe",
+    "ahe-codex"
+  ],
+  "author": "ksuchoi216",
+  "files": [
+    "bin/",
+    ".codex/"
+  ],
+  "license": "MIT"
+}