container-superposition 0.1.4 → 0.1.6

package/docs/specs/002-superposition-config-file/tasks.md

@@ -0,0 +1,215 @@
+# Tasks: Project Configuration File
+
+**Input**: Design documents from `docs/specs/002-superposition-config-file/`
+**Prerequisites**: [plan.md](plan.md), [spec.md](spec.md), [research.md](research.md), [data-model.md](data-model.md), [init-project-config.md](contracts/init-project-config.md), [quickstart.md](quickstart.md)
+
+**Tests**: Add automated coverage for config discovery, precedence, no-config fallback, explicit `--from-project`, implicit project-file regen, manifest isolation, source-conflict validation, validation failures, and customization parity in `tool/__tests__/commands.test.ts`, `tool/__tests__/composition.test.ts`, `tool/__tests__/manifest-only.test.ts`, and `tool/__tests__/minimal-and-editor.test.ts`, then run `npm test`, `npm run lint`, and `npm run test:smoke`.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g. `US1`, `US2`, `US3`)
+- Include exact repo-relative file paths in descriptions
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Record the approved spec gate and align the feature docs with the implementation baseline before code changes.
+
+- [x] T001 Confirm approved spec status and implementation gate in `docs/specs/002-superposition-config-file/spec.md`
+- [x] T002 Align implementation sequencing and verification scope in `docs/specs/002-superposition-config-file/plan.md`
+- [x] T003 Align parity examples and validation steps in `docs/specs/002-superposition-config-file/quickstart.md`
+- [x] T004 [P] Record supported project-config surface and customization parity expectations in `docs/specs/002-superposition-config-file/contracts/init-project-config.md`
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Add the shared project-config schema and merge-path support that every story depends on.
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+- [x] T005 Define project-config file discovery, parsed shape, and validation helpers in `tool/schema/project-config.ts`
+- [x] T006 Extend shared config types and `QuestionnaireAnswers` parity fields in `tool/schema/types.ts`
+- [x] T007 Update supported config schema entries for project-config parity in `tool/schema/config.schema.json`
+- [x] T008 Refactor answer-source merging to accept project-config defaults alongside manifest and CLI inputs in `scripts/init.ts`
+- [x] T009 Add foundational regression coverage for project-config discovery, merge precedence, and dual-file ambiguity in `tool/__tests__/commands.test.ts`
+- [x] T010 Add fixture coverage for supported customization parity inputs in `tool/__tests__/composition.test.ts`
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in priority order
+
+---
+
+## Phase 3: User Story 1 - Generate from committed project config (Priority: P1) 🎯 MVP
+
+**Goal**: Let maintainers define the full supported generation intent, including supported customizations, in one repository-root config file and generate the same output as clean generation.
+
+**Independent Test**: Put a valid `.superposition.yml` in the repository root with stack, overlays, output path, and supported customization inputs such as custom container definitions, environment-related settings, and additional generated features, run `npm run init`, and confirm the generated output matches equivalent clean-generation input without re-entering declared values.
+
+### Verification for User Story 1
+
+- [x] T011 [US1] Add command regression coverage for valid project-config driven generation in `tool/__tests__/commands.test.ts`
+- [x] T012 [US1] Add composition parity coverage for project-config custom image and container definition inputs in `tool/__tests__/composition.test.ts`
+- [x] T013 [US1] Add parity coverage for environment-related settings and additional generated features in `tool/__tests__/minimal-and-editor.test.ts`
+
+### Implementation for User Story 1
+
+- [x] T014 [US1] Load repository-root `.superposition.yml` and `superposition.yml` defaults into the standard init flow in `scripts/init.ts`
+- [x] T015 [US1] Map project-config selections into the clean-generation answer model in `tool/schema/project-config.ts`
+- [x] T016 [US1] Preserve supported customization inputs through generation and summary rendering in `scripts/init.ts`
+- [x] T017 [US1] Ensure project-config driven answers produce the same composed output as equivalent clean-generation input in `tool/questionnaire/composer.ts`
+- [x] T018 [US1] Keep generated run summaries accurate for project-config sourced generation in `tool/utils/summary.ts`
+- [x] T018a [US1] Let `adopt --project-file` write a repository-root project config from inferred overlay selections and supported customizations in `tool/commands/adopt.ts` and `tool/schema/project-config.ts`
+- [x] T018b [US1] Let `init` and `regen` target a different repository root for project-file and manifest discovery via `--project-root <path>` in `scripts/init.ts` and `tool/__tests__/commands.test.ts`
+
+**Checkpoint**: User Story 1 should now be fully functional and testable on its own
+
+---
+
+## Phase 4: User Story 2 - Use config-driven setup in automation (Priority: P2)
+
+**Goal**: Let teams run unattended generation from a committed project config while preserving per-run overrides and explicit manifest isolation.
+
+**Independent Test**: Run `npm run init` in a non-interactive repository with a valid project config and confirm declared values are not prompted again, direct CLI flags override only that run, and `--from-manifest` remains isolated from project-config defaults.
+
+### Verification for User Story 2
+
+- [x] T019 [US2] Add non-interactive command regression coverage for project-config defaults and CLI override precedence in `tool/__tests__/commands.test.ts`
+- [x] T020 [US2] Add manifest-isolation regression coverage for project-config and `--from-manifest` interactions in `tool/__tests__/manifest-only.test.ts`
+- [x] T021 [US2] Add regression coverage for no-config fallback to current interactive and flag-driven behavior in `tool/__tests__/commands.test.ts`
+- [x] T022 [US2] Add regression coverage for partial project-config defaults that still require remaining answers in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 2
+
+- [x] T023 [US2] Apply project-config values as default persisted input for standard init without prompting for already-declared values in `scripts/init.ts`
+- [x] T024 [US2] Preserve partial project-config values as shared defaults while collecting only unresolved required answers in `scripts/init.ts`
+- [x] T025 [US2] Preserve run-scoped CLI override precedence over project-config defaults in `scripts/init.ts`
+- [x] T026 [US2] Keep explicit manifest mode isolated from repository project-config defaults in `scripts/init.ts`
+
+**Checkpoint**: User Stories 1 and 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - Correct invalid or ambiguous config quickly (Priority: P3)
+
+**Goal**: Stop invalid, unsupported, conflicting, or ambiguous project-config input before generation and point users to the corrective action.
+
+**Independent Test**: Introduce invalid YAML, unsupported keys, unsupported customization values, conflicting selections, missing non-interactive requirements, and both supported filenames, then confirm generation stops before output with actionable guidance tied to the repository state or config entry.
+
+### Verification for User Story 3
+
+- [x] T027 [US3] Add command regression coverage for invalid YAML, unsupported keys, and unsupported values in `tool/__tests__/commands.test.ts`
+- [x] T028 [US3] Add regression coverage for conflicting selections, missing required non-interactive values, and dual-file ambiguity in `tool/__tests__/commands.test.ts`
+- [x] T029 [US3] Add regression coverage for unsupported customization declarations outside the clean-generation surface in `tool/__tests__/commands.test.ts`
+
+### Implementation for User Story 3
+
+- [x] T030 [US3] Validate project-config syntax, supported keys, supported values, and conflicting selections before generation in `tool/schema/project-config.ts`
+- [x] T031 [US3] Report repository-root ambiguity and non-interactive missing-value failures with actionable guidance in `scripts/init.ts`
+- [x] T032 [US3] Reject unsupported customization declarations that fall outside the supported clean-generation surface in `tool/schema/project-config.ts`
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+## Phase 6: Polish & Cross-Cutting Concerns
+
+**Purpose**: Finish documentation, changelog, and end-to-end verification for the declarative workflow.
+
+- [x] T033 [P] Document project-config usage, parity scope, and supported customization examples in `README.md`
+- [x] T034 [P] Document local and CI workflow examples for project config in `docs/workflows.md`
+- [x] T035 [P] Document project-config parity examples and customization cases in `docs/examples.md`
+- [x] T036 Update the user-visible project-config change summary in `CHANGELOG.md`
+- [x] T037 Run the maintainer workflow review for SC-003 and record the outcome in `docs/specs/002-superposition-config-file/quickstart.md`
+- [x] T038 Record final verification steps and observed outcomes in `docs/specs/002-superposition-config-file/quickstart.md`
+- [x] T039 Run `npm test`, `npm run lint`, and `npm run test:smoke`, then record the results in `docs/specs/002-superposition-config-file/quickstart.md`
+- [x] T040 Add explicit `--from-project` and implicit `regen` project-file regression coverage in `tool/__tests__/commands.test.ts`
+- [x] T041 Implement `--from-project`, implicit project-file `regen`, and source-conflict validation in `scripts/init.ts`
+- [x] T042 Update project-file regeneration and conflict-resolution documentation in `README.md`, `docs/workflows.md`, and `docs/examples.md`
+- [x] T043 Update the user-visible changelog entry to include `regen --from-project`, implicit project-file `regen`, and source-conflict validation in `CHANGELOG.md`
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: Starts immediately
+- **Foundational (Phase 2)**: Depends on Setup completion and blocks all user story work
+- **User Story 1 (Phase 3)**: Depends on Foundational completion
+- **User Story 2 (Phase 4)**: Depends on Foundational completion and should follow US1 because it extends the same answer-resolution path into unattended and manifest-sensitive flows
+- **User Story 3 (Phase 5)**: Depends on Foundational completion and should follow US1 and US2 because validation rules depend on the final supported project-config surface and precedence behavior
+- **Polish (Phase 6)**: Depends on the desired user stories being complete and now also covers explicit source-selection and regeneration workflow updates
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: No dependency on other stories after Phase 2
+- **User Story 2 (P2)**: Depends on the project-config merge path from US1 and extends it to automation, overrides, and manifest isolation
+- **User Story 3 (P3)**: Depends on the supported config surface from US1 and the precedence rules from US2 so failure behavior matches the completed feature
+
+### Within Each User Story
+
+- Add or update verification tasks before implementation for that story
+- Land project-config loading and normalization before parity-sensitive generation changes
+- Complete precedence and failure-handling behavior before final docs and smoke validation
+
+### Parallel Opportunities
+
+- `T003` and `T004` can run in parallel during Setup
+- `T009` and `T010` can run in parallel after the foundational schema shape is settled
+- `T012` and `T013` can run in parallel once project-config mapping is defined
+- `T033`, `T034`, and `T035` can run in parallel after behavior is stable
+- `T040`, `T042`, and `T043` can run in parallel after the source-selection behavior is stable
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+Task: "Add composition parity coverage for project-config custom image and container definition inputs in tool/__tests__/composition.test.ts"
+Task: "Add parity coverage for environment-related settings and additional generated features in tool/__tests__/minimal-and-editor.test.ts"
+```
+
+## Parallel Example: Polish
+
+```bash
+Task: "Document project-config usage, parity scope, and supported customization examples in README.md"
+Task: "Document local and CI workflow examples for project config in docs/workflows.md"
+Task: "Document project-config parity examples and customization cases in docs/examples.md"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational
+3. Complete Phase 3: User Story 1
+4. Validate project-config driven generation against equivalent clean-generation output
+5. Stop for review before extending into unattended and failure-handling behavior
+
+### Incremental Delivery
+
+1. Land project-config discovery, typing, and merge foundations
+2. Deliver User Story 1 for repository-root config driven generation with customization parity
+3. Add User Story 2 for automation, CLI overrides, no-config fallback, and manifest isolation
+4. Add User Story 3 for validation, ambiguity handling, and corrective guidance
+5. Finish docs, changelog, and full verification
+6. Add explicit source-selection and project-file regeneration follow-through so spec, plan, tasks, and CLI behavior stay aligned
+
+### Parallel Team Strategy
+
+1. One developer completes Setup and Foundational work
+2. After the project-config schema and merge path are stable, one developer can drive US1 implementation while another prepares the parity-focused verification cases
+3. After US1 is stable, the same command owner should complete US2 and US3 because they concentrate in `scripts/init.ts` and shared validation helpers
+
+---
+
+## Notes
+
+- All tasks use the required checklist format with IDs, optional `[P]` markers, story labels for story phases, and exact repo-relative file paths
+- The approved spec gate is already satisfied; execution readiness now depends on completing implementation, verification, and documentation tasks cleanly
+- Favor command-level and composition-level regression tests because the risk is user-visible generation behavior and customization parity drift

package/docs/team-workflow.md

@@ -33,6 +33,37 @@ my-project/
 
 ## Step-by-Step Setup
 
+### 0. Migrating an Existing Devcontainer (Optional)
+
+If you already have a hand-crafted `.devcontainer/`, use `adopt` to create the
+initial manifest automatically instead of writing it by hand:
+
+```bash
+# See what would be detected and generated (nothing is written)
+npx container-superposition adopt --dry-run
+
+# Run the adoption (writes superposition.json and custom/ patches)
+npx container-superposition adopt
+
+# Or also emit a repository-root project file for project-config workflows
+npx container-superposition adopt --project-file
+```
+
+`adopt` reads every feature URI, VS Code extension, and Docker Compose service
+image in your existing configuration and maps them to overlays. Anything with
+no overlay equivalent (custom features, project-specific services, custom
+mounts, unmatched environment variables, …) is written to
+`.devcontainer/custom/` so it survives every subsequent `regen`.
+
+`superposition.json` is written to the **project root** (not inside
+`.devcontainer/`), so it can be committed alongside your application code and
+shared with the rest of the team — matching the standard team workflow. If you
+pass `--project-file`, `adopt` also writes a repository-root `.superposition.yml`
+using the same inferred stack, overlays, output path, and supported
+customizations.
+
+See the [Adopt Command guide](adopt.md) for full details.
+
 ### 1. Create the Team Manifest
 
 The team lead or maintainer creates the initial manifest:
@@ -51,7 +82,7 @@ This creates `superposition.json` in the current directory:
 ```json
 {
     "manifestVersion": "1",
-    "generatedBy": "0.1.2",
+    "generatedBy": "X.Y.Z",
     "generated": "2026-02-17T14:00:00.000Z",
     "baseTemplate": "compose",
     "baseImage": "bookworm",
@@ -535,6 +566,7 @@ code .
 
 ## See Also
 
+- [Adopt Command](adopt.md) - Migrate an existing devcontainer to the overlay-based workflow
 - [Quick Reference](quick-reference.md) - Common commands and flags
 - [Overlay Documentation](overlays.md) - Available overlays
 - [Custom Patches](../tool/README.md#custom-patches) - Custom patch format

package/docs/workflows.md

@@ -0,0 +1,139 @@
+# Workflows and Regeneration
+
+This guide covers project-config driven generation, manifest-based regeneration,
+and common workflows.
+
+## Project Config Workflow
+
+Commit exactly one project config file at the repository root:
+
+- `.superposition.yml`
+- `superposition.yml`
+
+Use it when you want standard `init` runs to start from committed defaults
+instead of a copied command line.
+
+```bash
+npx container-superposition init
+```
+
+Use `--no-interactive` when the config fully describes the intended setup and
+you want unattended generation:
+
+```bash
+npx container-superposition init --no-interactive
+```
+
+Direct CLI flags still win for that run only:
+
+```bash
+npx container-superposition init --no-interactive --output ./tmp-devcontainer
+```
+
+## Manifest Basics
+
+Every generation writes a `superposition.json` manifest that records your choices. It enables:
+
+- Reproducible environments
+- Safe upgrades
+- Team sharing
+- Regeneration with backups
+
+## When to Regenerate
+
+Use `regen` when you:
+
+- Add or remove overlays
+- Update to newer overlay versions
+- Change port offsets
+- Switch base templates
+
+Use `init --from-project` or `init --from-manifest` when you:
+
+- Want to start from a persisted source and then adjust choices interactively
+- Want a persisted source to provide defaults before making a targeted change
+
+Use manual edits when you:
+
+- Adjust VS Code settings
+- Add small scripts or config files
+- Tweak a single setting in custom patches
+
+## Quick Regeneration
+
+```bash
+# Uses the repository project file when one exists
+npx container-superposition regen
+
+# Or select the project file explicitly
+npx container-superposition regen --from-project
+
+# Or run from another directory while targeting a repository root
+npx container-superposition regen --from-project --project-root ../my-project
+
+# Falls back to manifest discovery when no project file exists
+npx container-superposition regen
+```
+
+## Regeneration With Changes
+
+```bash
+# Uses manifest as defaults, then prompts for changes
+npx container-superposition init --from-manifest ./.devcontainer/superposition.json
+
+# Uses the repository project file as defaults, then prompts for changes
+npx container-superposition init --from-project
+```
+
+## Source-Selection Conflicts
+
+Persisted-input source flags are mutually exclusive and do not mix with
+clean-generation selection flags:
+
+```bash
+# Invalid: two persisted sources
+npx container-superposition regen --from-project --from-manifest ./.devcontainer/superposition.json
+
+# Invalid: persisted source plus structural selection flags
+npx container-superposition init --from-project --stack compose
+```
+
+## Non-Interactive (CI/CD)
+
+```bash
+npx container-superposition init --no-interactive
+
+# Or keep using an explicit manifest when you want that mode
+npx container-superposition init \
+  --from-manifest ./.devcontainer/superposition.json \
+  --no-interactive \
+  --no-backup
+```
+
+## Backup Behavior
+
+- Default: creates `.devcontainer.backup-<timestamp>/`
+- `--no-backup`: skips backup
+- `--backup-dir <path>`: writes backups to a custom location
+
+## Example Workflow
+
+```bash
+# 1. Initial setup
+npx container-superposition init --stack compose --language nodejs --database postgres
+
+# 2. Later: reapply the committed project file
+npx container-superposition regen
+
+# 3. Or regenerate explicitly from a manifest when that is the intended source
+npx container-superposition init --from-manifest ./.devcontainer/superposition.json
+
+# 4. Update to latest overlays
+npx container-superposition@latest regen
+```
+
+## Team Workflow
+
+For a manifest-first approach (commit only `superposition.json`), see:
+
+- [team-workflow.md](team-workflow.md)

package/features/cross-distro-packages/README.md

@@ -6,6 +6,7 @@ A devcontainer feature that installs system packages with automatic distribution
 
 - 🔍 **Auto-detection**: Automatically detects whether the container uses apt or apk
 - 📦 **Distro-specific packages**: Specify different package names for each distribution
+- 🔁 **Fallback package names**: Use `pkgA|pkgB` when Debian/Ubuntu variants expose different names
 - 🧹 **Clean installation**: Cleans up package manager caches to minimize image size
 - ⚡ **Fast**: No unnecessary updates or cache rebuilds
 
@@ -26,6 +27,19 @@ A devcontainer feature that installs system packages with automatic distribution
 
 ### Real-World Examples
 
+**Fallback package names within apt-based distros:**
+
+```json
+{
+    "features": {
+        "./features/cross-distro-packages": {
+            "apt": "fonts-carlito|fonts-crosextra-carlito",
+            "apk": ""
+        }
+    }
+}
+```
+
 **Node.js Build Tools:**
 
 ```json
@@ -85,6 +99,10 @@ A devcontainer feature that installs system packages with automatic distribution
 | `apt`  | string | `""`    | Space-separated list of packages for apt-based distributions (Debian, Ubuntu) |
 | `apk`  | string | `""`    | Space-separated list of packages for apk-based distributions (Alpine Linux)   |
 
+Package entries may include fallback candidates separated by `|`, for example
+`fonts-carlito|fonts-crosextra-carlito`. The feature selects the first package
+name that exists for the detected package manager.
+
 ## Package Name Differences
 
 Common packages that have different names across distributions:

package/features/cross-distro-packages/devcontainer-feature.json

@@ -2,18 +2,18 @@
     "id": "cross-distro-packages",
     "version": "1.0.0",
     "name": "Cross-Distribution Package Manager",
-    "description": "Install system packages with automatic distribution detection (supports apt and apk)",
+    "description": "Install system packages with automatic distribution detection and fallback package-name support (supports apt and apk)",
     "documentationURL": "https://github.com/veggerby/container-superposition/tree/main/features/cross-distro-packages",
     "options": {
         "apt": {
             "type": "string",
             "default": "",
-            "description": "Space-separated list of packages for apt-based distros (Debian, Ubuntu)"
+            "description": "Space-separated list of packages for apt-based distros (Debian, Ubuntu). Use pkgA|pkgB to try fallback names."
         },
         "apk": {
             "type": "string",
             "default": "",
-            "description": "Space-separated list of packages for apk-based distros (Alpine)"
+            "description": "Space-separated list of packages for apk-based distros (Alpine). Use pkgA|pkgB to try fallback names."
         }
     },
     "installsAfter": ["ghcr.io/devcontainers/features/common-utils"]

package/features/cross-distro-packages/install.sh

@@ -14,6 +14,50 @@ deduplicate_packages() {
     echo "$packages" | tr ' ' '\n' | sort -u | tr '\n' ' ' | sed 's/ $//'
 }
 
+resolve_package_token() {
+    local manager="$1"
+    local token="$2"
+    local IFS='|'
+    read -r -a candidates <<< "$token"
+
+    for candidate in "${candidates[@]}"; do
+        if [ -z "$candidate" ]; then
+            continue
+        fi
+
+        if [ "$manager" = "apt" ]; then
+            if apt-cache show "$candidate" >/dev/null 2>&1; then
+                echo "$candidate"
+                return 0
+            fi
+        elif [ "$manager" = "apk" ]; then
+            if apk search -x "$candidate" >/dev/null 2>&1; then
+                echo "$candidate"
+                return 0
+            fi
+        fi
+    done
+
+    return 1
+}
+
+resolve_package_list() {
+    local manager="$1"
+    local packages="$2"
+    local resolved=()
+
+    for token in $packages; do
+        local selected=""
+        if ! selected=$(resolve_package_token "$manager" "$token"); then
+            echo "❌ No package candidate found for \"$token\" using $manager" >&2
+            exit 1
+        fi
+        resolved+=("$selected")
+    done
+
+    deduplicate_packages "${resolved[*]}"
+}
+
 # Exit early if no packages specified
 if [ -z "$APT_PACKAGES" ] && [ -z "$APK_PACKAGES" ]; then
     echo "⚠️  No packages specified for installation"
@@ -26,9 +70,8 @@ echo "📦 Installing cross-distro packages..."
 if command -v apk > /dev/null 2>&1; then
     # Alpine Linux (apk)
     if [ -n "$APK_PACKAGES" ]; then
-        # Deduplicate package list
-        APK_PACKAGES=$(deduplicate_packages "$APK_PACKAGES")
-        
+        APK_PACKAGES=$(resolve_package_list "apk" "$APK_PACKAGES")
+
         echo "  Detected: Alpine Linux (apk)"
         echo "  Installing: $APK_PACKAGES"
         apk add --no-cache $APK_PACKAGES
@@ -39,12 +82,11 @@ if command -v apk > /dev/null 2>&1; then
 elif command -v apt-get > /dev/null 2>&1; then
     # Debian/Ubuntu (apt)
     if [ -n "$APT_PACKAGES" ]; then
-        # Deduplicate package list
-        APT_PACKAGES=$(deduplicate_packages "$APT_PACKAGES")
-        
+        apt-get update
+        APT_PACKAGES=$(resolve_package_list "apt" "$APT_PACKAGES")
+
         echo "  Detected: Debian/Ubuntu (apt)"
         echo "  Installing: $APT_PACKAGES"
-        apt-get update
         DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends $APT_PACKAGES
         apt-get clean
         rm -rf /var/lib/apt/lists/*

package/overlays/.presets/sdd.yml

@@ -0,0 +1,84 @@
+# Spec-Driven Development Preset
+# Complete environment for SDD with specify-cli and your choice of AI coding agent
+
+id: sdd
+name: Spec-Driven Development
+description: Complete Spec-Driven Development environment with specify-cli and your choice of AI coding agent
+type: meta
+category: preset
+supports: []
+tags: [preset, sdd, spec-driven, ai, specify, spec-kit]
+
+# Overlays to always include
+selects:
+    required:
+        - spec-kit
+
+# Parameterized agent selection
+# Option 'id' is the value passed to `specify init --ai <id>`.
+# 'overlays' is the list of container-superposition overlay IDs to include.
+parameters:
+    agent:
+        description: AI coding agent to use with Spec Kit
+        default: codex
+        options:
+            - id: codex
+              overlays: [codex]
+              description: OpenAI Codex CLI (--ai codex)
+            - id: claude
+              overlays: [claude-code]
+              description: Anthropic Claude Code (--ai claude)
+            - id: gemini
+              overlays: [gemini-cli]
+              description: Google Gemini CLI (--ai gemini)
+            - id: amp
+              overlays: [amp]
+              description: Sourcegraph Amp (--ai amp)
+            - id: windsurf
+              overlays: [windsurf-cli]
+              description: Codeium Windsurf (--ai windsurf)
+            - id: opencode
+              overlays: [opencode]
+              description: opencode (--ai opencode)
+            - id: copilot
+              overlays: []
+              description: GitHub Copilot (IDE-integrated, no extra CLI needed) (--ai copilot)
+
+# Glue configuration
+glueConfig:
+    # environment values support {{parameters.<key>.id}} template substitution —
+    # the preset expander replaces it with the selected option's id at generation time.
+    environment:
+        SPECIFY_AI_AGENT: '{{parameters.agent.id}}'
+
+    readme: |
+        ## Spec-Driven Development (SDD)
+
+        This devcontainer is configured for Spec-Driven Development using [Spec Kit](https://github.com/github/spec-kit).
+
+        ### Getting Started
+
+        Initialize SDD in your project:
+
+        ```bash
+        specify init . --here --ai ${SPECIFY_AI_AGENT:-codex}
+        ```
+
+        ### SDD Workflow
+
+        Use these slash commands in your AI agent:
+
+        | Step | Command | Description |
+        |------|---------|-------------|
+        | 1 | `/speckit.constitution` | Create project governing principles |
+        | 2 | `/speckit.specify` | Define requirements |
+        | 3 | `/speckit.clarify` | Clarify ambiguities |
+        | 4 | `/speckit.plan` | Create implementation plan |
+        | 5 | `/speckit.analyze` | Cross-artifact consistency check |
+        | 6 | `/speckit.tasks` | Break plan into tasks |
+        | 7 | `/speckit.implement` | Execute tasks with AI |
+
+        ### References
+
+        - [Spec Kit GitHub](https://github.com/github/spec-kit)
+        - [SDD Methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md)

package/overlays/README.md

@@ -55,7 +55,13 @@ Each overlay directory contains:
 - **docker-in-docker** - Docker daemon inside container (conflicts with docker-sock)
 - **docker-sock** - Docker socket mounting (conflicts with docker-in-docker)
 - **playwright** - Browser automation with Chromium installed
-- **codex** - AI-powered code assistant
+- **codex** - OpenAI Codex CLI for AI-powered code generation and assistance
+- **spec-kit** - Specify CLI for Spec-Driven Development with any AI coding agent
+- **claude-code** - Anthropic Claude Code CLI for AI-powered development assistance
+- **gemini-cli** - Google Gemini CLI for AI-powered development assistance
+- **amp** - Sourcegraph Amp CLI for AI-powered code generation and assistance
+- **windsurf-cli** - Codeium Windsurf CLI for AI-powered development assistance
+- **opencode** - opencode AI coding agent for terminal-based development assistance
 
 ## Environment Variables