@ksuchoi216/ahe 0.1.6 → 0.1.10

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

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

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

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

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

@@ -0,0 +1,107 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.11"
+# dependencies = []
+# ///
+#
+# How to run:
+# 1. Install uv (if not installed):
+#      curl -LsSf https://astral.sh/uv/install.sh | sh
+# 2. Run directly:
+#      uv run write_plan.py --root "$PWD" --plan-name "Plan Title" < /tmp/ahe-plan.md
+# 3. Or with Python when dependencies are already available:
+#      python write_plan.py --root "$PWD" --plan-name "Plan Title" < /tmp/ahe-plan.md
+
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, slots=True)
+class WritePlanArgs:
+    root: Path
+    plan_name: str
+    overwrite: bool
+
+
+class ArgumentError(Exception):
+    def __init__(self, message: str) -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class PlanAlreadyExistsError(Exception):
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        super().__init__(f"Plan file already exists: {path}")
+
+
+def sanitize_plan_name(plan_name: str) -> str:
+    normalized_name = re.sub(r"[^a-z0-9]+", "-", plan_name.strip().lower()).strip("-")
+    if normalized_name:
+        return normalized_name
+    raise ArgumentError("plan name must contain at least one letter or digit")
+
+
+def parse_args(argv: list[str]) -> WritePlanArgs:
+    root: Path | None = None
+    plan_name: str | None = None
+    overwrite = False
+    index = 0
+
+    while index < len(argv):
+        argument = argv[index]
+        if argument == "--root":
+            index += 1
+            if index >= len(argv):
+                raise ArgumentError("--root requires a value")
+            root = Path(argv[index])
+        elif argument == "--plan-name":
+            index += 1
+            if index >= len(argv):
+                raise ArgumentError("--plan-name requires a value")
+            plan_name = argv[index]
+        elif argument == "--overwrite":
+            overwrite = True
+        else:
+            raise ArgumentError(f"unknown argument: {argument}")
+        index += 1
+
+    if root is None:
+        raise ArgumentError("--root is required")
+    if plan_name is None:
+        raise ArgumentError("--plan-name is required")
+
+    return WritePlanArgs(root=root, plan_name=plan_name, overwrite=overwrite)
+
+
+def write_plan(args: WritePlanArgs, markdown: str) -> Path:
+    filename = f"{sanitize_plan_name(args.plan_name)}.md"
+    plans_dir = args.root / ".plans"
+    plan_path = plans_dir / filename
+
+    if plan_path.exists() and not args.overwrite:
+        raise PlanAlreadyExistsError(plan_path)
+
+    plans_dir.mkdir(parents=True, exist_ok=True)
+    plan_path.write_text(markdown, encoding="utf-8")
+    return plan_path
+
+
+def main() -> int:
+    try:
+        args = parse_args(sys.argv[1:])
+        plan_path = write_plan(args, sys.stdin.read())
+    except (ArgumentError, PlanAlreadyExistsError) as error:
+        print(error, file=sys.stderr)
+        return 1
+
+    print(plan_path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

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

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

@@ -0,0 +1,114 @@
+---
+name: ahe-think
+description: Internal AHE orchestration protocol for routing exact `ahe`, `ahe <query>`, and `<query> ahe` requests through the AHE agent network.
+---
+
+# AHE Thinker
+
+This is an internal AHE workflow skill, not a user-facing command.
+
+Do not treat `$ahe-think` as a user command.
+Use it as the central decision layer for AHE work.
+
+## Purpose
+
+- Judge what is missing before another agent acts.
+- Judge the active `project`, `feature`, or `sub-feature`.
+- Decide which of `Why`, `What`, and `How` are still missing.
+- Choose the next internal agent: `ahe-review`, `ahe-converse`,
+  `ahe-harness`, or `ahe-solve`.
+- Receive each agent result, reassess the state, and decide the next step.
+
+## Routing Inputs
+
+- Exact `ahe` means continue existing harness work.
+- Exact `ahe init`, exact `ahe-new`, and exact `$ahe-new` stay on the
+  `$ahe-new` path.
+- `ahe <query>` and `<query> ahe` mean route the query through `ahe-think`.
+- Broad non-prefixed prompts must not activate AHE.
+
+## Size and Stale-Test Preflight
+
+- Before reading full harness files, run
+  `sh .codex/skills/ahe-compress/scripts/check-harness-size.sh`.
+- Run the test-overlap detector `python .codex/skills/ahe-compress/scripts/detect_stale_tests.py`
+  when the user's explicit AHE query is compression-oriented (e.g., `ahe compress`).
+- Run both compression detectors before choosing the next compression step.
+- If either detector exits with `COMPRESSION_REQUIRED` or code `2`, call
+  `ahe-compress` before normal routing. However, `ahe-compress` must not delete tests directly;
+  for test compression, `ahe-think` must decide whether the next step is `ahe-harness` for
+  harness-file compaction, `ahe-review` for stale-test confirmation and keeper selection,
+  or both in sequence.
+- Do not read oversized harness files wholesale before compression routing is
+  settled.
+
+## Startup Contract
+
+- Check whether the copied harness files are correct before reading their contents.
+- Read files strictly in this order:
+  `AGENTS.md` -> `docs/product.md` plus `docs/product{n}.md` -> `docs/architecture.md` -> `docs/instructions.md` -> `init.sh` -> `feature-list.json` -> `status.json` -> `progress.md` -> `session-handoff.md`
+- `ahe-think` explicitly owns the "what to do next" decisions for Codex-side AHE work.
+
+## Decision Rules
+
+- For a `project`, require `Why`, `What`, and `How` by default.
+- For a `feature` or `sub-feature`, require only the minimum of `Why`, `What`,
+  and `How` needed to proceed safely.
+- Read all existing `docs/*.md` files before choosing product work.
+- Treat `docs/product.md` as overview context.
+- Treat only `docs/product{number}.md` files as ordered product stages, starting
+  with `docs/product1.md` and then `docs/product2.md`.
+- Ignore non-numeric product docs such as `docs/product-alpha.md` for stage
+  ordering.
+- Choose the active product source as the lowest-numbered stage whose derived
+  feature work is not complete, or `docs/product.md` when no numbered stage
+  exists.
+- If the need is understanding repo code, harness drift, progress evidence, or
+  CodeGraph context, call `ahe-review`.
+- If the need is user clarification, call `ahe-converse`.
+- If the need is updating harness artifacts, product docs, feature tracking,
+  todo sync, or compression of completed history, call `ahe-harness`.
+- If the need is solving or decomposing feature work, call `ahe-solve`.
+
+## Interaction Model
+
+- `ahe-think` is centered, but direct worker-to-worker calls are allowed when
+  they are the obvious next step.
+- Typical loops:
+  - `ahe-think -> ahe-review -> ahe-think`
+  - `ahe-think -> ahe-harness -> ahe-think`
+  - `ahe-think -> ahe-converse -> ahe-think`
+  - `ahe-think -> ahe-solve -> ahe-think`
+  - `ahe-think -> ahe-harness-checker -> ahe-think`
+- Allowed direct handoffs include:
+  - `ahe-harness -> ahe-converse`
+  - `ahe-solve -> ahe-review`
+  - `ahe-review -> ahe-harness`
+  - `ahe-harness -> ahe-harness-checker`
+  - `ahe-new -> ahe-harness -> ahe-harness-checker`
+- Every handoff must state the goal, reason, relevant files or context, and the
+  expected result.
+
+## Broad Intent Routing
+
+- Use `ahe-review` for review-first requests.
+- Use `ahe-harness` for product, instructions, progress, feature-list, todo, or
+  compression maintenance.
+- Use `ahe-solve` for feature implementation planning or execution work.
+- Use `ahe-converse` when no safe next step exists without user input.
+
+## Hard Editing Rule
+
+- `AGENTS.md` and any `instructions.md` file may only be modified inside an explicitly changeable section.
+- If no changeable section exists, AHE must ask via `ahe-converse` instead of editing.
+- Reference and template folders must be strictly excluded from reads and edits per project rules.
+
+## Completion
+
+- Continue to the next skill or next unfinished feature until the active unit is
+  resolved.
+- Keep `docs/product.md` as overview context and `feature-list.json` as a
+  derived tracker.
+- Derive features from only the active product stage.
+- Advance from one numbered product stage to the next only after all
+  feature-list items derived from the current active stage are `done`.