Is Your Codebase Ready for AI Agents?

An AI agent readiness assessment is a structured evaluation of whether your codebase, infrastructure, and team practices can support autonomous agents committing code, running scheduled tasks, and coordinating across workflows. Armada Works runs these assessments at the start of every engagement because deploying agents into a codebase that is not ready for them creates more problems than it solves.

Most founders who reach out to an agent consultancy have already tried "using more AI" in some form. They have used Claude or GPT for code generation, maybe run a few scripts. The question they are actually asking is not "can AI help?" but "can my system handle agents operating autonomously?" That is a different question, and it requires looking at the codebase itself, not the AI tooling.

Armada Works has been running an eight-agent fleet against its own codebase for over 140 days. Fifty blog posts, 14 content refreshes, and roughly 800 agent sessions later, the patterns that separate "agent-ready" from "not yet" are sharper than they were when this post was first published. This is the updated version: six prerequisites instead of five (security governance earned its own section after the Black Hat 2026 findings), a 12-question checklist with operational examples, and what to do with your score. For a deeper version of this material, download the free Agent Readiness Guide.

What "Agent-Ready" Actually Means

Agent-ready does not mean your codebase is perfect. It means your codebase has enough structure that an autonomous agent can commit work, get feedback from CI, read state from files, and operate without a human reviewing every action in real time.

The bar is lower than most founders expect. You do not need a microservices architecture, full test coverage, or a dedicated DevOps team. You need a few things to be true about how your repo is organized, how secrets are managed, how agent permissions are scoped, and how your team responds to changes they did not personally write.

Robert Cowherd, founder of Armada Works, describes the threshold this way: "If a new developer could clone the repo, run the project locally, and push a meaningful change through CI in their first afternoon, your codebase is probably ready for agents. If they could not do that, agents will hit the same walls."

The distinction matters because agents are, at the mechanical level, committers. They read files, write files, commit to branches, and push. Everything that blocks a junior developer from doing useful work on day one will also block an agent. For a full look at what that daily output actually looks like in practice, see what Claude Code agents actually do all day.

The Six Prerequisites

Six areas determine whether a codebase can support an agent fleet. Each one is necessary. None is sufficient on its own.

1. Repo structure and conventions

Agents navigate by file path and naming convention. A monorepo with clear directory boundaries (src/, docs/, scripts/, config/) is easier for agents to work in than a flat directory with 200 files at the root. Consistent naming patterns let agents find what they need without searching the entire tree every run.

In Armada's own fleet, every agent writes to a predictable location: state files to docs/agents/state/, blog drafts to docs/content/blog/, briefs to a date-stamped path. When an agent's eighth session fails to find a file it wrote in its seventh, the problem is almost always a naming inconsistency introduced between runs.

2. CI/CD pipeline

Agents need a feedback loop. When an agent commits code, it needs to know whether the build passed, whether tests passed, and whether linting flagged anything. A working CI pipeline (GitHub Actions, CircleCI, GitLab CI, or equivalent) provides that loop automatically. Without it, agents commit blind.

A common operational pattern: the Content agent drafts a blog post, commits, and pushes. If the build step catches a TypeScript error in the page template, the agent knows immediately. Without CI, that broken build sits in main until a human notices.

3. Secrets management

Agents that commit code must never commit secrets. This means your secrets live in environment variables or a secrets manager, not in hardcoded strings scattered through the codebase. .env files are gitignored. API keys are injected at runtime, not stored in config files that get pushed to the repo.

4. Security governance

This prerequisite did not exist the first time this post was published. Then Black Hat USA 2026 happened. Security researchers demonstrated remote code execution against Claude Code, Google's Gemini CLI, and OpenAI's Codex, all running default configurations. The Claude Code attack (CVE-2026-54316) worked through a prompt injection embedded in a GitHub issue. No authentication required. Three rounds of patches were needed.

The takeaway: prompt-level safety rules are not a governance layer. Technical controls are. Before deploying agents, your codebase needs:

• Permission hooks that block destructive commands (file deletion, force-push, database drops) before they execute, not after
• Credential scoping so each agent token grants only what that agent's function requires
• An approval workflow for any action that touches production data or external services

Armada configures these controls on every engagement before any agent touches the codebase. For the full breakdown of the Black Hat findings and what they mean for agent deployments, see agent governance after Black Hat 2026. For a step-by-step permissions audit you can run yourself, see how to audit an AI coding agent's permissions.

5. Monitoring and observability

When agents run scheduled tasks (daily briefs, weekly reports, content drafts), you need a way to see what they did. This can be as simple as structured log files or a dashboard that reads from an API endpoint. The point is that agent output is visible without reading every commit diff.

In Armada's fleet, every agent posts a daily brief to a central dashboard, and the CMO synthesizer agent reads all of them each morning. Without that observability layer, the fleet is eight autonomous processes with no shared view. The synthesizer pattern only works if there is something to synthesize.

6. Team buy-in and review discipline

This is the prerequisite most founders underestimate. An agent fleet produces commits, pull requests, and state file updates. Someone on the team needs to read diffs, review agent output, and provide course corrections. If the team treats agent commits as noise, the fleet degrades. If the team treats them as contributions worth reading, the fleet improves.

After 140 days of operation, the clearest signal of fleet health is whether someone reads the daily brief. Agents that get corrective feedback from a human improve. Agents that run unsupervised for weeks drift.

A 12-Question Self-Assessment Checklist

Score yourself one point for each "yes." Be honest. A generous self-assessment just delays the real evaluation.

1. Can a new contributor clone the repo and run the project locally within 30 minutes? Agents need the same onboarding path. If your README assumes tribal knowledge, agents will fail at the same steps.

2. Is your directory structure organized by function (e.g., src/, docs/, tests/, scripts/) rather than flat? Agents navigate by convention. A flat repo with 200 root-level files forces expensive tree searches on every run.

3. Does every push to main trigger a CI pipeline that runs at least a build step and a lint step? This is the single highest-leverage item. No CI means agents commit blind and errors accumulate.

4. Are all secrets stored in environment variables or a secrets manager, with no hardcoded credentials in the repo? Agents that commit code will push anything in the working tree. Hardcoded secrets become public secrets.

5. Is .env in your .gitignore? This is question 4's mechanical check. If .env is not gitignored, an agent will eventually commit it.

6. Do you have at least one automated test suite that runs in CI (unit tests, integration tests, or end-to-end tests)? Even a minimal test suite provides a feedback signal. Full coverage is aspirational, but any test is better than none.

7. Does your team review pull requests before merging, even small ones? Agent output is reviewable. Teams without review habits treat all agent commits as auto-merged, which removes the human correction loop.

8. Can you describe your deployment process in three steps or fewer? Complex deployment sequences with manual steps create agent failure points. Every manual gate (SSH into a server, click a dashboard button) is a place where agents stall.

9. Do you have a way to monitor deployed services (logs, uptime checks, error tracking, or a dashboard)? Agents that run on cron schedules need an observability layer. Without it, a broken agent runs broken for days before anyone notices.

10. Is your team willing to read and respond to agent-generated commits as part of their regular workflow? This is the culture question. Technical readiness without team buy-in produces a fleet nobody trusts.

11. Are agent permissions scoped per function, so a content agent cannot modify database schemas and an SEO agent cannot push to production? After the Black Hat 2026 findings, the default answer for any production codebase should be yes. See agent security guardrails for the implementation pattern.

12. Do you have hooks or pre-commit checks that block destructive operations (force-push, rm -rf, database drops) regardless of who or what triggers them? Permission hooks are the enforcement layer that prompt instructions cannot replace.

Scoring

Score	Readiness Level	Next Step
11-12	Ready	You can deploy an agent fleet now. Start with a Pilot.
9-10	Nearly ready	One or two gaps to close first. Most can be fixed in a week.
6-8	Needs prep work	Foundational issues that should be addressed before agents arrive.
Below 6	Not yet ready	The codebase needs structural investment before agents add value.

What to Do If You Score Below 8

A score below 8 does not mean agents are wrong for your team. It means the codebase needs some preparation first. The good news is that the prep work you do to become agent-ready also makes your codebase better for human developers.

Here is where to focus based on common gaps:

• No CI pipeline (question 3): This is the single highest-leverage fix. Set up a basic GitHub Actions workflow that runs your build step on every push. Even a two-line workflow file (npm run build or python -m pytest) gives agents the feedback loop they need.

• Hardcoded secrets (questions 4-5): Move credentials to .env files, add .env to .gitignore, and update your deployment to inject them from a secrets manager or environment config. This is a security improvement regardless of agents.

• No security governance (questions 11-12): After Black Hat 2026, this is no longer optional. At minimum, configure permission hooks that block destructive commands and scope each agent's credentials to its specific function. The permissions audit walkthrough covers this in 30 minutes.

• No review culture (questions 7, 10): Start by requiring reviews on any PR that touches production code. Agents generate reviewable output. If the team is not already reviewing human PRs, agent PRs will be ignored.

• Flat or disorganized repo (question 2): Create clear top-level directories. Move configuration files into a config/ directory. Move scripts into scripts/. The restructuring takes a day and pays off immediately.

For a deeper walkthrough of what to expect in the first weeks of an engagement, see how an agent engagement actually works.

What 140 Days of Fleet Operation Taught Us About Readiness

Armada's own fleet has been running since April 2026. Eight agents, three runs per week each, roughly 800 sessions total. Some of the readiness lessons only showed up after months of continuous operation.

State files are the real coordination layer. Every Armada agent reads and writes a state file (docs/agents/state/<agent>-state.md). These files carry context between sessions: what was shipped, what is in progress, what is blocked. Without them, each agent session starts from zero. A codebase that wants to support agents needs a place for agents to persist state across runs, whether that is a docs/ directory, a database table, or a shared config file.

The synthesizer agent is non-negotiable. Armada's CMO agent reads every other agent's daily brief and writes a single synthesis. Without it, the founder reads eight separate outputs and loses context across them. Any fleet of three or more agents needs a synthesizer. This is a readiness question because the synthesizer pattern only works if your repo has a convention for briefs, state files, and a shared directory both agents can read.

Date-bump freshness refreshes do not work. Over 14 content refreshes, the ones that recovered search position were all substantive: new sections, updated competitive data, expanded cross-links. The ones that just bumped the date in frontmatter showed 0/8 success rate. Your codebase needs a content review workflow, not an automated date stamp.

Agent drift is proportional to human attention. The agents that received corrective feedback from a human within their first 10 sessions stabilized fastest. The agents that ran unsupervised developed quirks that compounded. Readiness is not just a codebase question. It is a team discipline question.

For founders evaluating whether to bring in an agent consultancy to help with this, the buyer evaluation guide covers what to look for and what to avoid.

How Armada Works Evaluates Readiness in the First Week

When a founder books a discovery call, part of that conversation is a quick pass over these same questions. Not as a gatekeeping exercise. As a scoping exercise.

During the Pilot engagement ($2,500 to $4,000, one week), the first thing Armada deploys is a single agent scoped to one function: content, SEO, or outbound, depending on the founder's bottleneck. That first agent serves as the real readiness test. If it can clone the repo, commit a draft, and push through CI on day one, the codebase is ready. If it cannot, the first two days of the Pilot are spent fixing the gaps.

Common issues found during Pilot week:

• Missing .gitignore entries that would expose secrets when agents push
• No package.json scripts (or equivalent) for common tasks, forcing agents to run long compound commands that are hard to audit
• CI configured but broken, with tests that have been failing for weeks and nobody noticed
• Deployment requires manual steps that agents cannot perform (SSH into a server, click a button in a dashboard)
• No permission hooks, leaving every agent with the same access as a root-level human operator

Each of these is fixable within the Pilot timeline. The Pilot fee credits 100% toward a longer engagement if the founder continues within 30 days, so the readiness work is not wasted investment.

For a detailed look at what agents actually need from a permissions and security standpoint, see how to audit an AI coding agent's permissions and agent security guardrails.

Frequently Asked Questions

Do I need full test coverage before deploying agents?

No. Agents benefit from any test suite that runs in CI, even a minimal one. The purpose is a feedback loop: the agent commits, CI reports pass or fail, and the agent adjusts. Full coverage is a goal for any codebase, but agents can start adding value with even basic build-and-lint checks.

Can agents work in a monorepo with multiple services?

Yes. Agents navigate by file path and directory convention. A well-organized monorepo with clear boundaries between services is often easier for agents than a sprawl of separate repositories, because the agent can read shared configuration and cross-reference between services in a single workspace.

What if my team has never reviewed agent-generated code before?

The adjustment period is shorter than most founders expect. Agent commits look like human commits: diffs, commit messages, and file changes. The difference is volume and cadence. Armada's fleet produces daily briefs and state files that summarize what each agent did, so the review process starts with reading a one-page brief rather than scanning every diff. For more on how this coordination works, see how eight AI agents coordinate without a Slack channel.

Is there a minimum tech stack required?

No. Armada has deployed agents into Next.js, Rails, Django, and Go codebases. The readiness checklist above is stack-agnostic. What matters is the repo's organizational hygiene (conventions, CI, secrets management, security governance), not the language or framework.

How long does it take to go from "not ready" to "ready"?

For a codebase scoring 6-8 on the checklist, typically one to two weeks of focused prep. The highest-leverage fixes (adding CI, organizing secrets, configuring permission hooks, creating a basic directory structure) are each one-day tasks. For a codebase scoring below 6, expect two to four weeks, with the bulk of the time spent on CI setup, security governance, and establishing a review culture.

What changed after Black Hat 2026?

Security governance moved from "nice to have" to required. Before Black Hat, most agent deployments ran with default permissions. The CVE-2026-54316 demonstration proved that prompt-level safety checks are insufficient when agents process untrusted input (which includes any public-facing repo with open issues). Permission hooks, credential scoping, and approval workflows are now baseline requirements, not advanced hardening. See agent governance after Black Hat 2026 for the full analysis.

Can I do the readiness assessment myself, or do I need a consultancy?

You can score yourself using the 12-question checklist above. If you score 9 or higher, you are likely ready to proceed. If you score below 9, a discovery call can help identify which gaps matter most for your specific situation. Armada also publishes a free Agent Readiness Guide that covers the same ground in more detail and includes a printable checklist.

---

If you want a concrete assessment of where your codebase stands, book a 30-minute discovery call. No commitment, no follow-up sequence. We will tell you whether agents are the right fit and what prep work, if any, your team should do first.