Skip to content

docs: propose local skill source governance - #34728

Open
hkrishg-aws wants to merge 1 commit into
kirodotdev:mainfrom
hkrishg-aws:docs/project-skills-governance-rfc-lts
Open

hkrishg-aws wants to merge 1 commit into
kirodotdev:mainfrom
hkrishg-aws:docs/project-skills-governance-rfc-lts

Conversation

@hkrishg-aws

Copy link
Copy Markdown
Contributor

Rebased replacement for #30574. That PR cannot merge: it edits
docs/request-for-change/rfc-crew-enterprise-edition.md, which
#32970 renamed to
rfc-crew-lts-edition.md on 2026-11-08, so git sees modify-versus-delete.
This branch carries the same design as one commit on current main, retargeted
to the LTS file. Two counts moved on main in the meantime: the Yellow class went
20 to 17, so splitting one appendix row into two now yields 18, not 21, and
the appendix heading ### Yellow (n) is updated alongside the class-table cell.
The control count goes 66 to 67 in both places it appears. The proposed key
skills.local_sources and policy term crew_extension_local_sources are
unchanged, since the appendix kept its crew_extension_* naming through the rename.


Problem / Motivation

Goal: Record the governance design for letting an operator's policy narrow which repository and config-selected local directories may supply skills to an agent.

A project's .kiro/skills, skills.extra_paths, local skill:// mappings and the KIROCREW_PROJECT_DIR source can supply SKILL.md instructions, but no policy key represents those source roots today. Project skills have a local off switch and directory trust grant; neither gives an enterprise operator a central ceiling.

Why it matters

A repository or local configuration can select skill content that enters the agent's context. The operator can govern discovery registries and many tool effects, but cannot centrally restrict these source directories. The design adds that missing ceiling without turning policy approval into a project trust grant.

Not a goal

  • Implementing the policy key or changing runtime behavior in this PR.
  • Governing the user's global skill roots, where packaged, installed and manually authored content share one path.
  • Governing skill content integrity, signatures or digests after a source is admitted.
  • Resolving remote or container path identity before a maintainer chooses the namespace.
  • Changing project-skill trust or enabling project skills on unsupported platforms.

What changed (motivation → approach → change)

This docs-only PR adds rfc-local-skill-sources-governance.md. It proposes an allow-only skills.local_sources policy key over canonical source roots, with policy acting as a conjunct beside the existing local controls. Four maintainer decisions are called out at the top.

The rollout has two gates. Phase 0 inventories detected roots and previews the policy decision without changing admission. Phase 1 enforces the enterprise default-off behavior only after that preview exists. The RFC defines 22 executable Phase 1 assertions, including profile handling, path aliases, source replacement, catalog-generation races, duplicate-name shadowing, audit deduplication and harness parity.

The accepted enterprise-edition RFC's single "Extension sources" row is split into registry hosts and local skill sources, raising the appendix count from 66 to 67. The request-for-change index gains the new draft row.

Backwards compatibility

Compatible: this PR changes documentation only. The RFC records that its future Phase 1 would be a breaking enterprise default, preceded by a non-enforcing Phase 0 preview and migration recipe.

Removes nothing: no runtime, policy parser, skill source, configuration or user-facing behavior changes in this PR.

Tests

Proof: not provable -- docs-only change.

  • make build passed.
  • ./scripts/docs-lint.sh passed.
  • .venv/bin/python scripts/local-gate.py passed: 505 backend tests and 13,395 frontend tests.

Manual verification

Reviewed all three changed documents against upstream main and confirmed the RFC index, enterprise control counts and cross-links agree. Confirmed no customer, private security-report or internal-only content appears in the diff.

Screenshots / video

N/A, docs-only design proposal with no user-interface change.

Related Issues

Refs #29686

Checklist

  • At most two commits, with a Conventional Commits title
  • Existing change-scoped tests pass
  • Self-review completed; documentation follows repository conventions
  • Documentation and indexes updated
  • No secrets, credentials or internal references in the diff

Contribution License Agreement

Contributed under the repository's Apache-2.0 license.

Rebase onto the LTS Edition rename (kirodotdev#32970), which moved the appendix row
this design splits from rfc-crew-enterprise-edition.md to
rfc-crew-lts-edition.md. The Yellow class count also moved from 20 to 17 on
main, so splitting one row into two now yields 18 rather than 21. Both the
class-table cell and the appendix heading are updated, and the control count
goes 66 to 67 in the two places it appears.

Supersedes kirodotdev#30574, which cannot merge because it edits the pre-rename path.
@hkrishg-aws
hkrishg-aws requested review from a team and KiroCrewCaptain as code owners November 10, 2026 18:36
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Nov 10, 2026
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 12, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant