Skip to content

feat: install scopes for global and linked installations - #19

Merged
legrab merged 1 commit into
mainfrom
dev/bg/global-installation
Aug 25, 2026
Merged

feat: install scopes for global and linked installations#19
legrab merged 1 commit into
mainfrom
dev/bg/global-installation

Conversation

@legrab

Copy link
Copy Markdown
Owner

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

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>
@legrab
legrab merged commit a604501 into mainAug 25, 2026
2 checks passed
@legrab
legrab deleted the dev/bg/global-installation branch August 25, 2026 15:57
@legrab
legrab restored the dev/bg/global-installation branch August 25, 2026 15:58
@legrab
legrab deleted the dev/bg/global-installation branch August 25, 2026 15:58
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

@legrab