ADR-0015: Dissolve the Skills Repository into PackV2 Packs (Smallest Stable Owner)

Status: Accepted as architectural direction (architecture-board review 2026-07-17); execution beyond baseline/documentation gated on the three items in "Execution gates" Date: 2026-07-17 Related: ADR-0011 (Oracle upstream convergence), ADR-0014 (Strict IaC for Gas City), beads iac-ozq (compiler decision), iac-zlp (blutown lifecycle)

Context

blueflyio/agentictools/skills (@bluefly/capabilities, 50M, 3,063 files, 436 SKILL.md) predates or overlaps the current PackV2 platform model and therefore contains responsibilities that now belong to the upstream platform. Six read-only audits (2026-07-17) established: a hand-rolled per-vendor materializer (69/69 symlinks broken), four parallel registry/lock formats, an obsolete MCP skill server, and a "Capability OS" runtime that CI never builds — alongside ~370 genuinely Bluefly-authored skills, which are the durable asset.

Decision principle — Smallest Stable Owner: the skills repository is no longer the smallest stable owner of most capabilities it contains. Capability ownership, logical identity, and physical repository layout are decoupled: pack identity is deliberately independent of pack location. Business behavior is retained (as pack payload); duplicated platform machinery is removed.

Artifact 1 — Upstream Equivalence Matrix

Every retired subsystem mapped to its verified PackV2/Gas City replacement. "Working evidence" = observed on 2026-07-17, this workspace.

Existing subsystem	Upstream replacement	Documentation	Working evidence
Projection/vendor-sink farms (.pi/.goose/.kiro/.continue/.adal/.codebuddy/.kilocode symlink farms; 69/69 broken)	gc pack materialization into <scope-root>/.<vendor>/skills/ sinks after gc start	pack-spec (docs.gascity.com/reference/specs/pack-spec.md); gc skill --help	gc skill list in blucity serves core.gc-* from the pack cache (~/.gc/cache/repos/<hash>/…/packs/core/skills/*/SKILL.md); the witness session's own skills are pack-materialized
Registries (.agents/registry.yaml skills/registry/v1.0.0; skill-index.yaml)	gc skill list inventory diagnostic; Portfolio Registry remains the architectural authority	gc skill --help	Same listing output, live
Bundles + lock (capability-index.yaml capability-index.v1; skills-lock.json source+hash; capability.bundle.zip)	Pack imports with durable source URLs + packs.lock pinning	pack-spec imports; understanding-packs ("durable sources… committed to version control")	gc import check → "Import state OK: 12 remote import(s) checked"; blucity packs.lock sha pins (tracked)
Compiler (src/compiler/capability-compiler.ts, skill-compiler.ts → compiled-skill.v1 per render target)	Pack loader + pack.toml schema (recursive import resolution, identity validation, deterministic lexicographic ordering, patch/overlay merging)	pack-spec "Loading Process"	blucity city loads 12 imported packs cleanly (import check above). NOTE: the business-graph "Platform Compiler" is a separate concern — bead iac-ozq — not retired by this row
Scheduling/procedures (src/procedures, order-like machinery)	Formulas / Orders	understanding-formulas; "plugins become orders" (coming-from-gascity)	mol-witness-patrol formula drives the auditing session itself; amcs pack ships 24 formulas / 15 orders
MCP skill server (scripts/bluefly-skills-mcp.mjs + .agents/config/mcp-skills.config.yaml)	gc materialization — provider tools read their sink directly; no server	gc skill --help materializer section	Session skills present with no skill MCP server running; repo's own STATUS.md marks the server obsolete
Discovery (src/discovery/duadp-publisher.ts / duadp-resolver.ts over bundles)	Pack imports via durable URLs; registry showcase for first-party discovery	understanding-packs (registry handles vs durable sources); guides/registry-showcase.md	Remote imports resolve from GitLab durable URLs (import check above)

Artifact 2 — Consumer Ledger

Capability/consumer	Consumer evidence	Migration status
blu-cli	package.json "@bluefly/capabilities": "file:../skills"; .gitlab-ci.yml clones release/v0.1.x as ../skills; src/commands/skills.ts imports compiler/registry/bundles/discovery and reads src/schema/skill-metadata.schema.json	BLOCKING GATE (Stage 4). Decide: blu skills wraps gc skill/gc doctor, or retires. Schema re-homes to api-schema-registry (contract authority)
.claude/skills (user level, mac-m4)	Verified NOT a consumer: contains only test-skill; zero symlinks into the repo; session skills provably come from the gc pack cache	None — no migration needed. (Claim from a prior thread disproven by direct inspection 2026-07-17)
blutown gt town	Rig agentictools_skills in rigs.json (bead prefix as); workspace dir is a 2-file stub	Work-routing only, no content load. Retires with town lifecycle (iac-zlp)
blucity / blucity-packs	Zero imports of this repo; packs self-carry skills (amcs/skills/*, seo-pack/.agents/skills/core.gc-*)	Already converged — the target pattern, working
iac / Oracle	Zero references in cloud-init.tftpl, runtime contract, or any .tf	None
OpenClaw	No live wiring; @openclaw/install-blu-skills.mjs self-declares "ARCHITECTURE VIOLATION" and is unused	None
Cursor/OpenCode/Goose/Kiro/Continue/adal/CodeBuddy/Kilocode sinks	69/69 symlinks broken; .opencode/config.json hardcodes a dead WORKING_DEMOs path	Dead — Stage 0 removal
Cosmetic references	blu-cli/src/bus/bus-doctor.ts path map, blu-cli/docs/AGENTS.md, ContextControl.ai/docs/CMS20_REPO_LAYOUT.md, dragonfly transcript noise	Doc cleanup alongside Stage 0/4
GitLab org-wide (beyond local workspace)	COMPLETE 2026-07-17 — GitLab group search (blueflyio): "@bluefly/capabilities" = 7 hits, all blu-cli (package.json + src/commands/skills.ts); "agentictools/skills" = 20 hits, all blu-cli CI clone / blutown rig registrations / blucity-docs+registry documentation references	Gate 1 CLOSED. blu-cli confirmed as the only code consumer org-wide. Stale doc/registry references (blucity-docs library+Research files, PRODUCT_SOD_REGISTRY.yaml "canonical reusable skill library" claims) update at Stage 5 archive

Upstream gaps

No upstream gaps have been identified during this investigation. If future migration uncovers functionality that PackV2 does not provide, that capability must be classified as exactly one of: an upstream contribution, a temporary compatibility layer, or a retained Bluefly-owned capability — recorded here with evidence.

Migration plan (approved shape)

• Stage 0a — Safe housekeeping (immediately executable, no migration narrative attached): .DS_Store files, empty directories (openai/), dead generated artifacts (.opencode/config.json dead path), adjudicate the 194 pending .agents/skills deletions, honest CI.
• Stage 0b — Architecture retirements (tied to the migration narrative; retire only after the relevant equivalence proof AND consumer checks are complete): broken symlink farms (69), registry files (.agents/registry.yaml, skill-index.yaml, capability-index.yaml, skills-lock.json), projection machinery, MCP skill server.
• Stage 1 — Dedupe: collapse @platform sink, @upstreams triplicate, @openai↔@figma/@notion/@tools overlaps.
• Stage 2 — Capability-first pack migrations, one bounded MR per pack (@drupal+@ddev→amcs; @openclaw→platform/openclaw; @ops→delivery/gitlab; @curly→foundation/governance; @data→platform/knowledge-dolt; @blu+@brand→platform pack), verified by gc skill list + gc doctor. Includes fixing the agent_defaults.scope deprecation warnings emitted by gc 1.3.2 across blucity and blucity-packs pack.tomls (observed 2026-07-17).
• Stage 3 — OSSA content → openstandardagents/platform-agents.
• Stage 4 — blu-cli decoupling, then retire src/ + index/lock formats.
• Stage 5 — archive the repository (provenance and migration history preserved — not deletion).

Execution gates (architecture board, 2026-07-17; statuses updated 2026-07-18)

1. GitLab-wide consumer verification — CLOSED 2026-07-17 (blu-cli sole code consumer; evidence in Consumer Ledger).
2. Long-term pack topology — DECIDED 2026-07-18 (operator): Option C, Hybrid. Default home: blucity-packs. Promotion rule: a pack leaves the catalog only when another repository is proven the smallest stable owner. One canonical catalog; mature products may own their packs later.
3. blu-cli replacement path — VALIDATED 2026-07-18: compile/bundle/publish retire (equivalence rows: materializer, pack imports, durable sources); validate splits — syntax→CI+gc lint, SKILL.md frontmatter→retained thin validator with schema re-homed to @bluefly/api-schema-registry (existing blu-cli dependency), capability.v1→retires with the format, OSSA manifests→OSSA tooling. Zero @bluefly/capabilities imports remain. Implementation = bead iac-wax.
4. Repository Unfrozen (added 2026-07-18) — required before Stage 4 and before any large-scale migration commits: ADRs committed; gitleaks gate passing (triage → rotate → baseline/narrow allowlists per Scratch/gitleaks-triage/TRIAGE-SUMMARY.md; history-rewrite decision recorded separately); governance documents landed; CI green. Discovered 2026-07-18: blucity-docs history carries 1,152 gitleaks findings (582 non-.md across 18 commits/159 files incl. runtime captures and embedded tokens) — the "blu secure scan" gate blocks ALL commits until remediated. No hook bypass, no immediate history rewrite.

Stage 0a proceeds with objectively safe items only (.DS_Store, empty dirs, dead generated caches, stale artifacts proven unused); the 194 pending .agents/skills deletions are excluded until the materialization equivalence proof completes — they sit on an active migration boundary. Stage 2 additionally requires operator confirmation of the namespace→pack mapping.

Consequences

• Bluefly ownership contracts to: pack content (business behavior), configuration, IaC, and the contracts schema — zero skills-platform machinery.
• Two repositories dissolve at end state: agentictools/skills (this ADR) and blutown (post GT→GC migration, iac-zlp).
• Future engineers find the "why" here: every retired subsystem has a verified upstream replacement with working evidence, and every consumer claim was proven or disproven by inspection.