ProjectGenesis: A Repo-Native Control Layer for AI-Built Software

I created ProjectGenesis because I kept running into the same problem with AI-assisted software work.

The first build session is exciting.

You have an idea. You explain it to an AI tool. It generates files. You adjust the prompt. It fixes something. You add a feature. It creates more files. The demo starts to look real.

Then the project begins to grow.

The chat gets long. The context gets noisy. Decisions are buried in old messages. The AI starts treating guesses like facts. Requirements are implied instead of written down. Tests appear after the implementation instead of before the risk is understood. A new agent joins the work and spends half the session rediscovering what the previous agent already knew.

That is the point where AI speed stops feeling like leverage and starts feeling like entropy.

ProjectGenesis is my attempt to give that workflow a stronger spine.

It is not a framework, runtime, SaaS product, or magic prompt. It is a reusable, Markdown-first software delivery scaffold that lives inside the repository. The goal is simple: let AI agents work from durable project files instead of relying on memory, chat history, or hidden prompt state.

The problem is not that AI writes code

AI coding tools are already useful. They can draft features, refactor files, explain unfamiliar code, write tests, and help turn an idea into something visible very quickly.

The weak point is not typing speed.

The weak point is project control.

Most AI-built projects begin with rough material: a product idea, screenshots, customer feedback, notes from a conversation, a half-written spec, or a few bullets about what the app should do. That raw input is valuable, but it is usually messy. If you hand it directly to an agent and ask for implementation, the agent has to fill in the gaps.

Sometimes that is fine. Often it is not.

The agent may invent requirements. It may miss constraints. It may forget why a decision was made. It may generate a tidy backlog that does not trace back to any real source. It may write tests for the happy path while leaving the risky part unvalidated. It may continue confidently because the prompt sounds clear enough, even when the underlying work is not ready.

That is why ProjectGenesis starts before implementation.

It gives the project a place to hold the truth before code begins.

What ProjectGenesis does

ProjectGenesis gives an AI agent a governed path from rough input to buildable work.

You can drop raw material into 00_intake/raw/: rough notes, product ideas, research, screenshots, feedback, early specs, or references. Then you ask the agent:

Start requirement breakdown.

That phrase is not meant to be a vague instruction. In the scaffold, it resolves through COMMANDS/COMMAND_INDEX.md to a reusable workflow prompt in COMMANDS/start-requirement-breakdown.md.

The agent is expected to register sources, assign stable source IDs, summarize the input, extract product context, identify requirements, record assumptions, surface risks, list open questions, create backlog candidates, draft specs where appropriate, identify architecture decision candidates, map validation needs, update traceability, and leave a handoff.

The important part is what it does not do.

It does not pretend every AI output is true.

ProjectGenesis separates what is confirmed, what is inferred, and what is still an assumption. It expects important requirements to trace back to source material or approved assumptions. It makes unclear input visible instead of hiding it inside confident prose.

That distinction matters because AI work often fails quietly. The bad decision does not always look bad when it is written. It becomes expensive later, when the implementation has already hardened around an assumption nobody approved.

The repo becomes the memory

The core idea behind ProjectGenesis is that repository files are the source of truth. Chat history is only context.

That sounds small, but it changes how agents behave.

Instead of asking a model to remember everything from a long conversation, you give it a stable workspace:

• 00_intake/ for raw inputs, source IDs, and summaries
• 01_context/ for product brief, charter, glossary, and constraints
• 02_requirements/ for requirements, assumptions, and risks
• SPECS/ for product, feature, spike, and implementation specs
• ADR/ for architecture decision records
• BACKLOG/ and BACKLOG.md for planning
• TESTS/ for acceptance maps and manual validation checklists
• REVIEWS/ for review records and PR review packages
• CONTEXT_PACKS/ for scoped read manifests
• memory/ai/ for shared agent rules and role definitions

That structure gives Codex, Claude, Gemini, or another agent the same working memory. A new session can read the same files, follow the same roles, inspect the same handoff, and continue without pretending that chat memory is durable.

This is especially useful for builders who move quickly. If you are vibe coding, you do not want a process that kills momentum. But you also do not want your project to become a pile of untraceable decisions after the first weekend.

ProjectGenesis is meant to sit in that middle space: lightweight enough to use, structured enough to keep the work reviewable.

Why traceability is the real feature

The most important feature is not the folder structure.

The most important feature is traceability.

When raw input becomes a requirement, there should be a line back to the source. When a requirement becomes a spec, the spec should preserve the reason and acceptance criteria. When a spec becomes backlog work, the backlog item should know what it is satisfying. When implementation begins, the task should have a definition of ready. When tests are written, they should map to acceptance criteria. When a review happens, the reviewer should be able to inspect the evidence instead of trusting the implementer's memory.

That is the difference between "the AI made a plan" and "the project has a plan."

ProjectGenesis includes files such as TRACEABILITY_MATRIX.md, ARTIFACT_REGISTRY.md, CURRENT_STATE.md, AI_HANDOFF.md, TEST_RESULTS.md, and review templates because AI-assisted work needs more than a good first draft. It needs visible state.

The scaffold also includes baseline validators:

bash SCRIPTS/validate-bootstrap.sh
bash SCRIPTS/validate-bootstrap-red-checks.sh

Those scripts are intentionally simple. They are not trying to prove your product is correct. They are there to catch scaffold-level drift and make sure the basic governance files still exist and stay connected.

It is built for multiple agents

One practical lesson from building with AI is that one agent rarely covers the whole job well.

A product analyst should not behave like an implementation agent. An implementation agent should not approve its own architecture. A security reviewer should not rely on the same context framing as the person who wrote the code. A documentation curator should not invent product facts because a source is missing.

ProjectGenesis includes shared role files under memory/ai/, including roles for product analysis, spec authoring, architecture, implementation, QA, security review, documentation, backlog planning, adversarial PR review, and release review.

That does not make the agents perfect. It gives them clearer boundaries.

The repo also includes review records and PR review package templates because fresh-context review is one of the strongest safeguards against AI confidence. A reviewer should be able to read the repository evidence and challenge the work from there, not from the implementer's explanation of why everything is fine.

The intended flow

The basic workflow is deliberately plain:

1. Copy the scaffold into your project or use the repository as a template.
2. Add rough material into 00_intake/raw/.
3. Ask your AI agent to run Start requirement breakdown.
4. Review the generated context, requirements, assumptions, risks, questions, backlog candidates, specs, and validation needs.
5. Fix the unclear parts.
6. Start implementation only when the relevant work is ready enough to build and validate.

That is it.

The goal is not to make AI development slower. The goal is to prevent speed from destroying the project's memory.

If the work is clear, ProjectGenesis should help the agent move faster because it knows where to look and what to update. If the work is unclear, the scaffold should make that visible before the project turns uncertainty into code.

What it is not

ProjectGenesis is not a replacement for product judgment.

It does not remove the need for engineering review, security review, user research, legal review, or real validation. It gives those activities a place to live and a process agents can follow.

It is also not tied to one AI vendor. The README is explicit about this: the scaffold is intentionally plain Markdown first, and it can work across Codex, Claude, Gemini, and other agents because the project state lives in files.

That matters to me. I do not want project continuity to depend on one tool's hidden memory. I want the repo to carry the context.

Why I made it public

I made ProjectGenesis available because I think a lot of AI builders are hitting the same wall.

The first prototype is easier than ever. The second phase is where things get messy. You need to decide what is real, what is assumed, what is risky, what is ready, what needs review, and what evidence proves the work is correct.

That is not a prompt problem. It is a project system problem.

ProjectGenesis is my current answer to that problem: a repo-native scaffold for turning messy AI-assisted ideation into reviewable software delivery artifacts.

It is still intentionally simple. It is mostly Markdown, workflow prompts, role files, validation scripts, examples, and governance docs. That is the point. The foundation should be inspectable. You should be able to open the files, understand the process, change it for your project, and keep moving.

If you build with AI and want your ideas to survive past the first exciting build session, ProjectGenesis might help.

GitHub: github.com/mrhussamahmed/ProjectGenesis