A methodology and toolkit for building real software with AI tools, designed to respect what the tools can and cannot do.
This repository contains a methodology for structured AI-assisted development, born from real production work and shaped by what AI tools can and cannot reliably do. It is not a framework, a library, or a wrapper around an AI provider. It is a disciplined way of thinking, planning, and executing that turns AI coding tools from unreliable oracles into reliable partners.
Two ways to work with an AI coding tool
┌──────────────┐
│ you have │
│ an idea │
└──────┬───────┘
│
▼
┌──────────────┐
┌────►│ prompt │◄────┐
│ └──────┬───────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ output │ │
│ │ (looks ok?) │ │
│ └──────┬───────┘ │
│ │ │
│ ┌─────┴─────┐ │
│ │ │ │
│ ▼ ▼ │
│ "not quite" "fine i │
│ guess" │
│ │ │ │
└──────┘ │ │
▼ │
┌──────────────┴┐
│ silent debt │
│ accumulates │
└──────┬─────────┘
│
▼
┌─────────────┐
│ one day: │
│ it breaks │
│ expensively│
└─────────────┘
flowchart TD
A[you have an idea] --> B[planning session<br/>with AI]
B --> C{gap analysis<br/>human gate}
C -->|approved| D[briefing + companion<br/>artifacts]
C -->|gaps found| B
D --> E[phased plan]
E --> F[Phase: kickoff<br/>inspector reviews]
F --> G{human gate:<br/>concerns addressed?}
G -->|yes| H[Phase: build]
G -->|no| F
H --> I[automated review chain<br/>test → code → constitution]
I --> J{review pass?}
J -->|no| H
J -->|yes| K[phase complete]
K --> L{more phases?}
L -->|yes| F
L -->|no| M[close plan<br/>audit + retrospective]
M --> N[working software<br/>with documented debt<br/>and learnings captured]
style A fill:#e8f4f8
style N fill:#d4edda
style C fill:#fff3cd
style G fill:#fff3cd
style J fill:#fff3cd
The constraint this methodology is designed around
Most published advice about AI-assisted development treats the AI tool as an oracle with unlimited memory. It is not. Every model has a finite context window, and every long session degrades — earlier decisions get forgotten, contradictions creep in, work gets repeated, and the quality of judgment declines as the context fills. This is not a flaw in any particular tool. It is a physical property of how these systems work. Pretending it isn't there is the single largest reason vibe coding produces what it produces.
The methodology in this repository is architected around that reality. Phases are sized to fit cleanly within a single execution context, so the tool never has to operate while running out of room. The planning conversation happens in a different context from the build session, so the planner is not competing with the implementer for context budget. A briefing artifact and a companion document carry state forward in writing rather than relying on the AI to remember — when context resets, the artifacts are the source of truth. The constitution holds decisions stable across sessions so they aren't relitigated when memory degrades. The learnings file accumulates patterns across plans so insights from one plan inform the next without needing to be re-derived.
The honest qualifier: the structural protections work when the architect uses them as intended. They fail in two predictable ways. The first is when a session uncovers something unexpected mid-phase — something that isn't large enough to warrant a new plan but is important enough to get right — and the session runs longer than the phase was sized for. The second is when the architect spots an opportunity and pivots without first recognizing the new constraints the pivot creates. Both are human moves, not tool failures, and both are normal. The methodology cannot prevent them. What it can do is make them visible: a phase running long is a signal worth noticing, and a pivot taken without a fresh planning conversation is the moment where the architect has to decide whether the cost of pausing to re-plan is greater than the cost of pushing through. Sometimes pushing through is the right answer. The methodology asks you to notice that you've made the choice.
This is not bureaucracy. It is structural respect for what the tool can and cannot do — and structural awareness that the architect is the one variable the methodology cannot constrain.
What this is
This methodology separates the conversation where you think from the session where you build. A planning session — typically run in a chat interface like Claude.ai — produces two artifacts: a briefing scoped to the building agent, and a companion document that carries voice and judgment forward into future sessions. The building agent — Claude Code, in the original implementation — executes against a phased plan with a serial review chain that runs automatically per phase: test gate, code reviewer, constitutional auditor, phase completer. A constitution of eleven articles pre-decides implementation choices so they aren't relitigated mid-build. Deferred work gets documented, not blocked.
The methodology is curated and portable on purpose. Every piece is in here because it was needed, not because it sounded good. The artifacts have been used to ship 16 plans, 68 phases, and approximately 98 active hours of production work over a 10-day window — all in a real codebase that real users access. The velocity reference in this repository documents that work in detail.
What changes is your role. Under this system you are not babysitting a process. You are a constructive partner reviewing work that is mostly right, looking for the nuance that a mission-driven agent will miss. The discipline lives in the system; your job is to bring judgment and to get out of its way.
What's in this repository
planning_protocol.md— The protocol for running a planning session. Keep this with you in your chat interface of choice — it is not meant to live in your codebase, and the build surface never reads it.workflow_automation.md— The operational guide for executing plans. Describes how the skills, subagents, and templates work together during a build session.constitution.md— Eleven articles that pre-decide implementation choices. Eight are domain-neutral and apply to any project. Three are flagged as domain-specific and must be replaced by the adopting project.velocity_reference.md— Documented velocity from real plans, with complexity tiers, per-phase throughput, and scaling factors. Use this to estimate your own work..claude/agents/— Eight subagents that run the review chain (planner, plan-inspector, reviewer, constitutional-auditor, test-gate, phase-completer, retrospective, plan-closer)..claude/commands/— Four skills (slash-commands) that orchestrate the workflow (/plan,/kickoff-phase,/complete-phase,/close-plan)..claude/templates/— Eight templates for plans, phase artifacts, and closeouts..claude/hooks/pre-commit-guard.sh— A behavioral guard that prevents commits without an updated changelog and an advanced plan primer.what_this_methodology_does_not_do.md— A standalone document on the methodology's real boundaries and what the architect is responsible for bringing to the table.
How to adopt this
The methodology is designed to be cloned, adapted, and put to work without ceremony. A reasonable adoption path:
- Clone or copy the repository contents into your project's root, except for
planning_protocol.md, which belongs in your chat interface's project workspace, not in your codebase. - Rename the constitution articles' identity references and adapt the three domain-specific articles (currently flagged) to your project's domain.
- Establish a
docs/plans/directory in your project where plan artifacts will live. - Wire the pre-commit hook into your Claude Code settings (the snippet is in the hook script's header).
- Run your first
/plancommand on a small piece of work and follow the flow through to/close-plan. The first plan will teach you more than reading the documentation will.
The methodology's features, once understood, are easily modified to fit the needs and work patterns of a small team or solo developer. Adjust the gates, change the cadence, simplify the constitution if you don't need all eleven articles. The shape is more important than the specifics.
A note on where things run
The methodology uses two execution surfaces, and the artifacts are split between them deliberately.
Planning runs in a high-reasoning chat interface — Claude.ai is the original implementation, but any sufficiently capable conversational AI will work. The planning protocol (planning_protocol.md) lives with you, not in your codebase. Copy it into a project or workspace in your chat interface of choice. Planning sessions happen there, away from the noise of code execution and tool calls. The output of a planning session is the artifact pair — briefing and companion — which gets written into your codebase's docs/plans/ directory for the build surface to consume.
Building runs in Claude Code — the subagents, skills, templates, hooks, and constitution all live in the .claude/ directory of your project. Build sessions execute against the briefing produced by the planning session. The build surface never sees the planning conversation; it sees only the artifact, which is deliberate. State that needs to survive context resets lives in writing, not in memory.
This split is what allows the methodology to respect context windows. It is also what lets each surface specialize — the planning surface for judgment and conversation, the build surface for execution and review. Trying to do both in the same context is a common mistake and a major contributor to the kind of degradation the methodology is designed to prevent.
What this methodology does not do
The methodology is bounded in ways worth understanding before you adopt it. It does not raise the business questions a project must answer before deployment. It does not know everything — esoteric processes and unfamiliar frameworks must be introduced to it deliberately. It is not a substitute for your own thought, and the planning process can help with these gaps only when you initiate the right conversations.
The standalone document what_this_methodology_does_not_do.md covers each of these in detail. Read it before you adopt.
Provenance and proof of life
This methodology was built to ship save.ag — a knowledge platform for regenerative agriculture with over 230,000 curated content clusters, evidence grading, and controversy detection across YouTube transcripts, podcasts, academic papers, and web content. The velocity numbers in velocity_reference.md are from real plans against the save.ag codebase, not synthetic examples. If you want to see what the methodology produced, the platform is the answer. Go look at it.
License and contribution
MIT licensed. Adopt freely.
Issues are disabled and there is no support channel. This repository is what I use; you are welcome to adopt it, fork it, or take it apart for parts. I am not maintaining this as a public project.
If the methodology helps you build something that matters, that's the only return I'm looking for.