container-superposition 0.1.4 → 0.1.5

package/overlays/opencode/README.md

@@ -0,0 +1,76 @@
+# opencode Overlay
+
+Adds the `opencode` AI coding agent for terminal-based development assistance.
+
+## Features
+
+- **opencode CLI** — Multi-provider AI coding agent for the terminal
+- **Provider flexibility** — Supports multiple AI providers (OpenAI, Anthropic, Google, and more)
+
+## What is opencode?
+
+opencode is an open-source, terminal-based AI coding agent that supports multiple AI providers:
+
+- **Multi-provider** — Choose from OpenAI, Anthropic, Google Gemini, and other providers
+- **Code generation** — Generate new code from natural language descriptions
+- **Codebase context** — Understands your project structure
+- **Agentic tasks** — Execute multi-step coding tasks autonomously
+
+## How It Works
+
+This overlay installs `opencode-ai` globally via npm, making the `opencode` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+opencode
+
+# Check version
+opencode --version
+```
+
+## Use Cases
+
+- **Flexible AI assistant** — Switch between AI providers as needed
+- **Open-source first** — Works with self-hosted models via compatible APIs
+- **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai opencode`
+
+**Integrates well with:**
+
+- `spec-kit` — Use opencode with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+
+## Configuration
+
+Configure your AI provider API key:
+
+```bash
+# For OpenAI
+export OPENAI_API_KEY=your-key
+
+# For Anthropic
+export ANTHROPIC_API_KEY=your-key
+
+# For Google Gemini
+export GEMINI_API_KEY=your-key
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-opencode.sh
+```
+
+## References
+
+- [opencode Website](https://opencode.ai)
+- [opencode GitHub](https://github.com/sst/opencode)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with opencode as the AI agent
+- `codex` — OpenAI Codex CLI (alternative AI assistant)
+- `claude-code` — Anthropic Claude Code (alternative AI assistant)
+- `nodejs` — Required for npm-based installation

package/overlays/opencode/devcontainer.patch.json

@@ -0,0 +1,3 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+}

package/overlays/opencode/overlay.yml

@@ -0,0 +1,14 @@
+id: opencode
+name: opencode
+description: opencode AI coding agent for terminal-based development assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - opencode
+ports: []

package/overlays/opencode/setup.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# opencode setup script - Install opencode AI coding agent
+
+set -e
+
+echo "📦 Installing opencode AI coding agent..."
+
+# Install opencode-ai globally
+npm install -g opencode-ai
+
+# Verify installation
+if command -v opencode &>/dev/null; then
+    echo "✓ opencode installed successfully: $(opencode --version 2>/dev/null || echo 'installed')"
+else
+    echo "✗ opencode installation failed"
+    exit 1
+fi
+
+echo "✓ opencode setup complete"
+echo "ℹ️  opencode: https://opencode.ai"
+echo "ℹ️  Run 'opencode --help' to get started"

package/overlays/opencode/verify.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# opencode overlay verification script
+
+set -e
+
+echo "🔍 Verifying opencode overlay setup..."
+
+# Check if opencode is installed
+if ! command -v opencode &>/dev/null; then
+    echo "✗ opencode is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ opencode is installed: $(opencode --version 2>/dev/null || echo 'installed')"
+
+echo ""
+echo "✅ opencode overlay verification complete!"
+echo ""
+echo "💡 Tips:"
+echo "  - Run 'opencode --help' to see available commands"
+echo "  - Configure your AI provider API key"

package/overlays/spec-kit/README.md

@@ -0,0 +1,181 @@
+# Spec Kit (SDD) Overlay
+
+Installs the `specify` CLI and its prerequisites (`uv`) for **Spec-Driven Development** — a disciplined workflow that elevates specifications to first-class artifacts driving AI-powered implementation.
+
+## Features
+
+- **`specify` CLI** — Interactive SDD workflow commands for any supported AI coding agent
+- **`uv`** — Fast Python package manager used to install and run `specify`
+- **20+ AI agent integrations** — Works with Codex, Claude Code, Gemini CLI, GitHub Copilot, Cursor, Windsurf, Amp, and more
+
+## What is Spec-Driven Development?
+
+Spec-Driven Development (SDD) flips the traditional workflow: instead of vibe-coding, you author rich specifications that become executable artifacts driving AI agents through a disciplined multi-step process:
+
+| Step | Command                 | Description                               |
+| ---- | ----------------------- | ----------------------------------------- |
+| 1    | `/speckit.constitution` | Create project governing principles       |
+| 2    | `/speckit.specify`      | Define requirements (what & why, not how) |
+| 3    | `/speckit.clarify`      | Clarify underspecified areas              |
+| 4    | `/speckit.plan`         | Create a technical implementation plan    |
+| 5    | `/speckit.analyze`      | Cross-artifact consistency analysis       |
+| 6    | `/speckit.tasks`        | Break plan into actionable tasks          |
+| 7    | `/speckit.implement`    | Execute tasks with an AI agent            |
+
+## How It Works
+
+This overlay:
+
+1. Installs `uv` (Astral's fast Python package manager) if not already present
+2. Uses `uv tool install` to install `specify-cli` from the [github/spec-kit](https://github.com/github/spec-kit) repository
+3. Makes `specify` available on the PATH inside the devcontainer
+
+**Why `uv`?** Spec Kit uses `uv` as its package manager for fast, isolated tool installation — it avoids the overhead of creating a full virtual environment while keeping `specify` globally accessible.
+
+## Common Commands
+
+### Initialize a project
+
+```bash
+# Initialize SDD for a project with a specific AI agent
+specify init . --here --ai codex
+specify init . --here --ai claude
+specify init . --here --ai gemini
+specify init . --here --ai copilot
+specify init . --here --ai amp
+```
+
+### SDD Workflow
+
+```bash
+# After initializing, use the installed slash commands in your AI agent:
+# /speckit.constitution  — Define project principles
+# /speckit.specify       — Author requirements spec
+# /speckit.clarify       — Clarify ambiguities
+# /speckit.plan          — Generate implementation plan
+# /speckit.analyze       — Check consistency
+# /speckit.tasks         — Break into tasks
+# /speckit.implement     — Implement with AI
+```
+
+### Utility Commands
+
+```bash
+# Check specify is available
+specify --version
+
+# List supported agents
+specify --help
+```
+
+## Supported AI Agents
+
+The `specify` CLI supports the following agents (pass as `--ai <agent>`):
+
+| Agent                 | `--ai` flag    | Notes                                   |
+| --------------------- | -------------- | --------------------------------------- |
+| OpenAI Codex          | `codex`        | Requires `codex` overlay                |
+| Anthropic Claude Code | `claude`       | Requires `claude-code` overlay          |
+| Google Gemini CLI     | `gemini`       | Requires `gemini-cli` overlay           |
+| GitHub Copilot        | `copilot`      | IDE-integrated, no extra overlay needed |
+| Cursor Agent          | `cursor-agent` | IDE-integrated                          |
+| Codeium Windsurf      | `windsurf`     | Requires `windsurf-cli` overlay         |
+| Sourcegraph Amp       | `amp`          | Requires `amp` overlay                  |
+| opencode              | `opencode`     | Requires `opencode` overlay             |
+| Roo Code              | `roo-code`     | IDE-integrated                          |
+| Kiro CLI              | `kiro`         | Check upstream docs                     |
+| Generic (BYOA)        | `generic`      | Bring your own agent                    |
+
+For the full list see the [spec-kit supported agents documentation](https://github.com/github/spec-kit#-supported-ai-agents).
+
+## Use Cases
+
+- **Greenfield projects** — Start with a specification before writing any code
+- **Feature development** — Spec out new features before asking AI to implement them
+- **Team alignment** — Share specifications as structured artifacts
+- **AI-assisted refactoring** — Spec the desired end state, let AI plan the migration
+- **Documentation-driven development** — Specifications become living documentation
+
+**Integrates well with:**
+
+- `codex` — OpenAI Codex CLI (most common with SDD)
+- `claude-code` — Anthropic Claude Code
+- `gemini-cli` — Google Gemini CLI
+- `amp` — Sourcegraph Amp
+- `git-helpers` — Git integration for specification artifacts
+- `pre-commit` — Quality gates for specification files
+
+## Configuration
+
+The `specify` tool stores its slash-command templates in your project directory after running `specify init`. These files are committed to your repository.
+
+**Environment variable (optional):**
+
+```bash
+# Set a default AI agent to avoid passing --ai on every command
+export SPECIFY_AI_AGENT=codex
+```
+
+## Verification
+
+After setup, run the verification script to ensure proper installation:
+
+```bash
+bash .devcontainer/scripts/verify-spec-kit.sh
+```
+
+This checks:
+
+- `uv` is installed
+- `specify` CLI is available on PATH
+
+## Troubleshooting
+
+### `specify` command not found
+
+**Solution:**
+
+Ensure `$HOME/.local/bin` is on your PATH:
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+
+# Or add to your shell profile:
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
+```
+
+### `uv` not found
+
+**Solution:**
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+export PATH="$HOME/.local/bin:$PATH"
+```
+
+### `specify` fails to install
+
+**Solution:**
+
+Check internet connectivity and try reinstalling:
+
+```bash
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git --force
+```
+
+## References
+
+- [Spec Kit GitHub](https://github.com/github/spec-kit)
+- [Spec-Driven Development Methodology](https://github.com/github/spec-kit/blob/main/spec-driven.md)
+- [Specify CLI Reference](https://github.com/github/spec-kit#-specify-cli-reference)
+- [Supported AI Agents](https://github.com/github/spec-kit#-supported-ai-agents)
+- [uv Documentation](https://docs.astral.sh/uv/)
+
+**Related Overlays:**
+
+- `codex` — OpenAI Codex CLI
+- `claude-code` — Anthropic Claude Code
+- `gemini-cli` — Google Gemini CLI
+- `amp` — Sourcegraph Amp
+- `opencode` — opencode CLI
+- `windsurf-cli` — Codeium Windsurf CLI

package/overlays/spec-kit/devcontainer.patch.json

@@ -0,0 +1,6 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json",
+    "remoteEnv": {
+        "PATH": "${containerEnv:PATH}:${containerEnv:HOME}/.local/bin"
+    }
+}

package/overlays/spec-kit/overlay.yml

@@ -0,0 +1,19 @@
+id: spec-kit
+name: Spec Kit (SDD)
+description: Specify CLI for Spec-Driven Development with any AI coding agent
+category: dev
+supports: []
+requires: []
+suggests:
+    - python
+    - codex
+conflicts: []
+tags:
+    - dev
+    - ai
+    - sdd
+    - spec-driven
+    - specify
+    - spec-kit
+ports: []
+order: 20

package/overlays/spec-kit/setup.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# spec-kit setup — install specify-cli for Spec-Driven Development
+
+set -e
+
+echo "📦 Installing prerequisites for spec-kit..."
+
+# Ensure uv tool bin directory is always on PATH (uv puts shims here regardless
+# of whether uv itself was pre-installed or freshly installed in this script)
+export PATH="$HOME/.local/bin:$PATH"
+
+# Ensure uv is available (fast Python package manager)
+if ! command -v uv &>/dev/null; then
+    echo "  Installing uv..."
+    curl -LsSf https://astral.sh/uv/install.sh | sh
+    # Re-source in case the installer wrote to a non-standard location
+    export PATH="$HOME/.cargo/bin:$HOME/.local/bin:$PATH"
+fi
+
+echo "📦 Installing specify-cli..."
+# Pin to a uv-managed Python (avoids broken system Python 3.13 on Debian trixie
+# where stdlib modules like shutil/os can be missing due to Debian's split packages)
+UV_PYTHON_VERSION="3.12"
+echo "  Ensuring uv-managed Python ${UV_PYTHON_VERSION} is available..."
+uv python install "${UV_PYTHON_VERSION}"
+
+# Install specify-cli using the uv-managed Python, not the system interpreter
+uv tool install specify-cli --from git+https://github.com/github/spec-kit.git \
+    --python "${UV_PYTHON_VERSION}"
+
+# Verify — use the full path as a fallback in case the shim dir is not yet in PATH
+SPECIFY_BIN="$(uv tool dir 2>/dev/null)/specify-cli/bin/specify"
+if command -v specify &>/dev/null; then
+    echo "✓ specify-cli installed: $(specify --version 2>/dev/null || echo 'ok')"
+elif [ -x "$SPECIFY_BIN" ]; then
+    echo "✓ specify-cli installed at $SPECIFY_BIN (add ~/.local/bin to PATH)"
+else
+    echo "✗ specify-cli installation failed"
+    exit 1
+fi
+
+echo "✓ spec-kit setup complete"
+echo "ℹ️  Spec Kit: https://github.com/github/spec-kit"
+echo "ℹ️  Usage:  specify init <PROJECT_NAME> --ai <agent>"
+echo "ℹ️  Agents: codex, claude, gemini, copilot, cursor-agent, windsurf, amp, ..."

package/overlays/spec-kit/verify.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# spec-kit overlay verification script
+
+set -e
+
+# uv installs shims to ~/.local/bin; ensure it is on PATH
+export PATH="$HOME/.local/bin:$PATH"
+
+echo "🔍 Verifying spec-kit overlay setup..."
+
+# Check uv is available
+if ! command -v uv &>/dev/null; then
+    echo "✗ uv not found"
+    exit 1
+fi
+
+echo "✓ uv is installed: $(uv --version 2>/dev/null || echo 'installed')"
+
+# Check specify CLI is available
+if ! command -v specify &>/dev/null; then
+    echo "✗ specify not found"
+    exit 1
+fi
+
+echo "✓ specify is installed: $(specify --version 2>/dev/null || echo 'installed')"
+
+echo ""
+echo "✅ spec-kit overlay verification complete!"
+echo ""
+echo "💡 Tips:"
+echo "  - Run 'specify --help' to see available commands"
+echo "  - Initialize a project: specify init <PROJECT_NAME> --ai <agent>"
+echo "  - Supported agents: codex, claude, gemini, copilot, cursor-agent, windsurf, amp, ..."

package/overlays/windsurf-cli/README.md

@@ -0,0 +1,69 @@
+# Windsurf CLI Overlay
+
+Adds the Codeium Windsurf CLI (`windsurf`) for AI-powered development assistance in the terminal.
+
+## Features
+
+- **Windsurf CLI** — Codeium's AI coding agent for terminal use
+- **Cascade flows** — AI-driven multi-step development tasks
+
+## What is Windsurf CLI?
+
+Windsurf CLI is Codeium's headless agentic coding assistant that brings the power of the Windsurf IDE agent to the command line:
+
+- **Agentic coding** — Autonomous multi-step task execution
+- **Codebase understanding** — Deep indexing of your repository
+- **Code generation** — Create features from natural language
+- **Refactoring** — Improve existing code with AI guidance
+
+## How It Works
+
+This overlay installs the Windsurf CLI globally via npm, making the `windsurf` command available in your devcontainer.
+
+## Common Commands
+
+```bash
+# Start an interactive session
+windsurf
+
+# Check version
+windsurf --version
+```
+
+## Use Cases
+
+- **Feature implementation** — Describe what you want, Windsurf implements it
+- **Code exploration** — Understand large or complex codebases
+- **Spec-Driven Development** — Works with `spec-kit` overlay via `specify init --ai windsurf`
+
+**Integrates well with:**
+
+- `spec-kit` — Use Windsurf with the SDD workflow
+- `nodejs` — Required for installation
+- `git-helpers` — Git integration for AI-generated code
+
+## Configuration
+
+Authenticate with your Codeium account:
+
+```bash
+windsurf auth
+```
+
+## Verification
+
+```bash
+bash .devcontainer/scripts/verify-windsurf-cli.sh
+```
+
+## References
+
+- [Windsurf Documentation](https://docs.codeium.com/windsurf/getting-started)
+- [Codeium Platform](https://codeium.com/)
+
+**Related Overlays:**
+
+- `spec-kit` — Spec-Driven Development with Windsurf as the AI agent
+- `codex` — OpenAI Codex CLI (alternative AI assistant)
+- `claude-code` — Anthropic Claude Code (alternative AI assistant)
+- `nodejs` — Required for npm-based installation

package/overlays/windsurf-cli/devcontainer.patch.json

@@ -0,0 +1,3 @@
+{
+    "$schema": "https://raw.githubusercontent.com/devcontainers/spec/main/schemas/devContainer.base.schema.json"
+}

package/overlays/windsurf-cli/overlay.yml

@@ -0,0 +1,15 @@
+id: windsurf-cli
+name: Windsurf CLI
+description: Codeium Windsurf CLI for AI-powered development assistance
+category: dev
+supports: []
+requires:
+    - nodejs
+suggests: []
+conflicts: []
+tags:
+    - dev
+    - ai
+    - windsurf
+    - codeium
+ports: []

package/overlays/windsurf-cli/setup.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# windsurf-cli setup script - Install Codeium Windsurf CLI
+
+set -e
+
+echo "📦 Installing Codeium Windsurf CLI..."
+
+# Install windsurf globally via npm
+npm install -g @codeium/windsurf-cli
+
+# Verify installation
+if command -v windsurf &>/dev/null; then
+    echo "✓ Windsurf CLI installed successfully: $(windsurf --version 2>/dev/null || echo 'installed')"
+else
+    echo "✗ Windsurf CLI installation failed"
+    exit 1
+fi
+
+echo "✓ windsurf-cli setup complete"
+echo "ℹ️  Codeium Windsurf: https://docs.codeium.com/windsurf/getting-started"
+echo "ℹ️  Run 'windsurf --help' to get started"

package/overlays/windsurf-cli/verify.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# windsurf-cli overlay verification script
+
+set -e
+
+echo "🔍 Verifying windsurf-cli overlay setup..."
+
+# Check if windsurf CLI is installed
+if ! command -v windsurf &>/dev/null; then
+    echo "✗ windsurf CLI is not installed or not in PATH"
+    exit 1
+fi
+
+echo "✓ windsurf CLI is installed: $(windsurf --version 2>/dev/null || echo 'installed')"
+
+echo ""
+echo "✅ windsurf-cli overlay verification complete!"
+echo ""
+echo "💡 Tips:"
+echo "  - Run 'windsurf --help' to see available commands"
+echo "  - Authenticate with your Codeium account"

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "container-superposition",
-    "version": "0.1.4",
+    "version": "0.1.5",
     "description": "Solution-ready devcontainer templates and features with guided initialization",
     "type": "module",
     "main": "dist/scripts/init.js",