Placeholder: `scaffold` subcommand for the bunx CLI

[diegohb]

Summary

bunx opencode-architect scaffold — a deterministic, code-based scaffolder that replaces the packager agent's mechanical file generation. Two modes: fresh (interactive questions → deploy a conformant package tree from the bundled templates) and promote (take existing .opencode/ extensions into a package, ensure the config reference, retire the source).

Motivation

Field evidence (two packaged runs, Oct 2026): an assets-only package with 1–3 simple skills took ~20 minutes of agentic file generation, and every deviation found in review (monolith plugin.ts, hand-rolled badge rows, missed .opencode/ residue) happened in exactly this mechanical scaffolding phase. Templates-as-prose is weak enforcement; code is strong enforcement. LLM work should be reserved for content authoring and judgment calls (merge decisions, plugin-engineer routing).

Modes

1. Fresh

Question set (interactive; every answer overridable by flag for AFK/agent use):

Question	Flag	Default
Package name (opencode-<name>)	--name	required
Deployment target: this workspace root or sibling	--target here|sibling	here
What it ships: skills / commands / agents / tools / plugins	--ship <list>	skills
Scope name for installs	derived	local

2. Promote

--promote <path> (default: scan cwd for .opencode/): detects existing extensions and runs the packager's promote flow mechanically:

1. Establish repo root (git rev-parse --show-toplevel, never .opencode/).
2. Deployment-target choice (this workspace default; sibling on --target sibling or when root package.json/plugin.ts merge is extensive — merge requires user consent per item).
3. Copy content into package-root directories (skills/, commands/, agents/, plugins/, tools/ — no assets/ wrapper).
4. Ensure the config reference (plugin entry or skills.paths) via the surgical editor; abort retirement if none can be established.
5. Run install, verify the payload on disk (manifest + files match).
6. Print the removal list; on explicit consent (--yes for non-interactive), delete promoted originals plus source package.json/lockfile/node_modules. End state: .opencode/ holds only the config plus hook-managed payload and manifests.

Template mapping

The command reads the suite's bundled assets/templates/* as the single source of truth (no duplicated templates): index.template.txt, plugin-local.template.txt → plugin.ts, plugin-name/manifest/registration/plugin-config/installer/cli templates → src/*.ts, package-basics.template.json/package-full.template.json → package.json (bin → src/cli.ts, files derived from shipped dirs, content declaration derived from inventory), tsconfig.template.json, skill-structure.template.md. Badge row emitted byte-for-byte (single line, D7 markup). Frontmatter for any content the command writes is double-quoted (D6).

Non-goals

• Authoring skill/command/agent content (skill-creator/command-crafter/agent-designer stay).
• Publishing (publisher agent and its package.json expansion stay).
• Custom plugin/tool merge decisions (still routed to plugin-engineer; scaffold copies then hands off).

Acceptance criteria

• scaffold (fresh, interactive and flag-driven) produces the full suite-conformant tree — the packager's self-audit inventory — in seconds, no LLM involved
• --promote on a fixture workspace with N skills yields: package at repo root, config reference present, payload verified, source retired to the exact end state (config + hook-managed files only)
• Content declaration derived automatically; code-backed packages refuse --mode copy (existing template behavior preserved)
• Retirement is consent-gated; a missing config reference aborts retirement with the source left in place
• Tests cover: fresh-tree inventory snapshot, promote flow, consent gate, no-reference abort, end-state check
• Packager agent instructions updated: mechanical scaffolding delegates to the CLI; the agent keeps content authoring, merge decisions, and judgment (self-audit gate remains as the agent-side verification)

Out of scope (follow-ups)

• migrate/clear-cache interplay with promoted scopes (reuse existing CLI behavior unchanged)
• Windows path/URI normalization for emitted file:/// snippets beyond what the templates already encode

[diegohb]

Spec drafted (replacing the placeholder) from the 0.8.0 grilling decisions: root-layout packages, deployment-target choice, D9 retirement end state, self-audit inventory as code. Key scope addition vs the placeholder: a --promote mode so the 20-minute agentic scaffolding path becomes a deterministic CLI invocation; the agent keeps content authoring and merge decisions.