@ksuchoi216/ahe 0.1.6 → 0.1.10

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

@@ -1,97 +0,0 @@
----
-name: ahe-compression
-description: Internal AHE compression workflow for detecting oversized harness-engineering files and compacting them before AHE thinking reads or routes large context. Use when AGENTS.md, docs/PRODUCT.md, docs/INSTRUCTIONS.md, feature-list.json, PROGRESS.md, SESSION-HANDOFF.md, docs/todo.md, or other AHE harness artifacts have too many lines or waste context.
----
-
-# AHE Compression
-
-This is an internal AHE workflow skill, not a user-facing command.
-
-Do not treat `$ahe-compression` as a user command.
-Use it after `ahe-thinking` decides that harness context is too large to read
-efficiently.
-
-## Size Detection
-
-Run the deterministic line-count preflight before reading full harness files:
-
-```bash
-sh .codex/skills/ahe-compression/scripts/check-harness-size.sh
-```
-
-The script checks these AHE-managed files when they exist:
-
-- `AGENTS.md`
-- `docs/PRODUCT.md`
-- `docs/INSTRUCTIONS.md`
-- `feature-list.json`
-- `PROGRESS.md`
-- `SESSION-HANDOFF.md`
-- `docs/todo.md`
-
-Default thresholds are configured in `.codex/ahe-shared/config.yaml`:
-
-- `agent_md`: 80
-- `product_md`: 180
-- `instructions_md`: 180
-- `feature_list_json`: 180
-- `progress_md`: 180
-- `session_handoff_md`: 180
-- `todo_md`: 180
-- `total`: 750 (combined harness context limit)
-
-Override thresholds only when the workspace has an explicit local rule using environment variables (e.g., `AHE_AGENT_MD_LIMIT`, `AHE_FILE_LINE_LIMIT`, `AHE_TOTAL_LINE_LIMIT`):
-
-```bash
-AHE_AGENT_MD_LIMIT=100 AHE_TOTAL_LINE_LIMIT=900 sh .codex/skills/ahe-compression/scripts/check-harness-size.sh
-```
-
-Exit code meanings:
-
-- `0`: no compression needed.
-- `2`: compression needed.
-- Output ending in `COMPRESSION_REQUIRED`: compression needed.
-- Any other nonzero code: detector failed; fall back to `wc -l` on the same
-  file set and continue the decision manually.
-
-## Compression Decision
-
-- If the detector exits `2`, compress before normal AHE routing continues.
-- If only one file exceeds the per-file threshold, compress that file first.
-- If total harness context exceeds the total threshold, compress the largest
-  AHE-managed files until the total is under the threshold.
-- If `AGENTS.md` is oversized, obey the local `AGENTS.md` instructions before
-  editing it. Compress only sections that local rules allow. If no section is
-  safely editable, report the blocker and compress other harness files instead.
-- Do not read an oversized file wholesale after detection. Read headings,
-  current-status sections, JSON keys, or bounded line ranges needed to preserve
-  behavior.
-
-## Compression Rules
-
-- Preserve active requirements, current decisions, incomplete work, blockers,
-  dependencies, and verification evidence.
-- Preserve required headers and file formats for `PROGRESS.md`,
-  `SESSION-HANDOFF.md`, `feature-list.json`, and `AGENTS.md`.
-- Keep `feature-list.json` valid JSON. Shorten old completed-feature evidence,
-  but preserve each feature `id`, `name`, `description`, `dependencies`,
-  `status`, and current unfinished details.
-- Keep `docs/PRODUCT.md` and `docs/INSTRUCTIONS.md` as the current harness
-  contract. Remove duplicate historical wording only when the active contract
-  remains clear.
-- Keep `PROGRESS.md` focused on current status, recent completed work,
-  decisions that still matter, blockers, and latest verification.
-- Keep `SESSION-HANDOFF.md` focused on the startup path for the next session,
-  important files, open questions, and current verification status.
-- Back up material before deleting substantial historical context by moving it
-  under `.ahe/backups/compression-YYYYMMDD-HHMMSS/` when that context may still
-  be useful.
-
-## Completion
-
-- Re-run the size detector after compression.
-- Run JSON validation when `feature-list.json` changed.
-- Run the repository's normal harness verification command when compression
-  changed tracked harness files.
-- Update `PROGRESS.md` and `SESSION-HANDOFF.md` with the compression evidence
-  when they changed or when compression affects the active workflow.

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

@@ -1,73 +0,0 @@
----
-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-spec/SKILL.md

@@ -1,63 +0,0 @@
----
-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. If `docs/INSTRUCTIONS.md` is missing, create it from `.codex/ahe-shared/templates/INSTRUCTIONS.md` first, then ask what additional instructions belong under `## CAN CHANGE INSTRUCTIONS`.
-- 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

@@ -1,104 +0,0 @@
----
-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
-
-- Before reading full harness files, decide whether compression is needed.
-  Run `sh .codex/skills/ahe-compression/scripts/check-harness-size.sh` when the
-  script exists (which checks against configurable thresholds in `.codex/ahe-shared/config.yaml`),
-  or fall back to `wc -l` over `AGENTS.md`, `docs/PRODUCT.md`, `docs/INSTRUCTIONS.md`, 
-  `feature-list.json`, `PROGRESS.md`, `SESSION-HANDOFF.md`, and `docs/todo.md`.
-- If the detector reports `COMPRESSION_REQUIRED` or exits with code `2`, call
-  `ahe-compression` before normal routing. Do not spend context reading the
-  oversized files wholesale first.
-- 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.
-
-## Broad User Intent Routing
-
-When the user provides a broad natural-language work intent (e.g., "add features", "update spec"), use their original prompt to determine the exact path:
-- Route **product/spec changes** to `ahe-spec`.
-- Route **instruction changes** to `ahe-spec`.
-- Route **feature/todo tracking** to `ahe-update`.
-- Route **unclear AHE work** to `ahe-conversation` and ask exactly one detail question before editing if the request is vague.
-
-## 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

@@ -1,66 +0,0 @@
----
-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.