docs: plan remote collections and record the OKF decision

[luabagg]

Summary

This PR adds a design spec and an implementation plan. It changes no runtime code.

• docs/superpowers/specs/2026-10-04-remote-collections-design.md: the design.
• docs/superpowers/plans/2026-10-04-remote-collections.md: 7 tasks with tests, code, and commits.

The plan lets Agentfolio use a collection from a git source:

agentfolio sync github:owner/repo#v1 --dry-run
agentfolio sync github:owner/repo#v1
agentfolio apply --collection github:owner/repo#v1

sync fetches the source into a managed clone, checks out one commit, validates collection.yaml, and runs an optional prepare command. All other commands stay offline. Without a source, sync runs prepare for a local collection.

Why

Today --collection accepts only a local directory. A consumer must clone the collection and install its dependencies by hand. Agentfolio cannot report a missing dependency step. With luabagg/agent-skills, a fresh clone without npm ci passes doctor and plan. apply then fails with only rejected request.

This feature helps people who consume a collection that someone else writes. An author keeps a normal checkout and gets only prepare.

Decisions and trade-offs

• Schema stays version: 1. prepare is an optional top-level field. Agentfolio 0.1.x rejects it as an unknown field. Release as 0.2.0 and document that minimum version.
• One fixed managed path per repository, $AGENTFOLIO_HOME/collections/<host>/<path>. Adapters link files into the collection root, so a directory per commit would break links on each update. Sync refuses a clone with changes to tracked files.
• Sync state lives in .git/agentfolio-sync.json. Other commands refuse a clone when the state is missing, does not match HEAD, or has a different ref. There is no automatic rollback. The error prints the last synced commit.
• Only sync uses the network. This extends the current rule against network installs during normal operation.
• git, not tarballs. git uses the SSH agent or credential helper, so private repositories work and Agentfolio never handles tokens. Agentfolio refuses URLs that contain credentials and sets GIT_TERMINAL_PROMPT=0.
• Out of scope: Windows, abbreviated SHAs, lock files, and cleanup of managed clones.

OKF knowledge bundles

The spec records why Open Knowledge Format bundles stay out of Agentfolio core:

• OKF defines content, not placement.
• Agentfolio keeps fields reference-only until an executable, pinned contract exists.
• The only generic part, fetching a pinned git source, is the sync primitive in this plan.

Revisit this after sync ships, if a collection needs pinned knowledge sources.

Known limitations

• prepare output above 64 KiB per stream stops the command, because of the runProcess() limit. Collections must use quiet flags.
• An https URL and an ssh URL for one repository map to one path. Sync refuses the second form and does not reconcile it.
• After two failed syncs in a row, the error no longer shows the last good commit.

Verification

The code in tasks 1 to 6 ran in a scratch worktree from b60df24:

• npm test: 86 tests pass.
• check:dependencies, check:secrets, and package:smoke pass.
• A smoke test against GitHub synced github:luabagg/agent-skills into a scratch AGENTFOLIO_HOME. plan --profile pi then printed its source and commit.

On this branch, npm test, check:secrets, and package:smoke pass.

Before release

package.json publishes docs/. Remove docs/superpowers/ before the 0.2.0 release, as in 7c612ae.

🤖 Generated with Claude Code