[Feature] Support hierarchical capabilities in monorepos

[toransahu]

Description

Capa currently documents capabilities.yaml or capabilities.json at the project root as the source of truth. The CLI appears to resolve the file from the current working directory, and agents content is materialized at that project root.

Please clarify the recommended Capa model for a monorepo that has shared repository capabilities plus nested projects with independently owned guidance and capability requirements. If there is no supported composition model today, this is a request for first-class hierarchical configuration.

Generic example:

repo/
  capabilities.yaml
  services/
    api/
      capabilities.yaml
  packages/
    web/
      capabilities.yaml

Questions about current behavior:

1. Is there a supported way for the root configuration to compose nested project configurations in one install?
2. Can a nested configuration inherit root providers, rules, hooks, tools, and agent instructions while adding or overriding project-local entries?
3. If each directory is installed as an independent Capa project, how should overlapping generated files, hooks, MCP gateway registration, status, and cleanup be coordinated?
4. What pattern does Capa recommend today for nested AGENTS.md or provider-specific guidance that must remain project-local?

Requested behavior

A first-class solution should provide:

1. Explicit workspace discovery. The root file declares nested capability files or workspace paths; Capa should not recursively trust arbitrary files by default.
2. Deterministic inheritance. A nested project receives root defaults and can add, override, or disable entries using documented precedence rules.
3. Scoped agent instructions. Capa materializes project-local guidance at the nested path in each provider's supported form, while preserving normal nearest-file/hierarchical discovery.
4. Provider-faithful scope. Path-sensitive rules remain scoped where the provider supports it, with a warning or validation error when inheritance would broaden behavior.
5. One lifecycle. Root-level install, dry-run, status, drift validation, and clean understand the full workspace graph and modify only Capa-owned output.
6. No duplicate runtime wiring. Inherited hooks, servers, tools, and subagents are not registered multiple times unless a child explicitly overrides or adds them.
7. Clear ownership and conflict handling. Duplicate IDs, provider-list changes, cycles, missing child files, and parent/child lockfile conflicts have deterministic diagnostics.
8. Independent operation where useful. Running from a nested project should resolve its effective inherited configuration without silently dropping repository defaults.

Possible syntax, only as an illustration:

# repo/capabilities.yaml
workspaces:
  - path: services/api
  - path: packages/web

or:

# repo/services/api/capabilities.yaml
extends: ../../capabilities.yaml

The exact model could also build on the capability composition proposed in #52, provided it adds local project scope and lifecycle semantics rather than only reusable remote imports.

Motivation

Large monorepos often have repository-wide agent policy and tooling alongside project-specific guidance owned by different teams. A single flat configuration centralizes unrelated details, while independent nested installs duplicate shared declarations and leave ownership of overlapping generated provider files unclear.

Hierarchical capability resolution would keep Capa as the authored source of truth while matching the scope model already used by providers that discover instructions from the repository root down to the nearest project directory.

Alternatives considered

• One root configuration with rules.appliesTo. Useful for scoped rules, but it does not provide independently owned project configuration or nested agents.base; providers that fold rules into root instructions may also broaden the declared scope.
• Independent Capa installation in every nested directory. Treats each directory as a separate project, with no documented inheritance or root lifecycle coordinating overlapping outputs.
• Manually maintained nested AGENTS.md, CLAUDE.md, or other provider files. Preserves native hierarchy but moves project guidance outside Capa ownership.
• Remote capability composition from Support the installation of remote capabilities #52. Helps reuse capability bundles, but does not by itself define parent/child path scope, nested generated files, or monorepo install and cleanup behavior.

[Minitour]

Thanks @toransahu for the issue. This is an interesting use case.

As of today, you can have independent capabilities.yaml files in nested projects. However running capa install will only materialize to that root folder. Meaning that if you a different capabilities file in subfolders or submodules, you'll need to cd into these directories and run capa install - this however will materialize provider configurations in those folders, and their consumption depends on the implementation of the harness.

Is there a supported way for the root configuration to compose nested project configurations in one install?

Not at the moment.

Can a nested configuration inherit root providers, rules, hooks, tools, and agent instructions while adding or overriding project-local entries?

Having a nested project inherit a parent's folder could be tricky, as the install process would need to scan the parent folders to see if there are any capability files, and install them first, but doable.

If each directory is installed as an independent Capa project, how should overlapping generated files, hooks, MCP gateway registration, status, and cleanup be coordinated?

There shouldn't be a conflict, because each subproject would receive it's own folder. Your agent would not read those files unless you launched that harness from that current working directory. For example if you use claude, claude code will not "see" the nested .claude directory. So anything configured there has a high chance of being ignored. The only thing that it will see is the CLAUDE.md file.

What pattern does Capa recommend today for nested AGENTS.md or provider-specific guidance that must remain project-local?

Currently there isn't an official supported pattern for this, but I understand the need. My recommendation is to have a capabilities file at the root, and if you are working directly inside submodules/project directories - give them their own capabilities file as well. As a current workaround you can implement a shell script which scans your work tree for capabilities files, and one by one cd to the folder and runs capa install

My takeaway from this issue - capa install should recursively scan for nested capabilities.yaml file - or at least support a flag -r .
This way you could potentially run something like

capa install -p cursor -r

Let me know what you think.

[toransahu]

Thanks @Minitour for acknowledging this request and sharing your thoughts on it. To me as well individual capabilities files inside each required dirs seems to be a near-fit solution. Looking forward to further detailing and development on this.