Skip to main content

​
SPEC-112 v0.3 — Client and Contributor Scaffold Boundary

Status: accepted (Frank ratified 2026-05-13 via Cherry → Donna → Texi relay). Owner / Author: Texi (architecture), Donna (engineering / Plan #18 integration). Related: SPEC-113 v0.3 (sibling — runtime template resolution + scaffold completeness), ADR-030 (consumer-grade install authority), SPEC-053 (Node CLI bootstrap/update), SPEC-084 (editor-host install), SPEC-089 (cloud customer onboarding/auth), Plan #16 Workstream H (.agent/ persona config).

​
Origin

Frank via Cherry to Donna, relayed to Texi 2026-05-13. v0.3 corrects the v0.2 architectural miss: PRISM.md is not a customer/project scaffold artifact. Prism installs once at $PRISM_ROOT; Ring 2 methodology is owned by Prism under $PRISM_ROOT/templates/ and read at runtime. Scaffold/adopt writes only the thin Prism edge into $PROJECT_ROOT, not copied Ring 2 methodology.

​
Canonical Terms

$PRISM_ROOT is the Prism install directory. It is a single instance per host, immutable to non-contributors, and owns methodology at $PRISM_ROOT/templates/: prism-base.md, ptype overlays, and the content that historically composed PRISM.md. Agents read methodology from $PRISM_ROOT/templates/ at runtime; it is never copied into ordinary project roots. $PROJECT_ROOT is the customer project directory. It is mutable customer space. It gets only the thin edge: CLAUDE.md and/or AGENTS.md Ring 1 replicas, .prism/, and .agent/ dotfile dirs when contributor mode is explicitly selected. It gets no root PRISM.md.

​
Corrected Architecture

Prism owns the upper methodology rings immutably at $PRISM_ROOT:
  • Ring 1 BIOS SOR: $PRISM_ROOT/templates/AGENTS.md, $PRISM_ROOT/templates/CLAUDE.md.
  • Ring 2 methodology SOR: $PRISM_ROOT/templates/prism-base.md plus ptype/profile overlays such as $PRISM_ROOT/templates/prism-application.md.
Agents read Ring 2 methodology at runtime from $PRISM_ROOT/templates/; scaffold/adopt does not copy or compose PRISM.md into $PROJECT_ROOT. Customer project directories contain only project-owned state and lower overlays:
  • $PROJECT_ROOT/.prism/ project metadata and Prism-managed local state.
  • $PROJECT_ROOT/.agent/ contributor/agent-contract config only when contributor mode is explicitly selected.
  • $PROJECT_ROOT/AGENTS.md and/or $PROJECT_ROOT/CLAUDE.md Ring 1 editor bootstrap replicas where needed by editor surfaces.

​
Special Case: Prism Repo Itself

On a contributor machine working on Prism itself, $PRISM_ROOT and $PROJECT_ROOT resolve to the same path. That is why PRISM.md exists at the Prism repo root: the repo is both product/install root and customer project for Prism development. This is a single-machine special case, not the general rule. Customer/client projects must not receive root PRISM.md replicas.

​
Prior Art Assessment

Prior art exists but was incomplete:
  • ADR-030 and SPEC-053 define consumer-grade install authority and Node CLI bootstrap/update.
  • SPEC-084 defines editor-host install.
  • SPEC-089 defines cloud customer onboarding/auth.
  • Plan #16 Workstream H defines .agent/ persona config for contributor/development projects.
  • SPEC-113 v0.3 defines runtime template resolution and scaffold completeness without PRISM.md replicas.

​
Decision

Introduce two scaffold/install modes:
  1. client mode — default for customer/user installs and ordinary Prism-tracked customer projects.
  2. contributor mode — explicit opt-in for Prism development/cohort machines and agent-mesh operation.
The default is client. Contributor artifacts cross into $PROJECT_ROOT only when explicitly requested or when $PROJECT_ROOT == $PRISM_ROOT for the Prism repo special case.

​
Client Mode Boundary

Client/customer mode may install or scaffold into $PROJECT_ROOT:
  • AGENTS.md and/or CLAUDE.md Ring 1 replicas as required by active editor surfaces.
  • .prism/ dotfile directory for project binding, ptype/profile metadata, local state, and repair/sync metadata.
  • Minimal project metadata required for Prism verbs and ordinary editor MCP use.
  • Editor MCP config and API credentials required to connect to the backend.
  • prism CLI and coder launcher only as user-facing entrypoints, without mesh-launch defaults.
  • Project docs generated by the selected client-safe project template.
Client/customer mode must not install/scaffold into $PROJECT_ROOT by default:
  • PRISM.md in the project root.
  • .agent/ persona contracts, role templates, project bindings, or launch.local.
  • agent-roster.psv or seed/export roster files.
  • start-all.sh, start-all.ps1, or mesh-launch scripts in the client project.
  • Prism repo source trees, backend source, dashboard source, test harnesses, smoke scripts, or internal governance/install lane docs.
  • Contributor-only hooks, release-cut tools, or agent cohort defaults.

​
Contributor Mode Boundary

Contributor mode may install/scaffold into $PROJECT_ROOT:
  • Full .agent/ config for the project/cohort.
  • Persona roles/bindings/launch.local.
  • Roster seed/export artifacts as compatibility files.
  • start-all launchers and validation tools.
  • Development docs/spec references, smoke scripts, and repo source as appropriate for a Prism contributor checkout.
  • Contributor/developer ptype/profile metadata in .prism/ so runtime template resolution reads the right $PRISM_ROOT/templates/ overlay.
Contributor mode still does not copy PRISM.md into arbitrary project roots. The Prism repo itself is the only legitimate root-PRISM.md carve-out.

​
Runtime Methodology Contract

PRISM.md has no standalone $PRISM_ROOT/templates/PRISM.md source file. Ring 2 methodology is runtime-composed by reading:
  • $PRISM_ROOT/templates/prism-base.md, and
  • the selected ptype/profile overlay under $PRISM_ROOT/templates/.
Composition rules:
  • Base is always prism-base.md.
  • Overlay/profile is selected from install/project metadata, typically recorded under $PROJECT_ROOT/.prism/ and/or backend project metadata.
  • Client default must not select a Prism-product/developer overlay if that overlay contains product-specific implementation rules inappropriate for the target project.
  • If no suitable overlay exists, bootstrap/scaffold repair fails closed as template_not_found_at_prism_root, prism_root_misconfigured, or template_resolution_failed; it must not write a misleading local PRISM.md.

​
Interface Contract

prism_create, prism_adopt, and install flows gain a scaffold profile parameter or equivalent:
  • scaffold_profile='client' default.
  • scaffold_profile='contributor' explicit.
They also persist enough project metadata for runtime template resolution:
  • ptype
  • scaffold_profile
  • selected overlay id/path or version reference
Existing dev flows may infer contributor mode only when $PROJECT_ROOT == $PRISM_ROOT for the Prism repo or an existing .agent/ tree is present and explicitly accepted. New customer projects do not infer contributor mode from local environment alone.

​
Failure Mode Names

  • contributor_surface_leak: client/customer scaffold includes contributor-only artifacts.
  • client_runtime_under_scaffolded: client/customer scaffold lacks files/dotfile metadata required for ordinary Prism use.
  • profile_ambiguity: scaffolder cannot determine intended profile; fail closed to client and surface ambiguity.
  • template_not_found_at_prism_root: $PRISM_ROOT/templates/ lacks required base or overlay template.
  • prism_root_misconfigured: runtime cannot locate or trust $PRISM_ROOT as the Prism install directory.
  • template_resolution_failed: runtime cannot resolve a valid base + overlay for the project ptype/profile.
  • misprofiled_template_overlay: client/customer project resolves contributor/product-specific Ring 2 methodology.
Removed failure mode:
  • missing_prism_replica is invalid because PRISM.md is not a project replica.

​
Acceptance Criteria

  • Default prism_create for a customer project produces no root PRISM.md, no .agent/, no agent-roster.psv, and no start-all launchers in $PROJECT_ROOT.
  • Default client scaffold records ptype/profile metadata sufficient for runtime template resolution from $PRISM_ROOT/templates/.
  • Client runtime Ring 2 methodology is client-safe and excludes Prism-product-specific application overlay content unless explicitly selected by ptype/profile.
  • Contributor mode produces .agent/, launch.local, role/persona config, and launcher compatibility artifacts, but does not copy PRISM.md except for the Prism repo special case.
  • Missing template/overlay fails visibly as template_not_found_at_prism_root, prism_root_misconfigured, or template_resolution_failed.
  • prism_adopt defaults to client mode unless existing contributor artifacts are present and explicitly accepted.
  • Install docs and CLI help describe client vs contributor mode.
  • Smoke tests assert no client-mode contributor artifact leak and no root PRISM.md in customer projects.

​
Non-Goals

  • Designing the hosted customer Tenant Console.
  • Changing WorkOS/human auth semantics.
  • Removing PRISM.md from the Prism repo itself.
  • Making .agent/ a local memory store; it remains committed config only in contributor mode.
Last modified on May 18, 2026