AHA - Aligned Human-AI
A prompting kit that turns a fuzzy agentic ask into a cold-runnable agent prompt, a handoff contract, and a memory-backed debrief loop. Six skills for Cursor and Claude Code.
What it does
/aha is the single door. It runs the full cycle, remembers prior sessions, resumes paused work, debriefs return packets, and proposes rules from what broke.
Full cycle:
/aha asks typed leverage questions.- It builds an alignment ledger with decisions, assumptions, unknowns, confidence, and status.
- It runs a premortem on execution failure, missing evidence, unsafe assumptions, and tool risks.
- It rewrites the task as a standalone agent prompt with an eval rubric.
- It emits a handoff packet plus
handoff_contract YAML and a required return_packet block.
- A later
/aha debrief compares the return packet against the contract and proposes safe memory updates.
The five standalone skills are still first-class quick checks:
/ask-me: typed questions when you only need sharper inputs./align-me: alignment ledger before a non-trivial task./critique-this: premortem critique of a draft, prompt, plan, or packet./optimize-prompt: standalone prompt rewrite with an eval rubric./debrief: post-run review when you only need the retro step.
Pipeline
/aha
ask -> align -> critique -> optimize -> handoff
|
executing agent returns return_packet
|
/aha debrief
Evaluation
AHA was A/B tested against building with no alignment layer, on the same model. The full evaluation and a production case study are on the experiment/aha-ab-test branch.
What it found:
- On tiny one-shot tasks the alignment layer is overhead. The kit redirects those to a standalone skill instead of a full run.
- On large multi-layer repos alignment pays for itself: less blind exploration, fewer wrong paths, and an acceptance-criteria contract the executor cannot shortcut. In a production case on a large Playwright test suite, an AHA cross-model pipeline ran about 30 percent cheaper than building direct and produced better tests, including catching a false-positive test the direct run shipped.
The cross-model handoff pattern documents the routing that made that work.
Install
Claude Code plugin
/plugin marketplace add omerakben/aha
/plugin install aha@aha
Cursor or manual
git clone https://github.com/omerakben/aha.git
cd aha
chmod +x install.sh
./install.sh
install.sh copies the skills into ~/.cursor/skills/ and ~/.claude/skills/. It does not delete skills already present from an older install.
Daily use
/aha
Task: <one paragraph, fuzzy is fine>
Use /aha when the task needs a full handoff cycle or prior memory may matter. It will redirect to a standalone skill when the ask is only a quick single-step check.
Typical full run:
- Answer the typed questions.
- Review the alignment ledger and answer any blocked inputs.
- Review the premortem. Reply
continue after the STOP gate.
- Copy the handoff packet into the executing agent chat.
- Require the executing agent to return the
return_packet YAML block.
- Run
/aha debrief or paste the results into /aha so it can compute the AHA delta and proposed rules.
Memory
/aha can create .aha/state.yaml in the user's project. The .aha/ folder is gitignored by default.
State stores sessions, stop gates, handoff contracts, return packets, proposed rules, and reusable patterns. It is private working memory, not a published artifact.
Promoted rules do not stay hidden in .aha/state.yaml. After explicit approval, they land in committed instruction surfaces such as AGENTS.md or CLAUDE.md under an AHA-learned rules section.
Layout
aha/
├── .claude-plugin/
│ ├── plugin.json
│ └── marketplace.json
├── commands/
│ └── aha.md -> /aha
├── skills/
│ ├── aha/ -> /aha orchestrator, phases, state schema
│ ├── ask-me/ -> /ask-me
│ ├── align-me/ -> /align-me
│ ├── critique-this/ -> /critique-this
│ ├── optimize-prompt/ -> /optimize-prompt
│ ├── debrief/ -> /debrief
│ └── SLASH-COMMANDS.md
├── workflows/
│ └── aha.md
├── docs/
│ ├── orchestrator.md
│ └── reference-packet-sketch.md
├── install.sh
├── CHANGELOG.md
└── LICENSE
Slash commands: skills/SLASH-COMMANDS.md
Workflow steps: workflows/aha.md
Account boundary
The skills use placeholders only ([SPECIFY: ...]). They carry no secrets, and they instruct the agent not to invent tenant secrets, repo URLs, or tool names.
Maintaining
