v3.6

AI-Native Agentic
Development Framework

Independent review, automatic capture, and human ownership
for software you build with AI.

"Reasoning is the primary artifact. Code is output."

The next 16 slides: the problem in one story · what this is and why you'd use it · one real review, replayed from the repo's own records · the machinery that guarantees it · and the honest trade-off.

⚠ Evolving rapidly — much is proof-of-concept. The core workflow (review, plan, build, deliberate) is stable; several advanced capabilities are POC and will shift. Pin a version if you need stability.

Navigate: ← → arrow keys

The Problem

The Problem with AI-Assisted Development Today

It doesn’t show up on day one. It shows up three weeks later, like this:

Tuesday. You asked your AI assistant to add authentication. It weighed JSON Web Tokens against server-side sessions, considered your deployment, and chose httpOnly-cookie JWTs with rotating refresh tokens. It wrote clean code. The tests pass. Today a teammate asks: “Why are refresh tokens rotated here? Can I simplify this?” The reasoning that made that choice lived in a chat session that no longer exists. The code remembers what was decided. Nothing remembers why — so your teammate will either guess, or re-litigate a decision that was already made well.

“A decision that exists only in a context window did not happen.” — the framework's constitution (CLAUDE.md, Principle #2: capture is automatic)

🕳️ No decision trail

Hundreds of AI choices per project. The reasoning evaporates with the session.

🪠 Self-graded homework

The same AI that wrote the code reviews it — and finds what it expects to find.

🎲 Quality is a dice roll

Ad-hoc sessions, no repeatable process, no enforced standards.

💨 Zero institutional memory

Every session starts from scratch. Lessons are re-learned, then lost again.

Start Here

What This Actually Is

A set of commands and rules you layer on top of Claude Code. Instead of chatting with one AI, you use structured commands — /review, /plan, /deliberate — that route your work through a team of specialist AI agents, capture the reasoning behind every decision to disk, and run a quality gate before anything is committed. You stay the decision-maker; the framework makes sure nothing important gets skipped or lost.

It runs inside Claude Code

Not a separate service, not a SaaS. Version-controlled files in your repo, driven through Anthropic's Claude Code CLI. Requires a paid Claude account (Pro or Max) — the agents won't run without one.

The commands are the framework

It doesn't change how you write code — it changes what happens around it. Every command automatically records its reasoning; the AI cannot opt out of the paper trail.

Who it's for

Anyone using Claude Code to build software they'll still own in six months — and who wants independent review, a record of decisions, and guardrails without building that machinery themselves.

Next: what it actually does for you — then three slides that replay one real code review, pulled verbatim from this repository’s own sealed records, so you can judge whether the machinery earns its keep.

The Value

Why Use This?

Six things it does for you that a plain AI chat doesn't.

🧭 Make better decisions

Facing a fork — ORM vs raw SQL, monolith vs services? /deliberate convenes a specialist panel that argues it out from security, architecture, performance, and anti-groupthink angles, then hands you a recommendation with the trade-offs explicit. You make the call; the reasoning is kept.

🔍 Review the builder can't rig

/review sends every change to independent contexts that never saw the builder's reasoning — findings ranked blocking vs advisory, with a verdict. Proven on the next three slides.

🔭 Learn from projects that already solved it

/discover-projects finds reference implementations on GitHub; /analyze-project — the Project Analyst agent — scores their patterns on a 5-dimension rubric. Only ≥20/25 gets recommended, with attribution. Evidence, not fashion.

🛡️ Git & GitHub, with guardrails

The agent drives the ceremony — feature branches, gated commits — while hooks block direct pushes to main and destructive git commands are prohibited outright. Pull requests come to you as links to approve. You don't have to be a Git expert to work safely.

🗃️ Nothing is forgotten

Every review and deliberation is sealed to disk automatically — the “why” behind any decision stays searchable months later. What graduates into long-term memory is your call, never automatic.

🎛️ You stay in control

Every gate is human-held: nothing merges itself, nothing pushes without you, and the education gate keeps you able to explain what ships. Autonomy never means skipping your verdict.

Claims are cheap. The next three slides replay a real review from this repository's own sealed records — judge the second claim yourself, and hold the rest to the same standard.

A Real Review · 1 of 3

Release Night, March 2026

The developer wants to ship v3.0 to the public tonight. The AI has spent the sprint building the release: new agent definitions, two new scripts, five new test files, an updated constitution. From inside the building context, everything looks done: tests green, 84% coverage, clean architecture. Then /review runs. Risk is assessed as HIGH — it's a public release — so six specialist agents are dispatched, each in its own context.

Risk: HIGH → 6 specialists dispatched → Independent analysis → Findings validated → Verdict

The one rule that matters here

None of the six reviewers saw the builder's reasoning. Each got the code and the request — not the conversation that produced them. That's deliberate, and it's the framework's core guarantee.

Why hide the reasoning from the reviewers?

A reviewer who reads your rationale inherits your blind spots — they check that the code does what you said, not whether what you said was right. A reviewer who sees only the artifact has to reconstruct the intent from the code alone. The gap between what they reconstruct and what you meant is exactly where the bugs live.

Everything on the next two slides is quoted from docs/reviews/REV-20260318-035523.md — a real file in this repository, written automatically on March 18, 2026.

A Real Review · 2 of 3

What the Independent Contexts Caught

Critical · Release-blocking F-023 found by: Independent Perspective

PyYAML missing from `requirements.txt` — used by 6 files

“Every new user gets ImportError on first interaction.” The very first command any adopter typed would have crashed — on release night.

Why the builder could never catch this: its own tests were green because its own environment already had PyYAML installed. From inside the building context, this bug was invisible by construction. It took a separate context asking “what does a new machine look like?” — validated at 0.97 confidence.

High F-017

Factual error in an ADR

“Expanded the agent roster from 11 to 11” — a decision record that contradicted itself. Found by Docs-Knowledge.

Medium F-025

Version discrepancy

pyproject.toml said 0.1.0; the release narrative said v3.0. Caught before the public saw both.

Invalidated F-012

…and one false positive, struck down

A plausible-sounding finding was invalidated during validation, and three low-confidence findings were filtered. The pipeline kills its own noise instead of drowning you in it.

28 findings raised· 3 release-blocking· 1 invalidated, 3 filtered· Verdict: REQUEST CHANGES· All 3 fixes: under 15 minutes

A Real Review · 3 of 3

What's Left on Disk — Automatically

# docs/reviews/REV-20260318-035523.md (frontmatter)
review_id: REV-20260318-035523
discussion_id: DISC-20260318-035523-review-sprint2-v3-release
risk_level: high
collaboration_mode: structured-dialogue
verdict: request-changes
confidence: 0.90
review_duration_minutes: 15

docs/reviews/

REV-20260318-035523.md — full report, every finding

discussions/

DISC-20260318-035523…/

events.jsonl — every turn, machine-readable, sealed

transcript.md — human-readable, sealed

metrics/

evaluation.db — queryable: agents, findings, calibration

Nobody remembered to write this down

Nobody had to. The report, the sealed transcript, and the metrics row were produced by the command's own pipeline — enforced by scripts and hooks, not by asking the AI to please remember. After a discussion closes, its record is locked; corrections require a new discussion that references the original.

Six months later, the “why” is still there

Which finding was raised by whom, at what confidence, what was invalidated and why the verdict was request-changes — all still readable, exactly as it happened.

This slide is the proof

The example you just read wasn't invented for this deck. It was quoted from the repo's own five-month-old sealed record, findings and frontmatter verbatim. The ability to do that — on any decision, years later — is the product.

Foundation

The Three Ideas You Just Watched

The generator is never the sole evaluator

Independence here is an information property, not a personality: a separate context that never saw the reasoning behind the code. Self-review finds what it expects to find.

You saw it: the builder's tests were green — the missing dependency was invisible from inside. Only a context that didn't share the builder's environment assumptions could ask the newcomer's question.

Capture is automatic

Enforced by scripts and hooks, not by instruction. If logging depended on the model's diligence, it would quietly fail on the day it mattered. The AI cannot opt out.

You saw it: the report and sealed transcript existed before anyone decided to document anything. “A decision that exists only in a context window did not happen.”

Reasoning is the primary artifact

Code is output. The deliberation, trade-offs, and decision lineage are the durable assets — the “why” outlives the diff.

You saw it: this deck quoted a review, verbatim, five months after it ran. Your teammate's “why are refresh tokens rotated?” gets an answer instead of a shrug.

These are three of seven constitutional principles — the full constitution is on slide 12. First: the machinery that makes them enforceable.

Machinery · Memory

Where the Paper Trail Lives: Four Layers

Everything you saw on the previous slide flows through this stack. Click a layer to expand.

1

Immutable Discussion Capture

Raw event streams, sealed after every reasoning session — the canonical record

▼

Every canonical reasoning session produces a sealed record in discussions/: events.jsonl (machine-readable) and transcript.md (human-readable). Events track agent identity, intent (proposal, critique, evidence, decision…), confidence, and risk flags. After closure the files are locked — corrections require new discussions that reference the original. This is where REV-20260318's transcript lives.

2

Relational Index

SQLite database that makes the raw reasoning queryable

▼

All events are ingested into SQLite, enabling cross-discussion analytics: agent contribution scoring, false-positive rates, time-to-consensus, reopened-decision tracking. This is what lets the framework ask “which reviewer keeps being right?” — the raw material of the learning loops on slide 14.

3

Curated Memory

Human-approved patterns, decisions, and lessons — nothing enters automatically

▼

The memory/ directory holds promoted knowledge: decision summaries, patterns, lessons, graduated rules. Promotion requires independent confirmations plus explicit human sign-off — institutional knowledge is deliberately curated, never auto-accumulated. Promoted artifacts carry a forgetting curve: reconfirm or archive.

4

Optional Vector Acceleration

Semantic retrieval, only when the corpus outgrows keyword search

▼

Activates only at scale, and never replaces the relational structure — it accelerates retrieval. Intentionally deferred; most projects won't need it for a long time.

Raw events → queryable metrics → curated knowledge. Nothing is lost, and nothing is canonized without you.

Machinery · Enforcement

Enforced at the Tooling Layer, Not by Trust

“Capture is automatic” and “quality is gated” are promises a model could quietly break. So they aren't left to the model.

Lifecycle hooks — guardrails at every stage

Before writes

Secret detection · protected files · file locking

Scans for a dozen secret patterns (API keys, JWTs, private keys) and blocks the write; protects .env, .git/, the metrics DB; prevents concurrent agent edits.

After edits

Auto-format · lock release

Every Python file is ruff-formatted after every edit. You never commit unformatted code.

At commit & push

Quality gate · main-branch protection

The full gate (right) runs as a git pre-commit hook; direct pushes to main are blocked with remediation instructions.

Across sessions

State save & restore

Working state is saved to BUILD_STATUS.md before context compaction and restored on resume — work-in-progress survives the session boundary.

The quality gate — every commit

✓ Formatting & linting (ruff)

✓ Tests (pytest, deterministic suite)

✓ Coverage ≥ 80%

✓ ADR completeness — decisions documented

✓ Review existence — code changes require /review

✓ Regression ledger — fixed bugs stay fixed

Two gates, then commit

Gate 1: the automated checklist above. Gate 2: the independent multi-agent /review you watched. Bypassing either takes an explicit, documented developer override — never a silent flag.

And it watches its own use

Telemetry tracks cost per discussion, failure and waste signals, and a value-vs-subscription lens in a live local dashboard — so “is this worth it?” is a number you can look at, not a feeling.

Machinery · The Team

Twelve Agents, Dispatched by Risk

You don't pick the panel — the risk of the change does. A typo gets two reviewers; release night got six.

● Opus — leadership & deep reasoning ● Sonnet — specialist analysis

👑

Facilitator

Orchestrates every multi-agent workflow; never renders verdicts itself

🏛️

Steward

Guards the framework's own evolution & lineage — episodic by design

🛡️

Security Specialist

Trust boundaries, auth, OWASP — red-team thinking

🧪

QA Specialist

Test adequacy, edge cases — active in every review

🏛️

Architecture Consultant

Boundaries, dependencies, drift — guards against over-abstraction

⚡

Performance Analyst

Complexity, hot paths, scalability — without premature optimization

🔍

Independent Perspective

Anti-groupthink — the agent that caught F-023

📚

Docs / Knowledge

Detects docs drifting from implementation

🎨

UX Evaluator

Friction, state feedback, accessibility on user-facing changes

🎓

Educator

Walkthroughs & quizzes — powers the education gate (slide 13)

🔬

Project Analyst

Scouts external projects for patterns worth adopting

📊

History Analyst

Git archaeology: churn, reverts, repeat fixes — deep reviews only

Risk picks the panel

Risk	Panel	Mode
Low	2–3 agents	Ensemble — independent, parallel
Medium	3–4 agents	Structured dialogue — findings cross-examined
High	4–5 agents	Full panel incl. Security + Independent Perspective
Critical	5–6 — full panel	Adversarial mode; hard floor of ≥3 independent contexts, never fewer

Productive tension, by design

Specialists share the goal but hold different professional priorities — security and performance will naturally surface different concerns. Disagreement is surfaced and recorded, not smoothed over.

The plurality floor

Critical-risk changes carry a written floor of at least three independent contexts — so the framework can never quietly become single-reviewer without someone deciding to make it so.

Full roster detail, model tiers, and the five collaboration modes: docs/AGENT_ARCHITECTURE.md in the repo.

The Constitution

A Prime Objective + 7 Non-Negotiable Principles

The Prime Objective, in plain words ADR-0015

Above the seven principles sits one commitment: the framework must never accumulate value at your expense. Your attribution stays yours. Nobody's work gets harvested for a third party without consent. And the framework's own evolution can't feed on derived projects without a human saying yes — each time, per instance. The framework provides the gates; a human renders every verdict.

Each principle refuses a specific way AI systems extract value from the people who use them. Click to expand.

1Reasoning is the primary artifact.refuses: invisible reasoning▼

Code is output. Deliberation, trade-offs, and decision lineage are the durable assets. Every significant decision must be traceable to the discussion that produced it. Why: six months from now, the reasoning is more valuable than the code.

2Capture is automatic.refuses: silent forgetting▼

Enforced by scripts and hooks, not by instruction. If logging depended on model compliance, it would fail. A decision that exists only in a context window did not happen. Why: voluntary compliance doesn't work for audit trails.

3The generator is never the sole evaluator.refuses: agent-as-judge over human work▼

Independent review means a separate context that did not see the reasoning behind the code — an information property, not a personality. Why: self-review finds what it expects to find. Plurality — several independent contexts at critical risk, not one — is a dispatch concern, specified in selecting-review-gates and restated in /review.

4ADRs are never deleted.refuses: revisable history▼

Architecture Decision Records are only superseded, with references to the replacing decision — an immutable decision history. Why: understanding past decisions prevents repeating mistakes.

5Understanding before merge — offered, not withheld.refuses: bypassed understanding▼

Briefing depth is sized to risk and may be declined — the decline is recorded rather than judged. Skip is unavailable for exactly two classes: changes to the framework's own governance or safety mechanisms, and distribution to derived projects. Why: developers must be able to understand AI-generated code — but a machine-checkable condition may never make a human's briefing non-completable.

6Curated memory needs human approval.refuses: automated canonization▼

No insight is promoted to curated memory automatically — independent confirmations plus explicit human sign-off. Why: institutional knowledge must be deliberately curated, not auto-accumulated.

7Clarify before acting (the 95% rule).refuses: acting on unsurfaced assumptions▼

Before a plan, code, or any substantive action: reach ≥95% confidence on intent and scope. Close the gap from the project record first; ask only at a genuine fork evidence cannot resolve, and name what you extrapolate from. Mandatory unless explicitly overridden; micro-fixes exempt. Why: a wrong assumption acted on costs far more than the question that would have prevented it.

Retired in v3.6 — recorded, not dropped

A principle is retired the way an ADR is superseded: with a reference to where the value went. Old #3, Collaboration precedes adversarial rigor — the posture half retired as model-facing scaffolding; the plurality half survives as a dispatch concern (see Principle 3 and the plurality floor on slide 11). Old #8, Least-complex intervention first — moved to PHILOSOPHY.md § Growth has a brake as the growth-side constraint on how new complexity enters.

Human Ownership

AI Writes the Code. You Still Own It.

The fastest way to lose a codebase is to merge six months of code you can't explain. The framework treats your understanding as a gated deliverable — offered, never forced.

1. Walkthrough

The AI teaches the change — what it does, why the decisions were made, how the pieces interact. Depth is sized to risk.

2. Quiz

Comprehension check — from recall up to debug scenarios and “what breaks if we change this?” questions.

3. Explain-back

You explain it in your own words — proving comprehension, not recognition.

✓ Merge

You approve the merge understanding what you're approving.

Declinable — and that's recorded

You can decline a briefing; the decline is recorded, not judged. Only two classes can never skip it: changes to the framework's own governance or safety mechanisms, and distribution to derived projects.

Every gate is human-held

Nothing reaches curated memory without your approval. Nothing merges itself. Nothing pushes to a remote on its own. Autonomy means running the full workflow without nagging you — never skipping its steps.

Scaffolding fades

Education intensity adapts as demonstrated competence grows. It's a ramp for owning AI-written systems — not a permanent toll booth.

Evolution

It Improves Itself — and You Stay in Control

Macro

Quarterly evolution

Meso

Sprint retros

Micro

Per-discussion

Micro — every discussion

After each discussion, agents write structured reflections — what they missed, confidence calibration — stored in the SQLite index as raw material for improvement.

Meso — every sprint

/retro queries the index: reopened decisions, override frequency, recurring issue tags — and proposes process adjustments backed by that evidence.

Macro — quarterly

/meta-review scores agent effectiveness and drift, and proposes framework-level evolution — gated by the Steward, then by you.

Goal-seeking, safely: `/goal-loop`

For tasks with a verifiable done-state, you author a goal contract and a deterministic driver iterates build → verify → refine until the criteria are met. The builder is never its own judge (Principle #3 — the generator is never the sole evaluator — extended to autonomous iteration). The loop halts for /review plus an education walkthrough before you approve any merge. It never pushes, never auto-merges.

It learns from other projects, too

/discover-projects and /analyze-project score external patterns on a 5-dimension rubric; only ≥20/25 is recommended, and patterns seen in 3+ independent projects get priority. As of May 2026: 165 patterns evaluated — 62 adopted, 42 deferred, 33 rejected, every adoption and rejection documented with reasoning — decision lineage is preserved (Principle #1).

Single-loop: tune thresholds within the rules. Double-loop: change what counts as “good” — with evidence, through the Steward gate, with your approval. Nothing evolves behind your back.

The Honest Slide

The Honest Trade-Off

The value on slide 4 is real — and so is the bill. Here's what the framework asks of you, and when that's worth paying.

⏱️ Time

A typical panel review runs a couple of minutes; the six-specialist, high-risk review on slide 7 took fifteen. Planning and building commands are longer, deliberate sessions — that's the point of them.

🪙 Tokens

Every specialist is a separate context, so a panel review spends several times the tokens of a bare prompt, on your paid Claude plan. The telemetry dashboard tracks cost per discussion — the framework shows you its own bill.

🧰 Ceremony

It adds process. The framework matches ceremony to risk — micro-fixes are exempt, typos don't convene panels — but yes: there is more structure here than vanilla Claude Code.

Worth it when…

You'll still own this code in six months. Someone else will ask “why?”. AI is writing a meaningful share of the code and you need review it can't grade itself on. The day F-023 gets caught before your release night, the machinery has paid for itself.

Skip it when…

Throwaway scripts, one-shot prototypes, code you'll delete on Friday. Vanilla Claude Code is the right tool there — this framework earns its cost on code with a future, not on scratch work.

Your first win takes about ten minutes

Clone, install, run /review on one real file. A few minutes later you're holding a verdict, findings ranked blocking vs advisory, and a sealed record in docs/reviews/ — written by contexts that didn't write the code. Judge it on that.

Summary

From Vibe Coding to Engineering Discipline

✗ AI decisions disappear with the session → ✓ Every decision captured, sealed, and quotable years later

✗ The same AI writes and reviews → ✓ Independent contexts that never saw the builder's reasoning

✗ Unstructured, ad-hoc sessions → ✓ Structured commands with capture the AI can't opt out of

✗ Developers merge code they can't explain → ✓ An education gate that keeps you the owner — offered, not forced

✗ No quality enforcement → ✓ Two gates on every commit, enforced at the tooling layer

✗ A static, unchanging process → ✓ Three learning loops that evolve it — with a human holding the pen