Environment lifecycle formalization — bind verb, creation skill, command wiring, project/migration integration

[jeonghun-jj-lee]

Important

Problem — Research environments have no guided creation flow and no UI entry points. Creating one requires a terminal (amico env create), binding a project requires hand-editing research-project.toml, and the three VS Code commands declared in package.json (newEnvironment, bindToEnvironment, promoteToEnvironment) have no registered handlers. A researcher who doesn't know the CLI can't use environments at all.

Approach — Wire the full environment lifecycle: a create-research-environment skill (6-stage interview), an amico env bind CLI verb (so nobody hand-edits TOML), handlers for the three dead VS Code commands, and an environment binding stage in both the create-research-project and migrate-research-project skills. The primary entry point is project creation — the environment skill is chained from there in a separate session tab. Command Palette is the secondary entry point; no sidebar button.

Scope — in: bind verb, environment creation skill, command handlers, project/migration skill updates. out: sidebar "+ New Environment" button (Command Palette suffices), environment deletion/archival, remote push automation.

Acceptance Criteria

• amico env bind <slug> [--path <dir>] [--env-path <abs>] [--force] writes [environment] section to research-project.toml
• Initial bind uses string append (preserves existing file content and comments); update (changing slug with --force) uses full parse→re-render
• Bind is idempotent on same slug; refuses different slug without --force
• Bind warns (but allows) when slug is not in the registry
• create-research-environment skill runs a 6-stage interview: name, system/domain (free text), research field, description, tags, optional GitHub remote
• Skill runs amico env create with collected flags, then git remote add origin if remote was provided
• Standalone post-creation: skill scans workspace for unbound research projects and offers multi-select binding via amico env bind
• Chained post-creation (from project skill): skill binds the triggering project directly via amico env bind, then tells the user to switch back to the project tab
• amicode.newEnvironment command: save dialog, mkdir, workspace add, spawn session via launchSession("/create-research-environment --path <dir>")
• amicode.bindToEnvironment command: quick-pick from registry, amico env bind, cache invalidation via invalidateEnvironmentCache()
• amicode.promoteToEnvironment command: active file, resolve environment, run amico env promote in terminal
• bind-to-environment and promote-to-environment sidebar bridge messages have handler cases in handleSidebarMessage() (extend SidebarMessageHandlers interface accordingly)
• create-research-project skill gains Stage 8: environment binding (list registered envs + "Create new" + "Skip")
• migrate-research-project skill gains Phase 6: environment binding after Phase 5 (Verify and orient), using direct string append to write [environment] section (matching the skill's existing direct-write pattern)
• "Create new" option in project/migration skills spawns create-research-environment in a separate session tab via amicode_session (LLM tool call from the skill's prose instructions)

Testing Decisions

• env_verb.test.ts — extend with ~6 tests for envBind: happy path (string append), idempotent on same slug, different-slug refusal, force override (re-render path), missing manifest, registry miss warning
• sidebar_view.test.ts — extend with ~4 tests for createNewEnvironment (mirrors existing createNewProject tests)
• sidebar_bridge.test.ts — extend with ~2 tests for new message handler cases
• Skills are prose — validated by repertoire_lint gate, no TypeScript tests

Key Decisions

• No sidebar button. The primary path is project creation → "bind to environment?" → "Create new" → environment skill in a new tab. Command Palette is the power-user secondary path.
• Free text for system/domain. Environments are domain-agnostic — not quantum-specific. A materials scientist types "DFT calculations," a bioinformatician types "protein folding."
• Separate sessions for chaining. When project creation spawns environment creation, it opens a new session tab via the LLM's amicode_session tool call. The environment session handles binding directly on completion — the project session does NOT need to detect registry changes.
• Two-path TOML write for bind. Initial bind (no [environment] section exists): string append to the file, preserving all existing content and comments. Update bind (--force changing the slug): full parse → mutate → renderProjectToml() re-render, which may lose comments — acceptable for the rare update case.
• Remote is optional. Asked in the interview but defaults to skip. Not every researcher has a shared repo ready at creation time.
• VS Code command uses launchSession() directly. The amicode.newEnvironment command handler calls ctx.launchSession(prompt) (mirroring createNewProject), not the amicode_session LLM tool. The LLM tool is for skill-to-skill chaining within chat sessions.
• Migrate skill uses direct-write. The migrate skill doesn't call CLI verbs — it writes TOML inline. Its new Phase 6 matches this pattern: string append of [environment] section to the already-written research-project.toml.

Constraints & Invariants

• Environments and projects must never be physically nested (nesting guard enforced by checkNestingViolation in env_verb.ts)
• Multi-repo topology only — no walk-up resolution
• [environment].slug in the project TOML is the sole binding mechanism
• Promotion is always human-gated (amico env promote requires explicit invocation)
• envVerb dispatch usage string must be updated to include the bind subcommand

Prior Art

• env_verb.ts — existing envCreate, envRegister, envPromote verbs; envVerb dispatch at line 488
• sidebar_view.ts createNewProject() at line 1053 — the exact pattern to mirror for createNewEnvironment
• extension.ts amicode.newProject at line 1814 — command registration pattern (save dialog → session spawn)
• skills/create-research-project/SKILL.md — 7-stage interview pattern to follow (new Stage 8 adds after Stage 7: domain pack)
• skills/migrate-research-project/SKILL.md — 5-phase flow (new Phase 6 adds after Phase 5: Verify and orient)
• sidebar_bridge.ts — SidebarMessageHandlers interface at line 162 needs extending for new handler slots
• project.ts renderProjectToml() at line 130 — the re-render path for forced bind updates

Source

Part of #880 Research Environments. Extends the integration PR #891.

Notes

Adversarial review findings (3 addressed):

1. TOML preservation: initial bind uses string append (preserves comments); forced update uses re-render (may lose comments). Trade-off documented in Key Decisions.
2. Cross-session detection: removed. The environment session handles binding directly on completion — no mechanism needed for the project session to detect registry changes.
3. Migrate skill pattern: new Phase 6 uses direct string append (matching the skill's existing inline-write approach), not CLI calls.