Collapse role-composed skill selectors into semantic wildcard families #861

Closed
opened 2026-08-04 04:58:20 +00:00 by coilyco-ops · 0 comments
Member

Outcome

Refactor the checked-in role-composed skill catalog so .agents/roles.kdl expresses role membership through durable semantic families instead of repeated exact names.

The current baseline is 61 selectors, including 17 wildcard selectors. The target shape is 36 selectors, including 24 wildcard selectors. The shorter file is an outcome of better taxonomy, not the primary correctness test.

Decision

  • Wildcards represent coherent families whose future members should intentionally join the role.
  • Do not use character classes, incidental prefixes, or patterns such as tooling-s* merely to reduce line count.
  • Rename misclassified cross-cutting methods into the families they already represent.
  • Keep role knowledge separate from runtime permission, credentials, harness selection, and authority.
  • Director receives the decision-relevant coding core and architecture shapes, not the entire implementation catalog.

Composed-skill renames

Rename each directory, frontmatter name, internal reference, generated reference, and documentation link:

  • coding-git to coding-core-git
  • kai-git-workflow to coding-core-git-workflow
  • coding-licenses to coding-core-licenses
  • tooling-supply-chain-audit to coding-core-supply-chain-audit
  • mcp-server-patterns to coding-mcp-server-patterns
  • tooling-product-brainstorming to tooling-pm-product-brainstorming
  • writing-observer-narrator to writing-voice-observer-narrator
  • writing-to-issues to tooling-issue-decomposition
  • writing-social-linkedin-video to writing-content-linkedin-video

Target role selectors

Engineer

  • coding-*
  • design-system
  • writing-public-repos
  • writing-system-improvement-vocab

Director

  • coding-core-*
  • coding-shape-*
  • tooling-director-decision-architecture
  • tooling-issue-*
  • tooling-pm-*
  • tooling-scout-*
  • tooling-skill-authoring
  • writing-system-improvement-vocab
  • writing-voice-*

QA

  • coding-*
  • design-system
  • tooling-code-review
  • tooling-qa-*
  • writing-public-repos

Ops

  • coding-*
  • tooling-ops-*
  • writing-system-improvement-vocab

Design

  • coding-javascript*
  • *design*
  • tooling-pm-*

Community

  • *discord*
  • tooling-customer-success-*
  • writing-social-*

Portfolio Strategist

  • tooling-advisor-*
  • tooling-ceo-*
  • tooling-director-decision-architecture
  • tooling-issue-*
  • tooling-pm-*
  • tooling-scout-*
  • tooling-skill-authoring
  • writing-voice-*

Content

  • writing-*

Deliberate role-boundary changes

  • Director gains two PM methods.
  • Design gains two PM methods.
  • Community gains writing-social-editorial-loop.
  • Content loses issue decomposition.
  • Director replaces broad coding-* with coding-core-* and coding-shape-*.
  • Director should land at approximately 24 composed skills, down from 34.
  • Other roles retain equivalent composed-skill coverage after renaming.

Implementation requirements

  • Update .agents/roles.kdl to the target selector shape.
  • Update all affected composed-skill paths, frontmatter, internal links, smoke expectations, coverage documentation, and principal-method references.
  • Refresh seed-skill data, selection traces, role probes, and other generated catalog artifacts through their owning generators.
  • Refresh context-budget snapshots and reports affected by renamed sources or changed Director membership.
  • Verify every glob is non-empty and non-overlapping under the owning agent-compose loader.
  • Search the repository for every retired name and resolve all live references.
  • Validate configuration through owning loaders and generators. Do not add a test that restates the selector inventory as a second source of truth.
  • Leave docs/FEATURES.md unchanged because this is a catalog refactor, not a new capability.

Acceptance criteria

  • .agents/roles.kdl contains 36 composed-skill selectors.
  • Twenty-four selectors are semantic wildcard selectors.
  • All nine composed skills use their new canonical names everywhere.
  • Every wildcard expands successfully without collisions or accidental role admissions.
  • Role membership is unchanged except for the deliberate changes listed above.
  • Director receives the core and shape coding families without broad implementation-specific coding guidance.
  • Every canonical role composes successfully.
  • Generated context-budget artifacts and selection evidence are current and drift-free.
  • Focused tests and the complete repository validation suite pass through Ward.
  • The change is committed, pushed, and carried through the resolved Forgejo workflow.

Coordination

  • Issue 764 tracks a separate P4 direction to remove checked-in role-composed sources entirely. This issue improves the currently shipped provider model and does not implement that teardown. Reconcile if issue 764 becomes active before this lands.
  • Issue 859 and PR 860 cover context-inventory measurement scope only. Preserve that boundary while regenerating affected reports.

Non-goals

  • Removing the checked-in role-composed source model.
  • Changing runtime permissions, credentials, mounts, or authority.
  • Changing role personalities, harness mappings, intent routes, or model selection.
  • Adding a new feature-inventory entry.
## Outcome Refactor the checked-in role-composed skill catalog so `.agents/roles.kdl` expresses role membership through durable semantic families instead of repeated exact names. The current baseline is 61 selectors, including 17 wildcard selectors. The target shape is 36 selectors, including 24 wildcard selectors. The shorter file is an outcome of better taxonomy, not the primary correctness test. ## Decision * Wildcards represent coherent families whose future members should intentionally join the role. * Do not use character classes, incidental prefixes, or patterns such as `tooling-s*` merely to reduce line count. * Rename misclassified cross-cutting methods into the families they already represent. * Keep role knowledge separate from runtime permission, credentials, harness selection, and authority. * Director receives the decision-relevant coding core and architecture shapes, not the entire implementation catalog. ## Composed-skill renames Rename each directory, frontmatter name, internal reference, generated reference, and documentation link: * `coding-git` to `coding-core-git` * `kai-git-workflow` to `coding-core-git-workflow` * `coding-licenses` to `coding-core-licenses` * `tooling-supply-chain-audit` to `coding-core-supply-chain-audit` * `mcp-server-patterns` to `coding-mcp-server-patterns` * `tooling-product-brainstorming` to `tooling-pm-product-brainstorming` * `writing-observer-narrator` to `writing-voice-observer-narrator` * `writing-to-issues` to `tooling-issue-decomposition` * `writing-social-linkedin-video` to `writing-content-linkedin-video` ## Target role selectors ### Engineer * `coding-*` * `design-system` * `writing-public-repos` * `writing-system-improvement-vocab` ### Director * `coding-core-*` * `coding-shape-*` * `tooling-director-decision-architecture` * `tooling-issue-*` * `tooling-pm-*` * `tooling-scout-*` * `tooling-skill-authoring` * `writing-system-improvement-vocab` * `writing-voice-*` ### QA * `coding-*` * `design-system` * `tooling-code-review` * `tooling-qa-*` * `writing-public-repos` ### Ops * `coding-*` * `tooling-ops-*` * `writing-system-improvement-vocab` ### Design * `coding-javascript*` * `*design*` * `tooling-pm-*` ### Community * `*discord*` * `tooling-customer-success-*` * `writing-social-*` ### Portfolio Strategist * `tooling-advisor-*` * `tooling-ceo-*` * `tooling-director-decision-architecture` * `tooling-issue-*` * `tooling-pm-*` * `tooling-scout-*` * `tooling-skill-authoring` * `writing-voice-*` ### Content * `writing-*` ## Deliberate role-boundary changes * Director gains two PM methods. * Design gains two PM methods. * Community gains `writing-social-editorial-loop`. * Content loses issue decomposition. * Director replaces broad `coding-*` with `coding-core-*` and `coding-shape-*`. * Director should land at approximately 24 composed skills, down from 34. * Other roles retain equivalent composed-skill coverage after renaming. ## Implementation requirements * Update `.agents/roles.kdl` to the target selector shape. * Update all affected composed-skill paths, frontmatter, internal links, smoke expectations, coverage documentation, and principal-method references. * Refresh seed-skill data, selection traces, role probes, and other generated catalog artifacts through their owning generators. * Refresh context-budget snapshots and reports affected by renamed sources or changed Director membership. * Verify every glob is non-empty and non-overlapping under the owning agent-compose loader. * Search the repository for every retired name and resolve all live references. * Validate configuration through owning loaders and generators. Do not add a test that restates the selector inventory as a second source of truth. * Leave `docs/FEATURES.md` unchanged because this is a catalog refactor, not a new capability. ## Acceptance criteria * [ ] `.agents/roles.kdl` contains 36 composed-skill selectors. * [ ] Twenty-four selectors are semantic wildcard selectors. * [ ] All nine composed skills use their new canonical names everywhere. * [ ] Every wildcard expands successfully without collisions or accidental role admissions. * [ ] Role membership is unchanged except for the deliberate changes listed above. * [ ] Director receives the core and shape coding families without broad implementation-specific coding guidance. * [ ] Every canonical role composes successfully. * [ ] Generated context-budget artifacts and selection evidence are current and drift-free. * [ ] Focused tests and the complete repository validation suite pass through Ward. * [ ] The change is committed, pushed, and carried through the resolved Forgejo workflow. ## Coordination * [Issue 764](https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/issues/764) tracks a separate P4 direction to remove checked-in role-composed sources entirely. This issue improves the currently shipped provider model and does not implement that teardown. Reconcile if issue 764 becomes active before this lands. * [Issue 859](https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/issues/859) and [PR 860](https://forgejo.coilysiren.me/coilyco-flight-deck/agentic-os/pulls/860) cover context-inventory measurement scope only. Preserve that boundary while regenerating affected reports. ## Non-goals * Removing the checked-in role-composed source model. * Changing runtime permissions, credentials, mounts, or authority. * Changing role personalities, harness mappings, intent routes, or model selection. * Adding a new feature-inventory entry.
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
coilyco-flight-deck/agentic-os#861
No description provided.