That duplication is the problem, and it shows up in two layers. Developers and others using AI already solved the first: they agreed on one neutral instruction file that every tool reads. The second layer, the folder, is still broken, and it holds the agents, skills, and memory that do the real work. This article makes the case for .contributing/, one shared folder any agent can read, and covers why the folder is the fix, why its name fits, and how you adopt it today.

The file is solved. The folder is not.

Two years ago the same mess lived one level down, in the files. Every tool wanted its own instructions file: CLAUDE.md, .cursorrules, .windsurfrules, GEMINI.md, copilot-instructions.md. You wrote the same project description five times and kept five copies in sync.

Then the ecosystem converged. AGENTS.md emerged as a neutral "README for agents." OpenAI shipped it first, Google, Cursor, Factory, Sourcegraph, and Amp backed it, and the Linux Foundation's Agentic AI Foundation now stewards it. By mid-2026, more than two dozen tools read it across tens of thousands of repositories. Even Claude Code, which keeps its richer CLAUDE.md, learned to read it. The lesson lands hard: developers converge fast when someone offers one good neutral format, and the providers who offered it competed on the quality of their agents rather than the stickiness of a filename. Moving first earned them the credit, not a loss of ground.

But AGENTS.md covers exactly one thing, a single file of prose. Modern agents load far more than prose:

• Agents: specialized personas for review, testing, and migration

• Skills: reusable, self-contained capabilities

• Commands: project-specific workflows

• Hooks: scripts that run before or after actions

• Memory: durable notes that survive across sessions

• Settings: permissions, tool access, and model defaults

Here is the catch: every provider expects that same list. Claude Code, Cursor, Codex, and OpenCode all reach for agents, skills, and memory, because agentic work needs the same ingredients no matter whose agent runs them. The content is provider-agnostic. Only the folder name is provider-specific. So we copy identical material into five provider-branded folders and sync it by hand. We fixed the file and rebuilt the same fragmentation one level up, with more to duplicate this time. And the pressure only builds. As capable models increasingly run locally, every new harness that wraps one adds another folder, even though it needs the same agents, skills, and memory as the rest.

One folder, and a name that fits

Standardize the folder the way we standardized the file. Put the agents, skills, memory, commands, hooks, and settings in one neutral directory:

.contributing/
├── agents/        # personas: review, test, migrate
├── skills/        # reusable capabilities
├── commands/      # project workflows
├── hooks/         # pre/post action scripts
├── memory/        # durable context
└── settings.json  # permissions, defaults, guardrails

AGENTS.md stays at the root as the front door. .contributing/ holds the machinery behind it. Any conformant tool reads .contributing/ first. Vendors keep their own folders for the genuinely proprietary parts, but the shared 90%, the agents and skills that describe your project rather than your vendor, lives in one place you maintain once. One place is also one place to secure, review, and keep in policy, and one fewer way for any single vendor to capture your project.

Now the name. It answers a question open source has asked for fifteen years: how do I help with this project? CONTRIBUTING.md has always held that answer for humans. It carries the build steps, the conventions, the test commands, and the etiquette.

Coding agents are contributors too. They arrive every session with no memory, needing the exact orientation a human newcomer needs. So the folder that configures them is not vendor exhaust. It is contribution guidance for a new kind of contributor. .contributing/ reads as part of the project, the way .github/ and CONTRIBUTING.md do, right down to the first-class treatment platforms already give those files. It belongs to the codebase, not to a company, and that feeling drives adoption.

That legibility matters more as agents move past code. Many people steering agentic work are not developers; they draft documents, build decks, and run analyses. .contributing/ tells them what it is at a glance, while .claude/ asks them to learn tool internals they would otherwise never touch. Developers shrug at a dotfolder and a symlink. For everyone else, a plain name is the on-ramp.

Adopt it today

Standards win by making the easy path the correct one.

Start now with symlinks. Point the vendor folders at the shared one:

ln -s .contributing .claude
ln -s .contributing .cursor

Developers already do this by hand, and tools like ruler exist to fan one source of truth out to many vendor folders. Nothing breaks and nobody has to agree: your vendor folders keep working, the change reverses in one command, and you get the full payoff alone, today. That people already improvise it proves the standard is missing.

Next, tools add .contributing/ to their discovery chain, the same cheap move that let them read AGENTS.md as a fallback. Vendor folder overrides shared folder, and the nearest directory wins, exactly as AGENTS.md resolution already works. The incentive runs both ways: a CLI or IDE that reads the shared folder works in any repo already configured for a rival, so trying it costs the user nothing, and a model provider makes the same open bet that paid off with the instruction file.

Then stewardship. The Agentic AI Foundation already governs AGENTS.md, MCP, and Goose. A folder that complements AGENTS.md sits squarely in its scope. Nobody has to found a new body. They have to finish a job that body already started.

Three objections come up, and none survives contact:

• "This is just xkcd 927, one more competing standard." That holds only if a folder standard already existed. None does. This fills a vacuum instead of re-solving a solved problem, which is the one case that justifies a new standard.

• "Tools need proprietary behavior." They do, and they keep their vendor folders for it. The point stands: your project's agents and skills are not proprietary, so they should not live in a vendor's folder.

• ".contributing/ will get confused with CONTRIBUTING.md." Keep them complementary. CONTRIBUTING.md stays human-first prose, and .contributing/ holds machine-loadable capabilities. If the overlap ever bites, the same proposal works as .agents/. But "contributing" carries meaning the ecosystem already respects.

What to do next

The ecosystem already standardized the instruction file and proved that developers converge on one neutral format. The folder is that same problem one layer up, and .contributing/ is the neutral folder that keeps the agents, skills, and memory you build portable and yours, ready for whatever agent you run next. Adoption costs a symlink today and a discovery-chain entry tomorrow.

So do three things. Create a .contributing/ folder in your next repository. Symlink your vendor folders to it today. And if you maintain a coding agent, add .contributing/ to your discovery chain and take the proposal to the Agentic AI Foundation.

Write your project's guidance once. Put it where contributors of every kind already look. Call it .contributing/.

One more thread

Throughout this piece I kept AGENTS.md and CONTRIBUTING.md in separate lanes, one for agents and one for humans. But the naming argument keeps pulling at that line. If agents are contributors, and CONTRIBUTING.md is where contributors have always looked, then why does agent guidance need a second file at all? The two already overlap on build steps, conventions, and test commands, and maintaining both is the file-level version of the duplication this article set out to kill.

Maybe the front door was never supposed to be a new file. Maybe it was CONTRIBUTING.md all along.

I'll consider that as a follow up article.

Written by Claude, edited by Cavelle Benjamin, across 14 iterations.

The age of AI-assisted development has arrived with a seductive promise: describe what you want, and watch it materialize before your eyes. This "vibe coding" approach—where developers iterate through conversational prompts until something works—feels magical. You can generate components, write functions, and scaffold entire features by simply expressing intent in natural language.

But here's the uncomfortable truth: getting anything working is not the same as building something releasable.

Vibe coding produces code that often works in isolation but fails under the scrutiny of real-world requirements. The function works, but does it handle edge cases? The component renders, but does it follow your team's patterns? The feature ships, but can anyone maintain it? Without structure, consistency, or repeatability, vibe coding leaves technical debt in its wake—a patchwork of solutions that technically function but don't cohere into a maintainable system.

The Agitation: The Illusion of Progress Without Principles

The problem compounds when you realize that vibe coding optimizes for the wrong metric: immediate results over sustainable development. Each interaction with an AI coding assistant becomes a one-off transaction, disconnected from the broader system you're building.

This approach breaks down at scale. When different team members use AI assistants with different prompts, you get divergent implementations. When you need to reproduce a solution, you're left guessing at the original context. When requirements change, there's no clear path to evolve the system because there was no clear path to build it in the first place.

Specifications help. They document intent and create a reference point for implementation. But specs alone bridge only part of the gap—they tell us what to build but often leave the how to individual interpretation. Even with detailed specifications, two developers with two AI assistants might produce vastly different implementations, neither wrong, but neither consistent with established patterns.

What we need isn't just documented intent—we need repeatable work. We need systems that produce consistent outcomes regardless of who's doing the work or when it's being done. We need the benefits of AI-assisted development without sacrificing the principles that make software maintainable, scalable, and reliable.

The Solution: Principled Agentic Systems

A principled agentic system transforms AI coding assistance from a creative free-for-all into an orchestrated, repeatable process. Instead of one-off prompts that produce unpredictable results, principled systems embed structure, roles, and workflows that ensure consistency while maintaining the speed and flexibility that make AI assistants valuable.

The Core Benefits

Portable: Solutions developed within a principled system can be understood, modified, and reused across contexts. The patterns, frameworks, and conventions that guide AI-generated code make it immediately recognizable to any team member.

Modular: By defining clear boundaries and interfaces, principled systems enable AI assistants to work on discrete components without accidentally creating tight coupling or architectural inconsistencies.

Orchestrated: Multiple AI agents can collaborate on complex tasks, each playing a specific role, without stepping on each other's toes. The orchestration ensures that the right agent handles the right task at the right time.

Scalable: As systems grow, principled approaches prevent the entropy that typically accompanies rapid AI-assisted development. Patterns remain consistent, conventions stay enforced, and technical debt doesn't compound exponentially.

Why This Matters

Principled agentic systems deliver three critical outcomes:

Consistency: Every interaction with an AI assistant follows established patterns. Code style, architectural decisions, and implementation approaches remain uniform across the codebase.

Reliability: Repeatable processes produce predictable results. When you ask an agent to implement a feature, you know it will follow your testing conventions, handle errors appropriately, and integrate cleanly with existing code.

Efficiency: Paradoxically, adding structure makes AI assistance faster, not slower. Agents waste no time on ambiguity, make fewer mistakes that require correction, and produce code that passes reviews on the first try.

How to Build Principled Systems

Building a principled agentic system requires five key elements:

Frameworks: Establish the technical scaffolding that guides AI-generated code. This includes coding conventions, architectural patterns, and technology choices that agents should follow.

Workflows: Define the sequence of steps that AI agents should follow when tackling different types of tasks. A workflow for adding a feature differs from a workflow for fixing a bug or refactoring code.

Ceremonies: Create checkpoints where AI work gets validated against project standards. These might include automated linting, type checking, test execution, or code review protocols.

Artifacts: Produce documentation, specifications, and configuration that capture decisions and provide context for future AI interactions. Each artifact becomes institutional knowledge that agents can reference.

Personas: Design specialized agents with specific roles and dispositions. A refactoring agent thinks differently from a feature-development agent. A testing agent has different priorities than a documentation agent. By assigning distinct personas, you ensure each agent optimizes for its domain.

Principled Systems in Practice

Tools like OpenCode demonstrate this approach in action. Rather than limiting you to a single, monolithic AI assistant, OpenCode enables you to orchestrate multiple specialized agents. Need to research an API while implementing a feature? Kick off a research sub-agent that gathers information and reports back to the primary agent. Need to verify that your changes don't break existing functionality? Delegate to a testing agent that validates your work.

This orchestration transforms AI assistance from a single-threaded process into a parallel, collaborative workflow. The primary agent maintains context and coordinates, while specialized sub-agents handle discrete tasks within their domain of expertise. Each agent operates according to its persona—its defined role and disposition—ensuring that every task gets handled by the right tool for the job.

The result is repeatable work at scale. The same orchestrated process produces consistent outcomes regardless of when it runs or who initiates it. The frameworks ensure technical consistency. The workflows guarantee procedural reliability. The ceremonies catch errors before they compound. The artifacts preserve knowledge. And the personas ensure that each task gets the appropriate treatment.

Conclusion: From Vibe to Value

Vibe coding will get you anything, but principled agentic systems will get you something releasable, maintainable, and scalable. By embedding structure into how we work with AI assistants, we capture the speed and creativity of AI-assisted development while maintaining the consistency and reliability that professional software demands.

The future of development isn't choosing between human rigor and AI speed—it's building systems where AI assistance operates within principled boundaries that amplify both.

Written with the support of Claude Opus 4.5

Product Management is the craft of observing, orienting, deciding, and acting on the improvement of outcomes through the use of physical goods and or services.

Product Management’s origins are often credited to the 1931 Neil Mcelroy’s 1931 Brand Men Memo. However, one could consider Product Management going back to the concept of workmanship or craftmanship througout human history. Said another way, the idea of creating something tangeable (hardware), or intageable (software), providing a service for someone else to use is an act of product management. Over time, we have developed tools and processes to execute this work in a repeatable way.

1. Create clarity of perspective and purpose

2. Cast a vision, formulate strategy, manage execution

3. Create feedback loops for continuous improvement of people, process, and tools

Creating a framework that is agnostic of hardware, software, or service is important. Here’s is a version of a framework that I’ve used with my teams.

• Definining the activity someone is doing

• Define the outcomes someone is trying to achieve with the activity

• Recognize gaps in outcomes

• Researching and contextualizing the reach and impact of the gap and the urgency of resolution

• Planning out a solution (minimum viable experience)

• Developing a solution

• Releasing a solution

• Monitoring and reviewing the performance of that solution

• Reflecting on changes to the solution with continous improvement