Version 0.1.5

[0.1.5] - 2026-03-11

Added

• Project config generation — Standard init can now read a repository-root .superposition.yml or superposition.yml
  • Lets teams and CI run generation from committed declarative defaults instead of reconstructing long CLI commands
  • regen now supports --from-project, uses the repository project file by default when present, and consistently behaves as deterministic replay across project-file and manifest-based persisted sources
  • init remains the editable flow, so persisted sources can still prefill the questionnaire when you want to modify a generated setup instead of replaying it exactly
  • Direct CLI flags still override the project config for one run, while explicit --from-manifest regeneration remains isolated
  • Conflicting persisted-input source combinations such as --from-project --from-manifest or source mode plus structural selection flags now fail before generation with a clear source-conflict error
  • Supports parity for the existing clean-generation surface, including custom images, container naming, minimal/editor settings, environment variables, and additional generated features declared through custom patches
• Verbose plan narration — plan --verbose now explains why each overlay was included
  • Shows direct selections, required dependencies, and dependency paths in the terminal output
  • Supports plan --from-manifest <path> --verbose so existing manifests get the same explanation model as explicit overlay lists
  • Adds structured inclusion reasons to plan --json --verbose without changing the default JSON shape
  • Calls out skipped overlays and conflict boundaries so dependency resolution is easier to audit
• spec-kit overlay — Spec-Driven Development with the specify CLI and any supported AI coding agent
  • Installs uv (Astral's fast Python package manager) and specify-cli from github/spec-kit
  • Supports 20+ AI agents: Codex, Claude Code, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Amp, opencode, and more
  • Usage: specify init . --here --ai <agent> after overlay setup
• claude-code overlay — Anthropic Claude Code CLI (@anthropic-ai/claude-code) for AI-powered terminal development
• gemini-cli overlay — Google Gemini CLI (@google/gemini-cli) for AI-powered terminal development
• amp overlay — Sourcegraph Amp CLI (@sourcegraph/amp) for AI-powered terminal development
• windsurf-cli overlay — Codeium Windsurf CLI for AI-powered terminal development
• opencode overlay — opencode AI coding agent (opencode-ai) for multi-provider terminal development
• sdd preset — Spec-Driven Development meta-preset bundling spec-kit with a user-selectable AI agent CLI
  • Prompts users to choose from: Codex, Claude Code, Gemini CLI, Amp, Windsurf, opencode, or GitHub Copilot (IDE-integrated)
  • Sets SPECIFY_AI_AGENT environment variable automatically to match the chosen agent
• hash command — Deterministic environment fingerprint for drift detection and reproducibility
  • Produces a stable SHA-256 fingerprint from stack, resolved overlays, preset, base image, and tool version
  • Auto-resolves overlay dependencies (same logic as plan) so the hash includes transitively required overlays
  • Works standalone (--stack/--overlays flags) or reads directly from an existing superposition.json manifest
  • --json flag emits machine-readable JSON with both a short 8-character hash (for display/badges) and the full 64-character hashFull (for CI comparison)
  • --write flag writes the full hash to .devcontainer/superposition.hash alongside the manifest
  • Hash is version-stable across patch releases (uses major.minor of the tool version only)
  • Full documentation at docs/hash.md
• adopt command — Adopt an existing .devcontainer/ into the overlay-based model
  • Reads devcontainer.json and any linked docker-compose.yml files and analyses their contents
  • Resolves the dockerComposeFile field (string or array, relative paths) to support Docker Compose-based devcontainers where the compose file lives outside the .devcontainer/ directory
  • Maps detected devcontainer features, Docker Compose service images, VS Code extensions, and remoteEnv variables to equivalent overlay IDs
  • Detection tables are built dynamically from the overlay registry — no hardcoded overlay names, every overlay is automatically supported
  • Best-match scoring ensures a feature used by multiple overlays (e.g. the Node.js feature shared by nodejs and bun) is assigned to the most appropriate one
  • Displays a table showing each detected signal → suggested overlay with a confidence level (exact or heuristic)
  • Prints the equivalent container-superposition init command to reproduce the configuration, using correct CLI flags per overlay category (--language, --database, --observability, --cloud-tools, --dev-tools)
  • Unmatched items (features, services, extensions not covered by any overlay) are surfaced separately; a custom/devcontainer.patch.json / custom/docker-compose.patch.yml is written to preserve them across regenerations
  • Backup support using the same auto-detect logic as regen — skipped in git repos by default; use --backup / --no-backup / --backup-dir to override
  • --dry-run flag prints the analysis without writing any files
  • Prompts to generate superposition.json (and optionally custom/ patch files) from the suggestions
  • --force flag allows overwriting existing generated files
  • --json flag for machine-readable output (suitable for scripting)
  • Gracefully handles configs with no recognisable overlay patterns
  • Full documentation at docs/adopt.md