The Codebase Singularity

Agentic Handbook

Central thesis: Build a sufficiently powerful agentic layer around your codebase — climbing a concrete ladder of classes and grades — until you reach the codebase singularity: the moment your agents can run your codebase better than you and your team can.

Overview

At the center of everything is the agentic layer — the new ring around your codebase where you teach your agents to operate your application on your behalf, as well as and better than you and your team could. Focusing on building this layer is the highest-ROI action for any engineer in the age of agents, because when you scale your compute you scale your impact. Compute in its most useful form is a prompt in a loop with tools — an agent — and this transformed the big three into the core four: context, model, prompt, tools.

The codebase singularity is a singular moment in your career: once your agentic layer is powerful enough, you realize your agents can now run your codebase better than you can. You trust them to ship more than you trust yourself or your team; nothing reaches production without your teams of agents. This is not something to fear — it is something to run toward.

To get there, this lesson lays out a maturity model of three classes (the agentic layer's tiers), each with one to N grades. Every grade is uniquely identified by a new distinguishing dimension. The green outer layer is the agentic layer; the dark inner layer bundles your entire application (database, front end, backend, scripts, DevOps) — often multiple repositories via git sub-modules, so agents can see everything at once.

You do not start at class three. You start with nothing and climb. The goal is not to race to the top but to identify where you are, spot the missing pieces, and make a plan to build them in.

Key concepts

The Codebase Singularity

The point at which you trust your agents, powered by your agentic layer, to ship better than you and your team — from prompt to production. There is an agentic layer that could exist inside your codebase so powerful that your codebase runs itself. The only question is whether you know how to build it. This is the North Star of the entire course.

The classes-and-grades maturity model

Three classes stack (each class contains all grades below it). Each grade is defined by one distinguishing dimension:

Class	Grade	Distinguishing dimension
1 — In-loop agentic layer	1	Prime prompt and/or memory files (the thinnest possible layer)
1	2	Specialized/plan prompts + sub-agents (specs dir, AI docs)
1	3	Custom tools — skills, MCP servers, prime commands with tool access
1	4	Feedback loops — closed-loop prompts (review, reproduce-bug, test)
1	5	Templates — structured plans with output formats (bug/feature/chore)
1	6	Prompt chains / agentic workflows (plan→build, scout→plan)
1	7	Agent experts — domain mental models keeping track of areas
2 — Out-loop (Peter) system	1	Webhook / HTTP endpoint calling prompts via the agent SDK
2	2	AI Developer Workflows (ADWs) — deterministic code + agents end to end
3 — Orchestrated system	1	The orchestrator agent CRUDs and commands your agents
3	2	Orchestrator Developer Workflows (OA conducts multi-team workflows)
3	3	Orchestrator can run AI Developer Workflows (raw code + full observability)

Notes on the ladder: Grade 3 is where many engineers get stuck — their tools are bloated, token-heavy, and do not scale; designing the right tools is a skill in itself. Grade 4 self-correcting agents are a massive win (request → validate → resolve). Grade 5 templates are where you truly teach agents to build like you do. Grade 6 makes context engineering a hard requirement — you cannot write a five-agent chain without adopting your agent's perspective. Grade 7 experts are the most slept-on, highest-ROI piece and lead directly to the singularity's doorstep. Class 2 is where you get out of the loop; ADWs (class 2, grade 2) are the single highest leverage point of agentic coding — deterministic control plus non-deterministic agents. Class 3 is orchestrated agentic coding, and grade 3 lets the orchestrator invoke ADWs so massive jobs stay observable and controllable.

The three modes (in-loop → out-loop → orchestrated)

Each class jump is a different type of agentic coding, and each is a hard transition:

graph LR
    C1[Class 1: In-loop
prompts, sub-agents, skills,
closed loops, chains, experts]
    C2[Class 2: Out-loop
webhook + ADWs,
agents run without you]
    C3[Class 3: Orchestrated
orchestrator commands
teams of agents]
    C1 -->|get out of the terminal| C2
    C2 -->|build a manager of agents| C3
    C3 --> ZTE[Zero-Touch Engineering
→ Codebase Singularity]

• In-loop (Class 1): you are in the terminal, scaling up prompts, sub-agents, skills, feedback loops, templates, chains, and experts on the first layer.
• Out-loop (Class 2): you expose a webhook (Slack, Jira, GitHub, Discord) that fires prompts via the agent SDK; agents run while you are not there. ADWs give deterministic control between each non-deterministic agent step — logging, validation, retries.
• Orchestrated (Class 3): an orchestrator agent — a custom "lead engineer" that runs CRUD on agents — conducts teams of agents, and can itself run ADWs.

Orchestrator Developer Workflows

At class 3, grade 2, you build orchestrator developer workflows: like ADWs, but you prompt an orchestrator that understands your agents, prompts, and skills, which then commands and converses with command-level agents. This creates a multi-level, open stream of communication — the orchestrator can spin up multiple teams on multiple problems, every event is summarized by a summary agent and reported back, and you can talk to any agent in the workflow at any time. The distinction at grade 3: the orchestrator can fire an AI developer workflow (raw, deterministic code) rather than only orchestrator workflows, because massive non-deterministic chains still need to be tracked, observed, and controlled.

How to apply it

1. Locate yourself on the ladder. Identify your current class and grade honestly — most engineers plateau at grade 3 (custom tools) or grade 6 (chains).
2. Start every codebase with a class-1, grade-1 layer. A prime command plus a memory file. If you have this, you technically have an agentic layer.
3. Add custom tools carefully (grade 3). Give agents only what they need — skills, a lean .mcp.json, or a prime command that teaches CLI usage (e.g., psql). Do not over-tool.
4. Install feedback loops (grade 4). Add closed-loop prompts (review, reproduce-bug, test-front-end, test-back-end) that follow request → validate → resolve. More compute should mean more trust.
5. Template your engineering (grade 5). Turn ad-hoc plans into bug/feature/chore templates with fixed output formats and embedded validation. Specialize them to this codebase — do not chase generic reuse.
6. Chain prompts into workflows (grade 6). Compose plan→build, scout→plan. Always keep each step runnable individually so you can isolate failures and parallelize.
7. Build agent experts into risky/complex areas (grade 7). Give agents domain mental models; this is where agents begin solving problems end to end without you.
8. Get out of the loop (class 2). Expose a secured webhook, drive prompts through the agent SDK, then replace prompt chains with full ADWs (deterministic scaffolding + agents).
9. Add an orchestrator (class 3). Build a custom agent that CRUDs and commands your agents; layer on orchestrator developer workflows and give it the ability to run ADWs.
10. Target zero-touch engineering. Aim for one-shot, end-to-end, prompt-to-production workflows — the doorstep of the codebase singularity.

Commands & conventions

Codebase shape (the winning structure):

repo-root/
├─ apps/                    # application layer (dark inner layer)
│  ├─ client/               # separate git sub-module if needed
│  ├─ server/               # separate git sub-module if needed
│  └─ .../                  # database, devops, notebooks — all co-located
├─ .claude/
│  ├─ CLAUDE.md             # memory file (always loads)
│  ├─ commands/             # raw prompts: plan, build, review, test-*, bug/feature/chore
│  │  └─ experts/<domain>/  # expertise file + question/self-improve prompts
│  ├─ agents/               # sub-agents (fetch-docs, test-writer, scout, planner)
│  └─ skills/               # skills (start/stop app, migrate db)
├─ ai_docs/                 # docs pulled in to aid agent context
├─ specs/                   # plan files
├─ app_reviews/             # review / bug-reproduction / resolution outputs
├─ .mcp.json               # MCP servers (Postgres, Firecrawl, Jira, Notion…)
└─ adws/                    # AI Developer Workflows (+ orchestrator at class 3)

Convention	Guidance
Git sub-modules	Put every application under apps/; bring separate repos in as sub-modules so agents see everything cleanly in one place.
Specialize, don't genericize	Your agentic layer should be tuned to this codebase. Duplicate and specialize per product rather than building one-size-fits-all.
Always keep steps runnable alone	Never build a plan→build→review chain whose pieces cannot run individually — you must be able to isolate failures and parallelize.
Skills/MCP ≈ prompts	Skills and MCP servers can both be replaced by a well-crafted prompt; a skill is just a markdown file referencing other files.
Core four is everything	Skill, chain, agent, workflow — every abstraction reduces to context, model, prompt, tools.
Impact over infrastructure (here)	This ladder tracks raw capability; hooks, logging, and observability matter but are deliberately set aside to focus on impact.

Key takeaways

• The agentic layer is the highest-ROI investment in the age of agents; build the system that builds the system, not the application layer.
• Climb the ladder deliberately: class 1 (in-loop) → class 2 (out-loop) → class 3 (orchestrated), each grade adding one distinguishing capability.
• Custom tools (grade 3), feedback loops (grade 4), templates (grade 5), chains (grade 6), and experts (grade 7) are the class-1 progression most engineers must master.
• ADWs (class 2, grade 2) are the single highest leverage point — deterministic code plus non-deterministic agents with full logging, validation, and retries.
• The orchestrator agent (class 3) is a custom lead engineer that CRUDs and commands teams of agents and can run ADWs (grade 3).
• Co-locate all related applications under apps/ via git sub-modules so agents have full visibility; specialize the agentic layer to your codebase.
• The point is not to reach class 3 for its own sake but to find your position, spot missing pieces, and build them in.
• Target zero-touch engineering; when agents can ship better than you can, you have reached the codebase singularity.

Notable quotes

"My agents can now run my codebase better than I can. I trust them to ship more than I trust myself or my team."

"The current state of your codebase is only a step to the next state of your codebase."

"You're building the machine that builds your product now. You're building the system that builds the system."

"This is not something to fear, it's something to run toward."