RFC: Constructs Network — Install, Discovery & Schema Foundation

[zkSoju]

Intent & Purpose

Constructs are expertise in any form. The network is the environment where that expertise becomes discoverable, installable, and composable.

No construct is prescribed a form. A construct could be a skill pack, a codex, a product with its full build history, or something nobody's thought of yet. The network's job is to make these pieces findable and connectable — then step aside and let people play.

The maintainer of this network embodies Gecko — the ecosystem intelligence lens. Not watching from above, but walking the stalls, noticing patterns, feeding what's observed back into the system. This RFC comes from that walk: a full audit of all 24 live constructs, grounded in what actually exists, not what we imagined.

Everyone who encounters constructs will approach them differently. Some will find a construct through an app that was built with it. Some will browse the explorer. Some will see a one-liner on Twitter and paste it into their terminal. Some will arrive through Loa. The network must support all of these entry points without privileging any of them.

"It's just a game. There's many ways to play and no right way to play. We just provide an environment where evolution can happen."

---

Context

This RFC emerges from a deep session examining the constructs network DX from multiple perspectives — Gecko (ecosystem intelligence), KEEPER (user observation), OSTROM (structural architecture), and STAMETS (game design patterns) — grounded in a full bazaar audit of all 24 live constructs.

The constructs network has genuine depth: observer at v3.0.0 with 24 skills, k-hole as the reference Nakamoto implementation, artisan governing a 5-stall design lineage, 9 repos synced with 216 symlinks. But the surfaces that present these constructs to the world are fractured, and the schema foundation that would enable composition is incomplete.

Companion RFC: See loa#452 for first-class construct support in the Loa framework.

Origin: Conversation between @janitooor and @zkSoju about better tooling support when not on golden path rails, and first-class support for the constructs network.

Problem

Fractured Install Surface

Three install commands across four surfaces:

Surface	Command Shown	Audience
Homepage (rotating hero)	npx constructs install <slug>	Everyone
Detail page (InstallBlock)	/constructs install <slug>	Assumes Loa user
Install page (/install)	npx @loa-constructs/cli install observer	Reference docs
Stack Composer HUD	/constructs install <slugs>	Power users

A first-time visitor copies /constructs install observer from a detail page, pastes it into their terminal, and gets nothing. The command is a Loa slash command — meaningless without the framework.

Post-Install Activation Gap

After install, files land in .claude/constructs/packs/. Nothing validates they work. No "now try this" prompt. The gap between "installed" and "using" is where most users fall off. Compare: brew install jq → jq --version → confirmation. Our install has no confirmation moment.

Schema Foundation is Sparse

Bazaar audit of all 24 stalls reveals:

Metric	Finding
workflow.gates declared	3/24 (the-easel, vocabulary-bank, protocol)
quick_start field	19/24 (missing: the-easel, webgl-particles, mibera-codex, hypha, herald)
composition_paths	~3 stalls use them
Command name collisions	2: /observe (gecko vs observer), /dig (k-hole vs hypha)
No construct.yaml	1 (webgl-particles — still on manifest.json v1)
Significant identity drift	4: beacon (persona says SEO, skills do agent-commerce), dynamic-auth (draft persona), the-mint (crypto naming, asset pipeline delivery), gecko (persona ahead of skills)
Hard deps that should be optional	4: showcase↔k-hole, vfx-playbook↔k-hole, protocol↔observer/artisan, observer↔crucible
index.yaml schema gaps	2 (the-speakers, the-mint — no name/description, routing fails silently)

These gaps mean: the archetype resolver (Loa RFC) has almost nothing to resolve. Composition-as-navigation can't show material chains if stalls don't declare their read/write paths. The "skill tab" would show mostly islands.

Composability is Aspirational

Constructs should work like Unix tools — composable, pipeable, adversarial-reviewable. The maintainer already does this manually: naming TeamCreate agents by construct, piping dig findings into observer canvases, getting adversarial review from multiple construct perspectives. The usage pattern exists. The infrastructure to make it consistent doesn't.

The compose_with declarations across the network are mostly one-sided (6+ asymmetric claims). composition_paths are barely declared. Event chains are disconnected. The material connections that would make composition automatic are missing from the schema.

Design Principles

Principle 0: Environment for Evolution

The network doesn't prescribe compositions, workflows, or usage patterns. It provides pieces and surfaces connections. The user discovers their path through play. Every design decision should be tested against: "does this enable evolution, or does it prescribe form?"

Drawn from the Hotel Experience Paradox (Octalysis/Yu-kai Chou), game design research (RuneScape, Dark Souls, BOTW), and developer ecosystem analysis (skills.sh, lazy.nvim, Homebrew):

1. Agency over prescription — the install experience empowers, doesn't prescribe. Show options, honor the choice, step aside. (Hotel Paradox: "more personalization often means less connection")
2. Use before understand — RuneScape's Tutorial Island makes you mine before you know Mining exists. The install should produce immediate output, not just deposit files.
3. The skill tab, not the leaderboard — persistent ambient awareness of what you have and what's adjacent. Desire through proximity, not download counts. (RuneScape's skill tab is always visible, always honest, always personal)
4. Composition as material fact — "Observer reads what K-Hole writes" (filesystem path overlap) is more honest than "these compose well together" (social claim). Surface material chains, not declared affinities. (Dark Souls' shortcuts are revelations, not rewards)
5. The ecosystem should be felt before it's understood — not explained, not onboarded. Felt. The way you feel a RuneScape skill tab by having it always there. (BOTW's runes are discovered through use, not tutorials)
6. Package-as-Portfolio — constructs aren't just skill packs. They can contain products, build history, progression artifacts. The Factorio modder gets hired because the mod demonstrates systems thinking. A construct's showcase isn't decoration — it's evidence that the expertise works. (NeoForge/Docusaurus: documentation as the product)

Proposals

P1: Unify Install Command

One command everywhere: npx constructs install <slug>

• Detail page InstallBlock: change from /constructs install → npx constructs install
• Install page: consolidate to npx constructs install (retire @loa-constructs/cli reference if same binary)
• Stack composer: npx constructs install slug1 slug2 (multi-slug support)
• /constructs install continues to exist for Loa users but is secondary — shown as "With Loa Framework:" disclosure

This command should be tweetable. Every social post about a construct should include the one-liner. The install command IS the social artifact.

P2: Post-Install Activation

After install succeeds, CLI outputs:

✓ k-hole installed (6 skills, 5 commands)

  Try it:  /dig "your topic here"
  
  K-Hole goes where search engines won't.
  Seven voices in productive tension.

Generated from quick_start + description in construct.yaml. This is the concierge pointing to the pool — not the hotel pre-setting your room temperature. An offer, not an automation.

P3: Composition-as-Navigation on Explorer

Add a second edge type to the canvas graph — material chain — computed from composition_paths.reads/writes overlaps:

"Observer writes to grimoires/laboratory/. Herald reads from grimoires/laboratory/." → material chain edge.

On detail pages, "Adjacent constructs" section: "3 constructs write to paths this one reads from." Not recommendations. Material facts. This is the Dark Souls elevator — the moment you realize the world was connected all along.

"Built With" layer: When a construct's showcase links to a live app, show the trail — which constructs contributed, what artifacts they produced. This is the Package-as-Portfolio pattern: the construct's output IS the proof.

P4: Schema Hygiene Sprint (Foundation)

This unblocks everything else. The Loa RFC's construct index is only useful if stalls declare their fields.

Priority 1 — Must-have for Loa construct index:

Fix	Scope	Effort
Add workflow.gates to 21 stalls	Bulk PR across construct repos	Low
Add quick_start to 5 missing stalls	5 repos	Low
Add composition_paths declarations	All stalls that read/write grimoires/	Medium
Resolve command collisions	/observe (gecko→/network-health?), /dig (hypha→/pol-dig?)	Medium

Priority 2 — Should-have (quality, non-blocking):

Fix	Scope	Effort
Fix index.yaml schema (add name/description)	the-speakers, the-mint	Low
Create construct.yaml for webgl-particles	1 repo	Low
Fix domain misclassifications	crucible→testing, k-hole→research, webgl-particles/webreel→tooling	Low
Downgrade hard deps to optional	showcase, vfx-playbook, protocol, observer	Low

Priority 3 — Nice-to-have (identity quality):

Fix	Scope	Effort
Rewrite beacon persona.yaml	1 repo	Medium
Add vfx-playbook to artisan governance	2 repos	Low

P5: Adjacent-Possible on Detail Pages

When viewing a construct, show uninstalled constructs that connect through composition paths:

"K-Hole writes research findings that Observer can synthesize. [Install Observer →]"

Desire through proximity — the dark tile next to the lit one. The RuneScape skill tab shows what's adjacent to what you have, not just what you have.

Personal canvas ("My Network" view): The canvas should have a mode where installed constructs are highlighted, composition edges are drawn from your active set, and uninstalled-but-connected constructs glow as possibilities. The full 24-tile grid is the backdrop. Your constructs are lit. The dark tiles are desire. This is the skill tab made spatial.

P6: External Builder DX

The ecosystem is growing with external builders. Hypha (El Capitan) is the first. The bazaar audit found it uses construct.json (not construct.yaml), has no SKILL.md files, and its commands conflict with internal constructs.

• Document minimum viable construct.yaml for external builders
• Define command namespace collision resolution
• Publish verification pipeline criteria (UNVERIFIED → BACKTESTED → PROVEN)
• Ensure the construct-base template is discoverable and up to date

Sequencing

1. P4 (schema hygiene — priority 1) — populate the fields that unblock Loa's construct index
2. P1 (unified install) — fix the surface
3. P2 (post-install activation) — close the activation gap
4. P4 (schema hygiene — priority 2+3) — quality improvements
5. P3 + P5 (composition navigation + adjacent possible) — enable discovery
6. P6 (external builder DX) — enable ecosystem growth
7. Loa RFC L1 (construct index) becomes possible once P4 priority 1 is done

Out of Scope

• Loa-side changes (name resolution, archetype resolver, freestyle mode) → loa#452
• Construct certification / OSINT verification → separate initiative
• Leaderboard / ranking mechanics → deliberately deferred (souk, not mall)
• Prescribing construct form or content → constructs are expertise in any form the creator chooses

Bazaar Audit Reference

Full 24-stall audit findings (click to expand)

Tier 1 — Mature

• observer v3.0.0 — 24 skills, tooling scripts, composition wired
• k-hole v1.2.1 — reference Nakamoto protocol, 7 voices
• protocol v1.0.0 — 10 skills, detect-state script, conditional routing
• artisan v1.0.0 — 14 skills, governance root for 5 stalls

Tier 2 — Solid

• hardening — 11 skills, best counterfactual writing in network
• gtm-collective — 8 skills + 14 commands, most feature-complete
• the-arcade — 6 skills, OSTROM/BARTH, game design depth
• showcase — 6 skills, landing page intelligence
• the-easel — 4 skills, only design stall with workflow.gates
• vocabulary-bank — 2 skills, governance clean for 4 targets
• the-speakers — 8 skills, rich TANDY persona (index.yaml schema gap)
• the-mint — 8 skills, dual CELLINI/MURAGE (naming confusion)
• growthpages — 5 skills, real pipeline with HITL gate
• social-oracle — 5 skills, good filter architecture
• beacon — 6 skills, strong content (WRONG persona — SEO ghost from v1)
• vfx-playbook — 4 skills, practitioner-grounded
• webreel — 4 skills, real Playwright+FFmpeg tool

Tier 3 — Early/Incomplete

• crucible v1.0.0 — domain: security is WRONG (it's QA/testing)
• gecko v0.1.0 — persona far ahead of implementation
• herald v0.1.0 — no commands array registered
• dynamic-auth v1.0.0 — draft persona, complete island
• webgl-particles — 9 deep skills, NO construct.yaml
• hypha v0.2.0 — external, no SKILL.md files

Cross-Cluster Patterns

• Asymmetric compositions: gtm-collective→observer, growthpages→k-hole (neither reciprocated)
• Security cluster ungoverned: protocol, hardening, beacon, dynamic-auth have zero governance
• Undeclared pipeline: dynamic-auth → hardening → protocol (auth→audit→verify chain)
• Content pipeline: vocabulary-bank → growthpages → k-hole research (exists in intent, not schema)
• Vocabulary-bank governance: 4/4 governed constructs acknowledge back (previous reports of false claims were stale)

---

🤖 Generated with Claude Code

[zkSoju]

Addendum: Operator OS as Methodology, Not Feature

The network RFC should reflect that constructs support composability to a broader extent than any single workflow configuration.

Operator OS is a methodology for composing constructs into personal workflows — not a prescribed set of modes. The four modes (FEEL/ARCH/DIG/SHIP) referenced in this RFC are one user's personal configuration. Other users will compose constructs differently.

What this means for the network side:

1. Composition declarations matter more than we stated. If users are building personal operator OS configurations from constructs, the compose_with and composition_paths fields aren't just for the explorer graph — they're the building blocks of personal workflows. The schema hygiene sprint (P4) is even more critical.

2. The explorer should show composability, not prescribe compositions. The canvas shows edges. Users decide which compositions to activate. No "recommended stacks" or "popular pairings" — just material facts about what connects.

3. The "adjacent possible" (P5) is the invitation to evolve. When a user sees "3 constructs write to paths this one reads from," that's not a recommendation — it's a possibility. The user discovers their workflow by exploring adjacencies, not by following a guide.

"It's just a game. There's many ways to play and no right way to play. We just provide an environment where evolution can happen."

This is the design philosophy for both RFCs. The network provides the pieces. Loa provides the environment. The user provides the play.

[zkSoju]

Rigorous Feedback: What's Missing, What's Wrong, What Needs Sharpening

Reading this RFC against the full conversation that produced it — the construct council, the bazaar audit, the dig research, the hotel paradox, and the "build the sandbox" philosophy — several gaps and enrichments surface.

---

1. The RFC Doesn't Address External Builders

The ecosystem is growing with external builders. Hypha (El Capitan) is the first external construct. The bazaar audit found it uses construct.json (not construct.yaml), has no SKILL.md files, and its commands conflict with internal constructs (/dig).

The schema hygiene sprint (P4) is scoped to internal constructs. But the network's growth depends on external builders succeeding. Missing:

• External construct schema spec: What's the minimum viable construct.yaml for an external builder? The construct-base template exists but the audit shows hypha didn't use it.
• Conflict resolution protocol: When an external construct's command collides with an internal one, who wins? Namespace prefixing? User choice?
• Verification pipeline for external constructs: The dig research surfaced the ToxicSkills study — 13.4% of skills.sh ecosystem has vulnerabilities. As external builders grow, trust signals matter. The explorer already shows PROVEN/BACKTESTED/UNVERIFIED badges. How do external constructs earn verification?

Proposed addition — P6: External Builder DX

• Document minimum viable construct.yaml for external builders
• Define command namespace collision resolution
• Publish the verification pipeline criteria

2. The Social Distribution Strategy Is Missing

skills.sh succeeds partly because every Twitter post has a one-liner: npx skills add vercel-labs/agent-skills. The RFC unifies the install command but doesn't address how that command gets in front of people.

The user's progressive disclosure chain starts with "see an app built with constructs → follow the Loa mark → constructs.network." But there's a faster path that skills.sh proved: social posts with copy-paste install commands.

Missing:

• What does a tweet about a construct look like?
• Does the explorer generate shareable cards with the install command embedded?
• Should construct detail pages have social meta tags optimized for this?

This isn't a marketing question — it's a DX question. The install command IS the social artifact. If it's not tweetable, it's not distributable.

3. "Package-as-Portfolio" Pattern Not Captured

The dig research surfaced a significant pattern from game modding ecosystems: the package IS the portfolio. Factorio modders get hired at Wube because their mods demonstrate systems thinking. NeoForged treats mod APIs with enterprise documentation rigor. The documentation is as valuable as the territory.

The user explicitly said: "constructs could very well contain the product within it... the app within it is the weight of what matters in their ecosystem... not only is it a visual experience but the progression and expertise that was distilled into making it."

This is missing from the RFC. Constructs aren't just skill packs — they're living portfolios of expertise. The showcases on detail pages currently link to external apps. But the deeper vision is: the construct's grimoire artifacts, commit progression, and build history ARE the proof that the expertise works.

Proposed enrichment to P3 (Composition-as-Navigation):
Add a "Built With" layer to the explorer. When a construct's showcase links to a live app, show the trail: which constructs contributed, what artifacts they produced, what the progression looked like. This is the Factorio "Friday Facts" model — deep technical progression as discoverable content.

4. The Canvas Direction Needs Grounding

The RFC mentions the explorer canvas and composition edges but doesn't connect to the existing design direction. From memory:

• The canvas is a React Flow infinite canvas with category territories
• Constructs are 120×80px tiles with smoothstep edges
• Edge types: depends_on, composes_with, governs, connected_via

The dig research provided the RuneScape skill tab insight: the canvas should show YOUR constructs, not ALL constructs. The full 24-tile grid is the backdrop. Your installed constructs are lit. The dark tiles are what you could have. Desire through proximity.

The RFC's P3 (composition-as-navigation) and P5 (adjacent-possible) should reference this: the canvas IS the skill tab. But it needs to be personal — filtered by what you have installed — not just a network topology view.

Proposed enrichment to P5:
The "adjacent possible" isn't just a section on detail pages. It's a mode of the canvas: "My Network" view where installed constructs are highlighted, composition edges are drawn from your active set, and uninstalled-but-connected constructs glow as possibilities. The personal canvas is the skill tab made spatial.

5. The Standalone vs. Framework Cycle

The dig research surfaced the "Cyclicality of Abstraction" from the Neovim ecosystem: communities oscillate between frameworks (LazyVim) and standalone templates (kickstart.nvim). Neither wins permanently. The cycle IS the pattern.

The RFC treats standalone (npx constructs install) and framework (/constructs install) as two tiers. But the research says they're two phases of the same cycle. Some users will start standalone and move to Loa. Some will start with Loa and eject to standalone. Some will oscillate.

What's missing: An eject path. If a Loa user wants to use constructs without Loa, is that clean? If a standalone user decides to adopt Loa, do their existing construct installations carry over? The RFC should address bidirectional migration, not just progressive disclosure in one direction.

6. P4 (Schema Hygiene) Needs Priority Ordering

P4 lists 10 fixes with "Low/Medium" effort but no priority order. Given that the Loa RFC's keystone (construct index) depends on P4, the priority should be:

Must-have for L1 (construct index):

1. Add workflow.gates to 21 stalls
2. Add quick_start to 5 stalls
3. Add composition_paths declarations
4. Resolve command name collisions

Should-have (improve quality but don't block L1):
5. Fix index.yaml schema (the-speakers, the-mint)
6. Create construct.yaml for webgl-particles
7. Fix domain misclassifications
8. Downgrade hard deps to optional

Nice-to-have (identity quality):
9. Rewrite beacon persona.yaml
10. Add vfx-playbook to artisan governance

7. The "Environment Where Evolution Happens"

The RFC's design principles are good but miss the deepest one from the conversation:

"It's just a game. There's many ways to play and no right way to play. We just provide an environment where evolution can happen."

This should be Principle 0 — the meta-principle that governs all others. The network doesn't prescribe compositions, workflows, or usage patterns. It provides pieces and surfaces connections. The user discovers their path through play.

This affects P5 specifically: the "adjacent possible" should never feel like a recommendation engine. It should feel like the castle on the mountain in Dark Souls — visible from the starting area, reachable when you're ready, meaningful because you chose to go there.

---

Summary of Proposed Changes

Addition	Where	Impact
P6: External Builder DX	New proposal	Unblocks ecosystem growth
Social distribution strategy	Enrichment to P1/P2	Unblocks adoption
Package-as-Portfolio / "Built With"	Enrichment to P3	Deepens explorer value
Personal canvas ("My Network" view)	Enrichment to P5	Makes skill tab spatial
Bidirectional migration (standalone ↔ framework)	Enrichment to P1	Supports the cycle
Priority ordering for P4	Restructure P4	Unblocks Loa RFC sequencing
Principle 0: environment for evolution	Design principles	Grounds all decisions

[zkSoju]

Dependency Chain — Issues #182, #183, #184

These four issues are facets of the same gap: constructs are files in a directory, not a runtime system.

Issue	Layer	Resolves when...
#181 (this)	Distribution	Constructs have identity, schema, install, discovery
#182	Communication	Signal pipeline has a contract constructs can rely on
#183	Lifecycle	Operator OS modes can evolve via construct metadata
#184	Runtime	Spawned agents inherit construct context (SKILL.md, rules)

#181 is the foundation. If the network gives constructs composable identity + schema, then:

• Signal pipeline consistency: document contract, fix mobile gap, clean phantom deps #182's signal contract falls out of the schema definition
• feat: /evolve-os — Operator OS discovery and evolution skill #183's evolution skill can query construct metadata programmatically
• Spawned agents don't inherit construct context — SKILL.md / rules invisible to teammates #184's agent inheritance can load construct context from the registry at spawn time

Suggest treating #181 as the trunk and #182-184 as branches that validate the RFC against real failure modes.