How to Turn any Repository into a Senior AI-Powered Development Environment

large

The Problem I Kept Running Into

Every time I started a new AI session, I found myself doing the same thing: re-explaining the project, re-describing the architecture, re-telling the AI what we were working on. Sometimes it would take 10–15 minutes just to get the AI to the point where it could actually help. And the next day? Same thing. Start over.

I was using Claude Code and Windsurf heavily on the CWAN API Service project, our API gateway platform here at Clearwater Analytics. Over 18 months of daily iteration on a production platform with 1,200+ API endpoints, our team built something that worked really well. The AI knew the codebase. It knew the architecture. It picked up where we left off every single session. The workspace grew to 93 workflows, 14 specialized agents, and 79 slash commands, and the team was genuinely operating at a different level than teams that were just using “AI chat.”

The question I kept asking myself was what exactly made it work? And could I package that so any team, on any codebase, could have the same thing?

That question led to the Agentic-Repos framework.

What Makes an “Agentic Repository” Different

A standard repository contains code. An agentic repository contains code plus a complete AI knowledge layer. The difference is significant.

The way I describe it, a standard repo is an empty apartment. The walls are the same, the plumbing is the same, but one is ready to live in. An agentic repository is furnished. When you open it in Claude Code or Windsurf, the AI already knows:

• What the project does
• What tech stack it uses
• What the current priorities are
• What was accomplished in the last session
• Where to find any specific piece of information

It does not ask you to explain the project. It does not start from scratch. It picks up where you left off.

The way this works is not magic. It is a set of files that load automatically when the AI session starts, a structured knowledge base it can navigate efficiently, and specialized agents tailored to the specific tech stack.

The Six Principles I Extracted from the CWAN API Service

After 18 months of running this in production, I distilled the approach into six principles. Every one of them is non-negotiable.

1. Evidence-Based Only. Every AI claim cites a source: file path and line number, or a URL. “I think” and “probably” are not acceptable in an engineering environment.
2. Zero Hallucination. When the AI is uncertain, it says so explicitly with confidence levels: HIGH, MEDIUM, or LOW. No invented endpoints, no made-up configurations.
3. Single Source of Truth. Agent prompts live in one location. Every wrapper and slash command is a thin pointer. When you update an agent, you update it once. On CWAN API I now maintain 93 workflows, 14 specialized agents, and 79 slash commands. Without single source of truth, keeping that many agents in sync would be impossible.
4. Session Continuity. Every session starts by reading the project context and a progress tracker. The AI never asks “what are we working on?” It reads the tracker and continues. This single pattern changed how my team interacted with AI more than any other.
5. Knowledge Graph Navigation. Knowledge is organized in a structured graph with tiers of authority. The AI navigates it in constant-time lookups instead of grepping through the filesystem.
6. Generated Artifacts Standard. All AI-produced content goes to a Generated/ directory. Knowledge is read-only. Source of Truth is immutable. Mixing AI output with authoritative knowledge corrupts the knowledge base.

The reason these work together is that they address the three biggest failure modes I kept seeing in teams using AI for development. The AI makes things up, the AI repeats itself because it has no memory, and the AI produces content that nobody can find or trust.

The Architecture

Here is what the AI knowledge layer looks like inside a repository after you run the conversion:

Each piece solves a specific problem:

CLAUDE.md loads automatically when you open the project in Claude Code. It tells the AI the rules it must follow, the commands available, and the structure of the project. This is not a generic set of instructions. It is tailored to the detected tech stack. AGENTS.md does the same for Claude Code’s workspace context.

START_HERE.md is what the AI reads at the beginning of every session. It contains the current project context, what the team is working on, and the priorities. This is the file that eliminates the “let me understand your project” conversation that wastes the first 10 minutes of every AI session.

The Knowledge Graph is the piece most people overlook, and it is the piece that makes the biggest difference. Instead of the AI searching blindly through files, it uses a structured graph with authority tiers, concept clusters, and a search index. Tier 1 is Source of Truth — documents that only humans can modify. When two documents conflict, the higher tier wins.

The Generated/ directory keeps AI output separate from human-authored knowledge. This seems like a small detail, but it is critical for trust. If everything in Knowledge/Source of Truth/ was verified by a human, and everything in Generated/ was produced by AI, you always know what to trust.

One Command to Convert Any Repository

The reason I built this as a framework rather than just documenting the CWAN API Service setup is that I wanted any team to be able to apply it to any codebase. The result is a single command:

You provide a repository URL or a local path. The framework:

1. Clones the repo if needed
2. Detects the tech stack by examining the actual files (Spring Boot, FastAPI, Express, Terraform, and more)
3. Counts endpoints, analyzes authentication patterns, finds tests and CI/CD config
4. Generates CLAUDE.md with rules tailored to the detected stack
5. Creates the full Knowledge/ structure
6. Generates three specialized agents: a developer agent, a researcher agent, and a code reviewer agent
7. Creates slash commands for code review, session context, and repo analysis
8. Builds a Progress Tracker so the next session picks up where this one left off

The entire thing is evidence-based. Nothing is invented. The agent reads actual files before making any claim about the repo. If you use Windsurf instead of Claude Code, the equivalent /convert-repo-to-agentic workflow is included as well.

How the Detection Works

One thing I spent real time on was making the tech stack detection reliable. The agent does not assume. It runs detection commands:

Then it adapts what it generates based on what it actually finds. A Spring Boot repo gets a CLAUDE.md with Maven commands and Spring-specific patterns. A FastAPI repo gets pytest patterns and uvicorn startup commands. A Terraform repo gets HCL syntax guidance and resource patterns.

The generated agents are also adapted. A developer agent for a Spring Boot service knows about annotations, Maven lifecycle, and Spring idioms. A developer agent for a FastAPI service knows about async patterns, Pydantic models, and pytest fixtures.

Session Continuity: The Piece That Changes Everything

I want to be specific about session continuity because this is the part that has the biggest practical impact.

In a standard AI workflow, every session starts from scratch. You explain the project, you explain what you are working on, you explain what you tried last time. This wastes time and leads to repetition.

In an agentic repo, the first thing the AI does in every session is run three reads:

1. START_HERE.md — current project context
2. Knowledge/KNOWLEDGE_GRAPH.md — navigation map
3. Generated/PROGRESS_TRACKER.md — where we left off

The Progress Tracker is updated at the end of every session using /project:generate-session-context. It captures what was accomplished, what is in progress, what decisions were made, and what the next three priorities are. The next session starts by reading it and continuing directly.

The difference in experience is significant. Teams that use this stop re-explaining their projects to AI. They start treating AI sessions the way they treat a colleague who was in the last meeting: you do not re-introduce the project, you just continue.

How I Built This Over 18 Months

This did not start as a framework. It started as a messy collection of markdown files in one repository.

1. I wrote the first CLAUDE.md file and a handful of workflow scripts. The AI stopped making certain categories of mistakes because it had explicit rules to follow. But there was no structure, and every new repository required manual setup.
2. I added the Knowledge Graph pattern after realizing that flat folder structures do not scale. The AI was spending too much time searching for information. The graph gave it a navigation map with O(1) lookups instead of O(n) grep searches. I also introduced the Source of Truth tier: documents that only humans can modify, which the AI must defer to when conflicts arise.
3. I built specialized agents for different roles: developer, code reviewer, researcher, architect, scrum master. Each agent had its own context and instructions. The single source of truth pattern for agents became necessary when the number of agents grew, because duplicate content was already drifting.
4. I introduced session continuity with the progress tracker. Before this, every AI session started from scratch. After this, the AI read what happened in the last session and continued directly. I also started building the Markdown Knowledge Base system that became the foundation of the knowledge layer.
5. I generalized everything into the Agentic-Repos framework. The conversion command was built so that any repository, regardless of tech stack, could get the full agentic layer with a single command. The detection system reads the actual files (pom.xml, build.gradle.kts, package.json, requirements.txt, go.mod) and adapts everything it generates.
6. The pattern is now becoming part of the CI/CD pipeline. New repositories get the agentic layer as part of their initial scaffolding. The Knowledge Graph is maintained as a living document that gets updated when architecture decisions are made, not as an afterthought at the end of a sprint. I published the enterprise implementation on our CWAN Engineering Blog.

The Scale Today

The CWAN API Service workspace that this framework was extracted from now has:

• 93 workflows covering everything from sprint planning to code review to service onboarding
• 14 specialized AI agents (developer, architect, security engineer, QA, DevOps, product manager, scrum master, and domain-specific agents)
• 79 slash commands for common development operations
• Knowledge Graphs across multiple repositories, each with authority tiers, concept clusters, and search indexes
• Automated repo conversion that detects tech stack and generates tailored agents

The measurable impact was that new developer onboarding dropped from weeks to about a day. An engineer joins the team, opens the repository, and the AI agent walks them through the architecture, the current priorities, and the conventions. The knowledge is in the graph, not in someone’s head.

Three Agents That Show What “Specialized” Actually Means

When I say the framework produces specialized agents, I do not mean agents with different names that do the same thing. I mean agents with fundamentally different initialization sequences, different knowledge loaded, and different operational modes. Here are three from the CWAN API Service that illustrate the range.

The Sprint Planning Agent

This agent acts as an AI-powered scrum master. When activated, it does not ask “what sprint are you on?” It runs a sequence: it reads the project onboarding file, loads the Knowledge Graph, pulls the latest state of the API gateway to count how many services are onboarded (a key metric the team tracks against a quarterly scorecard), then syncs the current sprint from the project management system. It compares the live ticket statuses against the last known state and only updates files if something changed. If nothing changed, it skips the rewrite entirely and reports “no changes since last sync.”

The result is that when an engineer or a manager opens a session, the agent greets them with a context-aware summary: how many services are live, what the sprint backlog looks like, which tickets are blocked, and what the velocity trend is. The entire initialization takes a few seconds. Without this agent, assembling the same picture from the ticketing system, the deployment state, and the sprint board would take 15–20 minutes of manual navigation.

The reason this works is that the agent has explicit rules for each step: where to read credentials, what commands to run, how to detect whether the data is stale, and what format to use for the greeting. None of this is left to the AI’s judgment. The judgment is encoded in the workflow.

The Domain Intelligence Agent

This is the agent I use for cross-domain reasoning across the entire platform. The CWAN API Service spans multiple service domains: security infrastructure, client management, reporting, fund accounting, and more. Each domain has its own repository, its own Knowledge Graph, and its own specialized agents. But sometimes you need to answer a question that spans domains: “If we change the authentication pattern on the gateway, which downstream services are affected?” or “What is the current integration status between our API platform and the frontend application layer?”

The domain intelligence agent loads knowledge files from multiple domains at initialization: the architecture blueprint, the verified system numbers, the integration strategy documents, and the service-level Knowledge Graphs from each domain it needs to reason about. It can trace a question from the gateway configuration through the authentication layer to the backend service and back to the frontend, citing specific documents at each step.

Without this agent, answering cross-domain questions required scheduling a meeting with engineers from each team. With it, the answer comes back in seconds, with citations to the source documents so you can verify every claim.

The Gateway Infrastructure Agent

This is the most technically specialized of the three. It understands the API gateway infrastructure: Terraform configurations, OpenAPI specifications, Nginx routing rules, service onboarding procedures, and the Lambda-based authentication system. When activated, it reads the gateway repository’s onboarding file, loads the gateway-specific Knowledge Graph, and presents a set of demo questions showing what it can answer.

The value of this agent is in what it prevents. Before it existed, onboarding a new backend service to the API gateway required reading multiple Terraform files, understanding the routing conventions, and manually verifying that the OpenAPI spec matched the backend’s actual endpoints. An engineer unfamiliar with the gateway could spend days on their first onboarding. With the agent, the process is guided: it knows the steps, the conventions, the common mistakes, and it can generate the configuration files based on the backend service’s actual endpoints.

This is what I mean when I say the agentic repo pattern produces senior-level agents. Each of these agents has deep domain knowledge that would take a human weeks to accumulate. The knowledge is not in the AI’s training data. It is in the Knowledge Graph, the architecture documents, and the rules files that the framework creates and maintains.

What Comes Next

The direction I am working toward is making the agentic layer a standard part of repository scaffolding, the same way a README, a .gitignore, and a CI/CD config are standard today. When you create a new repository, it should come with a Knowledge Graph, a set of AI agents tailored to the tech stack, and the rules that make those agents reliable.

The gap between teams that use AI as a chat interface and teams that build structured knowledge environments for their AI agents is already significant. It will only grow. Rolling this out across CWAN is how we make our whole SDLC smarter.

References

• Building an AI-Powered Markdown Knowledge Base System for Your Engineering Team — CWAN Engineering Blog
• Agentic Repos: The Framework That Turns Any Repository into a Senior AI Development Environment — the public LinkedIn companion to this article

About the Author

large

Rany ElHousieny is an Engineering Leader at Clearwater Analytics with over 30 years of experience in software development, machine learning, and artificial intelligence. He has held leadership roles at Microsoft for two decades, where he led the NLP team at Microsoft Research and Azure AI, contributing to advancements in AI technologies. At Clearwater, Rany continues to leverage his extensive background to drive innovation in AI, helping teams solve complex challenges while maintaining a collaborative approach to leadership and problem-solving.