Reconsider flat delivery as the fresh-install default

[ihabadham]

Problem

Fresh install-agent-workflows installations default to flat, even though Agent Workflows now ships native Codex and Claude plugins and recommends one auto-invocable delivery route per host/profile.

The history establishes a reason for interpreting legacy metadata as flat, but does not record a separate decision for why a fresh installation should continue choosing flat:

• Commit 5d60b8d introduced the host installer before native plugin delivery existed. Copying or symlinking skills into <target>/skills was therefore the installer's original and only behavior.
• PR Publish Agent Workflows under the scw native-plugin namespace #135 added the native scw plugin while deliberately preserving the existing flat installer.
• Issue Follow-up: Migrate flat installs without duplicate auto-invocable Agent Workflows skills #131 / PR Add plugin companion delivery mode #136 added flat and plugin-companion. Their explicit compatibility decision was that metadata predating delivery_mode is interpreted as flat.
• Issue Follow-up: Migrate flat installs without duplicate auto-invocable Agent Workflows skills #131 also required that deliberate flat installation remain supported, but neither the issue nor PR decision log explains why a brand-new installation with no prior state should prefer flat delivery.

The likely explanation is compatibility with the historical no-flag command: install-agent-workflows --host ... still succeeds without requiring a native plugin to be installed first. That is a reasonable inference, but it is not currently an explicit product decision.

Why reconsider it

Codex documents user and repository skill directories as authoring/local-discovery locations, and recommends plugins when distributing reusable skills beyond one repository or when bundling skills with other capabilities:

https://developers.openai.com/codex/skills/

That does not make flat installation invalid. For Agent Workflows specifically, however:

• this is a centrally maintained multi-skill source pack rather than a few personal skills;
• native scw plugins already exist for both supported hosts;
• plugin namespaces avoid collisions with unrelated personal or repository skills;
• plugin installation gives the host ownership of provider identity and updates;
• maintaining flat and native paths already required the collision/migration machinery in Follow-up: Migrate flat installs without duplicate auto-invocable Agent Workflows skills #131 and exposed the unrelated-skill failure in Plugin-companion install rejects unrelated existing skills #191.

This is therefore more than aesthetic preference, but it is also not enough evidence to blindly change the default to plugin-companion: companion mode currently requires an already installed and enabled native plugin, so changing the default without a bootstrap or detection design could make first-time installation worse.

Decision to make

Choose and document the intended fresh-install policy separately from legacy migration policy. Evaluate at least:

1. Keep the generic installer default flat, but make ShakaCode/full-stack setup explicitly native-plugin-first plus plugin-companion.
2. Detect an active native plugin and select companion automatically; otherwise retain flat with precise guidance.
3. Add a native-plugin bootstrap mode that installs/enables scw, then installs companion assets, allowing native delivery to become the fresh default.
4. Require an explicit delivery mode for fresh installs while continuing to replay recorded state for upgrades.

Whichever policy wins, deliberate flat installation must remain supported unless separately deprecated, and metadata predating delivery_mode must continue to resolve safely as flat.

Acceptance criteria

• The fresh-install default is an explicit documented decision, not an accidental continuation of pre-plugin behavior.
• Legacy metadata behavior is considered independently and remains backward compatible.
• A clean Codex and Claude home has a clear first-install path.
• Native-plugin-present, native-plugin-absent, existing-flat, and existing-companion cases are covered.
• Unrelated personal skills are preserved.
• Exactly one auto-invocable Agent Workflows skill surface remains active.
• Installer, status, upgrade, and agent-stack documentation agree on the result.

Process gap disposition

• Mechanism target: script + documented product decision
• Motivating miss: the legacy-state compatibility decision also became the fresh-install default without a separately recorded rationale after native plugin delivery was introduced.
• Replay evidence: original installer commit 5d60b8d, native plugin PR Publish Agent Workflows under the scw native-plugin namespace #135, delivery-mode issue Follow-up: Migrate flat installs without duplicate auto-invocable Agent Workflows skills #131 / PR Add plugin companion delivery mode #136, and unrelated-skill issue Plugin-companion install rejects unrelated existing skills #191.
• Non-goal: removing deliberate flat installs or changing legacy metadata interpretation as part of the decision alone.

[ihabadham]

Decision

Three independent fresh-context architecture reviews converged on the same policy. This issue remains open for implementation, but the product decision is:

Generic installer: adaptive compatibility default

When --delivery-mode is omitted:

1. An explicit mode always wins.
2. Existing valid metadata replays its recorded concrete mode.
3. Legacy metadata without delivery_mode remains flat.
4. With no existing metadata:
   • a proven active native scw plugin resolves to plugin-companion;
   • a proven inactive/absent native plugin resolves to flat, with native-plugin guidance;
   • unknown, malformed, conflicting, or legacy-plugin state fails closed.
5. Persist only the resolved concrete mode, never auto.

Native scw + companion should be documented as preferred on plugin-capable Codex CLI/Desktop and Claude Code. Flat remains supported for Codex IDE, offline/restricted/older hosts, deliberate unqualified installs, and compatibility.

This removes the current unnecessary failure where an already-active native plugin plus an omitted mode selects flat and then reports a collision, without reinterpreting any existing installation.

ShakaCode agent-stack: native-first

agent-stack is an opinionated, networked ShakaCode setup layer and should ultimately establish native plugin state deliberately, then use plugin-companion by default. It should either bootstrap and prove scw, or stop with exact host-specific setup guidance. Explicit flat remains an opt-out for unsupported/headless profiles.

Do not silently fall back to flat in the final ShakaCode contract merely because a machine had not yet installed the plugin.

Required prerequisites

Do not switch automated defaults until:

• Plugin-companion install rejects unrelated existing skills #191 lands so unrelated personal skills do not block fresh/already-companion installs;
• host/profile-specific native plugin bootstrap or preflight is reliable;
• partial-failure ownership between host plugin installation and companion installation is defined;
• native skill and companion helper revisions are bound or compatibility-attested;
• update/reload behavior is covered for Codex and Claude;
• active/absent/disabled/unknown, legacy metadata, explicit overrides, migrations, and unrelated skills have regression coverage.

Consumer contract for ShakaCode repositories

Consumer repositories should not silently combine current plugin instructions with older repo-pinned workflows/helpers. One operation selects one provider revision.

Normal mode uses a fresh rolling provider resolved once to an exact SHA. Checkout-only environments may use an explicit coherent fallback/cache, but it must:

• identify itself and its exact revision;
• remain outside skill-picker discovery;
• provide workflows and helpers as one all-or-nothing bundle;
• never mix with installed provider files;
• report stale/unknown freshness honestly;
• refuse merge, release, hosted-CI authorization, claim ownership, and final-readiness mutations unless current-provider freshness is proven.

Prefer a thin checkout bootstrap that resolves/caches the current provider at one exact SHA over committed scattered helper/workflow copies. Truly offline ordinary local/read-only work may use a last-known coherent cache; high-consequence workflow mutations fail closed.

Alternatives rejected

• Universal flat forever: compatible, but wrong as the preferred distribution policy for a centrally maintained multi-skill package with native plugin delivery.
• Universal companion immediately: clean homes fail because companion does not install the plugin; plugin support is not universal; current prerequisites are incomplete.
• Detection-only for ShakaCode: makes organizational architecture depend on accidental pre-existing machine state.
• Mandatory explicit choice for every generic fresh install: breaks the historical unattended no-flag path without solving plugin bootstrap.
• Silent per-file fallback chains: allow current instructions, stale workflows, and whichever helper happens to exist to form an untested mixed provider.

The governing distinction is: legacy compatibility determines how existing state is replayed; it does not determine the preferred architecture for a new ShakaCode setup.