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:

1. /aha asks typed leverage questions.
2. It builds an alignment ledger with decisions, assumptions, unknowns, confidence, and status.
3. It runs a premortem on execution failure, missing evidence, unsafe assumptions, and tool risks.
4. It rewrites the task as a standalone agent prompt with an eval rubric.
5. It emits a handoff packet plus handoff_contract YAML and a required return_packet block.
6. 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:

1. Answer the typed questions.
2. Review the alignment ledger and answer any blocked inputs.
3. Review the premortem. Reply continue after the STOP gate.
4. Copy the handoff packet into the executing agent chat.
5. Require the executing agent to return the return_packet YAML block.
6. 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

Edit skills/<name>/SKILL.md, then re-run ./install.sh or bump the plugin version in .claude-plugin/plugin.json. Share the update.

Notes: CHANGELOG.md

License

MIT. See LICENSE.