🚀 Why Agent Rigor?

Most AI coding agents fail not because they lack intelligence, but because they lack discipline. When left to their own devices, they:

• ❌ Skip planning and jump straight to implementation.
• ❌ Write plausible-looking code that doesn't actually work.
• ❌ Get trapped in "doom loops" (fix-forward spirals).
• ❌ Forget what they learned between sessions (context amnesia).
• ❌ Suffer from "context rot" by loading too many instructions at once.

Agent Rigor solves this. It provides a structured, multi-layer progressive disclosure framework: a set of mandatory protocols, verification gates, and anti-rationalization safeguards that force empirical discipline at every step.

🛡️ Core Philosophy

1. Actionable Protocols: Every instruction is a verifiable step with exit criteria, not an essay.
2. Empirical Sovereignty: Claims require evidence. "Seems right" is never sufficient.
3. Atomic State Transitions: The codebase moves between known-good states. Broken states are never committed.
4. Anti-Rationalization: Every skill actively anticipates and rebuts the excuses agents use to skip discipline.
5. Progressive Disclosure: The agent reads only the files it needs for the current phase, saving tokens and preventing instruction neglect.

🏗️ Architecture

The system is organized into a robust 3-tier hierarchy using Progressive Disclosure to prevent context window collapse.

The 3-Tier Context Hierarchy

1. L1: Apex Kernel (SYSTEM_CORE.md): Always-on routing and non-negotiable laws.
2. L2: Phase Directors (00_PHASE_DIRECTOR.md): Just-in-time orchestration loaded only when entering a phase.
3. L3: Skill Protocols (skills/*.md): Deep execution guidelines loaded only when requested by the Director.

The Operational Loop

graph TD
    A[Phase 1: Mission Synthesis] -->|PLAN.md| B(Phase 2: Execution Engine)
    B -->|Committed Code| C{Phase 3: Verification Matrix}
    C -->|CRITICAL Findings| B
    C -->|Zero Findings| D[Phase 4: Cognitive Persistence]
    D -->|Context Snapshot| A
    
    subgraph Phase 6: Adaptive Protocols
    Z[Self-Correction / Scope Defense / Consolidation]
    end
    
    B -.->|3-Strike Failure| Z
    Z -.->|Recovery| B

🛠️ The 6 Operational Phases

⚡ Quickstart

Get Agent Rigor working in your project in under 2 minutes.

1. Bootstrap Your Project

Run the installation script in your project root:

curl -sSL https://raw.githubusercontent.com/MeherBhaskar/agent-rigor/main/install.sh | bash

(Alternatively, clone this repo into an .agents/ directory).

2. Tell Your Agent to Start

Simply prompt your agent with:

"I need to build [feature]. Read .agents/SYSTEM_CORE.md and begin Phase 1 (Mission Synthesis)."

The agent will automatically read the Phase 1 Director, create a PLAN.md, and orchestrate its own work through implementation, review, and context saving.

🤖 Supported Agents

Agent Rigor is pure markdown and platform-agnostic. It works natively with:

🤝 Contributing

We welcome contributions to make agents smarter and more disciplined! Please see our Contributing Guidelines to understand how to design skills that agents actually follow.

If this framework saves your agent from a doom loop, consider leaving a ⭐!