Intent Files Across Multiple Repos: The Missing Governance Layer for Real App Teams

Intent Files Across Multiple Repos: The Missing Governance Layer for Real App Teams

Intro

Today’s demo went well because the architecture was strong, the tooling was advanced, and the environment had serious governance behind it: Claude Code, plugins, agents, MCP servers, shared rules, and architectural guardrails.

That is powerful.

But it also exposes a real problem for application teams.

In a perfect-world setup, the platform team already knows the patterns. They already know the architecture. They already know what “good” looks like. The app team is then expected to produce code that matches that standard immediately.

That creates pressure.

Not always because the team is weak. Often because the governance model is too far away from how real delivery teams actually work.

And one question from the demo hit the real issue:

What happens when one application solution spans multiple repositories, and the team needs to share common intent files across all of them?

That question matters.

Because this is where Intent-Driven Engineering moves from a cool demo into a real enterprise operating model.

What Is the Problem?

Most enterprise solutions are not clean monorepos.

A single business capability may span:

• frontend repo

• backend API repo

• shared domain repo

• infrastructure repo

• test automation repo

• data pipeline repo

• event processor repo

• adapter repo

So when a team starts using intent files, the question becomes:

Where does shared intent live?

If every repo copies the same intent definitions manually, the system breaks down quickly.

If every repo invents its own version, governance collapses.

If shared services owns everything, app teams lose autonomy.

So the answer is not “just put intent files everywhere.”

The answer is:

Create a team-level shared intent library, version it properly, and let each repo consume it intentionally.

The Right Pattern: A Team Intent Library Repo

The best practice is to create a separate repository owned by the delivery team or product capability team.

Something like:

provider-submission-intent-library

or

claims-platform-intent-contracts

or

team-intent-standards

This repo becomes the team’s shared intent layer.

It should not replace the enterprise shared services layer. It should sit between enterprise governance and individual application repos.

The model looks like this:

Enterprise Governance Layer

  ↓

Shared MCP Servers / Plugins / Agents / Architectural Rules

  ↓

Team Intent Library Repo

  ↓

Application Repos

  ↓

Feature-Level Intent Files

That is the clean separation.

Enterprise governance defines the big rules.

The team intent library defines reusable team patterns.

Each application repo defines the specific feature intent.

Why Not Just Copy Intent Files?

Because copying is not governance.

Copying creates drift.

One repo changes the customer validation intent. Another repo still has the old version. A third repo modifies the retry behavior. A fourth repo removes a success criterion to make a PR pass faster.

Now the team thinks it has standards, but really it has fragments.

That is worse than no governance because everyone believes they are aligned when they are not.

Intent files need version control, ownership, review, release notes, and dependency strategy.

That means shared intent should be treated like code.

What Goes in the Team Intent Library?

The team intent library should include common definitions that multiple repos need.

For example:

/intents

  /shared

    provider-submission-base.intent.yaml

    insurance-validation.intent.yaml

    audit-trail.intent.yaml

    error-handling.intent.yaml

    retry-policy.intent.yaml

    security-boundaries.intent.yaml

    api-contract-standard.intent.yaml

It may also include shared schemas:

/schemas

  provider-submission.schema.json

  payer-response.schema.json

  eligibility-check.schema.json

  audit-event.schema.json

And shared success criteria:

/success-criteria

  rest-api-quality.yaml

  observability-required.yaml

  pii-protection.yaml

  contract-test-required.yaml

The goal is simple:

Do not make every repo rediscover the same intent.

How Application Repos Should Use It

Each application repo should keep its own local feature intent files.

For example:

/provider-api

  /intents

    submit-provider-claim.intent.yaml

But that local intent file should reference the shared library.

Example:

intent_id: submit-provider-claim

version: 1.0.0

inherits_from:

  - repo: provider-submission-intent-library

    intent: provider-submission-base

    version: 1.2.0

  - repo: provider-submission-intent-library

    intent: audit-trail

    version: 1.0.3

goal: Create a REST API endpoint for provider claim submission.

inputs:

  - provider

  - member

  - payer

  - procedure_codes

  - attachments

outputs:

  - submission_id

  - validation_status

  - payer_routing_result

  - audit_event

success_criteria:

  - api_contract_generated

  - validation_rules_applied

  - pii_not_logged

  - audit_event_created

  - tests_generated

That gives the team local flexibility without losing shared governance.

The Key Rule: Shared Intent Must Be Versioned

The team intent library should use semantic versioning.

1.0.0 = initial shared intent

1.1.0 = backward-compatible enhancement

2.0.0 = breaking change

Application repos should pin to a version.

Do not let every repo automatically pull latest without review.

That sounds convenient, but it is dangerous.

Governance should be dynamic, but not reckless.

A better model is:

inherits_from:

  version: 1.2.0

Then upgrade intentionally through a PR.

That gives teams traceability.

The Best Practice Architecture

The best model is three-layer intent governance:

1. Enterprise Intent Standards

Owned by shared services, architecture, platform, or governance teams.

This includes:

security rules

API standards

approved frameworks

logging requirements

observability standards

deployment rules

MCP server access rules

Claude Code plugins

agent behavior

2. Team Intent Library

Owned by the app/product team.

This includes:

domain-specific patterns

shared DTO rules

team API patterns

common validation logic

common workflow intent

team testing expectations

team-specific success criteria

3. Repo-Level Feature Intent

Owned by the engineers building the feature.

This includes:

specific feature goal

inputs

outputs

constraints

business rules

acceptance criteria

implementation boundaries

That is how you avoid both extremes:

You avoid chaos.

You also avoid over-centralized control.

Why This Matters

A lot of companies love control centers.

They love dashboards, standards, review gates, plugins, agents, and governance.

That is not automatically bad.

But if governance becomes a watchdog instead of an enablement system, teams become afraid to build.

They are no longer engineering.

They are trying not to get caught.

Intent-Driven Engineering should not be about making app teams look bad because they did not magically know the perfect answer.

It should be about giving them the reusable context, constraints, patterns, and success criteria they need before they start.

Good governance does not just reject bad work.

Good governance helps good work happen earlier.

The Practical Recommendation

For teams working across many repos, do this:

Create a dedicated team-level intent library repo.

Version every shared intent.

Allow application repos to inherit from that library.

Keep feature-specific intent files inside each application repo.

Use PR review for shared intent changes.

Require each repo to pin the shared intent version.

Automate validation in CI/CD.

Track which repos consume which intent versions.

That gives you enterprise control, team autonomy, and repo-level execution.

Final Takeaway

If a solution spans ten repos, then intent cannot live in ten disconnected places.

And it cannot live only in some central architecture tower either.

The right answer is a governed shared intent library owned close to the team, versioned like code, consumed by each repo, and aligned to enterprise standards.

That is how Intent-Driven Engineering becomes real.

Not just prompts.

Not just plugins.

Not just agents.

Not just MCP servers.

A working system of governed intent.

Because the intent file is not documentation.

It is the system.