Identifier: IEPE-001
Version: 0.2.0
Software package release: 0.2.2
Status: Normative Candidate
Date: 2026-10-20
Scope: Operating governance from intent to authorized work, including promotion blockers.
How does intent become authorized work, and what blocks promotion?
- Treat evaluation as promotion. They are separate; human evidence is required before comprehension and trust claims.
IEPE is the short name for this project.
IEPE (Intent and Evidence Project Engine) is an open-source, project-agnostic engine for documentation-first, ticket-first, evidence-qualified AI software engineering.
It solves the fundamental failure modes of autonomous coding agents: governance livelocks, infinite retry loops, phantom completions, unverified claims, and lost project context.
To adopt IEPE on any new or existing project, copy and paste this single command block directly into a coding agent or assistant that can edit the repository:
Adopt IEPE for this repository.
Target: ./
Pinned IEPE source: https://github.com/zachshallbetter/IEPE (v0.2.0)
Project Intent: "<Describe the core project intent here>"
Project Mode: existing | new
Mutation Authority: local-files
Execution sequence:
1. Preflight: Run workspace write capability probe once.
2. Reconcile: Perform read-only discovery of intent, files, and authority order.
3. Apply: Generate AGENTS.md, PROJECT_PROFILE.json, and .iepe/protocol-reference.json.
4. Validate: Run iepe-validate or python3 tools/validate.py.
Modern AI agents write code fast, but without governance they drift from intent, claim completion on broken builds, overwrite existing invariants, or loop indefinitely on missing environment capabilities.
IEPE provides a deterministic operating layer beneath any agent:
- Intent Governs Implementation: Code exists to fulfill declared human intent, not arbitrary agent guesswork.
- Ticket-Bound Authority: Agents execute bounded work contracts with explicit scope, permissions, and budget.
- Preflight Capability Probing: Environment constraints (e.g. read-only filesystems) are detected before discovery to prevent governance livelocks.
- Evidence-Qualified Promotion: Claims require empirical proof (tests, schemas, benchmarks) before work is promoted to
Done. - Status Honesty: Strict operational boundary:
Documented != Implemented != Tested != Empirically Validated.
Every material change must preserve complete lineage from intent to promotion:
Intent
-> Doctrine & Experience Contracts
-> Portfolio Objectives & Epics
-> Issue Contracts & Experiments
-> Coordinated Agent Execution
-> Artifacts & Empirical Observations
-> Independent Evaluation
-> Evidence-Qualified Promotion
-> Retained Institutional Memory
| Document | Purpose |
|---|---|
| ⚡ Single Agent Reference | One-page cheat-sheet for human developers and AI agents |
| 📖 Protocol Specification | Canonical protocol invariants, condition taxonomy, and stop semantics |
| 🚀 Adoption Guide | Two-stage adoption pattern (reconcile then apply) |
| 🛠️ Initialization Guide | Step-by-step onboarding for greenfield and existing projects |
| 🔄 Coordinator Specification | Coordinator state machine, preflight sequence, and blocker deduplication |
| 🧪 Epistemic Stress Testing | Designed perturbation trials and unknown-variable discovery |
| 📜 Negative Results Register | Institutional memory of disproven hypotheses and protocol lessons |
pip install -e .[dev]Inspect an existing repository without making any file modifications:
iepe-init existing --project-root /path/to/project --report /path/to/report.jsonEstablish the project-local operating layer:
iepe-init new \
--project-root /path/to/project \
--project-id project.example \
--project-name "Example Project" \
--intent "The core outcome this project exists to cause." \
--protocol-source "https://github.com/zachshallbetter/IEPE" \
--protocol-revision "v0.2.0"Run the full validation suite (schemas, issue templates, skills, evidence bundles, and domain neutrality):
iepe-validateOr execute unit tests directly:
pytest -v| Path | Contents |
|---|---|
docs/ |
Protocol, coordinator, adoption and reference specifications |
schemas/ |
JSON schemas for the contracts and records |
iepe_core/ |
Python reference implementation |
tools/ |
iepe-init, iepe-compile and iepe-validate |
tests/ |
Pytest suite |
examples/, fixtures/ |
Example projects and conformance fixtures |
work/, evidence/ |
The project's own issue contracts and evidence bundles |
.agents/ |
Agent operating contract and process skills |
Documented != Implemented != Tested != Empirically Validated
| Capability | Maturity | Evidence / Location |
|---|---|---|
Core Protocol (IEPE-001) |
Tested | docs/PROTOCOL.md |
| Preflight Capability Probing | Tested | iepe_core/bootstrap.py |
| Blocker Fingerprinting & Livelock Fix | Tested | iepe_core/coordinator.py |
WAITING_EXTERNAL Parked State |
Tested | tests/test_coordinator.py |
| Provisional Profile Generation | Tested | tests/test_bootstrap.py |
| Contract Schema Suite (16 Schemas) | Tested | schemas/ |
| GitHub Issue Templates (8 contract templates, plus bug report and feature request forms) | Tested | .github/ISSUE_TEMPLATE/ |
Conformance Suite (iepe-validate) |
Tested | tools/validate.py |
| Agent Project Package Compiler | Tested | tools/compile_package.py |
IEPE Core is open-source software licensed under the Apache License, Version 2.0.
If you use this software, please cite:
Shallbetter, Z. (2026). Intent and Evidence Project Engine (Version 0.2.2) [Computer software]. https://github.com/zachshallbetter/IEPE
Machine-readable metadata: CITATION.cff. Related research: Foundations of Computational Interaction; related software: Fundamental.
Apache License 2.0. See LICENSE.