Skip to main content

Init assistant CLI (eai-supinit)

PyPI package eai-supinit ships a contract-first greenfield assistant for new multi-repo / superbuild workspaces. Import package: eai_supinit.

It shares eai-supcore with eai-supmig so steady-state scaffolding (layout, tools/ai-rules, Cursor adapters) stays consistent. After init sign-off or migration completion, day-to-day handling of the multi-repo should feel the same.

Install​

pip install eai-supcore eai-supinit
# from this clone:
pip install -e packages/eai-supcore -e packages/eai-supinit

Commands​

CommandPurpose
eai-supinit assessInspect workspace; write .tools/esys/eai-supinit/workspace-contract.yaml
eai-supinit planWrite .tools/esys/eai-supinit/workspace-plan.md
eai-supinit bootstrapSteady-state dirs, consumer rails (hooks/gitignore/manifest/CHANGELOG.md), optional AI-rules + Cursor
eai-supinit extension / extList/add/status workspace extensions (e.g. cmake)
eai-supinit resetRemove journey artifacts (tools/ai-rules/ never deleted)
eai-supinit promptWrite prompts/01-scaffold-workspace.md (+ optional follow-up)
eai-supinit doctorValidate layout, rails, and init artifacts
eai-supinit workflowGates, deliverables, next milestone
eai-supinit workflow preferencesAuto-commit preference
eai-supinit workflow sign-offHuman approval that init is complete
eai-supinit workflow complete <gate>Manual gate mark (non-auto gates)

All commands accept --workspace PATH. Mutating commands support --auto-commit / --no-auto-commit.

Tool state vs steady-state​

PathGitRole
.tools/esys/eai-supinit/CommittedJourney tool state (contract, journal, workflow)
.tools_local/Not committedLocal installs (gitignored; reserved)
tools/ai-rules/Committed submoduleShared method / policy tree
src/, libs/, docs/adr/, AGENTS.mdCommittedSteady-state layout

Typical flow​

eai-supinit assess
eai-supinit plan
eai-supinit bootstrap --with-ai-rules --with-cursor --yes
python scripts/setup-dev.py
# optional when the multi-repo uses CMake:
eai-supinit extension add cmake
eai-supinit prompt
eai-supinit doctor
eai-supinit workflow sign-off

After bootstrap (fill before sign-off)​

Bootstrap already writes the governance pack. Humans (or the scaffold agent chat) should:

  1. Fill placeholders in root AGENTS.md and README.md (workspace name is pre-filled)
  2. Review docs/adr/0000-adopt-superbuild-workflow.md, set Status: Accepted, date, and deciders; pin the tools/ai-rules revision in ADR-0000 / .gitmodules / manifest
  3. Curate CHANGELOG.md [Unreleased] as release-relevant work starts
  4. Start a new agent chat with @prompts/01-scaffold-workspace.md after eai-supinit prompt

Bootstrap rails (defaults on)​

FlagDefaultEffect
--with-dev-hooks / --no-dev-hookson.pre-commit-config.yaml, .gitlint, scripts/setup-dev.py, expanded .gitignore
(always)—CHANGELOG.md, requirements-dev.txt, .gitattributes, .dockerignore, ADR pack, AGENTS.md, README.md
--with-esysrepo-manifest / --no-esysrepo-manifestonBasic .esysrepo.manifest.xml (includes tools/ai-rules)
--with-ai-rulesoffMount tools/ai-rules submodule; ADR-0000 uses submodule variant
--with-cursoroffMaterialize shared .cursor/rules/ + 90-<slug>-local.mdc overlay
--install-hooksoffRun scripts/setup-dev.py during bootstrap

Stack extras are not bootstrap flags — use extension / ext:

eai-supinit extension list
eai-supinit extension add cmake
eai-supinit extension licenses          # SPDX menu for license extension
eai-supinit extension add license       # interactive index (default: 1 = MIT)
eai-supinit extension add license -i 2  # Apache-2.0
eai-supinit ext status   # short alias

Applied extensions are recorded in .tools/esys/eai-supcore/extensions.yaml.

Version control​

Commit .tools/esys/eai-supinit/ and prompts/ at checkpoints. See CLI Commit checkpoint output. Do not hand-edit workflow-state.yaml.