Skip to content

About

Intent and Evidence Project Engine — documentation-first, ticket-first, evidence-qualified engineering for autonomous agents.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Intent and Evidence Project Engine

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.

Question

How does intent become authorized work, and what blocks promotion?

Non-goals / Refusals

  • Treat evaluation as promotion. They are separate; human evidence is required before comprehension and trust claims.

Intent and Evidence Project Engine

IEPE is the short name for this project.

License Protocol Version Python Version

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.


⚡ Single Agentic Adoption Command

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.

💡 What is IEPE?

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:

  1. Intent Governs Implementation: Code exists to fulfill declared human intent, not arbitrary agent guesswork.
  2. Ticket-Bound Authority: Agents execute bounded work contracts with explicit scope, permissions, and budget.
  3. Preflight Capability Probing: Environment constraints (e.g. read-only filesystems) are detected before discovery to prevent governance livelocks.
  4. Evidence-Qualified Promotion: Claims require empirical proof (tests, schemas, benchmarks) before work is promoted to Done.
  5. Status Honesty: Strict operational boundary: Documented != Implemented != Tested != Empirically Validated.

🔗 The Governing Chain

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

📖 Quick Links & Documentation Index

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

🛠️ Quickstart CLI

Installation

pip install -e .[dev]

1. Stage 1: Reconcile (Existing Project Discovery)

Inspect an existing repository without making any file modifications:

iepe-init existing --project-root /path/to/project --report /path/to/report.json

2. Stage 2: Apply (Initialize Operating Layer)

Establish 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"

3. Conformance Validation

Run the full validation suite (schemas, issue templates, skills, evidence bundles, and domain neutrality):

iepe-validate

Or execute unit tests directly:

pytest -v

Repository map

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

📊 Current Engine Maturity

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

📄 License

IEPE Core is open-source software licensed under the Apache License, Version 2.0.


Citation

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.

License

Apache License 2.0. See LICENSE.

About

Intent and Evidence Project Engine — documentation-first, ticket-first, evidence-qualified engineering for autonomous agents.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages