A lightweight, project-agnostic framework for working effectively with AI models during development. Built from real-world experience across 40+ production sessions with Claude, GPT-4, and custom AI coding assistants. Now evolved into a highly-efficient 4-component architecture (3 Markdown blueprints + 1 structured JSON ledger) for total alignment and seamless continuity.

Most AI frameworks focus on what the AI should know. This one focuses on what the AI should remember, how it should behave, and how collaboration between human and AI should actually work. The framework enforces an Anti-Assistant / Technical Partner posture and is inspired in part by Andrej Karpathy's coding guidelines.

At the start of every session, the AI must process the core files in this exact order:

1. SOUL.md — Sync with core technical values, philosophies, and strict execution rules.
2. HUMAN.md (or HUMANS.md) — Align with user profile, communication preferences, and team context.
3. memory.json — Load the current project state, recent blockers, and past lessons learned.

Embedded directly in SOUL.md to ensure they are codified into the AI's core behavior:

1. Ask, don't guess — Surface confusion before writing code. A clarifying question saves hours; a wrong assumption wastes them.
2. Minimum code — Write the absolute minimum amount of code required to solve the problem. No speculative abstractions, no unrequested/bloated architecture.
3. Surgical changes — Focus modifications narrowly. Ensure zero collateral damage on the existing codebase; do not touch unrelated files or adjacent lines.
4. Define done first — State the verifiable success criteria first. Implementation is complete when that criterion is met, not when the code looks right.

To eliminate the "trial-and-error" loop, the AI operates under a strict Plan ➔ Do ➔ Check ➔ Act cycle, prioritizing deep analysis, reproduction, and diagnostic isolation before making any modifications.

1. Copy the core framework files into your project root.
2. Choose between HUMAN.md (Solo project) or HUMANS.md (Team project) and delete the other.
3. ⚠️ CRITICAL OPSEC: Immediately add HUMAN.md, HUMANS.md and memory.json to your .gitignore file.
4. Fill in your profile/preferences in your human context file.
5. Create or let the AI initialize the structured memory.json memory file, and start hacking.

# Example setup for v3
cp /path/to/framework/v3/{AGENTS.md,SOUL.md,HUMAN.md} ./
echo "memory.json" >> .gitignore
echo "HUMAN.md" >> .gitignore
echo "HUMANS.md" >> .gitignore

• Dual-Layer Memory — Separation between static rules (SOUL.md) and dynamic project state (memory.json) ensuring high focus without cluttering the AI's system prompt or context window.
• Structured Schema — Transitioning from Markdown logging to structured JSON for the dynamic session memory allows fast, zero-parser-error reads by the LLM.
• Strict OPSEC & Privacy — Human context is strictly separated and kept local via .gitignore to prevent leaking private workflows, proprietary API keys, or team identities to public repositories.
• Zero Sycophancy — Designed to form a dry, direct, and elite technical sparring partner that actively challenges poor development decisions or unnecessary complexity.

• Execution rules inspired by Andrej Karpathy's coding guidelines.
• Framework developed collaboratively between Jiab77 and v0 by Vercel across the Athena and Virgil projects.
• Powered and executed via ai-pipeline for seamless automation and terminal collaboration.