Jossue AlcaláCreate and Build

Official reference · AHP+ 1.1.0

AHP+ Command Atlas

A guide to installing AHP+ and using it, whether you type in the terminal or ask for it in your AI assistant’s chat. Every command is ready to copy.

40commands ready to copy

6platforms with an installer

Gitwhere everything is stored

00 / Orientation

Terminal and chat are not the same.

There is only one AHP+. What changes is where you ask for it and what can be proven afterwards.

TERMINAL

Here it actually runs

You type the command and the terminal answers. That answer counts as proof, because anyone can repeat it and get the same result.

shell
npx ahp verify . --strict

IDE / CHAT

Here you only ask for it

You ask the assistant for the operation. It has to run the command and show you the output: saying it did is not the same as doing it.

chat
/ahp verify strict

01 / Installation

Installation by operating system.

You need a project that already uses Git and has at least one commit, plus Node.js 20 or newer. Run the commands from the project’s main folder.

Open Terminal and move into the project’s main folder before running each line.

zsh
node --version
npm install --save-dev @jossuealcala/ahp-plus@latest
npx ahp init . --owner "Your name" --project my-project
npx ahp doctor .
npx ahp verify . --strict

STABLE

@latest

The normal choice: the latest tested version.

terminal
npm install --save-dev @jossuealcala/ahp-plus@latest

PINNED

@1.1.0

Pins exactly the version this guide documents.

terminal
npm install --save-dev @jossuealcala/ahp-plus@1.1.0

DEVELOPMENT

@next

Only for trying out what is coming and reporting issues.

terminal
npm install --save-dev @jossuealcala/ahp-plus@next

02 / Start-up

Start-up check.

Run this sequence whenever you open the project, switch assistants, or receive a handover. It tells you where you stand before you touch anything.

terminal · all OS
npx ahp root .
npx ahp doctor .
npx ahp verify . --strict
npx ahp status .
npx ahp context . --format markdown --budget 8000

Then look at the .ahp/manifest.json, .ahp/state/project.json, and .ahp/INDEX.md files. If the saved summary and the command output disagree, the command wins: that is what is happening right now.

03 / Terminal

Every command.

Search by what you want to do, by command name, or filter by category. Every example uses the copy installed in your project, through npx ahp.

40 commands visible

Repository

Set up

Creates the .ahp/ folder inside the repository you are in.

terminal
npx ahp init . --owner "Tu nombre" --project mi-proyecto

Repository

Confirm where you are

Tells you which repository and which .ahp/ folder it is using, so you do not write into the wrong project.

terminal
npx ahp root .

Repository

Health check

Checks the project, the scope, the file structure, and whether everything is valid, all at once.

terminal
npx ahp doctor .

Repository

Strict check

Reviews structure, references, and integrity, and warns if any secrets slipped in.

terminal
npx ahp verify . --strict

Repository

Where the project stands

Shows where it stands, the state of Git, any active notices, and whether the work has left your computer yet.

terminal
npx ahp status .

Repository

Is it backed up?

Compares what you have locally with the server. With --require-remote it fails if nothing has been pushed yet.

terminal
npx ahp sync check . --require-remote

Context

Summary for machines

Returns the project summary as JSON, ready for another program to read.

terminal
npx ahp context . --format json --budget 8000

Context

Summary for people

The same summary in plain text, to read yourself or paste into a chat.

terminal
npx ahp context . --format markdown --budget 8000

Context

Refresh the saved summary

Rewrites the .ahp/INDEX.md file with the latest state.

terminal
npx ahp brief . --budget 8000

Context

Mark where you stopped

Saves a point in the session you can come back to later.

terminal
npx ahp checkpoint . --session mi-sesion --summary "Límite validado" --next-action "Continuar"

Context

See the history

Lists the saved points and the handovers made so far.

terminal
npx ahp history .

Context

History of one session

Filters that history down to a single work session.

terminal
npx ahp history . --session mi-sesion

Context

Update the direction

Updates the phase the project is in, the objective, and the next step.

terminal
npx ahp set-state . --phase IN_PROGRESS --objective "Objetivo" --next-action "Siguiente paso" --confidence USER_CONFIRMED

Records

Decision

Puts a decision in writing, so nobody has to recall it from memory later.

terminal
npx ahp record decision . --title "Decisión" --status ACCEPTED --confidence USER_CONFIRMED

Records

To-do

Notes something to be done and the state it is in.

terminal
npx ahp record task . --title "Implementar mejora" --status PLANNED --confidence USER_CONFIRMED

Records

Bug

Notes an error that can be reproduced on demand.

terminal
npx ahp record bug . --title "Fallo reproducible" --status OPEN --confidence VERIFIED

Records

Risk

Keeps an open risk written down so it is not forgotten.

terminal
npx ahp record risk . --title "Riesgo de migración" --status OPEN --confidence VERIFIED

Records

Review passed or failed

Passes or fails a quality review. To mark PASS you must cite a concrete piece of proof (EVD-...).

terminal
npx ahp record qa . --title "Gate de aceptación" --status PASS --confidence VERIFIED --source EVD-...

Records

Requirement

Notes something the project has to satisfy.

terminal
npx ahp record requirement . --title "Debe ser portable" --status ACCEPTED --confidence USER_CONFIRMED

Records

Proof that something happened

Stores the real result of something that ran: the command, what it returned, and whether it finished cleanly.

terminal
npx ahp record evidence . --title "Validación local" --type test --locator "npm test" --result "PASS: 18 pruebas" --confidence VERIFIED --exit-code 0

Records

See the records

Lists every record, or only those of one kind.

terminal
npx ahp list risk .

Records

See only what is open

Leaves out anything already closed.

terminal
npx ahp list task . --active

Records

Close a record

Closes a record with the reason why.

terminal
npx ahp close RISK-... . --status CLOSED --reason "Mitigación verificada"

Records

Change a decision

Replaces an accepted decision by creating a new one: the original is never rewritten, it stays in the history.

terminal
npx ahp supersede DEC-... . --title "Decisión revisada" --accept --confidence USER_CONFIRMED

Handover

Prepare the handover

Packages the context so it can be passed to another tool.

terminal
npx ahp handoff create . --from codex --to cursor --session feature-x --summary "Continuar"

Handover

Review before accepting

Opens the handover and checks it is complete, without accepting it yet.

terminal
npx ahp handoff inspect HOF-... .

Handover

Accept the handover

Accepts it only if the project, the contents, and the commit match what it claims.

terminal
npx ahp handoff receive HOF-... .

Working in parallel

Write without overwriting anyone

Cancels the write if someone else moved the repository while you were working.

terminal
npx ahp checkpoint . --summary "Límite" --expected-head COMMIT --expected-state DIGEST

Working in parallel

Flag that you are working

Leaves a notice that you are inside one part of the project. It is a courtesy notice, not a lock.

terminal
npx ahp lock acquire . --scope src/editor --owner codex --minutes 60

Working in parallel

Remove the notice

Removes your notice when you are done. The history is kept.

terminal
npx ahp lock release LOCK-... . --owner codex

Migration

See what would move

Reviews the version 1.0 agent/ folder and tells you what it would do, without touching any file.

terminal
npx ahp migrate . --plan

Migration

Make the change

Creates the version 1.1 structure and leaves the original agent/ folder untouched.

terminal
npx ahp migrate . --apply

Installers

See the available platforms

Shows which programs and assistants have an installer.

terminal
npx ahp adapter list

Installers

See what it would install

Shows which files it would create and which it might clash with, without installing anything.

terminal
npx ahp adapter install all .

Installers

Install on all of them

Installs all six: generic agent, Claude, Cursor, OpenCode, Codex, and ChatGPT.

terminal
npx ahp adapter install all . --apply

Installers

Install on just one

Replace PLATFORM with generic, claude, cursor, opencode, codex, or chatgpt.

terminal
npx ahp adapter install PLATFORM . --apply

Versions

Install the stable version

Installs the latest tested version. This is the normal choice.

terminal
npm install --save-dev @jossuealcala/ahp-plus@latest

Versions

Pin an exact version

Installs exactly 1.1.0, the same version this guide documents.

terminal
npm install --save-dev @jossuealcala/ahp-plus@1.1.0

Versions

Try what is coming

Installs the in-progress version. For testing and reporting issues only, not for production.

terminal
npm install --save-dev @jossuealcala/ahp-plus@next

Versions

Uninstall

Removes the program. Your records in .ahp/ and the installers stay where they are.

terminal
npm uninstall @jossuealcala/ahp-plus

04 / CHAT

Commands by platform.

First install the adapter from the terminal, once. After that you can ask for things inside the chat, using the wording shown below.

IDE / APP

Cursor

Adds the /ahp command to Cursor chat, so you can ask for it without leaving the editor.

In terminal

terminal
npx ahp adapter install cursor . --apply

Directly in chat

  • CHAT
    /ahp doctor
  • CHAT
    /ahp verify strict
  • CHAT
    /ahp context
  • CHAT
    /ahp checkpoint summary="Validated boundary" next="Create handoff"
  • CHAT
    /ahp handoff to codex
  • CHAT
    /ahp receive HOF-...

IDE / APP

OpenCode

Adds the same /ahp command in OpenCode. You type it exactly as in Cursor.

In terminal

terminal
npx ahp adapter install opencode . --apply

Directly in chat

  • CHAT
    /ahp status
  • CHAT
    /ahp verify strict
  • CHAT
    /ahp handoff to claude
  • CHAT
    /ahp receive HOF-...

IDE / APP

Codex

Installs the $ahp skill and keeps the project rules in AGENTS.md.

In terminal

terminal
npx ahp adapter install codex . --apply

Directly in chat

  • CHAT
    Use $ahp to check this repository and show me where the project stands.
  • CHAT
    Use $ahp to mark where we stopped and prepare the handover to Cursor.
  • CHAT
    Use $ahp to accept handover HOF-... and do not edit anything unless the result says READY.

IDE / APP

Claude Code

Connects CLAUDE.md to the AHP+ instructions. Here you ask in plain language: there is no slash command.

In terminal

terminal
npx ahp adapter install claude . --apply

Directly in chat

  • CHAT
    Before continuing, use AHP+ to run the health check, the strict check, and the project summary.
  • CHAT
    Mark where we stopped and prepare the handover from Claude to Codex, without committing or pushing.
  • CHAT
    Accept handover HOF-... with AHP+ and stop if anything does not match.

IDE / APP

ChatGPT / Mobile

Installs AHP_MOBILE.md. If the chat has a terminal it can run commands; if it can only read, it has to say so.

In terminal

terminal
npx ahp adapter install chatgpt . --apply

Directly in chat

  • CHAT
    Read AHP_INSTRUCTIONS.md. Run the start check with AHP+ and tell me the project, the commit, whether the work is backed up, what is blocked, and the next step.
  • CHAT
    If you have no terminal: read AHP_MOBILE.md, .ahp/INDEX.md, and the latest handover. Do not say you checked, tested, committed, or pushed, because you cannot.

IDE / APP

Cualquier otro agente

Installs AHP_INSTRUCTIONS.md and a block in AGENTS.md, for agents without their own installer.

In terminal

terminal
npx ahp adapter install generic . --apply

Directly in chat

  • CHAT
    Follow this repository’s AHP+ instructions. Check before writing and treat the repository as the source of truth, not the conversation.
  • CHAT
    Run the health check, the strict check, and the project summary. Show me the real output and wait for my authorization before any action outside the repository.

05 / Handover

Passing the work to another tool.

A handover puts in writing where everything stands and which repository and commit it belongs to. Git is what carries it, and you authorize the commit and the push.

  1. 01

    Mark where you stopped

    Save a point you can return to, before switching tools.

    terminal
    npx ahp checkpoint . --session feature-x --platform codex --actor "Codex" --summary "Límite validado" --next-action "Recibir y continuar"
  2. 02

    Create the handover

    State which tool it comes from, which one it goes to, and what is left to do.

    terminal
    npx ahp handoff create . --from codex --to cursor --session feature-x --summary "Continuar desde el límite validado"
  3. 03

    You push it

    The handover has to be committed in Git and available on the server. AHP+ neither runs Git nor grants you permission to publish it: that step is yours.

  4. 04

    Check before continuing

    Whoever receives it checks that the handover is complete and matches this repository and this commit. Only then do they start editing.

    terminal
    npx ahp verify . --strict
npx ahp handoff inspect HOF-... .
npx ahp handoff receive HOF-... .
npx ahp sync check . --require-remote

06 / Migration

If you are coming from version 1.0.

Version 1.0 projects kept everything in a folder called agent/. If that is your case, do not install from scratch again: use the migration.

READ ONLY

1. See what would move

terminal
npx ahp migrate . --plan

It only reports what it found, where it would go, and which files might clash. It changes nothing.

WRITE

2. Do it once you have reviewed it

terminal
npx ahp migrate . --apply
npx ahp verify . --strict

It keeps the original agent/ folder. If .ahp/ already exists, AHP+ stops instead of merging the two.

07 / Limits

AHP+ records and checks; it does not authorize.

A handover saying READY means the data lines up, not that there is permission to act. These actions are always a person’s call:

  • commit
  • push
  • pull
  • merge
  • publish
  • deploy
  • destructive actions
GitHubnpmView product case

This guide was prepared from the official AHP+ 1.1.0 documentation and tool. Before copying the installation commands, confirm which version is published and review the official changelog.