Multi-parent / mixin profile inheritance

[psenger]

The Problem

Agent-OS's profile system uses single-parent inheritance — each profile has exactly one inherits_from in config.yml. For projects that fit cleanly into one technology stack, this works well.

Real-world projects often don't. A fullstack application with a React frontend and a FastAPI backend needs standards from two separate profile branches at once. Right now there's no native way to express that, so you end up reaching for workarounds that technically work but leave the setup implicit and brittle.

This is related to [#200](#200), which proposes a similar concept from the install script side (--mixins propel-auth,prisma). This discussion focuses on the config representation side of the same problem — how multi-profile intent gets encoded in config.yml so tooling can understand and enforce it.

Why Single-Parent Falls Short

Consider a monorepo or fullstack project:

• The frontend needs TypeScript conventions, React patterns, and frontend testing rules
• The backend needs Python conventions, FastAPI patterns, and async error handling rules
• Both sides share org-wide base standards

None of those concerns belong to a single profile lineage. Forcing them into one inherits_from chain means either creating bespoke composite profiles for every combination, or silently dropping standards from one side.

Current Workarounds and Their Costs

Option A — Composite leaf profile: Manually copy standards from multiple source profiles into a dedicated composite directory. Explicit, but it duplicates files, drifts as source profiles evolve, and requires manual upkeep whenever an upstream profile changes.

Option B — Sequential install + manual cp: Install the primary profile via project-install.sh, then copy standards from a second profile into agent-os/standards/. Fragile — a second run of project-install.sh overwrites everything — and the layering is invisible in config.yml.

Option C — /discover-standards after install: Let the agent infer standards for the secondary language from the codebase. Useful when the secondary stack is genuinely project-specific, but not the right fit when the standards already exist in a known profile.

All three produce a working setup. None of them encode the intent ("this project uses both of these profiles") in a way that tooling can understand or enforce.

Proposed Change

Allow inherits_from to accept a list:

profiles:
  fullstack-react-fastapi:
    inherits_from:
      - frontend-react
      - backend-fastapi

Resolution order (leftmost wins on conflict) would keep the behavior predictable. A separate mixins: key is another option — it makes the additive intent explicit without touching the existing inherits_from semantics, and would align naturally with the install-time --mixins flag proposed in [#200](#200).

Questions for the Maintainers

• Is multi-parent inheritance something you have considered or deliberately avoided?
• If a mixins: approach is preferred, are there constraints on how conflict resolution should work?
• Is there an alternative design that achieves the same goal within the current architecture?
• Is it worth coordinating this with [#200](Project Mixins #200) so the config representation and the install interface land consistently?

Happy to open a PR if the direction looks right. Thanks for the project — it has meaningfully improved consistency across how our AI agents operate.

[phil-cc]

Hey @CasJam - wanted to push on this with some real operational context, because the problem is sharper than the "fullstack app" framing captures.

We run multiple monorepos, and inside each one there are genuinely co-equal language stacks - not a "primary" language with a secondary one bolted on. A typical repo for us has PHP/Laravel handling the API layer, TypeScript/React on the frontend, and Python services alongside for data work. These are not separate concerns that could be split into separate repos. They live together because they are the same product.

This is where the current profile model breaks down. The entire inheritance system assumes a project has one dominant technology lineage and you walk up that chain to collect standards. In a monorepo with co-equal stacks, that assumption doesn't hold. There is no single lineage. There are three, and all three need to be active at the same time.

The workarounds all hit the same wall - they don't survive the next install, or they introduce structural problems of their own. Composite profiles drift the moment an upstream profile changes. Sequential installs get overwritten. /discover-standards is useful for surfacing project-specific patterns but it can't reconstruct what a profile would have provided.

The most sophisticated thing I tried: install a base/common profile at the repo root, then install stack-specific profiles inside subdirectories and link back up to the root for shared items. It didn't work - Agent OS isn't designed with nested installs or cross-directory linking in mind, and the result was brittle enough that I abandoned it. I raise it because it shows the monorepo case drives you toward solutions the tool's architecture doesn't support.

The mixin proposal is the right direction. But before the design is locked, one question I'd want answered:

Is a flat global merge the right model for a monorepo? If I merge php-laravel, frontend-react, and backend-python into a single flat standards folder, the agent has all three sets of conventions active simultaneously with no way to know that PHP error handling conventions shouldn't apply when it's working in a Python file. The conflict resolution problem shifts from the install step to the inference step.

A few things I'd like your thinking on:

• When you designed single-parent inheritance, was the co-equal multi-stack case deliberately deferred, or was the working assumption that projects have a primary language with occasional supplements?
• Does the mixin model solve the install problem but leave the standards-scoping problem unaddressed - and does that matter in practice?
• Have you considered directory-scoped profile resolution as a complement - where config says "under backend/, apply php-laravel standards; under frontend/, apply frontend-react standards"? That maps more naturally to how a monorepo is structured than a flat merge.

This is the hardest wall we hit with Agent OS in practice. The answer shapes whether mixins fully solve it or only solve part of it.