feat: install scopes for global and linked installations - #19
Merged
Conversation
Why: The framework had a single install root, so using it across many repositories meant maintaining byte-identical copies of every framework file, and there was no way to get the behavior at all in a repository that should not be modified. What: - --scope repository|global|linked on both installers. global installs framework-owned instructions and managed skills into $HOME/.agents and writes no repository state; linked installs only a repository's own learning state and reads the rest from the global installation. repository stays the default and behaves exactly as before. - .repository-files manifests naming the repository-authored seeds. The framework-owned half was already declared in .managed-files, so this makes the split explicit instead of implicit in what update happens not to overwrite, and ci-validate.py now rejects a packaged file declared in neither or in both. - A "Framework root" rule in agentic-flow/AGENTS.md: resolve at the repository root first and ~/.agents/ second, a repository copy always wins, never merge the two, and repository state is never read from the global root. - learning-flow/.install-scope recording scope and framework version, with a skew warning between a linked repository and its global installation. This reintroduces a version marker under the three conditions DESIGN_NOTES set in 1.3: a documented reader, a stated rule, and a CI check. - Scope conversion in both directions, and a warning when a repository-scoped install would make the host agent discover every managed skill twice. - Fixes docs/EXAMPLE_WALKTHROUGH.md missing from MANIFEST.txt, which shipped a packaged docs/README.md whose link to it was broken. Checks: - Nine scope scenarios pass identically on install.sh and install.ps1 against a locally built package: refusal without a global installation, no cross-root leakage in either direction, seed preservation on update, profile and extension inheritance, both conversion directions, and unrelated global skills left untouched. - scripts/ci-release-test.sh passes with its new global and linked assertions. - MANIFEST.txt matches disk, and all relative markdown links resolve both in the repository and inside the built package. - scripts/ci-validate.py was not executed: no Python is available locally. Its checks were ported to PowerShell and run against the same data, so the Python itself is verified by reading only and relies on the first CI run. Traceability: - Requirements: global installation support with repository-local learning state - Design: docs/DESIGN_NOTES.md, "v1.4 install scopes: one framework, many repositories" - Behavior change: Minor (additive opt-in dimension; repository scope unchanged) - Risk level: Medium - Tests: Added - Documentation: Updated Co-authored-by: Cursor <cursoragent@cursor.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why:
The framework had a single install root, so using it across many repositories meant maintaining byte-identical copies of every framework file, and there was no way to get the behavior at all in a repository that should not be modified.
What:
Checks:
Traceability: