Let's Build Prompt-First Repositories for Your Applications

Production applications were never just code.

Even a modest service carries layers humans must maintain: build pipelines, environments, tests, docs, security controls, observability, dependency hygiene, and the social process of review and release. AI coding agents do not remove those layers. They change where the work lives and who — or what — does the repetitive parts.

A prompt-first repository treats agent instructions, skills, tool connections, and execution loops as first-class artifacts alongside application code. “Prompt-first” does not mean prompt-only, and it does not put natural-language instructions above architecture. It means the repository carries enough machine-readable operating context for an agent to work without reconstructing the team’s process from chat history.

The article’s thesis is an editorial hypothesis, not a benchmark result: hardening those four pieces can reduce avoidable rework and shorten the path to a reviewable change, but only when deterministic controls — tests, permissions, CI, and human escalation — remain authoritative.

This article compares the traditional maintenance stack with recent AI development advances, maps each advance to a specific bottleneck, and ends with open questions about what comes next.

TL;DR

• Modern production apps require many layers beyond source code: CI/CD, environments, observability, security, docs, and review rituals.
• AI development does not eliminate those layers. It shifts effort toward specification, repository context, tool access, and verification loops.
• A prompt-first repository stacks four primitives:
  • AGENTS.md — cross-tool repo instructions (build, test, conventions, guardrails)
  • Skills — reusable procedural knowledge in SKILL.md folders
  • MCP — standardized connections to external systems (issue trackers, databases, CI, docs)
  • Loops — scheduled or triggered agent cycles with durable state and exit conditions
• Each primitive targets a different bottleneck: onboarding, repeated workflows, integration friction, and turn-by-turn prompting fatigue.
• Instructions guide behavior; tests, permissions, CI, branch protection, and review enforce boundaries.
• The open frontier is governance: versioning skills, auditing MCP access, cross-repo workspaces, and deciding when a prompt-first repo is worth the overhead.

What You Will Learn Here

• The maintenance layers a production application actually needs, stated as a systems map rather than a tool list.
• How recent AI development patterns map one-to-one onto classic bottlenecks.
• A reference layout for a hardened prompt-first repository.
• Where skills, MCP, and loops fit relative to specs, worktrees, and subagents.
• How to migrate an existing repository one layer at a time.
• Which controls must be enforced outside the prompt, and which metrics show whether the approach is helping.
• Honest limits and open questions for the next phase of application development.

Audience: engineers and architects who already use coding agents and want a repository design that scales beyond ad hoc prompting.

The Maintenance Stack We Already Had

Before agents entered the IDE, a “modern production application” was already a bundle of layers. The application code was the visible center, but teams paid ongoing tax on everything around it.

                         ┌─────────────────────────────┐
                         │   Product & requirements      │
                         └──────────────┬──────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │   Application code + tests   │
                         └──────────────┬──────────────┘
                                        │
        ┌───────────────────────────────┼───────────────────────────────┐
        │                               │                               │
┌───────▼────────┐            ┌─────────▼─────────┐           ┌────────▼────────┐
│ Build & deploy │            │ Environments &     │           │ Security &       │
│ CI/CD          │            │ configuration      │           │ compliance       │
└───────┬────────┘            └─────────┬─────────┘           └────────┬────────┘
        │                               │                               │
        └───────────────────────────────┼───────────────────────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │ Observability & operations   │
                         └──────────────┬──────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │ Docs, onboarding, decisions  │
                         └──────────────┬──────────────┘
                                        │
                         ┌──────────────▼──────────────┐
                         │ Review, release, ownership   │
                         └─────────────────────────────┘

Each layer exists because something broke without it:

That ladder is familiar. If you want the full architectural version — when to add CQRS, events, externalized auth, and AI as a product layer — see The Pieces of Modern, Effective Software Design.

The important point for this article: agents inherit the same stack. If your repo lacks tests, CI, or clear conventions, an agent cannot reliably infer the missing controls. It may produce plausible output quickly, but plausibility is not production readiness.

How AI Development Attacks the Bottlenecks

AI-assisted development is often described as “faster coding.” That framing is incomplete. The durable gains should be evaluated by whether each advance reduces a specific friction point in the old workflow.

Here is the bottleneck map I find most useful as an editorial model on July 17, 2026:

Two related articles go deeper on adjacent slices:

• Blueprint Over Bytes — why specifications matter more, not less, when code is cheap to generate.
• Building a Senior-Engineer Agent — loop engineering, subagents, and the confidence ladder for auto-PRs.

The prompt-first repository is the single-application packaging layer that makes those advances repeatable inside Git. It is narrower than an agentic workspace, which coordinates several repositories, and different from a daily workflow audit, which helps decide where repeated knowledge belongs.

What “Prompt-First” Means

“Prompt-first” does not mean “no code.” It means the repository is designed so an agent can answer these questions without guessing:

1. What is this project?
2. How do I build, test, and lint it?
3. What must I never do?
4. Which workflows are standardized?
5. Which external systems can I call?
6. When is a task actually done?

Humans needed the same answers. Teams often scatter them across READMEs, wikis, chat, and individual experience. Agents make the cost of missing answers visible in bad diffs, broken builds, and repeated corrections.

Layer 1: AGENTS.md — repo instructions for machines

AGENTS.md is an open Markdown convention stewarded by the Agentic AI Foundation under the Linux Foundation. It complements README.md: README orients humans; AGENTS.md orients coding agents.

As documented on July 17, 2026, a growing set of tools reads AGENTS.md directly — including OpenAI Codex, GitHub Copilot, Cursor, Google Jules, and others listed on agents.md. The format is intentionally plain: no required schema, just Markdown sections agents parse as instructions.

Recommended sections:

• project overview
• build and test commands
• code style and conventions
• security gotchas
• commit and PR rules

For monorepos, nested AGENTS.md files let subpackages carry local rules. The nearest file to the edited path wins.

Tooling caveat (source-backed, not opinion): Claude Code reads CLAUDE.md, not AGENTS.md. The documented compatibility pattern is a one-line CLAUDE.md that imports shared rules: @AGENTS.md. Cursor supports AGENTS.md and adds scoped overrides in .cursor/rules/*.mdc. One source of truth, multiple entrypoints — not three diverging copies.

Layer 2: Skills — procedural knowledge on demand

A skill is a directory with a required SKILL.md file. Under the cross-tool Agent Skills specification, YAML frontmatter requires name and description; the body holds instructions and can point to scripts, references, and assets. Anthropic’s engineering write-up on Agent Skills describes progressive disclosure: agents preload metadata, then load full instructions only when relevant.

Implementations vary at the edges. Cursor requires both fields, while current Claude Code documentation is more permissive for Claude-specific skills. If portability matters, follow the stricter open specification.

Skills attack a different bottleneck than AGENTS.md:

• AGENTS.md answers “how does this repo work?”
• Skills answer “how do we run this workflow across repos?”

Examples: research-article drafting, source audit, worktree PR packaging, security review, migration playbooks.

For company-scale skill governance, see How to Build a Company Skill Registry for AI Agents.

Layer 3: MCP — integrations without bespoke glue

The Model Context Protocol standardizes how agents connect to tools and data over JSON-RPC. Instead of every host inventing its own Jira/Slack/Postgres adapter, MCP servers expose tools, resources, and (where supported) interactive UI.

Important 2026 milestones:

• January 26, 2026 — MCP Apps shipped as the first official extension, letting tools return sandboxed interactive UI inside agent hosts.
• July 28, 2026 (scheduled final release) — the 2026-07-28 MCP specification RC moves toward a stateless core, formal deprecation policy, OAuth-aligned authorization, and graduated extensions like Tasks.

MCP targets integration friction, not code generation quality. With an appropriately configured host, it can turn “here is a patch” into “PR opened, ticket updated, CI status checked.”

MCP configuration is host-specific even though the protocol is shared. Claude Code supports a root-level .mcp.json for project-scoped servers; Cursor uses .cursor/mcp.json. Treat server access like API credentials: least privilege, auditable actions, and explicit approval for production systems.

Layer 4: Loops — from chatting to operating

Loop engineering is the shift from prompting an agent once to designing a bounded cycle that runs until a verifiable exit condition, budget limit, or escalation condition is met. Triggers can be schedules, labels, failing CI, or new issues. Durable state lives outside the model context — task boards, status files, Beads graphs, or Spec Kit artifacts.

Cursor’s agent capabilities documented as of July 17, 2026 make several loop primitives practical in mainstream tooling:

• Worktrees for isolated checkouts per agent task
• Subagents and /multitask for parallel work
• Cloud subagents for long-running or CI-fix loops on separate VMs

A minimal loop anatomy:

trigger -> load repo context (AGENTS.md + skills)
       -> plan in isolated worktree
       -> act (edit code, call MCP tools)
       -> verify (tests, lint, CI)
       -> exit or escalate
       -> open PR / update ticket

Explicit exit conditions improve reliability only when enforceable controls back them. If CI must be green before merge, document that expectation in AGENTS.md and enforce it with branch protection.

Reference Layout: A Hardened Prompt-First Repository

Below is a practical starter layout. Adapt depth to team size; a solo project needs less ceremony than a platform team.

repo/
├── AGENTS.md                 # cross-tool instructions (build, test, guardrails)
├── CLAUDE.md                 # optional: @AGENTS.md import for Claude Code
├── README.md                 # human onboarding
├── .cursor/
│   ├── rules/                # scoped Cursor overrides (*.mdc)
│   └── skills/               # repo-local skills (or .claude/skills/)
├── .claude/
│   ├── skills/               # Claude Code project skills
│   └── commands/             # slash commands for repeatable workflows
├── .github/
│   └── workflows/            # CI — the agent's hard verifier
├── .mcp.json                 # Claude Code project MCP config (optional)
├── .cursor/mcp.json          # Cursor project MCP config (optional)
├── specs/ or openspec/       # optional: approved change artifacts
└── src/ ...                  # application code (still the product)

Do not commit both MCP files by default. Choose the configuration surfaces your team actually uses, avoid duplicating server definitions, and never place secrets directly in either file.

Portability matrix

The content model is converging faster than the file locations:

AGENTS.md starter (trimmed)

# MyApp

## Commands
- Install: `npm ci`
- Dev: `npm run dev`
- Build: `npm run build`
- Lint: `npm run lint`
- Test: `npm test`

## Conventions
- TypeScript strict mode; match existing file layout.
- Keep diffs minimal; do not refactor unrelated code.
- Commit with signoff: `git commit --signoff`

## Behavioral boundaries
- Do not commit secrets or edit production env files.
- Do not disable tests to make CI pass.
- Run `npm run build` before opening a PR for user-facing changes.

## PR rules
- One logical change per PR.
- Include validation steps in the PR description.

Skill stub

---
name: release-patch
description: Prepare a patch release. Use when the user asks to cut a release or bump patch version.
---

# Release patch workflow

1. Confirm main is green in CI.
2. Update CHANGELOG and version fields.
3. Run full test suite.
4. Open PR with release notes; do not push tags until approved.

Decision table: where to put knowledge

Hardening: Guidance Is Not Enforcement

This is the most important boundary in a prompt-first repository:

AGENTS.md + skills     -> influence agent behavior
permissions + CI      -> constrain what can happen
branch protection     -> decides what can merge
human escalation      -> handles ambiguity and high-impact actions

Instructions are context, not a security boundary. Claude Code’s documentation says this directly: CLAUDE.md shapes behavior, while managed settings enforce policy. The same principle applies across hosts.

Test the agent-facing artifacts

Treat instructions and skills like code even when they are Markdown:

1. Validate skill frontmatter against the Agent Skills specification.
2. Keep a small eval set with prompts that should and should not trigger each important skill.
3. Run documented build and test commands in CI so stale instructions fail visibly.
4. Review MCP configuration changes with the same care as application permission changes.
5. Record an owner and last-reviewed date for high-impact instructions, skills, and tools.

Define ownership before scale

The exact ownership model is organizational. The requirement is not: every artifact needs a different committee. The requirement is: every privileged artifact needs somebody accountable for changes and rollback.

Failure walkthrough: the safe path matters

Consider a release loop that receives conflicting instructions and then fails validation:

Issue requests patch release
  -> AGENTS.md says "release only from main"
  -> release skill says "work on a release branch"
  -> agent detects conflict and escalates instead of guessing
  -> human confirms branch policy
  -> agent works in isolated worktree
  -> restricted GitHub MCP can read CI and open a PR, but cannot merge
  -> build fails twice
  -> loop reaches retry limit and records logs + blocker
  -> human receives a reviewable PR, not a hidden production action

The successful outcome is not always a merged change. Sometimes it is a bounded failure with enough evidence for a human to continue safely.

Bottleneck by Bottleneck: Before and After

Onboarding

Before: New contributors read README, ask in Slack, copy commands from an old PR.

After: AGENTS.md tells compatible agents which commands to attempt. Nested files handle monorepo packages, while CI proves whether the commands actually pass.

Limit: AGENTS.md rots like any doc. Assign an owner; review it in PRs when build steps change.

Repeated workflows

Before: Senior engineers re-type the same release, migration, or audit checklist.

After: Skills encode the checklist once. Descriptions act as routing metadata.

Limit: Skills can embed unsafe scripts or stale instructions. Review them like libraries. See the skill registry article for governance patterns.

External integrations

Before: Agents suggest shell commands that curl production APIs from a laptop.

After: MCP hosts can expose approved tools through host-specific authentication, consent, and logging controls.

Limit: MCP itself does not enforce those controls. It expands attack surface, so the specification’s security guidance and each host’s permission model are necessary reading.

Scheduling and parallelism

Before: One developer, one branch, one agent chat, sequential tasks.

After: Worktrees isolate tasks; subagents parallelize exploration; cloud agents babysit CI.

Limit: Parallelism without ownership rules recreates merge conflicts at machine speed. Keep the rule from Spec Kit parallel delivery: one task stream, one branch, one worktree, one owner at a time.

Quality and trust

Before: Review catches what tests miss — if review happens.

After: AGENTS.md tells agents which checks to run; CI enforces merge gates; optional evals score non-deterministic outputs.

Limit: Agents can game weak verifiers. For high-risk changes, separate the maker that creates the change from an independent checker that reviews it. Start with narrow auto-PR scopes (dependency bumps, formatting) before architecture edits.

Migration Path: Earn Each Layer

Do not rebuild an existing repository around agents in one pull request. Add the next layer only after the previous one solves a visible problem:

Stage 0: code + CI baseline
  -> Stage 1: AGENTS.md for commands, boundaries, and ownership
  -> Stage 2: skills for workflows repeated often enough to standardize
  -> Stage 3: MCP for governed external data and actions
  -> Stage 4: bounded loops for work with reliable verification

A 30-minute starting pass

1. Create AGENTS.md with the five commands contributors actually use.
2. Add three behavioral boundaries: scope, secrets, and required validation.
3. Link to the architecture decision records (ADRs) or runbooks agents commonly miss.
4. Extract one repeated, low-risk workflow into a skill.
5. Keep production MCP access disabled.
6. Confirm CI independently runs the build and tests named in AGENTS.md.

That is enough for the first iteration. Add external tools and unattended loops only after ordinary agent sessions are predictable.

Measure Whether It Helps

The article’s thesis should be tested inside each team rather than accepted on intuition. Capture a baseline before adding automation, then track:

Generated lines of code and number of agent sessions are activity metrics, not success metrics. A prompt-first repository is helping only when it reduces rework or lead time without increasing escaped defects and operational risk.

Anti-Patterns

• The instruction landfill: one giant AGENTS.md consumes context and mixes stable rules with rare procedures.
• Three sources of truth: AGENTS.md, CLAUDE.md, and Cursor rules repeat the same text and drift independently.
• Prompt-only security: instructions say “ask first,” but credentials still permit irreversible production actions.
• Unbounded loops: no retry cap, cost budget, durable state, or escalation path.
• Self-certified high-risk changes: the same agent implements, reviews, and declares success.
• Green-build theater: compilation passes, but migrations, accessibility, security, and rollback are untested.
• Skill supply-chain blindness: copied skills can contain stale guidance, executable scripts, or hidden network assumptions.

When Not to Use This Pattern

Do not add the full stack to every repository. README plus CI may be enough when the code is a disposable experiment, agent use is rare, no workflow repeats, or external actions would add more security overhead than value.

Use the following as an editorial heuristic, not a universal threshold:

Do people or agents repeatedly lose the same repo context?
  no  -> improve README and CI first
  yes -> add AGENTS.md
        Does a procedure repeat and have a stable success condition?
          yes -> add a skill
          Does the workflow require external data or action?
            yes -> add least-privilege MCP access
            Can deterministic checks bound unattended execution?
              yes -> add a loop with limits and escalation
              no  -> keep a human in the execution path

What Is Next: Open Questions

The primitives are available as of July 17, 2026. The operating model is not settled. These are the questions I would put in a team RFC before scaling prompt-first repos across an organization.

1. Who owns prompt-first artifacts?

Application teams own code. Platform teams often own CI. Who owns AGENTS.md, skills, and MCP allowlists? Without explicit ownership, these artifacts can drift like any other documentation or configuration.

2. How do we version and test skills?

We version packages and pin dependencies. Skills can contain executable scripts and operational instructions, yet many repositories still store them as ordinary Markdown. Do we need skill lockfiles, semver, provenance, and CI validation for SKILL.md frontmatter — the way this repo validates article frontmatter at build time?

3. How portable should the repository be?

AGENTS.md, Agent Skills, and MCP provide shared content or protocol layers, but host-specific rule and configuration files remain. Should a team optimize for the widest agent compatibility, or deliberately use one host’s stronger policy and automation features? Portability has value, but lowest-common-denominator configuration can hide capabilities a single-platform team actually needs.

4. Cross-repo and polyrepo agents

Cursor’s April 24, 2026 changelog introduced multi-root workspaces in the Agents Window so one session can span frontend, backend, and shared libraries. That pushes prompt-first design up from a single repo to a workspace manifest. As of July 17, 2026, I did not find a broadly adopted open standard for that layer.

5. Security and compliance at scale

The 2026-07-28 MCP release candidate aligns authorization more closely with OAuth and OpenID Connect deployments, but teams still need server allowlists, data-classification rules, and audit logs for tool calls. Prompt-first repos can make agents productive; they can also make exfiltration paths more convenient if MCP is misconfigured.

6. The human role after prompt-first adoption

If loops handle routine implementation, human work concentrates on:

• problem selection and product judgment
• architecture and failure-mode design
• verifier design (what “done” means)
• reviewing diffs and organizational risk

That rhymes with Blueprint Over Bytes. One plausible emerging specialty is the repository operator: someone who curates AGENTS.md, skills, MCP policies, and loop exit conditions the way SREs curate runbooks. That is editorial inference, not an established role.

7. Does the repository become an executable operating contract?

Source repositories historically stored code and build configuration. Prompt-first repositories also store intent, procedures, tool boundaries, verifiers, and automation. The open question is whether those artifacts converge into an executable operating contract — or remain a loose collection of host-specific files that teams must continuously reconcile.

Conclusion

Prompt-first repositories are not a replacement for software architecture, CI, or engineering judgment. They are a way to make the operating context around an application visible and reusable by both people and agents.

Start with one source of instructions and one enforced CI baseline. Add a skill when a procedure repeats, MCP when an external action has a clear permission boundary, and a loop only when deterministic checks can bound execution. Measure rework, review load, escaped defects, and lead time before adding more autonomy.

The future advantage is unlikely to come from prompts alone. It will come from repositories that make intent legible, access constrained, verification automatic, and failure safe.

Sources

Primary and official sources consulted for this article:

• AGENTS.md — open format overview, nested files, ecosystem support (Agentic AI Foundation / Linux Foundation)
• Agent Skills specification — portable SKILL.md structure, required metadata, and progressive disclosure
• Anthropic — Equipping agents for the real world with Agent Skills — SKILL.md structure and progressive disclosure
• Claude Code Skills documentation — frontmatter, invocation, project vs personal skills
• Claude Code memory documentation — CLAUDE.md, imports, AGENTS.md compatibility, and guidance-versus-enforcement boundary
• Claude Code MCP documentation — project-scoped .mcp.json, approval, and configuration scopes
• Model Context Protocol specification (2025-11-25) — protocol primitives and security guidance
• MCP Blog — MCP Apps announcement (January 26, 2026) — interactive UI extension
• MCP Blog — 2026-07-28 specification release candidate (May 21, 2026) — stateless core, deprecation policy, OAuth alignment
• Cursor Docs — Rules — AGENTS.md support and .cursor/rules/*.mdc
• Cursor Docs — Agent Skills — .cursor/skills, required metadata, and skill discovery
• Cursor Docs — MCP — .cursor/mcp.json, authentication, and configuration scopes
• Cursor Docs — Worktrees — isolated checkouts, .cursor/worktrees.json
• Cursor Docs — Subagents — parallel agents, cloud subagents, MCP inheritance rules
• Cursor Changelog — Multitask, Worktrees, Multi-root Workspaces (April 24, 2026)
• Cursor Changelog — Cloud subagents in Agents Window

Related reading on this devlog:

• The Pieces of Modern, Effective Software Design
• Blueprint Over Bytes
• Building a Senior-Engineer Agent
• From Spec to Parallel Delivery with Spec Kit, Cursor, and Beads
• How to Build a Company Skill Registry for AI Agents
• Correct Planning for Engineering Development: From Prompts to Spec Kit
• Agentic Workspaces: Submodules, Skills, Knowledge, and Spec-Driven Delivery
• Audit Your Daily AI Agent Workflow