Nexus Setup CLI

[sameera]

Epic: Nexus Setup CLI

Description

Getting Nexus into a repo — single or multi — is structural work that happens before a Claude
session has anything to run. Today it is a manual shell step (nxs.update.claude.sh), and for a
multi-repo product there is a further act no single-repo command can perform: deciding which
checkout is the hub and which are members, authoring the hub manifest, stamping each member's hub
pointer, and distributing .claude/ across sibling checkouts. A command confined to one repo's cwd
has no vantage point from which to do that.

This epic gives the structural half a single home: a deterministic, portable nexus CLI. Its
foundation is one component-deploy primitive — copy the Nexus components (slash commands, agents,
skills, the rest of .claude/) into a repo — exposed directly as nexus deploy for the single-repo
case and reused by nexus workspace init to fan out across every checkout. On top of that primitive
the CLI declares a workspace, adds a member later, and reports status. It runs on a bare
Node runtime with no in-repo tooling installed — it ships on the portable distributable already built
for the concept validator and atlas generator (portable-tooling, epic #44) —
so it can bootstrap a repo before that repo is scaffolded. The manual nxs.update.claude.sh script
is retired; nexus deploy replaces it.

Everything the CLI writes for a workspace is exactly what the one deterministic resolver
(workspace-resolution, epic #38) already reads; the CLI is the writer
for the manifest and pointer artifacts the resolver owns on the read side, never a second definition
of workspace shape.

This draws a clean seam through Nexus setup: the CLI owns structure and deployment — getting
components in place, whether into one repo or a whole workspace — and /nxs.setup owns judgment —
stack docs, standards, the product-context interview, run inside each repo once its components are
present. /nxs.setup is re-scoped accordingly: it detects an existing hub pointer or manifest through
the resolver and skips any placement prompt. Single-repo projects stay simple — nexus deploy then
/nxs.setup, with no manifest or pointer ever written.

Scope note: this epic covers the Claude agent surface only. Support for other agents (e.g. Gemini)
is out of scope, and their update scripts are not addressed here.

Success Metrics

• Getting Nexus into a fresh single repo is one nexus deploy invocation (replacing the removed
  nxs.update.claude.sh step), after which /nxs.setup runs — the legacy Claude update script no
  longer exists in the distribution.
• Declaring a new N-repo workspace (one hub + N−1 members) is a single nexus workspace init
  invocation whose output the existing workspace resolver accepts with zero follow-up edits —
  resolution from the hub and from every member yields the identical workspace description (the
  resolver parity guarantee).
• Adding one member to an existing workspace mutates exactly two files: the hub manifest and the
  new member's pointer — no third file in any repo changes.
• Every CLI verb runs to completion on a checkout with no in-repo Node tooling installed (bare
  runtime, no install step).
• After the CLI has placed a repo, a /nxs.setup run in that repo issues no hub/member placement
  prompt and creates or modifies no manifest or pointer file.

Personas

Per docs/product/context.md, with one addition specific to this epic:

• Team lead standing up a Nexus product — deploys the components into a single repo, or makes the
  hub/member placement decision once and runs the CLI to make it real across every checkout, then
  hands each repo to /nxs.setup for its own per-repo judgment pass.

Assumptions

• The component-deploy primitive introduced in Story 1 is the single distribution mechanism for
  Nexus Claude components; the legacy nxs.update.claude.sh script is removed rather than kept as a
  parallel path. The exact copy implementation (what the primitive treats as the component source of
  truth) is an HLD decision, but it produces the same component set the old script installed.
• The manifest/pointer writer this epic introduces is the counterpart to the epic Workspace Manifest & Resolution #38 resolver
  (the reader). The resolver stays the single authority on workspace shape; the CLI writes artifacts
  in that shape and never re-derives or re-defines it.
• Ongoing, idempotent hub-pointer stamping on repeat component updates, the per-engineer self-gating
  scratch-capture hook, and a one-time engineer installer remain a separate concern from this
  epic's one-time deploy/declare/add CLI — they stay with the engineer-install backlog stub (still
  proposed), not folded in here.

Out of Scope

• Non-Claude agent support. This epic covers the Claude component surface only; Gemini (and any
  other agent) deployment and their update scripts are untouched.
• Manifest-skeleton auto-generation — the CLI proposing which sibling is the hub and which are
  members, versus listing the discovered siblings for the user to designate. Deferred: it pushes
  against the workspace-manifest epic's (Workspace Manifest & Resolution #38) deliberate "no manifest-generation tooling" posture and
  would push Story 2 past M. Re-triage under the workspace-setup-cli stub if picked up later.
• The engineer-install stub's self-gating scratch-capture hook, one-time engineer installer, and
  update-script hub-pointer extension (docs/features/multi-repo-workspaces/backlog.md) — separate,
  not-yet-promoted scope.
• Cross-repo range recording for epics implemented across multiple member repos — tracked under the
  cross-repo-range-recording backlog stub.

Open Questions

None.

[sameera]

Close Record

Epic closed. Durable record below — the queue close-record.md drains post-merge.

Key Decisions

• Component payload fingerprint pinned as a claude-components key in the existing bundle-fingerprint.json: implements the decision record's "extend the existing parity/fingerprint gate" mitigation; one pin file keeps vendor, pin, and test in single-headed lockstep. (Refuted: a separate component-fingerprint.json, which forks the pin discipline into two files.)
• Mirror deletion in the deploy primitive is scoped to the nxs./nxs- namespace: convergence needs retired managed files deleted, but "don't clobber user files" needs an enforceable ownership boundary — the nxs namespace is exactly the set the retired update script owned. (Refuted: deleting any non-payload file under the three subtrees, which destroys user-authored commands/skills.)
• The member-vs-hub collision rule was added inside the resolver's parseAndValidateManifest, not the CLI: the resolver previously only compared members pairwise; the shape authority must own the rule so read and write sides can't diverge (invariant 2). (Refuted: a CLI-side pre-check, which creates a second copy of collision logic.)

Deviation Rationale

• The shared bundler (buildBundle) was changed to emit a createRequire banner for all bundles — beyond "add a new entrypoint": without it, any bundle inlining a CommonJS dep (yaml) dies on a bare runtime with "Dynamic require of 'process' is not supported." The fix belongs in the shared bundler because the defect was already latent in the shipped derive-entry-diff.mjs; per-entry externals or a CJS switch would change the distributable's shape for every consumer instead of fixing the one interop gap. The banner is inert for bundles that don't inline CJS deps.

Pointers (durable)

• Deferred scope → docs/features/multi-repo-workspaces/backlog.md
• Process lesson → docs/delivery/lessons/2026-07-16-nexus-setup-cli.md