Unify role providers and composed skills in .agents/roles.kdl #196

New issue

Closed

opened 2026-08-05 05:45:16 +00:00 by coilyco-ops · 0 comments

coilyco-ops commented

2026-08-05 05:45:16 +00:00

Member

Outcome

Make .agents/roles.kdl the single authored role graph for both repository-provider inclusion and composed-skill selection.

Move product-native role-provider declarations out of the separate role_providers_file YAML path. Keep provider resolution and skill selection as distinct internal phases while presenting one coherent authoring model.

Problem

Role composition is currently split across two canonical inputs:

.agents/roles.kdl selects role-composed skills.
A separate config/role-providers.yaml selects repository providers for each role.

The second file is difficult to discover because it describes agent behavior but lives outside .agents/. It is also projected into host configuration through a special symlink even though the mapping is product-native and shared across Kai's personal hosts rather than host-specific deployment tuning.

The split makes one role's effective capability graph harder to inspect and maintain. For example, Ops receives Infrastructure and Deploy through the YAML file while its composed skills are selected in KDL.

Proposed authoring model

Extend .agents/roles.kdl with named provider declarations and explicit role references:

providers {
    provider hardware path="coilyco-bridge/agentic-os-hardware" {
        skill "compute-stack"
        skill "machine-*"
    }

    provider infrastructure path="coilyco-flight-deck/infrastructure"
    provider deploy path="coilyco-bridge/deploy"
}

roles {
    role engineer {
        use-provider hardware required=true

        composed-skill "coding-*"
    }

    role ops {
        use-provider hardware required=true
        use-provider infrastructure required=true
        use-provider deploy required=true

        composed-skill "coding-*"
        composed-skill "tooling-ops-*"
    }
}

Named providers replace YAML anchors and keep repository paths and selectors defined once. Provider identifiers should be document-local so multiple trusted root catalogues cannot collide accidentally.

Runtime model

Unify authoring without flattening the resolver:

Load the trusted root catalogues configured for the host.
Read each root catalogue's .agents/roles.kdl.
Resolve provider references for the assigned role.
Hydrate and fully validate the selected provider catalogues.
Apply exact and glob selectors.
Union ordinary and composed skills into the verified bundle.

Only trusted root manifests should be allowed to introduce repository providers. Imported providers must not recursively widen the provider graph unless a future explicit contract permits it.

Validation and explanation

Fail closed on:

duplicate or conflicting provider definitions
missing required providers
recursive imports and cycles
unmatched or invalid selectors
conflicting definitions for one resolved repository path
provider references that are not declared in the same trusted manifest

Preserve full provenance in compose --explain, describe, and semantic diff output. A trace should make edges such as role ops -> AOSK provider deploy -> selected catalogue visible.

Migration

Extend the KDL schema and compile provider declarations into the same internal role-provider representation currently produced from YAML.
Temporarily accept the legacy role_providers_file, but fail when legacy and KDL provider declarations are both active.
Migrate AOSK's mappings into .agents/roles.kdl.
Compare every canonical role's provider set, selected skills, trace, and context-budget snapshot for semantic parity.
Remove role_providers_file from the host schema after migration.
Remove Infrastructure's conventional role-provider symlink and its template wiring.
Retire the standalone YAML parser and update migration and feature documentation.

Host configuration should retain genuinely host-level inputs such as projects_root, trusted catalogue roots, harness load points, and machine-specific overlays.

Acceptance criteria

.agents/roles.kdl supports named provider declarations with path, required-state, and optional skill selectors.
Roles can reference declared providers without repeating paths or selectors.
Provider definitions are document-local and only trusted root manifests can widen the repository-provider set.
Provider cycles, conflicts, missing required paths, and selector failures are rejected deterministically.
Existing provider hydration and full-catalogue validation guarantees remain intact.
Explanation, description, and diff surfaces show role-to-provider provenance.
Legacy YAML and KDL inputs cannot silently merge.
All canonical roles retain semantically identical provider and skill selections through the AOSK migration.
Host configuration no longer needs role_providers_file after migration.
Infrastructure no longer maintains the role-provider symlink after migration.
Documentation, migration guidance, fixtures, context-budget evidence, and feature inventory remain consistent.
Repository validation passes through declared Ward verbs.

## Outcome Make `.agents/roles.kdl` the single authored role graph for both repository-provider inclusion and composed-skill selection. Move product-native role-provider declarations out of the separate `role_providers_file` YAML path. Keep provider resolution and skill selection as distinct internal phases while presenting one coherent authoring model. ## Problem Role composition is currently split across two canonical inputs: * `.agents/roles.kdl` selects role-composed skills. * A separate `config/role-providers.yaml` selects repository providers for each role. The second file is difficult to discover because it describes agent behavior but lives outside `.agents/`. It is also projected into host configuration through a special symlink even though the mapping is product-native and shared across Kai's personal hosts rather than host-specific deployment tuning. The split makes one role's effective capability graph harder to inspect and maintain. For example, Ops receives Infrastructure and Deploy through the YAML file while its composed skills are selected in KDL. ## Proposed authoring model Extend `.agents/roles.kdl` with named provider declarations and explicit role references: ```kdl providers { provider hardware path="coilyco-bridge/agentic-os-hardware" { skill "compute-stack" skill "machine-*" } provider infrastructure path="coilyco-flight-deck/infrastructure" provider deploy path="coilyco-bridge/deploy" } roles { role engineer { use-provider hardware required=true composed-skill "coding-*" } role ops { use-provider hardware required=true use-provider infrastructure required=true use-provider deploy required=true composed-skill "coding-*" composed-skill "tooling-ops-*" } } ``` Named providers replace YAML anchors and keep repository paths and selectors defined once. Provider identifiers should be document-local so multiple trusted root catalogues cannot collide accidentally. ## Runtime model Unify authoring without flattening the resolver: 1. Load the trusted root catalogues configured for the host. 2. Read each root catalogue's `.agents/roles.kdl`. 3. Resolve provider references for the assigned role. 4. Hydrate and fully validate the selected provider catalogues. 5. Apply exact and glob selectors. 6. Union ordinary and composed skills into the verified bundle. Only trusted root manifests should be allowed to introduce repository providers. Imported providers must not recursively widen the provider graph unless a future explicit contract permits it. ## Validation and explanation Fail closed on: * duplicate or conflicting provider definitions * missing required providers * recursive imports and cycles * unmatched or invalid selectors * conflicting definitions for one resolved repository path * provider references that are not declared in the same trusted manifest Preserve full provenance in `compose --explain`, `describe`, and semantic diff output. A trace should make edges such as `role ops -> AOSK provider deploy -> selected catalogue` visible. ## Migration 1. Extend the KDL schema and compile provider declarations into the same internal role-provider representation currently produced from YAML. 2. Temporarily accept the legacy `role_providers_file`, but fail when legacy and KDL provider declarations are both active. 3. Migrate AOSK's mappings into `.agents/roles.kdl`. 4. Compare every canonical role's provider set, selected skills, trace, and context-budget snapshot for semantic parity. 5. Remove `role_providers_file` from the host schema after migration. 6. Remove Infrastructure's conventional role-provider symlink and its template wiring. 7. Retire the standalone YAML parser and update migration and feature documentation. Host configuration should retain genuinely host-level inputs such as `projects_root`, trusted catalogue roots, harness load points, and machine-specific overlays. ## Acceptance criteria * [ ] `.agents/roles.kdl` supports named provider declarations with path, required-state, and optional skill selectors. * [ ] Roles can reference declared providers without repeating paths or selectors. * [ ] Provider definitions are document-local and only trusted root manifests can widen the repository-provider set. * [ ] Provider cycles, conflicts, missing required paths, and selector failures are rejected deterministically. * [ ] Existing provider hydration and full-catalogue validation guarantees remain intact. * [ ] Explanation, description, and diff surfaces show role-to-provider provenance. * [ ] Legacy YAML and KDL inputs cannot silently merge. * [ ] All canonical roles retain semantically identical provider and skill selections through the AOSK migration. * [ ] Host configuration no longer needs `role_providers_file` after migration. * [ ] Infrastructure no longer maintains the role-provider symlink after migration. * [ ] Documentation, migration guidance, fixtures, context-budget evidence, and feature inventory remain consistent. * [ ] Repository validation passes through declared Ward verbs.

coilyco-ops referenced this issue

2026-08-05 05:53:34 +00:00

Add transitional roles.kdl provider graph support #197

coilyco-ops referenced this issue from coilyco-flight-deck/infrastructure

2026-08-05 05:53:34 +00:00

Remove legacy Agent Compose role-provider symlink wiring #756

coilyco-ops referenced this issue from a commit

2026-08-05 06:35:45 +00:00

feat: retire legacy role provider YAML (closes #196)

coilyco-ops referenced this issue from a pull request that will close it,

2026-08-05 06:35:59 +00:00

feat: retire legacy role provider YAML #199