AI Intent Protocol — An open protocol for organizing an AI agent's intent as a governed, prioritizable, feedback-revised Intent Tree that generates work and focuses knowledge.
Protocol: AIIP v0.1.0
Full Name: AI Intent Protocol
Authority: aiip.dev
Center: hsaw.dev (Axiom 0)
Executor: soulbot.dev
Axiom 0: Human Sovereignty and Wellbeing
Status: v0.1.0 — first internally-consistent draft, machinery not yet frozen. The Chinese specification (specification/AIIP_Protocol_cn.md) is the authoritative draft for v0.1.0; it ships with a canonical enum registry, JSON Schemas, conformant examples, a conformance test suite, ADRs, and an English narrative (docs/). A faithful English specification (specification/AIIP_Protocol.md) ships alongside; promoting English to authoritative (Chinese becoming the translation) is the remaining v1.0 item (see docs/02_AIIP_Plan.md).
As agents gain autonomy, the bottleneck is no longer getting information (long context, RAG, memory, MCP solved that), nor even organizing the work (AIKP knowledge, AIJP work) — it is the persistence and evolution of intent itself: why the agent is doing any of this, which goals are still valid, which conflict, what to do when execution drifts from the original aim. The classic user prompt → ad-hoc plan → action → result loop suits short tasks; it does not suit long-running agents, where long-term goals evaporate after the conversation ends, natural-language aims cannot be turned into a schedulable work tree, and there is no mechanism to detect or correct goal drift.
AIIP organizes what an AI agent is trying to achieve into a decomposable, prioritizable, work-/knowledge-binding, alignment-governed, feedback-revisable intent space — so the agent has an explicit, addressable, traceable goal structure that can generate work, focus knowledge, and be corrected by grounded feedback.
AIIP turns intent into work. AIJP turns work into execution. AIKP turns knowledge into focus.
The Intent Tree is AIIP. The Knowledge Tree is AIKP. The Work Tree is AIJP.
The core object is the intent (a goal unit), not a task (an execution unit): one Intent can generate many AIJP Jobs, and a Job's feedback can revise one Intent. The keystone is the last step — revise intent from grounded feedback: without it, AIIP is only goal storage; with it, AIIP becomes an intent loop.
AIIP does not reinvent the planner, the executor, storage, or the LLM. It is the goal layer above AIKP / AIJP: it holds a declarable, inspectable, portable Intent Tree and references (never copies) the Work Tree and Knowledge Tree. Its novelty is not goal modeling itself (OKR, BDI, and goal-modeling are established) but a JSON-native, framework-neutral, portable intent artifact plus its bindings to AIKP / AIJP and an Axiom 0 alignment gate.
Intent → AIJP Work Tree → AIKP Knowledge Focus → Execution → Feedback → Intent Revision
An Intent Tree produces a Work Tree; the Work Tree, when executed, reads the Knowledge Tree; the execution's grounded feedback revises the Intent Tree; the Knowledge Tree records the history of intents and work. Drift between the original intent and the running work raises an AIIP_DRIFT_WARNING (warning, non-blocking) and is handled by one of request_user_confirmation / revise_intent / regenerate_jobs / pause_execution.
| Tree | Protocol | Governs |
|---|---|---|
| Intent Tree | AIIP | why to do it (goals / direction) |
| Knowledge Tree | AIKP | what to read |
| Work Tree | AIJP | what to do |
In one line: AIKP loses no knowledge · AIJP loses no task · AIIP loses no direction. AIIP references AIKP / AIJP, it does not duplicate them.
- JSON is the source of truth — Mermaid is a structural view; Markdown/HTML are generated (regenerated, never hand-edited). On conflict,
json_wins. - Intent ≠ instruction ≠ task — AIIP represents goals and direction (e.g.
Build SoulIDE MVP), not low-level commands (those are AISOP/AIAP) and not execution tasks (those are AIJP). It stays at the goal layer. - Intent Tree, conflict-aware — a
childrenIntent Tree as the decomposable goal structure; typedintent_relations(contains · supports · conflicts_with · depends_on · derived_from · revises · supersedes · blocks · enables · aligns_with) as the goal graph, with conflict sub-typing. - Priority is first-class —
level(low/medium/high/critical) plusstrategic_value · urgency · user_importance · alignment_weight∈ [0,1] and atime_horizon(short/mid/long term); v0.1.0 defines the priority signals, not a scheduler formula. - Feedback loop — "done ≠ aligned": an Intent is revised by grounded feedback from AIJP job reports, AIKP knowledge, runtime/external events, or human review. Grounded feedback is preferred over pure self-reflection; this loop is the keystone.
- AIJP / AIKP binding — an Intent generates an AIJP Work Tree (
generate_worktree, …) and focuses an AIKP knowledge context; AIIP itself never performs consequential actions. - Axiom 0 / HSAW alignment — every intent MUST pass an Intent Alignment Check (human sovereignty / wellbeing / user-intent consistency / risk level / permission); high-risk intents MUST pass a human approval gate; AI-derived intents MUST be marked
source=agentand the agent must explain any revision. - Machine-checkable — a validation section with rules + error codes; a single-source-of-truth enum registry; JSON Schemas + a green conformance suite.
- Standards-aligned, not reinvented — goal types ↔ BDI achieve/maintain/perform;
status↔ schema.org ActionStatusType; relation strength ↔ GRL contribution; drift ↔ the goal drift literature; provenance ↔ W3C PROV. AIIP aligns rather than rebuilds.
┌─────────────────────────────────────┐
│ HSAW — Axiom 0 (Why-ultimate) │
│ AIZP — Logical Center (Alignment) │
│ ★ AIIP — Intent Space (Why) │ ← This protocol
│ AIKP — Knowledge Space (What to know) │
│ AIJP — Work Space (What to do) │
│ AISOP — Capability / Operation │
│ AIAP — Execution Programs │
│ SoulBot / SoulIDE — Runtime │
└─────────────────────────────────────┘
HSAW — Axiom 0 (anchors all layers)
Stack order: HSAW → AIZP → AIIP → AIKP → AIJP → AISOP → AIAP → SoulBot/SoulIDE.
AIIP decides why to do it; AIKP decides what to know; AIJP decides what to do. AIIP sits at the top of the what/why layers — it drives both knowledge and work — while keeping AIKP above AIJP, consistent with those two repositories. (The runtime data flow intent → work → knowledge is a separate concern and does not change the stack order.) Because AIIP decides whether and why an action should happen at all, it sits closer to value and sovereignty than the knowledge or work layers, and therefore carries the Axiom 0 alignment and human approval gate.
| Extension | Purpose | schema prefix |
|---|---|---|
.aiip.json |
Intent Space / index (intent_space) |
aiip.v0.1.0.intent_space |
.intent.json |
a single Intent Node (intent) |
aiip.v0.1.0.intent |
.intentfeedback.json |
Intent Feedback (intent_feedback) |
aiip.v0.1.0.intent_feedback |
.intentreport.json |
Intent Report / revision report (intent_report) |
aiip.v0.1.0.intent_report |
schema values follow aiip.v0.1.0.<kind> (all lowercase, dot-separated). See the registry for the full enum allocations.
pip install jsonschema
python -m pytest tests/This runs the reference validator (tests/test_aiip.py) and the consistency guards (tests/test_consistency.py) against the JSON Schemas and the conformant examples.
AIIP-Protocol/
├── specification/ # normative: AIIP_Protocol_cn.md, registry.md, registry_cn.md, standards/
├── schemas/ # JSON Schemas (intent_space / intent / intentfeedback / intentreport)
├── examples/ # conformant example files (all 4 file types)
├── tests/ # validator + conformance suite (green)
├── docs/ # English narrative
├── docs_cn/ # Chinese narrative: design intent / plan / prior-art
│ └── plan/ # archived historical drafts (non-authoritative)
└── adrs/ # Architecture Decision Records
| Document | Description |
|---|---|
| Specification | Normative object model, Intent Tree / intent graph, priority, feedback, AIJP/AIKP binding, alignment, validation, compliance |
| Registry | Canonical enum allocations (single source of truth) |
| Design Intent | Why AIIP exists; boundary with AIKP / AIJP and the rest of the stack |
| Plan | Convergence, key decisions, deferred items, roadmap |
| Spec Guide | Object-model & core-mechanism walkthrough (companion to the spec) |
| Prior Art and Improvements | Prior-art positioning, standards alignment, improvements (cited) |
| Examples | Conformant .aiip.json / .intent.json / .intentfeedback.json / .intentreport.json files |
| Tests | Reference validator + consistency suite |
| ADRs | Architecture Decision Records |
| CHANGELOG | Release history |
Authority order: when documents disagree, the registry wins over the JSON Schemas, which win over the specification prose.
This protocol specification and any reference artifacts are provided for research and educational purposes only. They are experimental and not intended for production use. Use at your own risk. The authors assume no liability for any damages arising from use of this software. See LICENSE for full terms (Apache 2.0).
AIXP Labs aixp.dev
AIIP is the intent layer of the AIXP protocol family, alongside HSAW, AIZP, AIKP, AIJP, AISOP, AIAP and the SoulBot reference runtime.
Align Axiom 0: Human Sovereignty and Wellbeing. AIIP v0.1.0. www.aiip.dev