Hexaphase: Make the Repo the Memory. An SDLC Framework for Coding with AI

The problem nobody standardized

In about two years, AI went from autocomplete to agents that write whole features. Yet our process for using it is improvised. Each developer invents their own prompts, their own context files and their own habits. Projects built that way tend to share three symptoms:

1. Amnesia. Every session starts from zero. The AI re-learns the project, or worse, guesses.
2. Skipped thinking. It's so easy to generate code that planning, design and testing quietly disappear.
3. Sprawl. Code, notes, experiments and docs end up mixed together in one folder.

Agile and Scrum standardized how teams organize work. Hexaphase is an attempt to standardize how humans and AI organize a project.

The whole framework in one picture

your-project/
├── ai-instructions.md
├── project-health.md
├── 1-Planning/
├── 2-Analysis/
├── 3-Design/
├── 4-Coding/
│   ├── main-app/
│   └── <supporting-app>/
├── 5-Testing/
└── 6-Deployment/

Two root files

• ai-instructions.md is a tool-agnostic contract: where things belong, how sessions start and end, and the rules (don't skip gates, ask instead of assuming, no secrets, no destructive actions).
• project-health.md is the single source of truth: current phase, gate approvals, risks, decisions and a session log, newest first.

Six numbered folders

The numbers encode the order of work and keep the folders sorted identically in every IDE and in every AI's context. All application code lives in 4-Coding/. main-app/ is always the thing you launch, and every supporting app gets its own folder.

Three rituals

Why this works

• Files outlive sessions. Context windows reset; project-health.md doesn't.
• Gates restore the thinking step. The AI can draft a design in seconds. The gate just makes sure someone looked at it.
• Traceability for free. Requirement IDs (US-03) flow from planning to design, code commits and test cases.
• Tool independence. It's just Markdown and folders. Switch from Claude Code to Gemini CLI tomorrow and nothing breaks.

Tested, not just proposed

Before release I ran the same script in a fresh session of each supported tool: Hexaphase Session Start → "write scope.md" → Hexaphase Session End.

Other tools (Cursor, Copilot, Codex, ChatGPT) should work, since it's all Markdown, but they're not verified yet. The guide explains how to try them.

A real example, built in public

SpendCLI is a small expense-tracking CLI I'm building with Hexaphase Lite right now. It's in progress, and you can follow along live: each phase lands in the repo as it's done (planning docs, design notes, code in 4-Coding/main-app/, the test checklist, the deployment), and project-health.md shows the current phase, which gates are approved, and the full Session Log.

It's not waterfall

Going back is expected. A failing test can reopen the design; the change is logged in the Decisions Log, and work moves on. For bigger products, run the six phases per feature inside your sprints.

Try it

1. Get the template: npx degit divyekksoni/hexaphase/template my-app (or download the repo ZIP and copy the template/ folder).
2. Fill in the project overview in ai-instructions.md, or ask the AI to interview you and fill it in.
3. Open the project in Claude Code or Gemini CLI and type Hexaphase Session Start. End with Hexaphase Session End.

New to coding? The README has a step-by-step Quick Start that assumes no programming experience.

👉 github.com/divyekksoni/hexaphase

Early-adopter study: use Hexaphase on a real project for 4 weeks and share honest feedback. It will shape v1.1 and a research paper. Sign up: https://forms.gle/gQLAMtDLiK3H16xe9

Case studies are welcome too, both successes and failures. Open an issue with the case-study label.

Hexaphase™ is created by Divyek Soni and released under CC BY 4.0 (docs) and MIT (template). Cite it: 10.5281/zenodo.24029073.